add remaining_executions

bsip-0040.md

@@ -44,17 +44,21 @@ The above list of named keys is nothing that is known to the backend as the back
 
 Note: The user can still use the active authority just like used to, no change in existing behavior. The named keys only give an additional possibility. For example: The user can login the UI using the private key of such a named key. Then he only as access to the operations that this named key grants. He can still login with the existing password to gain full access (similar a local wallet can be created that only contains the named key).
 
-This BSIP will be split into three parts that will be voted on separately (see Milestones section). All of the above keys are possible with Milestone 1. Milestone 2 allows stateful restrictions (e.g. allow market orders up to some amount for every month), Milestone 3 gives finer control of how to combine restrictions. Milestone 2 and 3 will be put up for voting if Milestone 1 proves successful.
+This BSIP will be split into three parts that will be voted on separately (see Milestones section). All of the above keys are possible with Milestone 1. Milestone 2 allows stateful restrictions (e.g. allow market orders up to some amount for every month), Milestone 3 gives finer control of how to combine restrictions and Milestone 4 allows to set a number of allowed executions per authority (makes the `custom active authorities` more dependent on the chain state). Milestone 2, 3 and 4 will be put up for voting if Milestone 1 proves successful.
 
 # Rational
 
 Custom active permission is a list of `custom active authorities`. A `custom active authority` contains an `operation_id`, 
-an `authority` (just like with active permission) and `restrictions` than can be used to restrict arguments and is only 
-valid a certain time period (`valid_from` and `valid_to`). When handling incoming signed transactions, the backend checks 
+an `authority` (just like with active permission) and `restrictions` than can be used to restrict arguments. 
+Furthermore, such a `custom active authority` is only valid in a specified time period (`valid_from` and `valid_to`). 
+When handling incoming signed transactions, the backend checks 
 for each operation if there is a `custom active authority` for any of its required accounts. Check for every required 
 account of the transaction if all its belonging operations have at least one positively matched `custom active authority` 
 (see Specifications for definition of "matching"), and if so behave as if the active authority of the corresponding account is present (recursive authorities are excluded, see Examples).
 
+Note: If Milestone 4 is implemented, a `custom active authority` can be valid in the above-mentioned time period and/or 
+for a number of executions defined by `remaining_executions`. The user can choose to restrict both or only the number of executions, but the number of executions can only be unlimited (not set) only if a time period is specified. 
+
 # Specification
 
 All descriptions in this section are on a pseudo/prosa level and no recommendation how it can best be implemented or serialized. They are meant to facilitate the understanding. If anything in the looping process or order of evaluation is unsuitable for actual implementation, changes can be made accordingly as long the same functionality is achieved.
@@ -68,12 +72,13 @@ custom_active_permission = {
     authorities = list of custom_active_authority objects
 }
 custom_active_authority = {
-    enabled,       // status of this authority, true or false. true when created
-    valid_from,    // timestamp when this is active
-    valid_to,      // timestamp when this is invalid
-    operation_id,   // operation id of the target operation,
-    authority,     // same as for the existing authotities (multisig with weighted accounts or keys),
-    restrictions        // see below
+    enabled,                // status of this authority, true or false. true when created
+    valid_from,             // timestamp when this is active
+    valid_to,               // timestamp when this is invalid
+    remaining_executions,   // number of allowed executions 
+    operation_id,           // operation id of the target operation,
+    authority,              // same as for the existing authotities (multisig with weighted accounts or keys),
+    restrictions            // see below
 }
 ```
 Note: This assumes `custom_active_permission` is stored in a separate index. Actual implementation details left to the implementer, as long as every `custom_active_permission` can be assigned to exactly one account.
@@ -83,6 +88,7 @@ A `custom active authority` is matched against operations of an incoming, signed
 - `account_id` is in the required accounts of the operation
 - the `authority` of the `custom_active_authority` is given by the signatures of the transaction
 - timestamp `now` is within `valid_to` and `valid_from` 
+- `remaining_executions` is either not set or > 0 (only Milestone 4)
 - all `restrictions` assert positively
 
 ### Restrictions
@@ -181,7 +187,7 @@ When a signed transaction arrives and before the backend evaluates if all necess
 - iterate over `required accounts`
   - iterate over all `operations` (child operations of proposal are not included) within the transactions that require the active authority of this account
     - iterate the `custom_active_authorities` of this account, and if it matches, remember that and continue with next `operation`
-  - if a `custom active authority` match was found for every operation in the loop, behave as if the `active authority` of this account is present for the corresponding operations
+  - if a `custom active authority` match was found for every operation in the loop, behave as if the `active authority` of this account is present for the corresponding operations. Decrease `remaining_executions` by one if set (only Milestone 4)
 
 Note:
 - A `custom_active_authority` can only grant the `active authority` of the required account of the corresponding operation, nothing more
@@ -201,7 +207,6 @@ Note:
 
 Notes: The implementation must not differentiate on which operation the custom active authority is applied, all operations are treated in same fashion
 
-
 # Economics
 
 Adding a custom active authority means increased effort for the backend, and with a stateful one also the need for more storage. Proposed transaction fees:
@@ -392,6 +397,7 @@ We propose do split the implmentation into two milestones. Each milestone will b
 1. Implementation of basic functionaliy to allow custom active permissions and authorities, including `any`, `none` and `lt, le, gt, ge, eq, neq`, `contains_all, contains_none` and `attribute_assert` `asserts`. If deemed necessary by developpers, reduce to only allow one key or one account for every `custom active authority`
 2. Implement stateful asserts `limit` and `limit_monthly`
 3. Implement `logical_or`
+4. Implement `remaining_executions`
 
 This approach allows as well to add other asserts at a later stage (with a new BSIP).