From d3e56d8054ef9c7f2d08534f7db703889c0771d1 Mon Sep 17 00:00:00 2001 From: t-bast Date: Fri, 14 Feb 2025 17:50:52 +0100 Subject: [PATCH] Zero-fee commitments using v3 transactions We introduce a new `channel_type` that leverages v3 transactions, pay-to-anchor outputs and ephemeral dust. With this change, commitment transactions don't pay any mining fee, which gets rid of `update_fee` and all of the related channel reserve issues. It also gets rid of the undesired channel force-closes that happen when the mempool feerate spikes and channel participants disagree on what feerate to use, which has been a major source of wasted on-chain space. It also offers better protection against pinning attacks and reduces the on-chain footprint compared to anchor output channels. We use a single anchor output whose amount is the sum of all trimmed outputs (and may thus be `0 sat`). We remove the 1-block relative delay used by anchor output channels: this allows using our channel outputs (main balance or pending HTLCs) to CPFP a remote commitment transaction (no need to add external inputs). v3 transactions and pay-to-anchor outputs have been standard since the release of Bitcoin Core v28.0. Ephemeral dust will become standard in the Bitcoin Core v29.0 release. --- 02-peer-protocol.md | 117 +++++++++++++++++++------------- 03-transactions.md | 159 ++++++++++++++++++++++++++++---------------- 05-onchain.md | 54 +++++++-------- 09-features.md | 2 + 4 files changed, 201 insertions(+), 131 deletions(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index 2057728..70e96b3 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -609,7 +609,6 @@ the `channel_ready` message, the channel is established and can begin normal operation. The `channel_ready` message includes information that will be used to construct channel authentication proofs. - +-------+ +-------+ | |--(1)--- open_channel ----->| | | |<-(2)-- accept_channel -----| | @@ -745,6 +744,7 @@ affect the channel operation). The currently defined basic types are: - `option_static_remotekey` (bit 12) - `option_anchors` and `option_static_remotekey` (bits 22 and 12) + - `zero_fee_commitments` (bit 40) Each basic type has the following variations allowed: - `option_scid_alias` (bit 46) @@ -776,14 +776,19 @@ The sending node: - MUST set it to a defined type representing the type it wants. - MUST use the smallest bitmap possible to represent the channel type. - SHOULD NOT set it to a type containing a feature which was not negotiated. + - if `channel_type` includes `zero_fee_commitments`: + - MUST set `feerate_per_kw` to `0`. - if `announce_channel` is `true` (not `0`): - MUST NOT send `channel_type` with the `option_scid_alias` bit set. The sending node SHOULD: - set `to_self_delay` sufficient to ensure the sender can irreversibly spend a commitment transaction output, in case of misbehavior by the receiver. - - set `feerate_per_kw` to at least the rate it estimates would cause the transaction to be immediately included in a block. - - set `dust_limit_satoshis` to a sufficient value to allow commitment transactions to propagate through the Bitcoin network. - set `htlc_minimum_msat` to the minimum value HTLC it's willing to accept from this peer. + - when using `zero_fee_commitments` or `option_anchors`: + - set `dust_limit_satoshis` to a sufficient value to ensure that it is economical to spend, taking the cost of HTLC transactions into account. + - otherwise (not using `zero_fee_commitments` or `option_anchors`): + - set `feerate_per_kw` to at least the rate it estimates would cause the transaction to be immediately included in a block. + - set `dust_limit_satoshis` to a sufficient value to allow commitment transactions to propagate through the Bitcoin network. The receiving node MUST: - ignore undefined bits in `channel_flags`. @@ -808,15 +813,19 @@ The receiving node MUST fail the channel if: - the `chain_hash` value is set to a hash of a chain that is unknown to the receiver. - `push_msat` is greater than `funding_satoshis` * 1000. - `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. + - `channel_type` includes `zero_fee_commitments` and: + - `max_accepted_htlcs` is greater than 283. + - `feerate_per_kw` is not `0`. + - `channel_type` does not include `zero_fee_commitments` and: + - `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` are not valid secp256k1 pubkeys in compressed format. - `dust_limit_satoshis` is greater than `channel_reserve_satoshis`. - `dust_limit_satoshis` is smaller than `354 satoshis` (see [BOLT 3](03-transactions.md#dust-limits)). - the funder's amount for the initial commitment transaction is not sufficient for full [fee payment](03-transactions.md#fee-payment). - both `to_local` and `to_remote` amounts for the initial commitment transaction are less than or equal to `channel_reserve_satoshis` (see [BOLT 3](03-transactions.md#commitment-transaction-outputs)). - - `funding_satoshis` is greater than or equal to 2^24 and the receiver does not support `option_support_large_channel`. + - `funding_satoshis` is greater than or equal to 2^24 and the receiver does not support `option_support_large_channel`. - It supports `channel_type` and `channel_type` was set: - if `type` is not suitable. - if `type` includes `option_zeroconf` and it does not trust the sender to open an unconfirmed channel. @@ -970,7 +979,9 @@ Both peers: - if `channel_type` was present in both `open_channel` and `accept_channel`: - This is the `channel_type` (they must be equal, required above) - otherwise: - - if `option_anchors` was negotiated: + - if `zero_fee_commitments` was negotiated: + - the `channel_type` is `zero_fee_commitments` (bit 40) + - otherwise, if `option_anchors` was negotiated: - the `channel_type` is `option_anchors` and `option_static_remotekey` (bits 22 and 12) - otherwise: - the `channel_type` is `option_static_remotekey` (bit 12) @@ -990,16 +1001,17 @@ The recipient: #### Rationale -We decide on `option_static_remotekey` or `option_anchors` at this point -when we first have to generate the commitment transaction. The feature -bits that were communicated in the `init` message exchange for the current -connection determine the channel commitment format for the total lifetime -of the channel. Even if a later reconnection does not negotiate this -parameter, this channel will continue to use `option_static_remotekey` or -`option_anchors`; we don't support "downgrading". +We decide on `option_static_remotekey`, `option_anchors` or +`zero_fee_commitments` at this point when we first have to generate the +commitment transaction. The feature bits that were communicated in the +`init` message exchanged for the current connection determine the channel +commitment format for the total lifetime of the channel. Even if a later +reconnection does not negotiate this parameter, this channel will continue +to use the initial commitment format; we don't support "downgrading". -`option_anchors` is considered superior to `option_static_remotekey`, -and the superior one is favored if more than one is negotiated. +`zero_fee_commitments` is considered superior to `option_anchors`, which +itself is superior to `option_static_remotekey`, and the superior one is +favored if more than one is negotiated. ### The `channel_ready` Message @@ -1176,6 +1188,8 @@ If nodes have negotiated `option_dual_fund`: The sending node: - MUST set `funding_feerate_perkw` to the feerate for this transaction + - if `channel_type` includes `zero_fee_commitments`: + - MUST set `commitment_feerate_perkw` to `0`. - If it requires the receiving node to only use confirmed inputs: - MUST set `require_confirmed_inputs` @@ -1184,6 +1198,7 @@ The receiving node: - the `locktime` is unacceptable - the `funding_feerate_perkw` is unacceptable - MUST fail the negotiation if: + - `channel_type` includes `zero_fee_commitments` and `commitment_feerate_perkw` is not `0`. - `require_confirmed_inputs` is set but it cannot provide confirmed inputs #### Rationale @@ -2204,9 +2219,9 @@ A node: The `max_dust_htlc_exposure_msat` is an upper bound on the trimmed balance from dust exposure. The exact value used is a matter of node policy. -For channels that don't use `option_anchors`, an increase of -the `feerate_per_kw` may trim multiple htlcs from commitment transactions, -which could create a large increase in dust exposure. +For channels that don't use `zero_fee_commitments` or `option_anchors`, an +increase of the `feerate_per_kw` may trim multiple htlcs from commitment +transactions, which could create a large increase in dust exposure. ### Adding an HTLC: `update_add_htlc` @@ -2237,26 +2252,27 @@ is destined, is described in [BOLT #4](04-onion-routing.md). #### Requirements A sending node: - - if it is _responsible_ for paying the Bitcoin fee: - - MUST NOT offer `amount_msat` if, after adding that HTLC to its commitment - transaction, it cannot pay the fee for either the local or remote commitment - transaction at the current `feerate_per_kw` while maintaining its channel - reserve (see [Updating Fees](#updating-fees-update_fee)). - - if `option_anchors` 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. - - SHOULD NOT offer `amount_msat` if, after adding that HTLC to its commitment - transaction, its remaining balance doesn't allow it to pay the commitment - transaction fee when receiving or sending a future additional non-dust HTLC - while maintaining its channel reserve. It is recommended that this "fee spike - buffer" can handle twice the current `feerate_per_kw` to ensure predictability - between implementations. - - if it is _not responsible_ for paying the Bitcoin fee: - - SHOULD NOT offer `amount_msat` if, once the remote node adds that HTLC to - its commitment transaction, it cannot pay the fee for the updated local or - remote transaction at the current `feerate_per_kw` while maintaining its - channel reserve. + - if `zero_fees_commitments` has not been negotiated: + - if it is _responsible_ for paying the Bitcoin fee: + - MUST NOT offer `amount_msat` if, after adding that HTLC to its commitment + transaction, it cannot pay the fee for either the local or remote commitment + transaction at the current `feerate_per_kw` while maintaining its channel + reserve (see [Updating Fees](#updating-fees-update_fee)). + - if `option_anchors` 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. + - SHOULD NOT offer `amount_msat` if, after adding that HTLC to its commitment + transaction, its remaining balance doesn't allow it to pay the commitment + transaction fee when receiving or sending a future additional non-dust HTLC + while maintaining its channel reserve. It is recommended that this "fee spike + buffer" can handle twice the current `feerate_per_kw` to ensure predictability + between implementations. + - if it is _not responsible_ for paying the Bitcoin fee: + - SHOULD NOT offer `amount_msat` if, once the remote node adds that HTLC to + its commitment transaction, it cannot pay the fee for the updated local or + remote transaction at the current `feerate_per_kw` while maintaining its + channel reserve. - 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. @@ -2325,12 +2341,16 @@ sides send the maximum number of HTLCs, the `commitment_signed` message will still be under the maximum message size. It also ensures that a single penalty transaction can spend the entire commitment transaction, as calculated in [BOLT #5](05-onchain.md#penalty-transaction-weight-calculation). +When using `zero_fee_commitments`, we further limit `max_accepted_htlcs` to +283 because v3 transactions are limited to 10kvB, which decreases the number +of outputs the commitment transaction can have. `cltv_expiry` values equal to or greater than 500000000 would indicate a time in seconds, and the protocol only supports an expiry in blocks. -The node _responsible_ for paying the Bitcoin fee should maintain a "fee -spike buffer" on top of its reserve to accommodate a future fee increase. +When `zero_fee_commitments` is not used, the node _responsible_ for paying +the Bitcoin fee should maintain a "fee spike buffer" on top of its reserve +to accommodate a future fee increase. Without this buffer, the node _responsible_ for paying the Bitcoin fee may reach a state where it is unable to send or receive any non-dust HTLC while maintaining its channel reserve (because of the increased weight of the @@ -2500,9 +2520,6 @@ 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_anchors` 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 @@ -2547,8 +2564,9 @@ A node: ### Updating Fees: `update_fee` -An `update_fee` message is sent by the node which is paying the -Bitcoin fee. Like any update, it's first committed to the receiver's +For channels that don't use `zero_fee_commitments`, an `update_fee` +message is sent by the node which is paying the Bitcoin fee. +Like any update, it's first committed to the receiver's commitment transaction and then (once acknowledged) committed to the sender's. Unlike an HTLC, `update_fee` is never closed but simply replaced. @@ -2569,6 +2587,9 @@ given in [BOLT #3](03-transactions.md#fee-calculation). #### Requirements +When using `zero_fee_commitments`, nodes: + - MUST NOT send `update_fee`. + The node _responsible_ for paying the Bitcoin fee: - SHOULD send `update_fee` to ensure the current fee rate is sufficient (by a significant margin) for timely processing of the commitment transaction. @@ -2611,7 +2632,9 @@ Bitcoin fees are required for unilateral closes to be effective. With `option_anchors`, `feerate_per_kw` is not as critical anymore to guarantee confirmation as it was in the legacy commitment format, but it still needs to be enough to be able to enter the mempool (satisfy min relay fee and mempool -min fee). +min fee). With `zero_fee_commitments`, transactions can enter the mempool +as a package with a child transaction paying the fees: channel transactions +thus don't need to directly include a fee, so this message isn't used. For the legacy commitment format, there is no general method for the broadcasting node to use child-pays-for-parent to increase its effective fee. diff --git a/03-transactions.md b/03-transactions.md index 7052acd..ba776e1 100644 --- a/03-transactions.md +++ b/03-transactions.md @@ -13,6 +13,7 @@ This details the exact format of on-chain transactions, which both sides need to * [`to_local` Output](#to_local-output) * [`to_remote` Output](#to_remote-output) * [`to_local_anchor` and `to_remote_anchor`](#to_local_anchor-and-to_remote_anchor-output-option_anchors) + * [`shared_anchor`](#shared_anchor-output-zero_fee_commitments) * [Offered HTLC Outputs](#offered-htlc-outputs) * [Received HTLC Outputs](#received-htlc-outputs) * [Trimmed Outputs](#trimmed-outputs) @@ -79,7 +80,7 @@ A `<>` designates an empty vector as required for compliance with MINIMALIF-stan ## Commitment Transaction -* version: 2 +* version: 3 when using `zero_fee_commitments`, otherwise 2 * locktime: upper 8 bits are 0x20, lower 24 bits are the lower 24 bits of the obscured commitment number * txin count: 1 * `txin[0]` outpoint: `txid` and `output_index` from `funding_created` message @@ -103,7 +104,9 @@ To allow an opportunity for penalty transactions, in case of a revoked commitmen The reason for the separate transaction stage for HTLC outputs is so that HTLCs can timeout or be fulfilled even though they are within the `to_self_delay` delay. Otherwise, the required minimum timeout on HTLCs is lengthened by this delay, causing longer timeouts for HTLCs traversing the network. -The amounts for each output MUST be rounded down to whole satoshis. If this amount, minus the fees for the HTLC transaction, is less than the `dust_limit_satoshis` set by the owner of the commitment transaction, the output MUST NOT be produced (thus the funds add to fees). +The amounts for each output MUST be rounded down to whole satoshis. +If this amount, minus the fees for the HTLC transaction, is less than the `dust_limit_satoshis` set by the owner of the commitment transaction, the output MUST NOT be produced. +If `zero_fee_commitments` is used, this amount is added to the `shared_anchor`, otherwise it adds to on-chain fees. #### `to_local` Output @@ -144,7 +147,7 @@ Otherwise, this output is a simple P2WPKH to `remotepubkey`. Note: the remote's #### `to_local_anchor` and `to_remote_anchor` Output (option_anchors) 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. +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). @@ -171,9 +174,24 @@ After 16 blocks, anyone can sweep the anchor with witness: <> +#### `shared_anchor` Output (zero_fee_commitments) + +This output can be spent by anyone to provide incentive to mine the transaction, using child-pays-for-parent (since the commitment transaction doesn't pay any mining fees). +This output is only added when the commitment transaction is using version 3 (`zero_fee_commitments`) and prevents pinning attacks on the commitment transaction. +It is using the following standard P2A (pay-to-anchor) script: + + OP_1 <0x4e73> + +The amount of this output is usually 0 sats, in which case it must be spent by the child transaction paying the mining fees. +When the commitment contains [trimmed outputs](#trimmed-outputs), their amount is added to this `shared_anchor` output. + +Spending of the output requires the following (emtpy) witness: + + <> + #### 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 (no option_anchors): +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_anchors`): # To remote node with revocation key OP_DUP OP_HASH160 OP_EQUAL @@ -280,60 +298,73 @@ To redeem the HTLC, the HTLC-success transaction is used as detailed below. This ### Trimmed Outputs Each peer specifies a `dust_limit_satoshis` below which outputs should -not be produced; these outputs that are not produced are termed "trimmed". A trimmed output is -considered too small to be worth creating and is instead added -to the commitment transaction fee. For HTLCs, it needs to be taken into -account that the second-stage HTLC transaction may also be below the -limit. +not be produced; these outputs that are not produced are termed "trimmed". +A trimmed output is considered too small to be worth creating: it is instead +either added to the commitment transaction fee or, if `zero_fee_commitments` +applies, to the [shared anchor output](#shared_anchor-output-zero_fee_commitments). + +For HTLCs, it needs to be taken into account that the second-stage HTLC +transaction may also be below the limit. Note that when using `option_anchors` +or `zero_fee_commitments`, HTLC transactions don't include a fee and thus +don't contribute to trimming: setting a higher `dust_limit_satoshis` makes +sense for those channels to ensure that outputs are economical to spend. #### Requirements -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). +Before the commitment transaction outputs are determined: + - the base fee MUST be subtracted from the `to_local` or `to_remote` output, + as specified in [Fee Calculation](#fee-calculation). + - if `option_anchors` applies: + - the `to_local_anchor` output value MUST be subtracted from the `to_local` output. + - the `to_remote_anchor` output value MUST be subtracted from the `to_remote` output. The commitment transaction: - if the amount of the commitment transaction `to_local` output would be -less than `dust_limit_satoshis` set by the transaction owner: + less than `dust_limit_satoshis` set by the transaction owner: - MUST NOT contain that output. + - if `zero_fee_commitments` applies: + - MUST add this amount to the `shared_anchor` output. - otherwise: - MUST be generated as specified in [`to_local` Output](#to_local-output). - if the amount of the commitment transaction `to_remote` output would be -less than `dust_limit_satoshis` set by the transaction owner: + less than `dust_limit_satoshis` set by the transaction owner: - MUST NOT contain that output. + - if `zero_fee_commitments` applies: + - MUST add this amount to the `shared_anchor` output. - otherwise: - MUST be generated as specified in [`to_remote` Output](#to_remote-output). - for every offered HTLC: - if the HTLC amount minus the HTLC-timeout fee would be less than - `dust_limit_satoshis` set by the transaction owner: + `dust_limit_satoshis` set by the transaction owner: - MUST NOT contain that output. + - if `zero_fee_commitments` applies: + - MUST add this amount to the `shared_anchor` output. - otherwise: - - MUST be generated as specified in - [Offered HTLC Outputs](#offered-htlc-outputs). + - MUST be generated as specified in [Offered HTLC Outputs](#offered-htlc-outputs). - for every received HTLC: - if the HTLC amount minus the HTLC-success fee would be less than - `dust_limit_satoshis` set by the transaction owner: + `dust_limit_satoshis` set by the transaction owner: - MUST NOT contain that output. + - if `zero_fee_commitments` applies: + - MUST add this amount to the `shared_anchor` output. - otherwise: - - MUST be generated as specified in - [Received HTLC Outputs](#received-htlc-outputs). + - MUST be generated as specified in [Received HTLC Outputs](#received-htlc-outputs). ## HTLC-Timeout and HTLC-Success Transactions These HTLC transactions are almost identical, except the HTLC-timeout transaction is timelocked. Both HTLC-timeout/HTLC-success transactions can be spent by a valid penalty transaction. -* version: 2 +* version: 3 when using `zero_fee_commitments`, otherwise 2 * locktime: `0` for HTLC-success, `cltv_expiry` for HTLC-timeout * txin count: 1 * `txin[0]` outpoint: `txid` of the commitment transaction and `output_index` of the matching HTLC output for the HTLC transaction - * `txin[0]` sequence: `0` (set to `1` for `option_anchors`) + * `txin[0]` sequence: `1` for `option_anchors`, `0xFFFFFFFD` for `zero_fee_commitments`, `0` otherwise * `txin[0]` script bytes: `0` * `txin[0]` witness stack: `0 ` for HTLC-success, `0 <>` for HTLC-timeout * txout count: 1 * `txout[0]` amount: the HTLC `amount_msat` divided by 1000 (rounding down) minus fees in satoshis (see [Fee Calculation](#fee-calculation)) * `txout[0]` script: version-0 P2WSH with witness script as shown below -* if `option_anchors` applies to this commitment transaction, `SIGHASH_SINGLE|SIGHASH_ANYONECANPAY` is used as described in [BOLT #5](05-onchain.md#generation-of-htlc-transactions). +* if `option_anchors` or `zero_fee_commitments` applies to this commitment transaction, `SIGHASH_SINGLE|SIGHASH_ANYONECANPAY` is used as described in [BOLT #5](05-onchain.md#generation-of-htlc-transactions). The witness script for the output is: @@ -434,7 +465,12 @@ Each node offering a signature: The fee calculation for both commitment transactions and HTLC transactions is based on the current `feerate_per_kw` and the -*expected weight* of the transaction. +*expected weight* of the transaction. Note that `feerate_per_kw` +is set to `0` when using `zero_fee_commitments`: in that case +the commitment transactions and HTLC transactions don't pay any +fee, which must be paid using child-pays-for-parent (for the +commitment transactions) or by adding inputs (for the HTLC +transactions). The actual and expected weights vary for several reasons: @@ -459,24 +495,27 @@ This yields the following *expected weights* (details of the computation in [App HTLC-success weight (no option_anchors): 703 HTLC-success weight (option_anchors): 706 -Note the reference to the "base fee" for a commitment transaction in the requirements below, which is what the funder pays. The actual fee may be higher than the amount calculated here, due to rounding and trimmed outputs. +Note the reference to the "base fee" for a commitment transaction in the requirements below, which is what the funder pays. +The actual fee may be higher than the amount calculated here, due to rounding and trimmed outputs. #### Requirements The fee for an HTLC-timeout transaction: - - If `option_anchors` applies: + - If `option_anchors` or `zero_fee_commitments` applies: 1. MUST be 0. - Otherwise, MUST be calculated to match: 1. Multiply `feerate_per_kw` by 663 and divide by 1000 (rounding down). The fee for an HTLC-success transaction: - - If `option_anchors` applies: + - If `option_anchors` or `zero_fee_commitments` applies: 1. MUST be 0. - Otherwise, MUST be calculated to match: 1. Multiply `feerate_per_kw` by 703 and divide by 1000 (rounding down). The base fee for a commitment transaction: - - MUST be calculated to match: + - If `zero_fee_commitments` applies: + 1. MUST be 0. + - Otherwise, MUST be calculated to match: 1. Start with `weight` = 724 (1124 if `option_anchors` applies). 2. For each committed HTLC, if that output is not trimmed as specified in [Trimmed Outputs](#trimmed-outputs), add 172 to `weight`. @@ -516,16 +555,19 @@ outputs) is 7140 satoshi. The final fee may be even higher if the ### Fee Payment -Base commitment transaction fees and amounts for `to_local_anchor` and `to_remote_anchor` outputs are extracted from the funder's amount; -Restrictions to the commitment tx output for the funder in relation to the -channel reserve apply as described in [BOLT #2](02-peer-protocol.md). +Base commitment transaction fees and amounts for `to_local_anchor` and +`to_remote_anchor` outputs are extracted from the funder's amount. + +When using `zero_fee_commitments`, the `shared_anchor` output amount is +the sum of all [trimmed outputs](#trimmed-outputs). 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 -contribute to fees. +contribute to fees (or, if `zero_fee_commitments` applies, to the +`shared_anchor`). A node: - - if the resulting fee rate is too low: + - if `zero_fee_commitments` is not used and the resulting fee rate is too low: - MAY send a `warning` and close the connection, or send an `error` and fail the channel. @@ -650,26 +692,28 @@ given that peer's `dust_limit_satoshis`, the current `feerate_per_kw`, the amounts due to each peer (`to_local` and `to_remote`), and all committed HTLCs: -1. Initialize the commitment transaction input and locktime, as specified - 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`). -If `option_anchors` applies to the commitment transaction, -also subtract two times the fixed anchor size of 330 sats from the funder -(either `to_local` or `to_remote`). -4. For every offered HTLC, if it is not trimmed, add an - [offered HTLC output](#offered-htlc-outputs). -5. For every received HTLC, if it is not trimmed, add an - [received HTLC output](#received-htlc-outputs). -6. If the `to_local` amount is greater or equal to `dust_limit_satoshis`, - add a [`to_local` output](#to_local-output). -7. If the `to_remote` amount is greater or equal to `dust_limit_satoshis`, - add a [`to_remote` output](#to_remote-output). -8. If `option_anchors` applies to the commitment transaction: - * if `to_local` exists or there are untrimmed HTLCs, add a [`to_local_anchor` output](#to_local_anchor-and-to_remote_anchor-output-option_anchors) - * if `to_remote` exists or there are untrimmed HTLCs, add a [`to_remote_anchor` output](#to_local_anchor-and-to_remote_anchor-output-option_anchors) -9. Sort the outputs into [BIP 69+CLTV order](#transaction-output-ordering). +* Initialize the commitment transaction input and locktime, as specified + in [Commitment Transaction](#commitment-transaction). +* Calculate which committed HTLCs need to be trimmed (see [Trimmed Outputs](#trimmed-outputs)). +* Calculate the base [commitment transaction fee](#fee-calculation). +* Subtract this base fee from the funder (either `to_local` or `to_remote`). + If `option_anchors` applies to the commitment transaction, + also subtract two times the fixed anchor size of 330 sats from the funder + (either `to_local` or `to_remote`). +* For every offered HTLC, if it is not trimmed, add an + [offered HTLC output](#offered-htlc-outputs). +* For every received HTLC, if it is not trimmed, add a + [received HTLC output](#received-htlc-outputs). +* If the `to_local` amount is greater or equal to `dust_limit_satoshis`, + add a [`to_local` output](#to_local-output). +* If the `to_remote` amount is greater or equal to `dust_limit_satoshis`, + add a [`to_remote` output](#to_remote-output). +* If `option_anchors` applies to the commitment transaction: + * if `to_local` exists or there are untrimmed HTLCs, add a [`to_local_anchor` output](#to_local_anchor-and-to_remote_anchor-output-option_anchors). + * if `to_remote` exists or there are untrimmed HTLCs, add a [`to_remote_anchor` output](#to_local_anchor-and-to_remote_anchor-output-option_anchors). +* If `zero_fee_commitments` applies to the commitment transaction: + * add a [`shared_anchor` output](#shared_anchor-output-zero_fee_commitments). +* Sort the outputs into [BIP 69+CLTV order](#transaction-output-ordering). # Keys @@ -906,7 +950,6 @@ Multiplying non-witness data by 4 results in a weight of: overall_weight = funding_transaction_weight + witness_weight - ## Expected Weight of the Commitment Transaction The *expected weight* of a commitment transaction is calculated as follows: @@ -1154,9 +1197,9 @@ Multiplying non-witness data by 4 results in a weight of 376. Adding the witness data for each case (285 or 288 + 2 for HTLC-timeout, 324 or 327 + 2 for HTLC-success) results in weights of: - 663 (HTLC-timeout) (666 with option_anchors)) - 703 (HTLC-success) (706 with option_anchors)) - - (really 702 and 705, but we use these numbers for historical reasons) + 663 (HTLC-timeout) (666 with option_anchors) + 703 (HTLC-success) (706 with option_anchors) + - (really 702 and 705, but we use these numbers for historical reasons) # Appendix B: Funding Transaction Test Vectors diff --git a/05-onchain.md b/05-onchain.md index 5a41b60..bdff2cd 100644 --- a/05-onchain.md +++ b/05-onchain.md @@ -90,7 +90,7 @@ trigger any action. # Commitment Transaction The local and remote nodes each hold a *commitment transaction*. Each of these -commitment transactions has up to six types of outputs: +commitment transactions has up to seven types of outputs: 1. _local node's main output_: Zero or one output, to pay to the *local node's* delayed_pubkey. @@ -100,9 +100,11 @@ delayed_pubkey. funding_pubkey. 4. _remote node's anchor output_: one output paying to the *remote node's* funding_pubkey. -5. _local node's offered HTLCs_: Zero or more pending payments (*HTLCs*), to pay +5. _shared ephemeral anchor_: one output paying to the *local* or *remote* +node's funding_pubkey. +6. _local node's offered HTLCs_: Zero or more pending payments (*HTLCs*), to pay the *remote node* in return for a payment preimage. -6. _remote node's offered HTLCs_: Zero or more pending payments (*HTLCs*), to +7. _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` @@ -148,9 +150,10 @@ A node: - otherwise: - MUST broadcast 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. - Special care must be taken when spending to a third-party, because this re-introduces the vulnerability that was - addressed by adding the CSV delay to the non-anchor outputs. + - MUST spend any `to_local_anchor` or `shared_anchor` output, providing sufficient fees + as incentive to include the commitment transaction in a block. When using `nVersion=2`, + special care must be taken when spending to a third-party, because this re-introduces + the vulnerability that was addressed by adding the CSV delay to the non-anchor outputs. - 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 @@ -166,10 +169,10 @@ 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 (or in the case of `option_anchors`, -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. +than those of commitment transactions (or in the case of commitments using anchor +outputs, the commitment transaction may require a child transaction to cause it +to be mined). So, the only reason not to use the mutual close transaction would +be if the fee offered was too small for it to be processed. # Mutual Close Handling @@ -276,8 +279,7 @@ The local HTLC-timeout transaction needs to be used to time out the HTLC (to prevent the remote node fulfilling it and claiming the funds) before the local node can back-fail any corresponding incoming HTLC, using `update_fail_htlc` (presumably with reason `permanent_channel_failure`), as -detailed in -[BOLT #2](02-peer-protocol.md#forwarding-htlcs). +detailed in [BOLT #2](02-peer-protocol.md#forwarding-htlcs). If the incoming HTLC is also on-chain, a node must simply wait for it to timeout: there is no way to signal early failure. @@ -515,7 +517,7 @@ A local node: using the revocation private key. - SHOULD extract the payment preimage from the transaction input witness, if it's not already known. - - if `option_anchors` applies: + - if `SIGHASH_SINGLE|SIGHASH_ANYONECANPAY` is used for HTLC transactions: - MAY use a single transaction to *resolve* all the outputs. - if confirmation doesn't happen before reaching `security_delay` blocks from expiry: @@ -532,8 +534,8 @@ A single transaction that resolves all the outputs will be under the standard size limit because of the 483 HTLC-per-party limit (see [BOLT #2](02-peer-protocol.md#the-open_channel-message)). -Note: if `option_anchors` applies, the cheating node can pin spends of its -HTLC-timeout/HTLC-success outputs thanks to SIGHASH_SINGLE malleability. +Note: when `SIGHASH_SINGLE|SIGHASH_ANYONECANPAY` is used for HTLC transactions, +the cheating node can pin spends of its HTLC-timeout/HTLC-success outputs. Using a single penalty transaction for all revoked outputs is thus unsafe as it could be blocked to propagate long enough for the _local node's `to_local` output_ 's relative locktime to expire and the cheating party escaping the penalty on this @@ -588,25 +590,25 @@ Note: even if the `to_remote` output is not swept, the resulting # Generation of HTLC Transactions -If `option_anchors` 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. +If `SIGHASH_ALL` is used for HTLC transactions, then HTLC-timeout and +HTLC-success transactions are complete transactions with (hopefully!) +reasonable fees and must be used directly. Otherwise, `SIGHASH_SINGLE|SIGHASH_ANYONECANPAY` MUST be used on the -HTLC signatures received from the peer, as this allows HTLC transactions to be combined with -other transactions. The local signature MUST use `SIGHASH_ALL`, otherwise -anyone can attach additional inputs and outputs to the tx. +HTLC signatures received from the peer, as this allows HTLC transactions to be +combined with other transactions. The local signature MUST use `SIGHASH_ALL`, +otherwise anyone can attach additional inputs and outputs to the tx. -If `option_anchors` applies, then the HTLC-timeout and -HTLC-success transactions are signed with the input and output having the same -value. This means they have a zero fee and MUST be combined with other inputs -to arrive at a reasonable fee. +If `SIGHASH_SINGLE|SIGHASH_ANYONECANPAY` is used, then the HTLC-timeout and +HTLC-success transactions are signed with the input and output having the +same value. This means they have a zero fee and MUST be combined with other +inputs to arrive at a reasonable fee. ## Requirements A node which broadcasts an HTLC-success or HTLC-timeout transaction for a commitment transaction: - - if `option_anchors` applies: + - if `SIGHASH_SINGLE|SIGHASH_ANYONECANPAY` is used: - MUST combine it with inputs contributing sufficient fee to ensure timely inclusion in a block. - MAY combine it with other transactions. diff --git a/09-features.md b/09-features.md index 5aa651b..bbd4acc 100644 --- a/09-features.md +++ b/09-features.md @@ -47,6 +47,7 @@ The Context column decodes as follows: | 28/29 | `option_dual_fund` | Use v2 of channel open, enables dual funding | IN | | [BOLT #2](02-peer-protocol.md) | | 34/35 | `option_quiesce` | Support for `stfu` message | IN | | [BOLT #2][bolt02-quiescence] | | 38/39 | `option_onion_messages` | Can forward onion messages | IN | | [BOLT #7](04-onion-routing.md#onion-messages) | +| 40/41 | `zero_fee_commitments` | Zero-fee commitment and HTLC transactions | IN | `option_channel_type` | [BOLT #3][bolt03-shared-anchor] | | 42/43 | `option_provide_storage` | Can store other nodes' encrypted backup data | IN | | [BOLT #1](01-messaging.md#peer-storage) | | 44/45 | `option_channel_type` | Node supports the `channel_type` field in open/accept | IN | | [BOLT #2](02-peer-protocol.md#the-open_channel-message) | | 46/47 | `option_scid_alias` | Supply channel aliases for routing | IN | | [BOLT #2][bolt02-channel-ready] | @@ -99,6 +100,7 @@ This work is licensed under a [Creative Commons Attribution 4.0 International Li [bolt02-open]: 02-peer-protocol.md#the-open_channel-message [bolt02-simple-close]: 02-peer-protocol.md#closing-negotiation-closing_complete-and-closing_sig [bolt03-htlc-tx]: 03-transactions.md#htlc-timeout-and-htlc-success-transactions +[bolt03-shared-anchor]: 03-transactions.md#shared_anchor-output-zero_fee_commitments [bolt02-shutdown]: 02-peer-protocol.md#closing-initiation-shutdown [bolt02-quiescence]: 02-peer-protocol.md#channel-quiescence [bolt02-channel-ready]: 02-peer-protocol.md#the-channel_ready-message