add more detailed asserts description and milestones

bsip-0040.md

@@ -31,37 +31,68 @@ Examples:
  - Trading Key: Only allows limit orders (arguments restricted to desired markets), update margin position and transfers (arguments restricted to certain accounts)
  - Proposal Update Key: Approve proposals (2FA comes to mind)
  - Faucet Key: Allow only to create accounts
+ - Withdrawal Key: Allow another account to transfer funds to himself
+ - Cold Storage Key: Only allow to move funds to the Hot Wallet
+ 
 The above list of named keys is nothing that is known to the backend as the backend should have an abstract implementation.
  The UI could provide a button "Create Trading Key" that properly configures the respective custom active permission entry.
 
 # Rational
 
 The description here is more on a superficial level and no recommendation how it can best be implemented.
-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 `assert`s than can be used to restrict arguments. When a transaction is signed with such an authority the backend checks if the contained operation has a corresponding custom active authority entry and if so acts as if the active authority of the corresponding account is given. It also checks if the arguments are in the allowed range.
+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 `asserts` than can be used to restrict arguments. When a transaction is signed with such an authority the backend checks if the contained operation has a corresponding custom active authority entry and if so acts as if the active authority of the corresponding account is given. If there are several custom active authorities, any matched one grants this, thus finding the first match is sufficient. It also checks if the arguments are in the allowed range.
 
 A Custom Active Permission looks like follows (in JSON for clarification, backend serializes and stores in a different way):
 ```
 custom_active_permission = list of custom_active_authority items
 custom_active_authority = {
+    valid_from, // this custom active authority is valid starting at this timestamp, defaults to now
+    valid_to,   // this custom active authority is valid until this timestamp, defaults to 1 year
     operationid,
     authority,
-    assert
+    asserts
 }
 ```
+Note: This assumes `custom_active_permission` is stored within `account_object`. Actual implementation details left to the implementer.
 
-Example:
+The `asserts` is a list of `assert_objects` that are all together evaluated with `and` logic to evaluate a match
+```
+asserts = list of assert_object
+assert_object = {
+    argument, // target argument of the operationid
+    function, // functionid to do the assert 
+    data,     // stores data specific to the chosen function
+    state     // if this assert is statefull
+}
+```
+List of possible asserts are:
+
+| function        | data           | state  |
+| ------------- |:-------------:| -----:|
+| `any`      | [`list`, `of`, `allowed`, `values`] | stateless |
+| `range`      | [`min`, `max`] | stateless |
+| `limit` | [`value`, `interval_in_sec`]      | [`current_cumsum`, `interval_began`] |
+| `limit_monthly` | [`value`, `interval_in_months`]      | [`current_cumsum`, `interval_began`] |
+
+Example A:
 Assume account A and B and some unrelated key K. Furthermore A has a custom active authority in the following way:
 ```
 custom active authority = {
-    operationid: 0 (transfer),
+    valid_from: 7.7.2018 00:00
+    valid_to: 8.7.2018 00:00
+    operationid: transfer,
     authority: {
        threshold: 1
        key_auth: [K, 1]
        account_auth: []
     },
-    assert: {
-        to: B
-    }
+    asserts: [
+        {
+            argument: to
+            function: any,
+            data: [B]
+        }
+    ]
 }
 ```
 That has the consquence now that a a transfer transaction sending funds away from A can be signed with key K as long as the receiver is B.
@@ -73,6 +104,16 @@ Requirements to modify the backend includes
 * Operation-specific authorities (if present) must be evaluated in incoming transactions
 * Additional committee parameters may be needed to limit the extend of usage of this feature
 
+Note: The implementation must not differentiate the logic, all operations receive the same 
+
+# Milestones
+We propose do split the implmentation into two milestones:
+
+1. Implementation of basic functionaliy to allow custom active permissions and authorities, including `range` and `any` `asserts`
+2. Evaluation of stateful asserts (performance) and if positive, implementation of `limit` and `limit_monthly` `asserts`
+
+This approach allows as well to add other asserts at a later stage (with a new BSIP).
+
 # Discussion
 
 To be found in the [issue](https://github.com/bitshares/bitshares-core/issues/1061).
@@ -81,6 +122,8 @@ To be found in the [issue](https://github.com/bitshares/bitshares-core/issues/10
 
 Bad publicity in terms of security can have very negative effect on the BTS value. This BSIP allows that traders can e.g. use a trading key, witnesses can use their witness key and a faucet can use a faucet key. If then for some reason the key or witness/faucet server becomes compromised, such a key can do little harm to the account holders, minimizing the risk.
 
+This BSIP opens up a lot of use-cases for the backend as well.
+
 # Copyright
 
 This document is placed in the public domain.