moved examples out of specifications

bsip-0040.md

@@ -140,11 +140,59 @@ Stateless assert, only for dictionary type objects. The data list contains restr
 Stateless assert, only for dictionary type objects. The data is a list of restrictions lists, i.e. 
 `data = [ [restriction 1, restriction 2], [restriction 3, restriction 4], ... ]`. If one of the restrictions sub-lists in data passes as whole, this restriction passes.
 
+### Outline of handling incoming transactions
+ 
+When a signed transaction arrives and before the backend evaluates if all necessary authorities are present through the signatures, do the following:
+- iterate over required accounts and for each account, iterate over all operations within the transactions that require the active authority of this account
+- iterate the `custom_active_authorities` of said account
+- if a `custom_active_authority` is found that matches , remember that and stop iterating the authorities and continue until all operations are checked
+- if the account has a `custom active authority` match for every operation in the transaction that requires it, then grant the `active authority` of said account. If no match is found, treat as if no authority was given
+
+Note:
+- A `custom_active_authority` can only grant the `active authority` of the corresponding account, nothing more
+
+### Modification to the backend
+
+* Add a new index or extend the account object to store custom active permission are assigned to an account and contain a list of custom active authorities. Multiple custom active authority entries are possible for one operation
+* If the active authority of the account is updated, all custom active authorities need to be confirmed in the update. Every unconfirmed one is deleted otherwise
+* Provide operations: `install_custom_active_authority`, `update_custom_active_authority`, `delete_custom_active_authority` to allow changing the custom active permission (3 operation to allow custom transaction fees and avoid having to send the complete list of all authorities for every update)
+* 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
+
+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:
+- `install_custom_active_authority`: Tied to the duration of the custom active authority. 
+Normal accounts can only create custom active authoritites with a duration of maximum 1 year. LTM can do any duration and also unlimited, but the transaction fee is capped at duration of 2 years.
+- `update_custom_active_authority` and `delete_custom_active_authority`: Similar to `account_update`
+
+# Milestones
+
+We propose do split the implmentation into two milestones. Each milestone will be voted on as a separate BSIP:
+
+1. Implementation of basic functionaliy to allow custom active permissions and authorities, including `any`, `none` and `lt, le, gt, ge` 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`
+
+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) and [pull request](https://github.com/bitshares/bsips/pull/86).
+
+# Examples
+
+These examples are for illustration and no specification of actual serialization.
+
+
 #### Example: Nested arguments like `options`
 Assume `asset_update_operation`. All attributes of its `options` must be filled on update call. This assert can not be used to realize a "may only change attribute xzy of `options`". This would require that the logic knows which of the arguments are reflected on-chain and it knows how to query it for every operation that contains `options`. If `options` are to be restricted with this assert, all values that should not change would need be fixated by defining an `any` assert for those attributes, while having e.g. a `lt` assert for the one attribute that is allowed to change.
 
 #### Example: Simple transfer
-Assume account A and B and some unrelated key K. Furthermore A has a custom active authority in the following way:
+Assume account A and B and some unrelated key K. 
+The custom active authority should be put that transfer transaction sending funds away from A can be signed with key K as long as the receiver is B. More concrete, the authority would look like
 ```
 custom active authority = {
     valid_from: 7.7.2018 00:00
@@ -164,12 +212,16 @@ custom active authority = {
     ]
 }
 ```
-That has the consquence now that a transfer transaction sending funds away from A can be signed with key K as long as the receiver is B.
+Note: This is included with the first Milestone
 
-Note: This is just an illustration of a possible serialization, not a specification of the serialized format.
 
 #### Example: Either or
-Assume account A, B and C and asset X and asset Y. Furthermore A has a custom active authority in the following way:
+Assume account A, B and C and asset X and asset Y. The custom active authority should now achieve
+ that a transfer transaction sending funds away from A can be signed with with active authority of account B if 
+- it sends less than 10000 of asset X to account C
+- it sends less than or equal to 20000 of asset Y to account C
+
+More concrete, the authority would look like
 ```
 custom active authority = {
     valid_from: 7.7.2018 00:00
@@ -240,24 +292,8 @@ or_list =
    }
 ]
 ```
-That has the consquence now that a transfer transaction sending funds away from A can be signed with with active authority of account B if 
-- it sends less than 10000 of asset X to account C
-- it sends less than or equal to 20000 of asset Y to account C
+Note: This is included with the third Milestone
 
-Note: 
-- This is just an illustration of a possible serialization, not a specification of the serialized format.
-- This is not included in the first Milestone
-
-### Outline of handling incoming transactions
- 
-When a signed transaction arrives and before the backend evaluates if all necessary authorities are present through the signatures, do the following:
-- iterate over required accounts and for each account, iterate over all operations within the transactions that require the active authority of this account
-- iterate the `custom_active_authorities` of said account
-- if a `custom_active_authority` is found that matches , remember that and stop iterating the authorities and continue until all operations are checked
-- if the account has a `custom active authority` match for every operation in the transaction that requires it, then grant the `active authority` of said account. If no match is found, treat as if no authority was given
-
-Note:
-- A `custom_active_authority` can only grant the `active authority` of the corresponding account, nothing more
 
 #### Example: Checking for custom active authorities
 
@@ -274,37 +310,6 @@ Acive authority of Account A is granted and normal authority checks are continue
 Since the required accounts is Account A, and the given accounts is also Account A through `custom active authority 2`, 
 the transaction is executed.
 
-### Modification to the backend
-
-* Add a new index or extend the account object to store custom active permission are assigned to an account and contain a list of custom active authorities. Multiple custom active authority entries are possible for one operation
-* If the active authority of the account is updated, all custom active authorities need to be confirmed in the update. Every unconfirmed one is deleted otherwise
-* Provide operations: `install_custom_active_authority`, `update_custom_active_authority`, `delete_custom_active_authority` to allow changing the custom active permission (3 operation to allow custom transaction fees and avoid having to send the complete list of all authorities for every update)
-* 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
-
-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:
-- `install_custom_active_authority`: Tied to the duration of the custom active authority. 
-Normal accounts can only create custom active authoritites with a duration of maximum 1 year. LTM can do any duration and also unlimited, but the transaction fee is capped at duration of 2 years.
-- `update_custom_active_authority` and `delete_custom_active_authority`: Similar to `account_update`
-
-# Milestones
-
-We propose do split the implmentation into two milestones. Each milestone will be voted on as a separate BSIP:
-
-1. Implementation of basic functionaliy to allow custom active permissions and authorities, including `any`, `none` and `lt, le, gt, ge` 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`
-
-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) and [pull request](https://github.com/bitshares/bsips/pull/86).
-
 # Summary for Shareholders
 
 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.