anchor outputs

Co-authored-by: Rusty Russell <rusty@rustcorp.com.au>

.aspell.en.pws

@@ -371,3 +371,6 @@ tlvs
 snprintf
 GitHub
 IRC
+SIGHASH
+ANYONECANPAY
+pushme

02-peer-protocol.md

@@ -121,6 +121,7 @@ the funding transaction and both versions of the commitment transaction.
    * [`point`:`payment_basepoint`]
    * [`point`:`delayed_payment_basepoint`]
    * [`point`:`htlc_basepoint`]
+   * [`point`:`anchor_pubkey`] (`option_anchor_outputs`)
    * [`point`:`first_per_commitment_point`]
    * [`byte`:`channel_flags`]
    * [`u16`:`shutdown_len`] (`option_upfront_shutdown_script`)
@@ -157,7 +158,10 @@ node can offer.
 (i.e. 1/4 the more normally-used 'satoshi per 1000 vbytes') that this
 side will pay for commitment and HTLC transactions, as described in
 [BOLT #3](03-transactions.md#fee-calculation) (this can be adjusted
-later with an `update_fee` message).
+later with an `update_fee` message). Note that if
+`option_anchor_outputs` is negotiated, this `feerate_per_kw`
+can be set to the min relay fee. It is still possible to increase the fee rate
+during the lifetime of the channel using the `update_fee` message.
 
 `to_self_delay` is the number of blocks that the other node's to-self
 outputs must be delayed, using `OP_CHECKSEQUENCEVERIFY` delays; this
@@ -175,6 +179,10 @@ even if one commitment transaction is seen; this property is very
 useful for preserving privacy when outsourcing penalty transactions to
 third parties.
 
+`anchor_pubkey` is the public key to which the anchor output of the channel
+initiator pays. This is a key separate from `payment_basepoint` because anchoring
+may happen from a different (hot) wallet.
+
 `first_per_commitment_point` is the per-commitment point to be used
 for the first commitment transaction,
 
@@ -196,7 +204,7 @@ The sending node:
   - MUST ensure `temporary_channel_id` is unique from any other channel ID with the same peer.
   - MUST set `funding_satoshis` to less than 2^24 satoshi.
   - MUST set `push_msat` to equal or less than 1000 * `funding_satoshis`.
-  - MUST set `funding_pubkey`, `revocation_basepoint`, `htlc_basepoint`, `payment_basepoint`, and `delayed_payment_basepoint` to valid DER-encoded, compressed, secp256k1 pubkeys.
+  - MUST set `funding_pubkey`, `revocation_basepoint`, `htlc_basepoint`, `payment_basepoint`, `delayed_payment_basepoint` and `anchor_pubkey` to valid DER-encoded, compressed, secp256k1 pubkeys.
   - MUST set `first_per_commitment_point` to the per-commitment point to be used for the initial commitment transaction, derived as specified in [BOLT #3](03-transactions.md#per-commitment-secret-requirements).
   - MUST set `channel_reserve_satoshis` greater than or equal to `dust_limit_satoshis`.
   - MUST set undefined bits in `channel_flags` to 0.
@@ -233,7 +241,9 @@ The receiving node MUST fail the channel if:
   - `to_self_delay` is unreasonably large.
   - `max_accepted_htlcs` is greater than 483.
   - it considers `feerate_per_kw` too small for timely processing or unreasonably large.
-  - `funding_pubkey`, `revocation_basepoint`, `htlc_basepoint`, `payment_basepoint`, or `delayed_payment_basepoint`
+    This range can be narrow for `option_anchor_outputs`, because both parties have the option to pay
+    for the transaction with a child (cpfp).
+  - `funding_pubkey`, `revocation_basepoint`, `htlc_basepoint`, `payment_basepoint`, `delayed_payment_basepoint` or `anchor_pubkey`
 are not valid DER-encoded compressed secp256k1 pubkeys.
   - `dust_limit_satoshis` is greater than `channel_reserve_satoshis`.
   - the funder's amount for the initial commitment transaction is not sufficient for full [fee payment](03-transactions.md#fee-payment).
@@ -291,6 +301,7 @@ funding transaction and both versions of the commitment transaction.
    * [`point`:`payment_basepoint`]
    * [`point`:`delayed_payment_basepoint`]
    * [`point`:`htlc_basepoint`]
+   * [`point`:`anchor_pubkey`] (`option_anchor_outputs`)
    * [`point`:`first_per_commitment_point`]
    * [`u16`:`shutdown_len`] (`option_upfront_shutdown_script`)
    * [`shutdown_len*byte`:`shutdown_scriptpubkey`] (`option_upfront_shutdown_script`)
@@ -367,10 +378,10 @@ This message introduces the `channel_id` to identify the channel. It's derived f
 #### Requirements
 
 Both peers:
-  - if `option_static_remotekey` was negotiated:
-    - `option_static_remotekey` applies to all commitment transactions
+  - if `option_static_remotekey` or `option_anchor_outputs` was negotiated:
+    - `option_static_remotekey` or `option_anchor_outputs` applies to all commitment transactions
   - otherwise:
-    - `option_static_remotekey` does not apply to any commitment transactions
+    - `option_static_remotekey` or `option_anchor_outputs` does not apply to any commitment transactions
 
 The sender MUST set:
   - `channel_id` by exclusive-OR of the `funding_txid` and the `funding_output_index` from the `funding_created` message.
@@ -385,9 +396,8 @@ The recipient:
 
 #### Rationale
 
-We decide on `option_static_remotekey` at this point when we first have to generate the commitment
-transaction.  Even if a later reconnection does not negotiate this parameter, this channel will continue to use `option_static_remotekey`; we don't support "downgrading".
-This simplifies channel state, particularly penalty transaction handling.
+We decide on `option_static_remotekey` or `option_anchor_outputs` at this point when we first have to generate the commitment
+transaction.  Even if a later reconnection does not negotiate this parameter, this channel will continue to use `option_static_remotekey` or `option_anchor_outputs`; we don't support "downgrading".
 
 ### The `funding_locked` Message
 
@@ -548,8 +558,11 @@ The funding node:
     - SHOULD send a `closing_signed` message.
 
 The sending node:
-  - MUST set `fee_satoshis` less than or equal to the
- base fee of the final commitment transaction, as calculated in [BOLT #3](03-transactions.md#fee-calculation).
+  - if `option_anchor_outputs` applies to the final commitment transaction:
+    - MUST set `fee_satoshis` greater or equal to the base fee of the final commitment transaction.
+  - otherwise:
+    - MUST set `fee_satoshis` less than or equal to the
+base fee of the final commitment transaction, as calculated in [BOLT #3](03-transactions.md#fee-calculation).
   - SHOULD set the initial `fee_satoshis` according to its
  estimate of cost of inclusion in a block.
   - MUST set `signature` to the Bitcoin signature of the close
@@ -562,10 +575,14 @@ The receiving node:
   - if `fee_satoshis` is equal to its previously sent `fee_satoshis`:
     - SHOULD sign and broadcast the final closing transaction.
     - MAY close the connection.
-  - otherwise, if `fee_satoshis` is greater than
-the base fee of the final commitment transaction as calculated in
-[BOLT #3](03-transactions.md#fee-calculation):
-    - MUST fail the connection.
+  - if `option_anchor_outputs` applies to the final commitment transaction:
+    - if `fee_satoshis` is less than the base fee of the final commitment transaction
+      - MUST fail the connection.
+  - otherwise (no `option_anchor_outputs`):
+    - if `fee_satoshis` is greater than
+      the base fee of the final commitment transaction as calculated in
+      [BOLT #3](03-transactions.md#fee-calculation):
+      - MUST fail the connection.
   - if `fee_satoshis` is not strictly
 between its last-sent `fee_satoshis` and its previously-received
 `fee_satoshis`, UNLESS it has since reconnected:
@@ -583,6 +600,13 @@ progress is made, even if only by a single satoshi at a time. To avoid
 keeping state and to handle the corner case, where fees have shifted
 between disconnection and reconnection, negotiation restarts on reconnection.
 
+In the `option_anchor_outputs` case, the fees on the commitment
+transaction itself are minimal (it is assumed that a child transaction will
+supply additional fee incentive), so that forms a floor for negotiation.
+
+Otherwise, the commitment transaction usually pays a premium fee, so that
+forms a ceiling.
+
 Note there is limited risk if the closing transaction is
 delayed, but it will be broadcast very soon; so there is usually no
 reason to pay a premium for rapid processing.
@@ -802,7 +826,12 @@ is destined, is described in [BOLT #4](04-onion-routing.md).
 A sending node:
   - MUST NOT offer `amount_msat` it cannot pay for in the
 remote commitment transaction at the current `feerate_per_kw` (see "Updating
-Fees") while maintaining its channel reserve.
+Fees") while maintaining its channel reserve
+  - if `option_anchor_outputs` applies to this commitment transaction and the sending
+    node is the funder:
+    - MUST be able to additionally pay for `to_local_anchor` and 
+      `to_remote_anchor` above its reserve. The anchor value should assumed to be
+      the maximum of the dust limits that have been negotiated by both parties.
   - MUST offer `amount_msat` greater than 0.
   - MUST NOT offer `amount_msat` below the receiving node's `htlc_minimum_msat`
   - MUST set `cltv_expiry` less than 500000000.
@@ -824,7 +853,7 @@ been received). It MUST continue incrementing instead.
 A receiving node:
   - receiving an `amount_msat` equal to 0, OR less than its own `htlc_minimum_msat`:
     - SHOULD fail the channel.
-  - receiving an `amount_msat` that the sending node cannot afford at the current `feerate_per_kw` (while maintaining its channel reserve):
+  - receiving an `amount_msat` that the sending node cannot afford at the current `feerate_per_kw` (while maintaining its channel reserve and any `to_local_anchor` and `to_remote_anchor` costs):
     - SHOULD fail the channel.
   - if a sending node adds more than receiver `max_accepted_htlcs` HTLCs to
     its local commitment transaction, OR adds more than receiver `max_htlc_value_in_flight_msat` worth of offered HTLCs to its local commitment transaction:
@@ -980,6 +1009,8 @@ fee changes).
     to the ordering of the commitment transaction (see [BOLT #3](03-transactions.md#transaction-input-and-output-ordering)).
   - if it has not recently received a message from the remote node:
       - SHOULD use `ping` and await the reply `pong` before sending `commitment_signed`.
+  - if `option_anchor_outputs` applies to this commitment transaction:
+    - MUST calculate each `htlc_signature` using `SIGHASH_SINGLE|SIGHASH_ANYONECANPAY`
 
 A receiving node:
   - once all pending updates are applied:
@@ -1007,6 +1038,8 @@ output HTLCs are fully resolved.
 
 Note that the `htlc_signature` implicitly enforces the time-lock mechanism in the case of offered HTLCs being timed out or received HTLCs being spent. This is done to reduce fees by creating smaller scripts compared to explicitly stating time-locks on HTLC outputs.
 
+The `option_anchor_outputs` allows HTLC transactions to "bring their own fees" by attaching other inputs and outputs, hence the modified signature flags.
+
 ### Completing the Transition to the Updated State: `revoke_and_ack`
 
 Once the recipient of `commitment_signed` checks the signature and knows
@@ -1106,6 +1139,10 @@ it's simplest to only allow it to set fee levels; however, as the same
 fee rate applies to HTLC transactions, the receiving node must also
 care about the reasonableness of the fee.
 
+With `option_anchor_outputs`, `feerate_per_kw` is not as critical anymore to
+guarantuee confirmation, but it still needs to be able to satisfy the min relay
+fee.
+
 ## Message Retransmission
 
 Because communication transports are unreliable, and may need to be