docs(dip-9): add asset lock subfeatures and document key types

dip-0009/assignments.md

@@ -6,7 +6,7 @@ Here is a table of current feature paths and any associated DIP. Future DIPs may
 | ------------------ | ------------ | ------------------- | ---- |
 | `3'` | Masternode Keys | [DIP 0003: Deterministic Masternode List](https://github.com/dashpay/dips/blob/master/dip-0003.md) | The masternode related keys are located in the following sub-paths:  <br>`0'/*` - _Reserved_<br>`1'/*` - Voting Key<br>`2'/*` - Owner Key<br>`3'/*` - Operator Key<br>`4'/*` - [Platform P2P Key](../dip-0028.md#calculating-the-platform-node-id) (ED25519)<br><br>For example, the first voting key for Dash would be at `m/9'/5'/3'/1'/0` |
 | `4'` | CoinJoin Keys | CoinJoin | The masternode related keys are located in the following sub-paths:  <br>`0'/0/*` - Account 0 (external)<br>`0'/1/*` - Account 0 (change, not typically used)<br><br>For example, the first key of Account 0 for CoinJoin would be at `m/9'/5'/4'/0'/0/0`.<br><br>The main purpose of this using this path is to segregate CoinJoin-related keys from the BIP44 paths that are used to receive coins and change.  CoinJoin derivation paths may require different lookup or gap values than the BIP44 paths that have much less transaction activity.  Additionally, it may be possible to prune used keys from the BIP37 bloom filters used by mobile apps.|
-| `5'` | Identity Keys | [DIP 0013: Identities in Hierarchical Deterministic wallets](../dip-0013.md) | The related keys are located in the following sub-paths: <br>`0'/key type'/identity index'/key index'/*` - Identity Authentication ([details](../dip-0013.md#identity-authentication-keys))<br>`1'/*` - Identity Registration Funding ([details](../dip-0013.md#identity-registration-funding-keys))<br>`2'/*` - Identity Topup Funding ([details](../dip-0013.md#identity-top-up-funding-keys))<br>`3'/*` - Identity Invitation Funding ([details](../dip-0013.md#identity-invitatation-funding-keys))<br><br>For example, the first Identity Registration Funding key for Dash would be at `m/9'/5'/5'/1'/0` |
+| `5'` | Identity Keys | [DIP 0013: Identities in Hierarchical Deterministic wallets](../dip-0013.md) | The related keys are located in the following sub-paths: <br>`0'/key type'/identity index'/key index'` - Identity Authentication ([details](../dip-0013.md#identity-authentication-keys))<br>&nbsp;&nbsp;&nbsp;&nbsp;Key types:<br>&nbsp;&nbsp;&nbsp;&nbsp;`0'` - ECDSA (secp256k1)<br>&nbsp;&nbsp;&nbsp;&nbsp;`1'` - BLS (bls12381)<br>`1'/*` - Identity Registration Asset Lock Funding ([details](../dip-0013.md#identity-registration-funding-keys))<br>`2'/*` - Identity Top up Asset Lock Funding ([details](../dip-0013.md#identity-top-up-funding-keys))<br>&nbsp;&nbsp;&nbsp;&nbsp;`2'/funding index` - Not bound to a specific identity<br>&nbsp;&nbsp;&nbsp;&nbsp;`2'/registration index'/top up index` - Bound to a specific identity<br>`3'/*` - Identity Invitation Asset Lock Funding ([details](../dip-0013.md#identity-invitation-funding-keys))<br>`4'/*` - Asset Lock Address Top up Funding<br>`5'/*` - Asset Lock Shielded Address Top up Funding<br><br>For example, the first ECDSA authentication key for the first identity on Dash would be at `m/9'/5'/5'/0'/0'/0'/0'`<br>The first Identity Registration Asset Lock Funding key for Dash would be at `m/9'/5'/5'/1'/0` |
 | `15'` | DashPay - Incoming Funds | [DIP 0015: DashPay](../dip-0015.md#dashpay-incoming-funds-derivation-path) | The related keys are located in the following sub-paths: `/0'/account'/*`<br><br>For example, incoming funds for the first identity would be at `m/9'/5'/15'/0'/*` |
 | `16'` | DashPay - Auto Accept Proof | [DIP 0015: DashPay](../dip-0015.md#auto-accept-proof-autoacceptproof) | The related keys are located in the following sub-paths: `16'/expiration timestamp'`<br><br>For example, the key for a proof expiring at a Unix epoch time of `1605927033` would be at `m/9'/5'/16'/1605927033'` |
 

dip-0013.md

@@ -102,7 +102,7 @@ the case with non-hardened keys.
 
 # Identity Registration Funding keys
 
-Identity Funding keys can either be for a registration or for a topup. We will create for each
+Identity Funding keys can either be for a registration or for a top up. We will create for each
 wallet two sets of secp256k1 keys. Funding transactions using these keys will be perceived as
 identical on the network. However by separating these keys based on two derivation paths, wallets
 can keep track of the motivation behind each credit funding transaction.
@@ -134,19 +134,35 @@ must use HASH160 of the public key which is one round of SHA256 followed by one
 
 # Identity Top Up Funding keys
 
-Identity Funding keys used for topup are the third sub-feature for identities. They are always
+Identity Funding keys used for top up are the third sub-feature for identities. They are always
 derived as ECDSA keys.
 
-We define the following levels for them:
+Sub feature is set to `2'`.
+
+There are two derivation methods for top up funding keys:
+
+## Top Up Funding keys not bound to a specific identity
 
 `m / purpose' / coin_type' / feature' / sub feature' / funding index`
 
-Sub feature is set to `2'`.
+These keys do not reference an identity and can be used to top up any identity. It is useful to
+point out that a registration funding key is a source of entropy in the unique identifier of the
+identity it will fund, and this is obviously not the case for top up funding keys.
+
+For example, the first unbound top up funding key for Dash would be at `m/9'/5'/5'/2'/0`.
+
+## Top Up Funding keys bound to a specific identity
 
-We should note that unlike Identity Registration keys, Top Up Funding keys do not reference an
-identity and can be used to top up any identity. It is useful to point out that a registration
-funding key is a source of entropy in the unique identifier of the identity it will fund, and this
-is obviously not the case for top up funding keys.
+`m / purpose' / coin_type' / feature' / sub feature' / registration index' / top up index`
+
+These keys include a hardened registration index that ties the top up to a specific identity.
+The registration index corresponds to the identity being topped up, and the top up index is a
+sequential non-hardened index for each top up transaction.
+
+For example, the first top up funding key for the first identity on Dash would be at
+`m/9'/5'/5'/2'/0'/0`.
+
+## Recovery and reuse
 
 If a wallet recovers an unused top up funding transaction, the wallet should attempt to reuse it.
 This is done in a few steps. First, the wallet must recognise the key used in a returned identity
@@ -155,9 +171,11 @@ the top up transaction has already been used and the balance transferred into cr
 not the case, the wallet can then perform an identity top up transition as defined in DIP11 using
 the top up funding key.
 
-It is recommended that 30 address hashes of these keys be added to the bloom filter sent to peers.
-If transactions containing 25 address hashes or more have been found, the filter should be
-regenerated with 30 more.
+It is recommended that 30 address hashes of unbound top up funding keys and 30 address hashes of
+bound top up funding keys for each known identity be added to the bloom filter sent to peers. If
+transactions containing 25 address hashes or more have been found for unbound keys, the filter
+should be regenerated with 30 more. If transactions containing 25 address hashes or more have been
+found for one or more identities, the relevant filter(s) should be regenerated with 30 more.
 
 # Identity Invitation Funding keys