From bb3eb80f28ffe9cea7d28f3b51b46404f8ab4d28 Mon Sep 17 00:00:00 2001 From: niftynei Date: Tue, 2 Mar 2021 21:10:33 -0600 Subject: [PATCH 01/36] interactive-tx: Add dual-funding flow, using the interactive tx protocol This commit adds the interactive transaction construction protcol, as well as the first practical example of using it, v2 of channel establishment. Note that for v2 we also update the channel_id, which now uses the hash of the revocation_basepoints. We move away from using the funding transaction id, as the introduction of RBF* makes it such that a single channel may have many funding transaction id's over the course of its lifetime. *Later, also splicing --- .aspell.en.pws | 21 ++ 01-messaging.md | 4 +- 02-peer-protocol.md | 702 ++++++++++++++++++++++++++++++++++++++++++++ 03-transactions.md | 347 +++++++++++++++++++++- 09-features.md | 1 + tools/spellcheck.sh | 3 +- 6 files changed, 1074 insertions(+), 4 deletions(-) diff --git a/.aspell.en.pws b/.aspell.en.pws index 2c0d09fdf..33ed0af59 100644 --- a/.aspell.en.pws +++ b/.aspell.en.pws @@ -23,6 +23,7 @@ nhops retransmitted dev tradeoff +kiloweight mixHeader uint hopsData @@ -115,6 +116,17 @@ delayedsig hopDataSize I'th segwit +RBF +accepter +accepter's +subtype +redeemScript +scriptSig +utxo +scriptPubKey +scriptPubKeys +scriptlen +sats htlc htlcs ChaCha @@ -387,3 +399,12 @@ CHECKSIGVERIFY IFDUP sats anysegwit +workflow +PUSHDATA +prev +vout +rbf +standardness +perkw +prevtx +ints diff --git a/01-messaging.md b/01-messaging.md index 678393e1b..ea928c20c 100644 --- a/01-messaging.md +++ b/01-messaging.md @@ -316,11 +316,11 @@ The 2-byte `len` field indicates the number of bytes in the immediately followin The channel is referred to by `channel_id`, unless `channel_id` is 0 (i.e. all bytes are 0), in which case it refers to all channels. -The funding node: +The funding node using channel establishment `open_channel`: - for all error messages sent before (and including) the `funding_created` message: - MUST use `temporary_channel_id` in lieu of `channel_id`. -The fundee node: +The fundee node using channel establishment v1 (`accept_channel`): - for all error messages sent before (and not including) the `funding_signed` message: - MUST use `temporary_channel_id` in lieu of `channel_id`. diff --git a/02-peer-protocol.md b/02-peer-protocol.md index ffea7bcb7..cbec51c00 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -7,12 +7,29 @@ operation, and closing. * [Channel](#channel) * [Definition of `channel_id`](#definition-of-channel_id) + * [Interactive Transaction Construction](#interactive-transaction-construction) + * [Set-Up and Vocabulary](#set-up-and-vocabulary) + * [Fee Responsibility](#fee-responsibility) + * [Overview](#overview) + * [The `tx_add_input` Message](#the-tx_add_input-message) + * [The `tx_add_output` Message](#the-tx_add_output-message) + * [The `tx_remove_input` and `tx_remote_output` Messages](#the-tx_remove_input-and-tx_remove_output-messages) + * [The `tx_complete` Message](#the-tx_complete-message) + * [The `tx_signatures` Message](#the-tx_signatures-message) * [Channel Establishment](#channel-establishment) * [The `open_channel` Message](#the-open_channel-message) * [The `accept_channel` Message](#the-accept_channel-message) * [The `funding_created` Message](#the-funding_created-message) * [The `funding_signed` Message](#the-funding_signed-message) * [The `funding_locked` Message](#the-funding_locked-message) + * [Channel Establishment v2](#channel-establishment-v2) + * [The `open_channel2` Message](#the-open_channel2-message) + * [The `accept_channel2` Message](#the-accept_channel2-message) + * [Funding Composition](#funding-composition) + * [The `commitment_signed` Message](#the-commitment_signed-message) + * [Sharing funding signatures: `tx_signatures`](#sharing-funding-signatures-tx_signatures) + * [The `init_rbf` Message](#the-init_rbf-message) + * [The `ack_rbf` Message](#the-ack_rbf-message) * [Channel Close](#channel-close) * [Closing Initiation: `shutdown`](#closing-initiation-shutdown) * [Closing Negotiation: `closing_signed`](#closing-negotiation-closing_signed) @@ -50,10 +67,361 @@ pubkey corresponding to the funding output nothing prevents duplicative channel ids. +### `channel_id`, v2 + +For channels established using the v2 protocol, the `channel_id` is the +SHA256(lesser-revocation-basepoint || greater-revocation-basepoint), +where the lesser and greater is based off the order of the basepoint. +The basepoints are compact DER-encoded public keys. + +If the peer's revocation basepoint is unknown (e.g. `open_channel2`), +a temporary `channel_id` should be found by using a zeroed out basepoint for the unknown peer. + +#### Rationale +These values must be remembered by both peers for correct operation anyway. +They're known from the first exchange of messages, obviating the need for +a `temporary_channel_id`. Finally, by mixing information from both sides, +they avoid `channel_id` collisions. + + +## Interactive Transaction Construction + +Interactive transaction construction allows two peers to collaboratively +build a transaction for broadcast. This protocol is the foundation +for dual-funded channels establishment (v2). + +### Set-Up and Vocabulary + +There are two parties to a transaction construction: an *initiator* +and a *non-initiator*. + The *initiator* is the peer which initiates the protocol, e.g. +for channel establishment v2 the *initiator* would be the peer which +sends `open_channel2`; for a close, the *initiator* sends `shutdown`. + +The protocol makes the following assumptions: + +- The `feerate` for the transaction is known. +- The `dust_limit` for the transaction is known. +- The `nLocktime` for the transaction has been negotiated, or is established + via convention. +- The transaction version is 2. + +### Fee Responsibility + +The *initiator* is responsible for paying the fees for the following fields, +to be referred to as the `common fields`. + + - version + - segwit marker + flag + - input count + - output count + - locktime + +The rest of the transaction bytes' fees are the responsibility of +the peer who contributed that input or output via `tx_add_input` or +`tx_add_output`, at the agreed upon `feerate`. + + +### Overview + +The *initiator* initiates the interactive transaction construction +protocol with `tx_add_input`. The *non-initiator* responds with any +of `tx_add_input`, `tx_add_output`, `tx_rm_input`, `tx_rm_output`, or + `tx_complete`. The protocol continues with the synchronous exchange +of interactive transaction protocol messages until both nodes have sent +and received a consecutive `tx_complete`. + +Once peers have exchanged consecutive `tx_complete`s, the +interactive transaction construction protocol is considered concluded. +Both peers should construct the transaction and fail the negotiation +if an error is discovered. + +This protocol is expressly designed to allow for parallel, multi-party +sessions to collectively construct a single transaction. This preserves +the ability to open multiple channels in a single transaction. While +`serial_id`s are generally chosen randomly, to maintain consistent transaction +ordering across all peer sessions, it is simplest to invert the bottom-bit of +received `serial_id` before forwarding them to other peers. + +Here are a few example exchanges. + +#### *initiator* only + +A, *initiator* has two inputs and an output (the funding output). +B, the *non-initiator* has nothing to contribute. +n + + +-------+ +-------+ + | |--(1)- tx_add_input -->| | + | |<-(2)- tx_complete ----| | + | |--(3)- tx_add_input -->| | + | A |<-(4)- tx_complete ----| B | + | |--(5)- tx_add_output ->| | + | | | | + | |--(6)- tx_complete --->| | + | |<-(7)- tx_complete ----| | + +-------+ +-------+ + +#### *initiator* and *non-initiator* + +A the *initiator* contributes 2 inputs and an output that they +then remove. B, the *non-initiator*, contributes 1 input and an output, +but waits until A adds a second input before contributing. + +Note that if A does not send a second input, the negotiation will end without +B's contributions. + + +-------+ +-------+ + | |--(1)- tx_add_input -->| | + | |<-(2)- tx_complete ----| | + | |--(3)- tx_add_output ->| | + | |<-(4)- tx_complete ----| | + | |--(5)- tx_add_input -->| | + | A |<-(6)- tx_add_input ---| B | + | |<-(7)- tx_add_output --| | + | |--(8)- tx_rm_output -->| | + | |<-(9)- tx_complete ----| | + | |--(10) tx_complete --->| | + +-------+ +-------+ + + +### The `tx_add_input` Message + +This message contains a transaction input. + +1. type: 66 (`tx_add_input`) +2. data: + * [`channel_id`:`channel_id`] + * [`u64`:`serial_id`] + * [`u16`:`prevtx_len`] + * [`prevtx_len*byte`:`prevtx`] + * [`u32`:`prevtx_vout`] + * [`u32`:`sequence`] + * [`u16`:`script_sig_len`] + * [`script_sig_len*byte`:`script_sig`] + +#### Requirements + +The sending node: + - MUST add all sent inputs to the transaction + - MUST use a unique `serial_id` for each input currently added to the + transaction + - MUST NOT re-transmit inputs it has received from the peer + - if is the *initiator*: + - MUST send even `serial_id`s + - if is the *non-initiator*: + - MUST send odd `serial_id`s + +The receiving node: + - MUST add all received inputs to the transaction + - MUST fail the negotiation if: + - the `prevtx` and `prevtx_vout` are identical to a previously added + (and not removed) input's + - `prevtx` is not a valid transaction + - `prevtx_vout` is greater or equal to the number of outputs on `prevtx` + - the `prevtx_out` input of `prevtx` is not an `OP_0` to `OP_16` + followed by a single push + - the `serial_id` is already included in the transaction + - the `serial_id` has the wrong parity + - if has received 4096 `tx_add_input` messages during this negotiation + +#### Rationale +Each node must know the set of the transaction inputs. The *non-initiator* +MAY omit this message. + +`serial_id` is a randomly chosen number which uniquely identifies this input. +Inputs in the constructed transaction are sorted by `serial_id`. + +`prevtx_tx` is the serialized transaction that contains the output +this input spends. Used to verify that the input is non-malleable. + +`prevtx_vout` is the index of the output being spent. + +`sequence` is the sequence number of this input. Must be less than +4294967294 (0xFFFFFFFE). See BIP125. + +`script_sig` is the scriptSig for the input, with length omitted. +The `script_sig` for non-P2SH-wrapped inputs will be an empty byte. + +### The `tx_add_output` Message + +This message adds a transaction output. + +1. type: 67 (`tx_add_output`) +2. data: + * [`channel_id`:`channel_id`] + * [`u64`:`serial_id`] + * [`u64`:`sats`] + * [`u16`:`scriptlen`] + * [`scriptlen*byte`:`script`] + +#### Requirements + +Either node: + - MAY omit this message + +The sending node: + - MUST add all sent outputs to the transaction + - if is the *initiator*: + - MUST send even `serial_id`s + - if is the *non-initiator*: + - MUST send odd `serial_id`s + +The receiving node: + - MUST add the specified output to the transaction + - MUST accept P2SH, P2WSH, P2WPKH, P2PKH `script`s + - MAY fail the negotiation if `script` is non-standard + - MUST fail the negotiation if: + - the `serial_id` is already included in the transaction + - the `serial_id` has the wrong parity + - it has received 4096 `tx_add_output` messages during this negotiation + - the `sats` amount is less than or equal to the `dust_limit` + + +#### Rationale +Each node must know the set of the transaction outputs. + +`serial_id` is a randomly chosen number which uniquely identifies this output. +Outputs in the constructed transaction are sorted by `serial_id`. + +`sats` is the satoshi value of the output. + +`script` is the scriptPubKey for the output. The length is omitted. +It's left undefined if you accept other standard outputs such as `OP_RETURN` +or implement stricter checks on standardness. + + +### The `tx_remove_input` and `tx_remove_output` Messages +These message removes an input from the transaction. + +1. type: 68 (`tx_remove_input`) +2. data: + * [`channel_id`:`channel_id`] + * [`u64`:`serial_id`] + +This message removes an output from the transaction. + +1. type: 69 (`tx_remove_output`) +2. data: + * [`channel_id`:`channel_id`] + * [`u64`:`serial_id`] + +#### Requirements + +The sending node: + - MUST NOT send a `tx_remove` with a `serial_id` it did not add + to the transaction or has already removed + +The receiving node: + - MUST remove the indicated input or output from the transaction + - MUST fail the negotiation if: + - the input or output identified by the `serial_id` was not added by the + sender + - the `serial_id` does not correspond to a currently added input (or output) + + +### The `tx_complete` Message + +This message signals the conclusion of a peer's transaction +contributions. + +1. type: 70 (`tx_complete`) +2. data: + * [`channel_id`:`channel_id`] + + +#### Requirements + +The nodes: + - MUST send this message in succession to conclude this protocol + +The receiving node: + - MUST use the negotiated inputs and outputs to construct a transaction + - MUST fail the negotiation if: + - the peer's total input satoshis is less than their outputs + - the peer's paid feerate does not meet or exceed the agreed `feerate`, + (based on the `minimum fee`). + - if is the *non-initiator*: + - the *initiator*'s fees do not cover the `common` fields + - there are more than 252 inputs + - there are more than 252 outputs + +#### Rationale +To signal the conclusion of exchange of transaction inputs and outputs. + +Upon successful exchange of `tx_complete` messages, both nodes +should construct the transaction and proceed to the next portion of the +protocol. For channel establishment v2, exchanging commitment transactions. + +For the `minimum fee` calculation see [BOLT #3](03-transactions.md#calculating-fees-for-collaborative-transaction-construction). + +The maximum inputs and outputs are capped at 252. This effectively fixes +the byte size of the input and output counts on the transaction to one (1). + + +### The `tx_signatures` Message + +1. type: 71 (`tx_signatures`) +2. data: + * [`channel_id`:`channel_id`] + * [`sha256`:`txid`] + * [`u16`:`num_witnesses`] + * [`num_witnesses*witness_stack`:`witness_stack`] + +1. subtype: `witness_stack` +2. data: + * [`u16`:`num_input_witness`] + * [`num_input_witness*witness_element`:`witness_element`] + +1. subtype: `witness_element` +2. data: + * [`u16`:`len`] + * [`len*byte`:`witness`] + + +#### Requirements +The sending node: + - MUST order the `witness_stack`s by the `serial_id` of the input they + correspond to + - number of `witness_stack`s MUST equal the number of inputs they added + +The receiving node: + - MUST fail the negotiation if: + - the message contains an empty `witness_stack` + - the number of `witness_stack`s does not equal the number of inputs + added by the sending node + - the `txid` does not match the txid of the transaction + - MUST fail the channel if: + - the `witness_stack` weight lowers the effective `feerate` + below the agreed upon transaction `feerate` + - SHOULD apply the `witness`es to the transaction and broadcast it + - MUST reply with their `tx_signatures` if not already transmitted + + +#### Rationale +`witness` is the data for a witness element in a witness stack. +Witness elements should *not* include their length. + +Witness data must be sorted according to the `serial_id` of +the corresponding input. + +While the `minimum fee` is calculated and verified at `tx_complete` conclusion, +it is possible for the fee for the exchanged witness data to be underpaid. +It is the responsibility of the sending peer to correctly account for the +required fee, e.g. a multisig witness stack whose weight exceeds 110. +If the fees paid by the peer (inputs - outputs) does not meet or exceed +the pre-established `feerate`, the receiving peer SHOULD immediately +fail the channel by broadcasting their commitment transaction. + ## Channel Establishment After authenticating and initializing a connection ([BOLT #8](08-transport.md) and [BOLT #1](01-messaging.md#the-init-message), respectively), channel establishment may begin. + +There are two pathways for establishing a channel, a legacy version presented here, +and a second version ([below](#channel-establishment-v2)). Which channel +establishment protocols are available for use is negotiated in the `init` message. + This consists of the funding node (funder) sending an `open_channel` message, followed by the responding node (fundee) sending `accept_channel`. With the channel parameters locked in, the funder is able to create the funding @@ -230,6 +598,8 @@ The receiving node MUST: `open_channel`, BUT before receiving a `funding_created` message: - accept a new `open_channel` message. - discard the previous `open_channel` message. + - if `option_dual_fund` has been negotiated: + - fail the channel. The receiving node MAY fail the channel if: - `announce_channel` is `false` (`0`), yet it wishes to publicly announce the channel. @@ -445,6 +815,338 @@ to broadcast the commitment transaction to get his funds back and open a new channel. To avoid this, the funder should ensure the funding transaction confirms in the next 2016 blocks. +If an RBF negotiation is in progress when a `funding_locked` message is +exchanged, the negotiation must be abandoned. + +## Channel Establishment v2 + +This is a revision of the channel establishment protocol. +It changes the previous protocol to allow the `accept_channel2` peer +(the *accepter*/*non-initiator*) to contribute inputs to the funding +transaction, via the interactive transaction construction protocol. + +The protocol is also expanded to include a mechanism for initiating RBF. + + +-------+ +-------+ + | |--(1)--- open_channel2 ----->| | + | |<-(2)--- accept_channel2 -----| | + | | | | + --->| | | | + | | | | | + | | |--(3)-- commitment_signed -->| | + | | |<-(4)-- commitment_signed ---| | + | | A | | B | + | | |<-(5)-- tx_signatures -------| | + | | |--(6)-- tx_signatures ------>| | + | | | | | + | | |--(a)--- init_rbf ----------->| | + ----| |<-(b)--- ack_rbf ------------| | + | | | | + | |--(7)--- funding_locked ----->| | +n- + | |<-(8)--- funding_locked ------| | + +-------+ +-------+ + + - where node A is *opener*/*initiator* and node B is + *accepter*/*non-initiator* + +### The `open_channel2` Message + +This message initiates the v2 channel establishment workflow. + +1. type: 64 (`open_channel2`) +2. data: + * [`chain_hash`:`chain_hash`] + * [`channel_id`:`channel_id`] + * [`u32`:`funding_feerate_perkw`] + * [`u32`:`commitment_feerate_perkw`] + * [`u64`:`funding_satoshis`] + * [`u64`:`dust_limit_satoshis`] + * [`u64`:`max_htlc_value_in_flight_msat`] + * [`u64`:`htlc_minimum_msat`] + * [`u16`:`to_self_delay`] + * [`u16`:`max_accepted_htlcs`] + * [`u32`:`locktime`] + * [`point`:`funding_pubkey`] + * [`point`:`revocation_basepoint`] + * [`point`:`payment_basepoint`] + * [`point`:`delayed_payment_basepoint`] + * [`point`:`htlc_basepoint`] + * [`point`:`first_per_commitment_point`] + * [`byte`:`channel_flags`] + * [`opening_tlvs`:`tlvs`] + + +1. `tlv_stream`: `opening_tlvs` +2. types: + 1. type: 1 (`option_upfront_shutdown_script`) + 2. data: + * [`u16`:`shutdown_len`] + * [`shutdown_len*byte`:`shutdown_scriptpubkey`] + + +Rationale and Requirements are the same as for [`open_channel`](#the-open_channel-message), with the following additions: + +#### Requirements: + +If nodes have negotiated `option_dual_fund`: + - the opening node: + - MUST NOT send `open_channel` + +The sending node: + - MUST set `funding_feerate_perkw` to the feerate for this transaction + - MUST ensure `temporary_channel_id` is unique from any + other channel ID with the same peer. + +The receiving node: + - MAY fail the negotiation if: + - the `locktime` is unacceptable + - the `funding_feerate_per_kw` is unacceptable + +#### Rationale +`channel_id` for the `open_channel2` MUST be derived using a zero-d out +basepoint for the peer's revocation basepoint. This allows the peer to +return channel-assignable errors before the *accepter*'s revocation +basepoint is known. + +`funding_feerate_perkw` indicates the fee rate that the opening node will +pay for the funding transaction in satoshi per 1000-weight, as described +in [BOLT-3, Appendix F](03-transactions.md#appendix-f-dual-funded-transaction-test-vectors). + +`locktime` is the locktime for the funding transaction. + +The receiving node, if the `locktime` or `feerate_funding_perkw` is considered +out of an acceptable range, may fail the negotiation. However, it is +recommended that the *accepter* permits the channel open to proceed +without their participation in the channel's funding. + +Note that `open_channel`'s `channel_reserve_satoshi` has been omitted. +Instead, the channel reserve is fixed at 1% of the total channel balance +(`open_channel2`.`funding_satoshis` + `accept_channel2`.`funding_satoshis`) +rounded down to the nearest whole satoshi or the `dust_limit_satoshis`, +whichever is greater. + +Note that `push_msat` has been omitted. + +### The `accept_channel2` Message + +This message contains information about a node and indicates its +acceptance of the new channel. + +1. type: 65 (`accept_channel2`) +2. data: + * [`channel_id`:`channel_id`] + * [`u64`:`funding_satoshis`] + * [`u64`:`dust_limit_satoshis`] + * [`u64`:`max_htlc_value_in_flight_msat`] + * [`u64`:`htlc_minimum_msat`] + * [`u32`:`minimum_depth`] + * [`u16`:`to_self_delay`] + * [`u16`:`max_accepted_htlcs`] + * [`point`:`funding_pubkey`] + * [`point`:`revocation_basepoint`] + * [`point`:`payment_basepoint`] + * [`point`:`delayed_payment_basepoint`] + * [`point`:`htlc_basepoint`] + * [`point`:`first_per_commitment_point`] + * [`accept_tlvs`:`tlvs`] + +1. `tlv_stream`: `accept_tlvs` +2. types: + 1. type: 1 (`option_upfront_shutdown_script`) + 2. data: + * [`u16`:`shutdown_len`] + * [`shutdown_len*byte`:`shutdown_scriptpubkey`] + + +Rationale and Requirements are the same as listed above, +for [`accept_channel`](#the-accept_channel-message) with the following +additions. + +#### Requirements: + +The accepting node: + - MAY respond with a `funding_satoshis` value of zero. + +#### Rationale + +The `funding_satoshis` is the amount of bitcoin in satoshis +the *accepter* will be contributing to the channel's funding transaction. + +Note that `accept_channel`'s `channel_reserve_satoshi` has been omitted. +Instead, the channel reserve is fixed at 1% of the total channel balance +(`open_channel2`.`funding_satoshis` + `accept_channel2`.`funding_satoshis`) +rounded down to the nearest whole satoshi or the `dust_limit_satoshis`, +whichever is greater. + + +### Funding Composition +Funding composition for channel establishment v2 makes use of the +[Interactive Transaction Construction](#interactive-transaction-construction) +protocol, with the following additional caveats. + + +#### The `tx_add_input` Message + +No additional caveats or requirements. + + +#### The `tx_add_output` Message +##### Requirements +The sending node: + - if is the *opener*: + - MUST send at least one `tx_add_output`, which contains the + channel's funding output + +##### Rationale +The channel funding output must be added by the *opener*, who pays its fees. + + +#### The `tx_complete` Message + +Upon receipt of consecutive `tx_complete`s, the receiving node: + - if is the *accepter*: + - MUST fail the negotiation if: + - no funding output was received + - the value of the funding output is not equal to the sum of + `open_channel2`.`funding_satoshis` and `accept_channel2`. + `funding_satoshis` + - the value of the funding output is less than the `dust_limit` + - if is an RBF attempt: + - MUST fail the negotiation if: + - the transaction's total fees is less than the last + successfully negotiated transaction's fees + - the transaction does not share a common input with all previous + funding transactions + +### The `commitment_signed` Message + +This message is exchanged by both peers. It contains the signatures for +the first commitment transaction. + +Rationale and Requirements are the same as listed below, +for [`commitment_signed`](#commiting-updates-so-far-commitment_signed) with the following additions. + +#### Requirements + +The sending node: + - MUST send zero HTLC's. + +The receiving node: + - if the message has one or more HTLC's: + - MUST fail the negotiation + - if it has not already transmitted its `commitment_signed`: + - MUST send `commitment_signed` + - Otherwise: + - MUST send `tx_signatures` + +#### Rationale + +The first commitment transaction has no HTLC's. + + +### Sharing funding signatures: `tx_signatures` + +After a valid `commitment_signature` has been received +from the peer and a `commitment_signature` has been sent, a peer: + - MUST transmit a [`tx_signatures` message](#the-tx_signatures-message) with their signatures for + the funding transaction + + +#### Requirements +The sending node: + - MUST verify it has received a valid commitment signature from its peer + - MUST remember the details of this funding transaction + - if it has NOT received a valid `commitment_signed` message: + - MUST NOT send a `tx_signatures` message + +The receiving node: + - if the received `witness_stack` weight results in the peer's + paid feerate falling below the *opener*'s feerate for the funding + transaction: + - SHOULD broadcast their commitment transaction, closing the channel. + - SHOULD apply `witness`es to the funding transaction and broadcast it + - if has already sent or received a `funding_locked` message for this + channel: + - MUST ignore this message + +#### Rationale +A peer sends their `tx_signatures` as soon as they have received a valid +`commitments_signed` message. + +The channel should be preemptively closed in the case where a peer provides +valid witness data that causes their paid feerate to fall beneath the +`open_channel2.funding_feerate_perkw` rate. This penalizes the peer +for underpayment of fees. + + +### The `init_rbf` Message + +This message initiates a replacement of a broadcast funding transaction. + +1. type: 72 (`init_rbf`) +2. data: + * [`channel_id`:`channel_id`] + * [`u64`:`funding_satoshis`] + * [`u32`:`locktime`] + * [`byte`:`fee_step`] + +#### Requirements + +The sender: + - MUST have sent `open_channel2` + - MUST set `fee_step` greater than zero and greater than any prior `fee_step` + - MUST NOT have sent or received a `funding_locked` message. + +The recipient: + - MUST respond with either an error or an `ack_rbf` message. + - MUST fail the negotiation if: + - the `fee_step` is not greater than the last successfully negotiated + `init_rbf` attempt or `one` if no prior successful `init_rbf` has + been received + - they have already sent or received `funding_locked` + - MAY fail the negotiation for any reason + +#### Rationale +`fee_step` is an integer value, which specifies the `feerate` for this +funding transaction, as a rate of increase above the `open_channel2`. +`funding_feerate_perkw`. + +The effective `funding_feerate_perkw` for this RBF attempt +if calculated as 1.25^`fee_step` * `funding_feerate_perkw`. +E.g. if `feerate_per_kw_funding` is 512 and the `fee_step` is 1, +the effective `feerate` for this RBF attempt is 512 + 512 / 4 or 640 sat/kw. +A `fee_step` 2 would be `1.25^2 * 512` (or 640 + 640 / 4), 800 sat/kw. + +If a valid `funding_locked` message is received in the middle of an +RBF attempt, the attempt MUST be abandoned. + +### The `ack_rbf` Message + +1. type: 73 (`ack_rbf`) +2. data: + * [`channel_id`:`channel_id`] + * [`u64`:`funding_satoshis`] + +#### Requirements + +The sender: + - MUST NOT have sent or received a `funding_locked` message + +The recipient: + - MUST either fail the negotiation or transmit a `tx_add_input` message + +#### Rationale +`funding_satoshis` is the amount of satoshis that this peer will +contribute to the funding output. Note that this may be different than +the amount transmitted in either `accept_channel2`.`funding_satoshis` or +any previous `ack_rbf`.`funding_satoshis`, as the amount the *accepter* +wishes to commit to the funding output may change. + +It's recommended that a peer, rather than fail the RBF negotiation due to +a large feerate change, instead sets their `funding_satoshis` to zero, +and decline to participate further in the channel funding. + ## Channel Close Nodes can negotiate a mutual close of the connection, which unlike a diff --git a/03-transactions.md b/03-transactions.md index 91a196f59..64d6966bb 100644 --- a/03-transactions.md +++ b/03-transactions.md @@ -37,6 +37,7 @@ This details the exact format of on-chain transactions, which both sides need to * [Storage Tests](#storage-tests) * [Appendix E: Key Derivation Test Vectors](#appendix-e-key-derivation-test-vectors) * [Appendix F: Commitment and HTLC Transaction Test Vectors (anchors)](#appendix-f-commitment-and-htlc-transaction-test-vectors-anchors) + * [Appendix G: Dual Funded Transaction Test Vectors](#appendix-f-dual-funded-transaction-test-vectors) * [References](#references) * [Authors](#authors) @@ -477,6 +478,14 @@ A node: - if the resulting fee rate is too low: - MAY fail the channel. + +### Calculating Fees for Collaborative Transactions + +For transactions constructed using the [interactive protocol](02-peer-protocol.md#interactive-transaction-construction), +fees are paid by each party to the transaction, at `feerate` determined during the +initiation, with the initiator covering the fees for the common transaction fields. + + ## Commitment Transaction Construction This section ties the previous sections together to detail the @@ -710,6 +719,104 @@ at each bucket is a prefix of the desired index. # Appendix A: Expected Weights +## Expected Weight of the Funding Transaction (v2 Channel Establishment) + +The *expected weight* of a funding transaction is calculated as follows: + + inputs: 40 bytes + var_int + `scriptlen` + - previous_out_point: 36 bytes + - hash: 32 bytes + - index: 4 bytes + - var_int: ? bytes (dependent on `scriptlen`) + - script_sig: `scriptlen` + - witness <---- Cost for "witness" data calculated separately. + - sequence: 4 bytes + + non_funding_outputs: 8 bytes + var_int + `scriptlen` + - value: 8 bytes + - var_int: ? bytes (dependent on `scriptlen`) + - script_sig: `scriptlen` + + funding_output: 43 bytes + - value: 8 bytes + - var_int: 1 byte + - script: 34 bytes + - OP_0: 1 byte + - PUSHDATA(32-byte-hash): 33 bytes + +Multiplying non-witness data by 4 results in a weight of: + + // transaction_fields = 10 (version, input count, output count, locktime) + // segwit_fields = 2 (marker + flag) + // funding_transaction = 43 + num_inputs * 40 + num_outputs * 8 + // + sum(scriptlen) + sum(var_ints) + + funding_transaction_weight = 4 * (funding_transaction + transaction_fields) + segwit_fields + + witness_weight = sum(max_witness_len) + + overall_weight = funding_transaction_weight + witness_weight + +### Calculating Fees for Collaborative Transaction Construction + +Every participant in a collaborative transaction covers the fees for +their own inputs and outputs. The initiator also provides funds to +cover for the common transaction fields. + +Upon successful exchange of `tx_complete` messages, each peer must at +least cover a minimum estimated fee. Here is how to calculate the minimum +fee for each participant. + +The minimum witness weight for an input is 110. + +In the following, the initiator has provided one input (P2WPKH), one change output +(P2WPKH), and the funding output. The contributor has provided two +inputs (P2WPKH) and two change outputs (P2WPKH). + +Assuming a `feerate` of 253 per kiloweight, the initiator's minimum fee is +calculated as follows. Note that the feerate is rounded down to the nearest satoshi. + + initiator_weight = transaction_fields * 4 + + segwit_fields + + p2wpkh_input * 4 + + funding_output * 4 + + p2wpkh_output * 4 + + input_count * 110 (minimum witness weight) + + initiator_weight = 10 * 4 + + 2 + + 41 * 4 + + 43 * 4 + + 31 * 4 + + 107 + + initiator_weight = 612 + + initiator_fees = initiator_weight * feerate + initiator_fees = 612 * 253 / 1000 + initiator_fees = 154 sats + +The contributor's minimum fee is calculated as follows. + + contributor_weight = 2 * p2wpkh_input * 4 + + 2 * p2wpkh_output * 4 + + input_count * 110 (minimum witness weight) + + contributor_weight = 2 * 41 * 4 + + 2 * 31 * 4 + + 2 * 110 + + contributor_weight = 796 + + contributor_fees = contributor_weight * feerate + contributor_fees = 796 * 253 / 1000 + contributor_fees = 201 sats + + +This is an estimated fee. The peer MUST at least contribute the estimated rate, +and MUST exceed the minimum fee in the case that their witness weight is greater +than the estimated weight of 110 per input. + + ## Expected Weight of the Commitment Transaction The *expected weight* of a commitment transaction is calculated as follows: @@ -1006,7 +1113,7 @@ The resulting funding transaction is: In the following: - *local* transactions are considered, which implies that all payments to *local* are delayed. - - It's assumed that *local* is the funder. + - It's assumed that *local* is the opener. - Private keys are displayed as 32 bytes plus a trailing 1 (Bitcoin's convention for "compressed" private keys, i.e. keys for which the public key is compressed). - Transaction signatures are all deterministic, using RFC6979 (using HMAC-SHA256). @@ -2380,6 +2487,244 @@ before subtraction of: "RemoteSigHex": "3045022100c592f6b80d35b4f5d1e3bc9788f51141a0065be6013bad53a1977f7c444651660220278ac06ead9016bfb8dc476f186eabace2b02793b2f308442f5b0d5f24a68948" } ] + +# Appendix G: Dual Funded Transaction Test Vectors + +## Funding Transaction Construction +### Preliminaries: + +``` +Genesis block 0: +0100000000000000000000000000000000000000000000000000000000000000000000003ba3edfd7a7b12b27ac72c3e67768f617fc81bc3888a51323a9fb8aa4b1e5e4adae5494dffff7f20020000000101000000010000000000000000000000000000000000000000000000000000000000000000ffffffff4d04ffff001d0104455468652054696d65732030332f4a616e2f32303039204368616e63656c6c6f72206f6e206272696e6b206f66207365636f6e64206261696c6f757420666f722062616e6b73ffffffff0100f2052a01000000434104678afdb0fe5548271967f1a67130b7105cd6a828e03909a67962e0ea1f61deb649f6bc3f4cef38c4f35504e51ec112de5c384df7ba0b8d578a4c702b6bf11d5fac00000000 + +Block 1:0000002006226e46111a0b59caaf126043eb5bbf28c34f3a5e332a1fc7b2b73cf188910ff86fd1d0db3ac5a72df968622f31e6b5e6566a09e29206d7c7a55df90e181de8be86815cffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03510101ffffffff0200f2052a0100000017a914113ca7e584fe1575b6fc39abae991529f66eda58870000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000 +Coinbase address pubkey: 2MtpN8zCxTp8AWSg7VBjBX7vU6x73bVCKP8 +Coinbase address privkey: cPxFtfE1w3ptFnsZvvFeWji21kTArYa9GXwMkYsoQHdaJKrjUTek + +Parent transaction (spends coinbase of block 1): +02000000000101f86fd1d0db3ac5a72df968622f31e6b5e6566a09e29206d7c7a55df90e181de800000000171600141fb9623ffd0d422eacc450fd1e967efc477b83ccffffffff0580b2e60e00000000220020fd89acf65485df89797d9ba7ba7a33624ac4452f00db08107f34257d33e5b94680b2e60e0000000017a9146a235d064786b49e7043e4a042d4cc429f7eb6948780b2e60e00000000160014fbb4db9d85fba5e301f4399e3038928e44e37d3280b2e60e0000000017a9147ecd1b519326bc13b0ec716e469b58ed02b112a087f0006bee0000000017a914f856a70093da3a5b5c4302ade033d4c2171705d387024730440220696f6cee2929f1feb3fd6adf024ca0f9aa2f4920ed6d35fb9ec5b78c8408475302201641afae11242160101c6f9932aeb4fcd1f13a9c6df5d1386def000ea259a35001210381d7d5b1bc0d7600565d827242576d9cb793bfe0754334af82289ee8b65d137600000000 +``` + +### Funding transaction (spends parent's outputs): + +Locktime: 618013 +Feerate: 253 sat/kiloweight +Opener's `funding_satoshi`: 4 0000 0000 sat +Accepter's `funding_satoshi`: 4 0000 0000 sat + +Inputs: +``` +4303ca8ff10c6c345b9299672a66f111c5b81ae027cc5b0d4d39d09c66b032b9 0 + witness_data: + preimage: 20 68656c6c6f2074686572652c2074686973206973206120626974636f6e212121 + witness_script: 27 82012088a820add57dfe5277079d069ca4ad4893c96de91f88ffb981fdc6a2a34d5336c66aff87 + scriptPubKey: 0020fd89acf65485df89797d9ba7ba7a33624ac4452f00db08107f34257d33e5b946 + address: bcrt1qlky6eaj5sh0cj7tanwnm573nvf9vg3f0qrdssyrlxsjh6vl9h9rql40v2g + +4303ca8ff10c6c345b9299672a66f111c5b81ae027cc5b0d4d39d09c66b032b9 1 + redeemScript: 0020fd89acf65485df89797d9ba7ba7a33624ac4452f00db08107f34257d33e5b946 + witness_data: + preimage: 20 68656c6c6f2074686572652c2074686973206973206120626974636f6e212121 + witness_script: 27 82012088a820add57dfe5277079d069ca4ad4893c96de91f88ffb981fdc6a2a34d5336c66aff87 + scriptPubKey: a9146a235d064786b49e7043e4a042d4cc429f7eb69487 + address: 2N2vRyi3cm5VYpw218MJJrJWK1Jd4qbaefW + +4303ca8ff10c6c345b9299672a66f111c5b81ae027cc5b0d4d39d09c66b032b9 2 + pubkey: 034695f5b7864c580bf11f9f8cb1a94eb336f2ce9ef872d2ae1a90ee276c772484 + privkey: cUM8Dr33wK4uFmw3Tz8sbQ7BiBNgX5BthRurU7RkgXVvNUPcWrJf + witness_program: fbb4db9d85fba5e301f4399e3038928e44e37d32 + scriptPubKey: 0014fbb4db9d85fba5e301f4399e3038928e44e37d32 + address: bcrt1qlw6dh8v9lwj7xq058x0rqwyj3ezwxlfjxsy7er + +4303ca8ff10c6c345b9299672a66f111c5b81ae027cc5b0d4d39d09c66b032b9 3 + pubkey: 034695f5b7864c580bf11f9f8cb1a94eb336f2ce9ef872d2ae1a90ee276c772484 + privkey: cUM8Dr33wK4uFmw3Tz8sbQ7BiBNgX5BthRurU7RkgXVvNUPcWrJf + redeemScript: 0014fbb4db9d85fba5e301f4399e3038928e44e37d32 + witness_program: fbb4db9d85fba5e301f4399e3038928e44e37d32 + scriptPubKey: a9147ecd1b519326bc13b0ec716e469b58ed02b112a087 + address: 2N4ogqX3kaLTT2jjxi18nAiyWdwKtE5PxLF +``` + +Expected Opener's `tx_add_input` (inputs 0+1 above): +``` + num_inputs: 2 + tx_add_input:[ + { + channel_id: xxx, + serial_id: 10, + prevtx_len: 353, + prevtx: 02000000000101f86fd1d0db3ac5a72df968622f31e6b5e6566a09e29206d7c7a55df90e181de800000000171600141fb9623ffd0d422eacc450fd1e967efc477b83ccffffffff0580b2e60e00000000220020fd89acf65485df89797d9ba7ba7a33624ac4452f00db08107f34257d33e5b94680b2e60e0000000017a9146a235d064786b49e7043e4a042d4cc429f7eb6948780b2e60e00000000160014fbb4db9d85fba5e301f4399e3038928e44e37d3280b2e60e0000000017a9147ecd1b519326bc13b0ec716e469b58ed02b112a087f0006bee0000000017a914f856a70093da3a5b5c4302ade033d4c2171705d387024730440220696f6cee2929f1feb3fd6adf024ca0f9aa2f4920ed6d35fb9ec5b78c8408475302201641afae11242160101c6f9932aeb4fcd1f13a9c6df5d1386def000ea259a35001210381d7d5b1bc0d7600565d827242576d9cb793bfe0754334af82289ee8b65d137600000000 +, + prev_vout: 0, + sequence: 4294967293, + script_sig_len: 0, + script_sig: null + },{ + channel_id: xxx, + serial_id: 20, + prevtx_len: 353, + prevtx: 02000000000101f86fd1d0db3ac5a72df968622f31e6b5e6566a09e29206d7c7a55df90e181de800000000171600141fb9623ffd0d422eacc450fd1e967efc477b83ccffffffff0580b2e60e00000000220020fd89acf65485df89797d9ba7ba7a33624ac4452f00db08107f34257d33e5b94680b2e60e0000000017a9146a235d064786b49e7043e4a042d4cc429f7eb6948780b2e60e00000000160014fbb4db9d85fba5e301f4399e3038928e44e37d3280b2e60e0000000017a9147ecd1b519326bc13b0ec716e469b58ed02b112a087f0006bee0000000017a914f856a70093da3a5b5c4302ade033d4c2171705d387024730440220696f6cee2929f1feb3fd6adf024ca0f9aa2f4920ed6d35fb9ec5b78c8408475302201641afae11242160101c6f9932aeb4fcd1f13a9c6df5d1386def000ea259a35001210381d7d5b1bc0d7600565d827242576d9cb793bfe0754334af82289ee8b65d137600000000 + prev_vout: 1, + sequence: 4294967293, + script_sig_len: 68, + script_sig: 0020fd89acf65485df89797d9ba7ba7a33624ac4452f00db08107f34257d33e5b946 + } + ] +``` + +Expected Accepter's `tx_add_input` (inputs 2+3 above): +``` + num_inputs: 2 + tx_add_input:[ + { + channel_id: xxx, + serial_id: 11, + prevtx_len: 353, + prevtx: 02000000000101f86fd1d0db3ac5a72df968622f31e6b5e6566a09e29206d7c7a55df90e181de800000000171600141fb9623ffd0d422eacc450fd1e967efc477b83ccffffffff0580b2e60e00000000220020fd89acf65485df89797d9ba7ba7a33624ac4452f00db08107f34257d33e5b94680b2e60e0000000017a9146a235d064786b49e7043e4a042d4cc429f7eb6948780b2e60e00000000160014fbb4db9d85fba5e301f4399e3038928e44e37d3280b2e60e0000000017a9147ecd1b519326bc13b0ec716e469b58ed02b112a087f0006bee0000000017a914f856a70093da3a5b5c4302ade033d4c2171705d387024730440220696f6cee2929f1feb3fd6adf024ca0f9aa2f4920ed6d35fb9ec5b78c8408475302201641afae11242160101c6f9932aeb4fcd1f13a9c6df5d1386def000ea259a35001210381d7d5b1bc0d7600565d827242576d9cb793bfe0754334af82289ee8b65d137600000000 + prev_vout: 2, + script_sig_len: 0, + script_sig: null + },{ + channel_id: xxx, + serial_id: 17, + prevtx_len: 353, + prevtx: 02000000000101f86fd1d0db3ac5a72df968622f31e6b5e6566a09e29206d7c7a55df90e181de800000000171600141fb9623ffd0d422eacc450fd1e967efc477b83ccffffffff0580b2e60e00000000220020fd89acf65485df89797d9ba7ba7a33624ac4452f00db08107f34257d33e5b94680b2e60e0000000017a9146a235d064786b49e7043e4a042d4cc429f7eb6948780b2e60e00000000160014fbb4db9d85fba5e301f4399e3038928e44e37d3280b2e60e0000000017a9147ecd1b519326bc13b0ec716e469b58ed02b112a087f0006bee0000000017a914f856a70093da3a5b5c4302ade033d4c2171705d387024730440220696f6cee2929f1feb3fd6adf024ca0f9aa2f4920ed6d35fb9ec5b78c8408475302201641afae11242160101c6f9932aeb4fcd1f13a9c6df5d1386def000ea259a35001210381d7d5b1bc0d7600565d827242576d9cb793bfe0754334af82289ee8b65d137600000000 + prev_vout: 3, + script_sig_len: 22, + script_sig: 0014fbb4db9d85fba5e301f4399e3038928e44e37d32 + } + ] +``` + +Outputs: (scriptPubKeys) +``` +# opener's change address +pubkey: 0206e626a4c6d4392d4030bc78bd93f728d1ba61214a77c63adc17d71e32ded3df +# privkey: cSpC1KYEV1vsUFBwTdcuRkncbwfipY1m5zuQ9CjgAYwiVvbQ4fc1 +scriptPubKey: 00141ca1cca8855bad6bc1ea5436edd8cff10b7e448b +address: bcrt1qrjsue2y9twkkhs022smwmkx07y9hu3ytshgjmj + +# accepter's change address +pubkey: 028f3978c211f4c0bf4d20674f345ae14e08871b25b2c957b4bdbd42e9726278fc +privkey: cQ1HXnbAE4wGhuB2b9rJEydV5ayeEmMqxf1dvHPZmyMTPkwvZJyg +scriptPubKey: 001444cb0c39f93ecc372b5851725bd29d865d333b10 +address: bcrt1qgn9scw0e8mxrw26c29e9h55asewnxwcsdxdp50 + +# the 2-of-2s +pubkey1: 0292edb5f7bbf9e900f7e024be1c1339c6d149c11930e613af3a983d2565f4e41e +pubkey2: 02e16172a41e928cbd78f761bd1c657c4afc7495a1244f7f30166b654fbf7661e3 +script_def: multi(2,0292edb5f7bbf9e900f7e024be1c1339c6d149c11930e613af3a983d2565f4e41e,02e16172a41e928cbd78f761bd1c657c4afc7495a1244f7f30166b654fbf7661e3) +script: 52210292edb5f7bbf9e900f7e024be1c1339c6d149c11930e613af3a983d2565f4e41e2102e16172a41e928cbd78f761bd1c657c4afc7495a1244f7f30166b654fbf7661e352ae +scriptPubKey: 0020297b92c238163e820b82486084634b4846b86a3c658d87b9384192e6bea98ec5 +address: bcrt1q99ae9s3czclgyzuzfpsggc6tfprts63uvkxc0wfcgxfwd04f3mzs3asq6l +``` + +Expected Opener's `tx_add_output`: + +``` + num_outputs: 2 + tx_add_output[ + { + channel_id: xxx, + serial_id: 30, + sats: 99999809 + scriptlen: 22 + script: 1600141ca1cca8855bad6bc1ea5436edd8cff10b7e448b + },{ + channel_id: xxx, + serial_id: 44, + sats: 800000000 + scriptlen: 34 + script: 220020297b92c238163e820b82486084634b4846b86a3c658d87b9384192e6bea98ec5 + } + ] +``` + +Expected Accepter's `tx_add_output`: + +``` + num_outputs: 1 + tx_add_output[ + { + channel_id: xxx, + serial_id: 33, + sats: 99999809 + scriptlen: 22 + script: 16001444cb0c39f93ecc372b5851725bd29d865d333b10 + } +``` + +Expected Fee Calculation: + +Opener's fees and change: +``` + initiator_weight = transaction_fields * 4 + + segwit_fields + + inputs * 4 + + funding_output * 4 + + change_output * 4 + + sum_max_witness_weight + + initiator_weight = 10 * 4 + + 2 + + (41 + 74) * 4 + + 43 * 4 + + 31 * 4 + + 148 + + initiator_weight = 946 + + initiator_fees = initiator_weight * feerate + initiator_fees = 946 * 253 / 1000 + initiator_fees = 239 sats + + change = total_funding + - funding_sats + - fees + + change = 5 0000 0000 + - 4 0000 0000 + - 239 + + change = 9999 9761 +``` + +Accepter's fees and change: +``` + contributor_weight = 2 * p2wpkh_input * 4 + + 2 * p2wpkh_output * 4 + + sum_max_witness_weight + + contributor_weight = (41 + 63) * 4 + + 31 * 4 + + 218 + + contributor_weight = 758 + + contributor_fees = contributor_weight * feerate + contributor_fees = 758 * 253 / 1000 + contributor_fees = 191 sats + + change = total_funding + - funding_sats + - fees + + change = 5 0000 0000 + - 4 0000 0000 + - 191 + + change = 9999 9809 + +``` + +Unsigned Funding Transaction: +``` +0200000004b932b0669cd0394d0d5bcc27e01ab8c511f1662a6799925b346c0cf18fca03430000000000ffffffffb932b0669cd0394d0d5bcc27e01ab8c511f1662a6799925b346c0cf18fca03430200000000ffffffffb932b0669cd0394d0d5bcc27e01ab8c511f1662a6799925b346c0cf18fca03430300000000ffffffffb932b0669cd0394d0d5bcc27e01ab8c511f1662a6799925b346c0cf18fca03430100000000ffffffff0341e0f505000000001600141ca1cca8855bad6bc1ea5436edd8cff10b7e448b11e0f5050000000016001444cb0c39f93ecc372b5851725bd29d865d333b100008af2f00000000220020297b92c238163e820b82486084634b4846b86a3c658d87b9384192e6bea98ec51d6e0900 +``` + +Signed Funding Transaction: +``` +TODO ``` # References diff --git a/09-features.md b/09-features.md index b508bac70..c1a8b1793 100644 --- a/09-features.md +++ b/09-features.md @@ -41,6 +41,7 @@ The Context column decodes as follows: | 20/21 | `option_anchor_outputs` | Anchor outputs | IN | `option_static_remotekey` | [BOLT #3](03-transactions.md) | | 22/23 | `option_anchors_zero_fee_htlc_tx` | Anchor commitment type with zero fee HTLC transactions | IN | | [BOLT #3][bolt03-htlc-tx], [lightning-dev][ml-sighash-single-harmful]| | 26/27 | `option_shutdown_anysegwit` | Future segwit versions allowed in `shutdown` | IN | | [BOLT #2][bolt02-shutdown] | +| 28/29 | `option_dual_fund` | Use v2 of channel open, enables dual funding | IN9 | `option_anchor_outputs`, `option_static_remotekey` | [BOLT #2](02-peer-protocol.md) | ## Requirements diff --git a/tools/spellcheck.sh b/tools/spellcheck.sh index fb309315f..709913db3 100755 --- a/tools/spellcheck.sh +++ b/tools/spellcheck.sh @@ -68,7 +68,8 @@ do -e 's/0x[a-fA-F0-9 ]\+//g' \ -e 's/[a-fA-F0-9]\{20,\}//g' \ -e 's/^ .*_htlcs//g' \ - -e 's/ \(bc\|tb\)1[qpzry9x8gf2tvdw0s3jn54khce6mua7l]\+//g' \ + -e 's/ ln\(bc\|tb\)[0-9munp]*1[qpzry9x8gf2tvdw0s3jn54khce6mua7l]\+//g' \ + -e 's/ \(bc\|tb\|bcrt\)1[qpzry9x8gf2tvdw0s3jn54khce6mua7l]\+//g' \ -e 's/pvjluezpp5qqqsyqcyq5rqwzqfqqqsyqcyq5rqwzqfqqqsyqcyq5rqwzqfqypqdpquwpc4curk03c9wlrswe78q4eyqc7d8d0xqzpuyk0sg5g70me25alkluzd2x62aysf2pyy8edtjeevuv4p2d5p76r4zkmneet7uvyakky2zr4cusd45tftc9c5fh0nnqpnl2jfll544esqchsrny//' \ -e 's/[123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz]\{20,\}//g' < $f | tee /tmp/`basename $f`.aspell | aspell -l en_US --home-dir ${homedir} list) if [ -n "$WORDS" ]; then From 07b9ffb49c9a150cbe730e550021a5bd80e66cd0 Mon Sep 17 00:00:00 2001 From: niftynei Date: Fri, 23 Apr 2021 13:45:57 -0500 Subject: [PATCH 02/36] dual-funding: accept_channel2 must also use the temporary channel-id So that it knows what open_channel2 is responding to. Spotted-By: @rustyrussell --- 02-peer-protocol.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index cbec51c00..dce1a1021 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -74,8 +74,9 @@ SHA256(lesser-revocation-basepoint || greater-revocation-basepoint), where the lesser and greater is based off the order of the basepoint. The basepoints are compact DER-encoded public keys. -If the peer's revocation basepoint is unknown (e.g. `open_channel2`), -a temporary `channel_id` should be found by using a zeroed out basepoint for the unknown peer. +If the peer's revocation basepoint is unknown (e.g. `open_channel2` +and `accept_channel2`), a temporary `channel_id` should be found by +using a zeroed out basepoint for the unknown peer. #### Rationale These values must be remembered by both peers for correct operation anyway. @@ -979,6 +980,10 @@ Instead, the channel reserve is fixed at 1% of the total channel balance rounded down to the nearest whole satoshi or the `dust_limit_satoshis`, whichever is greater. +`channel_id` for the `accept_channel2` MUST be derived using a zero-d out +basepoint for the peer's revocation basepoint. This allows the peer to +return channel-assignable errors before the *accepter*'s revocation +basepoint is known. ### Funding Composition Funding composition for channel establishment v2 makes use of the From 3dcb9d17a36be3c75713b910b4ce601807e93599 Mon Sep 17 00:00:00 2001 From: niftynei Date: Tue, 8 Jun 2021 12:56:09 -0500 Subject: [PATCH 03/36] fixup! interactive-tx: Add dual-funding flow, using the interactive tx protocol Suggested-By: Antoine Riard @ariard --- 02-peer-protocol.md | 21 +++++++++++++++++---- 1 file changed, 17 insertions(+), 4 deletions(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index dce1a1021..1f764bd58 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -221,7 +221,7 @@ The receiving node: - `prevtx` is not a valid transaction - `prevtx_vout` is greater or equal to the number of outputs on `prevtx` - the `prevtx_out` input of `prevtx` is not an `OP_0` to `OP_16` - followed by a single push + followed by a single push of 2 to 40 bytes - the `serial_id` is already included in the transaction - the `serial_id` has the wrong parity - if has received 4096 `tx_add_input` messages during this negotiation @@ -276,7 +276,8 @@ The receiving node: - the `serial_id` is already included in the transaction - the `serial_id` has the wrong parity - it has received 4096 `tx_add_output` messages during this negotiation - - the `sats` amount is less than or equal to the `dust_limit` + - the `sats` amount is less than the `dust_limit` + - the `sats` amount is greater than 21,0000,0000 (`MAX_MONEY`) #### Rationale @@ -346,6 +347,7 @@ The receiving node: - the *initiator*'s fees do not cover the `common` fields - there are more than 252 inputs - there are more than 252 outputs + - the estimated weight of the tx is greater than 400,000 (`MAX_STANDARD_TX_WEIGHT`) #### Rationale To signal the conclusion of exchange of transaction inputs and outputs. @@ -382,12 +384,18 @@ the byte size of the input and output counts on the transaction to one (1). #### Requirements The sending node: + - if it has the lowest total satoshis contributed, as defined + by total `tx_add_input` values: + - MUST transmit their `tx_signatures` before the peer - MUST order the `witness_stack`s by the `serial_id` of the input they correspond to - number of `witness_stack`s MUST equal the number of inputs they added The receiving node: - MUST fail the negotiation if: + - if they have not sent a `tx_signatures` message and they are the + peer with the lowest total satoshis contributed, as defined by + `tx_add_input` values - the message contains an empty `witness_stack` - the number of `witness_stack`s does not equal the number of inputs added by the sending node @@ -400,6 +408,10 @@ The receiving node: #### Rationale +The peer with the lowest total of inputs amounts must transmit its +`tx_signatures` first. This gives in a strict ordering of transmission +for any multiparty tx collaboration. + `witness` is the data for a witness element in a witness stack. Witness elements should *not* include their length. @@ -844,7 +856,6 @@ The protocol is also expanded to include a mechanism for initiating RBF. ----| |<-(b)--- ack_rbf ------------| | | | | | | |--(7)--- funding_locked ----->| | -n- | |<-(8)--- funding_locked ------| | +-------+ +-------+ @@ -1139,7 +1150,9 @@ The sender: - MUST NOT have sent or received a `funding_locked` message The recipient: - - MUST either fail the negotiation or transmit a `tx_add_input` message + - MUST either fail the negotiation or transmit a `tx_add_input` message, + restarting the interactive tx collaboration protocol, and proceeding + the same as with `accept_channel2`. #### Rationale `funding_satoshis` is the amount of satoshis that this peer will From b2949cd4fb59d804fb58e7f48bc68d9da40a0c69 Mon Sep 17 00:00:00 2001 From: niftynei Date: Fri, 9 Jul 2021 13:17:06 -0500 Subject: [PATCH 04/36] fixup: remove fee_step from init_rbf in favor of an explicity feerate Remove the fee_step in favor of using an explicit bump feerate, with the constraint that it must be at least 1/64th greater than the last sent rate. Suggested-By: @rustyrussell --- 02-peer-protocol.md | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index 1f764bd58..0a3d03dc9 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -1105,34 +1105,34 @@ This message initiates a replacement of a broadcast funding transaction. * [`channel_id`:`channel_id`] * [`u64`:`funding_satoshis`] * [`u32`:`locktime`] - * [`byte`:`fee_step`] + * [`u32`:`funding_feerate_perkw`] #### Requirements The sender: - MUST have sent `open_channel2` - - MUST set `fee_step` greater than zero and greater than any prior `fee_step` + - MUST set `funding_feerate_perkw` greater than or equal to + 65/64 times the last sent `funding_feerate_perkw` rounded down. - MUST NOT have sent or received a `funding_locked` message. The recipient: - MUST respond with either an error or an `ack_rbf` message. - MUST fail the negotiation if: - - the `fee_step` is not greater than the last successfully negotiated - `init_rbf` attempt or `one` if no prior successful `init_rbf` has - been received + - the `funding_feerate_perkw` is not greater than 65/64 times + `funding_feerate_perkw` of the last successfully negotiated + open attempt - they have already sent or received `funding_locked` - MAY fail the negotiation for any reason #### Rationale -`fee_step` is an integer value, which specifies the `feerate` for this -funding transaction, as a rate of increase above the `open_channel2`. -`funding_feerate_perkw`. - -The effective `funding_feerate_perkw` for this RBF attempt -if calculated as 1.25^`fee_step` * `funding_feerate_perkw`. -E.g. if `feerate_per_kw_funding` is 512 and the `fee_step` is 1, -the effective `feerate` for this RBF attempt is 512 + 512 / 4 or 640 sat/kw. -A `fee_step` 2 would be `1.25^2 * 512` (or 640 + 640 / 4), 800 sat/kw. +`funding_feerate_perkw` is the feerate this funding transaction +will pay. It must be at least 1/64 greater than the last +received `funding_feerate_perkw`, rounded down to the nearest +satoshi. + +E.g. if the last `feerate_per_kw_funding` was 520 +the next sent `feerate_per_kw_funding` must be 528 +(520 * 65 / 64 = 528.125, rounded down to 528). If a valid `funding_locked` message is received in the middle of an RBF attempt, the attempt MUST be abandoned. From 53371feb37d3743898296923e7996df9a8bb18d3 Mon Sep 17 00:00:00 2001 From: niftynei Date: Fri, 13 Aug 2021 18:04:51 -0500 Subject: [PATCH 05/36] fixup: remove '9' from option_dual_fund flag --- 09-features.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/09-features.md b/09-features.md index c1a8b1793..82790fe5a 100644 --- a/09-features.md +++ b/09-features.md @@ -41,7 +41,7 @@ The Context column decodes as follows: | 20/21 | `option_anchor_outputs` | Anchor outputs | IN | `option_static_remotekey` | [BOLT #3](03-transactions.md) | | 22/23 | `option_anchors_zero_fee_htlc_tx` | Anchor commitment type with zero fee HTLC transactions | IN | | [BOLT #3][bolt03-htlc-tx], [lightning-dev][ml-sighash-single-harmful]| | 26/27 | `option_shutdown_anysegwit` | Future segwit versions allowed in `shutdown` | IN | | [BOLT #2][bolt02-shutdown] | -| 28/29 | `option_dual_fund` | Use v2 of channel open, enables dual funding | IN9 | `option_anchor_outputs`, `option_static_remotekey` | [BOLT #2](02-peer-protocol.md) | +| 28/29 | `option_dual_fund` | Use v2 of channel open, enables dual funding | IN | `option_anchor_outputs`, `option_static_remotekey` | [BOLT #2](02-peer-protocol.md) | ## Requirements From 28dfc1c7691d7469af36bb36df9406fd31266fe0 Mon Sep 17 00:00:00 2001 From: niftynei Date: Fri, 13 Aug 2021 18:06:56 -0500 Subject: [PATCH 06/36] fixup: nit, add 'v1' to channel open description --- 01-messaging.md | 2 +- 02-peer-protocol.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/01-messaging.md b/01-messaging.md index ea928c20c..549b7016c 100644 --- a/01-messaging.md +++ b/01-messaging.md @@ -316,7 +316,7 @@ The 2-byte `len` field indicates the number of bytes in the immediately followin The channel is referred to by `channel_id`, unless `channel_id` is 0 (i.e. all bytes are 0), in which case it refers to all channels. -The funding node using channel establishment `open_channel`: +The funding node using channel establishment v1 `open_channel`: - for all error messages sent before (and including) the `funding_created` message: - MUST use `temporary_channel_id` in lieu of `channel_id`. diff --git a/02-peer-protocol.md b/02-peer-protocol.md index 0a3d03dc9..e218ac966 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -16,7 +16,7 @@ operation, and closing. * [The `tx_remove_input` and `tx_remote_output` Messages](#the-tx_remove_input-and-tx_remove_output-messages) * [The `tx_complete` Message](#the-tx_complete-message) * [The `tx_signatures` Message](#the-tx_signatures-message) - * [Channel Establishment](#channel-establishment) + * [Channel Establishment v1](#channel-establishment-v1) * [The `open_channel` Message](#the-open_channel-message) * [The `accept_channel` Message](#the-accept_channel-message) * [The `funding_created` Message](#the-funding_created-message) @@ -426,7 +426,7 @@ If the fees paid by the peer (inputs - outputs) does not meet or exceed the pre-established `feerate`, the receiving peer SHOULD immediately fail the channel by broadcasting their commitment transaction. -## Channel Establishment +## Channel Establishment v1 After authenticating and initializing a connection ([BOLT #8](08-transport.md) and [BOLT #1](01-messaging.md#the-init-message), respectively), channel establishment may begin. From 25af2c69bfb7c253f2e769557d03789363457ddb Mon Sep 17 00:00:00 2001 From: niftynei Date: Fri, 13 Aug 2021 18:09:22 -0500 Subject: [PATCH 07/36] fixup: mirror desc of nLocktime, same as others --- 02-peer-protocol.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index e218ac966..181e6b4fd 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -103,8 +103,7 @@ The protocol makes the following assumptions: - The `feerate` for the transaction is known. - The `dust_limit` for the transaction is known. -- The `nLocktime` for the transaction has been negotiated, or is established - via convention. +- The `nLocktime` for the transaction is known. - The transaction version is 2. ### Fee Responsibility From 4eb0029c2447a55e540db08565b02f675007f789 Mon Sep 17 00:00:00 2001 From: niftynei Date: Fri, 13 Aug 2021 18:11:53 -0500 Subject: [PATCH 08/36] fixup: remove reference to 'DER' encoding As @t-bast points out, we define 'point' in 01, which covers the encoding. --- 02-peer-protocol.md | 1 - 1 file changed, 1 deletion(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index 181e6b4fd..b3d4843c8 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -72,7 +72,6 @@ ids. For channels established using the v2 protocol, the `channel_id` is the SHA256(lesser-revocation-basepoint || greater-revocation-basepoint), where the lesser and greater is based off the order of the basepoint. -The basepoints are compact DER-encoded public keys. If the peer's revocation basepoint is unknown (e.g. `open_channel2` and `accept_channel2`), a temporary `channel_id` should be found by From 89df351815cb61ae2665caff5b1402243bb32750 Mon Sep 17 00:00:00 2001 From: niftynei Date: Fri, 13 Aug 2021 18:13:10 -0500 Subject: [PATCH 09/36] fixup: remove errant 'n' --- 02-peer-protocol.md | 1 - 1 file changed, 1 deletion(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index b3d4843c8..3d153e441 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -148,7 +148,6 @@ Here are a few example exchanges. A, *initiator* has two inputs and an output (the funding output). B, the *non-initiator* has nothing to contribute. -n +-------+ +-------+ | |--(1)- tx_add_input -->| | From db2bf1df57f599c8722ca722ba0ad534afb9086f Mon Sep 17 00:00:00 2001 From: niftynei Date: Fri, 13 Aug 2021 18:19:20 -0500 Subject: [PATCH 10/36] fixup: clarify exactly what field on `prevtx` should be `OP_1..OP_16` Suggested-By: @t-bast --- 02-peer-protocol.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index 3d153e441..dabd1266c 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -217,7 +217,7 @@ The receiving node: (and not removed) input's - `prevtx` is not a valid transaction - `prevtx_vout` is greater or equal to the number of outputs on `prevtx` - - the `prevtx_out` input of `prevtx` is not an `OP_0` to `OP_16` + - the `scriptPubKey` of the `prevtx_out` output of `prevtx` does not begin with `OP_0` to `OP_16` followed by a single push of 2 to 40 bytes - the `serial_id` is already included in the transaction - the `serial_id` has the wrong parity From eaaf6fa49084072f41e943a88fd517c2ee0e916f Mon Sep 17 00:00:00 2001 From: niftynei Date: Fri, 13 Aug 2021 18:22:15 -0500 Subject: [PATCH 11/36] fixup: correct name prevtx_tx -> prevtx --- 02-peer-protocol.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index dabd1266c..697763da1 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -230,7 +230,7 @@ MAY omit this message. `serial_id` is a randomly chosen number which uniquely identifies this input. Inputs in the constructed transaction are sorted by `serial_id`. -`prevtx_tx` is the serialized transaction that contains the output +`prevtx` is the serialized transaction that contains the output this input spends. Used to verify that the input is non-malleable. `prevtx_vout` is the index of the output being spent. From 801166fc4dbba7459db854c7992c997d48ddd447 Mon Sep 17 00:00:00 2001 From: niftynei Date: Fri, 13 Aug 2021 18:25:40 -0500 Subject: [PATCH 12/36] fixup: the `script_sig` should be empty, thus an empty array not byte Spotted-By: @t-bast --- 02-peer-protocol.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index 697763da1..af6ac5b0a 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -239,7 +239,7 @@ this input spends. Used to verify that the input is non-malleable. 4294967294 (0xFFFFFFFE). See BIP125. `script_sig` is the scriptSig for the input, with length omitted. -The `script_sig` for non-P2SH-wrapped inputs will be an empty byte. +The `script_sig` for non-P2SH-wrapped inputs will be an empty byte array. ### The `tx_add_output` Message From 105213d4f7a17db82e3f64d238cca69fcc38804b Mon Sep 17 00:00:00 2001 From: niftynei Date: Fri, 13 Aug 2021 18:27:25 -0500 Subject: [PATCH 13/36] fixup: add P2TR (pay to taproot) to acceptable address list Suggested-By: @t-bast --- 02-peer-protocol.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index af6ac5b0a..f139f8816 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -267,7 +267,7 @@ The sending node: The receiving node: - MUST add the specified output to the transaction - - MUST accept P2SH, P2WSH, P2WPKH, P2PKH `script`s + - MUST accept P2SH, P2WSH, P2WPKH, P2PKH, P2TR `script`s - MAY fail the negotiation if `script` is non-standard - MUST fail the negotiation if: - the `serial_id` is already included in the transaction From c2d1a9b3b2bd6452de9dba40b821b04e5f213007 Mon Sep 17 00:00:00 2001 From: niftynei Date: Mon, 16 Aug 2021 11:45:38 -0500 Subject: [PATCH 14/36] fixup: move mention of failing the channel to implementation section "Failing the channel" may not be the right action in all cases where the interactive construction protocol is used (e.g. closes), so we move reference to it as a mitigation technique specifically to the usage of the interactive protocol in the v2 open sequence. Suggested-By: @t-bast --- 02-peer-protocol.md | 11 ++--------- 1 file changed, 2 insertions(+), 9 deletions(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index f139f8816..315d54674 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -397,9 +397,6 @@ The receiving node: - the number of `witness_stack`s does not equal the number of inputs added by the sending node - the `txid` does not match the txid of the transaction - - MUST fail the channel if: - - the `witness_stack` weight lowers the effective `feerate` - below the agreed upon transaction `feerate` - SHOULD apply the `witness`es to the transaction and broadcast it - MUST reply with their `tx_signatures` if not already transmitted @@ -419,9 +416,6 @@ While the `minimum fee` is calculated and verified at `tx_complete` conclusion, it is possible for the fee for the exchanged witness data to be underpaid. It is the responsibility of the sending peer to correctly account for the required fee, e.g. a multisig witness stack whose weight exceeds 110. -If the fees paid by the peer (inputs - outputs) does not meet or exceed -the pre-established `feerate`, the receiving peer SHOULD immediately -fail the channel by broadcasting their commitment transaction. ## Channel Establishment v1 @@ -1074,9 +1068,8 @@ The sending node: - MUST NOT send a `tx_signatures` message The receiving node: - - if the received `witness_stack` weight results in the peer's - paid feerate falling below the *opener*'s feerate for the funding - transaction: + - the `witness_stack` weight lowers the effective `feerate` + below the the *opener*'s feerate for the funding transaction: - SHOULD broadcast their commitment transaction, closing the channel. - SHOULD apply `witness`es to the funding transaction and broadcast it - if has already sent or received a `funding_locked` message for this From aedaa3acba0b269746de7d9e833c68e607e6ffeb Mon Sep 17 00:00:00 2001 From: niftynei Date: Mon, 16 Aug 2021 11:51:30 -0500 Subject: [PATCH 15/36] fixup: use "tx_remove_*" in all places, not "tx_rm_" Suggested-By: @t-bast --- 02-peer-protocol.md | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index 315d54674..3784855e5 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -125,7 +125,7 @@ the peer who contributed that input or output via `tx_add_input` or The *initiator* initiates the interactive transaction construction protocol with `tx_add_input`. The *non-initiator* responds with any -of `tx_add_input`, `tx_add_output`, `tx_rm_input`, `tx_rm_output`, or +of `tx_add_input`, `tx_add_output`, `tx_remove_input`, `tx_remove_output`, or `tx_complete`. The protocol continues with the synchronous exchange of interactive transaction protocol messages until both nodes have sent and received a consecutive `tx_complete`. @@ -169,18 +169,18 @@ but waits until A adds a second input before contributing. Note that if A does not send a second input, the negotiation will end without B's contributions. - +-------+ +-------+ - | |--(1)- tx_add_input -->| | - | |<-(2)- tx_complete ----| | - | |--(3)- tx_add_output ->| | - | |<-(4)- tx_complete ----| | - | |--(5)- tx_add_input -->| | - | A |<-(6)- tx_add_input ---| B | - | |<-(7)- tx_add_output --| | - | |--(8)- tx_rm_output -->| | - | |<-(9)- tx_complete ----| | - | |--(10) tx_complete --->| | - +-------+ +-------+ + +-------+ +-------+ + | |--(1)- tx_add_input ---->| | + | |<-(2)- tx_complete ------| | + | |--(3)- tx_add_output --->| | + | |<-(4)- tx_complete ------| | + | |--(5)- tx_add_input ---->| | + | A |<-(6)- tx_add_input -----| B | + | |<-(7)- tx_add_output ----| | + | |--(8)- tx_remove_output >| | + | |<-(9)- tx_complete ------| | + | |--(10) tx_complete ----->| | + +-------+ +-------+ ### The `tx_add_input` Message From 9d33274c1e079f3ea7b6d40797fa248851b1177a Mon Sep 17 00:00:00 2001 From: niftynei Date: Mon, 16 Aug 2021 18:07:29 -0500 Subject: [PATCH 16/36] fixup: explicitly note that interactive protocol is turn based --- 02-peer-protocol.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index 3784855e5..5c931d9ec 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -128,7 +128,7 @@ protocol with `tx_add_input`. The *non-initiator* responds with any of `tx_add_input`, `tx_add_output`, `tx_remove_input`, `tx_remove_output`, or `tx_complete`. The protocol continues with the synchronous exchange of interactive transaction protocol messages until both nodes have sent -and received a consecutive `tx_complete`. +and received a consecutive `tx_complete`. This is a turn-based protocol. Once peers have exchanged consecutive `tx_complete`s, the interactive transaction construction protocol is considered concluded. From 3ad9552d735c01810cf4fd062ec129e6cbdcbb4e Mon Sep 17 00:00:00 2001 From: niftynei Date: Mon, 16 Aug 2021 18:11:20 -0500 Subject: [PATCH 17/36] fixup: remove temp_chan_id reference, rename channel_id to zerod_chan_id For open_channel2 + accept_channel2 we use the opener's basepoint and a zeroed out point for the accepter. This is because we don't know what the accepter's basepoint is yet. (It's transmitted in accept_channel2) Pointed-Out-By: @t-bast --- 02-peer-protocol.md | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index 5c931d9ec..62a0fd7f0 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -860,7 +860,7 @@ This message initiates the v2 channel establishment workflow. 1. type: 64 (`open_channel2`) 2. data: * [`chain_hash`:`chain_hash`] - * [`channel_id`:`channel_id`] + * [`channel_id`:`zerod_channel_id`] * [`u32`:`funding_feerate_perkw`] * [`u32`:`commitment_feerate_perkw`] * [`u64`:`funding_satoshis`] @@ -898,8 +898,6 @@ If nodes have negotiated `option_dual_fund`: The sending node: - MUST set `funding_feerate_perkw` to the feerate for this transaction - - MUST ensure `temporary_channel_id` is unique from any - other channel ID with the same peer. The receiving node: - MAY fail the negotiation if: @@ -907,7 +905,7 @@ The receiving node: - the `funding_feerate_per_kw` is unacceptable #### Rationale -`channel_id` for the `open_channel2` MUST be derived using a zero-d out +`zerod_channel_id` for the `open_channel2` MUST be derived using a zero-d out basepoint for the peer's revocation basepoint. This allows the peer to return channel-assignable errors before the *accepter*'s revocation basepoint is known. @@ -938,7 +936,7 @@ acceptance of the new channel. 1. type: 65 (`accept_channel2`) 2. data: - * [`channel_id`:`channel_id`] + * [`channel_id`:`zerod_channel_id`] * [`u64`:`funding_satoshis`] * [`u64`:`dust_limit_satoshis`] * [`u64`:`max_htlc_value_in_flight_msat`] @@ -982,7 +980,7 @@ Instead, the channel reserve is fixed at 1% of the total channel balance rounded down to the nearest whole satoshi or the `dust_limit_satoshis`, whichever is greater. -`channel_id` for the `accept_channel2` MUST be derived using a zero-d out +`zerod_channel_id` for the `accept_channel2` MUST be derived using a zero-d out basepoint for the peer's revocation basepoint. This allows the peer to return channel-assignable errors before the *accepter*'s revocation basepoint is known. From 996cdf842c1b312c91235acdbc617af3788f7f5b Mon Sep 17 00:00:00 2001 From: niftynei Date: Mon, 16 Aug 2021 18:16:23 -0500 Subject: [PATCH 18/36] fixup: add 'it' --- 02-peer-protocol.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index 62a0fd7f0..ba1ee58fa 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -1017,7 +1017,7 @@ Upon receipt of consecutive `tx_complete`s, the receiving node: `open_channel2`.`funding_satoshis` and `accept_channel2`. `funding_satoshis` - the value of the funding output is less than the `dust_limit` - - if is an RBF attempt: + - if it is an RBF attempt: - MUST fail the negotiation if: - the transaction's total fees is less than the last successfully negotiated transaction's fees From 8595a9703b1a5d023d84f4d6d1e3e656b117e3dd Mon Sep 17 00:00:00 2001 From: niftynei Date: Mon, 16 Aug 2021 18:45:46 -0500 Subject: [PATCH 19/36] fixup: remove 'error' language Suggested-By: @t-bast --- 02-peer-protocol.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index ba1ee58fa..7c873d422 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -1104,7 +1104,7 @@ The sender: - MUST NOT have sent or received a `funding_locked` message. The recipient: - - MUST respond with either an error or an `ack_rbf` message. + - MUST respond either by failing the negotiation or with an `ack_rbf` message. - MUST fail the negotiation if: - the `funding_feerate_perkw` is not greater than 65/64 times `funding_feerate_perkw` of the last successfully negotiated From 4670bec468723337d8f081451ca61194d411ec93 Mon Sep 17 00:00:00 2001 From: niftynei Date: Mon, 31 Jan 2022 14:46:19 -0600 Subject: [PATCH 20/36] fixup: MAX_MONEY is 21million bitcoins, not satoshis Noticed-By: @SomberNight --- 02-peer-protocol.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index 7c873d422..2907d96dd 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -274,7 +274,7 @@ The receiving node: - the `serial_id` has the wrong parity - it has received 4096 `tx_add_output` messages during this negotiation - the `sats` amount is less than the `dust_limit` - - the `sats` amount is greater than 21,0000,0000 (`MAX_MONEY`) + - the `sats` amount is greater than 210,0000,000,000,000(`MAX_MONEY`) #### Rationale From f2d4c89c315a51b98ba035150b7affc053ecd369 Mon Sep 17 00:00:00 2001 From: niftynei Date: Mon, 31 Jan 2022 14:50:35 -0600 Subject: [PATCH 21/36] fixup: show turn based protocol in diagrams Reported-by: @SomberNight --- 02-peer-protocol.md | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index 2907d96dd..9b41eeac3 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -155,9 +155,8 @@ B, the *non-initiator* has nothing to contribute. | |--(3)- tx_add_input -->| | | A |<-(4)- tx_complete ----| B | | |--(5)- tx_add_output ->| | - | | | | - | |--(6)- tx_complete --->| | - | |<-(7)- tx_complete ----| | + | |<-(6)- tx_complete ----| | + | |--(7)- tx_complete --->| | +-------+ +-------+ #### *initiator* and *non-initiator* @@ -176,10 +175,10 @@ B's contributions. | |<-(4)- tx_complete ------| | | |--(5)- tx_add_input ---->| | | A |<-(6)- tx_add_input -----| B | - | |<-(7)- tx_add_output ----| | - | |--(8)- tx_remove_output >| | - | |<-(9)- tx_complete ------| | - | |--(10) tx_complete ----->| | + | |--(7)- tx_remove_output >| | + | |<-(8)- tx_add_output ----| | + | |--(9)- tx_complete ----->| | + | |<-(10) tx_complete ------| | +-------+ +-------+ From e582d832483f906f142ffb31c4cab7883c50d7f0 Mon Sep 17 00:00:00 2001 From: niftynei Date: Mon, 31 Jan 2022 14:52:41 -0600 Subject: [PATCH 22/36] fixup: use BIP141 text to describe witness version scripts Suggested-by: @instagibbs --- 02-peer-protocol.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index 9b41eeac3..e20ee603b 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -216,7 +216,7 @@ The receiving node: (and not removed) input's - `prevtx` is not a valid transaction - `prevtx_vout` is greater or equal to the number of outputs on `prevtx` - - the `scriptPubKey` of the `prevtx_out` output of `prevtx` does not begin with `OP_0` to `OP_16` + - the `scriptPubKey` of the `prevtx_out` output of `prevtx` is not exactly a 1-byte push opcode (for the numeric values 0 to 16) followed by a data push between 2 and 40 bytes followed by a single push of 2 to 40 bytes - the `serial_id` is already included in the transaction - the `serial_id` has the wrong parity From 96880f6a27d95f7e8694affad2903c6650098680 Mon Sep 17 00:00:00 2001 From: niftynei Date: Mon, 31 Jan 2022 14:59:42 -0600 Subject: [PATCH 23/36] fixup: add switch stmt for P2SH-wrapped segwit input verification P2SH-wrapped inputs are segwit inputs and should be eligible for spending, however the spec as written didn't permit them Reported-by: @SomberNight --- 02-peer-protocol.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index e20ee603b..7908684a3 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -216,7 +216,10 @@ The receiving node: (and not removed) input's - `prevtx` is not a valid transaction - `prevtx_vout` is greater or equal to the number of outputs on `prevtx` - - the `scriptPubKey` of the `prevtx_out` output of `prevtx` is not exactly a 1-byte push opcode (for the numeric values 0 to 16) followed by a data push between 2 and 40 bytes + - if the `script_sig` is provided: + - and it is not exactly a 1-byte push opcode (for the numeric values `0` to `16`) followed by a data push between 2 and 40 bytes OR + - else: + - the `scriptPubKey` of the `prevtx_out` output of `prevtx` is not exactly a 1-byte push opcode (for the numeric values 0 to 16) followed by a data push between 2 and 40 bytes followed by a single push of 2 to 40 bytes - the `serial_id` is already included in the transaction - the `serial_id` has the wrong parity From 9346349235c4da48020c0f692d90e002ab733f2e Mon Sep 17 00:00:00 2001 From: niftynei Date: Mon, 31 Jan 2022 15:13:01 -0600 Subject: [PATCH 24/36] fixup: disallow P2SH scripts in outputs P2SH outputs have larger dust requirements than native SegWit (and Taproot) scripts; we disallow the creation of them on funding txs as a they're problematic for relay when allowing dust limits below 546 sats (see #894) Suggested-by: @t-bast --- 02-peer-protocol.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index 7908684a3..22d787d8a 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -269,7 +269,7 @@ The sending node: The receiving node: - MUST add the specified output to the transaction - - MUST accept P2SH, P2WSH, P2WPKH, P2PKH, P2TR `script`s + - MUST accept P2WSH, P2WPKH, P2PKH, P2TR `script`s - MAY fail the negotiation if `script` is non-standard - MUST fail the negotiation if: - the `serial_id` is already included in the transaction From d7713deaaa5d2e07da72f79b889cce38eac6e787 Mon Sep 17 00:00:00 2001 From: niftynei Date: Mon, 31 Jan 2022 15:32:09 -0600 Subject: [PATCH 25/36] df: v2 opens use a temp channel id until accept_channel2 is exchanged --- 01-messaging.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/01-messaging.md b/01-messaging.md index 549b7016c..814a8bdbc 100644 --- a/01-messaging.md +++ b/01-messaging.md @@ -324,6 +324,14 @@ The fundee node using channel establishment v1 (`accept_channel`): - for all error messages sent before (and not including) the `funding_signed` message: - MUST use `temporary_channel_id` in lieu of `channel_id`. +The opener node using channel establishment v2 `open_channel2`: + - for all error messages sent before the `accept_channel2` message is received: + - MUST use `temporary_channel_id` in lieu of `channel_id`. + +The accepter node using channel establishment v2 `open_channel2`: + - for all error messages sent before (and including) the `accept_channel2` message: + - MUST use `temporary_channel_id` in lieu of `channel_id`. + A sending node: - when sending `error`: - MUST fail the channel referred to by the error message. From 17bd7ac0e1fa480063b0d0cac4c28fe692d7d0fb Mon Sep 17 00:00:00 2001 From: niftynei Date: Mon, 31 Jan 2022 15:32:44 -0600 Subject: [PATCH 26/36] v2 opens: add a `tx_abort` message Requested-by: @t-bast --- 02-peer-protocol.md | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index 22d787d8a..be99bfbb8 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -16,6 +16,7 @@ operation, and closing. * [The `tx_remove_input` and `tx_remote_output` Messages](#the-tx_remove_input-and-tx_remove_output-messages) * [The `tx_complete` Message](#the-tx_complete-message) * [The `tx_signatures` Message](#the-tx_signatures-message) + * [The `tx_abort` Message](#the-tx_abort-message) * [Channel Establishment v1](#channel-establishment-v1) * [The `open_channel` Message](#the-open_channel-message) * [The `accept_channel` Message](#the-accept_channel-message) @@ -419,6 +420,41 @@ it is possible for the fee for the exchanged witness data to be underpaid. It is the responsibility of the sending peer to correctly account for the required fee, e.g. a multisig witness stack whose weight exceeds 110. + +### The `tx_abort` Message + +1. type: 74 (`tx_abort`) +2. data: + * [`channel_id`:`channel_id`] + * [`u16`:`len`] + * [`len*byte`:`data`] + +The 2-byte `len` field indicates the number of bytes in the immediately following field. + +#### Requirements + +A sending node: + - MUST NOT have already transmitted `tx_signatures` + - SHOULD forget the current negotiation and reset their state. + +A receiving node: + - if they have already sent `tx_signatures` to the peer: + - MUST NOT forget the channel until any inputs to the negotiated tx + have been spent. + - if they have not sent `tx_signatures`: + - SHOULD forget the current negotiation and reset their state. + +#### Rationale + +A recieving node, if they've already sent their `tx_signatures` has no guarantee +that the transaction won't be signed and published by their peer. They must remember +the transaction and channel (if appropriate) until the transaction is no longer +eligible to be spent (i.e. any input has been spent in a different transaction). + +The `tx_abort` message allows for the cancelation of an in progress negotation, +and a return to the initial starting state. + + ## Channel Establishment v1 After authenticating and initializing a connection ([BOLT #8](08-transport.md) From 22de9efe197f73d6b02f846756959dd9f46cb4c5 Mon Sep 17 00:00:00 2001 From: niftynei Date: Thu, 10 Feb 2022 13:05:13 -0600 Subject: [PATCH 27/36] fixup: mistake, should be 110 input_count of 1 times min witness weight of 110, is 110. not 107 the sum of 612 is correct, however. Reported-By: @SimonVrouwe --- 03-transactions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/03-transactions.md b/03-transactions.md index 64d6966bb..06e74b70b 100644 --- a/03-transactions.md +++ b/03-transactions.md @@ -787,7 +787,7 @@ calculated as follows. Note that the feerate is rounded down to the nearest sat + 41 * 4 + 43 * 4 + 31 * 4 - + 107 + + 110 initiator_weight = 612 From adb62720efa15b0e15ffb1e9c9d4ffa1c8836712 Mon Sep 17 00:00:00 2001 From: t-bast Date: Tue, 26 Apr 2022 09:22:25 +0200 Subject: [PATCH 28/36] Dual funding proposed updates * Move RBF inside the interactive-tx protocol * Use same tlvs as open_channel / accept_channel * Require native segwit * Fix a few typos and whitespaces issues (thanks markdown linter) --- 02-peer-protocol.md | 239 ++++++++++++++++++++++++-------------------- 09-features.md | 2 +- 2 files changed, 129 insertions(+), 112 deletions(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index be99bfbb8..c1c31c150 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -29,8 +29,8 @@ operation, and closing. * [Funding Composition](#funding-composition) * [The `commitment_signed` Message](#the-commitment_signed-message) * [Sharing funding signatures: `tx_signatures`](#sharing-funding-signatures-tx_signatures) - * [The `init_rbf` Message](#the-init_rbf-message) - * [The `ack_rbf` Message](#the-ack_rbf-message) + * [The `tx_init_rbf` Message](#the-tx_init_rbf-message) + * [The `tx_ack_rbf` Message](#the-tx_ack_rbf-message) * [Channel Close](#channel-close) * [Closing Initiation: `shutdown`](#closing-initiation-shutdown) * [Closing Negotiation: `closing_signed`](#closing-negotiation-closing_signed) @@ -67,7 +67,6 @@ transaction is confirmed are also not persistent - until you know the script pubkey corresponding to the funding output nothing prevents duplicative channel ids. - ### `channel_id`, v2 For channels established using the v2 protocol, the `channel_id` is the @@ -79,12 +78,12 @@ and `accept_channel2`), a temporary `channel_id` should be found by using a zeroed out basepoint for the unknown peer. #### Rationale + These values must be remembered by both peers for correct operation anyway. They're known from the first exchange of messages, obviating the need for a `temporary_channel_id`. Finally, by mixing information from both sides, they avoid `channel_id` collisions. - ## Interactive Transaction Construction Interactive transaction construction allows two peers to collaboratively @@ -95,7 +94,7 @@ for dual-funded channels establishment (v2). There are two parties to a transaction construction: an *initiator* and a *non-initiator*. - The *initiator* is the peer which initiates the protocol, e.g. +The *initiator* is the peer which initiates the protocol, e.g. for channel establishment v2 the *initiator* would be the peer which sends `open_channel2`; for a close, the *initiator* sends `shutdown`. @@ -121,13 +120,12 @@ The rest of the transaction bytes' fees are the responsibility of the peer who contributed that input or output via `tx_add_input` or `tx_add_output`, at the agreed upon `feerate`. - ### Overview The *initiator* initiates the interactive transaction construction protocol with `tx_add_input`. The *non-initiator* responds with any of `tx_add_input`, `tx_add_output`, `tx_remove_input`, `tx_remove_output`, or - `tx_complete`. The protocol continues with the synchronous exchange +`tx_complete`. The protocol continues with the synchronous exchange of interactive transaction protocol messages until both nodes have sent and received a consecutive `tx_complete`. This is a turn-based protocol. @@ -182,7 +180,6 @@ B's contributions. | |<-(10) tx_complete ------| | +-------+ +-------+ - ### The `tx_add_input` Message This message contains a transaction input. @@ -195,8 +192,6 @@ This message contains a transaction input. * [`prevtx_len*byte`:`prevtx`] * [`u32`:`prevtx_vout`] * [`u32`:`sequence`] - * [`u16`:`script_sig_len`] - * [`script_sig_len*byte`:`script_sig`] #### Requirements @@ -217,16 +212,13 @@ The receiving node: (and not removed) input's - `prevtx` is not a valid transaction - `prevtx_vout` is greater or equal to the number of outputs on `prevtx` - - if the `script_sig` is provided: - - and it is not exactly a 1-byte push opcode (for the numeric values `0` to `16`) followed by a data push between 2 and 40 bytes OR - - else: - - the `scriptPubKey` of the `prevtx_out` output of `prevtx` is not exactly a 1-byte push opcode (for the numeric values 0 to 16) followed by a data push between 2 and 40 bytes - followed by a single push of 2 to 40 bytes + - the `scriptPubKey` of the `prevtx_vout` output of `prevtx` is not exactly a 1-byte push opcode (for the numeric values `0` to `16`) followed by a data push between 2 and 40 bytes - the `serial_id` is already included in the transaction - the `serial_id` has the wrong parity - if has received 4096 `tx_add_input` messages during this negotiation #### Rationale + Each node must know the set of the transaction inputs. The *non-initiator* MAY omit this message. @@ -241,9 +233,6 @@ this input spends. Used to verify that the input is non-malleable. `sequence` is the sequence number of this input. Must be less than 4294967294 (0xFFFFFFFE). See BIP125. -`script_sig` is the scriptSig for the input, with length omitted. -The `script_sig` for non-P2SH-wrapped inputs will be an empty byte array. - ### The `tx_add_output` Message This message adds a transaction output. @@ -270,17 +259,17 @@ The sending node: The receiving node: - MUST add the specified output to the transaction - - MUST accept P2WSH, P2WPKH, P2PKH, P2TR `script`s + - MUST accept P2WSH, P2WPKH, P2TR `script`s - MAY fail the negotiation if `script` is non-standard - MUST fail the negotiation if: - the `serial_id` is already included in the transaction - the `serial_id` has the wrong parity - it has received 4096 `tx_add_output` messages during this negotiation - the `sats` amount is less than the `dust_limit` - - the `sats` amount is greater than 210,0000,000,000,000(`MAX_MONEY`) - + - the `sats` amount is greater than 2,100,000,000,000,000 (`MAX_MONEY`) #### Rationale + Each node must know the set of the transaction outputs. `serial_id` is a randomly chosen number which uniquely identifies this output. @@ -288,13 +277,13 @@ Outputs in the constructed transaction are sorted by `serial_id`. `sats` is the satoshi value of the output. -`script` is the scriptPubKey for the output. The length is omitted. +`script` is the scriptPubKey for the output (with its length omitted). It's left undefined if you accept other standard outputs such as `OP_RETURN` or implement stricter checks on standardness. - ### The `tx_remove_input` and `tx_remove_output` Messages -These message removes an input from the transaction. + +This message removes an input from the transaction. 1. type: 68 (`tx_remove_input`) 2. data: @@ -321,7 +310,6 @@ The receiving node: sender - the `serial_id` does not correspond to a currently added input (or output) - ### The `tx_complete` Message This message signals the conclusion of a peer's transaction @@ -331,7 +319,6 @@ contributions. 2. data: * [`channel_id`:`channel_id`] - #### Requirements The nodes: @@ -350,6 +337,7 @@ The receiving node: - the estimated weight of the tx is greater than 400,000 (`MAX_STANDARD_TX_WEIGHT`) #### Rationale + To signal the conclusion of exchange of transaction inputs and outputs. Upon successful exchange of `tx_complete` messages, both nodes @@ -361,7 +349,6 @@ For the `minimum fee` calculation see [BOLT #3](03-transactions.md#calculating-f The maximum inputs and outputs are capped at 252. This effectively fixes the byte size of the input and output counts on the transaction to one (1). - ### The `tx_signatures` Message 1. type: 71 (`tx_signatures`) @@ -381,8 +368,8 @@ the byte size of the input and output counts on the transaction to one (1). * [`u16`:`len`] * [`len*byte`:`witness`] - #### Requirements + The sending node: - if it has the lowest total satoshis contributed, as defined by total `tx_add_input` values: @@ -403,8 +390,8 @@ The receiving node: - SHOULD apply the `witness`es to the transaction and broadcast it - MUST reply with their `tx_signatures` if not already transmitted - #### Rationale + The peer with the lowest total of inputs amounts must transmit its `tx_signatures` first. This gives in a strict ordering of transmission for any multiparty tx collaboration. @@ -420,6 +407,81 @@ it is possible for the fee for the exchanged witness data to be underpaid. It is the responsibility of the sending peer to correctly account for the required fee, e.g. a multisig witness stack whose weight exceeds 110. +### The `tx_init_rbf` Message + +This message initiates a replacement of the transaction after it's been +completed. + +1. type: 72 (`tx_init_rbf`) +2. data: + * [`channel_id`:`channel_id`] + * [`u32`:`locktime`] + * [`u32`:`feerate`] + +1. `tlv_stream`: `tx_init_rbf_tlvs` +2. types: + 1. type: 0 (`funding_output_contribution`) + 2. data: + * [`tu64`:`satoshis`] + +#### Requirements + +The sender: + - MUST set `feerate` greater than or equal to 65/64 times the `feerate` + of the previously constructed transaction, rounded down. + +The recipient: + - MUST respond either by failing the negotiation or with `tx_ack_rbf`. + - MUST fail the negotiation if: + - the `feerate` is not greater than 65/64 times `feerate` of the last + successfully constructed transaction + - MAY fail the negotiation for any reason + +#### Rationale + +`feerate` is the feerate this transaction will pay. It must be at least +1/64 greater than the last used `feerate`, rounded down to the nearest +satoshi to ensure there is progress. + +E.g. if the last `feerate` was 520, the next sent `feerate` must be 528 +(520 * 65 / 64 = 528.125, rounded down to 528). + +If the previous transaction confirms in the middle of an RBF attempt, +the attempt MUST be abandoned. + +`funding_output_contribution` is the amount of satoshis that this peer +will contribute to the funding output of the transaction, when there is +such an output. Note that it may be different from the contribution +made in the previously completed transaction. + +### The `tx_ack_rbf` Message + +1. type: 73 (`tx_ack_rbf`) +2. data: + * [`channel_id`:`channel_id`] + +1. `tlv_stream`: `tx_ack_rbf_tlvs` +2. types: + 1. type: 0 (`funding_output_contribution`) + 2. data: + * [`tu64`:`satoshis`] + +#### Requirements + +The recipient: + - MUST either fail the negotiation or transmit a `tx_add_input` message, + restarting the interactive tx collaboration protocol. + +#### Rationale + +`funding_output_contribution` is the amount of satoshis that this peer +will contribute to the funding output of the transaction, when there is +such an output. Note that it may be different from the contribution +made in the previously completed transaction. + +It's recommended that a peer, rather than fail the RBF negotiation due to +a large feerate change, instead sets their `funding_output_contribution` to +zero, and decline to participate further in the transaction. ### The `tx_abort` Message @@ -429,7 +491,7 @@ required fee, e.g. a multisig witness stack whose weight exceeds 110. * [`u16`:`len`] * [`len*byte`:`data`] -The 2-byte `len` field indicates the number of bytes in the immediately following field. +The `len` field indicates the number of bytes in the immediately following field. #### Requirements @@ -446,15 +508,14 @@ A receiving node: #### Rationale -A recieving node, if they've already sent their `tx_signatures` has no guarantee +A receiving node, if they've already sent their `tx_signatures` has no guarantee that the transaction won't be signed and published by their peer. They must remember the transaction and channel (if appropriate) until the transaction is no longer eligible to be spent (i.e. any input has been spent in a different transaction). -The `tx_abort` message allows for the cancelation of an in progress negotation, +The `tx_abort` message allows for the cancelation of an in progress negotiation, and a return to the initial starting state. - ## Channel Establishment v1 After authenticating and initializing a connection ([BOLT #8](08-transport.md) @@ -867,8 +928,6 @@ It changes the previous protocol to allow the `accept_channel2` peer (the *accepter*/*non-initiator*) to contribute inputs to the funding transaction, via the interactive transaction construction protocol. -The protocol is also expanded to include a mechanism for initiating RBF. - +-------+ +-------+ | |--(1)--- open_channel2 ----->| | | |<-(2)--- accept_channel2 -----| | @@ -881,8 +940,8 @@ The protocol is also expanded to include a mechanism for initiating RBF. | | |<-(5)-- tx_signatures -------| | | | |--(6)-- tx_signatures ------>| | | | | | | - | | |--(a)--- init_rbf ----------->| | - ----| |<-(b)--- ack_rbf ------------| | + | | |--(a)--- tx_init_rbf -------->| | + ----| |<-(b)--- tx_ack_rbf ----------| | | | | | | |--(7)--- funding_locked ----->| | | |<-(8)--- funding_locked ------| | @@ -917,18 +976,16 @@ This message initiates the v2 channel establishment workflow. * [`byte`:`channel_flags`] * [`opening_tlvs`:`tlvs`] - 1. `tlv_stream`: `opening_tlvs` 2. types: - 1. type: 1 (`option_upfront_shutdown_script`) + 1. type: 0 (`upfront_shutdown_script`) 2. data: - * [`u16`:`shutdown_len`] - * [`shutdown_len*byte`:`shutdown_scriptpubkey`] + * [`...*byte`:`shutdown_scriptpubkey`] +Rationale and Requirements are the same as for [`open_channel`](#the-open_channel-message), +with the following additions. -Rationale and Requirements are the same as for [`open_channel`](#the-open_channel-message), with the following additions: - -#### Requirements: +#### Requirements If nodes have negotiated `option_dual_fund`: - the opening node: @@ -943,6 +1000,7 @@ The receiving node: - the `funding_feerate_per_kw` is unacceptable #### Rationale + `zerod_channel_id` for the `open_channel2` MUST be derived using a zero-d out basepoint for the peer's revocation basepoint. This allows the peer to return channel-assignable errors before the *accepter*'s revocation @@ -992,17 +1050,15 @@ acceptance of the new channel. 1. `tlv_stream`: `accept_tlvs` 2. types: - 1. type: 1 (`option_upfront_shutdown_script`) + 1. type: 0 (`upfront_shutdown_script`) 2. data: - * [`u16`:`shutdown_len`] - * [`shutdown_len*byte`:`shutdown_scriptpubkey`] - + * [`...*byte`:`shutdown_scriptpubkey`] Rationale and Requirements are the same as listed above, for [`accept_channel`](#the-accept_channel-message) with the following additions. -#### Requirements: +#### Requirements The accepting node: - MAY respond with a `funding_satoshis` value of zero. @@ -1024,26 +1080,27 @@ return channel-assignable errors before the *accepter*'s revocation basepoint is known. ### Funding Composition + Funding composition for channel establishment v2 makes use of the [Interactive Transaction Construction](#interactive-transaction-construction) protocol, with the following additional caveats. - #### The `tx_add_input` Message No additional caveats or requirements. - #### The `tx_add_output` Message + ##### Requirements + The sending node: - if is the *opener*: - MUST send at least one `tx_add_output`, which contains the channel's funding output ##### Rationale -The channel funding output must be added by the *opener*, who pays its fees. +The channel funding output must be added by the *opener*, who pays its fees. #### The `tx_complete` Message @@ -1073,10 +1130,10 @@ for [`commitment_signed`](#commiting-updates-so-far-commitment_signed) with the #### Requirements The sending node: - - MUST send zero HTLC's. + - MUST send zero HTLCs. The receiving node: - - if the message has one or more HTLC's: + - if the message has one or more HTLCs: - MUST fail the negotiation - if it has not already transmitted its `commitment_signed`: - MUST send `commitment_signed` @@ -1085,8 +1142,7 @@ The receiving node: #### Rationale -The first commitment transaction has no HTLC's. - +The first commitment transaction has no HTLCs. ### Sharing funding signatures: `tx_signatures` @@ -1095,8 +1151,8 @@ from the peer and a `commitment_signature` has been sent, a peer: - MUST transmit a [`tx_signatures` message](#the-tx_signatures-message) with their signatures for the funding transaction - #### Requirements + The sending node: - MUST verify it has received a valid commitment signature from its peer - MUST remember the details of this funding transaction @@ -1113,83 +1169,44 @@ The receiving node: - MUST ignore this message #### Rationale + A peer sends their `tx_signatures` as soon as they have received a valid -`commitments_signed` message. +`commitment_signed` message. The channel should be preemptively closed in the case where a peer provides valid witness data that causes their paid feerate to fall beneath the `open_channel2.funding_feerate_perkw` rate. This penalizes the peer for underpayment of fees. +### Fee bumping: `tx_init_rbf` and `tx_ack_rbf` -### The `init_rbf` Message - -This message initiates a replacement of a broadcast funding transaction. - -1. type: 72 (`init_rbf`) -2. data: - * [`channel_id`:`channel_id`] - * [`u64`:`funding_satoshis`] - * [`u32`:`locktime`] - * [`u32`:`funding_feerate_perkw`] +After the funding transaction has been broadcast, it can be replaced by +a transaction paying more fees to make the channel confirm faster. #### Requirements -The sender: - - MUST have sent `open_channel2` - - MUST set `funding_feerate_perkw` greater than or equal to - 65/64 times the last sent `funding_feerate_perkw` rounded down. +The sender of `tx_init_rbf`: + - MUST be the *initiator* - MUST NOT have sent or received a `funding_locked` message. The recipient: - - MUST respond either by failing the negotiation or with an `ack_rbf` message. - - MUST fail the negotiation if: - - the `funding_feerate_perkw` is not greater than 65/64 times - `funding_feerate_perkw` of the last successfully negotiated - open attempt - - they have already sent or received `funding_locked` + - MUST fail the negotiation if they have already sent or received + `funding_locked` - MAY fail the negotiation for any reason #### Rationale -`funding_feerate_perkw` is the feerate this funding transaction -will pay. It must be at least 1/64 greater than the last -received `funding_feerate_perkw`, rounded down to the nearest -satoshi. - -E.g. if the last `feerate_per_kw_funding` was 520 -the next sent `feerate_per_kw_funding` must be 528 -(520 * 65 / 64 = 528.125, rounded down to 528). If a valid `funding_locked` message is received in the middle of an RBF attempt, the attempt MUST be abandoned. -### The `ack_rbf` Message - -1. type: 73 (`ack_rbf`) -2. data: - * [`channel_id`:`channel_id`] - * [`u64`:`funding_satoshis`] - -#### Requirements - -The sender: - - MUST NOT have sent or received a `funding_locked` message - -The recipient: - - MUST either fail the negotiation or transmit a `tx_add_input` message, - restarting the interactive tx collaboration protocol, and proceeding - the same as with `accept_channel2`. - -#### Rationale -`funding_satoshis` is the amount of satoshis that this peer will -contribute to the funding output. Note that this may be different than -the amount transmitted in either `accept_channel2`.`funding_satoshis` or -any previous `ack_rbf`.`funding_satoshis`, as the amount the *accepter* -wishes to commit to the funding output may change. +Peers can use different values in `tx_init_rbf.funding_output_contribution` +and `tx_ack_rbf.funding_output_contribution` from the amounts transmitted +in `open_channel2` and `accept_channel2`: they are allowed to change how +much they wish to commit to the funding output. It's recommended that a peer, rather than fail the RBF negotiation due to -a large feerate change, instead sets their `funding_satoshis` to zero, -and decline to participate further in the channel funding. +a large feerate change, instead sets their `sats` to zero, and decline to +participate further in the channel funding. ## Channel Close diff --git a/09-features.md b/09-features.md index 82790fe5a..ff852e2fd 100644 --- a/09-features.md +++ b/09-features.md @@ -41,7 +41,7 @@ The Context column decodes as follows: | 20/21 | `option_anchor_outputs` | Anchor outputs | IN | `option_static_remotekey` | [BOLT #3](03-transactions.md) | | 22/23 | `option_anchors_zero_fee_htlc_tx` | Anchor commitment type with zero fee HTLC transactions | IN | | [BOLT #3][bolt03-htlc-tx], [lightning-dev][ml-sighash-single-harmful]| | 26/27 | `option_shutdown_anysegwit` | Future segwit versions allowed in `shutdown` | IN | | [BOLT #2][bolt02-shutdown] | -| 28/29 | `option_dual_fund` | Use v2 of channel open, enables dual funding | IN | `option_anchor_outputs`, `option_static_remotekey` | [BOLT #2](02-peer-protocol.md) | +| 28/29 | `option_dual_fund` | Use v2 of channel open, enables dual funding | IN | `option_anchors_zero_fee_htlc_tx` | [BOLT #2](02-peer-protocol.md) | ## Requirements From 53b740e2b33661971c7ccb31997c50fca966a0af Mon Sep 17 00:00:00 2001 From: t-bast Date: Mon, 2 May 2022 16:41:24 +0200 Subject: [PATCH 29/36] Fix table of contents --- 02-peer-protocol.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index c1c31c150..ed1cc6da1 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -16,6 +16,8 @@ operation, and closing. * [The `tx_remove_input` and `tx_remote_output` Messages](#the-tx_remove_input-and-tx_remove_output-messages) * [The `tx_complete` Message](#the-tx_complete-message) * [The `tx_signatures` Message](#the-tx_signatures-message) + * [The `tx_init_rbf` Message](#the-tx_init_rbf-message) + * [The `tx_ack_rbf` Message](#the-tx_ack_rbf-message) * [The `tx_abort` Message](#the-tx_abort-message) * [Channel Establishment v1](#channel-establishment-v1) * [The `open_channel` Message](#the-open_channel-message) @@ -29,8 +31,7 @@ operation, and closing. * [Funding Composition](#funding-composition) * [The `commitment_signed` Message](#the-commitment_signed-message) * [Sharing funding signatures: `tx_signatures`](#sharing-funding-signatures-tx_signatures) - * [The `tx_init_rbf` Message](#the-tx_init_rbf-message) - * [The `tx_ack_rbf` Message](#the-tx_ack_rbf-message) + * [Fee bumping: `tx_init_rbf` and `tx_ack_rbf`](#fee-bumping-tx_init_rbf-and-tx_ack_rbf) * [Channel Close](#channel-close) * [Closing Initiation: `shutdown`](#closing-initiation-shutdown) * [Closing Negotiation: `closing_signed`](#closing-negotiation-closing_signed) From 1687397065252dcd6cc3b1a9a8462d52dc0fbab0 Mon Sep 17 00:00:00 2001 From: t-bast Date: Wed, 4 May 2022 11:26:58 +0200 Subject: [PATCH 30/36] Fix a few typos And add `channel_type` tlv. --- 02-peer-protocol.md | 18 ++++++++----- 03-transactions.md | 63 ++++++++++++++++++++++----------------------- 2 files changed, 43 insertions(+), 38 deletions(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index ed1cc6da1..d86b518ec 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -97,7 +97,7 @@ There are two parties to a transaction construction: an *initiator* and a *non-initiator*. The *initiator* is the peer which initiates the protocol, e.g. for channel establishment v2 the *initiator* would be the peer which -sends `open_channel2`; for a close, the *initiator* sends `shutdown`. +sends `open_channel2`. The protocol makes the following assumptions: @@ -511,10 +511,10 @@ A receiving node: A receiving node, if they've already sent their `tx_signatures` has no guarantee that the transaction won't be signed and published by their peer. They must remember -the transaction and channel (if appropriate) until the transaction is no longer +the transaction and channel (if appropriate) until the transaction is no longer eligible to be spent (i.e. any input has been spent in a different transaction). -The `tx_abort` message allows for the cancelation of an in progress negotiation, +The `tx_abort` message allows for the cancellation of an in progress negotiation, and a return to the initial starting state. ## Channel Establishment v1 @@ -982,6 +982,9 @@ This message initiates the v2 channel establishment workflow. 1. type: 0 (`upfront_shutdown_script`) 2. data: * [`...*byte`:`shutdown_scriptpubkey`] + 1. type: 1 (`channel_type`) + 2. data: + * [`...*byte`:`type`] Rationale and Requirements are the same as for [`open_channel`](#the-open_channel-message), with the following additions. @@ -998,7 +1001,7 @@ The sending node: The receiving node: - MAY fail the negotiation if: - the `locktime` is unacceptable - - the `funding_feerate_per_kw` is unacceptable + - the `funding_feerate_perkw` is unacceptable #### Rationale @@ -1054,6 +1057,9 @@ acceptance of the new channel. 1. type: 0 (`upfront_shutdown_script`) 2. data: * [`...*byte`:`shutdown_scriptpubkey`] + 1. type: 1 (`channel_type`) + 2. data: + * [`...*byte`:`type`] Rationale and Requirements are the same as listed above, for [`accept_channel`](#the-accept_channel-message) with the following @@ -1161,10 +1167,10 @@ The sending node: - MUST NOT send a `tx_signatures` message The receiving node: - - the `witness_stack` weight lowers the effective `feerate` + - if the `witness_stack` weight lowers the effective `feerate` below the the *opener*'s feerate for the funding transaction: - SHOULD broadcast their commitment transaction, closing the channel. - - SHOULD apply `witness`es to the funding transaction and broadcast it + - SHOULD apply `witnesses` to the funding transaction and broadcast it - if has already sent or received a `funding_locked` message for this channel: - MUST ignore this message diff --git a/03-transactions.md b/03-transactions.md index 06e74b70b..9928a817c 100644 --- a/03-transactions.md +++ b/03-transactions.md @@ -21,6 +21,7 @@ This details the exact format of on-chain transactions, which both sides need to * [Fees](#fees) * [Fee Calculation](#fee-calculation) * [Fee Payment](#fee-payment) + * [Calculating Fees for Collaborative Transactions](#calculating-fees-for-collaborative-transactions) * [Keys](#keys) * [Key Derivation](#key-derivation) * [`localpubkey`, `remotepubkey`, `local_htlcpubkey`, `remote_htlcpubkey`, `local_delayedpubkey`, and `remote_delayedpubkey` Derivation](#localpubkey-remotepubkey-local_htlcpubkey-remote_htlcpubkey-local_delayedpubkey-and-remote_delayedpubkey-derivation) @@ -28,6 +29,7 @@ This details the exact format of on-chain transactions, which both sides need to * [Per-commitment Secret Requirements](#per-commitment-secret-requirements) * [Efficient Per-commitment Secret Storage](#efficient-per-commitment-secret-storage) * [Appendix A: Expected Weights](#appendix-a-expected-weights) + * [Expected Weight of the Funding Transaction (v2 Channel Establishment)](#expected-weight-of-the-funding-transaction-(v2-channel-establishment)) * [Expected Weight of the Commitment Transaction](#expected-weight-of-the-commitment-transaction) * [Expected Weight of HTLC-timeout and HTLC-success Transactions](#expected-weight-of-htlc-timeout-and-htlc-success-transactions) * [Appendix B: Funding Transaction Test Vectors](#appendix-b-funding-transaction-test-vectors) @@ -37,7 +39,7 @@ This details the exact format of on-chain transactions, which both sides need to * [Storage Tests](#storage-tests) * [Appendix E: Key Derivation Test Vectors](#appendix-e-key-derivation-test-vectors) * [Appendix F: Commitment and HTLC Transaction Test Vectors (anchors)](#appendix-f-commitment-and-htlc-transaction-test-vectors-anchors) - * [Appendix G: Dual Funded Transaction Test Vectors](#appendix-f-dual-funded-transaction-test-vectors) + * [Appendix G: Dual Funded Transaction Test Vectors](#appendix-g-dual-funded-transaction-test-vectors) * [References](#references) * [Authors](#authors) @@ -478,14 +480,12 @@ A node: - if the resulting fee rate is too low: - MAY fail the channel. - ### Calculating Fees for Collaborative Transactions For transactions constructed using the [interactive protocol](02-peer-protocol.md#interactive-transaction-construction), fees are paid by each party to the transaction, at `feerate` determined during the initiation, with the initiator covering the fees for the common transaction fields. - ## Commitment Transaction Construction This section ties the previous sections together to detail the @@ -724,37 +724,37 @@ at each bucket is a prefix of the desired index. The *expected weight* of a funding transaction is calculated as follows: inputs: 40 bytes + var_int + `scriptlen` - - previous_out_point: 36 bytes - - hash: 32 bytes - - index: 4 bytes - - var_int: ? bytes (dependent on `scriptlen`) - - script_sig: `scriptlen` - - witness <---- Cost for "witness" data calculated separately. - - sequence: 4 bytes - - non_funding_outputs: 8 bytes + var_int + `scriptlen` - - value: 8 bytes - - var_int: ? bytes (dependent on `scriptlen`) - - script_sig: `scriptlen` - - funding_output: 43 bytes - - value: 8 bytes - - var_int: 1 byte - - script: 34 bytes - - OP_0: 1 byte - - PUSHDATA(32-byte-hash): 33 bytes + - previous_out_point: 36 bytes + - hash: 32 bytes + - index: 4 bytes + - var_int: ? bytes (dependent on `scriptlen`) + - script_sig: `scriptlen` + - witness <---- Cost for "witness" data calculated separately. + - sequence: 4 bytes + + non_funding_outputs: 8 bytes + var_int + `scriptlen` + - value: 8 bytes + - var_int: ? bytes (dependent on `scriptlen`) + - script: `scriptlen` + + funding_output: 43 bytes + - value: 8 bytes + - var_int: 1 byte + - script: 34 bytes + - OP_0: 1 byte + - PUSHDATA(32-byte-hash): 33 bytes Multiplying non-witness data by 4 results in a weight of: - // transaction_fields = 10 (version, input count, output count, locktime) - // segwit_fields = 2 (marker + flag) - // funding_transaction = 43 + num_inputs * 40 + num_outputs * 8 - // + sum(scriptlen) + sum(var_ints) + - funding_transaction_weight = 4 * (funding_transaction + transaction_fields) + segwit_fields + // transaction_fields = 10 (version, input count, output count, locktime) + // segwit_fields = 2 (marker + flag) + // funding_transaction = 43 + num_inputs * 40 + num_outputs * 8 + // + sum(scriptlen) + sum(var_ints) + + funding_transaction_weight = 4 * (funding_transaction + transaction_fields) + segwit_fields - witness_weight = sum(max_witness_len) + witness_weight = sum(witness_len) - overall_weight = funding_transaction_weight + witness_weight + overall_weight = funding_transaction_weight + witness_weight ### Calculating Fees for Collaborative Transaction Construction @@ -811,12 +811,10 @@ The contributor's minimum fee is calculated as follows. contributor_fees = 796 * 253 / 1000 contributor_fees = 201 sats - -This is an estimated fee. The peer MUST at least contribute the estimated rate, +This is an estimated fee. The peer MUST at least contribute the estimated fee, and MUST exceed the minimum fee in the case that their witness weight is greater than the estimated weight of 110 per input. - ## Expected Weight of the Commitment Transaction The *expected weight* of a commitment transaction is calculated as follows: @@ -2487,6 +2485,7 @@ before subtraction of: "RemoteSigHex": "3045022100c592f6b80d35b4f5d1e3bc9788f51141a0065be6013bad53a1977f7c444651660220278ac06ead9016bfb8dc476f186eabace2b02793b2f308442f5b0d5f24a68948" } ] +``` # Appendix G: Dual Funded Transaction Test Vectors From 6f3583b3dc0cebd80300de413b437325682e9460 Mon Sep 17 00:00:00 2001 From: t-bast Date: Tue, 10 May 2022 20:48:38 +0200 Subject: [PATCH 31/36] Increase RBF increment We use 1/24 instead of 1/64 to produce larger steps in fee-bumping. --- 02-peer-protocol.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index d86b518ec..ad6e9f10b 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -428,24 +428,24 @@ completed. #### Requirements The sender: - - MUST set `feerate` greater than or equal to 65/64 times the `feerate` + - MUST set `feerate` greater than or equal to 25/24 times the `feerate` of the previously constructed transaction, rounded down. The recipient: - MUST respond either by failing the negotiation or with `tx_ack_rbf`. - MUST fail the negotiation if: - - the `feerate` is not greater than 65/64 times `feerate` of the last + - the `feerate` is not greater than 25/24 times `feerate` of the last successfully constructed transaction - MAY fail the negotiation for any reason #### Rationale `feerate` is the feerate this transaction will pay. It must be at least -1/64 greater than the last used `feerate`, rounded down to the nearest +1/24 greater than the last used `feerate`, rounded down to the nearest satoshi to ensure there is progress. -E.g. if the last `feerate` was 520, the next sent `feerate` must be 528 -(520 * 65 / 64 = 528.125, rounded down to 528). +E.g. if the last `feerate` was 520, the next sent `feerate` must be 541 +(520 * 25 / 24 = 541.667, rounded down to 541). If the previous transaction confirms in the middle of an RBF attempt, the attempt MUST be abandoned. From 124fcfa1ee4c374e430cbb70a884adc974c536e9 Mon Sep 17 00:00:00 2001 From: niftynei Date: Fri, 13 May 2022 16:07:52 -0500 Subject: [PATCH 32/36] dual-fund: update funding transaction test case Add signature data, remove wrapped segwit inputs, update calculations to be more explicit about how to figure fee --- 03-transactions.md | 211 ++++++++++++++++++++++++--------------------- 1 file changed, 115 insertions(+), 96 deletions(-) diff --git a/03-transactions.md b/03-transactions.md index 9928a817c..309385750 100644 --- a/03-transactions.md +++ b/03-transactions.md @@ -2506,10 +2506,10 @@ Parent transaction (spends coinbase of block 1): ### Funding transaction (spends parent's outputs): -Locktime: 618013 +Locktime: 120 Feerate: 253 sat/kiloweight -Opener's `funding_satoshi`: 4 0000 0000 sat -Accepter's `funding_satoshi`: 4 0000 0000 sat +Opener's `funding_satoshi`: 2 0000 0000 sat +Accepter's `funding_satoshi`: 2 0000 0000 sat Inputs: ``` @@ -2520,14 +2520,6 @@ Inputs: scriptPubKey: 0020fd89acf65485df89797d9ba7ba7a33624ac4452f00db08107f34257d33e5b946 address: bcrt1qlky6eaj5sh0cj7tanwnm573nvf9vg3f0qrdssyrlxsjh6vl9h9rql40v2g -4303ca8ff10c6c345b9299672a66f111c5b81ae027cc5b0d4d39d09c66b032b9 1 - redeemScript: 0020fd89acf65485df89797d9ba7ba7a33624ac4452f00db08107f34257d33e5b946 - witness_data: - preimage: 20 68656c6c6f2074686572652c2074686973206973206120626974636f6e212121 - witness_script: 27 82012088a820add57dfe5277079d069ca4ad4893c96de91f88ffb981fdc6a2a34d5336c66aff87 - scriptPubKey: a9146a235d064786b49e7043e4a042d4cc429f7eb69487 - address: 2N2vRyi3cm5VYpw218MJJrJWK1Jd4qbaefW - 4303ca8ff10c6c345b9299672a66f111c5b81ae027cc5b0d4d39d09c66b032b9 2 pubkey: 034695f5b7864c580bf11f9f8cb1a94eb336f2ce9ef872d2ae1a90ee276c772484 privkey: cUM8Dr33wK4uFmw3Tz8sbQ7BiBNgX5BthRurU7RkgXVvNUPcWrJf @@ -2535,67 +2527,39 @@ Inputs: scriptPubKey: 0014fbb4db9d85fba5e301f4399e3038928e44e37d32 address: bcrt1qlw6dh8v9lwj7xq058x0rqwyj3ezwxlfjxsy7er -4303ca8ff10c6c345b9299672a66f111c5b81ae027cc5b0d4d39d09c66b032b9 3 - pubkey: 034695f5b7864c580bf11f9f8cb1a94eb336f2ce9ef872d2ae1a90ee276c772484 - privkey: cUM8Dr33wK4uFmw3Tz8sbQ7BiBNgX5BthRurU7RkgXVvNUPcWrJf - redeemScript: 0014fbb4db9d85fba5e301f4399e3038928e44e37d32 - witness_program: fbb4db9d85fba5e301f4399e3038928e44e37d32 - scriptPubKey: a9147ecd1b519326bc13b0ec716e469b58ed02b112a087 - address: 2N4ogqX3kaLTT2jjxi18nAiyWdwKtE5PxLF ``` -Expected Opener's `tx_add_input` (inputs 0+1 above): +### Expected Opener's `tx_add_input` (input 0 above): ``` - num_inputs: 2 + num_inputs: 1 tx_add_input:[ { - channel_id: xxx, - serial_id: 10, - prevtx_len: 353, - prevtx: 02000000000101f86fd1d0db3ac5a72df968622f31e6b5e6566a09e29206d7c7a55df90e181de800000000171600141fb9623ffd0d422eacc450fd1e967efc477b83ccffffffff0580b2e60e00000000220020fd89acf65485df89797d9ba7ba7a33624ac4452f00db08107f34257d33e5b94680b2e60e0000000017a9146a235d064786b49e7043e4a042d4cc429f7eb6948780b2e60e00000000160014fbb4db9d85fba5e301f4399e3038928e44e37d3280b2e60e0000000017a9147ecd1b519326bc13b0ec716e469b58ed02b112a087f0006bee0000000017a914f856a70093da3a5b5c4302ade033d4c2171705d387024730440220696f6cee2929f1feb3fd6adf024ca0f9aa2f4920ed6d35fb9ec5b78c8408475302201641afae11242160101c6f9932aeb4fcd1f13a9c6df5d1386def000ea259a35001210381d7d5b1bc0d7600565d827242576d9cb793bfe0754334af82289ee8b65d137600000000 -, - prev_vout: 0, - sequence: 4294967293, - script_sig_len: 0, - script_sig: null - },{ - channel_id: xxx, + channel_id: "xxx", serial_id: 20, prevtx_len: 353, - prevtx: 02000000000101f86fd1d0db3ac5a72df968622f31e6b5e6566a09e29206d7c7a55df90e181de800000000171600141fb9623ffd0d422eacc450fd1e967efc477b83ccffffffff0580b2e60e00000000220020fd89acf65485df89797d9ba7ba7a33624ac4452f00db08107f34257d33e5b94680b2e60e0000000017a9146a235d064786b49e7043e4a042d4cc429f7eb6948780b2e60e00000000160014fbb4db9d85fba5e301f4399e3038928e44e37d3280b2e60e0000000017a9147ecd1b519326bc13b0ec716e469b58ed02b112a087f0006bee0000000017a914f856a70093da3a5b5c4302ade033d4c2171705d387024730440220696f6cee2929f1feb3fd6adf024ca0f9aa2f4920ed6d35fb9ec5b78c8408475302201641afae11242160101c6f9932aeb4fcd1f13a9c6df5d1386def000ea259a35001210381d7d5b1bc0d7600565d827242576d9cb793bfe0754334af82289ee8b65d137600000000 - prev_vout: 1, - sequence: 4294967293, - script_sig_len: 68, - script_sig: 0020fd89acf65485df89797d9ba7ba7a33624ac4452f00db08107f34257d33e5b946 + prevtx: "02000000000101f86fd1d0db3ac5a72df968622f31e6b5e6566a09e29206d7c7a55df90e181de800000000171600141fb9623ffd0d422eacc450fd1e967efc477b83ccffffffff0580b2e60e00000000220020fd89acf65485df89797d9ba7ba7a33624ac4452f00db08107f34257d33e5b94680b2e60e0000000017a9146a235d064786b49e7043e4a042d4cc429f7eb6948780b2e60e00000000160014fbb4db9d85fba5e301f4399e3038928e44e37d3280b2e60e0000000017a9147ecd1b519326bc13b0ec716e469b58ed02b112a087f0006bee0000000017a914f856a70093da3a5b5c4302ade033d4c2171705d387024730440220696f6cee2929f1feb3fd6adf024ca0f9aa2f4920ed6d35fb9ec5b78c8408475302201641afae11242160101c6f9932aeb4fcd1f13a9c6df5d1386def000ea259a35001210381d7d5b1bc0d7600565d827242576d9cb793bfe0754334af82289ee8b65d137600000000", + prev_vout: 0, + sequence: 4294967293 } ] ``` -Expected Accepter's `tx_add_input` (inputs 2+3 above): +### Expected Accepter's `tx_add_input` (input 2 above): ``` - num_inputs: 2 + num_inputs: 1 tx_add_input:[ { - channel_id: xxx, + channel_id: "xxx", serial_id: 11, prevtx_len: 353, - prevtx: 02000000000101f86fd1d0db3ac5a72df968622f31e6b5e6566a09e29206d7c7a55df90e181de800000000171600141fb9623ffd0d422eacc450fd1e967efc477b83ccffffffff0580b2e60e00000000220020fd89acf65485df89797d9ba7ba7a33624ac4452f00db08107f34257d33e5b94680b2e60e0000000017a9146a235d064786b49e7043e4a042d4cc429f7eb6948780b2e60e00000000160014fbb4db9d85fba5e301f4399e3038928e44e37d3280b2e60e0000000017a9147ecd1b519326bc13b0ec716e469b58ed02b112a087f0006bee0000000017a914f856a70093da3a5b5c4302ade033d4c2171705d387024730440220696f6cee2929f1feb3fd6adf024ca0f9aa2f4920ed6d35fb9ec5b78c8408475302201641afae11242160101c6f9932aeb4fcd1f13a9c6df5d1386def000ea259a35001210381d7d5b1bc0d7600565d827242576d9cb793bfe0754334af82289ee8b65d137600000000 + prevtx: "02000000000101f86fd1d0db3ac5a72df968622f31e6b5e6566a09e29206d7c7a55df90e181de800000000171600141fb9623ffd0d422eacc450fd1e967efc477b83ccffffffff0580b2e60e00000000220020fd89acf65485df89797d9ba7ba7a33624ac4452f00db08107f34257d33e5b94680b2e60e0000000017a9146a235d064786b49e7043e4a042d4cc429f7eb6948780b2e60e00000000160014fbb4db9d85fba5e301f4399e3038928e44e37d3280b2e60e0000000017a9147ecd1b519326bc13b0ec716e469b58ed02b112a087f0006bee0000000017a914f856a70093da3a5b5c4302ade033d4c2171705d387024730440220696f6cee2929f1feb3fd6adf024ca0f9aa2f4920ed6d35fb9ec5b78c8408475302201641afae11242160101c6f9932aeb4fcd1f13a9c6df5d1386def000ea259a35001210381d7d5b1bc0d7600565d827242576d9cb793bfe0754334af82289ee8b65d137600000000", prev_vout: 2, - script_sig_len: 0, - script_sig: null - },{ - channel_id: xxx, - serial_id: 17, - prevtx_len: 353, - prevtx: 02000000000101f86fd1d0db3ac5a72df968622f31e6b5e6566a09e29206d7c7a55df90e181de800000000171600141fb9623ffd0d422eacc450fd1e967efc477b83ccffffffff0580b2e60e00000000220020fd89acf65485df89797d9ba7ba7a33624ac4452f00db08107f34257d33e5b94680b2e60e0000000017a9146a235d064786b49e7043e4a042d4cc429f7eb6948780b2e60e00000000160014fbb4db9d85fba5e301f4399e3038928e44e37d3280b2e60e0000000017a9147ecd1b519326bc13b0ec716e469b58ed02b112a087f0006bee0000000017a914f856a70093da3a5b5c4302ade033d4c2171705d387024730440220696f6cee2929f1feb3fd6adf024ca0f9aa2f4920ed6d35fb9ec5b78c8408475302201641afae11242160101c6f9932aeb4fcd1f13a9c6df5d1386def000ea259a35001210381d7d5b1bc0d7600565d827242576d9cb793bfe0754334af82289ee8b65d137600000000 - prev_vout: 3, - script_sig_len: 22, - script_sig: 0014fbb4db9d85fba5e301f4399e3038928e44e37d32 + sequence: 4294967293 } ] ``` -Outputs: (scriptPubKeys) +### Outputs: (scriptPubKeys) ``` # opener's change address pubkey: 0206e626a4c6d4392d4030bc78bd93f728d1ba61214a77c63adc17d71e32ded3df @@ -2618,28 +2582,28 @@ scriptPubKey: 0020297b92c238163e820b82486084634b4846b86a3c658d87b9384192e6bea98e address: bcrt1q99ae9s3czclgyzuzfpsggc6tfprts63uvkxc0wfcgxfwd04f3mzs3asq6l ``` -Expected Opener's `tx_add_output`: +### Expected Opener's `tx_add_output`: ``` num_outputs: 2 tx_add_output[ { - channel_id: xxx, + channel_id:"xxx", serial_id: 30, - sats: 99999809 - scriptlen: 22 - script: 1600141ca1cca8855bad6bc1ea5436edd8cff10b7e448b + sats: 49999845, + scriptlen: 22, + script: "1600141ca1cca8855bad6bc1ea5436edd8cff10b7e448b" },{ - channel_id: xxx, + channel_id: "xxx", serial_id: 44, - sats: 800000000 - scriptlen: 34 - script: 220020297b92c238163e820b82486084634b4846b86a3c658d87b9384192e6bea98ec5 + sats: 400000000, + scriptlen: 34, + script: "220020297b92c238163e820b82486084634b4846b86a3c658d87b9384192e6bea98ec5" } ] ``` -Expected Accepter's `tx_add_output`: +### Expected Accepter's `tx_add_output`: ``` num_outputs: 1 @@ -2647,83 +2611,138 @@ Expected Accepter's `tx_add_output`: { channel_id: xxx, serial_id: 33, - sats: 99999809 - scriptlen: 22 + sats: 49999899, + scriptlen: 22, script: 16001444cb0c39f93ecc372b5851725bd29d865d333b10 } + ] ``` -Expected Fee Calculation: +### Expected Fee Calculation: Opener's fees and change: ``` - initiator_weight = transaction_fields * 4 - + segwit_fields - + inputs * 4 + initiator_weight = (input_count, output_count, version, locktime) * 4 + + segwit_fields (marker + flag) + + inputs (txid, vout, scriptSig, sequence) * number initiator inputs * 4 + funding_output * 4 + change_output * 4 - + sum_max_witness_weight + + max(number initiator inputs + * minimum witness weight, + actual witness weight of all inputs) - initiator_weight = 10 * 4 + initiator_weight = (1 + 1 + 4 + 4) * 4 + 2 - + (41 + 74) * 4 + + (32 + 4 + 1 + 4) * 1 * 4 + 43 * 4 + 31 * 4 - + 148 + + max(1 * 110, 71) - initiator_weight = 946 + initiator_weight = 612 initiator_fees = initiator_weight * feerate - initiator_fees = 946 * 253 / 1000 - initiator_fees = 239 sats + initiator_fees = 722 * 253 / 1000 + initiator_fees = 155 sats change = total_funding - funding_sats - fees - change = 5 0000 0000 - - 4 0000 0000 - - 239 + change = 2 5000 0000 + - 2 0000 0000 + - 155 - change = 9999 9761 -``` + change = 4999 9845 -Accepter's fees and change: + as hex: e5effa0200000000 ``` - contributor_weight = 2 * p2wpkh_input * 4 - + 2 * p2wpkh_output * 4 - + sum_max_witness_weight - contributor_weight = (41 + 63) * 4 +### Accepter's fees and change: +``` + contributor_weight = inputs(txid, vout, scriptSig, sequence) + * number contributor inputs * 4 + + change_output * 4 + + max(number contributor inputs + * minimum witness weight, + actual witness weight of all inputs) + + contributor_weight = (32 + 4 + 1 + 4) * 1 * 4 + 31 * 4 - + 218 + + max(1 * 110, 99) - contributor_weight = 758 + contributor_weight = 398 contributor_fees = contributor_weight * feerate - contributor_fees = 758 * 253 / 1000 - contributor_fees = 191 sats + contributor_fees = 398 * 253 / 1000 + contributor_fees = 101 sats change = total_funding - funding_sats - fees - change = 5 0000 0000 - - 4 0000 0000 - - 191 + change = 2 5000 0000 + - 2 0000 0000 + - 101 + + change = 4999 9899 + + as hex: 1bf0fa0200000000 +``` + +### Unsigned Funding Transaction: +``` +0200000002b932b0669cd0394d0d5bcc27e01ab8c511f1662a6799925b346c0cf18fca03430200000000fdffffffb932b0669cd0394d0d5bcc27e01ab8c511f1662a6799925b346c0cf18fca03430000000000fdffffff03e5effa02000000001600141ca1cca8855bad6bc1ea5436edd8cff10b7e448b1bf0fa020000000016001444cb0c39f93ecc372b5851725bd29d865d333b100084d71700000000220020297b92c238163e820b82486084634b4846b86a3c658d87b9384192e6bea98ec578000000 +``` - change = 9999 9809 +### Expected Opener's `tx_signatures`: +``` + tx_signatures{ + channel_id: xxx, + txid: "046f570b49c60e5dcb5ce3295c9678bde91f673f5fe71e6aafcf76b6babb1050", + num_witnesses: 1, + witness_stack[{ + num_input_witness: 2, + witness_element:[ + { + len: 32, + witness: "68656c6c6f2074686572652c2074686973206973206120626974636f6e212121" + },{ + len: 39, + witness: "82012088a820add57dfe5277079d069ca4ad4893c96de91f88ffb981fdc6a2a34d5336c66aff87" + }] + }] + } ``` -Unsigned Funding Transaction: +### Expected Accepter's `tx_signatures`: + ``` -0200000004b932b0669cd0394d0d5bcc27e01ab8c511f1662a6799925b346c0cf18fca03430000000000ffffffffb932b0669cd0394d0d5bcc27e01ab8c511f1662a6799925b346c0cf18fca03430200000000ffffffffb932b0669cd0394d0d5bcc27e01ab8c511f1662a6799925b346c0cf18fca03430300000000ffffffffb932b0669cd0394d0d5bcc27e01ab8c511f1662a6799925b346c0cf18fca03430100000000ffffffff0341e0f505000000001600141ca1cca8855bad6bc1ea5436edd8cff10b7e448b11e0f5050000000016001444cb0c39f93ecc372b5851725bd29d865d333b100008af2f00000000220020297b92c238163e820b82486084634b4846b86a3c658d87b9384192e6bea98ec51d6e0900 + tx_signatures{ + channel_id: xxx, + txid: "046f570b49c60e5dcb5ce3295c9678bde91f673f5fe71e6aafcf76b6babb1050", + num_witnesses: 1, + witness_stack[{ + num_input_witness: 2, + witness_element:[ + { + len: 71, + witness: "304402207fd87dbbf34bc4fca19d1f4b03f7ae1cfa5e764fef5ca0ab133034432f6383a302204c9bc5ce6f7996a55d550b5425086f71dda57387377c05e63e164d84f1aed71c01", + },{ + len: 33, + witness: "034695f5b7864c580bf11f9f8cb1a94eb336f2ce9ef872d2ae1a90ee276c772484" + }] + }] + } ``` -Signed Funding Transaction: +#### Signed Funding Transaction: + +Note locktime is set to 120. + ``` -TODO +02000000000102b932b0669cd0394d0d5bcc27e01ab8c511f1662a6799925b346c0cf18fca03430200000000fdffffffb932b0669cd0394d0d5bcc27e01ab8c511f1662a6799925b346c0cf18fca03430000000000fdffffff03e5effa02000000001600141ca1cca8855bad6bc1ea5436edd8cff10b7e448b1bf0fa020000000016001444cb0c39f93ecc372b5851725bd29d865d333b100084d71700000000220020297b92c238163e820b82486084634b4846b86a3c658d87b9384192e6bea98ec50247304402207fd87dbbf34bc4fca19d1f4b03f7ae1cfa5e764fef5ca0ab133034432f6383a302204c9bc5ce6f7996a55d550b5425086f71dda57387377c05e63e164d84f1aed71c0121034695f5b7864c580bf11f9f8cb1a94eb336f2ce9ef872d2ae1a90ee276c772484022068656c6c6f2074686572652c2074686973206973206120626974636f6e2121212782012088a820add57dfe5277079d069ca4ad4893c96de91f88ffb981fdc6a2a34d5336c66aff8778000000 + ``` # References From ba0f679131a0b8973613a1a1bc397229b665e5fe Mon Sep 17 00:00:00 2001 From: niftynei Date: Fri, 13 May 2022 16:49:40 -0500 Subject: [PATCH 33/36] dual-fund: tie-break tx_sigs send order on node's pubkey If both peers contribute an equal amount to a interactive tx, peer with "lower" pubkey sends first --- 02-peer-protocol.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index ad6e9f10b..7ba26730a 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -394,7 +394,9 @@ The receiving node: #### Rationale The peer with the lowest total of inputs amounts must transmit its -`tx_signatures` first. This gives in a strict ordering of transmission +`tx_signatures` first. If both peers have contributed equal input amounts, +the peer with the first `node_id` (sorted lexicographically) sends their +`tx_signatures` first. This gives in a strict ordering of transmission for any multiparty tx collaboration. `witness` is the data for a witness element in a witness stack. From 8dbba6249992d3d123b983f2f138a9aa1848559b Mon Sep 17 00:00:00 2001 From: niftynei Date: Mon, 16 May 2022 12:52:03 -0500 Subject: [PATCH 34/36] dual-fund: adjust the minimum witness weight down to 107 (from 110) The weight of a witness stack for a p2wpkh low-r signature is 107 bytes. --- 02-peer-protocol.md | 2 +- 03-transactions.md | 58 ++++++++++++++++++++++----------------------- 2 files changed, 30 insertions(+), 30 deletions(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index 7ba26730a..026d3f97d 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -408,7 +408,7 @@ the corresponding input. While the `minimum fee` is calculated and verified at `tx_complete` conclusion, it is possible for the fee for the exchanged witness data to be underpaid. It is the responsibility of the sending peer to correctly account for the -required fee, e.g. a multisig witness stack whose weight exceeds 110. +required fee, e.g. a multisig witness stack whose weight exceeds 107. ### The `tx_init_rbf` Message diff --git a/03-transactions.md b/03-transactions.md index 309385750..2a90be255 100644 --- a/03-transactions.md +++ b/03-transactions.md @@ -766,54 +766,54 @@ Upon successful exchange of `tx_complete` messages, each peer must at least cover a minimum estimated fee. Here is how to calculate the minimum fee for each participant. -The minimum witness weight for an input is 110. +The minimum witness weight for an input is 107. In the following, the initiator has provided one input (P2WPKH), one change output (P2WPKH), and the funding output. The contributor has provided two inputs (P2WPKH) and two change outputs (P2WPKH). Assuming a `feerate` of 253 per kiloweight, the initiator's minimum fee is -calculated as follows. Note that the feerate is rounded down to the nearest satoshi. +calculated as follows. Note that the feerate is rounded up to the nearest satoshi. initiator_weight = transaction_fields * 4 + segwit_fields + p2wpkh_input * 4 + funding_output * 4 + p2wpkh_output * 4 - + input_count * 110 (minimum witness weight) + + input_count * 107 (minimum witness weight) initiator_weight = 10 * 4 + 2 + 41 * 4 + 43 * 4 + 31 * 4 - + 110 + + 107 - initiator_weight = 612 + initiator_weight = 609 initiator_fees = initiator_weight * feerate - initiator_fees = 612 * 253 / 1000 - initiator_fees = 154 sats + initiator_fees = 609 * 253 / 1000 + initiator_fees = 155 sats The contributor's minimum fee is calculated as follows. contributor_weight = 2 * p2wpkh_input * 4 + 2 * p2wpkh_output * 4 - + input_count * 110 (minimum witness weight) + + input_count * 107 (minimum witness weight) contributor_weight = 2 * 41 * 4 + 2 * 31 * 4 - + 2 * 110 + + 2 * 107 - contributor_weight = 796 + contributor_weight = 790 contributor_fees = contributor_weight * feerate - contributor_fees = 796 * 253 / 1000 - contributor_fees = 201 sats + contributor_fees = 790 * 253 / 1000 + contributor_fees = 200 sats This is an estimated fee. The peer MUST at least contribute the estimated fee, and MUST exceed the minimum fee in the case that their witness weight is greater -than the estimated weight of 110 per input. +than the estimated weight of 107 per input. ## Expected Weight of the Commitment Transaction @@ -2611,7 +2611,7 @@ address: bcrt1q99ae9s3czclgyzuzfpsggc6tfprts63uvkxc0wfcgxfwd04f3mzs3asq6l { channel_id: xxx, serial_id: 33, - sats: 49999899, + sats: 49999900, scriptlen: 22, script: 16001444cb0c39f93ecc372b5851725bd29d865d333b10 } @@ -2636,12 +2636,12 @@ Opener's fees and change: + (32 + 4 + 1 + 4) * 1 * 4 + 43 * 4 + 31 * 4 - + max(1 * 110, 71) + + max(1 * 107, 71) - initiator_weight = 612 + initiator_weight = 609 initiator_fees = initiator_weight * feerate - initiator_fees = 722 * 253 / 1000 + initiator_fees = 609 * 253 / 1000 initiator_fees = 155 sats change = total_funding @@ -2668,13 +2668,13 @@ Opener's fees and change: contributor_weight = (32 + 4 + 1 + 4) * 1 * 4 + 31 * 4 - + max(1 * 110, 99) + + max(1 * 107, 99) - contributor_weight = 398 + contributor_weight = 395 contributor_fees = contributor_weight * feerate contributor_fees = 398 * 253 / 1000 - contributor_fees = 101 sats + contributor_fees = 100 sats change = total_funding - funding_sats @@ -2682,16 +2682,17 @@ Opener's fees and change: change = 2 5000 0000 - 2 0000 0000 - - 101 + - 100 - change = 4999 9899 + change = 4999 9900 - as hex: 1bf0fa0200000000 + as hex: 1cf0fa0200000000 ``` ### Unsigned Funding Transaction: + ``` -0200000002b932b0669cd0394d0d5bcc27e01ab8c511f1662a6799925b346c0cf18fca03430200000000fdffffffb932b0669cd0394d0d5bcc27e01ab8c511f1662a6799925b346c0cf18fca03430000000000fdffffff03e5effa02000000001600141ca1cca8855bad6bc1ea5436edd8cff10b7e448b1bf0fa020000000016001444cb0c39f93ecc372b5851725bd29d865d333b100084d71700000000220020297b92c238163e820b82486084634b4846b86a3c658d87b9384192e6bea98ec578000000 +0200000002b932b0669cd0394d0d5bcc27e01ab8c511f1662a6799925b346c0cf18fca03430200000000fdffffffb932b0669cd0394d0d5bcc27e01ab8c511f1662a6799925b346c0cf18fca03430000000000fdffffff03e5effa02000000001600141ca1cca8855bad6bc1ea5436edd8cff10b7e448b1cf0fa020000000016001444cb0c39f93ecc372b5851725bd29d865d333b100084d71700000000220020297b92c238163e820b82486084634b4846b86a3c658d87b9384192e6bea98ec578000000 ``` ### Expected Opener's `tx_signatures`: @@ -2699,7 +2700,7 @@ Opener's fees and change: ``` tx_signatures{ channel_id: xxx, - txid: "046f570b49c60e5dcb5ce3295c9678bde91f673f5fe71e6aafcf76b6babb1050", + txid: "5ca4e657c1aa9d069ea4a5d712045d233a7d7c52738cb02993637289e6386057", num_witnesses: 1, witness_stack[{ num_input_witness: 2, @@ -2720,14 +2721,14 @@ Opener's fees and change: ``` tx_signatures{ channel_id: xxx, - txid: "046f570b49c60e5dcb5ce3295c9678bde91f673f5fe71e6aafcf76b6babb1050", + txid: "5ca4e657c1aa9d069ea4a5d712045d233a7d7c52738cb02993637289e6386057", num_witnesses: 1, witness_stack[{ num_input_witness: 2, witness_element:[ { len: 71, - witness: "304402207fd87dbbf34bc4fca19d1f4b03f7ae1cfa5e764fef5ca0ab133034432f6383a302204c9bc5ce6f7996a55d550b5425086f71dda57387377c05e63e164d84f1aed71c01", + witness: "304402207de9ba56bb9f641372e805782575ee840a899e61021c8b1572b3ec1d5b5950e9022069e9ba998915dae193d3c25cb89b5e64370e6a3a7755e7f31cf6d7cbc2a49f6d01", },{ len: 33, witness: "034695f5b7864c580bf11f9f8cb1a94eb336f2ce9ef872d2ae1a90ee276c772484" @@ -2741,8 +2742,7 @@ Opener's fees and change: Note locktime is set to 120. ``` -02000000000102b932b0669cd0394d0d5bcc27e01ab8c511f1662a6799925b346c0cf18fca03430200000000fdffffffb932b0669cd0394d0d5bcc27e01ab8c511f1662a6799925b346c0cf18fca03430000000000fdffffff03e5effa02000000001600141ca1cca8855bad6bc1ea5436edd8cff10b7e448b1bf0fa020000000016001444cb0c39f93ecc372b5851725bd29d865d333b100084d71700000000220020297b92c238163e820b82486084634b4846b86a3c658d87b9384192e6bea98ec50247304402207fd87dbbf34bc4fca19d1f4b03f7ae1cfa5e764fef5ca0ab133034432f6383a302204c9bc5ce6f7996a55d550b5425086f71dda57387377c05e63e164d84f1aed71c0121034695f5b7864c580bf11f9f8cb1a94eb336f2ce9ef872d2ae1a90ee276c772484022068656c6c6f2074686572652c2074686973206973206120626974636f6e2121212782012088a820add57dfe5277079d069ca4ad4893c96de91f88ffb981fdc6a2a34d5336c66aff8778000000 - +02000000000102b932b0669cd0394d0d5bcc27e01ab8c511f1662a6799925b346c0cf18fca03430200000000fdffffffb932b0669cd0394d0d5bcc27e01ab8c511f1662a6799925b346c0cf18fca03430000000000fdffffff03e5effa02000000001600141ca1cca8855bad6bc1ea5436edd8cff10b7e448b1cf0fa020000000016001444cb0c39f93ecc372b5851725bd29d865d333b100084d71700000000220020297b92c238163e820b82486084634b4846b86a3c658d87b9384192e6bea98ec50247304402207de9ba56bb9f641372e805782575ee840a899e61021c8b1572b3ec1d5b5950e9022069e9ba998915dae193d3c25cb89b5e64370e6a3a7755e7f31cf6d7cbc2a49f6d0121034695f5b7864c580bf11f9f8cb1a94eb336f2ce9ef872d2ae1a90ee276c772484022068656c6c6f2074686572652c2074686973206973206120626974636f6e2121212782012088a820add57dfe5277079d069ca4ad4893c96de91f88ffb981fdc6a2a34d5336c66aff8778000000 ``` # References From e86d4a5bd1b15259c2b44a09af986168008b2e36 Mon Sep 17 00:00:00 2001 From: niftynei Date: Wed, 18 May 2022 12:51:13 -0500 Subject: [PATCH 35/36] dual-fund: add missing tlv structs to RBF messages Don't show up in the CLN generator w/o this --- 02-peer-protocol.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index 026d3f97d..f16ee6d57 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -420,6 +420,7 @@ completed. * [`channel_id`:`channel_id`] * [`u32`:`locktime`] * [`u32`:`feerate`] + * [`tx_init_rbf_tlvs`:`tlvs`] 1. `tlv_stream`: `tx_init_rbf_tlvs` 2. types: @@ -461,7 +462,8 @@ made in the previously completed transaction. 1. type: 73 (`tx_ack_rbf`) 2. data: - * [`channel_id`:`channel_id`] + * [`channel_id`:`channel_id`] + * [`tx_ack_rbf_tlvs`:`tlvs`] 1. `tlv_stream`: `tx_ack_rbf_tlvs` 2. types: From 96dc0b7726dbf7c6283866a20acc90e5710157d6 Mon Sep 17 00:00:00 2001 From: Dustin Dettmer Date: Thu, 30 Jun 2022 15:54:48 -0500 Subject: [PATCH 36/36] Add funding outpoint sigs to tx_signatures message --- 02-peer-protocol.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index f16ee6d57..138e52447 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -358,6 +358,7 @@ the byte size of the input and output counts on the transaction to one (1). * [`sha256`:`txid`] * [`u16`:`num_witnesses`] * [`num_witnesses*witness_stack`:`witness_stack`] + * [`txsigs_tlvs`:`tlvs`] 1. subtype: `witness_stack` 2. data: @@ -369,6 +370,12 @@ the byte size of the input and output counts on the transaction to one (1). * [`u16`:`len`] * [`len*byte`:`witness`] +1. `tlv_stream`: `txsigs_tlvs` +2. types: + 1. type: 0 (`funding_outpoint_sig`) + 2. data: + * [`...*byte`:`sig`] + #### Requirements The sending node: @@ -377,7 +384,10 @@ The sending node: - MUST transmit their `tx_signatures` before the peer - MUST order the `witness_stack`s by the `serial_id` of the input they correspond to + - MAY add `funding_outpoint_sig`s if funding outpoints are being spent. In + this case the corresponding inputs are not included in the `witness_stack`. - number of `witness_stack`s MUST equal the number of inputs they added + less the inputs spending funding outpoints The receiving node: - MUST fail the negotiation if: