mirrors/lightning-bolts
1
0
Fork 0
mirror of https://github.com/lightning/bolts.git synced 2025-02-22 14:22:46 +01:00
Code Issues Projects Releases Wiki Activity

Zero-fee commitments using v3 transactions

Browse source 
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.
This commit is contained in:
t-bast 2025-02-14 17:50:52 +01:00
parent ccfa38ed4f
commit d3e56d8054
No known key found for this signature in database
GPG key ID: 34F377B0100ED6BB
4 changed files with 201 additions and 131 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

117
02-peer-protocol.md
View file

@ -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.

159
03-transactions.md
View file

@ -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 <RIPEMD160(SHA256(revocationpubkey))> 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 <remotehtlcsig> <localhtlcsig> <payment_preimage>` for HTLC-success, `0 <remotehtlcsig> <localhtlcsig> <>` 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

54
05-onchain.md
View file

@ -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.

2
09-features.md
View file

@ -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