Anchor outputs

This commit extends the specification with a new commitment format that
adds two anchor outputs to the commitment transaction. Anchor outputs
are a safety feature that allows a channel party to unilaterally increase
the fee of the commitment transaction using CPFP and ensure timely
confirmation on the chain. There is no cooperation required from the
remote party.

Author: joostjager

.aspell.en.pws

@@ -376,3 +376,12 @@ bitmasks
 CSPRNG
 lexicographically
 MINIMALIF
+SIGHASH
+ANYONECANPAY
+cpfp
+utxo
+txes
+csv
+CHECKSIGVERIFY
+IFDUP
+sats

02-peer-protocol.md

@@ -378,10 +378,10 @@ This message introduces the `channel_id` to identify the channel. It's derived f
 #### Requirements
 
 Both peers:
-  - if `option_static_remotekey` was negotiated:
-    - `option_static_remotekey` applies to all commitment transactions
+  - if `option_static_remotekey` or `option_anchor_outputs` was negotiated:
+    - `option_static_remotekey` or `option_anchor_outputs` applies to all commitment transactions
   - otherwise:
-    - `option_static_remotekey` does not apply to any commitment transactions
+    - `option_static_remotekey` or `option_anchor_outputs` does not apply to any commitment transactions
 
 The sender MUST set:
   - `channel_id` by exclusive-OR of the `funding_txid` and the `funding_output_index` from the `funding_created` message.
@@ -396,9 +396,10 @@ The recipient:
 
 #### Rationale
 
-We decide on `option_static_remotekey` at this point when we first have to generate the commitment
-transaction.  Even if a later reconnection does not negotiate this parameter, this channel will continue to use `option_static_remotekey`; we don't support "downgrading".
-This simplifies channel state, particularly penalty transaction handling.
+We decide on `option_static_remotekey` or `option_anchor_outputs` at this point when we first have to generate the commitment
+transaction. 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_anchor_outputs`; we don't support "downgrading".
 
 ### The `funding_locked` Message
 
@@ -811,6 +812,10 @@ A sending node:
     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_anchor_outputs` applies to this commitment transaction and the sending
+    node is the funder:
+    - MUST be able to additionally pay for `to_local_anchor` and 
+      `to_remote_anchor` above its reserve.
     - 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
@@ -843,7 +848,7 @@ been received). It MUST continue incrementing instead.
 A receiving node:
   - receiving an `amount_msat` equal to 0, OR less than its own `htlc_minimum_msat`:
     - SHOULD fail the channel.
-  - receiving an `amount_msat` that the sending node cannot afford at the current `feerate_per_kw` (while maintaining its channel reserve):
+  - receiving an `amount_msat` that the sending node cannot afford at the current `feerate_per_kw` (while maintaining its channel reserve and any `to_local_anchor` and `to_remote_anchor` costs):
     - SHOULD fail the channel.
   - if a sending node adds more than receiver `max_accepted_htlcs` HTLCs to
     its local commitment transaction, OR adds more than receiver `max_htlc_value_in_flight_msat` worth of offered HTLCs to its local commitment transaction:
@@ -1034,6 +1039,8 @@ output HTLCs are fully resolved.
 
 Note that the `htlc_signature` implicitly enforces the time-lock mechanism in the case of offered HTLCs being timed out or received HTLCs being spent. This is done to reduce fees by creating smaller scripts compared to explicitly stating time-locks on HTLC outputs.
 
+The `option_anchor_outputs` allows HTLC transactions to "bring their own fees" by attaching other inputs and outputs, hence the modified signature flags.
+
 ### Completing the Transition to the Updated State: `revoke_and_ack`
 
 Once the recipient of `commitment_signed` checks the signature and knows
@@ -1118,13 +1125,18 @@ A receiving node:
 
 #### Rationale
 
-Bitcoin fees are required for unilateral closes to be effective —
-particularly since there is no general method for the broadcasting node to use
-child-pays-for-parent to increase its effective fee.
+Bitcoin fees are required for unilateral closes to be effective.
+With `option_anchor_outputs`, `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).
+
+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.
 
 Given the variance in fees, and the fact that the transaction may be
 spent in the future, it's a good idea for the fee payer to keep a good
-margin (say 5x the expected fee requirement); but, due to differing methods of
+margin (say 5x the expected fee requirement) for legacy commitment txes; but, due to differing methods of
 fee estimation, an exact value is not specified.
 
 Since the fees are currently one-sided (the party which requested the