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