diff --git a/.aspell.en.pws b/.aspell.en.pws index 97b6ebdbd..abe98781f 100644 --- a/.aspell.en.pws +++ b/.aspell.en.pws @@ -371,3 +371,6 @@ tlvs snprintf GitHub IRC +SIGHASH +ANYONECANPAY +pushme diff --git a/02-peer-protocol.md b/02-peer-protocol.md index 4c94c5408..70aa7743a 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -121,6 +121,7 @@ the funding transaction and both versions of the commitment transaction. * [`point`:`payment_basepoint`] * [`point`:`delayed_payment_basepoint`] * [`point`:`htlc_basepoint`] + * [`point`:`anchor_pubkey`] (`option_anchor_outputs`) * [`point`:`first_per_commitment_point`] * [`byte`:`channel_flags`] * [`u16`:`shutdown_len`] (`option_upfront_shutdown_script`) @@ -157,7 +158,10 @@ node can offer. (i.e. 1/4 the more normally-used 'satoshi per 1000 vbytes') that this side will pay for commitment and HTLC transactions, as described in [BOLT #3](03-transactions.md#fee-calculation) (this can be adjusted -later with an `update_fee` message). +later with an `update_fee` message). Note that if +`option_anchor_outputs` is negotiated, this `feerate_per_kw` +can be set to the min relay fee. It is still possible to increase the fee rate +during the lifetime of the channel using the `update_fee` message. `to_self_delay` is the number of blocks that the other node's to-self outputs must be delayed, using `OP_CHECKSEQUENCEVERIFY` delays; this @@ -175,6 +179,10 @@ even if one commitment transaction is seen; this property is very useful for preserving privacy when outsourcing penalty transactions to third parties. +`anchor_pubkey` is the public key to which the anchor output of the channel +initiator pays. This is a key separate from `payment_basepoint` because anchoring +may happen from a different (hot) wallet. + `first_per_commitment_point` is the per-commitment point to be used for the first commitment transaction, @@ -196,7 +204,7 @@ The sending node: - MUST ensure `temporary_channel_id` is unique from any other channel ID with the same peer. - MUST set `funding_satoshis` to less than 2^24 satoshi. - MUST set `push_msat` to equal or less than 1000 * `funding_satoshis`. - - MUST set `funding_pubkey`, `revocation_basepoint`, `htlc_basepoint`, `payment_basepoint`, and `delayed_payment_basepoint` to valid DER-encoded, compressed, secp256k1 pubkeys. + - MUST set `funding_pubkey`, `revocation_basepoint`, `htlc_basepoint`, `payment_basepoint`, `delayed_payment_basepoint` and `anchor_pubkey` to valid DER-encoded, compressed, secp256k1 pubkeys. - MUST set `first_per_commitment_point` to the per-commitment point to be used for the initial commitment transaction, derived as specified in [BOLT #3](03-transactions.md#per-commitment-secret-requirements). - MUST set `channel_reserve_satoshis` greater than or equal to `dust_limit_satoshis`. - MUST set undefined bits in `channel_flags` to 0. @@ -233,7 +241,9 @@ The receiving node MUST fail the channel if: - `to_self_delay` is unreasonably large. - `max_accepted_htlcs` is greater than 483. - it considers `feerate_per_kw` too small for timely processing or unreasonably large. - - `funding_pubkey`, `revocation_basepoint`, `htlc_basepoint`, `payment_basepoint`, or `delayed_payment_basepoint` + This range can be narrow for `option_anchor_outputs`, because both parties have the option to pay + for the transaction with a child (cpfp). + - `funding_pubkey`, `revocation_basepoint`, `htlc_basepoint`, `payment_basepoint`, `delayed_payment_basepoint` or `anchor_pubkey` are not valid DER-encoded compressed secp256k1 pubkeys. - `dust_limit_satoshis` is greater than `channel_reserve_satoshis`. - the funder's amount for the initial commitment transaction is not sufficient for full [fee payment](03-transactions.md#fee-payment). @@ -291,6 +301,7 @@ funding transaction and both versions of the commitment transaction. * [`point`:`payment_basepoint`] * [`point`:`delayed_payment_basepoint`] * [`point`:`htlc_basepoint`] + * [`point`:`anchor_pubkey`] (`option_anchor_outputs`) * [`point`:`first_per_commitment_point`] * [`u16`:`shutdown_len`] (`option_upfront_shutdown_script`) * [`shutdown_len*byte`:`shutdown_scriptpubkey`] (`option_upfront_shutdown_script`) @@ -367,10 +378,10 @@ This message introduces the `channel_id` to identify the channel. It's derived f #### Requirements Both peers: - - if `option_static_remotekey` was negotiated: - - `option_static_remotekey` applies to all commitment transactions + - if `option_static_remotekey` or `option_anchor_outputs` was negotiated: + - `option_static_remotekey` or `option_anchor_outputs` applies to all commitment transactions - otherwise: - - `option_static_remotekey` does not apply to any commitment transactions + - `option_static_remotekey` or `option_anchor_outputs` does not apply to any commitment transactions The sender MUST set: - `channel_id` by exclusive-OR of the `funding_txid` and the `funding_output_index` from the `funding_created` message. @@ -385,9 +396,8 @@ The recipient: #### Rationale -We decide on `option_static_remotekey` at this point when we first have to generate the commitment -transaction. Even if a later reconnection does not negotiate this parameter, this channel will continue to use `option_static_remotekey`; we don't support "downgrading". -This simplifies channel state, particularly penalty transaction handling. +We decide on `option_static_remotekey` or `option_anchor_outputs` at this point when we first have to generate the commitment +transaction. Even if a later reconnection does not negotiate this parameter, this channel will continue to use `option_static_remotekey` or `option_anchor_outputs`; we don't support "downgrading". ### The `funding_locked` Message @@ -548,8 +558,11 @@ The funding node: - SHOULD send a `closing_signed` message. The sending node: - - MUST set `fee_satoshis` less than or equal to the - base fee of the final commitment transaction, as calculated in [BOLT #3](03-transactions.md#fee-calculation). + - if `option_anchor_outputs` applies to the final commitment transaction: + - MUST set `fee_satoshis` greater or equal to the base fee of the final commitment transaction. + - otherwise: + - MUST set `fee_satoshis` less than or equal to the +base fee of the final commitment transaction, as calculated in [BOLT #3](03-transactions.md#fee-calculation). - SHOULD set the initial `fee_satoshis` according to its estimate of cost of inclusion in a block. - MUST set `signature` to the Bitcoin signature of the close @@ -562,10 +575,14 @@ The receiving node: - if `fee_satoshis` is equal to its previously sent `fee_satoshis`: - SHOULD sign and broadcast the final closing transaction. - MAY close the connection. - - otherwise, if `fee_satoshis` is greater than -the base fee of the final commitment transaction as calculated in -[BOLT #3](03-transactions.md#fee-calculation): - - MUST fail the connection. + - if `option_anchor_outputs` applies to the final commitment transaction: + - if `fee_satoshis` is less than the base fee of the final commitment transaction + - MUST fail the connection. + - otherwise (no `option_anchor_outputs`): + - if `fee_satoshis` is greater than + the base fee of the final commitment transaction as calculated in + [BOLT #3](03-transactions.md#fee-calculation): + - MUST fail the connection. - if `fee_satoshis` is not strictly between its last-sent `fee_satoshis` and its previously-received `fee_satoshis`, UNLESS it has since reconnected: @@ -583,6 +600,13 @@ progress is made, even if only by a single satoshi at a time. To avoid keeping state and to handle the corner case, where fees have shifted between disconnection and reconnection, negotiation restarts on reconnection. +In the `option_anchor_outputs` case, the fees on the commitment +transaction itself are minimal (it is assumed that a child transaction will +supply additional fee incentive), so that forms a floor for negotiation. + +Otherwise, the commitment transaction usually pays a premium fee, so that +forms a ceiling. + Note there is limited risk if the closing transaction is delayed, but it will be broadcast very soon; so there is usually no reason to pay a premium for rapid processing. @@ -802,7 +826,12 @@ is destined, is described in [BOLT #4](04-onion-routing.md). A sending node: - MUST NOT offer `amount_msat` it cannot pay for in the remote commitment transaction at the current `feerate_per_kw` (see "Updating -Fees") while maintaining its channel reserve. +Fees") while maintaining its channel reserve + - if `option_anchor_outputs` applies to this commitment transaction and the sending + node is the funder: + - MUST be able to additionally pay for `to_local_anchor` and + `to_remote_anchor` above its reserve. The anchor value should assumed to be + the maximum of the dust limits that have been negotiated by both parties. - MUST offer `amount_msat` greater than 0. - MUST NOT offer `amount_msat` below the receiving node's `htlc_minimum_msat` - MUST set `cltv_expiry` less than 500000000. @@ -824,7 +853,7 @@ been received). It MUST continue incrementing instead. A receiving node: - receiving an `amount_msat` equal to 0, OR less than its own `htlc_minimum_msat`: - SHOULD fail the channel. - - receiving an `amount_msat` that the sending node cannot afford at the current `feerate_per_kw` (while maintaining its channel reserve): + - receiving an `amount_msat` that the sending node cannot afford at the current `feerate_per_kw` (while maintaining its channel reserve and any `to_local_anchor` and `to_remote_anchor` costs): - SHOULD fail the channel. - if a sending node adds more than receiver `max_accepted_htlcs` HTLCs to its local commitment transaction, OR adds more than receiver `max_htlc_value_in_flight_msat` worth of offered HTLCs to its local commitment transaction: @@ -980,6 +1009,8 @@ fee changes). to the ordering of the commitment transaction (see [BOLT #3](03-transactions.md#transaction-input-and-output-ordering)). - if it has not recently received a message from the remote node: - SHOULD use `ping` and await the reply `pong` before sending `commitment_signed`. + - if `option_anchor_outputs` applies to this commitment transaction: + - MUST calculate each `htlc_signature` using `SIGHASH_SINGLE|SIGHASH_ANYONECANPAY` A receiving node: - once all pending updates are applied: @@ -1007,6 +1038,8 @@ output HTLCs are fully resolved. Note that the `htlc_signature` implicitly enforces the time-lock mechanism in the case of offered HTLCs being timed out or received HTLCs being spent. This is done to reduce fees by creating smaller scripts compared to explicitly stating time-locks on HTLC outputs. +The `option_anchor_outputs` allows HTLC transactions to "bring their own fees" by attaching other inputs and outputs, hence the modified signature flags. + ### Completing the Transition to the Updated State: `revoke_and_ack` Once the recipient of `commitment_signed` checks the signature and knows @@ -1106,6 +1139,10 @@ it's simplest to only allow it to set fee levels; however, as the same fee rate applies to HTLC transactions, the receiving node must also care about the reasonableness of the fee. +With `option_anchor_outputs`, `feerate_per_kw` is not as critical anymore to +guarantuee confirmation, but it still needs to be able to satisfy the min relay +fee. + ## Message Retransmission Because communication transports are unreliable, and may need to be diff --git a/03-transactions.md b/03-transactions.md index c72bd0981..cc6568fac 100644 --- a/03-transactions.md +++ b/03-transactions.md @@ -100,14 +100,14 @@ This output sends funds back to the owner of this commitment transaction and thu # Penalty transaction OP_ELSE - `to_self_delay` + `local_to_self_delay` OP_CHECKSEQUENCEVERIFY OP_DROP OP_ENDIF OP_CHECKSIG -The output is spent by a transaction with `nSequence` field set to `to_self_delay` (which can only be valid after that duration has passed) and witness: +The output is spent by a transaction with `nSequence` field set to `to_local_self_delay` (which can only be valid after that duration has passed) and witness: 0 @@ -117,17 +117,62 @@ If a revoked commitment transaction is published, the other party can spend this #### `to_remote` Output -This output sends funds to the other peer and thus is a simple P2WPKH to `remotepubkey`. +This output sends funds to the other peer, thus is not encumbered by a +revocation private key. + +If `option_anchor_outputs` applies to the commitment transaction, the `to_remote` output is delayed similarly to the `to_local` output, and is to a fixed key: + + `remote_to_self_delay` + OP_CSV + OP_DROP + + OP_CHECKSIG + +The output is spent by a transaction with `nSequence` field set to `to_remote_self_delay` (which can only be valid after that duration has passed) and witness: + + + +Otherwise, this output is a simple P2WPKH to `remotepubkey`. + + +#### `to_local_anchor` and `to_remote_anchor` Output (option_anchor_outputs) + +This output can be spent by the local and remote nodes respectively to provide incentive to mine the transaction, using child-pays-for-parent. Both +anchor outputs are always added, except for the case where there are no htlcs and one of the parties has a commitment output that is below the dust limit. +In that case only an anchor is added for the commitment output that does materialize. This typically happens if the initiator closes right after opening (no `to_remote` output). +The outputs are regular P2WPKH outputs to `local_anchorpubkey` and `remote_anchorpubkey`. These are likely to be wallet addresses which can be +used to fund a future transaction. + +The size of the output is equal to the dust limit negotiated by the party that publishes the transaction. #### Offered HTLC Outputs -This output sends funds to either an HTLC-timeout transaction after the HTLC-timeout or to the remote node using the payment preimage or the revocation key. The output is a P2WSH, with a witness script: +This output sends funds to either an HTLC-timeout transaction after the HTLC-timeout or to the remote node using the payment preimage or the revocation key. The output is a P2WSH, with a witness script (no option_anchor_outputs): + + # To remote node with revocation key + OP_DUP OP_HASH160 OP_EQUAL + OP_IF + OP_CHECKSIG + OP_ELSE + OP_SWAP OP_SIZE 32 OP_EQUAL + OP_NOTIF + # To local node via HTLC-timeout transaction (timelocked). + OP_DROP 2 OP_SWAP 2 OP_CHECKMULTISIG + OP_ELSE + # To remote node with preimage. + OP_HASH160 OP_EQUALVERIFY + OP_CHECKSIG + OP_ENDIF + OP_ENDIF + +Or, with `option_anchor_outputs`: # To remote node with revocation key OP_DUP OP_HASH160 OP_EQUAL OP_IF OP_CHECKSIG OP_ELSE + 1 OP_CHECKSEQUENCEVERIFY OP_DROP OP_SWAP OP_SIZE 32 OP_EQUAL OP_NOTIF # To local node via HTLC-timeout transaction (timelocked). @@ -151,7 +196,7 @@ The sending node can use the HTLC-timeout transaction to timeout the HTLC once t #### Received HTLC Outputs -This output sends funds to either the remote node after the HTLC-timeout or using the revocation key, or to an HTLC-success transaction with a successful payment preimage. The output is a P2WSH, with a witness script: +This output sends funds to either the remote node after the HTLC-timeout or using the revocation key, or to an HTLC-success transaction with a successful payment preimage. The output is a P2WSH, with a witness script (no `option_anchor_outputs`): # To remote node with revocation key OP_DUP OP_HASH160 OP_EQUAL @@ -170,6 +215,26 @@ This output sends funds to either the remote node after the HTLC-timeout or usin OP_ENDIF OP_ENDIF +Or, with `option_anchor_outputs`: + + # To remote node with revocation key + OP_DUP OP_HASH160 OP_EQUAL + OP_IF + OP_CHECKSIG + OP_ELSE + 1 OP_CHECKSEQUENCEVERIFY OP_DROP + OP_SWAP OP_SIZE 32 OP_EQUAL + OP_IF + # To local node via HTLC-success transaction. + OP_HASH160 OP_EQUALVERIFY + 2 OP_SWAP 2 OP_CHECKMULTISIG + OP_ELSE + # To remote node after timeout. + OP_DROP OP_CHECKLOCKTIMEVERIFY OP_DROP + OP_CHECKSIG + OP_ENDIF + OP_ENDIF + To timeout the HTLC, the remote node spends it with the witness: 0 @@ -191,7 +256,7 @@ limit. #### Requirements -The base fee: +The base fee and anchor output values: - before the commitment transaction outputs are determined: - MUST be subtracted from the `to_local` or `to_remote` outputs, as specified in [Fee Calculation](#fee-calculation). @@ -313,10 +378,12 @@ Thus, a simplified formula for *expected weight* is used, which assumes: * Signatures are 73 bytes long (the maximum length). * There are a small number of outputs (thus 1 byte to count them). * There are always both a `to_local` output and a `to_remote` output. +* (if `option_anchor_outputs`) there are always both a `to_local_anchor` and `to_remote_anchor` output. This yields the following *expected weights* (details of the computation in [Appendix A](#appendix-a-expected-weights)): - Commitment weight: 724 + 172 * num-untrimmed-htlc-outputs + Commitment weight (no option_anchor_outputs): 724 + 172 * num-untrimmed-htlc-outputs + Commitment weight (option_anchor_outputs): + 172 * num-untrimmed-htlc-outputs HTLC-timeout weight: 663 HTLC-success weight: 703 @@ -373,7 +440,7 @@ outputs) is 7140 satoshi. The final fee may be even higher if the ### Fee Payment -Base commitment transaction fees are extracted from the funder's amount; if that amount is insufficient, the entire amount of the funder's output is used. +Base commitment transaction fees and amounts for `to_local_anchor` and `to_remote_anchor` outputs are extracted from the funder's amount; if that amount is insufficient, the entire amount of the funder's output is used. Note that after the fee amount is subtracted from the to-funder output, that output may be below `dust_limit_satoshis`, and thus will also @@ -395,17 +462,21 @@ committed HTLCs: in [Commitment Transaction](#commitment-transaction). 1. Calculate which committed HTLCs need to be trimmed (see [Trimmed Outputs](#trimmed-outputs)). 2. Calculate the base [commitment transaction fee](#fee-calculation). -3. Subtract this base fee from the funder (either `to_local` or `to_remote`), - with a floor of 0 (see [Fee Payment](#fee-payment)). -3. For every offered HTLC, if it is not trimmed, add an +3. Subtract this base fee from the funder (either `to_local` or `to_remote`). +If `option_anchor_outputs` applies to the commitment transaction, +also subtract two times the local `dust_limit_satoshis` from the funder +(either `to_local` or `to_remote`). Keep a floor of 0 (see [Fee Payment](#fee-payment)). +4. For every offered HTLC, if it is not trimmed, add an [offered HTLC output](#offered-htlc-outputs). -4. For every received HTLC, if it is not trimmed, add an +5. For every received HTLC, if it is not trimmed, add an [received HTLC output](#received-htlc-outputs). -5. If the `to_local` amount is greater or equal to `dust_limit_satoshis`, +6. If the `to_local` amount is greater or equal to `dust_limit_satoshis`, add a [`to_local` output](#to_local-output). -6. If the `to_remote` amount is greater or equal to `dust_limit_satoshis`, +7. If the `to_remote` amount is greater or equal to `dust_limit_satoshis`, add a [`to_remote` output](#to_remote-output). -7. Sort the outputs into [BIP 69+CLTV order](#transaction-input-and-output-ordering). +8. If `option_anchor_outputs` applies to the commitment transaction, add + `to_local_anchor` and `to_remote_anchor`. +9. Sort the outputs into [BIP 69+CLTV order](#transaction-input-and-output-ordering). # Keys @@ -413,7 +484,9 @@ committed HTLCs: Each commitment transaction uses a unique `localpubkey`, and a `remotepubkey`. The HTLC-success and HTLC-timeout transactions use `local_delayedpubkey` and `revocationpubkey`. -These are changed for every transaction based on the `per_commitment_point`, with the exception of `remotepubkey` if `option_static_remotekey` is negotiated. +These are changed for every transaction based on the `per_commitment_point`. +For `option_static_remotekey` and `option_anchor_outputs`, no key rotation +is appllied to `remotepubkey`. The reason for key change is so that trustless watching for revoked transactions can be outsourced. Such a _watcher_ should not be able to @@ -449,6 +522,7 @@ These pubkeys are simply generated by addition from their base points: pubkey = basepoint + SHA256(per_commitment_point || basepoint) * G The `localpubkey` uses the local node's `payment_basepoint`; +The `remotepubkey` uses the remote node's `payment_basepoint`; the `local_htlcpubkey` uses the local node's `htlc_basepoint`; the `remote_htlcpubkey` uses the remote node's `htlc_basepoint`; the `local_delayedpubkey` uses the local node's `delayed_payment_basepoint`; @@ -461,7 +535,7 @@ secrets are known (i.e. the private keys corresponding to `localpubkey`, `local_ ### `remotepubkey` Derivation -If `option_static_remotekey` is negotiated the `remotepubkey` is simply the +If `option_static_remotekey` or `option_anchor_outputs` is negotiated, the `remotepubkey` is simply the remote node's `payment_basepoint`, otherwise it is calculated as above using the remote node's `payment_basepoint`. @@ -608,6 +682,8 @@ at each bucket is a prefix of the desired index. ## Expected Weight of the Commitment Transaction +(TODO: fix weights) + The *expected weight* of a commitment transaction is calculated as follows: p2wsh: 34 bytes @@ -657,12 +733,22 @@ The *expected weight* of a commitment transaction is calculated as follows: - var_int: 1 byte (pk_script length) - pk_script (p2wsh): 34 bytes - output_paying_to_remote: 31 bytes + output_paying_to_remote (no option_anchor_outputs): 31 bytes - value: 8 bytes - var_int: 1 byte (pk_script length) - pk_script (p2wpkh): 22 bytes - htlc_output: 43 bytes + output_paying_to_remote (option_anchor_outputs): 43 bytes + - value: 8 bytes + - var_int: 1 byte (pk_script length) + - pk_script (p2wsh): 34 bytes + + output_anchor (option_simplified_commitment XXX): 43 bytes + - value: 8 bytes + - var_int: 1 byte (pk_script length) + - pk_script (p2wpkh): 22 bytes + + htlc_output: 43 bytes - value: 8 bytes - var_int: 1 byte (pk_script length) - pk_script (p2wsh): 34 bytes @@ -671,7 +757,7 @@ The *expected weight* of a commitment transaction is calculated as follows: - flag: 1 byte - marker: 1 byte - commitment_transaction: 125 + 43 * num-htlc-outputs bytes + commitment_transaction (no option_anchor_outputs): 125 + 43 * num-htlc-outputs bytes - version: 4 bytes - witness_header <---- part of the witness data - count_tx_in: 1 byte @@ -684,15 +770,32 @@ The *expected weight* of a commitment transaction is calculated as follows: ....htlc_output's... - lock_time: 4 bytes + commitment_transaction (option_anchor_outputs): 223 + 43 * num-htlc-outputs bytes + - version: 4 bytes + - witness_header <---- part of the witness data + - count_tx_in: 1 byte + - tx_in: 41 bytes + funding_input + - count_tx_out: 1 byte + - tx_out: 172 + 43 * num-htlc-outputs bytes + output_paying_to_remote, + output_paying_to_local, + output_anchor, + output_anchor, + ....htlc_output's... + - lock_time: 4 bytes + Multiplying non-witness data by 4 results in a weight of: - // 500 + 172 * num-htlc-outputs weight + // 500 + 172 * num-htlc-outputs weight (no option_simplified_commitment XXX) + // 892 + 172 * num-htlc-outputs weight (option_simplified_commitment XXX) commitment_transaction_weight = 4 * commitment_transaction // 224 weight witness_weight = witness_header + witness - overall_weight = 500 + 172 * num-htlc-outputs + 224 weight + overall_weight (no option_simplified_commitment XXX) = 500 + 172 * num-htlc-outputs + 224 weight + overall_weight (option_simplified_commitment XXX) = 892 + 172 * num-htlc-outputs + 224 weight ## Expected Weight of HTLC-timeout and HTLC-success Transactions diff --git a/05-onchain.md b/05-onchain.md index 84fc39276..4ad7a294b 100644 --- a/05-onchain.md +++ b/05-onchain.md @@ -39,6 +39,7 @@ encounters any of the above situations, on-chain. * [HTLC Output Handling: Remote Commitment, Remote Offers](#htlc-output-handling-remote-commitment-remote-offers) * [Revoked Transaction Close Handling](#revoked-transaction-close-handling) * [Penalty Transactions Weight Calculation](#penalty-transactions-weight-calculation) + * [Generation of HTLC Transactions](#generation-of-htlc-transactions) * [General Requirements](#general-requirements) * [Appendix A: Expected Weights](#appendix-a-expected-weights) * [Expected Weight of the `to_local` Penalty Transaction Witness](#expected-weight-of-the-to-local-penalty-transaction-witness) @@ -89,21 +90,29 @@ trigger any action. # Commitment Transaction The local and remote nodes each hold a *commitment transaction*. Each of these -commitment transactions has four types of outputs: +commitment transactions has six types of outputs: 1. _local node's main output_: Zero or one output, to pay to the *local node's* -commitment pubkey. +delayed pubkey. 2. _remote node's main output_: Zero or one output, to pay to the *remote node's* -commitment pubkey. -3. _local node's offered HTLCs_: Zero or more pending payments (*HTLCs*), to pay +delayed_pubkey. +3. _local node's anchor output_: one output paying to the *local node's* +anchor pubkey. +4. _remote node's anchor output_: one output paying to the *remote node's* +anchor_pubkey. +5. _local node's offered HTLCs_: Zero or more pending payments (*HTLCs*), to pay the *remote node* in return for a payment preimage. -4. _remote node's offered HTLCs_: Zero or more pending payments (*HTLCs*), to +6. _remote node's offered HTLCs_: Zero or more pending payments (*HTLCs*), to pay the *local node* in return for a payment preimage. To incentivize the local and remote nodes to cooperate, an `OP_CHECKSEQUENCEVERIFY` -relative timeout encumbers the *local node's outputs* (in the *local node's +relative timeout encumbers some outputs: the *local node's outputs* (in the *local node's commitment transaction*) and the *remote node's outputs* (in the *remote node's -commitment transaction*). So for example, if the local node publishes its +commitment transaction*). If `option_anchor_outputs` applies +to the commitment transaction, then the *to_remote* output of each commitment is +identically encumbered, for fairness. + +Without `option_anchor_outputs`, if the local node publishes its commitment transaction, it will have to wait to claim its own funds, whereas the remote node will have immediate access to its own funds. As a consequence, the two commitment transactions are not identical, but they are @@ -140,6 +149,8 @@ A node: - otherwise: - MUST use the *last commitment transaction*, for which it has a signature, to perform a *unilateral close*. + - MUST spend any `to_local_anchor` output, providing sufficient fees as incentive to include the commitment transaction in a block + - 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. ## Rationale @@ -154,7 +165,8 @@ need not consume resources monitoring the channel state. There exists a bias towards preferring mutual closes over unilateral closes, because outputs of the former are unencumbered by a delay and are directly spendable by wallets. In addition, mutual close fees tend to be less exaggerated -than those of commitment transactions. So, the only reason not to use the +than those of commitment transactions (or in the case of `option_anchor_outputs`, +the commitment transaction may require a child transaction to cause it to be mined). So, the only reason not to use the signature from `closing_signed` would be if the fee offered was too small for it to be processed. @@ -557,6 +569,18 @@ Thus, 483 bidirectional HTLCs (containing both `to_local` and Note: even if the `to_remote` output is not swept, the resulting `max_num_htlcs` is 967; which yields the same unidirectional limit of 483 HTLCs. +# Generation of HTLC Transactions + +If `option_anchor_outputs` does not apply to the commitment transaction, then HTLC-timeout and HTLC-success transactions are complete transactions with (hopefully!) reasonable fees and must be used directly. + +Otherwise, the use of `SIGHASH_SINGLE|SIGHASH_ANYONECANPAY` on the HTLC signatures received from the peer allows HTLC transactions to be combined with other transactions. + +## Requirements + +A node which broadcasts an HTLC-success or HTLC-timeout transaction for a commitment transaction for which `option_anchor_outputs` applies: + - MUST contribute sufficient fee to ensure timely inclusion in a block. + - MAY combine it with other transactions. + # General Requirements A node: diff --git a/09-features.md b/09-features.md index ee79290d4..0e0cf6968 100644 --- a/09-features.md +++ b/09-features.md @@ -36,6 +36,7 @@ The following `globalfeatures` bits are currently assigned by this specification | Bits | Name | Description | Link | |------|-------------------|--------------------------------------------------------------------|---------------------------------------| | 8/9 | `var_onion_optin` | This node requires/supports variable-length routing onion payloads | [Routing Onion Specification][bolt04] | +| 14/15| `option_anchor_outputs` | Anchor outputs | [BOLT #3](03-transactions.md) | ## Requirements