diff --git a/Revault-Tx-Diagram.png b/Revault-Tx-Diagram.png deleted file mode 100644 index 6e3ddc9..0000000 Binary files a/Revault-Tx-Diagram.png and /dev/null differ diff --git a/TX-Diagram.jpg b/TX-Diagram.jpg new file mode 100644 index 0000000..bf4adbc Binary files /dev/null and b/TX-Diagram.jpg differ diff --git a/introduction.md b/introduction.md index 53d7e77..6e50da0 100644 --- a/introduction.md +++ b/introduction.md @@ -28,24 +28,24 @@ In addition, Revault comes with an (optional) deterrent feature for emergency sc ## Process and Revault Transaction Types -![Revault Transaction Graph. ](Revault-Tx-Diagram.png) +![Revault Transaction Graph. Note that only one of the Cancel, Unvault Emergency or Spend TXs can consume a specific UTXO, and that the Spend TX has lowest priority as it must wait for the unvault time-lock to expire.](TX-Diagram.jpg) -Funds enter custody through Deposit transactions (TXs) as unspent-transaction-outputs (UTXOs) locked to the *deposit output descriptor*, an N-of-N multi-signature among stakeholders. After receiving a deposit, the stakeholders exchange signatures for a set of 4 transactions which are _not broadcast_. These "pre-signed" transactions are used by stakeholders to control the flow of funds and enable the delegation and emergency deterrent features of Revault. As seen in the diagram, they include; Emergency, Unvault, Cancel and Unvault Emergency TXs. +Funds enter custody through Deposit transactions (TXs) as unspent-transaction-outputs (UTXOs) locked to the *[deposit output descriptor](transactions.md#out)*, an N-of-N multi-signature among stakeholders. After receiving a deposit, the stakeholders exchange signatures for a set of 4 transactions which are _not broadcast_. These "pre-signed" transactions are used by stakeholders to control the flow of funds and enable the delegation and emergency deterrent features of Revault. As seen in the diagram, they include; Emergency, Unvault, Cancel and Unvault Emergency TXs. -During the set-up, stakeholders prepare an *emergency output descriptor* which is a bitcoin script that is harder to unlock than *deposit output descriptor*. Keeping the *emergency output descriptor* private among stakeholders strengthens the emergency deterrent feature as attackers don't know how the emergency wallet is protected before it is spent from. +During the set-up, stakeholders prepare an *[emergency output descriptor](transactions.md#emergency_txs)* which is a Bitcoin script template that is harder to unlock than *deposit output descriptor*. Keeping the *emergency output descriptor* private among stakeholders strengthens the emergency deterrent feature as attackers don't know how the emergency wallet is protected before it is spent from. The stakeholders exchange signatures for the Cancel, Emergency and Unvault Emergency TXs: -- The Cancel TX would spend the Unvault TX to pay back to the *[deposit output descriptor](transactions.md#out)*. -- The Emergency TX would spend a deposit and pay to the *[emergency output descriptor](transactions.md#emergency_txs)*. -- The Unvault Emergency TX would spend the Unvault TX to pay to the *[emergency output descriptor](transactions.md#emergency_txs)*. +- The Cancel TX would spend the Unvault TX to pay back to the *deposit output descriptor*. +- The Emergency TX would spend a deposit and pay to the *emergency output descriptor*. +- The Unvault Emergency TX would spend the Unvault TX to pay to the *emergency output descriptor*. -This way, funds are protected _before_ delegation to fund managers. Eventually, the Unvault TX may be signed (to restrictively delegate the UTXO to managers). It spends from the *[deposit output descriptor](transactions.md#out)* and pays to the *[unvault output descriptor](transactions.md#out-1)*, and is accessible with either: +This way, funds are protected _before_ delegation to fund managers. Eventually, the Unvault TX may be signed (to restrictively delegate the UTXO to managers). It spends from the *deposit output descriptor* and pays to the *[unvault output descriptor](transactions.md#out-1)*, and is accessible with either: -- the managers' K-of-M multi-signature + time-lock of X blocks + J cosigning servers (where J = 0 if deploying without co-signers or N of deploying with co-signers), or +- the managers' K-of-M multi-signature + time-lock of X blocks + J cosigning servers (where J = 0 if deploying without co-signers or J = N if deploying with co-signers), or - the stakeholders' N-of-N multi-signature (with no delay). -Managers broadcast the relevant Unvault TX, and can attempt to use the Spend TX to pay external wallets, but are forced to wait for the Unvault time-lock to expire before their transaction finalizes. During that delay period, a Cancel or Unvault Emergency TX can be broadcasted which will revoke the spend attempt. +Managers broadcast the relevant Unvault TX and are forced to wait for the unvault time-lock to expire before they can broadcast a Spend TX which pays to external wallets. During that delay period, a Cancel or Unvault Emergency TX can be broadcasted which will revoke the spend attempt. Please check the complete specification of [transactions](transactions.md) for more details. @@ -59,13 +59,13 @@ First, there are base requirements common to all Revault deployments. Each stake - **Signing Device**: a hardware module used to store private keys and wallet descriptors and to handle signing operations. Given information of the UTXO locked to the *[deposit output descriptor](transactions.md#out)*, this device can construct the set of Revault TXs itself based on its configuration data. This alleviates the need for human-verification of the TXs when signing. -- **Coordinator server**: An always-online server used for efficient message routing among participants and other servers. Its primary use is for exchanging signatures of pre-signed transactions and Spend TXs. +- **Coordinator server**: An always-online untrusted server used for efficient message routing among participants and other servers. Its primary use is for exchanging signatures of pre-signed transactions and Spend TXs. With these in place, stakeholders are able to delegate bitcoin to fund managers and manually broadcast Cancel, Emergency and Unvault-Emergency TXs. Fund managers will also be able to manually broadcast Cancel TXs to recover from mistakes. Next, users who want additional features will require additional infrastructure components. Each stakeholder may control one or more watchtowers and/ or a co-signing server. -- **Watchtower**: An always-online server that monitors the Bitcoin network and chain, and depending on its responsibilities (which could include; automated unvault policy enforcement, automated spend policy enforcement, emergency deterrent) it will respond to relevant events. +- **Watchtower**: An always-online server that monitors the Bitcoin network and chain, and depending on its responsibilities (which could include: automated unvault policy enforcement, automated spend policy enforcement, emergency deterrent) it will respond to relevant events. - **Co-signing Server**: An always-online server that acts as a 'stupidly simple' anti-replay signing oracle: it will accept to sign any Spend TX (consuming an Unvault UTXO), *but only once*. This is necessary to stop the managers from changing the Spend TX after the Unvault TX is broadcast. @@ -113,7 +113,7 @@ In addition, if the network becomes highly congested, high feerates would trigge ### Key-tree Risk -The usage of a BIP32 unhardened derivation introduce even more reliance on the signing devices' security. Since the chaincodes are exchanged and stored on the wallets (running on untrusted online devices) of each participant, leaking a single child private key would be fatal to a participant's entire key-tree. Therefore the leak of a single child private key of all N stakeholders would be equivalent to the loss of all the funds. Using unhardened derivation implies that there is no partial loss of funds in case of a key leak by every stakeholder. +The use of BIP32 unhardened derivation introduces even more reliance on the signing devices' security. Since the chaincodes are exchanged and stored on the wallets (running on untrusted online devices) of each participant, leaking a single child private key would be fatal to a participant's entire key-tree. Therefore the leak of a single child private key of all N stakeholders would be equivalent to the loss of all the funds. Using unhardened derivation implies that there is no partial loss of funds in case of a key leak by every stakeholder. ### Transaction Fee Risk @@ -122,6 +122,6 @@ A fundamental issue arises with pre-signed transactions commiting to the feerate [Pinning attacks](https://bitcoinops.org/en/topics/transaction-pinning/) are possible when using either RBF or CPFP to dynamically allocate fees to transactions. These attacks exploit vulnerabilities that can cause transactions to become "stuck" in the mempool for long times. For protocols like Revault which require timely transaction confirmation, these attacks can be used to defeat theft-mitigation features (e.g. pinning a Cancel TX for longer than the Unvault TX's time-lock, and stealing funds). -The Unvault TXs have an additional output that allows dynamically allocating fees through child-pays-for-parent (CPFP). This feature helps managers optimise withdrawal times. The possibility of pinning Unvault TXs doesn't impact the theft-mitigation features of Revault but can be used as a denial-of-service attack by comrpomised managers. This is acceptable since managers already have multiple ways to launch denial-of-service attacks. For the Cancel, Emergency and Unvault Emergency TXs it is critical to avoid transaction pinning attacks. Unfortunately, these transactions aren't compatible with Bitcoin's [CPFP carve-out](https://github.com/bitcoin/bitcoin/pull/15681) rule which is used to mitigate pinning attacks in Lightning. +The Unvault TXs have an additional output that allows dynamically allocating fees through child-pays-for-parent (CPFP). This feature helps managers optimise withdrawal times. The possibility of pinning Unvault TXs doesn't impact the theft-mitigation features of Revault but can be used as a denial-of-service attack by comrpomised managers. This is acceptable since managers already have multiple ways to launch denial-of-service attacks. For the Cancel, Emergency and Unvault Emergency TXs it is critical to avoid transaction pinning attacks. Unfortunately, we are not aware of a method to dynamically allocate fees to these transactions without the risk of pinning attacks (at least, without any soft-forks to Bitcoin). A more detailed discussion can be found [here](https://lists.linuxfoundation.org/pipermail/bitcoin-dev/2021-November/019614.html). Emergency and Unvault Emergency TXs are simply pre-signed with exorbitant fees as they are intended as a deterrent, and not a regular expense. Since Cancel TXs may (or may not) occur frequently, it is important to minimise their feerates while still ensuring timely confirmation. The best solution currently is to prepare multiple variants of the same Cancel TX with a broad distribution of feerates, from typical to extreme and with many in-between. At the time of broadcast, the one with the appropriate fee should be selected. \ No newline at end of file