├── LICENSE ├── README.md ├── img └── tx_diagram.jpg ├── introduction.md ├── messages.md ├── transactions.md └── transport.md /LICENSE: -------------------------------------------------------------------------------- 1 | Attribution 4.0 International 2 | 3 | ======================================================================= 4 | 5 | Creative Commons Corporation ("Creative Commons") is not a law firm and 6 | does not provide legal services or legal advice. Distribution of 7 | Creative Commons public licenses does not create a lawyer-client or 8 | other relationship. Creative Commons makes its licenses and related 9 | information available on an "as-is" basis. Creative Commons gives no 10 | warranties regarding its licenses, any material licensed under their 11 | terms and conditions, or any related information. Creative Commons 12 | disclaims all liability for damages resulting from their use to the 13 | fullest extent possible. 14 | 15 | Using Creative Commons Public Licenses 16 | 17 | Creative Commons public licenses provide a standard set of terms and 18 | conditions that creators and other rights holders may use to share 19 | original works of authorship and other material subject to copyright 20 | and certain other rights specified in the public license below. The 21 | following considerations are for informational purposes only, are not 22 | exhaustive, and do not form part of our licenses. 23 | 24 | Considerations for licensors: Our public licenses are 25 | intended for use by those authorized to give the public 26 | permission to use material in ways otherwise restricted by 27 | copyright and certain other rights. Our licenses are 28 | irrevocable. Licensors should read and understand the terms 29 | and conditions of the license they choose before applying it. 30 | Licensors should also secure all rights necessary before 31 | applying our licenses so that the public can reuse the 32 | material as expected. Licensors should clearly mark any 33 | material not subject to the license. This includes other CC- 34 | licensed material, or material used under an exception or 35 | limitation to copyright. More considerations for licensors: 36 | wiki.creativecommons.org/Considerations_for_licensors 37 | 38 | Considerations for the public: By using one of our public 39 | licenses, a licensor grants the public permission to use the 40 | licensed material under specified terms and conditions. If 41 | the licensor's permission is not necessary for any reason--for 42 | example, because of any applicable exception or limitation to 43 | copyright--then that use is not regulated by the license. Our 44 | licenses grant only permissions under copyright and certain 45 | other rights that a licensor has authority to grant. Use of 46 | the licensed material may still be restricted for other 47 | reasons, including because others have copyright or other 48 | rights in the material. A licensor may make special requests, 49 | such as asking that all changes be marked or described. 50 | Although not required by our licenses, you are encouraged to 51 | respect those requests where reasonable. More considerations 52 | for the public: 53 | wiki.creativecommons.org/Considerations_for_licensees 54 | 55 | ======================================================================= 56 | 57 | Creative Commons Attribution 4.0 International Public License 58 | 59 | By exercising the Licensed Rights (defined below), You accept and agree 60 | to be bound by the terms and conditions of this Creative Commons 61 | Attribution 4.0 International Public License ("Public License"). To the 62 | extent this Public License may be interpreted as a contract, You are 63 | granted the Licensed Rights in consideration of Your acceptance of 64 | these terms and conditions, and the Licensor grants You such rights in 65 | consideration of benefits the Licensor receives from making the 66 | Licensed Material available under these terms and conditions. 67 | 68 | 69 | Section 1 -- Definitions. 70 | 71 | a. Adapted Material means material subject to Copyright and Similar 72 | Rights that is derived from or based upon the Licensed Material 73 | and in which the Licensed Material is translated, altered, 74 | arranged, transformed, or otherwise modified in a manner requiring 75 | permission under the Copyright and Similar Rights held by the 76 | Licensor. For purposes of this Public License, where the Licensed 77 | Material is a musical work, performance, or sound recording, 78 | Adapted Material is always produced where the Licensed Material is 79 | synched in timed relation with a moving image. 80 | 81 | b. Adapter's License means the license You apply to Your Copyright 82 | and Similar Rights in Your contributions to Adapted Material in 83 | accordance with the terms and conditions of this Public License. 84 | 85 | c. Copyright and Similar Rights means copyright and/or similar rights 86 | closely related to copyright including, without limitation, 87 | performance, broadcast, sound recording, and Sui Generis Database 88 | Rights, without regard to how the rights are labeled or 89 | categorized. For purposes of this Public License, the rights 90 | specified in Section 2(b)(1)-(2) are not Copyright and Similar 91 | Rights. 92 | 93 | d. Effective Technological Measures means those measures that, in the 94 | absence of proper authority, may not be circumvented under laws 95 | fulfilling obligations under Article 11 of the WIPO Copyright 96 | Treaty adopted on December 20, 1996, and/or similar international 97 | agreements. 98 | 99 | e. Exceptions and Limitations means fair use, fair dealing, and/or 100 | any other exception or limitation to Copyright and Similar Rights 101 | that applies to Your use of the Licensed Material. 102 | 103 | f. Licensed Material means the artistic or literary work, database, 104 | or other material to which the Licensor applied this Public 105 | License. 106 | 107 | g. Licensed Rights means the rights granted to You subject to the 108 | terms and conditions of this Public License, which are limited to 109 | all Copyright and Similar Rights that apply to Your use of the 110 | Licensed Material and that the Licensor has authority to license. 111 | 112 | h. Licensor means the individual(s) or entity(ies) granting rights 113 | under this Public License. 114 | 115 | i. Share means to provide material to the public by any means or 116 | process that requires permission under the Licensed Rights, such 117 | as reproduction, public display, public performance, distribution, 118 | dissemination, communication, or importation, and to make material 119 | available to the public including in ways that members of the 120 | public may access the material from a place and at a time 121 | individually chosen by them. 122 | 123 | j. Sui Generis Database Rights means rights other than copyright 124 | resulting from Directive 96/9/EC of the European Parliament and of 125 | the Council of 11 March 1996 on the legal protection of databases, 126 | as amended and/or succeeded, as well as other essentially 127 | equivalent rights anywhere in the world. 128 | 129 | k. You means the individual or entity exercising the Licensed Rights 130 | under this Public License. Your has a corresponding meaning. 131 | 132 | 133 | Section 2 -- Scope. 134 | 135 | a. License grant. 136 | 137 | 1. Subject to the terms and conditions of this Public License, 138 | the Licensor hereby grants You a worldwide, royalty-free, 139 | non-sublicensable, non-exclusive, irrevocable license to 140 | exercise the Licensed Rights in the Licensed Material to: 141 | 142 | a. reproduce and Share the Licensed Material, in whole or 143 | in part; and 144 | 145 | b. produce, reproduce, and Share Adapted Material. 146 | 147 | 2. Exceptions and Limitations. For the avoidance of doubt, where 148 | Exceptions and Limitations apply to Your use, this Public 149 | License does not apply, and You do not need to comply with 150 | its terms and conditions. 151 | 152 | 3. Term. The term of this Public License is specified in Section 153 | 6(a). 154 | 155 | 4. Media and formats; technical modifications allowed. The 156 | Licensor authorizes You to exercise the Licensed Rights in 157 | all media and formats whether now known or hereafter created, 158 | and to make technical modifications necessary to do so. The 159 | Licensor waives and/or agrees not to assert any right or 160 | authority to forbid You from making technical modifications 161 | necessary to exercise the Licensed Rights, including 162 | technical modifications necessary to circumvent Effective 163 | Technological Measures. For purposes of this Public License, 164 | simply making modifications authorized by this Section 2(a) 165 | (4) never produces Adapted Material. 166 | 167 | 5. Downstream recipients. 168 | 169 | a. Offer from the Licensor -- Licensed Material. Every 170 | recipient of the Licensed Material automatically 171 | receives an offer from the Licensor to exercise the 172 | Licensed Rights under the terms and conditions of this 173 | Public License. 174 | 175 | b. No downstream restrictions. You may not offer or impose 176 | any additional or different terms or conditions on, or 177 | apply any Effective Technological Measures to, the 178 | Licensed Material if doing so restricts exercise of the 179 | Licensed Rights by any recipient of the Licensed 180 | Material. 181 | 182 | 6. No endorsement. Nothing in this Public License constitutes or 183 | may be construed as permission to assert or imply that You 184 | are, or that Your use of the Licensed Material is, connected 185 | with, or sponsored, endorsed, or granted official status by, 186 | the Licensor or others designated to receive attribution as 187 | provided in Section 3(a)(1)(A)(i). 188 | 189 | b. Other rights. 190 | 191 | 1. Moral rights, such as the right of integrity, are not 192 | licensed under this Public License, nor are publicity, 193 | privacy, and/or other similar personality rights; however, to 194 | the extent possible, the Licensor waives and/or agrees not to 195 | assert any such rights held by the Licensor to the limited 196 | extent necessary to allow You to exercise the Licensed 197 | Rights, but not otherwise. 198 | 199 | 2. Patent and trademark rights are not licensed under this 200 | Public License. 201 | 202 | 3. To the extent possible, the Licensor waives any right to 203 | collect royalties from You for the exercise of the Licensed 204 | Rights, whether directly or through a collecting society 205 | under any voluntary or waivable statutory or compulsory 206 | licensing scheme. In all other cases the Licensor expressly 207 | reserves any right to collect such royalties. 208 | 209 | 210 | Section 3 -- License Conditions. 211 | 212 | Your exercise of the Licensed Rights is expressly made subject to the 213 | following conditions. 214 | 215 | a. Attribution. 216 | 217 | 1. If You Share the Licensed Material (including in modified 218 | form), You must: 219 | 220 | a. retain the following if it is supplied by the Licensor 221 | with the Licensed Material: 222 | 223 | i. identification of the creator(s) of the Licensed 224 | Material and any others designated to receive 225 | attribution, in any reasonable manner requested by 226 | the Licensor (including by pseudonym if 227 | designated); 228 | 229 | ii. a copyright notice; 230 | 231 | iii. a notice that refers to this Public License; 232 | 233 | iv. a notice that refers to the disclaimer of 234 | warranties; 235 | 236 | v. a URI or hyperlink to the Licensed Material to the 237 | extent reasonably practicable; 238 | 239 | b. indicate if You modified the Licensed Material and 240 | retain an indication of any previous modifications; and 241 | 242 | c. indicate the Licensed Material is licensed under this 243 | Public License, and include the text of, or the URI or 244 | hyperlink to, this Public License. 245 | 246 | 2. You may satisfy the conditions in Section 3(a)(1) in any 247 | reasonable manner based on the medium, means, and context in 248 | which You Share the Licensed Material. For example, it may be 249 | reasonable to satisfy the conditions by providing a URI or 250 | hyperlink to a resource that includes the required 251 | information. 252 | 253 | 3. If requested by the Licensor, You must remove any of the 254 | information required by Section 3(a)(1)(A) to the extent 255 | reasonably practicable. 256 | 257 | 4. If You Share Adapted Material You produce, the Adapter's 258 | License You apply must not prevent recipients of the Adapted 259 | Material from complying with this Public License. 260 | 261 | 262 | Section 4 -- Sui Generis Database Rights. 263 | 264 | Where the Licensed Rights include Sui Generis Database Rights that 265 | apply to Your use of the Licensed Material: 266 | 267 | a. for the avoidance of doubt, Section 2(a)(1) grants You the right 268 | to extract, reuse, reproduce, and Share all or a substantial 269 | portion of the contents of the database; 270 | 271 | b. if You include all or a substantial portion of the database 272 | contents in a database in which You have Sui Generis Database 273 | Rights, then the database in which You have Sui Generis Database 274 | Rights (but not its individual contents) is Adapted Material; and 275 | 276 | c. You must comply with the conditions in Section 3(a) if You Share 277 | all or a substantial portion of the contents of the database. 278 | 279 | For the avoidance of doubt, this Section 4 supplements and does not 280 | replace Your obligations under this Public License where the Licensed 281 | Rights include other Copyright and Similar Rights. 282 | 283 | 284 | Section 5 -- Disclaimer of Warranties and Limitation of Liability. 285 | 286 | a. UNLESS OTHERWISE SEPARATELY UNDERTAKEN BY THE LICENSOR, TO THE 287 | EXTENT POSSIBLE, THE LICENSOR OFFERS THE LICENSED MATERIAL AS-IS 288 | AND AS-AVAILABLE, AND MAKES NO REPRESENTATIONS OR WARRANTIES OF 289 | ANY KIND CONCERNING THE LICENSED MATERIAL, WHETHER EXPRESS, 290 | IMPLIED, STATUTORY, OR OTHER. THIS INCLUDES, WITHOUT LIMITATION, 291 | WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR 292 | PURPOSE, NON-INFRINGEMENT, ABSENCE OF LATENT OR OTHER DEFECTS, 293 | ACCURACY, OR THE PRESENCE OR ABSENCE OF ERRORS, WHETHER OR NOT 294 | KNOWN OR DISCOVERABLE. WHERE DISCLAIMERS OF WARRANTIES ARE NOT 295 | ALLOWED IN FULL OR IN PART, THIS DISCLAIMER MAY NOT APPLY TO YOU. 296 | 297 | b. TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE 298 | TO YOU ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION, 299 | NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT, 300 | INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES, 301 | COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS PUBLIC LICENSE OR 302 | USE OF THE LICENSED MATERIAL, EVEN IF THE LICENSOR HAS BEEN 303 | ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR 304 | DAMAGES. WHERE A LIMITATION OF LIABILITY IS NOT ALLOWED IN FULL OR 305 | IN PART, THIS LIMITATION MAY NOT APPLY TO YOU. 306 | 307 | c. The disclaimer of warranties and limitation of liability provided 308 | above shall be interpreted in a manner that, to the extent 309 | possible, most closely approximates an absolute disclaimer and 310 | waiver of all liability. 311 | 312 | 313 | Section 6 -- Term and Termination. 314 | 315 | a. This Public License applies for the term of the Copyright and 316 | Similar Rights licensed here. However, if You fail to comply with 317 | this Public License, then Your rights under this Public License 318 | terminate automatically. 319 | 320 | b. Where Your right to use the Licensed Material has terminated under 321 | Section 6(a), it reinstates: 322 | 323 | 1. automatically as of the date the violation is cured, provided 324 | it is cured within 30 days of Your discovery of the 325 | violation; or 326 | 327 | 2. upon express reinstatement by the Licensor. 328 | 329 | For the avoidance of doubt, this Section 6(b) does not affect any 330 | right the Licensor may have to seek remedies for Your violations 331 | of this Public License. 332 | 333 | c. For the avoidance of doubt, the Licensor may also offer the 334 | Licensed Material under separate terms or conditions or stop 335 | distributing the Licensed Material at any time; however, doing so 336 | will not terminate this Public License. 337 | 338 | d. Sections 1, 5, 6, 7, and 8 survive termination of this Public 339 | License. 340 | 341 | 342 | Section 7 -- Other Terms and Conditions. 343 | 344 | a. The Licensor shall not be bound by any additional or different 345 | terms or conditions communicated by You unless expressly agreed. 346 | 347 | b. Any arrangements, understandings, or agreements regarding the 348 | Licensed Material not stated herein are separate from and 349 | independent of the terms and conditions of this Public License. 350 | 351 | 352 | Section 8 -- Interpretation. 353 | 354 | a. For the avoidance of doubt, this Public License does not, and 355 | shall not be interpreted to, reduce, limit, restrict, or impose 356 | conditions on any use of the Licensed Material that could lawfully 357 | be made without permission under this Public License. 358 | 359 | b. To the extent possible, if any provision of this Public License is 360 | deemed unenforceable, it shall be automatically reformed to the 361 | minimum extent necessary to make it enforceable. If the provision 362 | cannot be reformed, it shall be severed from this Public License 363 | without affecting the enforceability of the remaining terms and 364 | conditions. 365 | 366 | c. No term or condition of this Public License will be waived and no 367 | failure to comply consented to unless expressly agreed to by the 368 | Licensor. 369 | 370 | d. Nothing in this Public License constitutes or may be interpreted 371 | as a limitation upon, or waiver of, any privileges and immunities 372 | that apply to the Licensor or You, including from the legal 373 | processes of any jurisdiction or authority. 374 | 375 | 376 | ======================================================================= 377 | 378 | Creative Commons is not a party to its public licenses. 379 | Notwithstanding, Creative Commons may elect to apply one of its public 380 | licenses to material it publishes and in those instances will be 381 | considered the “Licensor.” The text of the Creative Commons public 382 | licenses is dedicated to the public domain under the CC0 Public Domain 383 | Dedication. Except for the limited purpose of indicating that material 384 | is shared under a Creative Commons public license or as otherwise 385 | permitted by the Creative Commons policies published at 386 | creativecommons.org/policies, Creative Commons does not authorize the 387 | use of the trademark "Creative Commons" or any other trademark or logo 388 | of Creative Commons without its prior written consent including, 389 | without limitation, in connection with any unauthorized modifications 390 | to any of its public licenses or any other arrangements, 391 | understandings, or agreements concerning use of licensed material. For 392 | the avoidance of doubt, this paragraph does not form part of the public 393 | licenses. 394 | 395 | Creative Commons may be contacted at creativecommons.org. 396 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Practical Revault 2 | 3 | The v0 specification for the initialization and operation of the Revault custody 4 | protocol. 5 | 6 | See the [introduction](introduction.md) for a high-level description of Revault. 7 | 8 | Contributions in any form are very welcome. Discussions happen in issues or at 9 | [`#revault` on Libera](https://web.libera.chat/?channels=#revault). 10 | 11 | ## Table of contents 12 | 13 | - [Revault description](introduction.md) 14 | - [Messages](messages.md) 15 | - [Transaction](transactions.md) 16 | - [Transport](transport.md) 17 | 18 | ## License 19 | 20 | This work is licensed under a Creative Commons Attribution 4.0 International License. A 21 | complete version of the license can be found in [LICENSE](LICENSE) or [here](https://creativecommons.org/licenses/by/4.0/). 22 | -------------------------------------------------------------------------------- /img/tx_diagram.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/revault/practical-revault/7936d377e89cf0ce63e1462dbff10d2687c35c2b/img/tx_diagram.jpg -------------------------------------------------------------------------------- /introduction.md: -------------------------------------------------------------------------------- 1 | # Revault: A Multi-Party Bitcoin Vault Architecture 2 | 3 | The secure storage and transaction of funds is a big challenge to Bitcoin users and especially to companies managing a substantial amount of bitcoins. Traditional controls of expenses are hard to set-up with Bitcoin due to its features: censorship-resistance, eventual transaction finality, and pseudonymous addresses. 4 | 5 | Revault is a self-managed custody solution for multi-party holders (such as a company or their third party custodian) with strong theft mitigation from external parties and internal fund managers. Revault participants will have one or both roles as a *stakeholder* or *manager*. Revault has several novel features; 6 | 7 | - On-chain tiered access control, where *stakeholders* have primary control and an ability to safely delegate funds to *managers*. 8 | - Ability to cancel managers' withdrawals from a vault (automatically based on pre-configured policy, or manually) 9 | - Ability to restrict managers' spending behaviours based on arbitrary policies 10 | - Physical coercion mitigation using a trapdoor mechanism to move all funds to a preset *emergency descriptor* 11 | 12 | Revault can be tailor-fit to many organisational structures with custom multi-signature thresholds, time-lock periods, and feature sets. Users can set policies in-line with business logic. Users can start with a simple deployment and scale infrastructure as their security budget increases. 13 | 14 | Contents: 15 | 16 | 1. [Introduction to Revault](#introduction-to-revault) 17 | 2. [Process and Revault Transaction Types](#process-and-revault-transaction-types) 18 | 3. [Infrastructure and Feature Choice](#infrastructure-and-feature-choice) 19 | 4. [Threat Model](#threat-model) 20 | 21 | ## Introduction to Revault 22 | 23 | Revault is a custody solution with tiered access control. The bitcoins are co-owned by N stakeholders and are accessible with an N-of-N multi-signature. Portions of these bitcoins are delegated to M fund managers as-needed and are accessible with a K-of-M multi-signature but are subject to a set of _restrictive policies_. In practice, this delegation only allows the managers to follow pre-approved unvaulting and spending policies, thus retaining control at the stakeholder level. 24 | 25 | The single-tiered multi-signature approach common today is subject to a trade-off between security (large number of signatures required) and usability (low number of parties required). By comparison, Revault achieves practical usability through safe delegation to managers who handle the spending process without sacrificing on the security of a large multi-signature. 26 | 27 | In addition, Revault comes with an (optional) deterrent feature for emergency scenarios. Before deploying Revault, stakeholders set-up an _emergency descriptor_. At any time stakeholders can trigger their panic button and unilaterally transfer all bitcoin in custody to the emergency descriptor. For example if 2 of the 3 stakeholders are abducted or physically threatened, the remaining stakeholder can save funds from theft. This feature drastically reduces the likelihood that a coordinated attack on the stakeholders will be profitable and thus acts as a credible deterrent from physical coercion. 28 | 29 | ## Process and Revault Transaction Types 30 | 31 | ![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.](img/tx_diagram.jpg) 32 | 33 | 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. 34 | 35 | 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. 36 | 37 | The stakeholders exchange signatures for the Cancel, Emergency and Unvault Emergency TXs: 38 | 39 | - The Cancel TX would spend the Unvault TX to pay back to the *deposit output descriptor*. 40 | - The Emergency TX would spend a deposit and pay to the *emergency output descriptor*. 41 | - The Unvault Emergency TX would spend the Unvault TX to pay to the *emergency output descriptor*. 42 | 43 | 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: 44 | 45 | - 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 46 | - the stakeholders' N-of-N multi-signature (with no delay). 47 | 48 | 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. 49 | 50 | Please check the complete specification of [transactions](transactions.md) for more details. 51 | 52 | ## Infrastructure and Feature Choice 53 | 54 | Users can choose features to suit their needs. Different features require different infrastructure to operate. 55 | 56 | First, there are base requirements common to all Revault deployments. Each stakeholder and manager controls a wallet and a signing device. An untrusted Coordinator server is used to route messages and thus enable wallets to update and synchronise their state. 57 | 58 | - **Revault Wallet**: an open-source software running with a bitcoind back-end used to keep track of the users' co-owned coins, transaction signatures, transaction history and to connect with a signing device and infrastructure servers. 59 | 60 | - **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. 61 | 62 | - **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. 63 | 64 | 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. 65 | 66 | 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. 67 | 68 | - **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. 69 | 70 | - **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. 71 | 72 | Automatic unvault policy enforcement; requires a Watchtower. By default the Watchtower will broadcast a Cancel TX any time it detects an Unvault TX unless it adheres to a specific pre-configured unvault policy. 73 | 74 | Spend policy enforcement; requires a Watchtower and Co-signing Server. By default the Watchtower will broadcast a Cancel TX any time it detects the Spend TX's parent Unvault TX unless it is made aware of the Spend TX in advance and that Spend TX adheres to a pre-configured spend policy. The co-signing server is a means to stop the managers from spending from the Unvault TX with a malicious TX which replaces the Spend TX after it was announced to the watchtowers (which must therefore be done *before* broadcasting the Unvault TX). 75 | 76 | Automatic Emergency Deterrent: requires a *Watchtower* which monitors the Bitcoin network and maintains multiple direct communication channels with the stakeholder. The trigger can be a panic button or dead-man-switch (or otherwise). When triggered the Watchtower which will broadcast all of its Emergency TXs and/or Unvault Emergency TXs. To further reduce the incentive of a theft attempt the broadcast of any Emergency TX associated with any vault triggers the broadcast of all Emergency TXs associated with all the remaining vaults. 77 | 78 | Please see [here](https://github.com/revault/practical-revault/blob/master/messages.md#processes) for a more detailed look at the processes in Revault. 79 | 80 | The flexibility brought by the active defense mechanism allows any unvault or spending policy to be set and enforced by watchtowers. This therefore largely extends the scope of the possibilities compared to on-chain enforcement and is more in-phase with typical business policies (enforcement of a 2FA, of business hours, etc..). 81 | 82 | 83 | ## Risk 84 | 85 | While Revault has been designed to fix (some of) the threats on existing custody protocols, it introduces new challenges and different assumptions. Revault aims to prevent theft with up to N-1 stakeholders' signing devices being compromised. Here we highlight different attack scenarios, trying to identify weaknesses in the design and finish with a set of security assumptions introduced when using Revault. For more detailed research, check the [Operational Risk Framework](https://github.com/revault/research/blob/master/risk_analysis/paper.pdf). 86 | 87 | ### Emergency Deterrent Risk 88 | 89 | While the Emergency TX is the strongest mitigation in the Revault architecture, it introduces a potential risk of blackmail or losses derived from lack of business continuity (e.g. a block-and-short attack). An attacker (internal or external) getting hold of a single Emergency TX can threaten to push it to the Bitcoin network, triggering a push of all Emergency TXs by the watchtowers. The funds are not at risk in this scenario but getting the funds back online would be long and difficult. On the other hand, an important part of the security model (the deterrent) is enforced by the pre-signed Emergency TXs being accessible. 90 | 91 | ### Delegation Risk - Unvault Policies 92 | 93 | An "active defence" mechanism is used to restrict the behaviour of fund managers. Contrary to commonly deployed multi-signature wallets, it takes managers two transactions to spend funds. The first step encodes an on-chain time-lock. During this time, only a single honest watchtower is required to cancel given a breach of the unvault policy. It is expected and encouraged to deploy many watchtowers (at least one per stakeholder). 94 | 95 | ### Delegation Risk - Spend Policies 96 | 97 | To by-pass the spend policy enforcement, an attacker would need to compromise all co-signing servers *or* to compromise all watchtowers. Note that due to the former, there are more attack vectors here compared with unvault policies and so spend policy enforcement is relatively weaker. In the former case, an attacker could alter the Spend TX after the Unvault time-lock expires. In the latter case, a malicious Spend TX would not trigger the broadcast of a Cancel TX. 98 | 99 | 100 | ### Denial-of-service Risk 101 | 102 | As a consequence of the N-1 resilience model, there are multiple attacks against the practical usage of the funds: 103 | 104 | - signing refusal by a stakeholder 105 | - unjustified Cancel TX push 106 | - unjustified Emergency TX push 107 | - taking down a co-signing server 108 | - taking down (all) the coordinator(s) 109 | - pinning Unvault TXs 110 | 111 | In addition, if the network becomes highly congested, high feerates would trigger most Bitcoin network nodes' to increase their mempool's minimum accepted feerate (those who didn't manually increase the mempool limits). Unvault TXs that are prepared with an initial 24 sat/vb feerate could fail to be relayed if the minimum accepted feerate increases sufficiently. Managers would not be able to use funds delegated to them until the backlog of transactions is processed by the Bitcoin network (mined). 112 | 113 | 114 | ### Key-tree Risk 115 | 116 | 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. 117 | 118 | 119 | ### Transaction Fee Risk 120 | 121 | A fundamental issue arises with pre-signed transactions commiting to the feerate well in advance of the time of broadcast. The required feerate is unpredictable and a transaction with a low feerate may not be included in a block in time. 122 | 123 | [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). 124 | 125 | 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). 126 | 127 | Emergency and Unvault Emergency TXs are simply pre-signed with exorbitant fees as they are intended as a deterrent, and not a regular expense. 128 | -------------------------------------------------------------------------------- /messages.md: -------------------------------------------------------------------------------- 1 | # Messages 2 | 3 | A description of how information is exchanged between the different entities, as well as the 4 | flow of operations. 5 | 6 | These messages are exchanged on top of an [encrypted and authenticated communication 7 | channel](network.md). 8 | 9 | JSON is used (pretty similarly to JSONRPC2) in order to prime debuggability over efficiency for 10 | the v0 specifications. 11 | Parsing should not be strict (ie unknown entries in a mapping should be disregarded) for forward 12 | compatibility. 13 | 14 | 15 | - [Watchtower](#watchtower) 16 | - [Cosigning server](#cosigning-server) 17 | - [Coordinator](#coordinator) 18 | 19 | ## Watchtower 20 | 21 | At least one watchtower is ran by every stakeholder, and at most one wallet is paired with 22 | each watchtower. A watchtower needs to be able to see all fully-signed revocation transaction 23 | before its corresponding wallet signs the unvaulting transaction. 24 | 25 | In addition, a watchtower will by default revault any unvaulting attempt. We need a way 26 | for the watchtowers to poll the spending transaction (as its revaulting policy may depend 27 | on it). For this matter we use the coordinator as a proxy between the managers 28 | and the watchtowers. 29 | When noticing an unvaulting attempt, the watchtower will poll the coordinator 30 | for a potential spend transaction. If there is one and it is valid according to its 31 | revaulting policy, it will not do anything. Otherwise it will broadcast the cancel 32 | transaction. 33 | 34 | 35 | ### Rough flow 36 | 37 | ``` 38 | STAKEHOLDER's WALLET WATCHTOWER 39 | || -- sigs --------------> || // Here are all sigs for the emergency transaction. 40 | || <-------- sigs_ack ----- || // I succesfully re-constructed, checked, and stored this transaction. 41 | ``` 42 | 43 | ### Messages format 44 | 45 | #### `sigs` 46 | 47 | Sent at any point in time by a stakeholder's wallet to share the revocation transactions' signature 48 | with (one of) its watchtower(s). 49 | 50 | It must wait for a positive response from the watchtower before sharing the Unvault transaction 51 | signature. 52 | 53 | #### Request 54 | 55 | ```json 56 | { 57 | "method": "sigs", 58 | "params": { 59 | "signatures": { 60 | "emergency": { 61 | "pubkeyA": "ALL|ANYONECANPAY Bitcoin ECDSA signature as hex", 62 | "pubkeyB": "ALL|ANYONECANPAY Bitcoin ECDSA signature as hex", 63 | }, 64 | "cancel": { 65 | "pubkeyA": "ALL|ANYONECANPAY Bitcoin ECDSA signature as hex", 66 | "pubkeyB": "ALL|ANYONECANPAY Bitcoin ECDSA signature as hex", 67 | } 68 | "unvault_emergency": { 69 | "pubkeyA": "ALL|ANYONECANPAY Bitcoin ECDSA signature as hex", 70 | "pubkeyB": "ALL|ANYONECANPAY Bitcoin ECDSA signature as hex", 71 | } 72 | }, 73 | "deposit_outpoint": "deposit utxo outpoint", 74 | "derivation_index": 42 75 | } 76 | } 77 | ``` 78 | 79 | #### Response 80 | 81 | The watchtower must not send an ACK if it did not successfully checked and stored all transactions' 82 | signatures, *or if it is unable to bump its feerate with its currently-available utxos*. 83 | 84 | ```json 85 | { 86 | "result": { 87 | "ack": true, 88 | } 89 | } 90 | ``` 91 | 92 | 93 | ------ 94 | 95 | 96 | ## Cosigning server 97 | 98 | A cosigning server is ran by each stakeholder. It is happy to sign any transaction input 99 | it can, but only once. 100 | 101 | ### Rough flow 102 | 103 | ``` 104 | WALLET COSIG_SERVER 105 | || -A-- sign --------> || // A: I need you to sign this transaction input 106 | || <-- sign result ---- || // Server: *signs* .. Here you go. 107 | || 108 | || -B-- sign --------> || // B: I need you to sign this same transaction input 109 | || <-- sign result ---- || // Server: I already signed an input spending this outpoint, here is the existing signature 110 | ``` 111 | 112 | ### Messages format 113 | 114 | #### `sign` 115 | 116 | Sent at any point in time by a manager who'll soon attempt to unvault and spend one or 117 | more vault(s). 118 | 119 | As the spend transaction must only spend unvault transaction outputs, the cosigning server 120 | shall sign all inputs (if all of them were not already signed). 121 | 122 | 123 | #### Request 124 | 125 | ```json 126 | { 127 | "method": "sign", 128 | "params": { 129 | "tx": "psbt" 130 | } 131 | } 132 | ``` 133 | 134 | #### Response 135 | 136 | The server must: 137 | - if no prevout was already signed 138 | - return the PSBT with its (newly generated) signature appended to each input 139 | - if all prevouts were already signed 140 | - return the PSBT with its (previously generated) signature appended to each input 141 | - else 142 | - return `null` 143 | 144 | ```json 145 | { 146 | "result": { 147 | "tx": "psbt" 148 | } 149 | } 150 | ``` 151 | Or 152 | ```json 153 | { 154 | "result": { 155 | "tx": null 156 | } 157 | } 158 | ``` 159 | 160 | 161 | ------ 162 | 163 | 164 | ## Coordinator 165 | 166 | The coordinator is a proxy for watchtowers to retrieve spend transactions, and conveniently 167 | permits to share pre-signed transaction signatures without interaction between participants. 168 | 169 | As each wallet will verify and store signatures locally, the server isn't trusted and can be 170 | managed by the organisation deploying Revault itself or any third party without risking any 171 | loss of funds. 172 | 173 | The server will also broadcast the spend transactions when the unvault timelock is expired; this 174 | way managers could shut down their wallets after broadcasting the unvault without further delaying 175 | the spend broadcast. 176 | 177 | Acting as a cache in place of -example given- a p2p network, the information stored on the 178 | coordinator is transient. 179 | 180 | 181 | ### Rough flow 182 | 183 | ``` 184 | STAKEHOLDER's WALLET COORDINATOR 185 | || -A-- sig --------> || // A: Here is a sig for this txid ! 186 | || -C-- sig --------> || 187 | || -B-- sig --------> || 188 | || 189 | || -C-- get_sigs ----> || // C: I gave my sig but now am waiting for everyone to complete.. 190 | ...(polling) 191 | || -A-- get_sigs ----> || 192 | ...(polling) 193 | || -B-- get_sigs ----> || 194 | ...(polling) 195 | ...(polling) // Eventually they all retrieve the sigs. 196 | ``` 197 | 198 | ``` 199 | 200 | MANAGER's WALLET COORDINATOR 201 | || -- set_spend_tx -------> || // I'm going to unvault these vaults, here is the 202 | fully signed spend transaction so watchtowers 203 | don't freak out. 204 | ``` 205 | 206 | ``` 207 | WATCHTOWER COORDINATOR 208 | || -- get_spend_tx -------> || // Is there any available spend tx for this vault ? 209 | || <--- spend_tx ---------- || // Here is what i know about. I may be lying but worst case you revault. 210 | ``` 211 | 212 | 213 | ### Messages format 214 | 215 | #### `sig` 216 | 217 | Sent by a stakeholder wallet at any point in time to share the signature for a transaction 218 | with all other stakeholders and all managers. 219 | Note that the managers are able to poll the Emergency transactions signatures from the 220 | coordinator. However, since they are not able to reconstruct the transactions (they don't 221 | know the `scriptPubKey`) they can't use them to DOS the operations by broadcasting them 222 | to the Bitcoin network. 223 | 224 | The wallet can safely post its signature for the `cancel` and `emergency`s of each 225 | `vault` without waiting for others. However, it must wait for everyone to have signed 226 | the `cancel` and `emergency` transactions and its watchtower to have verified and stored 227 | the signature before possibly sharing its signature for the unvault transaction. 228 | 229 | A wallet is not bound to share its signature for the unvault transaction. This flexibility 230 | allows "unactive vaults": a multisig which is not spendable by default but still guarded 231 | by the emergency transaction deterrent. 232 | A wallet must share its signature for the `cancel` and the unvault `emergency` 233 | transactions nonetheless. 234 | An inactive vault may later become active by sharing signatures for the `unvault` 235 | transaction. 236 | 237 | Revocation transactions (`cancel` and `emergency`s) are signed with the `ALL|ANYONECANPAY` 238 | flag. 239 | 240 | 241 | #### Request 242 | 243 | ```json 244 | { 245 | "method": "sig", 246 | "params": { 247 | "pubkey": "Secp256k1 public key used to sign the transaction (hex)", 248 | "signature": "Bitcoin ECDSA signature (without sighash type byte) as hex", 249 | "txid": "transaction txid" 250 | } 251 | } 252 | ``` 253 | 254 | #### Response 255 | 256 | The Coordinator must only set `ack` to `true` if it claims to have successfully stored the signature. 257 | 258 | ```json 259 | { 260 | "result": { 261 | "ack": true 262 | } 263 | } 264 | ``` 265 | 266 | 267 | #### `get_sigs` 268 | 269 | Sent by a wallet to retrieve all signatures for a specific transaction. 270 | 271 | 272 | #### Request 273 | 274 | ```json 275 | { 276 | "method": "get_sigs", 277 | "params": { 278 | "txid": "transaction txid" 279 | } 280 | } 281 | ``` 282 | 283 | #### Response 284 | 285 | ```json 286 | { 287 | "result": { 288 | "signatures": { 289 | "pubkeyA": "Bitcoin ECDSA signature", 290 | "pubkeyC": "Bitcoin ECDSA signature" 291 | } 292 | } 293 | } 294 | ``` 295 | 296 | Note the absence of `pubkeyB` in the above samples. 297 | 298 | 299 | #### `set_spend_tx` 300 | 301 | Sent by a manager to advertise the Spend transaction that will eventually be used for a 302 | set of Unvault. 303 | 304 | 305 | #### Request 306 | 307 | ```json 308 | { 309 | "method": "set_spend_tx", 310 | "params": { 311 | "deposit_outpoints": ["txid:vout", "txid:vout"], 312 | "spend_tx": "base64 of Bitcoin-serialized fully-signed spend transaction" 313 | } 314 | } 315 | ``` 316 | 317 | #### Response 318 | 319 | The Coordinator must only set `ack` to `true` if it claims to have successfully stored the Spend 320 | transaction. 321 | 322 | ```json 323 | { 324 | "result": { 325 | "ack": true 326 | } 327 | } 328 | ``` 329 | 330 | 331 | #### `get_spend_tx` 332 | 333 | Sent by a watchtower to the coordinator after an unvault event to learn 334 | about the spend transaction. 335 | The coordinator might not have the spend transaction, in which case it will 336 | return `null`. 337 | 338 | 339 | #### Request 340 | 341 | ```json 342 | { 343 | "method": "get_spend_tx", 344 | "params": { 345 | "deposit_outpoint": "txid:vout" 346 | } 347 | } 348 | ``` 349 | 350 | #### Response 351 | 352 | ```json 353 | { 354 | "result": { 355 | "spend_tx": "base64 of Bitcoin-serialized spend tx" 356 | } 357 | } 358 | ``` 359 | or, if the coordinator doesn't have the spend: 360 | ```json 361 | { 362 | "result": { 363 | "spend_tx": null, 364 | } 365 | } 366 | ``` 367 | 368 | 369 | ## Processes 370 | 371 | ### Presigning process 372 | 373 | #### Revocation transactions signing step 374 | 375 | ``` 376 | stakeholder coordinator 377 | + + 378 | | +-sig emer---------> | 379 | | +-sig emer_unvault-> | 380 | | +-sig cancel-------> | 381 | | | 382 | | +--get_sigs--------> | 383 | | + 384 | | 385 | | watchtower 386 | | + 387 | | +--sig emer---------> | 388 | | <--------sig_ack----+ | 389 | | | 390 | | +--sig emer_unvault-> | 391 | | <--------sig_ack----+ | 392 | | | 393 | | +--sig cancel-------> | 394 | | <-------sig_ack-----+ | 395 | + + 396 | ``` 397 | 398 | | flow | request | 399 | | -------------------------- | --------------------- | 400 | | stakeholder -> coordinator | [sig](#sig-1) | 401 | | stakeholder -> coordinator | [get_sigs](#get_sigs) | 402 | | stakeholder -> watchtower | [sig](#sig) | 403 | | watchtower -> stakeholder | [sig_ack](#sig_ack) | 404 | 405 | #### Activation signing step 406 | 407 | ``` 408 | stakeholder coordinator 409 | + + 410 | | +-sig unvault-> | 411 | | | 412 | | +--get_sigs---> | 413 | + | 414 | | 415 | manager | 416 | + | 417 | | +---get_sigs--> | 418 | + + 419 | ``` 420 | 421 | | flow | request | 422 | | -------------------------- | --------------------- | 423 | | stakeholder -> coordinator | [sig](#sig-1) | 424 | | stakeholder -> coordinator | [get_sigs](#get_sigs) | 425 | 426 | ### Spending process 427 | 428 | ``` 429 | ... Gather sufficient managers signatures ... 430 | 431 | manager cosig_server 432 | | + 433 | | | 434 | | +----sign-----> | 435 | | <-sign result-+ | 436 | | + 437 | | 438 | | coordinator 439 | | + 440 | | | 441 | | +-set_spend_tx ---------> | 442 | | | 443 | + + 444 | 445 | ... Broadcast the unvault tx ... 446 | 447 | coordinator watchtower 448 | + + 449 | | | 450 | | <-- get_spend_tx ------ | 451 | | --------- spend_tx ---> | 452 | + + 453 | ``` 454 | 455 | | flow | request | 456 | | ------------------------- | ----------------------------------- | 457 | | manager -> cosig_server | [sign](#sign) | 458 | | manager -> coordinator | [set_spend_tx](#set_spend_tx) | 459 | | watchtower -> coordinator | [get_spend_tx](#get_spend_tx) | 460 | 461 | 462 | 463 | [revaulting_txs]: transactions.md#cancel_tx 464 | [unvault_tx]: transactions.md#unvault_tx 465 | -------------------------------------------------------------------------------- /transactions.md: -------------------------------------------------------------------------------- 1 | # Revault transactions 2 | 3 | All transactions are version 2 and use version 0 native Segwit scripts. 4 | 5 | We use [miniscript](http://bitcoin.sipa.be/miniscript/) and output descriptors to generally 6 | describe outputs spending policies. 7 | 8 | We denote `N` the number of stakeholders, `M` the number of fund managers (allowed 9 | to unlock the unvault transaction output along with the cosigning servers after a timeout), 10 | and `X` the CSV value in the unvault transaction. Each transaction type here signals 11 | replace-by-fee (RBF). 12 | 13 | While a larger number of participants is technically possible, we explicitly limit the number of 14 | stakeholders and managers to `20`. 15 | 16 | - [deposit_tx](#deposit_tx) 17 | - [unvault_tx](#unvault_tx) 18 | - [spend_tx](#spend_tx) 19 | - [cancel_tx](#cancel_tx) 20 | - [emergency_txs](#emergency_txs) 21 | - [deposit_emergency_tx](#deposit_emergency_tx) 22 | - [unvault_emergency_tx](#unvault_emergency_tx) 23 | - [bypass_tx](#bypass_tx) 24 | 25 | 26 | ## deposit_tx 27 | 28 | The transaction which deposits into the vault. 29 | 30 | #### IN 31 | 32 | N/A 33 | 34 | #### OUT 35 | 36 | At least one output paying to `deposit_descriptor`, with: 37 | ``` 38 | deposit_descriptor = wsh(deposit_witness_script) 39 | deposit_witness_script = thresh(N, pubkey1, pubkey2, ..., pubkeyN) 40 | ``` 41 | 42 | 43 | ## unvault_tx 44 | 45 | The transaction which spends the [`deposit_tx`](#deposit_tx) deposit output, and creates an 46 | unvault output spendable by the `N` stakeholders or the managers (along with the cosigning 47 | servers) after `X` blocks. 48 | 49 | The Unvault transaction is signed using a fixed `6 sat/WU` feerate. This is a 50 | completely arbitrary value that was chosen to avoid blocking operations too early 51 | in case of a huge load of transactions on the network and an increase of the 52 | network mempools minimum feerate. 53 | This transaction's fees can be bumped if not competitive (using the CPFP output) but 54 | it will likely not be relayed if the network mempools minimum feerate goes above 55 | `24 sat/vb` until [package relay][package_relay] is deployed on the Bitcoin network. 56 | 57 | - version: 2 58 | - locktime: 0 59 | 60 | #### IN 61 | 62 | - count: 1 63 | - inputs[0]: 64 | - txid: `` 65 | - vout: `` 66 | - sequence: `0xfffffffd` 67 | - scriptSig: `` 68 | - witness: `satisfy(deposit_descriptor)` 69 | 70 | #### OUT 71 | 72 | - count: 2 73 | - outputs[0]: 74 | - value: `` 75 | - scriptPubkey: `unvault_descriptor` 76 | 77 | - outputs[1]: 78 | - value: `30000` 79 | - scriptPubkey: `cpfp_descriptor` 80 | 81 | With: 82 | ``` 83 | unvault_descriptor = wsh(unvault_witness_script) 84 | unvault_witness_script = or(1@thresh(len(stakeholders), stakeholders), 9@and(thresh(len(managers), managers), and(thresh(len(cosigners), cosigners), older(X)))) 85 | ``` 86 | 87 | ``` 88 | cpfp_descriptor = wsh(cpfp_witness_script) 89 | cpfp_witness_script = thresh(1, pubkey1, pubkey2, ..., pubkeyM) # The pubkeys being the managers' 90 | ``` 91 | 92 | ## spend_tx 93 | 94 | The transaction which spends one or many [`unvault_tx`](#unvault_tx) `output[0]` by the [`M` + cosigners] 95 | path, only spendable after `X` blocks. 96 | The CPFP output value is adjusted depending on the actual transaction size. 97 | 98 | - version: 2 99 | - locktime: 0 100 | 101 | #### IN 102 | 103 | - count: 1 104 | - inputs[0]: 105 | - txid: `` 106 | - sequence: `X` 107 | - scriptSig: `` 108 | - witness: `satisfy(unvault_descriptor)` 109 | 110 | #### OUT 111 | 112 | - count: 1 113 | - outputs[0]: 114 | - value: `2 * 32 * tx_size_vbytes` 115 | - scriptPubkey: `cpfp_descriptor` 116 | - outputs[1]: 117 | - value: N/A (may be many of them) 118 | - scriptPubkey: N/A 119 | - outputs[n]: 120 | - value: N/A (may be many of them) 121 | - scriptPubkey: N/A 122 | 123 | 124 | ## cancel_tx 125 | 126 | The transaction which spends the [`unvault_tx`](#unvault_tx) `output[0]` using the N-of-N path and 127 | pays back to a deposit output (it is therefore another vault deposit transaction). 128 | 129 | The Cancel transaction is signed using the `ALL | ANYONECANPAY` signature hash flag, to 130 | allow watchtowers (or anyone else) to attach fee-bumping inputs. 131 | 132 | The Cancel transaction is signed at a fixed `22 sat/WU` feerate. This is in order to 133 | reduce the funds burden on *each* of the watchtowers. 134 | 135 | - version: 2 136 | - locktime: 0 137 | 138 | #### IN 139 | 140 | - count: 1 141 | - inputs[0]: 142 | - txid: `` 143 | - vout: 0 144 | - sequence: `0xfffffffd` 145 | - scriptSig: `` 146 | - witness: `satisfy(unvault_descriptor)` 147 | 148 | #### OUT 149 | 150 | - count: 1 151 | - outputs[0]: 152 | - value: `` 153 | - scriptPubkey: `deposit_descriptor` 154 | 155 | 156 | ## emergency_txs 157 | 158 | Emergency transactions are used as deterrents against threats targeting stakeholders' 159 | funds. They lock coins to what we call an EDV (Emergency Deep Vault): a script chosen 160 | by the participants and kept obfuscated by the properties of P2WSH, as the emergency 161 | transactions are never meant to be used. 162 | 163 | Both Emergency transactions are signed at a fixed `75 sat/WU` feerate. 164 | 165 | Both Emergency transaction are signed using the `ALL | ANYONECANPAY` signature hash flag, 166 | to allow watchtowers (or anyone else) to attach fee-bumping inputs. 167 | 168 | The Emergency `scriptPubKey` is not known to the managers. 169 | 170 | 171 | ### deposit_emergency_tx 172 | 173 | The transaction which spends the [`deposit_tx`](#deposit_tx) output to the EDV by the `N`-of-`N` path. 174 | 175 | - version: 2 176 | - locktime: 0 177 | 178 | #### IN 179 | 180 | - count: 1 181 | - inputs[0]: 182 | - txid: `` 183 | - vout: `` 184 | - sequence: `0xfffffffd` 185 | - scriptSig: `` 186 | - witness: `satisfy(deposit_descriptor)` 187 | 188 | #### OUT 189 | 190 | - count: 1 191 | - outputs[0]: 192 | - value: `` 193 | - scriptPubkey: `0x00 SHA256()` 194 | 195 | 196 | ### unvault_emergency_tx 197 | 198 | This transaction spends the [`unvault_tx`](#unvault_tx) `output[0]` to the EDV by the `N`-of-`N` path. 199 | 200 | - version: 2 201 | - locktime: 0 202 | 203 | #### IN 204 | 205 | - count: 1 206 | - inputs[0]: 207 | - txid: `` 208 | - vout: 0 209 | - sequence: `0xfffffffd` 210 | - scriptSig: `` 211 | - witness: `satisfy(unvault_descriptor)` 212 | 213 | #### OUT 214 | 215 | - count: 1 216 | - outputs[0]: 217 | - value: `` 218 | - scriptPubkey: `0x00 SHA256()` 219 | 220 | 221 | ## bypass_tx 222 | 223 | Bypass txs are used in the case where stakeholders need immediate access to funds. Bypass 224 | txs avoid the controls on expenses set by stakeholders and enforced by watchtowers. A 225 | Bypass tx spends the [`deposit_tx`](#deposit_tx) and pays to arbitrary addresses. 226 | 227 | - version: 2 228 | - locktime: 0 229 | 230 | #### IN 231 | 232 | - count: 1 233 | - inputs[0]: 234 | - txid: `` 235 | - vout: `` 236 | - sequence: `0xfffffffd` 237 | - scriptSig: `` 238 | - witness: `satisfy(deposit_descriptor)` 239 | 240 | #### OUT 241 | 242 | Unspecified 243 | 244 | 245 | [package_relay]: https://github.com/bitcoin/bitcoin/issues/14895 246 | -------------------------------------------------------------------------------- /transport.md: -------------------------------------------------------------------------------- 1 | # Transport 2 | 3 | Definition of transport used by communications happening in a version 0 Revault 4 | deployment. All the entities of the network being known in advance, each of them has 5 | a static public key exchanged during the deployment setup to then establish 6 | [Noise](Noise_protocol) [KK](Noise_kk) authenticated and encrypted channels. 7 | 8 | ### Entity Types 9 | 10 | The humans participating in an instance of the Revault protocol can have the role of Stakeholder and/ or Manager. Each Stakeholder will operate the following devices: portable device with revaultd, hardware wallet, co-signing server, and a watchtower. Managers will operate only a portable device with revaultd and a hardware wallet. The Coordinator will be operated by the organization using revault. 11 | 12 | In a future version of the protocol the Coordinator and additional watchtowers may be outsourced to a service provider. 13 | 14 | ### Network Map 15 | 16 | > TODO: Insert Diagram Here 17 | 18 | This diagram is an example where there are 4 humans. 2 have the role of Stakeholder, 1 is both a Stakeholder and a Manager, and 1 is only a Manager. Trust boundaries are drawn to distinguish which hardware and software instances are operated by each human. Additional trust boundaries are drawn to show that certain physical boundaries are required for some of the hardware. 19 | 20 | ### Networking Layers 21 | 22 | The design of the Revault network is logically separated into 4 layers: 23 | 24 | | Layer | Description | 25 | |----------------|---------------------------------------------------------------------------------------------------| 26 | | User Interface | Handles the communication between users and the Revault protocol | 27 | | Revault | Handles application level semantics and authentication of messages passed across multiple machines| 28 | | Noise | Handles authenticated and encrypted channels between any two connected machines | 29 | | Transport | Handles TCP streams for connections between any two machines | 30 | 31 | ### Noise Channels 32 | 33 | Authenticated and encrypted channels are established using [Noise KK](Noise_kk). 34 | The `KK` notation states that both the initiator's and the responder's static public 35 | keys are known to each other during the handshake. 36 | 37 | Consider the flow of [messages](https://github.com/re-vault/practical-revault/blob/master/messages.md) for spending and for routine transaction signing. We use the following definition of directionality for communications, with initiators on the left and responders on the right. 38 | 39 | ``` 40 | Stakeholder -> their Watchtower 41 | 42 | Stakeholder -> Coordinator 43 | 44 | Manager -> Cosigner 45 | 46 | Manager -> Coordinator 47 | 48 | Watchtower -> Coordinator 49 | ``` 50 | 51 | This determines with which entities the static public keys must be shared (as part of configuration information) during the initialization ceremony. 52 | 53 | We use noise channels with `Curve25519` for Diffie-Hellman functions, `ChaCha20-Poly1305` 54 | for cipher functions and `SHA256` for hash functions. 55 | 56 | [Noise_protocol]:http://noiseprotocol.org/noise.html#application-responsibilities 57 | [Noise_kk]:https://noiseexplorer.com/patterns/KK/ 58 | --------------------------------------------------------------------------------