├── LICENSE ├── README.md ├── feature-flags.md ├── img └── taproot-lightning-txs.jpg ├── lightning-privacy.md ├── lightning-txs.md ├── pinning-attacks.md ├── schnorr.md ├── spam-prevention.md ├── sphinx.md └── taproot-updates.md /LICENSE: -------------------------------------------------------------------------------- 1 | Apache License 2 | Version 2.0, January 2004 3 | http://www.apache.org/licenses/ 4 | 5 | TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 6 | 7 | 1. Definitions. 8 | 9 | "License" shall mean the terms and conditions for use, reproduction, 10 | and distribution as defined by Sections 1 through 9 of this document. 11 | 12 | "Licensor" shall mean the copyright owner or entity authorized by 13 | the copyright owner that is granting the License. 14 | 15 | "Legal Entity" shall mean the union of the acting entity and all 16 | other entities that control, are controlled by, or are under common 17 | control with that entity. For the purposes of this definition, 18 | "control" means (i) the power, direct or indirect, to cause the 19 | direction or management of such entity, whether by contract or 20 | otherwise, or (ii) ownership of fifty percent (50%) or more of the 21 | outstanding shares, or (iii) beneficial ownership of such entity. 22 | 23 | "You" (or "Your") shall mean an individual or Legal Entity 24 | exercising permissions granted by this License. 25 | 26 | "Source" form shall mean the preferred form for making modifications, 27 | including but not limited to software source code, documentation 28 | source, and configuration files. 29 | 30 | "Object" form shall mean any form resulting from mechanical 31 | transformation or translation of a Source form, including but 32 | not limited to compiled object code, generated documentation, 33 | and conversions to other media types. 34 | 35 | "Work" shall mean the work of authorship, whether in Source or 36 | Object form, made available under the License, as indicated by a 37 | copyright notice that is included in or attached to the work 38 | (an example is provided in the Appendix below). 39 | 40 | "Derivative Works" shall mean any work, whether in Source or Object 41 | form, that is based on (or derived from) the Work and for which the 42 | editorial revisions, annotations, elaborations, or other modifications 43 | represent, as a whole, an original work of authorship. For the purposes 44 | of this License, Derivative Works shall not include works that remain 45 | separable from, or merely link (or bind by name) to the interfaces of, 46 | the Work and Derivative Works thereof. 47 | 48 | "Contribution" shall mean any work of authorship, including 49 | the original version of the Work and any modifications or additions 50 | to that Work or Derivative Works thereof, that is intentionally 51 | submitted to Licensor for inclusion in the Work by the copyright owner 52 | or by an individual or Legal Entity authorized to submit on behalf of 53 | the copyright owner. For the purposes of this definition, "submitted" 54 | means any form of electronic, verbal, or written communication sent 55 | to the Licensor or its representatives, including but not limited to 56 | communication on electronic mailing lists, source code control systems, 57 | and issue tracking systems that are managed by, or on behalf of, the 58 | Licensor for the purpose of discussing and improving the Work, but 59 | excluding communication that is conspicuously marked or otherwise 60 | designated in writing by the copyright owner as "Not a Contribution." 61 | 62 | "Contributor" shall mean Licensor and any individual or Legal Entity 63 | on behalf of whom a Contribution has been received by Licensor and 64 | subsequently incorporated within the Work. 65 | 66 | 2. Grant of Copyright License. Subject to the terms and conditions of 67 | this License, each Contributor hereby grants to You a perpetual, 68 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 69 | copyright license to reproduce, prepare Derivative Works of, 70 | publicly display, publicly perform, sublicense, and distribute the 71 | Work and such Derivative Works in Source or Object form. 72 | 73 | 3. Grant of Patent License. Subject to the terms and conditions of 74 | this License, each Contributor hereby grants to You a perpetual, 75 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 76 | (except as stated in this section) patent license to make, have made, 77 | use, offer to sell, sell, import, and otherwise transfer the Work, 78 | where such license applies only to those patent claims licensable 79 | by such Contributor that are necessarily infringed by their 80 | Contribution(s) alone or by combination of their Contribution(s) 81 | with the Work to which such Contribution(s) was submitted. If You 82 | institute patent litigation against any entity (including a 83 | cross-claim or counterclaim in a lawsuit) alleging that the Work 84 | or a Contribution incorporated within the Work constitutes direct 85 | or contributory patent infringement, then any patent licenses 86 | granted to You under this License for that Work shall terminate 87 | as of the date such litigation is filed. 88 | 89 | 4. Redistribution. You may reproduce and distribute copies of the 90 | Work or Derivative Works thereof in any medium, with or without 91 | modifications, and in Source or Object form, provided that You 92 | meet the following conditions: 93 | 94 | (a) You must give any other recipients of the Work or 95 | Derivative Works a copy of this License; and 96 | 97 | (b) You must cause any modified files to carry prominent notices 98 | stating that You changed the files; and 99 | 100 | (c) You must retain, in the Source form of any Derivative Works 101 | that You distribute, all copyright, patent, trademark, and 102 | attribution notices from the Source form of the Work, 103 | excluding those notices that do not pertain to any part of 104 | the Derivative Works; and 105 | 106 | (d) If the Work includes a "NOTICE" text file as part of its 107 | distribution, then any Derivative Works that You distribute must 108 | include a readable copy of the attribution notices contained 109 | within such NOTICE file, excluding those notices that do not 110 | pertain to any part of the Derivative Works, in at least one 111 | of the following places: within a NOTICE text file distributed 112 | as part of the Derivative Works; within the Source form or 113 | documentation, if provided along with the Derivative Works; or, 114 | within a display generated by the Derivative Works, if and 115 | wherever such third-party notices normally appear. The contents 116 | of the NOTICE file are for informational purposes only and 117 | do not modify the License. You may add Your own attribution 118 | notices within Derivative Works that You distribute, alongside 119 | or as an addendum to the NOTICE text from the Work, provided 120 | that such additional attribution notices cannot be construed 121 | as modifying the License. 122 | 123 | You may add Your own copyright statement to Your modifications and 124 | may provide additional or different license terms and conditions 125 | for use, reproduction, or distribution of Your modifications, or 126 | for any such Derivative Works as a whole, provided Your use, 127 | reproduction, and distribution of the Work otherwise complies with 128 | the conditions stated in this License. 129 | 130 | 5. Submission of Contributions. Unless You explicitly state otherwise, 131 | any Contribution intentionally submitted for inclusion in the Work 132 | by You to the Licensor shall be under the terms and conditions of 133 | this License, without any additional terms or conditions. 134 | Notwithstanding the above, nothing herein shall supersede or modify 135 | the terms of any separate license agreement you may have executed 136 | with Licensor regarding such Contributions. 137 | 138 | 6. Trademarks. This License does not grant permission to use the trade 139 | names, trademarks, service marks, or product names of the Licensor, 140 | except as required for reasonable and customary use in describing the 141 | origin of the Work and reproducing the content of the NOTICE file. 142 | 143 | 7. Disclaimer of Warranty. Unless required by applicable law or 144 | agreed to in writing, Licensor provides the Work (and each 145 | Contributor provides its Contributions) on an "AS IS" BASIS, 146 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 147 | implied, including, without limitation, any warranties or conditions 148 | of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A 149 | PARTICULAR PURPOSE. You are solely responsible for determining the 150 | appropriateness of using or redistributing the Work and assume any 151 | risks associated with Your exercise of permissions under this License. 152 | 153 | 8. Limitation of Liability. In no event and under no legal theory, 154 | whether in tort (including negligence), contract, or otherwise, 155 | unless required by applicable law (such as deliberate and grossly 156 | negligent acts) or agreed to in writing, shall any Contributor be 157 | liable to You for damages, including any direct, indirect, special, 158 | incidental, or consequential damages of any character arising as a 159 | result of this License or out of the use or inability to use the 160 | Work (including but not limited to damages for loss of goodwill, 161 | work stoppage, computer failure or malfunction, or any and all 162 | other commercial damages or losses), even if such Contributor 163 | has been advised of the possibility of such damages. 164 | 165 | 9. Accepting Warranty or Additional Liability. While redistributing 166 | the Work or Derivative Works thereof, You may choose to offer, 167 | and charge a fee for, acceptance of support, warranty, indemnity, 168 | or other liability obligations and/or rights consistent with this 169 | License. However, in accepting such obligations, You may act only 170 | on Your own behalf and on Your sole responsibility, not on behalf 171 | of any other Contributor, and only if You agree to indemnify, 172 | defend, and hold each Contributor harmless for any liability 173 | incurred by, or claims asserted against, such Contributor by reason 174 | of your accepting any such warranty or additional liability. 175 | 176 | END OF TERMS AND CONDITIONS 177 | 178 | APPENDIX: How to apply the Apache License to your work. 179 | 180 | To apply the Apache License to your work, attach the following 181 | boilerplate notice, with the fields enclosed by brackets "[]" 182 | replaced with your own identifying information. (Don't include 183 | the brackets!) The text should be enclosed in the appropriate 184 | comment syntax for the file format. We also recommend that a 185 | file or class name and description of purpose be included on the 186 | same "printed page" as the copyright notice for easier 187 | identification within third-party archives. 188 | 189 | Copyright [yyyy] [name of copyright owner] 190 | 191 | Licensed under the Apache License, Version 2.0 (the "License"); 192 | you may not use this file except in compliance with the License. 193 | You may obtain a copy of the License at 194 | 195 | http://www.apache.org/licenses/LICENSE-2.0 196 | 197 | Unless required by applicable law or agreed to in writing, software 198 | distributed under the License is distributed on an "AS IS" BASIS, 199 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 200 | See the License for the specific language governing permissions and 201 | limitations under the License. 202 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Lightning Documentation 2 | 3 | A collection of some in-depth articles about the Lightning Network: 4 | 5 | * [Lightning transactions: from Zero to Hero](./lightning-txs.md) 6 | * [Lightning privacy: from Zero to Hero](./lightning-privacy.md) 7 | * [Pinning attacks](./pinning-attacks.md) 8 | * [Sphinx onion encryption: from Zero to Hero](./sphinx.md) 9 | * [Schnorr Wizardry](./schnorr.md) 10 | * [When Taproot?](./taproot-updates.md) 11 | * [Spamming the Lightning Network](./spam-prevention.md) 12 | * [Feature flags: from Zero to Hero](./feature-flags.md) 13 | -------------------------------------------------------------------------------- /feature-flags.md: -------------------------------------------------------------------------------- 1 | # Lightning feature flags: from Zero to Hero 2 | 3 | This article describes optional lightning features that nodes can turn on and off. 4 | Nodes actively tell the whole network about the features they support, to help peers looking for specific features connect to them. 5 | 6 | ## `data_loss_protect` 7 | 8 | This flag allows a node to detect upon channel reestablishment that it has lost state (i.e. thinks a state is 'current' while it has been superseded and maybe even revoked). This works because the commitment point (that is added with this flag) can be verified to be authentically derived from the secret, so the 'forgetful' node must have sent it to them before it lost its commitment point counter state. 9 | 10 | The node that receives the `channel_reestablish` could also just _pretend_ that it has lost state, and e.g. drop the connection after receiving `channel_reestablish`, tempting the peer to close with a revoked state that it thinks the pretender can't punish. But tempting a cheating node is better for an honest node, than entering into a Lightning peer connection, which would eventually get forced closed because of a commitment mismatch. At that point, a cheater knows with certainty that the 'forgetful' node is not bluffing, so the attack odds are better. 11 | 12 | Accepted in November 2017: [meeting log](https://docs.google.com/document/d/1x2Qr2VgqauFfPgs-uBv7B4GegifAzRmfA_LpebvsETM/edit) 13 | 14 | This option is required by most implementations, e.g. LND: [brontide.go:2749](https://github.com/lightningnetwork/lnd/blob/cc0321d1881ed23c9608cf898af2e2a7b347304a/peer/brontide.go#L2749). 15 | 16 | ## `upfront_shutdown_script` 17 | 18 | This makes a channel party commit to a `scriptpubkey` (output locking script) upon opening of a channel. In a cooperative close, without this flag, the funds are sent to an address chosen upon closing. This flag can increase security somewhat, since even an attacker with the channel keys may not have the keys of the address controlling the chosen `scriptpubkey`. 19 | 20 | ### Implementations 21 | 22 | - Electrum: since [this PR from January 2021](https://github.com/spesmilo/electrum/pull/6875#issuecomment-757900498), most likely part of v4.1. 23 | - C-Lightning: since [v0.7.3 from November 2019](https://medium.com/blockstream/the-latest-c-lightning-0-7-3-3efc107f092b) 24 | - LND: since [this PR merged in December 2019](https://github.com/lightningnetwork/lnd/pull/3655), part of [v0.9.0 from January 2020 according to release notes](https://github.com/lightningnetwork/lnd/releases/tag/v0.9.0-beta). 25 | - Eclair: since [this PR merged in July 2121](https://github.com/ACINQ/eclair/pull/1846) 26 | 27 | ## `gossip_queries` and `gossip_queries_ex` 28 | 29 | `gossip_queries` enables: 30 | * a `query_short_channel_ids` message such that a node can request gossip for given list of short channel IDs. 31 | * a `query_channel_range` message such that a node can request channel updates from a specified block range. 32 | * a `gossip_timestamp_filter` message that a node must use to signal the range of the channel updates it is interested in, filtered by their timestamp. 33 | 34 | `gossip_queries_ex` adds timestamps and checksums to `query_channel_range` replies. 35 | 36 | ### Implementations of `gossip_queries_ex` 37 | 38 | * Eclair: since [this PR merged in October 2019](https://github.com/ACINQ/eclair/pull/1165), part of [v0.3.2 according to branch tags on Github](https://github.com/ACINQ/eclair/commit/4300e7b651b934a5e0605d8a0319308894164936). 39 | * C-Lightning: since [this PR merged in September 2019](https://github.com/ElementsProject/lightning/pull/3071/commits/b553da3910daab41d5ef62281d92bb3499a146b2), part of [v0.7.3 according to branch tags on GitHub](https://github.com/ElementsProject/lightning/commit/27790832a5ee60fb595b322386d02883e77cd71a). 40 | * LND: `gossip_queries` supported since [this PR merged in May 2018](https://github.com/lightningnetwork/lnd/pull/1106), part of v0.5. 41 | 42 | ## `static_remote_key` 43 | 44 | This removes key-rotation from the `to_remote` output. This means that the `to_remote` output of every commitment transaction can be spent by the same key. If you lose channel state, this will allow you to claim your balance when the counterparty closes. Without this option, you'd have to grind and see which key matches. Watchtowers are also easier to implement with this. 45 | 46 | ### Implementations 47 | 48 | - C-Lightning: since [this PR from September 2019](https://github.com/ElementsProject/lightning/pull/3104), part of v0.7.3 according to the milestone there. 49 | - Eclair: since [this PR merged in June 2020](https://github.com/ACINQ/eclair/pull/1141), part of v0.5.0 according to [branch information](https://github.com/ACINQ/eclair/commit/dc364a1996548e405199fe38ad861a693baf4787) 50 | - LND: since [v0.8.0 from October 2019](https://github.com/lightningnetwork/lnd/releases/tag/v0.8.0-beta). LND requires this option for new channels: [brontide.go:2790](https://github.com/lightningnetwork/lnd/blob/cc0321d1881ed23c9608cf898af2e2a7b347304a/peer/brontide.go#L2790) 51 | - Electrum requires this for all peers since [4.0.1 from July 2020](https://github.com/spesmilo/electrum/blob/922a48f2b74bd6c58682f9d5b6163c4fbd45981a/RELEASE-NOTES#L107) 52 | 53 | ## `payment_secret` 54 | 55 | Merged in July 2019 as part of MPP: https://github.com/lightningnetwork/lightning-rfc/pull/643 56 | 57 | The feature prevents probing attacks as noted in BOLT-11. 58 | 59 | You can use payment_secret without necessarily using MPP, though it is a requirement for MPP. 60 | 61 | ### Implementations 62 | 63 | - C-Lightning: since at least [v0.8.0 from December 2019](https://github.com/ElementsProject/lightning/releases/tag/v0.8.0), since that version supports receiving MPP 64 | - Eclair: since at least [this PR from October 2019](https://github.com/ACINQ/eclair/pull/1153), released with MPP (see below) 65 | - Electrum: sent/accepted since [4.0.1 from July 2020](https://github.com/spesmilo/electrum/blob/922a48f2b74bd6c58682f9d5b6163c4fbd45981a/RELEASE-NOTES#L107) 66 | - LND: supported since v0.10.0 (see below), **required** in incoming payments since [v0.12.0](https://github.com/lightningnetwork/lnd/pull/4752) (unreleased as of January 7th, 2020): All generated invoices will include the `s` field. 67 | 68 | ## `basic_mpp` (multi-part payments) 69 | 70 | This splits a payment into multiple pieces, that all have the same payment hash (so it is [vulnerable to a straddling attack](https://lists.linuxfoundation.org/pipermail/lightning-dev/2018-February/000993.html)). This means that the theoretical maximum payment amount can be higher. A receiver doesn't know how many parts a payment is split into. To avoid an attack where one part the MPP payment will never arrive and the HTLC consumes resources over too long, receivers must fail incoming HTLCs after a reasonable timeout, usually 60 seconds. 71 | 72 | ### Implementations 73 | 74 | All listed implementations that have send support, also have receive support. 75 | 76 | - C-Lightning: Send support since [v0.9.0 from July 2020](https://github.com/ElementsProject/lightning/releases/tag/v0.9.0) 77 | - Eclair: Send support since [v0.3.3 from January 2020](https://github.com/ACINQ/eclair/releases/tag/v0.3.3), see also [wiki page](https://github.com/ACINQ/eclair/wiki/Multipart-Payments). 78 | - LND: Send support since [v0.10.0 from April 2020](https://github.com/lightningnetwork/lnd/releases/tag/v0.10.0-beta) 79 | -------------------------------------------------------------------------------- /img/taproot-lightning-txs.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/t-bast/lightning-docs/398a1b78250f564f7c86a414810f7e87e5af23ba/img/taproot-lightning-txs.jpg -------------------------------------------------------------------------------- /lightning-privacy.md: -------------------------------------------------------------------------------- 1 | # Lightning privacy: from Zero to Hero 2 | 3 | This article contains many privacy pitfalls of lightning, how you can avoid them, and how we plan 4 | on addressing them in the future. 5 | 6 | ## Table of Contents 7 | 8 | * [On-Chain to Off-Chain privacy](#on-chain-to-off-chain-privacy) 9 | * [Identifying lightning channel funding scripts](#identifying-lightning-channel-funding-scripts) 10 | * [Public Channels](#public-channels) 11 | * [Unannounced Channels](#unannounced-channels) 12 | * [Off-Chain to Off-Chain privacy](#off-chain-to-off-chain-privacy) 13 | * [Payment correlation](#payment-correlation) 14 | * [Identifying mobile wallets](#identifying-mobile-wallets) 15 | * [Path-finding tricks](#path-finding-tricks) 16 | * [Trampoline](#trampoline) 17 | * [Resources](#resources) 18 | 19 | ## On-Chain to Off-Chain privacy 20 | 21 | Whenever you use lightning, there will be an on-chain footprint: you will be opening and closing 22 | channels. It is important to ensure that this on-chain footprint doesn't leak too much information. 23 | 24 | ### Identifying lightning channel funding scripts 25 | 26 | As we saw in the [lightning transactions](./lightning-txs.md) article, the channel funding 27 | transaction uses a p2wsh 2-of-2 multisig. 28 | While the channel is open, this is fine: an attacker looking at the blockchain only sees a p2wsh 29 | output, which could contain anything. 30 | However, when the channel is closed, we have to reveal that it is using a 2-of-2 multisig, which 31 | is a strong indication that this may be a lightning channel. 32 | 33 | Fortunately, this is very easy to fix with Taproot. Instead of using a p2wsh output, we will use 34 | [Musig2](./schnorr.md) with a key path spend, which will be indistinguishable from a normal single 35 | signature output. 36 | 37 | However, there are two ways that a lightning channel can be closed: either cooperatively, where 38 | both participants create a transaction that sends each one of them their final balance, or 39 | unilaterally when one of the participants isn't collaborating. 40 | 41 | In the second case, the transaction that is broadcast is the commitment transaction that we 42 | described in the [lightning transactions](./lightning-txs.md) article. This transaction relies on 43 | specialized scripts that are unique to lightning to allow participants to recover their funds. 44 | These scripts will be visible on-chain and make it obvious that this was a lightning channel. 45 | Unfortunately, there is probably no way to work around this issue while guaranteeing funds safety. 46 | Node operators should avoid unilaterally closing as much as possible: this should only happen when 47 | a peer is malicious or has disappeared. 48 | 49 | ### Public Channels 50 | 51 | Lightning nodes currently advertize their channels in the lightning network by sending a 52 | `channel_announcement` message to their peers, who will relay this announcement to the rest of the 53 | network. This message contains the details of the funding transaction, which lets anyone running a 54 | lightning node know which utxos are actually lightning channels. 55 | 56 | The reason channels are advertized publicly inside the network is because we are using source 57 | routing to ensure payment privacy: when Alice wants to send a payment to Bob, Alice must find a 58 | route through existing channels to reach Bob. If Alice has access to the complete topology of the 59 | graph, she can find the route herself, without revealing to anyone that she intends to send a 60 | payment to Bob. 61 | 62 | ```text 63 | +------+ +-----+ 64 | | Node | | Bob | 65 | +------+ +-----+ 66 | | | 67 | | | 68 | +-------+ +------+ +------+ 69 | | Alice |---------| Node |---------| Node | 70 | +-------+ +------+ +------+ 71 | | | 72 | | +------+ | 73 | +-------------| Node |-------------+ 74 | +------+ 75 | ``` 76 | 77 | We can't get rid of this mechanism entirely if we want to preserve payment anonymity, but we can 78 | make it better. Instead of disclosing all the details of our channel, we only need to let the 79 | network know that there exists an on-chain transaction of at least a given amount that created a 80 | channel between two nodes. The details of how we'll do that are not completely fleshed out yet, 81 | but it should be possible with some cryptographic wizardry (e.g. ring signatures or zkps). 82 | 83 | ### Unannounced Channels 84 | 85 | Fortunately, nodes that don't want to route payments (e.g. mobile wallets and merchants) have the 86 | option of not announcing their channels to the network. 87 | 88 | ```text 89 | +------+ +------+ 90 | | Node |---------| Node | 91 | +------+ +------+ 92 | | | 93 | | | 94 | +-------+ +------+ +------+ +------+ +-----+ 95 | | Alice |ooooooooo| Node |---------| Node |---------| Node |ooooooooo| Bob | 96 | +-------+ +------+ +------+ +------+ +-----+ 97 | o | 98 | o +------+ | 99 | oooooooooooooo| Node |-------------+ 100 | +------+ 101 | 102 | NB: unannounced channels are represented with "ooooo" 103 | ``` 104 | 105 | However, whenever nodes want to receive a payment, the sender needs to know how to find them in the 106 | graph, so they have to disclose some information about their unannounced channels. 107 | This is currently done using Bolt 11 invoices, where all the details of some of their unannounced 108 | channels are included. This is bad because invoices are sometimes shared publicly (e.g. on Twitter) 109 | which reveals these unannounced channels to everyone. 110 | 111 | We have two upcoming features that will fix this: 112 | 113 | * [Offers](https://github.com/lightning/bolts/pull/798) provide a static "address" that can be 114 | shared publicly without revealing channel details. 115 | * [Route Blinding](https://github.com/lightning/bolts/pull/765) lets recipients completely hide 116 | their `node_id` and channels from payers. 117 | 118 | Note that routing nodes can also partially leverage unannounced channels to preserve some utxo 119 | privacy. Whenever two nodes have more than one channel open between them, they can choose to only 120 | announce one of them to the network and keep the others private. When they receive a payment to 121 | relay, they can use the unannounced channels, and nobody can know that they didn't use the public 122 | channel. See the following example where unannounced channels are represented with `oooo`: 123 | 124 | ```text 125 | 0.4 btc 1.2 btc 126 | oooooooooooooooooooo oooooooooooooooooooooo 127 | o o o o 128 | +------+ 1 btc +------+ 1.5 btc +------+ 0.8 btc +------+ 129 | | Node |-----------| Node |-------------| Node |-------------| Node | 130 | +------+ +------+ +------+ +------+ 131 | o 0.6 btc o 132 | oooooooooooooooooooo 133 | ``` 134 | 135 | There is a small drawback though: path-finding heuristics use the capacity between nodes to rank 136 | which channels to use. Since routing nodes will be hiding some of their capacity, they may rank a 137 | bit lower in path-finding scores. 138 | 139 | ## Off-Chain to Off-Chain privacy 140 | 141 | Once you have opened channels, lightning should offer greater anonymity for your payments, as they 142 | don't have any on-chain footprint. We explore some subtleties and pitfalls in the following 143 | sections. 144 | 145 | ### Payment correlation 146 | 147 | Lightning payments use an onion routing scheme called [Sphinx](./sphinx.md), which guarantees that 148 | intermediate nodes only know the previous and the next node in the route, but cannot know whether 149 | there are other hops before or after these nodes. 150 | 151 | For example, if Alice uses the following payment route to pay Dave: 152 | 153 | ```text 154 | +-------+ +-----+ +-------+ +------+ 155 | | Alice |---------->| Bob |---------->| Carol |---------->| Dave | 156 | +-------+ +-----+ +-------+ +------+ 157 | ``` 158 | 159 | When Bob receives the request to forward the payment to Carol, Bob only learns that: 160 | 161 | * the payment could come from Alice or another unknown node before Alice 162 | * the payment goes to Carol or another unknown node after Carol 163 | 164 | Similarly, Carol only learns the following facts: 165 | 166 | * the payment could come from Bob or another unknown node before Bob 167 | * the payment goes to Dave or another unknown node after Dave 168 | 169 | This mechanism provides great privacy for payments. However, we are unfortunately leaking some 170 | data: because of how HTLCs work, all nodes in the route are given the same payment identifier, 171 | the `payment_hash`. If two nodes in the route are controlled by the same entity, they can see 172 | that this is the same payment. 173 | 174 | ```text 175 | +---------------------------+ 176 | | Well well well... | 177 | | I know that payment hash! | 178 | +---------------------------+ 179 | | 180 | | 181 | +-------+ +-----+ +-------+ +------+ +------+ 182 | | Alice |---------->| Bob |---------->| Carol |---------->| Bob2 |---------->| Dave | 183 | +-------+ | +-----+ | +-------+ | +------+ | +------+ 184 | | | | | 185 | +--------------+ +--------------+ +--------------+ +--------------+ 186 | | payment_hash | | payment_hash | | payment_hash | | payment_hash | 187 | | 0x123456 | | 0x123456 | | 0x123456 | | 0x123456 | 188 | +--------------+ +--------------+ +--------------+ +--------------+ 189 | ``` 190 | 191 | We will see in the following section how this kind of payment correlation can hurt the privacy 192 | of mobile wallet payments. 193 | 194 | The good news is that Taproot lets us switch from HTLCs to PTLCs, and one of the benefits of that 195 | change is that it fixes this payment correlation attack entirely: with PTLCs, every node in the 196 | route sees a different, random payment identifier. 197 | 198 | ```text 199 | +-------------------------+ 200 | | Never seen that payment | 201 | | point before... | 202 | +-------------------------+ 203 | | 204 | | 205 | +-------+ +-----+ +-------+ +------+ +------+ 206 | | Alice |---------->| Bob |---------->| Carol |---------->| Bob2 |---------->| Dave | 207 | +-------+ | +-----+ | +-------+ | +------+ | +------+ 208 | | | | | 209 | +---------------+ +---------------+ +---------------+ +---------------+ 210 | | payment_point | | payment_point | | payment_point | | payment_point | 211 | | 0x02123456 | | 0x03ff0123 | | 0x03abcdef | | 0x026bcad3 | 212 | +---------------+ +---------------+ +---------------+ +---------------+ 213 | ``` 214 | 215 | ### Identifying mobile wallets 216 | 217 | Most users will make their lightning payments from mobile wallets. 218 | Mobile wallets are fundamentally different from server nodes: it is impossible for a mobile wallet 219 | to hide the fact that it is a mobile wallet to its direct peers. 220 | They do not have a stable IP address, they are offline most of the time, and they are not relaying 221 | payments, which is easy to detect. 222 | 223 | One of the consequences of that is that when a mobile wallet asks one of its peers to forward a 224 | payment, that peers learns that the mobile wallet is the sender. Similarly, when a node forwards 225 | a payment to a mobile wallet, it learns that this mobile wallet is the recipient. 226 | 227 | Combined with the payment correlation issue described in the previous section, it can let attackers 228 | discover who is paying who: 229 | 230 | ```text 231 | +-----------------------+ 232 | | Well well well... | 233 | | Alice is paying Dave! | 234 | +-----------------------+ 235 | | 236 | mobile | mobile 237 | +-------+ +-----+ +-------+ +------+ +------+ 238 | | Alice |---------->| Bob |---------->| Carol |---------->| Bob2 |---------->| Dave | 239 | +-------+ | +-----+ | +-------+ | +------+ | +------+ 240 | | | | | 241 | +--------------+ +--------------+ +--------------+ +--------------+ 242 | | payment_hash | | payment_hash | | payment_hash | | payment_hash | 243 | | 0x123456 | | 0x123456 | | 0x123456 | | 0x123456 | 244 | +--------------+ +--------------+ +--------------+ +--------------+ 245 | ``` 246 | 247 | Once lightning moves to PTLCs though, intermediate nodes will only be able to learn who the payer 248 | or the recipient is, but not both. As we've seen, mobile wallets cannot expect to hide this 249 | information anyway. However this isn't too bad, because: 250 | 251 | * mobile wallets can use Tor or VPNs to hide their real IP address: the only identity that they 252 | have on lightning is their `node_id`, which they can change regularly (at the cost of opening 253 | new channels) 254 | * peers only learn that mobile wallets are making payments or receiving them, but cannot know to 255 | or from whom 256 | * mobile wallets can make payments to themselves to create synthetic traffic and thwart off-chain 257 | analysis heuristics 258 | * mobile wallets can have multiple peers so that each of their peers only see a subset of their 259 | payments 260 | 261 | Note that this section only applies to mobile wallets that connect to nodes that are run by other 262 | people. If you run a lightning node yourself, and your mobile wallet only connects to that node, 263 | these issues don't apply: the network will not even see that your mobile wallet exists, since 264 | everything will go through your lightning node. 265 | 266 | ### Path-finding tricks 267 | 268 | More advanced attacks against payment privacy are possible by exploiting path-finding subtleties. 269 | Let's explore two of them: 270 | 271 | 1. multi-part payment path intersection 272 | 2. graph filtering 273 | 274 | Let's explore multi-part payment path intersection first. 275 | Multi-part payments improve payment privacy against intermediate nodes (because they only see a 276 | fraction of the total payment amount) but gives more data to the recipient node (because it sees 277 | multiple parts arriving through different channels). Let's consider the following multi-part 278 | payment: 279 | 280 | ```text 281 | +-------+ +------+ +------+ 282 | | Alice |----------| Node |----------| Node |------------------+ 283 | +-------+ +------+ +------+ | 284 | | | MPP part #1 285 | +------------------+ | 286 | | | 287 | +-----+ +------+ +------+ MPP part #2 +------+ 288 | | Bob |------------| Node |----------| Node |---------------| Dave | 289 | +-----+ +------+ +------+ +------+ 290 | | | 291 | | | 292 | | | MPP part #3 293 | +-------+ +------+ +------+ | 294 | | Carol |----------| Node |----------| Node |------------------+ 295 | +-------+ +------+ +------+ 296 | ``` 297 | 298 | Dave can walk back all possible paths to find where they intersect. A simple analysis of the graph 299 | makes it obvious that the most likely sender is thus Bob. With this kind of analysis, sender 300 | anonymity cannot be guaranteed. 301 | 302 | Note however that this is a toy theoretical example, exploiting this on the public graph for real 303 | payments may not be feasible, but I believe it's worth mentioning. 304 | 305 | The graph filtering attack is even more complex, and requires more resources, but the general idea 306 | is interesting to explore. 307 | 308 | Let's consider an end user (Alice) that is connected to a single node (Eve): 309 | 310 | ```text 311 | +-------+ +-----+ 312 | | Alice |----------| Eve | 313 | +-------+ +-----+ 314 | ``` 315 | 316 | Alice thinks her payments are private because she computes the routes herself. However, since her 317 | only peer is Eve, Alice gets updates about the public graph only through Eve. Eve can use this fact 318 | to filter out some channels, and provide Alice with a pruned version of the graph that forces Alice 319 | to go through nodes Eve controls to reach most parts of the network. 320 | 321 | ```text 322 | +------+ +------+ +------+ 323 | +-------------| Node |----------| Node |----------| Eve2 |-------------+ 324 | | +------+ +------+ +------+ | 325 | | | | 326 | | +-----------------+ | 327 | | | | 328 | +-------+ +-----+ +------+ +------+ +------+ +------+ 329 | | Alice |----------| Eve |----------| Node |xxxxxxxxxx| Node |----------| Node |----------| Dave | 330 | +-------+ +-----+ +------+ +------+ +------+ +------+ 331 | | | | 332 | | | | 333 | | | | 334 | | +------+ +------+ +------+ | 335 | +-------------| Node |xxxxxxxxxx| Node |----------| Node |-------------+ 336 | +------+ +------+ +------+ 337 | ``` 338 | 339 | In the sample graph above, Eve filters out the channels marked with `xxxxx`. If Alice wants to pay 340 | Dave, the only routes that she will find will go through Eve's second node, which allows Eve to 341 | deanonymize the payment. 342 | 343 | Again, it's important to emphasize that this kind of attacks only works in very specific cases, 344 | and is probably only of theoretical interest. 345 | 346 | ### Trampoline 347 | 348 | [Trampoline routing](https://github.com/lightning/bolts/pull/829) is a mechanism that lets mobile 349 | wallets partially defer calculation of a payment route to intermediate nodes. It is important to 350 | highlight that wallets don't defer the complete route calculation to intermediate nodes, only a 351 | part of it, which is why it can preserve payment privacy. 352 | 353 | Let's consider the following graph: 354 | 355 | ```text 356 | Alice's local neighborhood Dave's local neighorhood 357 | +--------------------------------------------------+ +--------------------------------------------------+ 358 | | | | | 359 | | +------+ | +------+ +------+ +------+ | +------+ | 360 | | +--------------| Node |-----------------------------| N2 |----------| N3 |----------| N4 |-------------+ +------------| Node | | 361 | | | +------+ | +------+ +------+ +------+ | | | +------+ | 362 | | | | | | | | | | | 363 | | | +------------------+ | | | | | | | 364 | | | | | | | | | | | 365 | | +-------+ +-----+ +-------+ | +------+ +------+ +------+ | +------+ +-------+ +------+ | 366 | | | Alice |----------| Bob |-----------| Terry |----------| N1 |----------| Node |----------| Node |----------| Ted |----------| Carol |----------| Dave | | 367 | | +-------+ +-----+ +-------+ | +------+ +------+ +------+ | +------+ +-------+ +------+ | 368 | | | | | | | 369 | | | +------------------+ | | | 370 | | | | | | | 371 | | | +------+ | | | 372 | | +--------------| Node | | | | 373 | | +------+ | | | 374 | | | | | 375 | +--------------------------------------------------+ +--------------------------------------------------+ 376 | ``` 377 | 378 | Alice and Dave don't need to sync the whole graph, just their local neighborhood, which saves them 379 | a lot of bandwidth and ensures that whenever they run path-finding algorithms, it's on a very small 380 | graph so it's very fast. 381 | 382 | Let's walk through a typical trampoline payment. 383 | 384 | The first step is for the recipient (Dave) to create an invoice, that will include some trampoline 385 | nodes that are in his neighborhood, and which will be able to route the payment to Dave. Dave finds 386 | these trampoline nodes by doing a simple graph search in his local neighborhood. 387 | To keep the example simple, Dave includes a single trampoline node (Ted) in his invoice. 388 | 389 | Alice scans Dave's invoice, which indicates that she must reach Ted. Alice selects a trampoline 390 | node in her own neighborhood (Terry). Alice then builds a trampoline route: 391 | 392 | ```text 393 | Alice -----> Terry -----> Ted -----> Dave 394 | ``` 395 | 396 | Alice encrypts this trampoline route in a payment onion, using exactly the same construction as 397 | normal payments, but with a smaller size. 398 | 399 | Alice then finds a route to Terry in her local neighborhood: 400 | 401 | ```text 402 | Alice -----> Bob -----> Terry 403 | ``` 404 | 405 | Alice creates a normal payment onion for that route, and includes the trampoline onion in the 406 | payload for Terry. At a high-level, the onion looks like this: 407 | 408 | ```text 409 | +---------------------------------+ 410 | | encrypted payload for Bob | 411 | +---------------------------------+ 412 | | encrypted payload for Terry | 413 | | +-----------------------------+ | 414 | | | encrypted payload for Terry | | 415 | | +-----------------------------+ | 416 | | | encrypted payload for Ted | | 417 | | +-----------------------------+ | 418 | | | encrypted payload for Dave | | 419 | | +-----------------------------+ | 420 | | | padding | | 421 | | +-----------------------------+ | 422 | +---------------------------------+ 423 | | padding | 424 | +---------------------------------+ 425 | ``` 426 | 427 | Alice sends the payment onwards: 428 | 429 | ```text 430 | Alice's local neighborhood Dave's local neighorhood 431 | +--------------------------------------------------+ +--------------------------------------------------+ 432 | | | | | 433 | | +------+ | +------+ +------+ +------+ | +------+ | 434 | | +--------------| Node |-----------------------------| N2 |----------| N3 |----------| N4 |-------------+ +------------| Node | | 435 | | | +------+ | +------+ +------+ +------+ | | | +------+ | 436 | | | | | | | | | | | 437 | | | +------------------+ | | | | | | | 438 | | | | | | | | | | | 439 | | +-------+ +-----+ +-------+ | +------+ +------+ +------+ | +------+ +-------+ +------+ | 440 | | | Alice |>>>>>>>>>>| Bob |>>>>>>>>>>>| Terry |----------| N1 |----------| Node |----------| Node |----------| Ted |----------| Carol |----------| Dave | | 441 | | +-------+ +-----+ +-------+ | +------+ +------+ +------+ | +------+ +-------+ +------+ | 442 | | | | | | | 443 | | | +------------------+ | | | 444 | | | | | | | 445 | | | +------+ | | | 446 | | +--------------| Node | | | | 447 | | +------+ | | | 448 | | | | | 449 | +--------------------------------------------------+ +--------------------------------------------------+ 450 | ``` 451 | 452 | Bob is an intermediate node in what looks to him like a normal payment. He only learns that: 453 | 454 | * the payment could come from Alice or another unknown node before Alice 455 | * the payment goes to Terry or another unknown node after Terry 456 | * Bob does not know that trampoline is being used 457 | 458 | When Terry receives the payment, he discovers that he must find a route to Ted and forward the 459 | payment to him. He only learns that: 460 | 461 | * the payment could come from Bob or another unknown node before Bob 462 | * the payment goes to Ted or another unknown node after Ted 463 | 464 | Terry finds a route to Ted and creates a normal onion for that route, including the trampoline 465 | onion in the payload for Ted (with the topmost layer of this onion unwrapped). 466 | At a high-level, the onion looks like this: 467 | 468 | ```text 469 | +--------------------------------+ 470 | | encrypted payload for N1 | 471 | +--------------------------------+ 472 | | encrypted payload for N2 | 473 | +--------------------------------+ 474 | | encrypted payload for N3 | 475 | +--------------------------------+ 476 | | encrypted payload for N4 | 477 | +--------------------------------+ 478 | | encrypted payload for Ted | 479 | | +----------------------------+ | 480 | | | encrypted payload for Ted | | 481 | | +----------------------------+ | 482 | | | encrypted payload for Dave | | 483 | | +----------------------------+ | 484 | | | padding | | 485 | | +----------------------------+ | 486 | +--------------------------------+ 487 | | padding | 488 | +--------------------------------+ 489 | ``` 490 | 491 | Terry sends the payment onwards: 492 | 493 | ```text 494 | Alice's local neighborhood Dave's local neighorhood 495 | +--------------------------------------------------+ +--------------------------------------------------+ 496 | | | | | 497 | | +------+ | +------+ +------+ +------+ | +------+ | 498 | | +--------------| Node |-----------------------------| N2 |>>>>>>>>>>| N3 |>>>>>>>>>>| N4 |>>>>>>>>>>>>>> +------------| Node | | 499 | | | +------+ | +------+ +------+ +------+ | v | +------+ | 500 | | | | | ^ | | v | | 501 | | | +------------------+ | ^ | | v | | 502 | | | | | ^ | | v | | 503 | | +-------+ +-----+ +-------+ | +------+ +------+ +------+ | +------+ +-------+ +------+ | 504 | | | Alice |>>>>>>>>>>| Bob |>>>>>>>>>>>| Terry |>>>>>>>>>>| N1 |----------| Node |----------| Node |----------| Ted |----------| Carol |----------| Dave | | 505 | | +-------+ +-----+ +-------+ | +------+ +------+ +------+ | +------+ +-------+ +------+ | 506 | | | | | | | 507 | | | +------------------+ | | | 508 | | | | | | | 509 | | | +------+ | | | 510 | | +--------------| Node | | | | 511 | | +------+ | | | 512 | | | | | 513 | +--------------------------------------------------+ +--------------------------------------------------+ 514 | ``` 515 | 516 | N1, N2, N3 and N4 are intermediate nodes in what looks like a normal payment. They only learn that: 517 | 518 | * the payment could come from the previous node or another unknown node before the previous node 519 | * the payment goes to the next node or another unknown node after the next node 520 | * they do not know that trampoline is being used 521 | 522 | When Ted receives the payment, he discovers that he must find a route to Dave and forward the 523 | payment to him. He only learns that: 524 | 525 | * the payment could come from N4 or another unknown node before N4 526 | * the payment goes to Dave or another unknown node after Dave 527 | * if Dave is a mobile wallet though, Ted learns that Dave is the final recipient 528 | * but Dave can use route blinding between him and Ted to hide its identity from Ted! 529 | 530 | Ted finds a route to Dave and creates a normal onion for that route, including the trampoline 531 | onion in the payload for Dave (with the topmost layer of this onion unwrapped). 532 | At a high-level, the onion looks like this: 533 | 534 | ```text 535 | +--------------------------------+ 536 | | encrypted payload for Carol | 537 | +--------------------------------+ 538 | | encrypted payload for Dave | 539 | | +----------------------------+ | 540 | | | encrypted payload for Dave | | 541 | | +----------------------------+ | 542 | | | padding | | 543 | | +----------------------------+ | 544 | +--------------------------------+ 545 | | padding | 546 | +--------------------------------+ 547 | ``` 548 | 549 | Ted sends the payment onwards: 550 | 551 | ```text 552 | Alice's local neighborhood Dave's local neighorhood 553 | +--------------------------------------------------+ +--------------------------------------------------+ 554 | | | | | 555 | | +------+ | +------+ +------+ +------+ | +------+ | 556 | | +--------------| Node |-----------------------------| N2 |>>>>>>>>>>| N3 |>>>>>>>>>>| N4 |>>>>>>>>>>>>>> +------------| Node | | 557 | | | +------+ | +------+ +------+ +------+ | v | +------+ | 558 | | | | | ^ | | v | | 559 | | | +------------------+ | ^ | | v | | 560 | | | | | ^ | | v | | 561 | | +-------+ +-----+ +-------+ | +------+ +------+ +------+ | +------+ +-------+ +------+ | 562 | | | Alice |>>>>>>>>>>| Bob |>>>>>>>>>>>| Terry |>>>>>>>>>>| N1 |----------| Node |----------| Node |----------| Ted |>>>>>>>>>>| Carol |>>>>>>>>>>| Dave | | 563 | | +-------+ +-----+ +-------+ | +------+ +------+ +------+ | +------+ +-------+ +------+ | 564 | | | | | | | 565 | | | +------------------+ | | | 566 | | | | | | | 567 | | | +------+ | | | 568 | | +--------------| Node | | | | 569 | | +------+ | | | 570 | | | | | 571 | +--------------------------------------------------+ +--------------------------------------------------+ 572 | ``` 573 | 574 | Carol is an intermediate node in what looks to her like a normal payment. She only learns that: 575 | 576 | * the payment could come from Ted or another unknown node before Ted 577 | * the payment goes to Dave or another unknown node after Dave 578 | * if Dave is a mobile wallet though, Carol learns that Dave is the final recipient (but it would 579 | be the same with a non-trampoline payment) 580 | * Carol does not know that trampoline is being used 581 | 582 | Since Alice and Dave are blind to most of the graph, there is a strong chance that the complete 583 | route used will be non-optimal. For example, the network could actually look like this: 584 | 585 | ```text 586 | Alice's local neighborhood Dave's local neighorhood 587 | +--------------------------------------------------+ +--------------------------------------------------+ 588 | | | | | 589 | | +------+ | +------+ +------+ +------+ | +------+ | 590 | | +--------------| Node |-----------------------------| N2 |----------| N3 |----------| N4 |-------------+ +------------| Node | | 591 | | | +------+ | +------+ +------+ +------+ | | | +------+ | 592 | | | | | | | | | | | 593 | | | +------------------+ | | | | | | | 594 | | | | | | | | | | | 595 | | +-------+ +-----+ +-------+ | +------+ +------+ +------+ | +------+ +-------+ +------+ | 596 | | | Alice |----------| Bob |-----------| Terry |----------| N1 |----------| Node |----------| Node |----------| Ted |----------| Carol |----------| Dave | | 597 | | +-------+ +-----+ +-------+ | +------+ +------+ +------+ | +------+ +-------+ +------+ | 598 | | | | | | | | 599 | | | +------------------+ | | | | 600 | | | | | | | | 601 | | | +------+ | | | | 602 | | +--------------| Node |----------------------|-------------------------------------------------------|--------------------------+ | 603 | | +------+ | | | 604 | | | | | 605 | +--------------------------------------------------+ +--------------------------------------------------+ 606 | ``` 607 | 608 | Where a very efficient route exists, but Alice and Dave don't know about it. 609 | This is actually a good thing for privacy, because it adds unpredictable randomness to the route 610 | which cannot be reverse-engineered by attackers' heuristics. 611 | 612 | In this example, we only used two intermediate trampoline nodes, as it is the most efficient way of 613 | using trampoline, but privacy-aware users may also randomly add another trampoline node in the 614 | middle of the route, which ensures that the final route will be very different from the optimal 615 | route. 616 | 617 | On top of that, trampoline combines very well with multi-part payments and makes them more reliable 618 | and private. Each trampoline node can aggregate the incoming multi-part payment and then split the 619 | outgoing payment differently: 620 | 621 | ```text 622 | 150k sat +------+ 250k sat 300k sat +------+ 200k sat 623 | +-------------| Node |-------------+ +-------------| Node |--------------+ 624 | | +------+ | | +------+ | 625 | | | | | 626 | | | | | 627 | | | | | 628 | +-------+ 250k sat +------+ 400k sat +-------+ 500k sat +------+ 629 | | Alice |---------------------------| Bob |-----------------------------| Carol |-------------------------| Dave | 630 | +-------+ +------+ +-------+ +------+ 631 | | | 632 | | | 633 | | | 634 | | +------+ | 635 | +-------------| Node |-------------+ 636 | 150k sat +------+ 300k sat 637 | ``` 638 | 639 | Since each trampoline node has knowledge of its local balances that remote nodes don't have, they 640 | are able to more efficiently decide how to split outgoing payments. 641 | 642 | Moreover, this also fixes the multi-part payment path intersection we've discussed earlier. 643 | Every trampoline node in the route (including the final recipient) is able to do some path 644 | intersection analysis, but the only thing that they would learn is who the previous trampoline 645 | node may be, which doesn't reveal who the actual payer is. 646 | 647 | ## Resources 648 | 649 | * [SLP 319: Lightning Protocol Privacy Exploration](https://stephanlivera.com/episode/319/) 650 | * [Offers specification](https://github.com/lightning/bolts/pull/798) 651 | * [Route Blinding specification](https://github.com/lightning/bolts/pull/765) 652 | * [Trampoline specification](https://github.com/lightning/bolts/pull/829) 653 | -------------------------------------------------------------------------------- /lightning-txs.md: -------------------------------------------------------------------------------- 1 | # Lightning transactions: from Zero to Hero 2 | 3 | This article contains everything you need to understand Bitcoin/Lightning transactions. 4 | We ignore segwit subtleties and fields that aren't necessary for our global understanding. 5 | 6 | ## Table of Contents 7 | 8 | * [Bitcoin transactions](#bitcoin-transactions) 9 | * [Transaction format](#transaction-format) 10 | * [Sighash flags](#sighash-flags) 11 | * [Absolute locktime](#absolute-locktime) 12 | * [Relative locktime](#relative-locktime) 13 | * [Lightning transactions](#lightning-transactions) 14 | * [Overview](#overview) 15 | * [Funding transaction](#funding-transaction) 16 | * [Commitment transaction](#commitment-transaction) 17 | * [HTLC transactions](#htlc-transactions) 18 | * [Closing transaction](#closing-transaction) 19 | * [Lightning transactions with anchor outputs](#lightning-transactions-with-anchor-outputs) 20 | * [Replace by fee](#replace-by-fee) 21 | * [Child pays for parent](#child-pays-for-parent) 22 | * [Bumping Lightning transactions](#bumping-lightning-transactions) 23 | * [Anchor outputs](#anchor-outputs) 24 | * [RBF Pinning](#rbf-pinning) 25 | * [Alternative proposal](#alternative-proposal) 26 | * [Resources](#resources) 27 | 28 | ## Bitcoin transactions 29 | 30 | ### Transaction format 31 | 32 | A Bitcoin transaction contains the following fields: 33 | 34 | ```json 35 | { 36 | "version": 2, 37 | "locktime": 634346, 38 | "vin": [ 39 | { 40 | "txid": "652cd2cc2b12ecc86e77ed067ae11815d6e6347e2ae40b8970a063880798787c", 41 | "vout": 2, 42 | "scriptSig": "", 43 | "sequence": 10 44 | } 45 | ], 46 | "vout": [ 47 | { 48 | "value": 0.1893, 49 | "scriptPubKey": "OP_HASH160 69ef88bab45ccfaa49f8421fdb4ae39efb23ffb2 OP_EQUAL" 50 | } 51 | ] 52 | } 53 | ``` 54 | 55 | * `locktime` can be used to impose an *absolute* timelock. 56 | * `vin` is the list of inputs that this transaction is spending: they match unspent outputs from 57 | previous transactions that have been included in blocks, and data that satisfies the spending 58 | conditions (`scriptPubKey`). 59 | * `txid` references the transaction containing the output we want to spend and `vout` is the index 60 | of that output in the transaction. It is computed as `SHA256(SHA256(raw_tx))`. 61 | * `scriptSig` contains data that satisfies the input's `scriptPubKey`. 62 | * `sequence` can be used to impose a *relative* timelock. 63 | * `vout` is the list of outputs that this transaction creates (unspent outputs until someone spends 64 | them by including them in a transaction's `vin`). `scriptPubKey` is a Bitcoin script that must be 65 | satisfied by the spender (usually a signature from a given public key, knowledge of the preimage 66 | of a hash, etc). 67 | 68 | ### Sighash flags 69 | 70 | One important and very useful subtlety of Bitcoin scripts is the `sighash` flags that can be used 71 | with the `OP_CHECKSIG` opcode (and variants of `OP_CHECKSIG`). 72 | 73 | Let's imagine that we have a UTXO with the following `scriptPubKey`: ` OP_CHECKSIG`, 74 | indicating that Alice can spend that UTXO. Alice can create a new transaction that includes that 75 | UTXO in `vin`. In the input's `scriptSig`, she needs to provide a valid signature of this *new* 76 | transaction. In addition to the signature bytes, she appends one byte that specifies what parts of 77 | the transaction were signed (that's the `sighash` flags). 78 | 79 | These `sighash` flags provide some flexibility for complex, multi-participants transactions. When 80 | some parts of the transaction are *not* signed, that means others participants can slightly update 81 | the transaction while keeping it valid, without requiring the signer to re-sign the changes. 82 | 83 | The possible values for that `sighash` byte are: 84 | 85 | * SIGHASH_ALL (default): the whole transaction is signed, except input scripts (otherwise there's a 86 | chicken-and-egg problem). That means the signer doesn't want anyone to be able to modify the 87 | transaction after it has been signed. 88 | * SIGHASH_NONE: the outputs are not signed. That means the signer agrees to the chosen inputs (where 89 | bitcoins come from), but lets other participants freely change the outputs (where the bitcoins go). 90 | * SIGHASH_SINGLE: only the output that has the same index as the input containing the signature is 91 | signed. There is also a small subtlety on the inputs: their `sequence` field isn't signed. This 92 | means the signer agrees to the chosen inputs and a single output of his choice, but lets other 93 | participants modify the other outputs freely. 94 | * SIGHASH_ANYONECANPAY: only the input containing the signature is signed, the other inputs are 95 | ignored and can be modified freely by other participants. 96 | 97 | Note that obviously, SIGHASH_ALL, SIGHASH_NONE and SIGHASH_SINGLE are mutually exclusive. However 98 | SIGHASH_ANYONECANPAY can be used in combination with SIGHASH_ALL, SIGHASH_NONE or SIGHASH_SINGLE. 99 | 100 | Note that the combination `SIGHASH_NONE | SIGHASH_ANYONECANPAY` is a dangerous footgun: you give 101 | away a UTXO but have no control whatsoever on where it will be sent. 102 | 103 | There are proposals to add a flag that doesn't sign any of the inputs, relying only on script 104 | compatibility to ensure transaction validity. There are currently two variations around that idea: 105 | 106 | * [SIGHASH_NOINPUT](https://lists.linuxfoundation.org/pipermail/bitcoin-dev/2016-February/012460.html) 107 | * [SIGHASH_ANYPREVOUT](https://github.com/bitcoin/bips/blob/master/bip-0118.mediawiki) 108 | 109 | ### Absolute locktime 110 | 111 | Bitcoin makes it possible to restrict the future time at which a transaction becomes valid. 112 | Such timelocks can be expressed in block height or timestamp, but we'll only consider the block 113 | height version here. 114 | 115 | A first possibility is to restrict this at the transaction level, by setting the `locktime` field. 116 | The transaction will then be considered invalid until the block height becomes greater than this 117 | `locktime` value. This may be useful if you want to share a signed transaction with someone, but 118 | don't want it to be included immediately in a block. Note that there is one exception to this rule: 119 | if all the inputs' `sequence` fields are set to `0xffffffff`, the `locktime` check is disabled (for 120 | historical reasons). 121 | 122 | Another possibility is to restrict this at the script level, by using the following script: 123 | ` OP_CHECKLOCKTIMEVERIFY`. This is a more powerful mechanism: you can create a UTXO 124 | that can be redeemed by someone else, while preventing the recipient from redeeming it before the 125 | specified `block_height`. 126 | 127 | ### Relative locktime 128 | 129 | Bitcoin also makes it possible to restrict when a UTXO can be spent, relatively to when that UTXO 130 | was created. This is especially useful when you exchange signed transactions off-chain, but don't 131 | know when these transactions will be broadcast on-chain (and thus have no idea what block height 132 | would make sense to put in the `locktime` field). 133 | 134 | This is done by using the `sequence` field on a transaction's inputs. When correctly set (according 135 | to the rules defined in BIP68), it ensures that the transaction becomes valid only `n` blocks after 136 | the output it spends has been included in a block. This may be useful if you want to share a signed 137 | transaction with someone, and that transaction spends from an unconfirmed transaction, and you want 138 | to ensure there is a specific delay between these two transactions confirm. 139 | 140 | Another possibility is to restrict this at the script level, by using the following script: 141 | ` OP_CHECKSEQUENCEVERIFY`. This is a more powerful mechanism: you can create a UTXO that can be 142 | redeemed by someone else, while ensuring the recipient can only redeem it at least `n` blocks after 143 | the first transaction was confirmed. 144 | 145 | ## Lightning transactions 146 | 147 | Lightning transactions leverage the mechanisms explained in the above sections, so make sure you 148 | understood them all before reading on. 149 | 150 | [Bolt 3](https://github.com/lightningnetwork/lightning-rfc/blob/master/03-transactions.md) also 151 | contains all the details about the transactions, but it's quite compact and can be hard to read for 152 | non-implementers. Hopefully this document helps fill in the gaps in that specification. 153 | 154 | ### Overview 155 | 156 | Here is the high-level view of all transactions used for a channel between A and B (note that we 157 | are B in this example, and when we say "us" in the following section we refer to B): 158 | 159 | ```ascii 160 | +------------+ 161 | | funding tx | 162 | +------------+ 163 | | 164 | | +-------------+ 165 | +------->| commit tx B | 166 | +-------------+ 167 | | | | | 168 | | | | | A's main output 169 | | | | +-----------------> to A 170 | | | | 171 | | | | +---> to B after relative delay 172 | | | | B's main output | 173 | | | +-----------------+ 174 | | | | 175 | | | +---> to A with revocation key 176 | | | 177 | | | +---> to B after relative delay 178 | | | +-----------------+ | 179 | | | +--->| HTLC-timeout tx |---+ 180 | | | HTLC offered by B | +-----------------+ | 181 | | +-------------------+ (after timeout) +---> to A with revocation key 182 | | | 183 | | +---> to A with payment preimage 184 | | | 185 | | +---> to A with revocation key 186 | | 187 | | +---> to B after relative delay 188 | | +-----------------+ | 189 | | +------>| HTLC-success tx |------+ 190 | | HTLC received by B | +-----------------+ | 191 | +--------------------+ (with payment preimage) +---> to A with revocation key 192 | | 193 | +---> to A after timeout (absolute delay) 194 | | 195 | +---> to A with revocation key 196 | ``` 197 | 198 | Notation: 199 | 200 | * transactions are enclosed in boxes 201 | * incoming arrows represent inputs 202 | * outgoing arrows represent outputs 203 | * branching in an output (with a `+`) represents a branching condition in script (`OP_IF`) 204 | 205 | A has a symmetric set of transactions, where A and B have been swapped (and amounts appropriately 206 | swapped as well). Participants are always able to generate the transaction that the *other* side 207 | holds (this is necessary to send them their signature). 208 | 209 | NB: in the sample transactions below, we directly write the spending scripts in `scriptPubKey` for 210 | clarity (in real transactions they are P2WSH scripts). 211 | 212 | ### Funding transaction 213 | 214 | A channel always starts with a funding transaction. This one is very simple. It only has to create 215 | an output with the following `scriptPubKey`: 216 | 217 | ```script 218 | 2 2 OP_CHECKMULTISIG 219 | ``` 220 | 221 | We don't care about the inputs that are used, and whether other outputs are created. 222 | The structure of the funding transaction thus looks like: 223 | 224 | ```json 225 | { 226 | "version": 2, 227 | "locktime": 0, 228 | "vin": [ 229 | { 230 | "...": "..." 231 | }, 232 | ... 233 | ], 234 | "vout": [ 235 | { 236 | "value": 1.0, 237 | "scriptPubKey": "2 2 OP_CHECKMULTISIG" 238 | }, 239 | ... 240 | ] 241 | } 242 | ``` 243 | 244 | ### Commitment transaction 245 | 246 | The commitment transaction contains the channel state, which consists of two parts: the balance of 247 | each participant and all the pending payments (HTLCs). 248 | 249 | It has a single input, which is the funding transaction and uses `SIGHASH_ALL`. This ensures both 250 | participants agree on the exact details of the commitment transaction when they exchange signatures. 251 | 252 | It sets `locktime` and `sequence` to values that allow spending it without delays (these fields are 253 | also used to hide some data in a very clever way we don't care about for this document). 254 | 255 | When anything changes in the channel (new payments are added, pending payments are failed or 256 | fulfilled): 257 | 258 | * a new commitment transaction is created that replaces the previous one 259 | * participants exchange signatures for that new commitment transaction 260 | * participants reveal the revocation secret for the previous commitment transaction 261 | 262 | The commitment transaction for a channel with capacity 1 BTC may look like: 263 | 264 | ```json 265 | { 266 | "version": 2, 267 | "locktime": 543210000, 268 | "vin": [ 269 | { 270 | "txid": "...", 271 | "vout": ..., 272 | "scriptSig": "0 ", 273 | "sequence": 2500123456 274 | } 275 | ], 276 | "vout": [ 277 | { 278 | "value": 0.5, 279 | "scriptPubKey": " 280 | # to_local output 281 | OP_IF 282 | # funds go to anyone who has the revocation key 283 | 284 | OP_ELSE 285 | # or back to us after a relative delay () 286 | 287 | OP_CHECKSEQUENCEVERIFY 288 | OP_DROP 289 | 290 | OP_ENDIF 291 | OP_CHECKSIG 292 | " 293 | }, 294 | { 295 | "value": 0.3, 296 | "scriptPubKey": " 297 | # to_remote output: goes back to the other channel participant immediately 298 | P2WKH() 299 | " 300 | }, 301 | { 302 | "value": 0.05, 303 | "scriptPubKey": " 304 | # A pending HTLC (payment) sent by us 305 | OP_DUP OP_HASH160 OP_EQUAL 306 | OP_IF 307 | # funds go to anyone who has the revocation key 308 | OP_CHECKSIG 309 | OP_ELSE 310 | OP_SWAP OP_SIZE 32 OP_EQUAL 311 | OP_NOTIF 312 | # funds go back to us via a second-stage HTLC-timeout transaction (which contains an absolute delay) 313 | # NB: we also need the remote signature, which prevents us from unilaterally changing the HTLC-timeout transaction 314 | OP_DROP 2 OP_SWAP 2 OP_CHECKMULTISIG 315 | OP_ELSE 316 | # funds go to the remote node if it has the payment preimage. 317 | OP_HASH160 OP_EQUALVERIFY 318 | OP_CHECKSIG 319 | OP_ENDIF 320 | OP_ENDIF 321 | " 322 | }, 323 | { 324 | "value": 0.03, 325 | "scriptPubKey": " 326 | # Another pending HTLC (payment) sent by us 327 | OP_DUP OP_HASH160 OP_EQUAL 328 | OP_IF 329 | # funds go to anyone who has the revocation key 330 | OP_CHECKSIG 331 | OP_ELSE 332 | OP_SWAP OP_SIZE 32 OP_EQUAL 333 | OP_NOTIF 334 | # funds go back to us via a second-stage HTLC-timeout transaction (which contains an absolute delay) 335 | # NB: we also need the remote signature, which prevents us from unilaterally changing the HTLC-timeout transaction 336 | OP_DROP 2 OP_SWAP 2 OP_CHECKMULTISIG 337 | OP_ELSE 338 | # funds go to the remote node if it has the payment preimage. 339 | OP_HASH160 OP_EQUALVERIFY 340 | OP_CHECKSIG 341 | OP_ENDIF 342 | OP_ENDIF 343 | " 344 | }, 345 | { 346 | "value": 0.08, 347 | "scriptPubKey": " 348 | # A pending HTLC (payment) sent to us 349 | OP_DUP OP_HASH160 OP_EQUAL 350 | OP_IF 351 | # funds go to anyone who has the revocation key 352 | OP_CHECKSIG 353 | OP_ELSE 354 | OP_SWAP OP_SIZE 32 OP_EQUAL 355 | OP_IF 356 | # funds go to us via a second-stage HTLC-success transaction once we have the payment preimage 357 | # NB: we also need the remote signature, which prevents us from unilaterally changing the HTLC-success transaction 358 | OP_HASH160 OP_EQUALVERIFY 359 | 2 OP_SWAP 2 OP_CHECKMULTISIG 360 | OP_ELSE 361 | # funds go to the remote node after an absolute delay (timeout) 362 | OP_DROP OP_CHECKLOCKTIMEVERIFY OP_DROP 363 | OP_CHECKSIG 364 | OP_ENDIF 365 | OP_ENDIF 366 | " 367 | }, 368 | { 369 | "value": 0.04, 370 | "scriptPubKey": " 371 | # Another pending HTLC (payment) sent to us 372 | OP_DUP OP_HASH160 OP_EQUAL 373 | OP_IF 374 | # funds go to anyone who has the revocation key 375 | OP_CHECKSIG 376 | OP_ELSE 377 | OP_SWAP OP_SIZE 32 OP_EQUAL 378 | OP_IF 379 | # funds go to us via a second-stage HTLC-success transaction once we have the payment preimage 380 | # NB: we also need the remote signature, which prevents us from unilaterally changing the HTLC-success transaction 381 | OP_HASH160 OP_EQUALVERIFY 382 | 2 OP_SWAP 2 OP_CHECKMULTISIG 383 | OP_ELSE 384 | # funds go to the remote node after an absolute delay (timeout) 385 | OP_DROP OP_CHECKLOCKTIMEVERIFY OP_DROP 386 | OP_CHECKSIG 387 | OP_ENDIF 388 | OP_ENDIF 389 | " 390 | }, 391 | ] 392 | } 393 | ``` 394 | 395 | A few important points to note: 396 | 397 | * there can be many incoming and outgoing pending payments (HTLCs) inside the commitment transaction 398 | * knowledge of the revocation key allows a participant to claim all the funds in the channel, so 399 | it's very important to make sure you don't publish an outdated commitment transaction 400 | * it's always better if it's the other side that publishes its commitment transaction: HTLCs can be 401 | directly fulfilled or timed out without the need for a second-stage transaction 402 | * these incentives ensure that you cooperatively close channels instead of publishing the commitment 403 | transaction: the only case where you should publish your commitment transaction is if the remote 404 | has become unresponsive or behaves maliciously 405 | 406 | ### HTLC transactions 407 | 408 | The HTLC transactions are second-stage transactions that spend HTLC outputs from your commitment 409 | transaction. They require `SIGHASH_ALL` signatures from both participants. This second stage is 410 | necessary to decouple the HTLC timeout (an absolute block height) from the relative timeout applied 411 | to local funds (`to_self_delay`); otherwise we wouldn't be able to fulfill or fail HTLCs before the 412 | `to_self_delay` period. 413 | 414 | An HTLC-success transaction looks like: 415 | 416 | ```json 417 | { 418 | "version": 2, 419 | "locktime": 0, 420 | "vin": [ 421 | { 422 | "txid": "...", 423 | "vout": 42, 424 | "scriptSig": "0 ", 425 | "sequence": 0 426 | } 427 | ], 428 | "vout": [ 429 | { 430 | "value": 0.04, 431 | "scriptPubKey": " 432 | OP_IF 433 | # funds go to anyone who has the revocation key 434 | 435 | OP_ELSE 436 | # or back to us after a relative delay () 437 | `to_self_delay` 438 | OP_CHECKSEQUENCEVERIFY 439 | OP_DROP 440 | 441 | OP_ENDIF 442 | OP_CHECKSIG 443 | " 444 | } 445 | ] 446 | } 447 | ``` 448 | 449 | An HTLC-timeout transaction looks like: 450 | 451 | ```json 452 | { 453 | "version": 2, 454 | "locktime": , 455 | "vin": [ 456 | { 457 | "txid": "...", 458 | "vout": 42, 459 | "scriptSig": "0 <>", 460 | "sequence": 0 461 | } 462 | ], 463 | "vout": [ 464 | { 465 | "value": 0.04, 466 | "scriptPubKey": " 467 | OP_IF 468 | # funds go to anyone who has the revocation key 469 | 470 | OP_ELSE 471 | # or back to us after a relative delay () 472 | `to_self_delay` 473 | OP_CHECKSEQUENCEVERIFY 474 | OP_DROP 475 | 476 | OP_ENDIF 477 | OP_CHECKSIG 478 | " 479 | } 480 | ] 481 | } 482 | ``` 483 | 484 | Once HTLC transactions are confirmed, their outputs can be spent simply with your (unilateral) 485 | signature, which allows you to send the funds back to your wallet whenever is convenient. 486 | 487 | ### Closing transaction 488 | 489 | You have probably noticed that using the commitment transaction and then HTLC transactions to 490 | transfer off-chain funds back on-chain is complex and expensive (this will cost quite a lot of 491 | on-chain transaction fees). This is meant to be the exceptional case where your peer isn't 492 | collaborating. The recommended way of closing a channel to transfer funds back on-chain is via a 493 | closing transaction that is built collaboratively. 494 | 495 | When one of the channel participants initiates a channel close, the channel stops accepting new 496 | payments. Both sides wait and settle pending payments (either fulfill or fail) to remove all HTLC 497 | outputs from the commitment transaction. Once there are only 2 outputs remaining (one for each 498 | participant, representing its latest balance in the channel), participants exchange adresses to 499 | send the funds to (which removes the relative `to_self_delay`, allowing channel funds to be spent 500 | immediately and unilaterally on-chain). 501 | 502 | The resulting closing transaction looks like: 503 | 504 | ```json 505 | { 506 | "version": 2, 507 | "locktime": 0, 508 | "vin": [ 509 | { 510 | "txid": "...", 511 | "vout": 42, 512 | "scriptSig": "0 ", 513 | "sequence": 0xFFFFFFFF 514 | } 515 | ], 516 | "vout": [ 517 | { 518 | "value": 0.4, 519 | "scriptPubKey": "an address provided by A" 520 | }, 521 | { 522 | "value": 0.6, 523 | "scriptPubKey": "an address provided by B" 524 | } 525 | ] 526 | } 527 | ``` 528 | 529 | The closing transaction spends directly from the funding transaction, hiding all the complexity of 530 | the commitment transaction and HTLC transactions. The resulting on-chain footprint of the channel 531 | looks like: 532 | 533 | ```ascii 534 | +------------+ 535 | | funding tx | 536 | +------------+ 537 | | 538 | | +------------+ 539 | +--------->| closing tx | 540 | +------------+ 541 | | | 542 | | | 543 | | +-----> A's output 544 | | 545 | +-------> B's output 546 | ``` 547 | 548 | NB: the `sequence` is set to `0xFFFFFFFF` to ensure all timelocks are disabled. 549 | 550 | ## Lightning transactions with anchor outputs 551 | 552 | The transactions format we've just described works great *if the following assumptions 553 | hold*: 554 | 555 | 1. nodes are receiving (on-chain) blocks without too much delay 556 | 2. published transactions are quickly included in blocks 557 | 558 | But what happens if your peer becomes unresponsive and suddenly on-chain fees rise tremendously? 559 | Because the commitment transaction and HTLC transactions require signatures from both participants, 560 | you are unable to raise the fee; your transaction will only be confirmed once on-chain fees go back 561 | to lower levels. Our second condition doesn't hold true anymore and this can be a real issue since 562 | HTLCs timeout at a specific, absolute block height. 563 | 564 | You need to be able to increase the fee of your commitment transaction and HTLC transactions to 565 | incentivize miners to include them in a block. Bitcoin provides two mechanisms for that, that we 566 | will explain below: replace-by-fee (RBF) and child-pays-for-parent (CPFP). 567 | 568 | RBF allows the *spender* to increase fees; CPFP allows the *recipient* to increase fees. 569 | 570 | ### Replace by fee 571 | 572 | RBF lets you replace a mempool transaction. But replacing transactions has a cost for the network 573 | because the new version of the transaction needs to propagate to the whole network. In order to 574 | avoid creating an easy DoS attack vector, RBF imposes strict restrictions on the new version of the 575 | transaction, detailed in [BIP 125](https://github.com/bitcoin/bips/blob/master/bip-0125.mediawiki). 576 | 577 | These rules have quite subtle consequences so it's worth reading the BIP in details. The gist of it 578 | is that the new transaction must pay strictly more fees than the whole unconfirmed "package" it 579 | replaces (otherwise miners would have no incentive to favor this new transaction). 580 | 581 | RBF can also be explicitly disabled at the transaction level by setting the `sequence` of all 582 | inputs to `0xFFFFFFFF`. 583 | 584 | ### Child pays for parent 585 | 586 | CPFP lets you attach a child transaction to an unconfirmed transaction. By paying a big fee on the 587 | child transaction, you can incentivize miners to include both the parent and the child transactions 588 | in a block, speeding up the confirmation of the parent transaction. 589 | 590 | If the child transaction still doesn't pay enough fees to get the transactions confirmed quickly 591 | (for example because the fees kept rising), the combination of RBF and CPFP can help you unblock 592 | the situation. You can use RBF on your child transaction (or on the parent if you're able to, but 593 | usually you won't be able to produce the signatures to replace the parent transaction), or use CPFP 594 | by appending yet another child to the chain of unconfirmed transactions. 595 | 596 | ```ascii 597 | mempool 598 | +------------------------------------------------------------+ 599 | | +---------------+ | 600 | | +---------+ | some other tx | | 601 | | | some tx | +---------------+ | 602 | | +---------+ | 603 | | | 604 | | +---------+ +-----------+ | 605 | | | tx with |----------->| child tx1 | | 606 | | | low fee |----+ +-----------+ | 607 | | +---------+ | +-----------+ +-----------+ | 608 | | +------>| child tx2 |------>| child tx3 | | 609 | | +-----------+ +-----------+ | 610 | +------------------------------------------------------------+ 611 | ``` 612 | 613 | There is however a limit on the chain of unconfirmed transactions you'll be able to add to the 614 | mempool. Once that limit is reached, the only options to speed up confirmation are: 615 | 616 | * wait for some of the transactions to be evicted from the mempool (then you can re-submit them 617 | with a higher fee): this can take a while 618 | * RBF one of the transactions: because of the RBF rules, this may be very costly (the fee increase 619 | you will need to provide may be non-negligible) 620 | * leverage the [CPFP carve-out rule](https://bitcoinops.org/en/topics/cpfp-carve-out/): this is a 621 | special rule that was added especially to unblock that scenario, which allows you to add a last 622 | additional child transaction, but only if its only parent is the first unconfirmed transaction. 623 | This means the first unconfirmed transaction needs to have an output available for that purpose. 624 | 625 | ```ascii 626 | mempool: the chain txA -> txB -> txC has the maximum allowed size 627 | +------------------------------------------------------------+ 628 | | +---------------+ | 629 | | +---------+ | some other tx | | 630 | | | some tx | +---------------+ | 631 | | +---------+ | 632 | | | 633 | | +---------+ +-----------+ +-----------+ | 634 | | | txA |----->| child txB |----->| child txC | | 635 | | | low fee | +-----------+ +-----------+ | 636 | | +---------+ | 637 | +------------------------------------------------------------+ 638 | 639 | the carve-out rule allows us to bypass the size limit and add the child txD 640 | +------------------------------------------------------------+ 641 | | +---------------+ | 642 | | +---------+ | some other tx | | 643 | | | some tx | +---------------+ | 644 | | +---------+ | 645 | | | 646 | | +---------+ +-----------+ +-----------+ | 647 | | | txA |----->| child txB |----->| child txC | | 648 | | | low fee |--+ +-----------+ +-----------+ | 649 | | +---------+ | +-----------+ | 650 | | +-->| child txD | | 651 | | +-----------+ | 652 | +------------------------------------------------------------+ 653 | ``` 654 | 655 | NB: when using CPFP, the child transaction you are adding must be valid (miners must be able to 656 | potentially include it in the next block). If your child transaction has an absolute or relative 657 | timelock set in the future, it will be rejected. In particular, if your child transaction has a 658 | relative timelock on a parent transaction that is still in the mempool, you cannot use it for CPFP. 659 | 660 | ### Bumping Lightning transactions 661 | 662 | As we've seen previously, there are 5 types of transactions in Lightning: 663 | 664 | * funding transaction 665 | * commitment transaction 666 | * htlc-success 667 | * htlc-timeout 668 | * closing transaction 669 | 670 | At a high-level, this table summarizes which can be RBF-ed or CPFP-ed *unilaterally*: 671 | 672 | | Transaction | RBF | CPFP | 673 | | ------------ | ------------------- | ------------------- | 674 | | funding | :heavy_check_mark:* | :heavy_check_mark: | 675 | | commitment | :x: | :heavy_check_mark:* | 676 | | htlc-success | :x: | :x: | 677 | | htlc-timeout | :x: | :x: | 678 | | closing | :x: | :heavy_check_mark: | 679 | 680 | The funding transaction can be RBF-ed (since it's created completely unilaterally), but this will 681 | invalidate its transaction id so you'll need to start a new channel creation flow, which is quite 682 | cumbersome. It's most of the time a better idea to use CPFP if you want to make your funding tx 683 | confirm faster. 684 | 685 | The commitment transaction can be CPFP-ed, but only by the remote node (via its main output, the 686 | revocation key or an HTLC output for which it has the preimage). All other outputs use relative 687 | timelocks, so they cannot be used for CPFP. 688 | 689 | None of the transactions can be *unilaterally* RBF-ed because they need signatures from both sides. 690 | 691 | This is quite inconvenient if you've been forced to broadcast your commitment transaction because 692 | the remote node was unresponsive and it's stuck in the mempool. It would be nice to be able to make 693 | it confirm faster, and this has been an area of active research. 694 | 695 | ### Anchor outputs 696 | 697 | The [anchor outputs proposal](https://github.com/lightningnetwork/lightning-rfc/pull/688) addresses 698 | these shortcomings by leveraging the CPFP carve-out rule and a better use of sighash flags. 699 | 700 | At a high-level, it consists of four main changes: 701 | 702 | 1. Update HTLC transactions to use `SIGHASH_SINGLE | SIGHASH_ANYONECANPAY`. This lets you RBF your 703 | HTLC transactions by adding new inputs/outputs to raise the fees. 704 | 2. Add new outputs (called `anchor outputs`) to the commitment transaction specifically for CPFP 705 | carve-out. This lets you do CPFP on a commitment transaction that's stuck in the mempool. 706 | 3. Add a relative timelock of 1 block to all outputs of the commitment transaction except the new 707 | `anchor outputs`. This ensures only these two outputs can be used for the CPFP carve-out; all 708 | other outputs cannot be used for CPFP, they have to wait for the commitment transaction to be 709 | confirmed before they can be spent. 710 | 4. Set the HTLC transactions fees to 0: this protects against a fee siphoning attack described 711 | [here](https://lists.linuxfoundation.org/pipermail/lightning-dev/2020-September/002796.html). 712 | 713 | Let's focus on the first point. An HTLC-success transaction now looks like: 714 | 715 | ```json 716 | { 717 | "version": 2, 718 | "locktime": 0, 719 | "vin": [ 720 | { 721 | "txid": "...", 722 | "vout": 42, 723 | "scriptSig": "0 ", 724 | "sequence": 1 725 | } 726 | ], 727 | "vout": [ 728 | { 729 | "value": 0.04, 730 | "scriptPubKey": " 731 | OP_IF 732 | # funds go to anyone who has the revocation key 733 | 734 | OP_ELSE 735 | # or back to us after a relative delay () 736 | `to_self_delay` 737 | OP_CHECKSEQUENCEVERIFY 738 | OP_DROP 739 | 740 | OP_ENDIF 741 | OP_CHECKSIG 742 | " 743 | } 744 | ] 745 | } 746 | ``` 747 | 748 | The only difference with the current format is the `sequence` set to `1` (instead of `0`) and that 749 | the remote signature uses `SIGHASH_SINGLE | SIGHASH_ANYONECANPAY` (but the local signature MUST use 750 | `SIGHASH_ALL` to prevent others from malleating the transaction after you broadcast it). This lets 751 | you replace the transaction with the following, without invalidating the signatures: 752 | 753 | ```json 754 | { 755 | "version": 2, 756 | "locktime": 0, 757 | "vin": [ 758 | { 759 | "txid": "...", 760 | "vout": 42, 761 | "scriptSig": "0 ", 762 | "sequence": 1 763 | }, 764 | { 765 | "txid": "...", 766 | "vout": ..., 767 | "scriptSig": "...", 768 | "sequence": ... 769 | } 770 | ], 771 | "vout": [ 772 | { 773 | "value": 0.04, 774 | "scriptPubKey": " 775 | OP_IF 776 | # funds go to anyone who has the revocation key 777 | 778 | OP_ELSE 779 | # or back to us after a relative delay () 780 | `to_self_delay` 781 | OP_CHECKSEQUENCEVERIFY 782 | OP_DROP 783 | 784 | OP_ENDIF 785 | OP_CHECKSIG 786 | " 787 | }, 788 | { 789 | "value": ..., 790 | "scriptPubKey": "..." 791 | } 792 | ] 793 | } 794 | ``` 795 | 796 | By attaching an input of amount `N` and an output of amount `M`, you are adding `N-M` fees to the 797 | transaction (you can of course attach multiple inputs/outputs). This lets you arbitrarily raise the 798 | fees and ensure the HTLC transaction gets confirmed in time. 799 | 800 | The second and third points change the format of the commitment transaction to: 801 | 802 | ```json 803 | { 804 | "version": 2, 805 | "locktime": 543210000, 806 | "vin": [ 807 | { 808 | "txid": "...", 809 | "vout": ..., 810 | "scriptSig": "0 ", 811 | "sequence": 2500123456 812 | } 813 | ], 814 | "vout": [ 815 | { 816 | "value": 0.5, 817 | "scriptPubKey": " 818 | # to_local output 819 | OP_IF 820 | # funds go to anyone who has the revocation key 821 | 822 | OP_ELSE 823 | # or back to us after a relative delay () 824 | 825 | OP_CHECKSEQUENCEVERIFY 826 | OP_DROP 827 | 828 | OP_ENDIF 829 | OP_CHECKSIG 830 | " 831 | }, 832 | { 833 | "value": 0.3, 834 | "scriptPubKey": " 835 | # to_remote output: goes back to the other channel participant after 1 block 836 | 837 | OP_CHECKSIGVERIFY 838 | 1 OP_CHECKSEQUENCEVERIFY 839 | " 840 | }, 841 | { 842 | "value": 0.00000330, 843 | "scriptPubKey": " 844 | # our anchor output: used by us to bump the fee with CPFP 845 | 846 | OP_CHECKSIG 847 | OP_IFDUP 848 | OP_NOTIF 849 | # after a relative timelock of 16 blocks, anyone can claim this tiny amount 850 | OP_16 OP_CHECKSEQUENCEVERIFY 851 | OP_ENDIF 852 | " 853 | }, 854 | { 855 | "value": 0.00000330, 856 | "scriptPubKey": " 857 | # remote anchor output: used by them to bump the fee with CPFP 858 | 859 | OP_CHECKSIG 860 | OP_IFDUP 861 | OP_NOTIF 862 | # after a relative timelock of 16 blocks, anyone can claim this tiny amount 863 | OP_16 OP_CHECKSEQUENCEVERIFY 864 | OP_ENDIF 865 | " 866 | }, 867 | { 868 | "value": 0.05, 869 | "scriptPubKey": " 870 | # A pending HTLC (payment) sent by us 871 | OP_DUP OP_HASH160 OP_EQUAL 872 | OP_IF 873 | # funds go to anyone who has the revocation key 874 | OP_CHECKSIG 875 | OP_ELSE 876 | OP_SWAP OP_SIZE 32 OP_EQUAL 877 | OP_NOTIF 878 | # funds go back to us via a second-stage HTLC-timeout transaction (which contains an absolute delay) 879 | # NB: we also need the remote signature, which prevents us from unilaterally changing the HTLC-timeout transaction 880 | OP_DROP 2 OP_SWAP 2 OP_CHECKMULTISIG 881 | OP_ELSE 882 | # funds go to the remote node if it has the payment preimage. 883 | OP_HASH160 OP_EQUALVERIFY 884 | OP_CHECKSIG 885 | OP_ENDIF 886 | # add a 1-block delay to prevent this output from being used for CPFP 887 | 1 OP_CHECKSEQUENCEVERIFY OP_DROP 888 | OP_ENDIF 889 | " 890 | }, 891 | { 892 | "value": 0.08, 893 | "scriptPubKey": " 894 | # A pending HTLC (payment) sent to us 895 | OP_DUP OP_HASH160 OP_EQUAL 896 | OP_IF 897 | # funds go to anyone who has the revocation key 898 | OP_CHECKSIG 899 | OP_ELSE 900 | OP_SWAP OP_SIZE 32 OP_EQUAL 901 | OP_IF 902 | # funds go to us via a second-stage HTLC-success transaction once we have the payment preimage 903 | # NB: we also need the remote signature, which prevents us from unilaterally changing the HTLC-success transaction 904 | OP_HASH160 OP_EQUALVERIFY 905 | 2 OP_SWAP 2 OP_CHECKMULTISIG 906 | OP_ELSE 907 | # funds go to the remote node after an absolute delay (timeout) 908 | OP_DROP OP_CHECKLOCKTIMEVERIFY OP_DROP 909 | OP_CHECKSIG 910 | OP_ENDIF 911 | # add a 1-block delay to prevent this output from being used for CPFP 912 | 1 OP_CHECKSEQUENCEVERIFY OP_DROP 913 | OP_ENDIF 914 | " 915 | }, 916 | ] 917 | } 918 | ``` 919 | 920 | If you squint really hard, you'll see that the change in the output scripts is only the addition 921 | of `1 OP_CHECKSEQUENCEVERIFY` to the outputs that were previously spendable without any delay. 922 | 923 | This ensures that each party has **exactly one output** that can be used for CPFP: the newly added 924 | anchors. This way whatever a malicious participant may do to prevent the commitment transaction 925 | from confirming in time, they can only do it by adding child transactions to their own anchor, and 926 | the honest participant always has an opportunity to leverage the CPFP carve-out rule to bump the 927 | fee at least once. 928 | 929 | The anchor outputs have a relative timelock branch that allows anyone to spend them. The reason for 930 | this is that we want to be nice to the Bitcoin layer and avoid creating many tiny UTXOs that would 931 | bloat the UTXO set. By letting anyone spend them, there's a chance they will be consolidated when 932 | fees are low. 933 | 934 | The overall transaction graph now looks like: 935 | 936 | ```ascii 937 | +------------+ 938 | | funding tx | 939 | +------------+ 940 | | 941 | | +-------------------+ 942 | +------->| commit tx B | 943 | +-------------------+ 944 | | | | | | | 945 | | | | | | | A's main output 946 | | | | | | +-----------------> to A after a 1-block relative delay 947 | | | | | | 948 | | | | | | +---> to B after relative delay 949 | | | | | | B's main output | 950 | | | | | +-----------------+ 951 | | | | | | 952 | | | | | +---> to A with revocation key 953 | | | | | 954 | | | | | A's anchor output 955 | | | | +--------------------> to A immediately (or anyone after 16-block relative delay) 956 | | | | 957 | | | | B's anchor output 958 | | | +-----------------------> to B immediately (or anyone after 16-block relative delay) 959 | | | 960 | | | (B's RBF inputs) ---+ 961 | | | | +---> to B after relative delay 962 | | | +---->+-----------------+ | 963 | | | +---------->| HTLC-timeout tx |------------+ 964 | | | HTLC offered by B | +-----------------+ | 965 | | +-------------------+ (after timeout + 1-block delay) +---> to A with revocation key 966 | | | 967 | | +---> to A with payment preimage after a 1-block relative delay 968 | | | 969 | | +---> to A with revocation key 970 | | 971 | | (B's RBF inputs) ---+ 972 | | | +---> to B after relative delay 973 | | +---->+-----------------+ | 974 | | +------------>| HTLC-success tx |----------------+ 975 | | HTLC received by B | +-----------------+ | 976 | +--------------------+ (with payment preimage + 1-block delay) +---> to A with revocation key 977 | | 978 | +---> to A after timeout (absolute delay + 1-block relative delay) 979 | | 980 | +---> to A with revocation key 981 | ``` 982 | 983 | ## RBF Pinning 984 | 985 | While the anchor outputs proposal solves the issue of a slow-to-confirm commitment transaction, it 986 | doesn't solve other issues related to transaction pinning and may even provide more attack surface 987 | to steal HTLC outputs. 988 | 989 | This [mail thread](https://lists.linuxfoundation.org/pipermail/lightning-dev/2020-April/002639.html) 990 | details these issues and starts the discussion around alternative proposals. 991 | 992 | The simplest incarnation of the attack works as follows: 993 | 994 | * The attacker (Mallory) sets up two channels with her target (Alice): `Mallory -> Alice -> Mallory` 995 | * Mallory then proceeds to send a payment to herself via these two channels 996 | * When she receives the HTLC, she stops responding and waits for the timeout, forcing Alice to 997 | publish her commitment transaction that contains an htlc-offered output 998 | * Mallory will then publish a transaction to claim that htlc output (revealing the preimage), with 999 | a low fee and RBF disabled 1000 | * If Mallory's transaction gets into miners mempools before Alice's htlc-timeout transaction, Alice 1001 | won't be able to claim the funds back because she can't replace Mallory's transaction 1002 | * If Alice isn't able to retrieve the preimage (because her own mempool contains her htlc-timeout 1003 | transaction), she will have to let the upstream htlc expire. When Mallory's transaction 1004 | eventually gets mined, Alice will have paid the htlc amount downstream but not received the 1005 | corresponding amount upstream 1006 | 1007 | Note that this attack is hard to carry out in practice: ensuring your transaction gets in more 1008 | mempools than your target's transaction without revealing the preimage to your target is a non 1009 | trivial task. But the anchor outputs proposal makes it slightly simpler than before. Without the 1010 | 1-block relative delay, Alice was able to broadcast the commitment transaction and her htlc-timeout 1011 | transaction together: this gave her a head-start to get her htlc-timeout in nodes' mempools before 1012 | Mallory. With anchor outputs she has to wait for the commitment transaction to be confirmed before 1013 | she is able to broadcast the htlc-timeout; she doesn't have a head-start anymore. 1014 | 1015 | The main reason this attack is possible is because Mallory has no constraints on how she can spend 1016 | htlc outputs in Alice's commitment transaction. The linked email thread proposes to make this more 1017 | symmetric, by only allowing Mallory to spend htlc outputs via a pre-signed transaction that requires 1018 | signatures from both participants, and adding anchor outputs to HTLC transactions. 1019 | 1020 | ## Alternative proposal 1021 | 1022 | Let's summarize our requirements and detail a proposal that combines ideas from the two previous 1023 | sections. 1024 | 1025 | Let's define the following constants (configurable by implementations): 1026 | 1027 | ```ascii 1028 | received htlc expiry offered htlc expiry 1029 | | | 1030 | | | 1031 | v v 1032 | +-----------------------------------------------------+ 1033 | cltv_expiry_delta 1034 | <-----------------------------------------------------> 1035 | fulfill_safety_delta N 1036 | <---------------------------><------------------------> 1037 | ``` 1038 | 1039 | When we broadcast our commitment transaction, we need to handle the following cases: 1040 | 1041 | * Offered HTLC times out: in that case, we want to ensure that either: 1042 | * our HTLC-timeout tx confirms in less than `N` blocks 1043 | * or we learn the HTLC preimage before `N` blocks 1044 | * Received HTLC should be fulfilled, but times out in less than `fulfill_safety_delta`. We want to 1045 | ensure that our HTLC-success tx confirms (prevent remote from spending it via the timeout branch) 1046 | 1047 | In case the remote participant broadcasts their commitment transaction, we want to ensure that: 1048 | 1049 | * If we have the preimage for a received HTLC (offered in their commitment) before the timeout, 1050 | we're able to claim the output (prevent remote from spending it via their HTLC-timeout tx) 1051 | * If an offered HTLC times out (received in their commitment), we must either: 1052 | * claim the HTLC output in less than `N` blocks 1053 | * or learn the HTLC preimage before `N` blocks 1054 | 1055 | The current transaction format lets us easily handle the second case (when the remote broadcasts 1056 | their commitment transaction), but not the first one. 1057 | 1058 | In order to leverage the CPFP carve-out rule on HTLC transactions, we need to be able to confirm 1059 | the commitment transaction quickly. That means we need the commitment transaction to have two 1060 | anchors and all other outputs with a 1-block relative timelock. 1061 | 1062 | The HTLC-timeout transaction can use `SIGHASH_SINGLE | SIGHASH_ANYONECANPAY` for the remote 1063 | signature, which lets us RBF it. The HTLC-success transaction however must use `SIGHASH_ALL` and 1064 | leverage anchor outputs to bump the fees with CPFP. A new transaction is necessary when the remote 1065 | claims an HTLC output by providing the preimage: we call it Remote-HTLC-success transaction. 1066 | It must use `SIGHASH_ALL` and have an output for each participant to allow CPFP carve-out. 1067 | No additional transaction seems required for claiming the timeout branch of a received HTLC. 1068 | 1069 | The trick to protect against a malicious participant that broadcasts a low-fee HTLC-success or 1070 | Remote-HTLC-success transaction is that we can always blindly do a CPFP carve-out on them; we know 1071 | their txid (because they use `SIGHASH_ALL`) so if we observe that our HTLC-timeout (or our claim of 1072 | the timeout branch of a received HTLC) doesn't confirm, we can try to broadcast a transaction that 1073 | spends our (potential) anchor output on the success transaction. The goal is to make it confirm 1074 | quickly if it exists so that we learn the preimage and can adapt our upstream behavior in time. 1075 | 1076 | ```ascii 1077 | +------------+ 1078 | | funding tx | 1079 | +------------+ 1080 | | 1081 | | +-------------------+ 1082 | +------->| commit tx B | 1083 | +-------------------+ 1084 | | | | | | | 1085 | | | | | | | A's main output 1086 | | | | | | +-----------------> to A after a 1-block relative delay 1087 | | | | | | 1088 | | | | | | +---> to B after relative delay 1089 | | | | | | B's main output | 1090 | | | | | +-----------------+ 1091 | | | | | | 1092 | | | | | +---> to A with revocation key 1093 | | | | | 1094 | | | | | A's anchor output 1095 | | | | +--------------------> to A immediately (or anyone after 16-block relative delay) 1096 | | | | 1097 | | | | B's anchor output 1098 | | | +-----------------------> to B immediately (or anyone after 16-block relative delay) 1099 | | | 1100 | | | (B's RBF inputs) ---+ 1101 | | | | +---> to B after relative delay 1102 | | | +---->+-----------------+ | 1103 | | | +---------->| HTLC-timeout tx |------------+ 1104 | | | HTLC offered by B | +-----------------+ | 1105 | | +-------------------+ (after timeout + 1-block delay) +---> to A with revocation key 1106 | | | 1107 | | | +------------------------+ 1108 | | +---------->| Remote-HTLC-success tx | 1109 | | | +------------------------+ 1110 | | | (with payment preimage + 1-block delay) 1111 | | | | | 1112 | | | | | A's output 1113 | | | | +-----------------> to A immediately (or anyone after 16-block relative delay) 1114 | | | | 1115 | | | | B's anchor output 1116 | | | +--------------------> to B immediately (or anyone after 16-block relative delay) 1117 | | | 1118 | | +---> to A with revocation key 1119 | | 1120 | | +-----------------+ 1121 | | +------------>| HTLC-success tx | 1122 | | HTLC received by B | +-----------------+ 1123 | +--------------------+ (with payment preimage + 1-block delay) 1124 | | | | | +---> to A with revocation key 1125 | | | | | B's output | 1126 | | | | +---------------------+---> to B after relative delay 1127 | | | | 1128 | | | | A's anchor output 1129 | | | +--------------------> to A immediately (or anyone after 16-block relative delay) 1130 | | | 1131 | | | B's anchor output 1132 | | +-----------------------> to B immediately (or anyone after 16-block relative delay) 1133 | | 1134 | +---> to A after timeout (absolute delay + 1-block relative delay) 1135 | | 1136 | +---> to A with revocation key 1137 | ``` 1138 | 1139 | Notes: 1140 | 1141 | * This raises quite significantly the minimum HTLC value that is economical to enforce on-chain, 1142 | which is quite sad, and it makes the transactions more complex/costly 1143 | * The blind CPFP carve-out is a one shot, so you'll likely need to pay a lot of fees for it to work 1144 | which still makes you lose money in case an attacker targets you (but the money goes to miners, 1145 | not to the attacker - unless he is the miner). It's potentially hard to estimate what fee you 1146 | should put into that blind CPFP carve-out because you have no idea what the current fee of the 1147 | success transaction package is (if the attacker created a long chain of unconfirmed transactions) 1148 | * If we take a step back, the only attack we need to protect against is an attacker pinning a 1149 | preimage transaction while preventing us from learning that preimage for at least `N` blocks. 1150 | If we have: 1151 | * a high enough `cltv_expiry_delta` (and thus a high enough `N` value) 1152 | * [off-chain preimage broadcast](https://github.com/lightningnetwork/lightning-rfc/issues/783) 1153 | * LN hubs (or any party commercially investing in running a lightning node) participating in 1154 | various mining pools to help discover preimages 1155 | * decent mitigations for eclipse attacks 1156 | * then the official anchor outputs proposal should be safe enough? 1157 | 1158 | ## Resources 1159 | 1160 | * [Bolt 3](https://github.com/lightningnetwork/lightning-rfc/blob/master/03-transactions.md) 1161 | * [SIGHASH_NOINPUT](https://github.com/bitcoin/bips/blob/master/bip-0118.mediawiki) 1162 | * [SIGHASH_ANYPREVOUT](https://github.com/ajtowns/bips/blob/bip-anyprevout/bip-anyprevout.mediawiki) 1163 | * [OP_CHECKLOCKTIMEVERIFY](https://github.com/bitcoin/bips/blob/master/bip-0065.mediawiki) 1164 | * [nSequence](https://github.com/bitcoin/bips/blob/master/bip-0068.mediawiki) 1165 | * [OP_CHECKSEQUENCEVERIFY](https://github.com/bitcoin/bips/blob/master/bip-0112.mediawiki) 1166 | * [Opt-in RBF](https://github.com/bitcoin/bips/blob/master/bip-0125.mediawiki) 1167 | * [CPFP carve-out](https://bitcoinops.org/en/topics/cpfp-carve-out/) 1168 | * [Anchor Outputs](https://github.com/lightningnetwork/lightning-rfc/pull/688) 1169 | * [Transaction Pinning](https://lists.linuxfoundation.org/pipermail/lightning-dev/2020-April/002639.html) 1170 | -------------------------------------------------------------------------------- /pinning-attacks.md: -------------------------------------------------------------------------------- 1 | # Pinning Attacks 2 | 3 | This article summarizes the discussions about pinning attacks (discussed 4 | [here](https://lists.linuxfoundation.org/pipermail/lightning-dev/2020-April/002639.html) and 5 | [here](https://lists.linuxfoundation.org/pipermail/lightning-dev/2020-June/002758.html)) and ideas 6 | that have been proposed to mitigate this class of attacks. 7 | 8 | ## Table of Contents 9 | 10 | * [Threat Model](#threat-model) 11 | * [Attacks on Lightning](#attacks-on-lightning) 12 | * [Attacking individual HTLCs](#attacking-individual-htlcs) 13 | * [Attacking commitment transactions](#attacking-commitment-transactions) 14 | * [Anchor outputs](#anchor-outputs) 15 | * [Mitigations](#mitigations) 16 | * [Update fee must stay](#update-fee-must-stay) 17 | * [Spamming the bitcoin network](#spamming-the-bitcoin-network) 18 | * [Pay for preimage](#pay-for-preimage) 19 | * [Out of band package relay](#out-of-band-package-relay) 20 | * [Insert your ideas here](#insert-your-ideas-here) 21 | 22 | ## Threat Model 23 | 24 | In Bitcoin, "There Ain't No Such Thing As A Global Mempool" (TANSTAAGM - credits to Z-man). 25 | Bitcoin will not try to enforce mempool convergence nor try to resolve mempool [split-brains](https://en.wikipedia.org/wiki/Split-brain_(computing)). 26 | These split-brain occurences are slowly and partially resolved by getting some of the mempool 27 | transactions confirmed in blocks: that is and will always be the only consensus-enforced data 28 | structure available. 29 | 30 | A clever and well-funded attacker is able to manipulate mempools and create arbitrary split-brains, 31 | that last an arbitrary amount of time. 32 | We must work under the assumption that such attackers are able to accurately split the network's 33 | mempools, ensuring for example that N% of miners' mempool contain a transaction txA while the rest 34 | of the network's mempools all contain a conflicting transaction txB. 35 | 36 | Lightning, as well as other off-chain contracts, must ensure that users don't suffer a loss of 37 | funds from such mempool partitions. 38 | 39 | ## Attacks on Lightning 40 | 41 | In this threat model, there are two types of attacks that can be carried out: attacks on individual 42 | HTLC transactions and attacks on commitment transactions. The goal of both of these attacks is to 43 | steal pending HTLCs (HTLC outputs in the broadcast commitment transaction), exploiting a routing 44 | node by timing out HTLCs upstream while collecting them on-chain downstream. 45 | 46 | ```ascii 47 | Attacker -----------------------> Victim ----------------------------> Attacker 48 | (upstream) ^ ^ (downstream) 49 | | | 50 | | | 51 | +---------------------------+ +------------------------+ 52 | | HTLCs timed out off-chain | | HTLCs claimed on-chain | 53 | +---------------------------+ +------------------------+ 54 | 55 | ``` 56 | 57 | Note that none of these attacks are able to steal participants' main outputs, only HTLCs. 58 | A general mitigation is thus to limit the number of pending HTLCs in the commitment transaction, 59 | and limit the amount pending across those HTLCs. Existing Lightning implementations already offer 60 | ways to configure these limits. 61 | 62 | These attacks cannot be used to steal from wallets either, since they don't relay payments. 63 | 64 | ### Attacking individual HTLCs 65 | 66 | This attack works at the HTLC transaction level. The attacker creates the following mempool 67 | split-brain: 68 | 69 | * all miners have a success transaction in their mempool, revealing the preimage to claim the HTLC 70 | * the rest of the network has a timeout transaction in their mempool 71 | 72 | The attacker ensures the preimage transaction has a low enough feerate to be kept in the mempool 73 | without confirming before the upstream channel can timeout them off-chain. 74 | 75 | The attacker can also ensure that the transaction in the miners' mempool cannot be replaced, by 76 | attaching a long enough chain of child transactions (BIP 125 rule 5). 77 | 78 | This can be done: 79 | 80 | * With the current commitment format (no anchor outputs), by forcing the victim to broadcast their 81 | commitment since the htlc preimage branch has no restriction on how it's spent. 82 | * With anchor outputs, either with the same solution as above, or by adding outputs to the 83 | HTLC-success transaction (thanks to `SIGHASH_SINGLE | SIGHASH_ANYONECANPAY`). 84 | 85 | There are two ways the victim can defend against this attack: 86 | 87 | * learn the preimage before the upstream HTLC times out 88 | * or get his timeout transaction confirmed 89 | 90 | ### Attacking commitment transactions 91 | 92 | This attack works at the commitment transaction level, and thus impacts all HTLCs outputs in that 93 | transaction. The attacker creates the following mempool split-brain: 94 | 95 | * all miners have one version of the commitment transaction 96 | * the rest of the network has another version of the commitment transaction 97 | 98 | Note that there are variants of this attack where the network can be arbitrarily split into N 99 | clusters, each with a different version of the commitment transaction. At a high level, this 100 | achieves the same result and mitigations should address this whole class of attacks. 101 | 102 | The attacker ensures the commitment transaction in the miners' mempools has a low enough feerate to 103 | be kept without confirming before the upstream channel can timeout HTLCs off-chain. 104 | 105 | The attacker can also ensure that the transaction in the miners' mempool cannot be replaced: 106 | 107 | * With the current commitment format (no anchor outputs), this can be done by using a commitment 108 | transaction with a feerate at least equal to the victim's latest commitment, since the victim 109 | cannot bump the fees of his own commitment transaction. 110 | * With anchor outputs, this can be done by attaching a long enough chain of child transactions via 111 | the attacker's anchor (BIP 125 rule 5). 112 | 113 | The only way the victim can defend against this attack is by somehow getting a commitment 114 | transaction confirmed. It doesn't matter which one is confirmed: if it's a revoked commitment, the 115 | victim can claim all the channels funds (payback time, b*tches), if it's the latest commitment the 116 | victim has to claim or timeout HTLCs afterwards. 117 | 118 | ## Anchor outputs 119 | 120 | The [anchor outputs proposal](https://github.com/lightningnetwork/lightning-rfc/pull/688) doesn't 121 | fix this class of attacks, but it doesn't make the situation worse. See the two previous sections 122 | for details. 123 | 124 | It solves another class of attacks, so I believe it makes sense to implement today (regardless of 125 | potential future commitment changes once bitcoin offers some kind of package relay). 126 | 127 | ## Mitigations 128 | 129 | First of all, let's clarify that CPFP/carve-out cannot save us in that case. Without package relay, 130 | CPFP will not help our valid transaction propagate all the way to miners' mempools. And even if you 131 | knew what transaction is in the miners' mempools somehow and wanted to use CPFP/carve-out to get 132 | that transaction to confirm (which unblocks the situation) you cannot propagate your carve-out to 133 | miners because your area of the network doesn't have the transaction from which you're carving out 134 | in their mempools, so they won't relay anything. 135 | 136 | A long-term mitigation is to deploy some form of package relay on the bitcoin network that would 137 | allow us to send a package "our valid tx + a child that bumps fee" that would always be able to 138 | replace the attacker's pinned transaction (as long as our package pays enough fees). This is not 139 | an easy task and it will take time, so we will now explore some short-term mitigations. 140 | 141 | Disclaimer: most of these (clever) ideas are not mine. I'm merely trying to summarize them to help 142 | the discussion move forward. 143 | 144 | ### Update fee must stay 145 | 146 | The current `update_fee` mechanism is clearly imperfect; it's impossible to predict the future. 147 | But it does raise the bar for the commitment transaction pinning attack. If you ensure commitment 148 | transactions you sign always pay a high fee, the attacker can only keep it pinned in miners' 149 | mempools during high mempool congestion. If your `cltv_expiry_delta` is high enough, the attacker's 150 | commitment transaction is likely to get confirmed, which thwarts the attack (especially if it's a 151 | revoked commitment transaction that confirms). 152 | 153 | This doesn't mitigate the attack on HTLC preimage transactions though, because those have a feerate 154 | unilaterally set by the attacker. 155 | 156 | ### Spamming the bitcoin network 157 | 158 | Since the root of the issue is that we're missing information that some mempools have, the most 159 | obvious solution is to connect to everyone available (ie every bitcoin node that accepts incoming 160 | connections). It allows a node to discover conflicting transactions and either learn a preimage 161 | or figure out what CPFP transaction it needs to send to speed up confirmation of a pinned 162 | commitment transaction. 163 | 164 | Obviously this solution doesn't scale and may potentially not work; you have no guarantee that you 165 | will be able to connect to enough nodes to probe mempools quickly enough (before upstream HTLCs 166 | timeout). 167 | 168 | NB: this solution would also require a small change to `bitcoind`. LN nodes will need their 169 | `bitcoind` to send them conflicting transactions that match a given format. When the LN node 170 | receives such transactions, it can then act on them (extract preimage / commitment transaction). 171 | 172 | ### Pay for preimage 173 | 174 | When we detect that our HTLC-timeout doesn't confirm in time, we can incentivize random nodes to 175 | discover and share preimages by giving them a reward. 176 | 177 | This can come in three forms: 178 | 179 | * Broadcast pay-for-preimage transactions on-chain hoping they'll be claimed and you learn the 180 | preimage in a block (`OP_SHA256 OP_EQUAL`) 181 | * Send probe HTLCs off-chain to random nodes; if these nodes know the preimage, they will claim 182 | the HTLC even though they didn't create a matching invoice 183 | * Rely on altruistic off-chain gossip of discovered preimages (we can rate-limit that gossip based 184 | on the channel capacity our peer opened to us to avoid making this a DoS vector) 185 | 186 | These solutions all assume that nodes watch for mempool conflicts and analyze the conflicting 187 | transactions to discover preimages (see previous section). These solutions only mitigate the attack 188 | on individual HTLCs, not the one on commitment transactions. 189 | 190 | ### Out of band package relay 191 | 192 | Another mitigation that could work for both attacks is to implement a limited package relay outside 193 | of the bitcoin p2p relay. If (some) miners pick up these packages and manually (to be defined) 194 | replace the conflicting transactions with the high-fee package received, that allows the honest 195 | participant to get his transactions confirmed in time. As long as the fees are higher, miners have 196 | an economic incentive to select these transactions. 197 | 198 | There are many out-of-band medium that can be used to propagate these packages, for example: 199 | 200 | * Using LN gossip (where we can rate-limit based on our peer's channel capacity). This assumes that 201 | (some) miners will run a lightning node and receive that gossip. 202 | * Using centralized APIs that miners would connect to over Tor. Lightning nodes with many funds at 203 | risk can expose web servers that serve these high-fee packages when they need to broadcast them. 204 | Miners could regularly poll these servers and pick transactions they like. 205 | * Using publicly advertised bitcoin nodes that miners could connect to. The drawback is that it 206 | attracts DoS attacks (same for the centralized APIs). 207 | 208 | This would require a few changes on Bitcoin Core. There is currently no RPC that lets the user 209 | evict transactions from the mempool (and replace them with a different package); this could be 210 | useful addition. Bitcoin Core could also provide a whitelist-only flag that would let miners 211 | blindly accept conflicting transactions from chosen nodes (this assumes the miners trust these 212 | nodes). 213 | 214 | ### Insert your ideas here 215 | 216 | 217 | 218 | ## Resources 219 | 220 | Thanks to David Harding, Matt Corallo, Antoine Riard and ZmnSCPxj for their patience, their 221 | explanations and lengthy discussions and brainstorms! 222 | 223 | The following links may be useful to dig further: 224 | 225 | * [Opt-in RBF](https://github.com/bitcoin/bips/blob/master/bip-0125.mediawiki) 226 | * [OG RBF pinning thread](https://lists.linuxfoundation.org/pipermail/lightning-dev/2020-April/002639.html) 227 | * [Summary RBF pinning thread](https://lists.linuxfoundation.org/pipermail/lightning-dev/2020-June/002758.html) 228 | -------------------------------------------------------------------------------- /schnorr.md: -------------------------------------------------------------------------------- 1 | # Schnorr Wizardry 2 | 3 | Bitcoin added support for schnorr signatures with the Taproot update, which activated at block 709 632. 4 | In this article, we dive into how it works and some of the advanced schemes it unlocks. 5 | 6 | ## Table of Contents 7 | 8 | * [Schnorr signatures](#schnorr-signatures) 9 | * [Linearity of Schnorr signatures](#linearity-of-schnorr-signatures) 10 | * [Adaptor signatures](#adaptor-signatures) 11 | * [Musig2](#musig2) 12 | * [Musig2 adaptor signatures](#musig2-adaptor-signatures) 13 | * [Musig2 BIP 32 derivation](#musig2-bip-32-derivation) 14 | 15 | ## Schnorr signatures 16 | 17 | Schnorr signatures are specified in [BIP 340](https://github.com/bitcoin/bips/blob/master/bip-0340.mediawiki). 18 | Ignoring many details described in the BIP, at a high level the signing algorithm works as follows: 19 | 20 | ```text 21 | P = k*G -> signer's public key 22 | m -> message to sign 23 | 24 | Sign: 25 | r = {0;1}^256 -> random nonce 26 | R = r*G 27 | e = H(R || P || m) 28 | s = r + e*k 29 | (s, R) -> message signature 30 | 31 | Verify: 32 | e = H(R || P || m) 33 | R' = s*G - e*P 34 | If R = R', the signature is valid 35 | ``` 36 | 37 | ## Linearity of Schnorr signatures 38 | 39 | A very interesting property of schnorr signatures compared to ECDSA signatures is that they make it easy to combine signatures for a given message if we slightly change the signing algorithm. 40 | 41 | ```text 42 | A = a*G -> Alice's public key 43 | B = b*G -> Bob's public key 44 | P = A + B -> combined public key 45 | m -> message to sign 46 | 47 | Sign: 48 | ra = {0;1}^256 -> random nonce generated by Alice 49 | RA = ra*G -> public partial nonce sent by Alice to Bob 50 | rb = {0;1}^256 -> random nonce generated by Bob 51 | RB = rb*G -> public partial nonce sent by Bob to Alice 52 | R = RA + RB -> public nonce 53 | e = H(R || P || m) 54 | sA = ra + e*a -> partial signature produced by Alice 55 | sB = rb + e*b -> partial signature produced by Bob 56 | s = sA + sB 57 | (s, R) -> combined message signature 58 | 59 | Verify: 60 | e = H(R || P || m) 61 | R' = s*G - e*P 62 | If R = R', the signature is valid 63 | ``` 64 | 65 | You should notice that the verification algorithm hasn't changed. 66 | This means that the verifier doesn't even know that multiple signers were involved: the signature looks like it comes from a standard single signer. 67 | 68 | :warning: This signing scheme is not secure when Alice or Bob is malicious. We will describe a secure signing scheme in the Musig2 section below. 69 | 70 | ## Adaptor signatures 71 | 72 | The linearity of schnorr signatures also allows revealing a secret through a signature. 73 | 74 | ```text 75 | P = k*G -> signer's public key 76 | T = t*G -> tweak (t is the secret that will be revealed) 77 | m -> message to sign 78 | 79 | Sign: 80 | r = {0;1}^256 81 | R = r*G 82 | e = H(R + T || P || m) -> notice that we tweak the nonce here with T 83 | s = r + e*k -> but we don't tweak it here with t 84 | (s, R, T) -> adaptor signature: will automatically reveal t when a valid signature for nonce R + T is produced 85 | 86 | Verify: 87 | e = H(R + T || P || m) 88 | R' = s*G - e*P 89 | If R = R', the adaptor signature is valid 90 | Note that (s, R) or (s, R + T) are not valid schnorr signatures 91 | 92 | Complete: 93 | s' = s + t 94 | R' = R + T 95 | (s', R') -> valid schnorr signature 96 | 97 | Extract: 98 | e' = H(R' || P || m) 99 | R'' = s'*G - e'*P 100 | If R'' = R', the signature is valid 101 | t = s' - s 102 | The verifier has learnt t through the schnorr signature 103 | ``` 104 | 105 | NB: for this to work, the verifier must ensure that the nonce `R + T` is fixed beforehand. 106 | Otherwise the signer may create a valid signature for an unrelated nonce, which would not reveal the secret `t`. 107 | This is most useful when combined with Musig2, where participants commit to the nonce before signing. 108 | 109 | Adaptor signatures can also be used in the opposite way. 110 | If the signer doesn't know the secret `t`, it can produce an adaptor signature. 111 | Then another participant that knows `t` can convert that adaptor signature to a valid signature. 112 | 113 | ## Musig2 114 | 115 | [Musig2](https://eprint.iacr.org/2020/1261.pdf) is a secure scheme for combining multiple signatures into a single schnorr signature. 116 | It only needs two rounds of communications between participants, and the first round can be done ahead of time (independently of the message to sign). 117 | The novel idea in that scheme is to use multiple nonces for each participant and combine them in a smart way to produce the final nonce. 118 | This results in an elegant scheme that looks very similar to standard schnorr signing. 119 | 120 | ```text 121 | PA = pa*G -> public key of participant A 122 | PB = pb*G -> public key of participant B 123 | L = (PA, PB) -> sorted list of participants public keys 124 | P = H(H(L) || PA)*PA + PB -> combined public key 125 | 126 | NonceGenA (run by participant A): 127 | ra1 = {0;1}^256 128 | ra2 = {0;1}^256 129 | RA1 = ra1*G 130 | RA2 = ra2*G 131 | 132 | NonceGenB (run by participant B): 133 | rb1 = {0;1}^256 134 | rb2 = {0;1}^256 135 | RB1 = rb1*G 136 | RB2 = rb2*G 137 | 138 | NonceExchange (communication round 1): 139 | Participant A sends RA1, RA2 to participant B 140 | Participant B sends RB1, RB2 to participant A 141 | 142 | SignA (run by participant A): 143 | x = H(P || RA1 + RB1 || RA2 + RB2 || m) 144 | R = RA1 + RB1 + x*(RA2 + RB2) 145 | ra = ra1 + x*ra2 146 | e = H(R || P || m) 147 | sa = ra + e*H(L || PA)*pa 148 | (sa, R) -> participant A's partial signature 149 | 150 | SignB (run by participant B): 151 | x = H(P || RA1 + RB1 || RA2 + RB2 || m) 152 | R = RA1 + RB1 + x*(RA2 + RB2) 153 | rb = rb1 + x*rb2 154 | e = H(R || P || m) 155 | sb = rb + e*pb 156 | (sb, R) -> participant B's partial signature 157 | 158 | Combine (communication round 2): 159 | s = sa + sb 160 | (s, R) -> valid schnorr signature for public key P 161 | 162 | Verify: 163 | e = H(R || P || m) 164 | R' = s*G - e*P 165 | = (sa + sb)*G - e*P 166 | = (ra + e*H(L || PA)*pa)*G + (rb + e*pb)*G - e*P 167 | = (ra + rb)*G + e*(H(L || PA)*pa + pb)*G - e*P 168 | = R + e*P - e*P 169 | = R 170 | -> this is a valid schnorr signature 171 | ``` 172 | 173 | NB: we used only two participants to simplify the example, but Musig2 works with any number of participants. 174 | 175 | ## Musig2 adaptor signatures 176 | 177 | Musig2 can be combined with adaptor signatures: 178 | 179 | ```text 180 | # The first round (pre-computing nonces) is vanilla Musig2 181 | 182 | PA = pa*G -> public key of participant A 183 | PB = pb*G -> public key of participant B 184 | L = (PA, PB) -> sorted list of participants public keys 185 | P = H(H(L) || PA)*PA + PB -> combined public key 186 | 187 | NonceGenA (run by participant A): 188 | ra1 = {0;1}^256 189 | ra2 = {0;1}^256 190 | RA1 = ra1*G 191 | RA2 = ra2*G 192 | 193 | NonceGenB (run by participant B): 194 | rb1 = {0;1}^256 195 | rb2 = {0;1}^256 196 | RB1 = rb1*G 197 | RB2 = rb2*G 198 | 199 | NonceExchange (communication round 1): 200 | Participant A sends RA1, RA2 to participant B 201 | Participant B sends RB1, RB2 to participant A 202 | 203 | # The second round simply tweaks the combined nonce with the secret 204 | 205 | T = t*G -> secret t known only by B 206 | 207 | SignA (run by participant A): 208 | x = H(P || RA1 + RB1 + T || RA2 + RB2 || m) 209 | R = RA1 + RB1 + x*(RA2 + RB2) 210 | ra = ra1 + x*ra2 211 | e = H(R + T || P || m) 212 | sa = ra + e*H(L || PA)*pa 213 | (sa, R + T) -> participant A's partial signature 214 | 215 | SignB (run by participant B): 216 | x = H(P || RA1 + RB1 + T || RA2 + RB2 || m) 217 | R = RA1 + RB1 + x*(RA2 + RB2) 218 | rb = rb1 + x*rb2 219 | e = H(R + T || P || m) 220 | sb = rb + e*pb 221 | (sb, R, T) -> participant B's adaptor signature 222 | 223 | Participant A can verify participant B's adaptor signature before sending its partial signature: 224 | (sa + sb)*G must be equal to R + H(R + T || P || m)*P 225 | -> NB: it's not a valid schnorr signature, notice the mismatch between R (outside of the hash) and R + T (inside the hash) 226 | 227 | Complete (run by participant B): 228 | s = sa + sb + t 229 | R' = R + T 230 | (s, R') -> valid schnorr signature for public key P and nonce R + T 231 | 232 | Extract (run by participant A): 233 | t = s - sa - sb 234 | ``` 235 | 236 | ## Musig2 BIP 32 derivation 237 | 238 | Musig2 can be used with [BIP 32](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki) derivation. 239 | The trick is that the individual keys will not change, we're only tweaking the aggregated public key. 240 | 241 | ```text 242 | PA = pa*G -> public key of participant A 243 | PB = pb*G -> public key of participant B 244 | L = (PA, PB) -> sorted list of participants public keys 245 | P = H(H(L) || PA)*PA + PB -> combined master public key 246 | Both participants agree on a chaincode c 247 | 248 | The combined public key at index i can be computed: 249 | I = H(c, P || i) 250 | IL = I[0:32] 251 | IR = I[33:64] 252 | Pi = P + IL*G 253 | ci = IR 254 | 255 | Participants create partial signatures for this child combined public key with the following steps. 256 | These are the same steps as vanilla Musig2 with Pi instead of P. 257 | 258 | NonceGenA (run by participant A): 259 | ra1 = {0;1}^256 260 | ra2 = {0;1}^256 261 | RA1 = ra1*G 262 | RA2 = ra2*G 263 | 264 | NonceGenB (run by participant B): 265 | rb1 = {0;1}^256 266 | rb2 = {0;1}^256 267 | RB1 = rb1*G 268 | RB2 = rb2*G 269 | 270 | NonceExchange (communication round 1): 271 | Participant A sends RA1, RA2 to participant B 272 | Participant B sends RB1, RB2 to participant A 273 | 274 | SignA (run by participant A): 275 | x = H(Pi || RA1 + RB1 || RA2 + RB2 || m) 276 | R = RA1 + RB1 + x*(RA2 + RB2) 277 | ra = ra1 + x*ra2 278 | e = H(R || Pi || m) 279 | sa = ra + e*H(L || PA)*pa 280 | (sa, R) -> participant A's partial signature 281 | 282 | SignB (run by participant B): 283 | x = H(Pi || RA1 + RB1 || RA2 + RB2 || m) 284 | R = RA1 + RB1 + x*(RA2 + RB2) 285 | rb = rb1 + x*rb2 286 | e = H(R || Pi || m) 287 | sb = rb + e*pb 288 | (sb, R) -> participant B's partial signature 289 | 290 | Combine (communication round 2): 291 | e = H(R || Pi || m) -> this step can be done with anyone able to compute this 292 | s = sa + sb + e*IL 293 | (s, R) -> valid schnorr signature for public key Pi 294 | 295 | Verify: 296 | e = H(R || Pi || m) 297 | R' = s*G - e*Pi 298 | = (sa + sb + e*IL)*G - e*Pi 299 | = (ra + e*H(L || PA)*pa)*G + (rb + e*pb)*G + e*IL*G - e*Pi 300 | = (ra + rb)*G + e*(H(L || PA)*pa + pb + IL)*G - e*Pi 301 | = R + e*Pi - e*Pi 302 | = R 303 | -> this is a valid schnorr signature 304 | ``` 305 | -------------------------------------------------------------------------------- /spam-prevention.md: -------------------------------------------------------------------------------- 1 | # Spamming the Lightning Network 2 | 3 | One of the Lightning Network's main goals is to provide good privacy for payers and payees, thanks 4 | to the combination of source-routing and onion encryption ([Sphinx](http://www.cypherpunks.ca/~iang/pubs/Sphinx_Oakland09.pdf)). 5 | 6 | Unfortunately, this property can be abused by malicious actors to spam the network: intermediate 7 | routing nodes cannot easily figure out if the payments they are relaying are genuine payments or 8 | spamming attempts. 9 | 10 | An evil routing node can use this property to ensure that its competitors' channels are unable to 11 | route payments: this may force payers to route through the evil node's channels instead, earning 12 | him fees and potentially making it economically unsustainable for his competitors. An even more 13 | evil entity could make the whole public lightning network unusable if it has access to a fraction 14 | of the network's capacity. 15 | 16 | ## Table of Contents 17 | 18 | * [Description of the attack](#description-of-the-attack) 19 | * [Mitigation strategies available today](#mitigation-strategies-available-today) 20 | * [Threat model](#threat-model) 21 | * [Proposals](#proposals) 22 | * [Provable Blaming](#provable-blaming) 23 | * [Local Reputation Tracking](#local-reputation-tracking) 24 | * [Naive upfront payment](#naive-upfront-payment) 25 | * [Reverse upfront payment](#reverse-upfront-payment) 26 | * [Bidirectional upfront payment](#bidirectional-upfront-payment) 27 | * [Hold-time-dependent bidirectional upfront payment](#hold-time-dependent-bidirectional-upfront-payment) 28 | * [Web of trust HTLC hold fees](#web-of-trust-htlc-hold-fees) 29 | 30 | ## Description of the attack 31 | 32 | The attacker leverages the HTLC-timeout mechanism to lock up liquidity in the network. 33 | This attack doesn't directly cost money to routing nodes, but it wastes capital allocation and may 34 | prevent legitimate payments from going through. 35 | 36 | The attacker controls two nodes: `A1` and `A2` (we'll refer to this attack as `controlled spam`). 37 | The attackers finds a long route between `A1` and `A2`, sends HTLCs through these routes and goes 38 | silent on the recipient's end (simulates a stuck HTLC): 39 | 40 | ```text 41 | A1 ---htlc1---> Some node ---> ... ---> Some node ---> A2 42 | A1 ---htlc2---> Some node ---> ... ---> Some node ---> A2 43 | ... 44 | A1 ---htlcN---> Some node ---> ... ---> Some node ---> A2 45 | ``` 46 | 47 | The intermediate nodes notice that the HTLCs seem stuck *somewhere downstream*, but: 48 | 49 | * their only choice is to wait for the HTLCs to timeout, otherwise they risk losing funds 50 | * they cannot know the final destination of the payment, nor its origin 51 | * they cannot blame their direct peers, they may or may not be the attacker 52 | * they cannot know that these HTLCs are related 53 | 54 | When the HTLCs are close to timing out, the attacker fails them from `A2` and repeats the same 55 | process. The only cost to the attacker is that he needs to lock the HTLC amounts, but he gets the 56 | funds back immediately when he fails the HTLCs from `A2`. 57 | 58 | Since payment routes can be at most 20 hops, it looks like the attacker can lock 20 times the funds 59 | he's allocating to the attack. But in reality it's worse: there is a limit to the number of pending 60 | HTLCs a channel can have (by default 483 HTLCs). By completely filling a channel with tiny HTLCs 61 | (just above the dust limit) the attacker is able to lock the whole channel down at a very small cost. 62 | 63 | Note that the attacker may use the same node on both ends (`A1 = A2`). 64 | 65 | Also note that the attacker doesn't necessarily need to hold the HTLCs for a very long time; he can 66 | release them and repeat the same process instantly, or keep a constant stream of HTLCs to flood the 67 | network; we'll call this attack `short-lived controlled spam`. 68 | 69 | There is another variant of this attack that is worth considering. Instead of sending to a node he 70 | controls (`A2`), the attacker sends HTLCs to random nodes he does *not* control. These final nodes 71 | will instantly fail the HTLC (because it doesn't match any invoice in their DB) but the HTLCs will 72 | spend some time locked in channels commitments due to forwarding delays. The attacker can flood the 73 | network with a constant stream of such HTLCs to disrupt legitimate payments. We'll call this attack 74 | `uncontrolled spam`. 75 | 76 | ## Mitigation strategies available today 77 | 78 | It is not possible today to fully prevent this type of attacks, but we can make the attacker's job 79 | harder by properly configuring channels: 80 | 81 | * the attacker needs to lock at least `htlc_minimum_msat * max_accepted_htlcs` of his own funds to 82 | completely fill a channel, so you should use a reasonable value for `htlc_minimum_msat` (1 sat is 83 | **not** a reasonable value for channels with a big capacity; it may be ok for smaller channels 84 | though) 85 | * open redundant unannounced channels to your most profitable peers 86 | * implement relaying policies to avoid filling up channels: always keep X% of your HTLC slots 87 | available, reserved for high-value HTLCs 88 | 89 | Long-lived controlled spams might also be mitigated by a relay policy rejecting too far in the 90 | future CLTV locktime or requiring a lower `cltv_expiry_delta`. This later mitigation may downgrade 91 | relay node security. 92 | 93 | ## Threat model 94 | 95 | We want to defend against attackers that have the following capabilities: 96 | 97 | * they are able to quickly open channels to any node in the network 98 | * they have up-to-date knowledge of the network's *public* topology 99 | * they are running modified (malicious) versions of LN node implementations 100 | * they are able to quickly create many seemingly unrelated nodes 101 | * they may already have long-lived channels (good reputation) 102 | * they might probe in real-time channel balances to adjust their spams 103 | * they might send long-held HTLCs that are indistinguishable from honest long-held HTLCs 104 | 105 | There are important properties of Lightning that we must absolutely preserve: 106 | 107 | * payer and payee's anonymity 108 | * trustless payments 109 | * minimal (reasonable) barrier to entry as routing node 110 | * minimal overhead/cost for legitimate payments 111 | * minimal overhead to declare public paths to the network 112 | * incentive to successfully relay payments 113 | 114 | And we must avoid creating opportunities for attackers to: 115 | 116 | * penalize an honest node's relationship with its own honest peers 117 | * make routing nodes lose non-negligible funds 118 | * steal money (even tiny amounts) from honest senders 119 | * more easily discover their position in a payment path 120 | * introduce third-party channel closure vectors (e.g Alice closing a channel between Bob and Caroll) 121 | 122 | ## Proposals 123 | 124 | Many ideas have been proposed over the years, exploring different trade-offs. 125 | We summarize them here with their pros and cons to help future research progress. 126 | 127 | ### Provable Blaming 128 | 129 | The oldest [proposal](https://lists.linuxfoundation.org/pipermail/lightning-dev/2015-August/000135.html) discusses 130 | to provide proof of channel closures in case of misbehaving peers not failing/succeeding HTLC 131 | quickly. E.g with Alice sending a HTLC to Caroll through Bob, if Caroll doesn't respond within a 132 | short amount of time, Bob should close his channel with her and present the closing transaction 133 | as a proof to Alice to clear himself from the routing failure. 134 | 135 | This scheme introduces a diverse set of concernes : requirement to understand channel types across 136 | links, privacy breakage, channel frailty, ... 137 | 138 | ### Local Reputation Tracking 139 | 140 | This [proposal](https://lists.linuxfoundation.org/pipermail/lightning-dev/2018-May/001232.html) discusses 141 | a reputation system for nodes. A node will keep a real-time accounting of its routing fees earned 142 | thanks to the relayed HTLCs from or to its neighboring peers. After every routing failure, faultive 143 | peer reputation is downgraded until reaching some threshold triggering a channel closure. 144 | 145 | This scheme doesn't prevent reputation contamination. From a node viewpoint, failure of your direct 146 | peer or from upstream peer can't be dissociated. 147 | 148 | ### Naive upfront payment 149 | 150 | The most obvious proposal is to require nodes to unconditionally pay a *fixed* tiny amount to the 151 | next node when they want to relay an HTLC. Let's explore why this proposal does **not** work: 152 | 153 | * the attacker will pay that fee at the first hop, but will receive it back at the last hop: it 154 | this doesn't cost him anything 155 | * this fee applies to every payment attempt: when a legitimate user is unlucky and tries multiple 156 | routes without success (potentially because of valid reasons such as liquidity issues downstream) 157 | he will have to pay that fee multiple times 158 | 159 | ### Reverse upfront payment 160 | 161 | This [proposal](https://lists.linuxfoundation.org/pipermail/lightning-dev/2020-February/002547.html) builds on the previous one, but reverses the flow. Nodes pay a fee for *receiving* 162 | HTLCs instead of *sending* them. 163 | 164 | ```text 165 | A -----> B -----> C -----> D 166 | 167 | B pays A to receive the HTLC. 168 | Then C pays B to receive the forwarded HTLC. 169 | Then D pays C to receive the forwarded HTLC. 170 | ``` 171 | 172 | There must be a grace period during which no fees are paid; otherwise the `uncontrolled spam` attack 173 | allows the attacker to force all nodes in the route to pay fees while he's not paying anything. 174 | 175 | The fee cannot be the same at each hop, otherwise it's free for the attacker when he is at both 176 | ends of the payment route. 177 | 178 | This fee must increase as the HTLC travels downstream: this ensures that nodes that hold HTLCs 179 | longer are penalized more than nodes that fail them fast, and if a node has to hold an HTLC for a 180 | long time because it's stuck downstream, they will receive more fees than what they have to pay. 181 | 182 | The grace period cannot be the same at each hop either, otherwise the attacker can force Bob to be 183 | the only one to pay fees. Similarly to how we have `cltv_expiry_delta`, nodes must have a 184 | `hold_grace_period_delta` and the `hold_grace_period` must be bigger upstream than downstream. 185 | 186 | Drawbacks: 187 | 188 | * The attacker can still lock HTLCs for the duration of the `hold_grace_period` and repeat the 189 | attack continuously 190 | 191 | Open questions: 192 | 193 | * Does the fee need to be based on the time the HTLC is held? 194 | * What happens when a channel closes and HTLC-timeout has to be redeemed on-chain? 195 | * Can we implement this without exposing the route length to intermediate nodes? 196 | 197 | ### Bidirectional upfront payment 198 | 199 | This [proposal](https://lists.linuxfoundation.org/pipermail/lightning-dev/2020-October/002862.html) 200 | builds on the two previous proposals and combines them. Nodes pay both a forward and a backwards 201 | upfront fee, but the backwards one is refunded if HTLCs are settled quickly. 202 | 203 | ```text 204 | A -----> B -----> C -----> D 205 | ``` 206 | 207 | We add a `hold_grace_period_delta` field to `channel_update` (in seconds). 208 | We add three new fields in the tlv extension of `update_add_htlc`: 209 | 210 | * `spam_fees` (msat) 211 | * `hold_grace_period` (seconds) 212 | * `hold_fees` (msat) 213 | 214 | We add two new fields in the onion per-hop payload: 215 | 216 | * `outgoing_hold_grace_period` 217 | * `outgoing_spam_fees` 218 | 219 | When nodes receive an `update_add_htlc`, they verify that: 220 | 221 | * `hold_fees` is not unreasonable large 222 | * `hold_grace_period` is not unreasonably small or large 223 | * `hold_grace_period` - `outgoing_hold_grace_period` >= `hold_grace_period_delta` 224 | * `spam_fees` - `outgoing_spam_fees` > `0` and not unreasonably small 225 | 226 | Otherwise they immediately fail the HTLC instead of relaying it. 227 | 228 | For the example we assume all nodes use `hold_grace_period_delta = 10`. 229 | 230 | We add a forward upfront payment (`spam_fees`) that is paid unconditionally when offering an HTLC. 231 | We add a backwards upfront payment of `hold_fees` that is paid when receiving an HTLC, but refunded 232 | if the HTLC is settled before the `hold_grace_period` ends (see footnotes about this). 233 | 234 | Forward upfront payments strictly decrement at each hop, while backwards upfront payments increment 235 | at each hop (non-strictly). 236 | 237 | ```text 238 | +---+ +---+ +---+ +---+ 239 | | A | | B | | C | | D | 240 | +---+ +---+ +---+ +---+ 241 | | | | | 242 | | Non-refundable fee: 15 msat | | | 243 | |----------------------------->| | | 244 | | Refundable fee: 50 msat | | | 245 | | Refund deadline: 100 seconds | | | 246 | |<-----------------------------| | | 247 | | | Non-refundable fee: 14 msat | | 248 | | |----------------------------->| | 249 | | | Refundable fee: 60 msat | | 250 | | | Refund deadline: 90 seconds | | 251 | | |<-----------------------------| | 252 | | | | Non-refundable fee: 13 msat | 253 | | | |----------------------------->| 254 | | | | Refundable fee: 70 msat | 255 | | | | Refund deadline: 80 seconds | 256 | | | |<-----------------------------| 257 | | | | | 258 | ``` 259 | 260 | * A sends an HTLC to B: 261 | * `hold_grace_period = 100 sec` 262 | * `hold_fees = 50 msat` 263 | * `outgoing_hold_grace_period = 90 sec` 264 | * `spam_fees = 15 msat` 265 | * `outgoing_spam_fees = 14 msat` 266 | * forward upfront payment: 15 msat are deduced from A's main output and added to B's main output 267 | * backwards upfront payment: 50 msat are deduced from B's main output and added to A's main output 268 | * B forwards the HTLC to C: 269 | * `hold_grace_period = 90 sec` 270 | * `hold_fees = 60 msat` 271 | * `outgoing_hold_grace_period = 80 sec` 272 | * `spam_fees = 14 msat` 273 | * `outgoing_spam_fees = 13 msat` 274 | * forward upfront payment: 14 msat are deduced from B's main output and added to C's main output 275 | * backwards upfront payment: 60 msat are deduced from C's main output and added to B's main output 276 | * C forwards the HTLC to D: 277 | * `hold_grace_period = 80 sec` 278 | * `hold_fees = 70 msat` 279 | * `spam_fees = 13 msat` 280 | * forward upfront payment: 13 msat are deduced from C's main output and added to D's main output 281 | * backwards upfront payment: 70 msat are deduced from D's main output and added to C's main output 282 | 283 | * Scenario 1: D settles the HTLC quickly: 284 | * all backwards upfront payments are refunded (returned to the respective main outputs) 285 | * only the forward upfront payments have been paid (to protect against `uncontrolled spam` and 286 | `short-lived controlled spam`) 287 | 288 | * Scenario 2: D settles the HTLC after the grace period: 289 | * D's backwards upfront payment is not refunded 290 | * If C and B relay the settlement upstream quickly (before `hold_grace_period_delta`) their backwards 291 | upfront payments are refunded 292 | * all the forward upfront payments have been paid (to protect against `uncontrolled spam` and 293 | `short-lived controlled spam`) 294 | 295 | * Scenario 3: C delays the HTLC: 296 | * D settles before its `grace_period`, so its backwards upfront payment is refunded by C 297 | * C delays before settling upstream: it can ensure B will not get refunded, but C will not get 298 | refunded either so B gains the difference in backwards upfront payments (which protects against 299 | `controlled spam`) 300 | * all the forward upfront payments have been paid (to protect against `uncontrolled spam` and 301 | `short-lived controlled spam`) 302 | 303 | * Scenario 4: the channel B <-> C closes: 304 | * D settles before its `grace_period`, so its backwards upfront payment is refunded by C 305 | * for whatever reason (malicious or not) the B <-> C channel closes 306 | * this ensures that C's backwards upfront payment is paid to B 307 | * if C publishes an HTLC-fulfill quickly, B may have his backwards upfront payment refunded by A 308 | * if B is forced to wait for his HTLC-timeout, his backwards upfront payment will not be refunded 309 | but it's ok because B got C's backwards upfront payment 310 | * all the forward upfront payments have been paid (to protect against `uncontrolled spam` and 311 | `short-lived controlled spam`) 312 | 313 | The backwards upfront payment is fixed instead of scaled based on the time an HTLC is left pending; 314 | it's slightly less penalizing for spammers, but is less complex and introduces less potential 315 | griefing against honest nodes. With the scaling approach, an honest node that has its channel 316 | unilaterally closed is too heavily penalized (because it has to pay for the maximum hold duration). 317 | 318 | Drawbacks: 319 | 320 | * If done naively, this mechanism may allow intermediate nodes to deanonymize sender/recipient. 321 | Randomizing the base `grace_period`, `hold_fees` and `spam_fees` may remove that probing vector. 322 | * Handling the `grace_period` will be a pain: 323 | * when do you start counting: when you send/receive `commit_sig` or `revoke_and_ack`? 324 | * what happens if there is a disconnection (how do you account for the delay of reconnecting)? 325 | * what happens if the remote settles after the `grace_period`, but refunds himself when sending 326 | his `commit_sig` (making it look like from his point of view he settled before the 327 | `grace_period`)? In that case the behavior should probably be to give your peers some leeway 328 | and let them get away with it, but record it. If they're doing it too often, close channels and 329 | ban them; stealing upfront fees should never be worth losing channels. 330 | 331 | ### Hold-time-dependent bidirectional upfront payment 332 | 333 | One characteristic of bidirectional upfront payments as described above is that 334 | the `hold_fees` are time-independent. If an htlc doesn't resolve within the 335 | `grace_period`, the receiver of the htlc will be forced to pay the full hold 336 | fee. The hold fee should cover the expenses for locking up an htlc for the 337 | maximum duration (could be 2000 blocks), so this can be a significant penalty. 338 | Applications such as atomic onchain/offchain swaps (Lightning Loop and others) 339 | rely on locking funds for some time and could get expensive with a fixed hold 340 | fee. 341 | 342 | A different variant of bidirectional upfront payments uses a time-proportional hold 343 | fee rate to address the limitation above. It aims to relate the fees paid more 344 | directly to the actual costs incurred and thereby reduce the number of 345 | parameters. 346 | 347 | The complete proposal can be found [here](https://lists.linuxfoundation.org/pipermail/lightning-dev/2021-February/002958.html). 348 | 349 | ### Web of trust HTLC hold fees 350 | 351 | This [proposal](https://lists.linuxfoundation.org/pipermail/lightning-dev/2020-October/002826.html) introduces fees depending on the amount of time HTLCs are kept pending. 352 | Nodes pay when *offering* HTLCs based on the following formula: 353 | 354 | ```text 355 | hold_fee = lock_time * (fee_base + fee_rate * htlc_value) 356 | ``` 357 | 358 | The `fee_base` and `fee_rate` depend on the trust relationship between the two peers: 359 | 360 | * Nodes charge a high rate to nodes they don't know/trust 361 | * Over time, nodes observe their peers and may lower the fees if they have behaved correctly 362 | for a long enough period of time 363 | * This ensures spamming is more costly to attackers, who have to either: 364 | * spend sats to spam 365 | * or spend time to build a reputation 366 | * Hold fees can be implemented on the protocol-level, but it is also possible to 367 | enforce the policy externally. For example: stop forwarding payments when the 368 | hold fee budget is exhausted and require the peer to top up via keysend. 369 | 370 | Drawbacks: 371 | 372 | * Barrier to entry (for new routing nodes) potentially leading to centralization 373 | * Correctly rating peers is hard: most of the metrics can be gamed by remote nodes to lower a 374 | peer's score 375 | * Small griefing is possible: peers have an incentive to hold HTLCs longer to collect more fees: 376 | this is true of all proposals that are based on pay-per-time held where the sender pays the fees 377 | * "Exit scam" type of attacks: malicious nodes behave correctly long enough, then launch an attack 378 | 379 | # Adjacent Issues 380 | 381 | Solving channel spamming might help in other corner cases of LN. 382 | 383 | ## Costless channel probing 384 | 385 | A node continuously probing channels across the network may discover the payment traffic of routing 386 | nodes and thus globally track LN payment traffic. 387 | 388 | ## Watchtower Credit Exhaustion 389 | 390 | Considering the upcoming deployment of public watchtowers, a LN node may have to pay a cost 391 | per-channel update to avoid a watchtower resource DoS. A malicious counterparty continously 392 | updating a channel may force the victim to exhaust its watchtower credit, thus knocking-out 393 | victim revocation protection. 394 | 395 | If a malicious HTLC sender/relayer have to pay a fixed fee to the victim, it creates a higher 396 | bound on victim watchtower budget. Additional watchtower coverage beyond what this fixed fee 397 | afford has to be paid from victim pocket. 398 | 399 | Eltoo is likely to solve this issue by restraining watchtower per-update resource cost to a 400 | bandwidth one only. 401 | 402 | # Sources 403 | 404 | ## Mailing List (chronological order) 405 | 406 | * [Loop attack](https://lists.linuxfoundation.org/pipermail/lightning-dev/2015-August/000135.html) 407 | * [Analysis: alternative DoS prevention concept](https://lists.linuxfoundation.org/pipermail/lightning-dev/2016-November/000648.html) 408 | * [Mitigations for loop attacks](https://lists.linuxfoundation.org/pipermail/lightning-dev/2018-May/001232.html) 409 | * [A proposal for upfront payment](https://lists.linuxfoundation.org/pipermail/lightning-dev/2019-November/002275.html) 410 | * [A proposal for upfront payment (reverse upfront)](https://lists.linuxfoundation.org/pipermail/lightning-dev/2020-February/002547.html) 411 | * [Proof-of-closure as griefing attack mitigation](https://lists.linuxfoundation.org/pipermail/lightning-dev/2020-April/002608.html) 412 | * [Hold fees: 402 Payment Required for Lightning itself](https://lists.linuxfoundation.org/pipermail/lightning-dev/2020-October/002826.html) 413 | 414 | ## Papers 415 | 416 | * [Discharged Payment Channels: Quantifying the Lightning Network's Resilience to Topology-Based Attacks](https://arxiv.org/pdf/1904.10253.pdf) 417 | * [LockDown: Balance Availability Attack Against Lightning Network Channels](https://eprint.iacr.org/2019/1149.pdf) 418 | * [Congestion Attacks in Payment Channel Networks](https://arxiv.org/pdf/2002.06564.pdf) 419 | * [Probing Channel Balances in the Lightning Network](https://arxiv.org/pdf/2004.00333.pdf) 420 | -------------------------------------------------------------------------------- /sphinx.md: -------------------------------------------------------------------------------- 1 | # Sphinx onion encryption: from Zero to Hero 2 | 3 | Lightning uses an onion encryption scheme called [Sphinx](http://www.cypherpunks.ca/~iang/pubs/Sphinx_Oakland09.pdf) 4 | to guarantee privacy along a payment path. 5 | 6 | This article describes the Sphinx construction. 7 | It can be particularly helpful for future implementers, curious users or people who want to tinker 8 | with the crypto to provide new functionalities (such as rendezvous routing). 9 | 10 | ## Table of Contents 11 | 12 | * [Notations](#notations) 13 | * [Computing shared secrets](#computing-shared-secrets) 14 | * [Generating a filler](#generating-a-filler) 15 | * [Creating the payload](#creating-the-payload) 16 | * [Decrypting the hop payload](#decrypting-the-hop-payload) 17 | * [Full diagram](#full-diagram) 18 | 19 | ## Notations 20 | 21 | ```text 22 | Alice -> N(1) -> N(2) -> ... -> N(r) 23 | ``` 24 | 25 | N(i)'s `node_id` is P(i) = k(i) * G. 26 | The length of the encrypted payload sent to N(i) is l(i) (this includes the inner mac). 27 | The total payload length is 1300 bytes. 28 | 29 | ## Computing shared secrets 30 | 31 | * session_key <- {0;1}^256 32 | * ek(1) = session_key 33 | * Shared with N(1): 34 | * E(1) = ek(1) * G (sent unencrypted in the onion header) 35 | * ss(1) = H(ek(1) * P(1)) = H(k(1) * E(1)) 36 | * rho(1) = HMAC(0x72686F, ss(1)) 37 | * b(1) = H(E(1) || ss(1)) 38 | * ... 39 | * ek(i) = b(i-1) * ek(i-1) 40 | * Shared with N(i): 41 | * E(i) = ek(i) * G (sent unencrypted in the onion header) 42 | * ss(i) = H(ek(i) * P(i)) = H(k(i) * E(i)) 43 | * rho(i) = HMAC(0x72686F, ss(i)) 44 | * b(i) = H(E(i) || ss(i)) 45 | 46 | Every N(i) is able to compute E(i+1) = b(i) * E(i). 47 | 48 | ## Generating a filler 49 | 50 | * Generate filler for payloads 1 to (r-1) 51 | * Total of `l(1) + l(2) + ... + l(r-1)` bytes 52 | * filler = [] 53 | * For i <- 1..(r-1): 54 | * filler <- (filler + [0; l(i)]) xor stream(rho(i))[1300-l(i-1)-...-l(1):1300+l(i)] 55 | 56 | Example filler for 3 nodes: 57 | 58 | ```text 59 | <---l(1)---> 60 | +----------+ 61 | | 00000000 | 62 | +----------+ 63 | (+) 64 | <-----------------1300-----------------><---l(1)---> 65 | +--------------------------------------------------+ 66 | | stream(rho(1)) | 67 | +--------------------------------------------------+ 68 | = 69 | <---l(1)---><-----l(2)-----> 70 | +----------++--------------+ 71 | | xxxxxxxx || 000000000000 | 72 | +----------++--------------+ 73 | (+) 74 | <-----------------1300-------------><-----l(2)-----> 75 | +--------------------------------------------------+ 76 | | stream(rho(2)) | 77 | +--------------------------------------------------+ 78 | = 79 | <---l(1) + l(2)------------><----l(3)----> 80 | +--------------------------++------------+ 81 | | xxxxxxxxxxxxxxxxxxxxxxxx || 0000000000 | 82 | +--------------------------++------------+ 83 | (+) 84 | <-----------------1300---------------><----l(3)----> 85 | +--------------------------------------------------+ 86 | | stream(rho(3)) | 87 | +--------------------------------------------------+ 88 | = 89 | <---l(1) + l(2) + l(3)-------------------> 90 | +----------------------------------------+ 91 | | xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx | 92 | +----------------------------------------+ 93 | ``` 94 | 95 | ## Creating the payload 96 | 97 | The payload is encrypted hop by hop, starting from the recipient. 98 | Every hop is authenticated. 99 | I'm ignoring the mac handling for simplicity, but there's nothing complicated with it. 100 | 101 | * Special case for the recipient: 102 | * payload(r) = ((p(r) + random bytes) xor stream(rho(r))[0:1300-l(r-1)-...-l(1)]) + filler 103 | * For i <- (r-1)..1: 104 | * payload(i) = (p(i) + payload(i-1)[0:1300-l(i)]) xor stream(rho(i)) 105 | 106 | ```text 107 | <--------1300-------------------------------------------------------------------> 108 | <---l(r)---><-------------------------><----l(1) + l(2) + l(3)------------------> 109 | +----------++-------------------------++----------------------------------------+ 110 | | p(r) || random initial bytes || xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx | 111 | +----------++-------------------------++----------------------------------------+ 112 | (+) 113 | <-------1300 - l(1) - l(2) - l(3)-----> 114 | +-------------------------------------+ 115 | | stream(rho(r)) | 116 | +-------------------------------------+ 117 | = 118 | <--------1300-------------------------------------------------------------------> 119 | +-------------------------------------------------------------------------------+ 120 | | encrypted payload for N(r) | 121 | +-------------------------------------------------------------------------------+ 122 | <----l(3)----><-------1300 - l(3)-----------------------------------------------> 123 | +------------++-----------------------------------------------------------------+ 124 | | p(3) || encrypted payload for N(r) (truncated) | 125 | +------------++-----------------------------------------------------------------+ 126 | (+) 127 | +-------------------------------------------------------------------------------+ 128 | | stream(rho(3)) | 129 | +-------------------------------------------------------------------------------+ 130 | = 131 | <--------1300-------------------------------------------------------------------> 132 | +-------------------------------------------------------------------------------+ 133 | | encrypted payload for N(3) | 134 | +-------------------------------------------------------------------------------+ 135 | <-----l(2)-----><-------1300 - l(2)---------------------------------------------> 136 | +--------------++---------------------------------------------------------------+ 137 | | p(2) || encrypted payload for N(3) (truncated) | 138 | +--------------++---------------------------------------------------------------+ 139 | (+) 140 | +-------------------------------------------------------------------------------+ 141 | | stream(rho(2)) | 142 | +-------------------------------------------------------------------------------+ 143 | = 144 | <--------1300-------------------------------------------------------------------> 145 | +-------------------------------------------------------------------------------+ 146 | | encrypted payload for N(2) | 147 | +-------------------------------------------------------------------------------+ 148 | <---l(1)---><--------1300 - l(1)------------------------------------------------> 149 | +----------++-------------------------------------------------------------------+ 150 | | p(1) || encrypted payload for N(2) (truncated) | 151 | +----------++-------------------------------------------------------------------+ 152 | (+) 153 | +-------------------------------------------------------------------------------+ 154 | | stream(rho(1)) | 155 | +-------------------------------------------------------------------------------+ 156 | = 157 | <--------1300-------------------------------------------------------------------> 158 | +-------------------------------------------------------------------------------+ 159 | | encrypted payload for N(1) | 160 | +-------------------------------------------------------------------------------+ 161 | ``` 162 | 163 | ## Decrypting the hop payload 164 | 165 | This is where the filler matters: because it's generated with the same stream 166 | cipher, decrypting re-creates it on-the-fly (and thus ensures macs are valid). 167 | 168 | ```text 169 | <--------1300-------------------------------------------------------------------> 170 | +-------------------------------------------------------------------------------+ 171 | | encrypted payload for N(1) | 172 | +-------------------------------------------------------------------------------+ 173 | (+) <---l(1)---> 174 | +-------------------------------------------------------------------------------------------+ 175 | | stream(rho(1)) | 176 | +-------------------------------------------------------------------------------------------+ 177 | = 178 | <---l(1)---><--------1300-------------------------------------------------------------------> 179 | +----------++-------------------------------------------------------------------------------+ 180 | | p(1) || encrypted payload for N(2) | 181 | +----------++-------------------------------------------------------------------------------+ 182 | (+) <-----l(2)-----> 183 | +-----------------------------------------------------------------------------------------------+ 184 | | stream(rho(2)) | 185 | +-----------------------------------------------------------------------------------------------+ 186 | <-----l(2)-----> = 187 | +--------------++-------------------------------------------------------------------------------+ 188 | | p(2) || encrypted payload for N(3) | 189 | +--------------++-------------------------------------------------------------------------------+ 190 | (+) <----l(3)----> 191 | +---------------------------------------------------------------------------------------------+ 192 | | stream(rho(3)) | 193 | +---------------------------------------------------------------------------------------------+ 194 | <----l(3)----> = 195 | +------------++-------------------------------------------------------------------------------+ 196 | | p(3) || encrypted payload for N(r) | 197 | +------------++-------------------------------------------------------------------------------+ 198 | (+) 199 | +-------------------------------------------------------------------------------+ 200 | | stream(rho(r)) | 201 | +-------------------------------------------------------------------------------+ 202 | = 203 | <--------1300-------------------------------------------------------------------> 204 | <---l(r)---><-------------------------><--- l(1) + l(2) + l(3) -----------------> 205 | +----------++-------------------------++----------------------------------------+ 206 | | p(r) || random initial bytes || xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx | 207 | +----------++-------------------------++----------------------------------------+ 208 | ``` 209 | 210 | ## Full diagram 211 | 212 | ```text 213 | Alice -> Bob -> Carol -> Dave 214 | ``` 215 | 216 | ```text 217 | 1. Filler Generation 218 | 219 | <-----l(B)-----> 220 | +--------------+ 221 | | 000000000000 | 222 | +--------------+ 223 | (+) 224 | <-----------------1300------------------------------------------><-----l(B)-----> 225 | +-------------------------------------------------------------------------------+ 226 | | stream(ss(Bob)) | 227 | +-------------------------------------------------------------------------------+ 228 | = 229 | <-----l(B)-----><-l(C)-> 230 | +--------------++------+ 231 | | xxxxxxxxxxxx || 0000 | 232 | +--------------++------+ 233 | (+) 234 | <-----------------1300------------------------------------------><-l(C)-> 235 | +-----------------------------------------------------------------------+ 236 | | stream(ss(C)) | 237 | +-----------------------------------------------------------------------+ 238 | = 239 | <-----l(B) + l(C)------> 240 | +----------------------+ 241 | | xxxxxxxxxxxxxxxxxxxx | 242 | +----------------------+ 243 | 244 | 2. Onion Encryption 245 | 246 | <-----------------1300------------------------------------------> 247 | <----l(D)----><-------------------------><------l(B) + l(C)-----> 248 | +------------++-------------------------++----------------------+ 249 | | p(D) || random init bytes || xxxxxxxxxxxxxxxxxxxx | 250 | +------------++-------------------------++----------------------+ 251 | (+) 252 | <---------1300 - l(B) - l(C)------------> 253 | +---------------------------------------+ 254 | | stream(ss(D)) | 255 | +---------------------------------------+ 256 | = 257 | <---------1300 - l(B) - l(C)------------><------l(B) + l(C)-----> 258 | +---------------------------------------++----------------------+ 259 | | encrypted payload for Dave || xxxxxxxxxxxxxxxxxxxx | 260 | +---------------------------------------++----------------------+ 261 | <-l(C)-><--------1300 - l(C)------------------------------------> 262 | +------++-------------------------------------------------------+ 263 | | p(C) || encrypted payload for Dave (truncated) | 264 | +------++-------------------------------------------------------+ 265 | (+) 266 | +---------------------------------------------------------------+ 267 | | stream(ss(C)) | 268 | +---------------------------------------------------------------+ 269 | = 270 | <--------1300---------------------------------------------------> 271 | +---------------------------------------------------------------+ 272 | | encrypted payload for Carol | 273 | +---------------------------------------------------------------+ 274 | <-----l(B)-----><----------1300 - l(B)--------------------------> 275 | +--------------++-----------------------------------------------+ 276 | | p(B) || encrypted payload for Carol (truncated) | 277 | +--------------++-----------------------------------------------+ 278 | (+) 279 | +---------------------------------------------------------------+ 280 | | stream(ss(B)) | 281 | +---------------------------------------------------------------+ 282 | = 283 | <--------1300---------------------------------------------------> 284 | +---------------------------------------------------------------+ 285 | | encrypted payload for Bob | 286 | +---------------------------------------------------------------+ 287 | 288 | 3. Onion Decryption 289 | 290 | <--------1300---------------------------------------------------> 291 | +---------------------------------------------------------------+ 292 | | encrypted payload for Bob | 293 | +---------------------------------------------------------------+ 294 | (+) <-----l(B)-----> 295 | +-------------------------------------------------------------------------------+ 296 | | stream(ss(B)) | 297 | +-------------------------------------------------------------------------------+ 298 | = 299 | <-----l(B)-----><------- 1300 --------------------------------------------------> 300 | +--------------++---------------------------------------------------------------+ 301 | | p(B) || encrypted payload for Carol | 302 | +--------------++---------------------------------------------------------------+ 303 | (+) <-l(C)-> 304 | +-----------------------------------------------------------------------+ 305 | | stream(ss(C)) | 306 | +-----------------------------------------------------------------------+ 307 | = 308 | <-l(C)-><------- 1300 --------------------------------------------------> 309 | +------++---------------------------------------------------------------+ 310 | | p(C) || encrypted payload for Dave | 311 | +------++---------------------------------------------------------------+ 312 | (+) 313 | +---------------------------------------------------------------+ 314 | | stream(ss(D)) | 315 | +---------------------------------------------------------------+ 316 | = 317 | <-----------------1300------------------------------------------> 318 | <----l(D)----><-------------------------><------l(B) + l(C)-----> 319 | +------------++-------------------------++----------------------+ 320 | | p(D) || random init bytes || xxxxxxxxxxxxxxxxxxxx | 321 | +------------++-------------------------++----------------------+ 322 | ``` 323 | -------------------------------------------------------------------------------- /taproot-updates.md: -------------------------------------------------------------------------------- 1 | # Lightning Is Getting Taprooty Scriptless-Scripty 2 | 3 | This article contains a summary of the many changes that Taproot will bring to lightning. 4 | But first of all, a disclaimer: 5 | 6 | ![taproot lightning txs image](img/taproot-lightning-txs.jpg) 7 | 8 | While Taproot brings many privacy improvements to the table, there are a lot of other, unrelated 9 | updates to lightning that are higher priority and orthogonal to it, and implementers are already 10 | struggling to find time to review and implement everything. Please be patient, Taproot is coming, 11 | but it will take time! 12 | 13 | Schnorr, Musig2 and adaptor signatures have been covered in [this article](./schnorr.md): they are 14 | the foundations upon which we'll build everything, so I suggest reading it if you want to 15 | understand the low-level details of the following proposals. 16 | 17 | Now that this is out of the way, let's dive into Taproot stuff. 18 | 19 | ## Table of Contents 20 | 21 | * [Musig2 Channel Funding](#musig2-channel-funding) 22 | * [Taproot Lightning Transactions](#taproot-lightning-transactions) 23 | * [Point Time-Locked Contracts](#point-time-locked-contracts) 24 | * [Further Changes](#further-changes) 25 | * [Resources](#resources) 26 | 27 | ## Musig2 Channel Funding 28 | 29 | Thanks to Schnorr and Musig2, we can make lightning channels indistinguishable from any other key 30 | path spend in the cooperative case. 31 | 32 | The funding transaction output will be a taproot output without a script path, where the 33 | `internal_pubkey` is the Musig2 aggregated public key of the two channel participants. 34 | 35 | We need to add Musig2 nonces to existing messages (in the `extension` tlv stream) but don't need to 36 | define any new message. For example, when updating a commitment, `revoke_and_ack` will contain the 37 | next set of nonces and `commit_sig` will contain the current nonces and the (partial) signature. 38 | 39 | Changing the funding output is a good opportunity to also introduce xpubs. Instead of directly 40 | exchanging a `funding_pubkey` when opening the channel, participants exchange a `funding_xpub` 41 | and then derive the actual `funding_pubkey` with non-hardened derivation. Future updates of the 42 | funding output (e.g. splicing funds in or out) can simply increment a derivation counter, which 43 | removes the need to explicitly share the next funding pubkeys and simplifies backup. This idea was 44 | proposed in [ajtowns' mailing list post](https://lists.linuxfoundation.org/pipermail/lightning-dev/2021-October/003278.html). 45 | 46 | This change is quite simple and can be added relatively quickly (once Musig2 has been finalized). 47 | 48 | ## Taproot Lightning Transactions 49 | 50 | The existing transaction structure (detailed in [this article](./lightning-txs.md)) can be updated 51 | to use Taproot scripts. 52 | 53 | This doesn't change the protocol: nodes still exchange the same messages when sending payments 54 | (`update_add_htlc`, `commit_sig`, `revoke_and_ack`, `update_fulfill_htlc`, `update_fail_htlc`). 55 | 56 | We simply take the existing scripts and split them into several branches of a taproot tree, 57 | leveraging the key path spend whenever it makes sense. 58 | 59 | The commitment transaction will then become: 60 | 61 | ```text 62 | { 63 | "version": 2, 64 | "locktime": 543210000, 65 | "vin": [ 66 | { 67 | "txid": "...", 68 | "vout": ..., 69 | "scriptSig": "", 70 | "sequence": 2500123456 71 | } 72 | ], 73 | "vout": [ 74 | { 75 | "value": 0.5, 76 | "output_type": "to_local", 77 | "scriptPubKey": { 78 | "internal_pubkey": " 79 | # funds go to the remote node with the revocation key 80 | musig2(,) 81 | ", 82 | "tapleaf": " 83 | # or back to us after a relative delay () 84 | 85 | OP_CHECKSIGVERIFY 86 | 87 | OP_CHECKSEQUENCEVERIFY 88 | " 89 | } 90 | }, 91 | { 92 | "value": 0.3, 93 | "output_type": "to_remote", 94 | "scriptPubKey": { 95 | "internal_pubkey": "", 96 | "tapleaf": " 97 | # funds go back to the other channel participant after 1 block 98 | 99 | OP_CHECKSIGVERIFY 100 | 1 OP_CHECKSEQUENCEVERIFY 101 | " 102 | } 103 | }, 104 | { 105 | "value": 0.00000330, 106 | "output_type": "local_anchor", 107 | "scriptPubKey": { 108 | "internal_pubkey": "", 109 | "tapleaf": " 110 | # after a relative timelock of 16 blocks, anyone can claim this tiny amount 111 | # once the to_local output has been spent, revealing the local_delayedpubkey 112 | OP_16 OP_CHECKSEQUENCEVERIFY 113 | " 114 | } 115 | }, 116 | { 117 | "value": 0.00000330, 118 | "output_type": "remote_anchor", 119 | "scriptPubKey": { 120 | "internal_pubkey": "", 121 | "tapleaf": " 122 | # after a relative timelock of 16 blocks, anyone can claim this tiny amount 123 | # once the to_remote output has been spent, revealing the remote_pubkey 124 | OP_16 OP_CHECKSEQUENCEVERIFY 125 | " 126 | } 127 | }, 128 | { 129 | "value": 0.05, 130 | "output_type": "offered_htlc", 131 | "scriptPubKey": { 132 | "internal_pubkey": " 133 | # funds go to the remote node with the revocation key 134 | musig2(,) 135 | ", 136 | "tapleaf_1": " 137 | # funds go back to us via a second-stage HTLC-timeout transaction (which contains an absolute delay) 138 | # NB: we also need the remote signature, which prevents us from unilaterally changing the HTLC-timeout transaction 139 | OP_CHECKSIGVERIFY OP_CHECKSIGVERIFY 140 | 1 OP_CHECKSEQUENCEVERIFY 141 | ", 142 | "tapleaf_2": " 143 | # funds go to the remote node if it has the payment preimage. 144 | OP_SIZE 32 OP_EQUALVERIFY OP_HASH160 OP_EQUALVERIFY 145 | 146 | OP_CHECKSIGVERIFY 147 | 1 OP_CHECKSEQUENCEVERIFY 148 | " 149 | } 150 | }, 151 | { 152 | "value": 0.08, 153 | "output_type": "received_htlc", 154 | "scriptPubKey": { 155 | "internal_pubkey": " 156 | # funds go to the remote node with the revocation key 157 | musig2(,) 158 | ", 159 | "tapleaf_1": " 160 | # funds go to us via a second-stage HTLC-success transaction once we have the payment preimage 161 | # NB: we also need the remote signature, which prevents us from unilaterally changing the HTLC-success transaction 162 | OP_SIZE 32 OP_EQUALVERIFY OP_HASH160 OP_EQUALVERIFY 163 | OP_CHECKSIGVERIFY OP_CHECKSIGVERIFY 164 | 1 OP_CHECKSEQUENCEVERIFY 165 | ", 166 | "tapleaf_2": " 167 | # funds go to the remote node after an absolute delay (timeout) 168 | 169 | OP_CHECKSIGVERIFY 170 | 1 OP_CHECKSEQUENCEVERIFY 171 | 172 | OP_CHECKLOCKTIMEVERIFY 173 | OP_DROP 174 | " 175 | } 176 | }, 177 | ] 178 | } 179 | ``` 180 | 181 | You should notice that the public keys used in the anchor outputs have changed. 182 | We were previously using the `local_funding_pubkey` and `remote_funding_pubkey` because since they 183 | were revealed in the witness of the funding input, it let anyone watching the blockchain claim 184 | these outputs after 16 blocks to avoid bloating the utxo set. 185 | But with Musig2 the individual funding public keys are never revealed, so we need to use other 186 | public keys that may be revealed when outputs of the commitment transaction are spent. 187 | 188 | A taproot HTLC-success transaction looks like: 189 | 190 | ```text 191 | { 192 | "version": 2, 193 | "locktime": 0, 194 | "vin": [ 195 | { 196 | "txid": "...", 197 | "vout": 42, 198 | "scriptSig": " ", 199 | "sequence": 1 200 | } 201 | ], 202 | "vout": [ 203 | { 204 | "value": 0.04, 205 | "scriptPubKey": { 206 | "internal_pubkey": " 207 | # funds go to the remote node with the revocation key 208 | musig2(,) 209 | ", 210 | "tapleaf": " 211 | # or back to us after a relative delay () 212 | 213 | OP_CHECKSIGVERIFY 214 | 215 | OP_CHECKSEQUENCEVERIFY 216 | " 217 | } 218 | } 219 | ] 220 | } 221 | ``` 222 | 223 | A taproot HTLC-timeout transaction looks like: 224 | 225 | ```text 226 | { 227 | "version": 2, 228 | "locktime": , 229 | "vin": [ 230 | { 231 | "txid": "...", 232 | "vout": 42, 233 | "scriptSig": " ", 234 | "sequence": 1 235 | } 236 | ], 237 | "vout": [ 238 | { 239 | "value": 0.04, 240 | "scriptPubKey": { 241 | "internal_pubkey": " 242 | # funds go to the remote node with the revocation key 243 | musig2(,) 244 | ", 245 | "tapleaf": " 246 | # or back to us after a relative delay () 247 | 248 | OP_CHECKSIGVERIFY 249 | 250 | OP_CHECKSEQUENCEVERIFY 251 | " 252 | } 253 | } 254 | ] 255 | } 256 | ``` 257 | 258 | Do note that the changes described in this section only make sense to do if we're able to integrate 259 | PTLCs without radically changing the transaction format. We will explore that in the next section. 260 | 261 | ## Point Time-Locked Contracts 262 | 263 | Once lightning transactions use taproot, we'd like to add support for PTLCs (Point Time Locked 264 | Contracts) in addition to HTLCs (Hash Time Locked Contracts). 265 | PTLCs can only be used when the whole route supports them, which means we'll have to keep 266 | supporting HTLCs until the majority of the network has been updated. 267 | 268 | The main benefit of PTLCs is payment decorrelation: instead of using the same secret for each hop 269 | in the route (`payment_hash` for HTLCs) we can use different secrets for each hop, which provides 270 | much better privacy. 271 | 272 | We can use [scriptless scripts multi-hop locks](https://github.com/ElementsProject/scriptless-scripts/blob/master/md/multi-hop-locks.md) 273 | to allow routing PTLCs across multiple hops. 274 | 275 | Conceptually, what we would like to do when offering a PTLC is to add an output with the following 276 | structure (or something similar) to our commitment transaction: 277 | 278 | ```text 279 | { 280 | "internal_pubkey": " 281 | # funds go to the remote node with the revocation key 282 | musig2(,) 283 | ", 284 | "tapleaf_1": " 285 | # funds go back to us via a second-stage PTLC-timeout transaction (which contains an absolute delay) 286 | # NB: we need the remote signature, which prevents us from unilaterally changing the PTLC-timeout transaction 287 | OP_CHECKSIGVERIFY OP_CHECKSIGVERIFY 288 | 1 OP_CHECKSEQUENCEVERIFY 289 | ", 290 | "tapleaf_2": " 291 | # funds go to the remote node via a second-stage Claim-PTLC-success transaction by completing an adaptor sig, revealing the payment secret 292 | # NB: we don't use musig2 here because it would force local and remote signatures to use the same sighash flags 293 | OP_CHECKSIGVERIFY OP_CHECKSIGVERIFY 294 | 1 OP_CHECKSEQUENCEVERIFY 295 | " 296 | } 297 | ``` 298 | 299 | But this introduces a fundamental change compared to HTLCs: the receiver cannot directly claim the 300 | PTLC from our commitment transaction once they have the secret. Instead, we need to introduce a 301 | second-stage transaction that must be pre-signed. 302 | 303 | First of all, let's explain why this fundamental change is necessary. 304 | 305 | With HTLCs, the secret (payment preimage) could be revealed by the receiver in the spending script 306 | of the HTLC output. Once the HTLC was spent, the sender could simply look at the signature script 307 | to learn the secret and propagate it upstream. 308 | 309 | With PTLCs, the secret is a private key. The way it is revealed is a two steps process: 310 | 311 | 1. the sender provides an adaptor signature based on the payment point 312 | 2. the receiver completes the adaptor signature (using the payment secret) to spend the output 313 | 314 | With both the adaptor signature and the complete signature, the sender can extract the secret. 315 | We can see a few problems emerge from that two steps process: 316 | 317 | * more signatures need to be exchanged, because each peer needs to send signatures for 2nd-stage 318 | transactions that let the remote peer claim PTLCs from the local commitment 319 | * claiming successful PTLCs from the remote peer's commitment now requires using RBF and sighash 320 | flags similar to anchor outputs HTLC transactions (`sighash_single | sighash_anyonecanpay` trick) 321 | * before signing a commitment update, peers must obtain from their counterparty adaptor signatures 322 | for their pending received PTLCs in the future remote commitment 323 | 324 | Let's now detail a strawman, high-level proposal that enables PTLCs. 325 | 326 | First of all, have a look at the [existing transaction structure](./lightning-txs.md#anchor-outputs). 327 | We simply add two new types of outputs to the commit tx (PTLC offered / PTLC received): 328 | 329 | ```ascii 330 | +------------+ 331 | | funding tx | 332 | +------------+ 333 | | 334 | | +------------------------+ 335 | +------->| commit tx B | 336 | +------------------------+ 337 | | | | | | | | | 338 | | | | | | | | | A's main output 339 | | | | | | | | +-----------------> to A after a 1-block relative delay 340 | | | | | | | | 341 | | | | | | | | +---> to B after relative delay 342 | | | | | | | | B's main output | 343 | | | | | | | +-----------------+ 344 | | | | | | | | 345 | | | | | | | +---> to A with revocation key 346 | | | | | | | 347 | | | | | | | A's anchor output 348 | | | | | | +--------------------> to A immediately (or anyone after 16-block relative delay) 349 | | | | | | 350 | | | | | | B's anchor output 351 | | | | | +-----------------------> to B immediately (or anyone after 16-block relative delay) 352 | | | | | 353 | | | | | (B's RBF inputs) ---+ 354 | | | | | | +---> to B after relative delay 355 | | | | | +---->+-----------------+ | 356 | | | | | +---------->| HTLC-timeout tx |------------+ 357 | | | | | HTLC offered by B | +-----------------+ | 358 | | | | +-------------------+ (after timeout + 1-block delay) +---> to A with revocation key 359 | | | | | 360 | | | | +---> to A with payment preimage after a 1-block relative delay 361 | | | | | 362 | | | | +---> to A with revocation key 363 | | | | 364 | | | | (B's RBF inputs) ---+ 365 | | | | | +---> to B after relative delay 366 | | | | +---->+-----------------+ | 367 | | | | +------------>| HTLC-success tx |----------------+ 368 | | | | HTLC received by B | +-----------------+ | 369 | | | +--------------------+ (with payment preimage + 1-block delay) +---> to A with revocation key 370 | | | | 371 | | | +---> to A after timeout (absolute delay + 1-block relative delay) 372 | | | | 373 | | | +---> to A with revocation key 374 | | | 375 | | | (B's RBF inputs) ---+ 376 | | | | +---> to B after relative delay 377 | | | +---->+-----------------+ | 378 | | | +------------>| PTLC-timeout tx |-------------+ 379 | | | PTLC offered by B | +-----------------+ | 380 | | +-------------------+ (after timeout + 1-block delay) +---> to A with revocation key 381 | | | 382 | | | (A's RBF inputs) ---+ 383 | | | | 384 | | | +---->+-----------------------+ 385 | | +-------------------------->| Claim-PTLC-success tx |--------------> to A 386 | | | +-----------------------+ 387 | | | (with payment secret + 1-block delay) 388 | | | 389 | | +---> to A with revocation key 390 | | 391 | | (B's RBF inputs) ---+ 392 | | | +---> to B after relative delay 393 | | +---->+-----------------+ | 394 | | +---------->| PTLC-success tx |----------------+ 395 | | PTLC received by B | +-----------------+ | 396 | +--------------------+ (with payment secret + 1-block delay) +---> to A with revocation key 397 | | 398 | +---> to A after timeout (absolute delay + 1-block relative delay) 399 | | 400 | +---> to A with revocation key 401 | ``` 402 | 403 | You should notice that the two PTLC outputs are very similar to the HTLC ones. 404 | The only difference is the introduction of the `claim-ptlc-success` transaction. 405 | This `claim-ptlc-success` transaction directly pays to the remote peer (no delay, no revocation). 406 | 407 | The current protocol for updating commitments is: 408 | 409 | ```text 410 | Alice Bob 411 | | commitment_signed | 412 | |------------------------>| 413 | | revoke_and_ack | 414 | |<------------------------| 415 | | commitment_signed | 416 | |<------------------------| 417 | | revoke_and_ack | 418 | |------------------------>| 419 | 420 | Alice -> Bob: commitment_signed 421 | channel id 422 | signature for Bob to spend funding tx 423 | sigs for Bob to spend HTLCs from his next commitment 424 | 425 | Bob -> Alice: revoke_and_ack 426 | channel id 427 | reveal previous commitment secret 428 | next commitment point 429 | 430 | Bob -> Alice: commitment_signed 431 | channel id 432 | signature for Alice to spend funding tx 433 | sigs for Alice to spend HTLCs from her next commitment 434 | 435 | Alice -> Bob: revoke_and_ack 436 | channel id 437 | reveal previous commitment secret 438 | next commitment point 439 | ``` 440 | 441 | The main difficulty introduced by the `claim-ptlc-success` transaction is that Alice needs to 442 | obtain adaptor signatures from Bob before she can send her `commitment_signed`. Let's detail why. 443 | 444 | Let's assume that there is currently a pending PTLC paying Alice in both commitments. What happens 445 | if Alice sends `commitment_signed` to Bob? 446 | 447 | Bob now has a new version of his commitment transaction, that he can broadcast. But Alice is unable 448 | to spend her PTLC output from this transaction, because she doesn't have Bob's signature for the 449 | new corresponding `claim-ptlc-success` (even if she obtains the payment secret). 450 | 451 | This can be fixed by changing the protocol: 452 | 453 | ```text 454 | Alice Bob 455 | | commitment_proposed | 456 | |------------------------>| 457 | | commitment_proposed | 458 | |<------------------------| 459 | | commitment_signed | 460 | |<------------------------| 461 | | revoke_and_ack | 462 | |------------------------>| 463 | | commitment_signed | 464 | |------------------------>| 465 | | revoke_and_ack | 466 | |<------------------------| 467 | 468 | Alice -> Bob: commitment_proposed 469 | channel id 470 | adaptor sigs for PTLCs to Bob in Alice's next commitment (claim-ptlc-success) 471 | musig nonces for Alice's signature on Alice's next commitment 472 | 473 | Bob -> Alice: commitment_proposed 474 | channel id 475 | adaptor sigs for PTLCs to Alice in Bob's next commitment (claim-ptlc-success) 476 | musig nonces for Bob's signature on Bob's next commitment 477 | 478 | Bob -> Alice: commitment_signed 479 | channel id 480 | musig nonces for Bob's signature on Alice's next commitment 481 | Bob's signature on Alice's next commitment 482 | sigs for Alice to spend HTLCs and PTLCs from her next commitment 483 | 484 | Alice -> Bob: revoke_and_ack 485 | channel id 486 | reveal previous commitment secret 487 | next commitment point 488 | 489 | Alice -> Bob: commitment_signed 490 | channel id 491 | musig nonces for Alice's signature on Bob's next commitment 492 | Alice's signature on Bob's next commitment 493 | sigs for Bob to spend HTLCs and PTLCs from his next commitment 494 | 495 | Bob -> Alice: revoke_and_ack 496 | channel id 497 | reveal previous commitment secret 498 | next commitment point 499 | ``` 500 | 501 | The `commitment_signed` and `revoke_and_ack` are mostly unchanged, the only difference is that the 502 | ptlc signatures in `commitment_signed` are now adaptor signatures for PTLC-success transactions. 503 | 504 | This change adds half a round-trip compared to the previous protocol, and changes which peer signs 505 | a new commitment first (with the previous protocol, Alice was signing first, but now it's Bob who 506 | signs first to save half another round-trip). 507 | 508 | ## Further changes 509 | 510 | We could wait for [Eltoo](https://blockstream.com/eltoo.pdf) before doing any kind of change that 511 | fundamentally updates the transaction structure and update protocol. 512 | However Eltoo requires a bitcoin soft-fork, so there is no guarantee that it will ever be possible. 513 | 514 | Alternatively, `ajtowns` proposed a new transaction format design on the mailing list in his 515 | [lightning over taproot with PTLCs post](https://lists.linuxfoundation.org/pipermail/lightning-dev/2021-October/003278.html). 516 | 517 | This proposal deserves its own article, which will be written once we have a first set of taproot 518 | updates deployed on the network. 519 | 520 | ## Resources 521 | 522 | * [BIP 341: Taproot](https://github.com/bitcoin/bips/blob/master/bip-0341.mediawiki) 523 | * [Scriptless Scripts Multi-Hop Locks](https://github.com/ElementsProject/scriptless-scripts/blob/master/md/multi-hop-locks.md) 524 | * [Eltoo](https://blockstream.com/eltoo.pdf) 525 | * [ajtowns lightning-dev post](https://lists.linuxfoundation.org/pipermail/lightning-dev/2021-October/003278.html) 526 | * [t-bast lightning-dev post](https://lists.linuxfoundation.org/pipermail/lightning-dev/2021-December/003377.html) 527 | --------------------------------------------------------------------------------