05-onchain.md (36862B)
1 # BOLT #5: Recommendations for On-chain Transaction Handling 2 3 ## Abstract 4 5 Lightning allows for two parties (a local node and a remote node) to conduct transactions 6 off-chain by giving each of the parties a *cross-signed commitment transaction*, 7 which describes the current state of the channel (basically, the current balance). 8 This *commitment transaction* is updated every time a new payment is made and 9 is spendable at all times. 10 11 There are three ways a channel can end: 12 13 1. The good way (*mutual close*): at some point the local and remote nodes agree 14 to close the channel. They generate a *closing transaction* (which is similar to a 15 commitment transaction, but without any pending payments) and publish it on the 16 blockchain (see [BOLT #2: Channel Close](02-peer-protocol.md#channel-close)). 17 2. The bad way (*unilateral close*): something goes wrong, possibly without evil 18 intent on either side. Perhaps one party crashed, for instance. One side 19 publishes its *latest commitment transaction*. 20 3. The ugly way (*revoked transaction close*): one of the parties deliberately 21 tries to cheat, by publishing an *outdated commitment transaction* (presumably, 22 a prior version, which is more in its favor). 23 24 Because Lightning is designed to be trustless, there is no risk of loss of funds 25 in any of these three cases; provided that the situation is properly handled. 26 The goal of this document is to explain exactly how a node should react when it 27 encounters any of the above situations, on-chain. 28 29 # Table of Contents 30 * [General Nomenclature](#general-nomenclature) 31 * [Commitment Transaction](#commitment-transaction) 32 * [Failing a Channel](#failing-a-channel) 33 * [Mutual Close Handling](#mutual-close-handling) 34 * [Unilateral Close Handling: Local Commitment Transaction](#unilateral-close-handling-local-commitment-transaction) 35 * [HTLC Output Handling: Local Commitment, Local Offers](#htlc-output-handling-local-commitment-local-offers) 36 * [HTLC Output Handling: Local Commitment, Remote Offers](#htlc-output-handling-local-commitment-remote-offers) 37 * [Unilateral Close Handling: Remote Commitment Transaction](#unilateral-close-handling-remote-commitment-transaction) 38 * [HTLC Output Handling: Remote Commitment, Local Offers](#htlc-output-handling-remote-commitment-local-offers) 39 * [HTLC Output Handling: Remote Commitment, Remote Offers](#htlc-output-handling-remote-commitment-remote-offers) 40 * [Revoked Transaction Close Handling](#revoked-transaction-close-handling) 41 * [Penalty Transactions Weight Calculation](#penalty-transactions-weight-calculation) 42 * [Generation of HTLC Transactions](#generation-of-htlc-transactions) 43 * [General Requirements](#general-requirements) 44 * [Limitations of v3 transactions](#limitations-of-v3-transactions) 45 * [Appendix A: Expected Weights](#appendix-a-expected-weights) 46 * [Expected Weight of the `to_local` Penalty Transaction Witness](#expected-weight-of-the-to-local-penalty-transaction-witness) 47 * [Expected Weight of the `offered_htlc` Penalty Transaction Witness](#expected-weight-of-the-offered-htlc-penalty-transaction-witness) 48 * [Expected Weight of the `accepted_htlc` Penalty Transaction Witness](#expected-weight-of-the-accepted-htlc-penalty-transaction-witness) 49 * [Authors](#authors) 50 51 # General Nomenclature 52 53 Any unspent output is considered to be *unresolved* and can be *resolved* 54 as detailed in this document. Usually this is accomplished by spending it with 55 another *resolving* transaction. Although, sometimes simply noting the output 56 for later wallet spending is sufficient, in which case the transaction containing 57 the output is considered to be its own *resolving* transaction. 58 59 Outputs that are *resolved* are considered *irrevocably resolved* 60 once the remote's *resolving* transaction is included in a block at least 100 61 deep, on the most-work blockchain. 100 blocks is far greater than the 62 longest known Bitcoin fork and is the same wait time used for 63 confirmations of miners' rewards (see [Reference Implementation](https://github.com/bitcoin/bitcoin/blob/4db82b7aab4ad64717f742a7318e3dc6811b41be/src/consensus/tx_verify.cpp#L223)). 64 65 ## Requirements 66 67 A node: 68 - once it has broadcast a funding transaction OR sent a commitment signature 69 for a commitment transaction that contains an HTLC output: 70 - until all outputs are *irrevocably resolved*: 71 - MUST monitor the blockchain for transactions that spend any output that 72 is NOT *irrevocably resolved*. 73 - MUST *resolve* all outputs, as specified below. 74 - MUST be prepared to resolve outputs multiple times, in case of blockchain 75 reorganizations. 76 - upon the funding transaction being spent, if the channel is NOT already 77 closed: 78 - MAY send a descriptive `error`. 79 - SHOULD fail the channel. 80 - SHOULD ignore invalid transactions. 81 82 ## Rationale 83 84 Once a local node has some funds at stake, monitoring the blockchain is required 85 to ensure the remote node does not close unilaterally. 86 87 Invalid transactions (e.g. bad signatures) can be generated by anyone, 88 (and will be ignored by the blockchain anyway), so they should not 89 trigger any action. 90 91 # Commitment Transaction 92 93 The local and remote nodes each hold a *commitment transaction*. Each of these 94 commitment transactions has up to seven types of outputs: 95 96 1. _local node's main output_: Zero or one output, to pay to the *local node's* 97 delayed_pubkey. 98 2. _remote node's main output_: Zero or one output, to pay to the *remote node's* 99 delayed_pubkey. 100 3. _local node's anchor output_: one output paying to the *local node's* 101 funding_pubkey. 102 4. _remote node's anchor output_: one output paying to the *remote node's* 103 funding_pubkey. 104 5. _shared anchor_: one output spendable by anyone (pay-to-anchor). 105 6. _local node's offered HTLCs_: Zero or more pending payments (*HTLCs*), to pay 106 the *remote node* in return for a payment preimage. 107 7. _remote node's offered HTLCs_: Zero or more pending payments (*HTLCs*), to 108 pay the *local node* in return for a payment preimage. 109 110 To incentivize the local and remote nodes to cooperate, an `OP_CHECKSEQUENCEVERIFY` 111 relative timeout encumbers the *local node's outputs* (in the *local node's 112 commitment transaction*) and the *remote node's outputs* (in the *remote node's 113 commitment transaction*). So for example, if the local node publishes its 114 commitment transaction, it will have to wait to claim its own funds, 115 whereas the remote node will have immediate access to its own funds. As a 116 consequence, the two commitment transactions are not identical, but they are 117 (usually) symmetrical. 118 119 See [BOLT #3: Commitment Transaction](03-transactions.md#commitment-transaction) 120 for more details. 121 122 # Failing a Channel 123 124 Although closing a channel can be accomplished in several ways, the most 125 efficient is preferred. 126 127 Various error cases involve closing a channel. The requirements for sending 128 error messages to peers are specified in 129 [BOLT #1: The `error` Message](01-messaging.md#the-error-message). 130 131 ## Requirements 132 133 A node: 134 - if a *local commitment transaction* has NOT ever contained a `to_local` 135 or HTLC output: 136 - MAY simply forget the channel. 137 - otherwise: 138 - if the *current commitment transaction* does NOT contain `to_local` or 139 other HTLC outputs: 140 - MAY simply wait for the remote node to close the channel. 141 - until the remote node closes: 142 - MUST NOT forget the channel. 143 - otherwise: 144 - if it has received a valid `closing_signed` message that includes a 145 sufficient fee: 146 - SHOULD use this fee to perform a *mutual close*. 147 - otherwise: 148 - if the node knows or assumes its channel state is outdated: 149 - MUST NOT broadcast its *last commitment transaction*. 150 - otherwise: 151 - MUST broadcast the *last commitment transaction*, for which it has a 152 signature, to perform a *unilateral close*. 153 - MUST spend any `to_local_anchor` or `shared_anchor` output, providing sufficient fees 154 as incentive to include the commitment transaction in a block. For `to_local_anchor`, 155 special care must be taken when spending to a third-party, because this re-introduces 156 the pinning vulnerability that was addressed by adding the CSV delay to the non-anchor 157 outputs. 158 - SHOULD use [replace-by-fee](https://github.com/bitcoin/bips/blob/master/bip-0125.mediawiki) 159 or other mechanism on the spending transaction if it proves insufficient for timely 160 inclusion in a block. 161 162 ## Rationale 163 164 Since `dust_limit_satoshis` is supposed to prevent creation of uneconomic 165 outputs (which would otherwise remain forever, unspent on the blockchain), all 166 commitment transaction outputs MUST be spent. 167 168 In the early stages of a channel, it's common for one side to have 169 little or no funds in the channel; in this case, having nothing at stake, a node 170 need not consume resources monitoring the channel state. 171 172 There exists a bias towards preferring mutual closes over unilateral closes, 173 because outputs of the former are unencumbered by a delay and are directly 174 spendable by wallets. In addition, mutual close fees tend to be less exaggerated 175 than those of commitment transactions (or in the case of commitments using anchor 176 outputs, the commitment transaction may require a child transaction to cause it 177 to be mined). So, the only reason not to use the mutual close transaction would 178 be if the fee offered was too small for it to be processed. 179 180 # Mutual Close Handling 181 182 A closing transaction *resolves* the funding transaction output. 183 184 In the case of a mutual close, a node need not do anything else, as it has 185 already agreed to the output, which is sent to its specified `scriptpubkey` (see 186 [BOLT #2: Closing initiation: `shutdown`](02-peer-protocol.md#closing-initiation-shutdown)). 187 188 # Unilateral Close Handling: Local Commitment Transaction 189 190 This is the first of two cases involving unilateral closes. In this case, a 191 node discovers its *local commitment transaction*, which *resolves* the funding 192 transaction output. 193 194 However, a node cannot claim funds from the outputs of a unilateral close that 195 it initiated, until the `OP_CHECKSEQUENCEVERIFY` delay has passed (as specified 196 by the remote node's `to_self_delay` field). Where relevant, this situation is 197 noted below. 198 199 ## Requirements 200 201 A node: 202 - upon discovering its *local commitment transaction*: 203 - SHOULD spend the `to_local` output to a convenient address. 204 - MUST wait until the `OP_CHECKSEQUENCEVERIFY` delay has passed (as 205 specified by the remote node's `to_self_delay` field) before spending the 206 output. 207 - Note: if the output is spent (as recommended), the output is *resolved* 208 by the spending transaction, otherwise it is considered *resolved* by the 209 commitment transaction itself. 210 - MAY ignore the `to_remote` output. 211 - Note: No action is required by the local node, as `to_remote` is 212 considered *resolved* by the commitment transaction itself. 213 - MUST handle HTLCs offered by itself as specified in 214 [HTLC Output Handling: Local Commitment, Local Offers](#htlc-output-handling-local-commitment-local-offers). 215 - MUST handle HTLCs offered by the remote node as 216 specified in [HTLC Output Handling: Local Commitment, Remote Offers](#htlc-output-handling-local-commitment-remote-offers). 217 218 ## Rationale 219 220 Spending the `to_local` output avoids having to remember the complicated 221 witness script, associated with that particular channel, for later 222 spending. 223 224 The `to_remote` output is entirely the business of the remote node, and 225 can be ignored. 226 227 ## HTLC Output Handling: Local Commitment, Local Offers 228 229 Each HTLC output can only be spent by either the *local offerer*, by using the 230 HTLC-timeout transaction after it's timed out, or the *remote recipient*, if it 231 has the payment preimage. 232 233 There can be HTLCs which are not represented by any outputs: either 234 because they were trimmed as dust, or because the transaction has only been 235 partially committed. 236 237 The HTLC output has *timed out* once the height of the latest block is equal to 238 or greater than the HTLC `cltv_expiry`. 239 240 ### Requirements 241 242 A node: 243 - if the commitment transaction HTLC output is spent using the payment 244 preimage, the output is considered *irrevocably resolved*: 245 - MUST extract the payment preimage from the transaction input witness. 246 - if the commitment transaction HTLC output has *timed out* and hasn't been 247 *resolved*: 248 - MUST *resolve* the output by spending it using the HTLC-timeout 249 transaction. 250 - once the resolving transaction has reached reasonable depth: 251 - MUST fail the corresponding incoming HTLC (if any). 252 - MUST resolve the output of that HTLC-timeout transaction. 253 - SHOULD resolve the HTLC-timeout transaction by spending it to a 254 convenient address. 255 - Note: if the output is spent (as recommended), the output is 256 *resolved* by the spending transaction, otherwise it is considered 257 *resolved* by the HTLC-timeout transaction itself. 258 - MUST wait until the `OP_CHECKSEQUENCEVERIFY` delay has passed (as 259 specified by the remote node's `open_channel` `to_self_delay` field) 260 before spending that HTLC-timeout output. 261 - for any committed HTLC that does NOT have an output in this commitment 262 transaction: 263 - if the payment preimage is known: 264 - MUST fulfill the corresponding incoming HTLC (if any). 265 - otherwise: 266 - once the commitment transaction has reached reasonable depth: 267 - MUST fail the corresponding incoming HTLC (if any). 268 - if no *valid* commitment transaction contains an output corresponding to 269 the HTLC: 270 - MAY fail the corresponding incoming HTLC sooner. 271 272 ### Rationale 273 274 The payment preimage either serves to prove payment (when the offering node 275 originated the payment) or to redeem the corresponding incoming HTLC from 276 another peer (when the offering node is forwarding the payment). Once a node has 277 extracted the payment, it no longer cares about the fate of the HTLC-spending 278 transaction itself. 279 280 In cases where both resolutions are possible (e.g. when a node receives payment 281 success after timeout), either interpretation is acceptable; it is the 282 responsibility of the recipient to spend it before this occurs. 283 284 The local HTLC-timeout transaction needs to be used to time out the HTLC (to 285 prevent the remote node fulfilling it and claiming the funds) before the 286 local node can back-fail any corresponding incoming HTLC, using 287 `update_fail_htlc` (presumably with reason `permanent_channel_failure`), as 288 detailed in [BOLT #2](02-peer-protocol.md#forwarding-htlcs). 289 If the incoming HTLC is also on-chain, a node must simply wait for it to 290 timeout: there is no way to signal early failure. 291 292 There are several reasons a committed HTLC may not have an output in the 293 confirmed commitment transaction: the HTLC may be smaller than 294 `dust_limit_satoshis`, the HTLC may not have been added to the commitment 295 transaction yet, or the HTLC may have already been failed or fulfilled. In any 296 case, if the payment preimage is known for the HTLC, the upstream HTLC needs to 297 be fulfilled to avoid loss of funds. 298 299 If the payment preimage is not known for the missing HTLC, the correct action 300 depends on the possibility of a blockchain reorganization that swaps out the 301 confirmed commitment transaction for one with the HTLC present. 302 If the HTLC is too small to appear in *any commitment transaction*, such a 303 reorganization is not possible, and the HTLC can be safely failed immediately. 304 Otherwise, a reorganization delay is required before failing the incoming HTLC. 305 The requirement that the incoming HTLC be failed before its own timeout still 306 applies as an upper bound. 307 308 ## HTLC Output Handling: Local Commitment, Remote Offers 309 310 Each HTLC output can only be spent by the recipient, using the HTLC-success 311 transaction, which it can only populate if it has the payment 312 preimage. If it doesn't have the preimage (and doesn't discover it), it's 313 the offerer's responsibility to spend the HTLC output once it's timed out. 314 315 There are several possible cases for an offered HTLC: 316 317 1. The offerer is NOT irrevocably committed to it. The recipient will usually 318 not know the preimage, since it will not forward HTLCs until they're fully 319 committed. So using the preimage would reveal that this recipient is the 320 final hop; thus, in this case, it's best to allow the HTLC to time out. 321 2. The offerer is irrevocably committed to the offered HTLC, but the recipient 322 has not yet committed to an outgoing HTLC. In this case, the recipient can 323 either forward or timeout the offered HTLC. 324 3. The recipient has committed to an outgoing HTLC, in exchange for the offered 325 HTLC. In this case, the recipient must use the preimage, once it receives it 326 from the outgoing HTLC; otherwise, it will lose funds by sending an outgoing 327 payment without redeeming the incoming payment. 328 329 ### Requirements 330 331 A local node: 332 - if it receives (or already possesses) a payment preimage for an unresolved 333 HTLC output that it has been offered AND for which it has committed to an 334 outgoing HTLC: 335 - MUST *resolve* the output by spending it, using the HTLC-success 336 transaction. 337 - MUST NOT reveal its own preimage when it's not the final recipient.<sup>[Preimage-Extraction](https://lists.linuxfoundation.org/pipermail/lightning-dev/2020-October/002857.html)</sup> 338 - MUST resolve the output of that HTLC-success transaction. 339 - otherwise: 340 - if the *remote node* is NOT irrevocably committed to the HTLC: 341 - MUST NOT *resolve* the output by spending it. 342 - SHOULD resolve that HTLC-success transaction output by spending it to a 343 convenient address. 344 - MUST wait until the `OP_CHECKSEQUENCEVERIFY` delay has passed (as specified 345 by the *remote node's* `open_channel`'s `to_self_delay` field), before 346 spending that HTLC-success transaction output. 347 348 If the output is spent (as is recommended), the output is *resolved* by 349 the spending transaction, otherwise it's considered *resolved* by the HTLC-success 350 transaction itself. 351 352 If it's NOT otherwise resolved, once the HTLC output has expired, it is 353 considered *irrevocably resolved*. 354 355 # Unilateral Close Handling: Remote Commitment Transaction 356 357 The *remote node's* commitment transaction *resolves* the funding 358 transaction output. 359 360 There are no delays constraining node behavior in this case, so it's simpler for 361 a node to handle than the case in which it discovers its local commitment 362 transaction (see [Unilateral Close Handling: Local Commitment Transaction](#unilateral-close-handling-local-commitment-transaction)). 363 364 ## Requirements 365 366 A local node: 367 - upon discovering a *valid* commitment transaction broadcast by a 368 *remote node*: 369 - if possible: 370 - MUST handle each output as specified below. 371 - MAY take no action in regard to the associated `to_remote`, which is 372 simply a P2WPKH output to the *local node*. 373 - Note: `to_remote` is considered *resolved* by the commitment transaction 374 itself. 375 - MAY take no action in regard to the associated `to_local`, which is a 376 payment output to the *remote node*. 377 - Note: `to_local` is considered *resolved* by the commitment transaction 378 itself. 379 - MUST handle HTLCs offered by itself as specified in 380 [HTLC Output Handling: Remote Commitment, Local Offers](#htlc-output-handling-remote-commitment-local-offers) 381 - MUST handle HTLCs offered by the remote node as specified in 382 [HTLC Output Handling: Remote Commitment, Remote Offers](#htlc-output-handling-remote-commitment-remote-offers) 383 - otherwise (it is NOT able to handle the broadcast for some reason): 384 - MUST inform the user of potentially lost funds. 385 386 ## Rationale 387 388 There may be more than one valid, *unrevoked* commitment transaction after a 389 signature has been received via `commitment_signed` and before the corresponding 390 `revoke_and_ack`. As such, either commitment may serve as the *remote node's* 391 commitment transaction; hence, the local node is required to handle both. 392 393 In the case of data loss, a local node may reach a state where it doesn't 394 recognize all of the *remote node's* commitment transaction HTLC outputs. It can 395 detect the data loss state, because it has signed the transaction, and the 396 commitment number is greater than expected. It can derive its own `remotepubkey` for the 397 transaction, in order to salvage its own funds. Note: in this scenario, the node 398 will be unable to salvage the HTLCs. 399 400 ## HTLC Output Handling: Remote Commitment, Local Offers 401 402 Each HTLC output can only be spent by either the *local offerer*, after it's 403 timed out, or by the *remote recipient*, by using the HTLC-success transaction 404 if it has the payment preimage. 405 406 There can be HTLCs which are not represented by any outputs: either 407 because the outputs were trimmed as dust, or because the remote node has two 408 *valid* commitment transactions with differing HTLCs. 409 410 The HTLC output has *timed out* once the depth of the latest block is equal to 411 or greater than the HTLC `cltv_expiry`. 412 413 ### Requirements 414 415 A local node: 416 - if the commitment transaction HTLC output is spent using the payment 417 preimage: 418 - MUST extract the payment preimage from the HTLC-success transaction input 419 witness. 420 - Note: the output is considered *irrevocably resolved*. 421 - if the commitment transaction HTLC output has *timed out* AND NOT been 422 *resolved*: 423 - MUST *resolve* the output, by spending it to a convenient address. 424 - for any committed HTLC that does NOT have an output in this commitment 425 transaction: 426 - if the payment preimage is known: 427 - MUST fulfill the corresponding incoming HTLC (if any). 428 - otherwise: 429 - once the commitment transaction has reached reasonable depth: 430 - MUST fail the corresponding incoming HTLC (if any). 431 - if no *valid* commitment transaction contains an output corresponding to 432 the HTLC: 433 - MAY fail the corresponding incoming HTLC sooner. 434 435 ### Rationale 436 437 If the commitment transaction belongs to the *remote* node, the only way for it 438 to spend the HTLC output (using a payment preimage) is for it to use the 439 HTLC-success transaction. 440 441 The payment preimage either serves to prove payment (when the offering node is 442 the originator of the payment) or to redeem the corresponding incoming HTLC from 443 another peer (when the offering node is forwarding the payment). After a node has 444 extracted the payment, it no longer need be concerned with the fate of the 445 HTLC-spending transaction itself. 446 447 In cases where both resolutions are possible (e.g. when a node receives payment 448 success after timeout), either interpretation is acceptable: it's the 449 responsibility of the recipient to spend it before this occurs. 450 451 Once it has timed out, the local node needs to spend the HTLC output (to prevent 452 the remote node from using the HTLC-success transaction) before it can 453 back-fail any corresponding incoming HTLC, using `update_fail_htlc` 454 (presumably with reason `permanent_channel_failure`), as detailed in 455 [BOLT #2](02-peer-protocol.md#forwarding-htlcs). 456 If the incoming HTLC is also on-chain, a node simply waits for it to 457 timeout, as there's no way to signal early failure. 458 459 There are several reasons a committed HTLC may not have an output in the 460 confirmed commitment transaction: the HTLC may be smaller than 461 `dust_limit_satoshis`, the HTLC may not have been added to the commitment 462 transaction yet, or the HTLC may have already been failed or fulfilled. In any 463 case, if the payment preimage is known for the HTLC, the upstream HTLC needs to 464 be fulfilled to avoid loss of funds. 465 466 If the payment preimage is not known for the missing HTLC, the correct action 467 depends on the possibility of a blockchain reorganization that swaps out the 468 confirmed commitment transaction for one with the HTLC present. 469 If the HTLC is too small to appear in *any commitment transaction*, such a 470 reorganization is not possible, and the HTLC can be safely failed immediately. 471 Otherwise, a reorganization delay is required before failing the incoming HTLC. 472 The requirement that the incoming HTLC be failed before its own timeout still 473 applies as an upper bound. 474 475 ## HTLC Output Handling: Remote Commitment, Remote Offers 476 477 The remote HTLC outputs can only be spent by the local node if it has the 478 payment preimage. If the local node does not have the preimage (and doesn't 479 discover it), it's the remote node's responsibility to spend the HTLC output 480 once it's timed out. 481 482 There are actually several possible cases for an offered HTLC: 483 484 1. The offerer is not irrevocably committed to it. In this case, the recipient 485 usually won't know the preimage, since it won't forward HTLCs until 486 they're fully committed. As using the preimage would reveal that 487 this recipient is the final hop, it's best to allow the HTLC to time out. 488 2. The offerer is irrevocably committed to the offered HTLC, but the recipient 489 hasn't yet committed to an outgoing HTLC. In this case, the recipient can 490 either forward it or wait for it to timeout. 491 3. The recipient has committed to an outgoing HTLC in exchange for an offered 492 HTLC. In this case, the recipient must use the preimage, if it receives it 493 from the outgoing HTLC; otherwise, it will lose funds by sending an outgoing 494 payment without redeeming the incoming one. 495 496 ### Requirements 497 498 A local node: 499 - if it receives (or already possesses) a payment preimage for an unresolved 500 HTLC output that it was offered AND for which it has committed to an 501 outgoing HTLC: 502 - MUST *resolve* the output by spending it to a convenient address. 503 - otherwise: 504 - if the remote node is NOT irrevocably committed to the HTLC: 505 - MUST NOT *resolve* the output by spending it. 506 507 If not otherwise resolved, once the HTLC output has expired, it is considered 508 *irrevocably resolved*. 509 510 # Revoked Transaction Close Handling 511 512 If any node tries to cheat by broadcasting an outdated commitment transaction 513 (any previous commitment transaction besides the most current one), the other 514 node in the channel can use its revocation private key to claim all the funds from the 515 channel's original funding transaction. 516 517 ## Requirements 518 519 Once a node discovers a commitment transaction for which *it* has a 520 revocation private key, the funding transaction output is *resolved*. 521 522 A local node: 523 - MUST NOT broadcast a commitment transaction for which *it* has exposed the 524 `per_commitment_secret`. 525 - MAY take no action regarding the _local node's main output_, as this is a 526 simple P2WPKH output to itself. 527 - Note: this output is considered *resolved* by the commitment transaction 528 itself. 529 - MUST *resolve* the _remote node's main output_ by spending it using the 530 revocation private key. 531 - MUST *resolve* the _remote node's offered HTLCs_ in one of three ways: 532 * spend the *commitment tx* using the payment revocation private key. 533 * spend the *commitment tx* using the payment preimage (if known). 534 * spend the *HTLC-timeout tx*, if the remote node has published it. 535 - MUST *resolve* the _local node's offered HTLCs_ in one of three ways: 536 * spend the *commitment tx* using the payment revocation private key. 537 * spend the *commitment tx* once the HTLC timeout has passed. 538 * spend the *HTLC-success tx*, if the remote node has published it. 539 - MUST *resolve* the _remote node's HTLC-timeout transaction_ by spending it 540 using the revocation private key. 541 - MUST *resolve* the _remote node's HTLC-success transaction_ by spending it 542 using the revocation private key. 543 - SHOULD extract the payment preimage from the transaction input witness, if 544 it's not already known. 545 - if `SIGHASH_SINGLE|SIGHASH_ANYONECANPAY` is used for HTLC transactions 546 (i.e. `option_anchors` or `zero_fee_commitments` applies): 547 - MAY use a single transaction to *resolve* all the outputs. 548 - If `zero_fee_commitments` applies: 549 - MUST NOT exceed the 10kvB limit of v3 transactions, otherwise the 550 transaction may not reach miners (as explained in the section 551 about [v3 limitations](#limitations-of-v3-transactions) below). 552 - if confirmation doesn't happen before reaching `security_delay` blocks from 553 expiry: 554 - SHOULD *resolve* revoked outputs in their own, separate penalty transactions. A previous 555 penalty transaction claiming multiple revoked outputs at once may be blocked from confirming 556 because of a transaction pinning attack. 557 - otherwise: 558 - MAY use a single transaction to *resolve* all the outputs. 559 - MUST handle its transactions being invalidated by HTLC transactions. 560 561 ## Rationale 562 563 A single transaction that resolves all the outputs will be under the 564 standard size limit because of the 483 HTLC-per-party limit (see 565 [BOLT #2](02-peer-protocol.md#the-open_channel-message)). 566 567 Note: when `SIGHASH_SINGLE|SIGHASH_ANYONECANPAY` is used for HTLC transactions 568 (i.e. `option_anchors` or `zero_fee_commitments`), the cheating node can pin 569 spends of its HTLC-timeout/HTLC-success outputs. 570 Using a single penalty transaction for all revoked outputs is thus unsafe as it 571 could be blocked to propagate long enough for the _local node's `to_local` output_ 's 572 relative locktime to expire and the cheating party escaping the penalty on this 573 output. Though this situation doesn't prevent faithful punishment of the second-level 574 revoked output if the pinning transaction confirms. 575 576 The `security_delay` is a fixed-point relative to the absolute expiration of 577 the revoked output at which the punishing node must broadcast a single-spend 578 transaction for the revoked output and actively fee-bump it until its confirmation. 579 The exact value of `security_delay` is left as a matter of node policy, though we 580 recommend 18 blocks (similar to incoming HTLC deadline). 581 582 ## Penalty Transactions Weight Calculation 583 584 There are three different scripts for penalty transactions, with the following 585 witness weights (details of weight computation are in 586 [Appendix A](#appendix-a-expected-weights)): 587 588 to_local_penalty_witness: 160 bytes 589 offered_htlc_penalty_witness: 243 bytes 590 accepted_htlc_penalty_witness: 249 bytes 591 592 The penalty *txinput* itself takes up 41 bytes and has a weight of 164 bytes, 593 which results in the following weights for each input: 594 595 to_local_penalty_input_weight: 324 bytes 596 offered_htlc_penalty_input_weight: 407 bytes 597 accepted_htlc_penalty_input_weight: 413 bytes 598 599 The rest of the penalty transaction takes up 4+1+1+8+1+34+4=53 bytes of 600 non-witness data: assuming it has a pay-to-witness-script-hash (the largest 601 standard output script), in addition to a 2-byte witness header. 602 603 In addition to spending these outputs, a penalty transaction may optionally 604 spend the commitment transaction's `to_remote` output (e.g. to reduce the total 605 amount paid in fees). Doing so requires the inclusion of a P2WPKH witness and an 606 additional *txinput*, resulting in an additional 108 + 164 = 272 bytes. 607 608 In the worst case scenario, the node holds only incoming HTLCs, and the 609 HTLC-timeout transactions are not published, which forces the node to spend from 610 the commitment transaction. 611 612 With a maximum standard weight of 400000 bytes, the maximum number of HTLCs that 613 can be swept in a single transaction is as follows: 614 615 max_num_htlcs = (400000 - 324 - 272 - (4 * 53) - 2) / 413 = 966 616 617 Thus, 483 bidirectional HTLCs (containing both `to_local` and 618 `to_remote` outputs) can be resolved in a single penalty transaction. 619 Note: even if the `to_remote` output is not swept, the resulting 620 `max_num_htlcs` is 967; which yields the same unidirectional limit of 483 HTLCs. 621 622 # Generation of HTLC Transactions 623 624 If `option_anchors` and `zero_fee_commitments` do not apply, then HTLC-timeout 625 and HTLC-success transactions are signed with `SIGHASH_ALL` and are complete 626 transactions with (hopefully!) reasonable fees and must be used directly. 627 628 Otherwise, `SIGHASH_SINGLE|SIGHASH_ANYONECANPAY` MUST be used on the 629 HTLC signatures received from the peer, as this allows HTLC transactions to be 630 combined with other transactions. The local signature MUST use `SIGHASH_ALL`, 631 otherwise anyone can attach additional inputs and outputs to the tx. 632 633 If `SIGHASH_SINGLE|SIGHASH_ANYONECANPAY` is used, then the HTLC-timeout and 634 HTLC-success transactions are signed with the input and output having the 635 same value. This means they have a zero fee and MUST be combined with other 636 inputs to arrive at a reasonable fee. 637 638 ## Requirements 639 640 A node which broadcasts an HTLC-success or HTLC-timeout transaction for a 641 commitment transaction: 642 - if `SIGHASH_SINGLE|SIGHASH_ANYONECANPAY` is used: 643 - MUST combine it with inputs contributing sufficient fee to ensure timely 644 inclusion in a block. 645 - MAY combine it with other transactions. 646 647 # General Requirements 648 649 A node: 650 - upon discovering a transaction that spends a funding transaction output 651 which does not fall into one of the above categories (mutual close, unilateral 652 close, or revoked transaction close): 653 - MUST warn the user of potentially lost funds. 654 - Note: the existence of such a rogue transaction implies that its private 655 key has leaked and that its funds may be lost as a result. 656 - MAY simply monitor the contents of the most-work chain for transactions. 657 - Note: on-chain HTLCs should be sufficiently rare that speed need not be 658 considered critical. 659 - MAY monitor (valid) broadcast transactions (a.k.a the mempool). 660 - Note: watching for mempool transactions should result in lower latency 661 HTLC redemptions. 662 663 ## Limitations of v3 transactions 664 665 When `zero_fee_commitments` applies, we use v3 transactions, also known as 666 TRUC transactions, which have different policy rules than v2 transactions. 667 668 Implementers should read [BIP-431](https://github.com/bitcoin/bips/blob/master/bip-0431.mediawiki) 669 to make sure they don't create transactions that aren't relayed by bitcoin 670 nodes. 671 672 The main limitation compared to v2 transactions (but not the only one) is 673 that transactions are restricted to 10kvB (instead of 400kvB): when batching 674 transactions (e.g. HTLC transactions), nodes MUST NOT exceed that limit, 675 otherwise the transaction will not reach miners and funds may be at risk. 676 677 # Appendix A: Expected Weights 678 679 ## Expected Weight of the `to_local` Penalty Transaction Witness 680 681 As described in [BOLT #3](03-transactions.md), the witness for this transaction 682 is: 683 684 <sig> 1 { OP_IF <revocationpubkey> OP_ELSE to_self_delay OP_CSV OP_DROP <local_delayedpubkey> OP_ENDIF OP_CHECKSIG } 685 686 The *expected weight* of the `to_local` penalty transaction witness is 687 calculated as follows: 688 689 to_local_script: 83 bytes 690 - OP_IF: 1 byte 691 - OP_DATA: 1 byte (revocationpubkey length) 692 - revocationpubkey: 33 bytes 693 - OP_ELSE: 1 byte 694 - OP_DATA: 1 byte (delay length) 695 - delay: 8 bytes 696 - OP_CHECKSEQUENCEVERIFY: 1 byte 697 - OP_DROP: 1 byte 698 - OP_DATA: 1 byte (local_delayedpubkey length) 699 - local_delayedpubkey: 33 bytes 700 - OP_ENDIF: 1 byte 701 - OP_CHECKSIG: 1 byte 702 703 to_local_penalty_witness: 160 bytes 704 - number_of_witness_elements: 1 byte 705 - revocation_sig_length: 1 byte 706 - revocation_sig: 73 bytes 707 - one_length: 1 byte 708 - witness_script_length: 1 byte 709 - witness_script (to_local_script) 710 711 ## Expected Weight of the `offered_htlc` Penalty Transaction Witness 712 713 The *expected weight* of the `offered_htlc` penalty transaction witness is 714 calculated as follows (some calculations have already been made in 715 [BOLT #3](03-transactions.md)): 716 717 offered_htlc_script: 133 bytes 718 719 offered_htlc_penalty_witness: 243 bytes 720 - number_of_witness_elements: 1 byte 721 - revocation_sig_length: 1 byte 722 - revocation_sig: 73 bytes 723 - revocation_key_length: 1 byte 724 - revocation_key: 33 bytes 725 - witness_script_length: 1 byte 726 - witness_script (offered_htlc_script) 727 728 ## Expected Weight of the `accepted_htlc` Penalty Transaction Witness 729 730 The *expected weight* of the `accepted_htlc` penalty transaction witness is 731 calculated as follows (some calculations have already been made in 732 [BOLT #3](03-transactions.md)): 733 734 accepted_htlc_script: 139 bytes 735 736 accepted_htlc_penalty_witness: 249 bytes 737 - number_of_witness_elements: 1 byte 738 - revocation_sig_length: 1 byte 739 - revocation_sig: 73 bytes 740 - revocationpubkey_length: 1 byte 741 - revocationpubkey: 33 bytes 742 - witness_script_length: 1 byte 743 - witness_script (accepted_htlc_script) 744 745 # Authors 746 747 [FIXME:] 748 749  750 <br> 751 This work is licensed under a [Creative Commons Attribution 4.0 International License](http://creativecommons.org/licenses/by/4.0/).