General Idea: New Functionality to Realize Recurring/Scheduled Withdrawals on BitShares

[TheTaconator]

Overview
A recurring/scheduled withdrawal on BitShares consists of one account (e.g. donor; customer; etc.), which will be called a "giver", authorizing another account, which will be called a "recipient", to withdraw up to a maximum amount ("limit") of assets during any one of defined periods (e.g. per week; per month; etc.) between a start date-time and for up to N quantity of periods (i.e. an implied end date).

1. (Optional) A recipient may request withdrawal authorization from a potential giver.
2. A giver may granting the withdrawal authorization to the recipient.
3. Any time after authorization, a giver may rescind the authorization. However, this only affects future withdrawals.
4. After the authorized start date, the recipient may withdraw up to the maximum approved amount every withdrawal period.

This functionality already exists in BitShares Core as of 2.0.171105a. However, this capability does not exist in the GUI reference wallet nor in the command-line interface (CLI) which are two "clients" to the blockchain. Both of those clients require an ability to query the present and past state (i.e. history) of withdrawal authorizations and withdrawals as they exist on the blockchain. That, in turn, requires changes to the API node.

Needed Functionality
(Optional) Requesting Withdrawal Authorization

• Potential recipient can add a recurring authorization request (Request includes giver account, recipient account, maximum amount per period, period duration, period start, number of periods)

(Optional) Informing a Potential Giver about a Withdrawal Authorization Request

• Potential recipient can provide a pending authorization request by recurring authorization ID (e.g. "x.x.x") which can be used by a potential giver to review and optionally authorize within the wallet of their choice
• Potential recipient can provide a pending authorization request by QR code, that contains the recurring authorization ID, which can be used by a potential giver to review and optionally authorize within the wallet of their choice
• Potential recipient can provide a pending authorization request by a URL, that contains the recurring authorization ID, that is coded up for recognized web wallets that the user can select: wallet.bitshares.org, OpenLedger, RuDex, etc. (Related to General Idea about unified functional "URL" for bitshares mobile client bitshares-ui#775)
• Potential recipient can provide multiple "buttons" on their web page which allows a user to select which web wallet that they would like to view the authorization request (presumably where the giver already has an account)

(Optional) Reviewing Withdrawal Authorization Requests

• Query authorization by authorization ID (whether pending, authorized, or cancelled)
• Query pending authorization requests from a recipient
• Query pending authorization requests by a giver

Authorizing Withdrawal

• Giver can authorize a withdrawal by a recipient

Rescinding Withdrawal Authorization

• Giver can cancel a withdrawal authorization

Querying Withdrawal Authorizations

• Query expired authorization requests from a recipient

• Query expired authorization requests by a giver

• Query current authorizations from a recipient

• Query current authorizations by a giver

• Query expired authorizations from a recipient

• Query expired authorizations by a giver

Executing Withdrawals

• Recipient can execute an authorized withdrawal

Querying Withdrawals

• Query how much has been withdrawn during the current period for a particular recurring payment ID
• Query how much can still be withdrawn during the current period for a particular recurring payment ID
• Query withdrawal history to a recipient
• Query withdrawal history from a giver
• Query withdrawal history from a giver to a recipient

Implementation Considerations
Almost every single feature above will require enhancements to client software (such as the reference GUI wallet for use by a typical end-user, and a CLI for a typical recipient) and API nodes to enable querying the existing state of withdrawal authorizations.

One consideration regards the optional first step: a potential recipient can request that a giver grant withdrawal authorization. This can be implemented as a proposed transaction that is submitted by a potential recipient, and reviewed by a potential giver on the client of their choice.

One debatable implementation is which functional entity (API node or client) should enumerate for an end-user the various period start and end dates that are implied by the withdrawal authorization. The nodes already know the the current period's end date but does not retain in memory prior periods nor subsequent periods. Therefore, the API node could calculate and provide this information. However, it is probably better to offload this calculation to the client software; a weakness to this approach is that it introduces the potential of client software incorrectly calculating the start and end dates and thereby misleading the end-user.

Another consideration is whether the functionality in the API should be written as a plug-in. I currently think that this functionality should be available on all API nodes because any user anywhere might be inquiring about withdrawals. However, perhaps an argument could be made that it should be possible to limit the history of withdrawal authorizations and actual withdrawals from active memory of the API node. Should limited history be a parameter that can be limited on any API node? Should full history only be available by making use of, perhaps, the elastic search plugin? Note: Should history also include the proposed withdrawal authorization from the Optional Step 1, or is Step 2 adequate?

Feedback
I would appreciate any feedback regarding this functionality

[pmconrad]

Good writeup!

IMO all history should be moved into an external database, i. e. ES. And I'm all for moving non-core functionality into plugins.

[abitmore]

• (Optional) A recipient may request withdrawal authorization from a potential giver.
• A giver may granting the withdrawal authorization to the recipient.

As mentioned in OP, these can be done with proposals.

Querying Withdrawal Authorizations

Need to develop new API's.