diff --git a/mint-005.md b/mint-005.md index 9882d5e..70977e0 100644 --- a/mint-005.md +++ b/mint-005.md @@ -8,9 +8,9 @@ To provide a custody arrangement in which an owner of bitcoin (Principal) is abl This introduces a concept of "Negative Control" where, by default, funds are not able to be moved unless both the Principal and Agent sign the transaction. -In the event the Principal loses access to all of their keys, a secondary agent is available to work with the Primary Agent such that funds can be recovered after a set period of time. +In the event the Principal loses access to all of their keys, a Secondary Agent is available to work with the Primary Agent such that funds can be recovered after a set period of time. -In the unlikely event the Primary Agent has lost 2 of their 3 keys, a timelock enabled threshold allows only 1 of 3 keys from the Primary Agent to be signed with the secondary agent. +In the unlikely event the Principal has lost 2 of their 3 keys, a timelock enabled threshold allows only 1 of 3 Principal keys to be signed (instead of 2), while still requiring the Primary Agent's 2-of-3 signature. Finally, in the event the Principal no longer wishes to work with the agent, say after a contract expires, the custody defers to a set of recovery keys, which can be held either by the Principal, or their own delegated managers of the recovery keys. As a result, when enough time has passed, the Principal is able to move bitcoin unilaterally without having the Agent sign key material. @@ -18,9 +18,9 @@ Finally, in the event the Principal no longer wishes to work with the agent, say There are three timelocks used for this MinT: -1. `smallest_epoch_timestamp` - The smallest epoch timestamp timelock enables a "Asset Recovery" period such that only one of the Principal keys is required to sign. +1. `smallest_epoch_timestamp` - The smallest epoch timestamp timelock enables an "Asset Recovery" period such that only one of the Principal keys is required to sign. -2. `between_epoch_timestamp` - The epoch timestamp value in between the smallest and largest epoch timestamp enables a "Emergency Recovery Path". In the event the Principal has lost all of their keys, the Primary Agent and Secondary Agent can work together to recover the bitcoin in the Joint Custody vault. +2. `between_epoch_timestamp` - The epoch timestamp value in between the smallest and largest epoch timestamp enables an "Emergency Recovery Path". In the event the Principal has lost all of their keys, the Primary Agent and Secondary Agent can work together to recover the bitcoin in the Joint Custody vault. 3. `largest_epoch_timestamp` - The largest epoch timestamp, signifying the expiration of the contract, where the Principal is able to unilaterally withdraw their bitcoin from the joint custody vault. @@ -31,8 +31,8 @@ In total, there are 10 keys in use for the 3 Key Joint Custody Vault, they are a | Key Names | Description | Key Abbreviations | Key Symbol | |:--|:--:|:--:|:--:| |Principal Keys 1,2,3 | These keys belong to the owner of the bitcoin. They are used as the default keys the Principal uses to transact bitcoin for the length of the relationship with the agent in the Joint Custody vault. | $PK_1$, $PK_2$, $PK_3$ |
![Blue Key](https://raw.githubusercontent.com/Rob1Ham/miniscript-templates/main/assets/key_blue.png)
| -|Primary Agent Keys 1,2,3 | These keys belong to the agent, who the Principal has engaged with to fascilitate the securing of bitcoin for a determined set of time. | $PAK_1$, $PAK_2$, $PAK_3$ |
![Green Key](https://raw.githubusercontent.com/Rob1Ham/miniscript-templates/main/assets/key_green.png)
| -|Secondary Agent Key | This key is held by a 3rd party unassoicated with the other keys, in the event the Principal has lost a majority of their keys, can sign transactions with the Primary Agent to move funds after a designated "Recovery Period" has started. | $SAK$ |
![Red Key](https://raw.githubusercontent.com/Rob1Ham/miniscript-templates/83a8c241b2c2cf7ee940570aa97d8b0e1d751f55/assets/key_red.png)
| +|Primary Agent Keys 1,2,3 | These keys belong to the agent, who the Principal has engaged with to facilitate the securing of bitcoin for a determined set of time. | $PAK_1$, $PAK_2$, $PAK_3$ |
![Green Key](https://raw.githubusercontent.com/Rob1Ham/miniscript-templates/main/assets/key_green.png)
| +|Secondary Agent Key | This key is held by a 3rd party unassociated with the other keys, in the event the Principal has lost a majority of their keys, can sign transactions with the Primary Agent to move funds after a designated "Recovery Period" has started. | $SAK$ |
![Red Key](https://raw.githubusercontent.com/Rob1Ham/miniscript-templates/83a8c241b2c2cf7ee940570aa97d8b0e1d751f55/assets/key_red.png)
| |Recovery Keys 1,2,3 | These keys in practice belong to the Principal, they may even be keys related to the Principal Keys with a different derivation path, but can also be delegated key holders. After the initial Joint Custody vault agreement has ended, the recovery keys can unilaterally be used to withdraw money from the vault. | $RK_1$, $RK_2$, $RK_3$ |
![Gray Key](https://raw.githubusercontent.com/Rob1Ham/miniscript-templates/main/assets/key_gray.png)
| @@ -43,13 +43,13 @@ Below are reference diagrams on how the 3 Key Joint Custody operates across time ### Joint Custody Summary Layers -Layer is used as an abstraction to segement the different eligible spending conditions, going in an ascending order of timelock values. At the start, only "Layer 1" is accessible for spending funds, over time, other spending conditions become available, but this does not restrict the ability to spend from a proceeding layer. +Layer is used as an abstraction to segment the different eligible spending conditions, going in an ascending order of timelock values. At the start, only "Layer 1" is accessible for spending funds, over time, other spending conditions become available, but this does not restrict the ability to spend from a preceding layer. | Layer | Layer Name | Key Set 1 | Condition Between Sets | Key Set 2 | Timelock Condition | Timelock | |:-----:|:-------------------------:|:------------------------------:|:----------------------:|:------------------:|:------------------:|:-------------------------------:| | 1 | Default Spending Path | $PK_1$, $PK_2$, $PK_3$ (2 of 3)| AND | $PAK_1$, $PAK_2$, $PAK_3$ (2 of 3)| N/A | None | | 2 | Asset Recovery Path | $PK_1$, $PK_2$, $PK_3$ (1 of 3) | AND | $PAK_1$, $PAK_2$, $PAK_3$ (2 of 3) | AND | After (`smallest_epoch_timestamp`) | -| 3 | Emergency Recovery Path | $PAK_1$, $PAK_2$, $PAK_3$ (2 of 3)| AND | $SAK$ | N/A | After (`between_epoch_timestamp`) | +| 3 | Emergency Recovery Path | $PAK_1$, $PAK_2$, $PAK_3$ (2 of 3)| AND | $SAK$ | AND | After (`between_epoch_timestamp`) | | 4 | Sovereign Recovery Path | $RK_1$, $RK_2$, $RK_3$ (2 of 3)| None | None | AND | After (`largest_epoch_timestamp`) | ### Layer 1 @@ -202,33 +202,31 @@ Layer is used as an abstraction to segement the different eligible spending cond --- # Example Miniscript Output Descriptor -For this example, the `smallest_epoch_timestamp` is: 1672531200 (Jan 1 2023, midnight gmt), the `between_epoch_timestamp` is: 1673740800 and `largest_epoch_timestamp` is: 1675209600 (Feb 1 2023, midnight gmt) +For this example, the `smallest_epoch_timestamp` is: 1753488000 (July 26, 2025 00:00:00 UTC), the `between_epoch_timestamp` is: 1766880000 (December 28, 2025 00:00:00 UTC) and `largest_epoch_timestamp` is: 1770768000 (February 11, 2026 00:00:00 UTC) - MINT-005 Output Descriptor: -wsh(andor(multi(2,$PAK_1$,$PAK_2$,$PAK_3$),or_i(and_v(v:pkh($SAK$),after(`between_epoch_timestamp`)),thresh(2,pk($PK_1$),s:pk($PK_2$),s:pk($PK_3$),snl:after(`smallest_epoch_timestamp`))),and_v(v:thresh(2,pkh($RK_1$),a:pkh($RK_2$),a:pkh($RK_3$)),after(`larget_epoch_timestamp`)))) +wsh(andor(multi(2,$PAK_1$,$PAK_2$,$PAK_3$),or_i(and_v(v:pkh($SAK$),after(`between_epoch_timestamp`)),thresh(2,pk($PK_1$),s:pk($PK_2$),s:pk($PK_3$),snl:after(`smallest_epoch_timestamp`))),and_v(v:thresh(2,pkh($RK_1$),a:pkh($RK_2$),a:pkh($RK_3$)),after(`largest_epoch_timestamp`)))) - Source Policy (FOR REFERENCE PURPOSES ONLY): "or(99@and(thresh(2,pk($PAK_1$),pk($PAK_2$),pk($PAK_3$)),or(99@thresh(2,pk($PK_1$),pk($PK_2$),pk($PK_3$),after(`smallest_epoch_timestamp`)),and(pk($SAK$),after(`between_epoch_timestamp`)))),and(thresh(2,pk($RK_1$),pk($RK_2$),pk($RK_3)),after(`largest_epoch_timestamp`)))" ## Layer 1 Example Spend -Signed by: $PK_1$, $PK_2$, $PAK_1$, $PAK_2$ +Signed by: $PK_2$, $PK_3$, $PAK_1$, $PAK_2$ -[Reference Testnet -Transaction](https://mempool.space/signet/tx/2836d6af6b5c4bb01e926391f64771fb333193676040b24d4236ba0bb89a7008) +[Reference Testnet Transaction](https://mempool.space/signet/tx/8b5d80b6b9adf6dc2d0f83372e77b81150e67689a0119348f8cbbea1121afd97) ## Layer 2 Example Spend -Signed by: $PK_1$, $PK_2$, $SAK$ +Signed by: $PK_2$, $PAK_1$, $PAK_2$ -[Reference Testnet -Transaction](https://mempool.space/signet/tx/36aa3dfd0c7b4f4d8c7924c411e240920e4b4d36950ca59f68098b77162ae54d) +[Reference Testnet Transaction](https://mempool.space/signet/tx/07cbd89200f05dd68ade5f10f9f6e212278f7bd1dd0b494039fe99752eb10d46) ## Layer 3 Example Spend -[Reference Testnet -Transaction](https://mempool.space/signet/tx/bc75e9c7bd62168134a6283a56c2a0bf3c872cc6703d9566f1851309d5ef7465) +Signed by: $PAK_1$, $PAK_2$, $SAK$ + +[Reference Testnet Transaction](https://mempool.space/signet/tx/a10a5962098e5912887137735c39a39e921e7f9cdf65e68062aed4bd72988dc7) ## Layer 4 Example Spend Signed by: $RK_1$, $RK_2$ -[Reference Testnet -Transaction](https://mempool.space/signet/tx/1d35568360a3a11309c77c893142a0c0cf58ed9cfce981c5492c66fb795f1872) \ No newline at end of file +[Reference Testnet Transaction](https://mempool.space/signet/tx/1de409327398bcdcb9e5bb1dc31a52a77e9567a4ce17ff794e8cb76e201833c6) \ No newline at end of file diff --git a/mint-006.md b/mint-006.md new file mode 100644 index 0000000..6e2df67 --- /dev/null +++ b/mint-006.md @@ -0,0 +1,236 @@ +# mint-006 + +## 3 Key Joint Custody, Sovereign First + +## Motivation + +This vault is very similar to [mint-005.md](mint-005.md). The difference is the sequential order of the 3rd and 4th "layers", where the Principal is able to unilaterally move funds prior to the recovery layer. This is done for users who wish to make sure that funds will require the Principal to sign before the Primary Agent and Secondary Agent are able to move funds unilaterally. The recovery layer still exists to provide support to recover funds in the event the Principal has lost access to their keys. + +**Key differences from MINT-005:** First, the layer ordering is changed — the Sovereign Recovery Path (Recovery Keys only) comes *before* the Emergency Recovery Path (Primary Agent + Secondary Agent), meaning the Principal can unilaterally move funds before the agents gain the ability to recover without the Principal. Second, the Primary Agent Keys (PAKs) are listed as Key Set 1 and the Principal Keys (PKs) as Key Set 2 in the summary table and layer diagrams, which is the reverse of MINT-005's column ordering. Together, these changes result in a different miniscript output descriptor. + + +### More on Timelock Values + +There are three timelocks used for this MinT: + +1. `smallest_epoch_timestamp` - The smallest epoch timestamp timelock enables a "Degraded Threshold Path" such that only one of the three Principal keys is required to sign (instead of two), while still requiring the Primary Agent 2-of-3. + +2. `between_epoch_timestamp` - The epoch timestamp value in between the smallest and largest epoch timestamp enables a "Sovereign Recovery Path". At this point, the Principal (via their Recovery Keys) can unilaterally withdraw bitcoin from the vault using a 2-of-3 multisig. + +3. `largest_epoch_timestamp` - The largest epoch timestamp, signifying the final emergency recovery period, where the Primary Agent and Secondary Agent can work together to recover the bitcoin in the Joint Custody vault. + +### Keys + +In total, there are 10 keys in use for the 3 Key Joint Custody, Sovereign First Vault, they are as follows: + +| Key Names | Description | Key Abbreviations | Key Symbol | +|:--|:--:|:--:|:--:| +|Principal Keys 1,2,3 | These keys belong to the owner of the bitcoin. They are used as the default keys the Principal uses to transact bitcoin for the length of the relationship with the Primary Agent in the Joint Custody vault. After the first timelock, the requirement degrades from 2-of-3 to 1-of-3. | $PK_1$, $PK_2$, $PK_3$ |
![Blue Key](https://raw.githubusercontent.com/Rob1Ham/miniscript-templates/main/assets/key_blue.png)
| +|Primary Agent Keys 1,2,3 | These keys belong to the Primary Agent, who the Principal has engaged with to facilitate the securing of bitcoin for a determined set of time. A 2-of-3 threshold is always required from these keys in the collaborative spending paths. | $PAK_1$, $PAK_2$, $PAK_3$ |
![Green Key](https://raw.githubusercontent.com/Rob1Ham/miniscript-templates/main/assets/key_green.png)
| +|Secondary Agent Key | This key is held by a 3rd party unassociated with the other keys. In the event both the Principal has lost all keys AND the Recovery Keys are unavailable, this key can sign transactions with the Primary Agent to move funds after the longest timelock period. | $SAK$ |
![Red Key](https://raw.githubusercontent.com/Rob1Ham/miniscript-templates/83a8c241b2c2cf7ee940570aa97d8b0e1d751f55/assets/key_red.png)
| +|Recovery Keys 1,2,3 | These keys in practice belong to the Principal, they may even be keys related to the Principal Keys with a different derivation path, but can also be delegated key holders. After a middle timelock period, these recovery keys can unilaterally be used to withdraw money from the vault using a 2-of-3 multisig. | $RK_1$, $RK_2$, $RK_3$ |
![Gray Key](https://raw.githubusercontent.com/Rob1Ham/miniscript-templates/main/assets/key_gray.png)
| + + + +Below are reference diagrams on how the 3 Key Joint Custody, Sovereign First Vault operates across time: + +--- + +### Joint Custody Summary Layers + +Layer is used as an abstraction to segment the different eligible spending conditions, going in an ascending order of timelock values. At the start, only "Layer 1" is accessible for spending funds, over time, other spending conditions become available, but this does not restrict the ability to spend from a preceding layer. + +| Layer | Layer Name | Key Set 1 | Condition Between Sets | Key Set 2 | Timelock Condition | Timelock | +|:-----:|:-------------------------:|:------------------------------:|:----------------------:|:------------------:|:------------------:|:-------------------------------:| +| 1 | Default Spending Path | $PAK_1$, $PAK_2$, $PAK_3$ (2 of 3)| AND | $PK_1$, $PK_2$, $PK_3$ (2 of 3)| N/A | None | +| 2 | Degraded Threshold Path | $PAK_1$, $PAK_2$, $PAK_3$ (2 of 3)| AND | $PK_1$, $PK_2$, $PK_3$ (1 of 3)| AND | After (`smallest_epoch_timestamp`) | +| 3 | Sovereign Recovery Path | $RK_1$, $RK_2$, $RK_3$ (2 of 3)| None | None | AND | After (`between_epoch_timestamp`) | +| 4 | Emergency Recovery Path | $PAK_1$, $PAK_2$, $PAK_3$ (2 of 3)| AND | $SAK$ | AND | After (`largest_epoch_timestamp`) | + +### Layer 1 + + + + + + + + + + + + + + + + + + + + + + + + +
Default Spending Path2 of 3 PAKs2 of 3 PKs
PAK1PAK2PAK3PK1PK2PK3
2 of 3 PAKs AND 2 of 3 PKsPAK1PAK2PAK3PK1PK2PK3
+ +#### Valid Layer 1 Spend Conditions +| Spending Scenario | $PAK_1$ | $PAK_2$ | $PAK_3$ | $PK_1$ | $PK_2$ | $PK_3$ | +|-------------------|:------:|:------:|:------:|:------:|:------:|:------:| +| Scenario 1 | ✅ | ✅ | | ✅ | ✅ | | +| Scenario 2 | ✅ | ✅ | | ✅ | | ✅ | +| Scenario 3 | ✅ | ✅ | | | ✅ | ✅ | +| Scenario 4 | ✅ | | ✅ | ✅ | ✅ | | +| Scenario 5 | ✅ | | ✅ | ✅ | | ✅ | +| Scenario 6 | ✅ | | ✅ | | ✅ | ✅ | +| Scenario 7 | | ✅ | ✅ | ✅ | ✅ | | +| Scenario 8 | | ✅ | ✅ | ✅ | | ✅ | +| Scenario 9 | | ✅ | ✅ | | ✅ | ✅ | + + +#### Layer 2 + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Degraded Threshold Path2 of 3 PAKs1 of 3 PKsBIP-113 time greater than `smallest_epoch_timestamp`
PAK1PAK2PAK3PK1PK2PK3
2 of 3 PAKs AND 1 of 3 PKs AND BIP-113 time is greater than `smallest_epoch_timestamp`PAK1PAK2PAK3PK1PK2PK3Timelock
+ + +##### Valid Layer 2 Spend Conditions +| Spending Scenario | $PAK_1$ | $PAK_2$ | $PAK_3$ | $PK_1$ | $PK_2$ | $PK_3$ | BIP-113 greater than `smallest_epoch_timestamp` | +|-------------------|:------:|:------:|:------:|:------:|:------:|:------:|:-----------------------------------------------:| +| Scenario 10 | ✅ | ✅ | | ✅ | | | ✅ | +| Scenario 11 | ✅ | ✅ | | | ✅ | | ✅ | +| Scenario 12 | ✅ | ✅ | | | | ✅ | ✅ | +| Scenario 13 | ✅ | | ✅ | ✅ | | | ✅ | +| Scenario 14 | ✅ | | ✅ | | ✅ | | ✅ | +| Scenario 15 | ✅ | | ✅ | | | ✅ | ✅ | +| Scenario 16 | | ✅ | ✅ | ✅ | | | ✅ | +| Scenario 17 | | ✅ | ✅ | | ✅ | | ✅ | +| Scenario 18 | | ✅ | ✅ | | | ✅ | ✅ | + +#### Layer 3: + + + + + + + + + + + + + + + + + + + + +
Sovereign Recovery Path2 of 3 RKsNetwork BIP-113 time greater than `between_epoch_timestamp`
RK1RK2RK3
2 of 3 RKs AND after BIP-113 time is greater than `between_epoch_timestamp`RK1RK2RK3Timelock
+ +##### Valid Layer 3 Spend Conditions +| Spending Scenario | $RK_1$ | $RK_2$ | $RK_3$ | BIP-113 time greater than (`between_epoch_timestamp`) | +|-------------------|:------:|:------:|:------:|:-----------------------------------------------------:| +| Scenario 19 | ✅ | ✅ | | ✅ | +| Scenario 20 | ✅ | | ✅ | ✅ | +| Scenario 21 | | ✅ | ✅ | ✅ | + +#### Layer 4: + + + + + + + + + + + + + + + + + + + + + + + +
Emergency Recovery Path2 of 3 PAKs1 SAKBIP-113 time greater than `largest_epoch_timestamp`
PAK1PAK2PAK3SAK
2 of 3 PAKs AND SAK AND after BIP-113 time is greater than `largest_epoch_timestamp`PAK1PAK2PAK3SAKTimelock
+ +##### Valid Layer 4 Spend Conditions +| Spending Scenario | $PAK_1$ | $PAK_2$ | $PAK_3$ | $SAK$ | BIP-113 time greater than (`largest_epoch_timestamp`) | +|-------------------|:------:|:------:|:------:|:-----:|:-----------------------------------------------------:| +| Scenario 22 | ✅ | ✅ | | ✅ | ✅ | +| Scenario 23 | ✅ | | ✅ | ✅ | ✅ | +| Scenario 24 | | ✅ | ✅ | ✅ | ✅ | + +--- +# Example Miniscript Output Descriptor + +- MINT-006 Output Descriptor: +wsh(andor(multi(2,$PAK_1$,$PAK_2$,$PAK_3$),andor(pk($SAK$),after(`largest_epoch_timestamp`),thresh(2,pk($PK_1$),s:pk($PK_2$),s:pk($PK_3$),snl:after(`smallest_epoch_timestamp`))),and_v(v:thresh(2,pkh($RK_1$),a:pkh($RK_2$),a:pkh($RK_3$)),after(`between_epoch_timestamp`)))) + +- Source Policy (FOR REFERENCE PURPOSES ONLY): +"or(99@and(thresh(2,pk($PAK_1$),pk($PAK_2$),pk($PAK_3$)),or(thresh(2,pk($PK_1$),pk($PK_2$),pk($PK_3$),after(`smallest_epoch_timestamp`)),and(pk($SAK$),after(`largest_epoch_timestamp`)))),and(thresh(2,pk($RK_1$),pk($RK_2$),pk($RK_3$)),after(`between_epoch_timestamp`)))" + +## Reference Implementation + +For the reference testnet transactions below, the following epoch timestamps were used: +- `smallest_epoch_timestamp`: 1688000400 (June 29, 2023 00:00:00 UTC) +- `between_epoch_timestamp`: 1704067200 (January 1, 2024 00:00:00 UTC) +- `largest_epoch_timestamp`: 1735689600 (January 1, 2025 00:00:00 UTC) + +## Layer 1 Example Spend + +Signed by: $PAK_1$, $PAK_2$, $PK_1$, $PK_2$ + +[Reference Testnet Transaction](https://mempool.space/signet/tx/cb5f6a595a77ac01afc9ac40641def2d6ae8978e7e9a12e7fc6b7dcb61ee901f) + +## Layer 2 Example Spend + +Signed by: $PAK_1$, $PAK_2$, $PK_1$ + +[Reference Testnet Transaction](https://mempool.space/signet/tx/7ea8816b5fcdb954836a60b699a71e3fbd54093f773ab818beb7767f60e40c14) + +## Layer 3 Example Spend + +Signed by: $RK_1$, $RK_2$ + +[Reference Testnet Transaction](https://mempool.space/signet/tx/a036f18e2888ab859bbd5547d717132aa1eefdebb78c53653c6c5d64680bc4a9) + +## Layer 4 Example Spend + +Signed by: $PAK_1$, $PAK_2$, $SAK$ + +[Reference Testnet Transaction](https://mempool.space/signet/tx/c3aaf3c0db07aa70a817953f12eb5b1b6b8ef25fd6c6cbb14b1c6189297a4763) \ No newline at end of file diff --git a/mint-007.md b/mint-007.md new file mode 100644 index 0000000..6e1d47d --- /dev/null +++ b/mint-007.md @@ -0,0 +1,166 @@ +# mint-007 + +## 1 Key Joint Custody + +## Motivation + +This template is similar to [mint-005.md](mint-005.md), with the difference being that the Principal uses a single key instead of a 2-of-3 multisig. This simplifies key management for the Principal while enabling robust joint custody. + + +### More on Timelock Values + +There are two timelocks used for this MinT: + +1. `smallest_epoch_timestamp` - The smallest epoch timestamp timelock enables an "Emergency Recovery Path". In the event the Principal has lost their key, the Primary Agent and Secondary Agent can work together to recover the bitcoin in the Joint Custody vault. + +2. `largest_epoch_timestamp` - The largest epoch timestamp, signifying the expiration of the contract, where the Principal is able to unilaterally withdraw their bitcoin from the joint custody vault using the Recovery Key. + +### Keys + +In total, there are 6 keys in use for the 1 Key Joint Custody Vault, they are as follows: + +| Key Names | Description | Key Abbreviations | Key Symbol | +|:--|:--:|:--:|:--:| +|Principal Key | This key belongs to the owner of the bitcoin. It is used as the default key the Principal uses to transact bitcoin for the length of the relationship with the Primary Agent in the Joint Custody vault. | $PK$ |
![Blue Key](https://raw.githubusercontent.com/Rob1Ham/miniscript-templates/main/assets/key_blue.png)
| +|Primary Agent Keys 1,2,3 | These keys belong to the Primary Agent, who the Principal has engaged with to facilitate the securing of bitcoin for a determined set of time. A 2-of-3 threshold is required from these keys in all collaborative spending paths. | $PAK_1$, $PAK_2$, $PAK_3$ |
![Green Key](https://raw.githubusercontent.com/Rob1Ham/miniscript-templates/main/assets/key_green.png)
| +|Secondary Agent Key | This key is held by a 3rd party unassociated with the other keys. In the event the Principal has lost their key, this key can sign transactions with the Primary Agent to move funds after a designated "Recovery Period" has started. | $SAK$ |
![Red Key](https://raw.githubusercontent.com/Rob1Ham/miniscript-templates/83a8c241b2c2cf7ee940570aa97d8b0e1d751f55/assets/key_red.png)
| +|Recovery Key | This key in practice belongs to the Principal, it may even be a key related to the Principal Key with a different derivation path, but can also be a delegated key holder. After the Joint Custody vault agreement has ended, the Recovery Key can unilaterally be used to withdraw money from the vault. | $RK$ |
![Gray Key](https://raw.githubusercontent.com/Rob1Ham/miniscript-templates/main/assets/key_gray.png)
| + + + +Below are reference diagrams on how the 1 Key Joint Custody Vault operates across time: + +--- + +### 1 Key Joint Custody Summary Layers + +Layer is used as an abstraction to segment the different eligible spending conditions, going in an ascending order of timelock values. At the start, only "Layer 1" is accessible for spending funds, over time, other spending conditions become available, but this does not restrict the ability to spend from a preceding layer. + +| Layer | Layer Name | Key Set 1 | Condition Between Sets | Key Set 2 | Timelock Condition | Timelock | +|:-----:|:-------------------------:|:------------------------------:|:----------------------:|:------------------:|:------------------:|:-------------------------------:| +| 1 | Default Spending Path | $PAK_1$, $PAK_2$, $PAK_3$ (2 of 3)| AND | $PK$ | N/A | None | +| 2 | Emergency Recovery Path | $PAK_1$, $PAK_2$, $PAK_3$ (2 of 3)| AND | $SAK$ | AND | After (`smallest_epoch_timestamp`) | +| 3 | Sovereign Recovery Path | $RK$ | None | None | AND | After (`largest_epoch_timestamp`) | + +### Layer 1 + + + + + + + + + + + + + + + + + + + + +
Default Spending Path2 of 3 PAKs1 PK
PAK1PAK2PAK3PK
2 of 3 PAKs AND PKPAK1PAK2PAK3PK
+ +#### Valid Layer 1 Spend Conditions +| Spending Scenario | $PAK_1$ | $PAK_2$ | $PAK_3$ | $PK$ | +|-------------------|:------:|:------:|:------:|:----:| +| Scenario 1 | ✅ | ✅ | | ✅ | +| Scenario 2 | ✅ | | ✅ | ✅ | +| Scenario 3 | | ✅ | ✅ | ✅ | + + +#### Layer 2 + + + + + + + + + + + + + + + + + + + + + + + +
Emergency Recovery Path2 of 3 PAKs1 SAKBIP-113 time greater than `smallest_epoch_timestamp`
PAK1PAK2PAK3SAK
2 of 3 PAKs AND SAK AND BIP-113 time is greater than `smallest_epoch_timestamp`PAK1PAK2PAK3SAKTimelock
+ + +##### Valid Layer 2 Spend Conditions +| Spending Scenario | $PAK_1$ | $PAK_2$ | $PAK_3$ | $SAK$ | BIP-113 greater than `smallest_epoch_timestamp` | +|-------------------|:------:|:------:|:------:|:-----:|:-----------------------------------------------:| +| Scenario 4 | ✅ | ✅ | | ✅ | ✅ | +| Scenario 5 | ✅ | | ✅ | ✅ | ✅ | +| Scenario 6 | | ✅ | ✅ | ✅ | ✅ | + +#### Layer 3: + + + + + + + + + + + + + + + + +
Sovereign Recovery Path1 RKNetwork BIP-113 time greater than `largest_epoch_timestamp`
RK
RK AND after BIP-113 time is greater than `largest_epoch_timestamp`RKTimelock
+ +##### Valid Layer 3 Spend Conditions +| Spending Scenario | $RK$ | BIP-113 time greater than (`largest_epoch_timestamp`) | +|-------------------|:----:|:-----------------------------------------------------:| +| Scenario 7 | ✅ | ✅ | + +--- +# Example Miniscript Output Descriptor + +- MINT-007 Output Descriptor: +wsh(andor(multi(2,$PAK_1$,$PAK_2$,$PAK_3$),or_d(pk($PK$),and_v(v:pk($SAK$),after(`smallest_epoch_timestamp`))),and_v(v:pkh($RK$),after(`largest_epoch_timestamp`)))) + +- Source Policy (FOR REFERENCE PURPOSES ONLY): +"or(99@and(thresh(2,pk($PAK_1$),pk($PAK_2$),pk($PAK_3$)),or(pk($PK$),and(pk($SAK$),after(`smallest_epoch_timestamp`)))),and(pk($RK$),after(`largest_epoch_timestamp`)))" + +## Reference Implementation + +For the reference testnet transactions below, the following epoch timestamps were used: +- `smallest_epoch_timestamp`: 1733011200 (December 1, 2024 00:00:00 UTC) +- `largest_epoch_timestamp`: 1736899200 (January 15, 2025 00:00:00 UTC) + +## Layer 1 Example Spend + +Signed by: $PAK_1$, $PAK_2$, $PK$ + +[Reference Testnet Transaction](https://mempool.space/signet/tx/a6a63180b843761fee3217e18b31473ddaee690ca9fdfabaca1a01737a68a373) + +## Layer 2 Example Spend + +Signed by: $PAK_1$, $PAK_2$, $SAK$ + +[Reference Testnet Transaction](https://mempool.space/signet/tx/47807141fe971834c8f8e483dfc20338aecc55af796c534d4855e578c00d59b8) + +## Layer 3 Example Spend + +Signed by: $RK$ + +[Reference Testnet Transaction](https://mempool.space/signet/tx/cd353c14985451911d4bbd37327fd99a759f26f4dc36e4ee8efb23ae23b8389c) + diff --git a/mint-008.md b/mint-008.md new file mode 100644 index 0000000..aecd2fa --- /dev/null +++ b/mint-008.md @@ -0,0 +1,173 @@ +# mint-008 + +## 1 Key Joint Custody, Sovereign First + +## Motivation + +This vault is similar to [mint-007.md](mint-007.md), using a single Principal key instead of a 2-of-3 multisig for simpler key management. Like [mint-006.md](mint-006.md), it uses an alternative timelock ordering where the sovereign recovery path is available before emergency recovery. + +By using a single Principal key rather than a 2-of-3 multisig, this vault simplifies key management for the Principal while still maintaining robust security through the Primary Agent's 2-of-3 multisig. The vault requires both the Principal and Primary Agent to sign by default, providing strong collaborative custody. + +After the initial timelock expires, the Principal can move funds unilaterally. If the Principal has lost their key, the Principal can work with the Primary and Secondary Agents to recover funds after the second timelock period. + +This timelock ordering, with sovereign recovery before emergency recovery, may be preferable when counter party risk is a greater concern than a principal losing their key. + +### More on Timelock Values + +There are two timelocks used for this MinT: + +1. `smallest_epoch_timestamp` - The smallest epoch timestamp timelock enables the "Sovereign Recovery Path". This signifies the expiration of the custody contract, where the Principal is able to unilaterally withdraw their bitcoin from the joint custody vault using the Recovery Key. This comes FIRST, prioritizing the Principal's self-custody rights. + +2. `largest_epoch_timestamp` - The largest epoch timestamp enables the "Emergency Recovery Path". In the event the Principal has lost their key after the custody period, the Primary Agent and Secondary Agent can work together to recover the bitcoin. This comes SECOND, providing a safety net only after sovereign recovery was available. + +### Keys + +In total, there are 6 keys in use for the 1 Key Joint Custody Vault, they are as follows: + +| Key Names | Description | Key Abbreviations | Key Symbol | +|:--|:--:|:--:|:--:| +|Principal Key | This key belongs to the owner of the bitcoin. It is used as the default key the Principal uses to transact bitcoin for the length of the relationship with the Primary Agent in the Joint Custody vault. | $PK$ |
![Blue Key](https://raw.githubusercontent.com/Rob1Ham/miniscript-templates/main/assets/key_blue.png)
| +|Primary Agent Keys 1,2,3 | These keys belong to the Primary Agent, who the Principal has engaged with to facilitate the securing of bitcoin for a determined set of time. A 2-of-3 threshold is required from these keys in all collaborative spending paths. | $PAK_1$, $PAK_2$, $PAK_3$ |
![Green Key](https://raw.githubusercontent.com/Rob1Ham/miniscript-templates/main/assets/key_green.png)
| +|Secondary Agent Key | This key is held by a 3rd party unassociated with the other keys. In the event the Principal has lost their key, this key can sign transactions with the Primary Agent to move funds after a designated "Recovery Period" has started. | $SAK$ |
![Red Key](https://raw.githubusercontent.com/Rob1Ham/miniscript-templates/83a8c241b2c2cf7ee940570aa97d8b0e1d751f55/assets/key_red.png)
| +|Recovery Key | This key in practice belongs to the Principal, it may even be a key related to the Principal Key with a different derivation path, but can also be a delegated key holder. After the Joint Custody vault agreement has ended, the Recovery Key can unilaterally be used to withdraw money from the vault. | $RK$ |
![Gray Key](https://raw.githubusercontent.com/Rob1Ham/miniscript-templates/main/assets/key_gray.png)
| + + + +Below are reference diagrams on how the 1 Key Joint Custody Vault operates across time: + +--- + +### 1 Key Joint Custody Summary Layers + +Layer is used as an abstraction to segment the different eligible spending conditions, going in an ascending order of timelock values. At the start, only "Layer 1" is accessible for spending funds, over time, other spending conditions become available, but this does not restrict the ability to spend from a preceding layer. + +| Layer | Layer Name | Key Set 1 | Condition Between Sets | Key Set 2 | Timelock Condition | Timelock | +|:-----:|:-------------------------:|:------------------------------:|:----------------------:|:------------------:|:------------------:|:-------------------------------:| +| 1 | Default Spending Path | $PAK_1$, $PAK_2$, $PAK_3$ (2 of 3)| AND | $PK$ | N/A | None | +| 2 | Sovereign Recovery Path | $RK$ | None | None | AND | After (`smallest_epoch_timestamp`) | +| 3 | Emergency Recovery Path | $PAK_1$, $PAK_2$, $PAK_3$ (2 of 3)| AND | $SAK$ | AND | After (`largest_epoch_timestamp`) | + +### Layer 1 + + + + + + + + + + + + + + + + + + + + +
Default Spending Path2 of 3 PAKs1 PK
PAK1PAK2PAK3PK
2 of 3 PAKs AND PKPAK1PAK2PAK3PK
+ +#### Valid Layer 1 Spend Conditions +| Spending Scenario | $PAK_1$ | $PAK_2$ | $PAK_3$ | $PK$ | +|-------------------|:------:|:------:|:------:|:----:| +| Scenario 1 | ✅ | ✅ | | ✅ | +| Scenario 2 | ✅ | | ✅ | ✅ | +| Scenario 3 | | ✅ | ✅ | ✅ | + + +#### Layer 2 + + + + + + + + + + + + + + + + +
Sovereign Recovery Path (FIRST)1 RKNetwork BIP-113 time greater than `smallest_epoch_timestamp`
RK
RK AND after BIP-113 time is greater than `smallest_epoch_timestamp`RKTimelock
+ +##### Valid Layer 2 Spend Conditions +| Spending Scenario | $RK$ | BIP-113 time greater than (`smallest_epoch_timestamp`) | +|-------------------|:----:|:------------------------------------------------------:| +| Scenario 4 | ✅ | ✅ | + +#### Layer 3: + + + + + + + + + + + + + + + + + + + + + + + +
Emergency Recovery Path (SECOND)2 of 3 PAKs1 SAKBIP-113 time greater than `largest_epoch_timestamp`
PAK1PAK2PAK3SAK
2 of 3 PAKs AND SAK AND BIP-113 time is greater than `largest_epoch_timestamp`PAK1PAK2PAK3SAKTimelock
+ +##### Valid Layer 3 Spend Conditions +| Spending Scenario | $PAK_1$ | $PAK_2$ | $PAK_3$ | $SAK$ | BIP-113 greater than `largest_epoch_timestamp` | +|-------------------|:------:|:------:|:------:|:-----:|:----------------------------------------------:| +| Scenario 5 | ✅ | ✅ | | ✅ | ✅ | +| Scenario 6 | ✅ | | ✅ | ✅ | ✅ | +| Scenario 7 | | ✅ | ✅ | ✅ | ✅ | + +--- +# Example Miniscript Output Descriptor + +- MINT-008 Output Descriptor: +wsh(andor(multi(2,$PAK_1$,$PAK_2$,$PAK_3$),or_d(pk($PK$),and_v(v:pk($SAK$),after(`largest_epoch_timestamp`))),and_v(v:pkh($RK$),after(`smallest_epoch_timestamp`)))) + +- Source Policy (FOR REFERENCE PURPOSES ONLY): +"or(99@and(thresh(2,pk($PAK_1$),pk($PAK_2$),pk($PAK_3$)),or(pk($PK$),and(pk($SAK$),after(`largest_epoch_timestamp`)))),and(pk($RK$),after(`smallest_epoch_timestamp`)))" + +## Reference Implementation + +For the reference testnet transactions below, the following epoch timestamps were used: +- `smallest_epoch_timestamp`: 1704067200 (January 1, 2024 00:00:00 UTC) - Sovereign Recovery Path +- `largest_epoch_timestamp`: 1735689600 (January 1, 2025 00:00:00 UTC) - Emergency Recovery Path + +## Layer 1 Example Spend + +Signed by: $PAK_1$, $PAK_2$, $PK$ + +[Reference Testnet Transaction](https://mempool.space/signet/tx/587c729158da463c3b1873f8d83440b202d85f2c71992fc815ebe8ae94736441) + +## Layer 2 Example Spend (Sovereign Recovery - First) + +Signed by: $RK$ + +**Note:** This is the sovereign recovery path that becomes available after the first timelock (Jan 1, 2024). + +[Reference Testnet Transaction](https://mempool.space/signet/tx/dcb508c79318ee081745358b93d89dd56ea5e2bfdfc5dbd5ba0e7cb531bb8dd0) + +## Layer 3 Example Spend (Emergency Recovery - Second) + +Signed by: $PAK_1$, $PAK_2$, $SAK$ + +**Note:** This is the emergency recovery path that becomes available after the second timelock (Jan 1, 2025). + +[Reference Testnet Transaction](https://mempool.space/signet/tx/b12fd6ba3e8a9940de16ea43c841282a8abc04920defbcaa4ba2c7b0bb6228ef) \ No newline at end of file diff --git a/mint-009.md b/mint-009.md new file mode 100644 index 0000000..67399c4 --- /dev/null +++ b/mint-009.md @@ -0,0 +1,150 @@ +# mint-009 + +## 2 Agent Joint Custody with Recovery + +## Motivation + +To provide a streamlined custody arrangement in which an owner of bitcoin (Principal) is able to secure bitcoin by working with a Primary Agent and Secondary Agent. This model introduces a **dual-agent authorization** structure where funds can only be moved when **both** the Primary Agent and Secondary Agent sign the transaction. + +Unlike traditional multisig where keys are distributed equally, this model requires explicit cooperation between two distinct parties - typically a Principal's chosen service provider (Primary Agent) and a custody specialist (Secondary Agent) - before any funds can be moved. + +In the event of catastrophic key loss or after a predetermined custody period, a set of Recovery keys becomes available to move funds unilaterally, ensuring bitcoin is never permanently locked. + +### Key Characteristics + +- **Dual Agent Authorization**: Both Primary Agent (1-of-2) and Secondary Agent (2-of-3) must approve all transactions +- **True Negative Control**: Neither agent can move funds without the other during normal operations +- **Flexible Recovery**: Recovery keys can be held by the Principal, Primary Agent, Secondary Agent, or a third-party custodian +- **Time-Bounded**: Recovery path activates after a specified date, allowing contract expiration + +### More on Timelock Values + +This MinT uses a single timelock for simplification: + +1. `recovery_epoch_timestamp` - The recovery epoch timestamp enables a "Recovery Path" where the Primary Agent (or their designated recovery key holders) can unilaterally withdraw bitcoin after the custody agreement has expired or in emergency situations after the timelock has passed. + +### Keys + +In total, there are 7 keys in use for the 2 Agent Joint Custody Vault with Recovery, they are as follows: + +| Key Names | Description | Key Abbreviations | Key Symbol | +|:--|:--:|:--:|:--:| +|Primary Agent Keys 1,2 | These keys belong to the Primary Agent - typically the Principal's chosen service provider (e.g., an exchange, payment processor, or financial institution). At least 1 of these 2 keys is required for any transaction during the custody period. | $PAK_1$, $PAK_2$ |
![Blue Key](https://raw.githubusercontent.com/Rob1Ham/miniscript-templates/main/assets/key_blue.png)
| +|Secondary Agent Keys 1,2,3 | These keys belong to the Secondary Agent - typically a specialized custody provider. At least 2 of these 3 keys are required for any transaction during the custody period. This provides operational redundancy while maintaining security. | $SAK_1$, $SAK_2$, $SAK_3$ |
![Green Key](https://raw.githubusercontent.com/Rob1Ham/miniscript-templates/main/assets/key_green.png)
| +|Recovery Keys 1,2 | These keys provide ultimate fallback control after the timelock expires. They can be held by the Principal, distributed between both agents, held by a third-party custodian, or any combination thereof. Only 1 of 2 recovery keys is needed to spend after the timelock. | $RK_1$, $RK_2$ |
![Gray Key](https://raw.githubusercontent.com/Rob1Ham/miniscript-templates/main/assets/key_gray.png)
| + +--- + +Below are reference diagrams on how the 2 Agent Joint Custody with Recovery operates across time: + +--- + +### Joint Custody Summary Layers + +Layer is used as an abstraction to segment the different eligible spending conditions, going in an ascending order of timelock values. At the start, only "Layer 1" is accessible for spending funds, over time, other spending conditions become available, but this does not restrict the ability to spend from a preceding layer. + +| Layer | Layer Name | Key Set 1 | Condition Between Sets | Key Set 2 | Timelock Condition | Timelock | +|:-----:|:-------------------------:|:------------------------------:|:----------------------:|:------------------:|:------------------:|:-------------------------------:| +| 1 | Default Spending Path | $PAK_1$, $PAK_2$ (1 of 2)| AND | $SAK_1$, $SAK_2$, $SAK_3$ (2 of 3)| N/A | None | +| 2 | Sovereign Recovery Path | $RK_1$, $RK_2$ (1 of 2)| None | None | AND | After (`recovery_epoch_timestamp`) | + +### Layer 1 + + + + + + + + + + + + + + + + + + + + + + +
Default Spending Path1 of 2 PAKs2 of 3 SAKs
PAK1PAK2SAK1SAK2SAK3
1 of 2 PAKs AND 2 of 3 SAKsPAK1PAK2SAK1SAK2SAK3
+ +#### Valid Layer 1 Spend Conditions +| Spending Scenario | $PAK_1$ | $PAK_2$ | $SAK_1$ | $SAK_2$ | $SAK_3$ | +|-------------------|:------:|:------:|:-------:|:-------:|:-------:| +| Scenario 1 | ✅ | | ✅ | ✅ | | +| Scenario 2 | ✅ | | ✅ | | ✅ | +| Scenario 3 | ✅ | | | ✅ | ✅ | +| Scenario 4 | | ✅ | ✅ | ✅ | | +| Scenario 5 | | ✅ | ✅ | | ✅ | +| Scenario 6 | | ✅ | | ✅ | ✅ | + +**Explanation**: The Primary Agent selects one of their two keys (providing flexibility and redundancy), while the Secondary Agent must provide two of their three keys (ensuring institutional-grade security with operational continuity). This structure prevents either party from unilaterally moving funds while maintaining practical redundancy. + +#### Layer 2: + + + + + + + + + + + + + + + + + + +
Sovereign Recovery Path1 of 2 RKsBIP-113 time greater than `recovery_epoch_timestamp`
RK1RK2
1 of 2 RKs AND after BIP-113 time is greater than `recovery_epoch_timestamp`RK1RK2Timelock
+ +##### Valid Layer 2 Spend Conditions +| Spending Scenario | RK_1 | RK_2 | Timelock (recovery_epoch_timestamp) | +|-------------------|:----:|:----:|:----------------------------------:| +| Scenario 7 | ✅ | | ✅ | +| Scenario 8 | | ✅ | ✅ | + +**Explanation**: After the recovery timelock expires (e.g., contract expiration date, emergency recovery period), either recovery key can independently spend the bitcoin. This provides ultimate protection against key loss while maintaining the dual-agent authorization requirement during the active custody period. + +--- +# Example Miniscript Output Descriptor + +For this example, the `recovery_epoch_timestamp` is: 1727740800 (October 1, 2025, midnight UTC) + +- MINT-009 Output Descriptor: +wsh(andor(multi(1,$PAK_1$,$PAK_2$),multi(2,$SAK_1$,$SAK_2$,$SAK_3$),and_v(v:multi(1,$RK_1$,$RK_2$),after(`recovery_epoch_timestamp`)))) + +- Source Policy (FOR REFERENCE PURPOSES ONLY): +"or(and(thresh(2,pk($SAK_1$),pk($SAK_2$),pk($SAK_3$)),thresh(1,pk($PAK_1$),pk($PAK_2$))),and(after(`recovery_epoch_timestamp`),thresh(1,pk($RK_1$),pk($RK_2$))))" + + + +## Reference Implementation + +**Test Network:** Bitcoin Signet + +For the reference testnet transactions below, the following epoch timestamp was used: +- `recovery_epoch_timestamp`: 1727740800 (October 1, 2025 00:00:00 UTC) + +## Layer 1 Example Spend + +Signed by: $PAK_1$, $SAK_1$, $SAK_2$ + + +[Reference Testnet Transaction](https://mempool.space/signet/tx/be2f19d0877237ec4fa900db79be2d9fdb469d60b6c6d3548da92cbef1210809) + + +## Layer 2 Example Spend + +Signed by: $RK_1$ + + +[Reference Testnet Transaction](https://mempool.space/signet/tx/392aaceada1f6e97688db3a9d447e06837aa68eac12bd8076571ffe5c7cd37c7) \ No newline at end of file