Skip to content

Zero-fee commitments using v3 transactions (feature 40/41) #1228

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
t-bast wants to merge 2 commits into
base: master
Choose a base branch
from
Open

Zero-fee commitments using v3 transactions (feature 40/41) #1228

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b3d9bed
Zero-fee commitments using v3 transactions
t-bast Feb 14, 2025
e59e30c
fixup! Zero-fee commitments using v3 transactions
t-bast Apr 7, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
96 changes: 59 additions & 37 deletions 02-peer-protocol.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -644,7 +644,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 -----| |
Expand Down Expand Up @@ -780,6 +779,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)
Comment thread
t-bast marked this conversation as resolved.

Each basic type has the following variations allowed:
- `option_scid_alias` (bit 46)
Expand Down Expand Up @@ -809,15 +809,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 `dust_limit_satoshis` to a sufficient value to allow HTLC 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.
Copy link
Copy Markdown
Collaborator

@TheBlueMatt TheBlueMatt Apr 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this applies in both cases.

Copy link
Copy Markdown
Collaborator Author

@t-bast t-bast Apr 7, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Indeed, moved back above where it applies to both cases in e59e30c.


The receiving node MUST:
- ignore undefined bits in `channel_flags`.
Expand All @@ -843,8 +847,12 @@ 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 114.
- `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`.
Expand Down Expand Up @@ -1200,6 +1208,8 @@ If nodes have negotiated `option_dual_fund`:
The sending node:
- MUST set `channel_type`
- 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`

Expand All @@ -1208,6 +1218,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
- `channel_type` is not set

Expand Down Expand Up @@ -2742,9 +2753,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`

Expand Down Expand Up @@ -2775,26 +2786,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_fee_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.
Expand Down Expand Up @@ -2867,12 +2879,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
114 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
Expand Down Expand Up @@ -3153,9 +3169,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.

Splicing requires us to send and receive additional signatures, as we don't
know which (if any) of the splice transactions will end up being the new
channel funding transaction. We use `start_batch` to send a batch of
Expand Down Expand Up @@ -3211,8 +3224,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.
Expand All @@ -3233,6 +3247,9 @@ given in [BOLT #3](03-transactions.md#fee-calculation).

#### Requirements

When using `zero_fee_commitments`, nodes:
Comment thread
t-bast marked this conversation as resolved.
- 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.
Expand All @@ -3253,6 +3270,9 @@ A sending node:
- MUST ensure that requirements are met for all commmitment transactions.

A receiving node:
- if `zero_fee_commitments` is used:
- MUST ignore the message.
- SHOULD send a `warning` and disconnect.
Copy link
Copy Markdown
Collaborator

@TheBlueMatt TheBlueMatt Apr 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think this is useful tbh. Many nodes will send a commitment-update-message in a batch with the actual commitment_signed. As a result, on reconnect they have to resend the commitment update (they already signed it!) and we just enter a reconnect loop. We should instead fail the channel - the peer is hopelessly broken.

Copy link
Copy Markdown
Collaborator Author

@t-bast t-bast Apr 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Makes sense, changed that to a channel fail in e59e30c.

- if the `update_fee` is too low for timely processing, OR is unreasonably large:
- MUST send a `warning` and close the connection, or send an
`error` and fail the channel.
Expand All @@ -3279,7 +3299,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.
Expand Down
Loading