From 944bccec007a808af87d9490b678baabc377c2b0 Mon Sep 17 00:00:00 2001 From: lisa neigut Date: Mon, 3 Dec 2018 13:36:03 -0600 Subject: [PATCH 01/44] features: add option for dual funding --- 09-features.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/09-features.md b/09-features.md index 74e1c7925..69ad94377 100644 --- a/09-features.md +++ b/09-features.md @@ -18,6 +18,7 @@ features may be required for opening a channel, but not a requirement for use of the channel, so the presentation of those features depends on the feature itself. + The Context column decodes as follows: * `I`: presented in the `init` message. * `N`: presented in the `node_announcement` messages @@ -37,6 +38,7 @@ The Context column decodes as follows: | 12/13 | `option_static_remotekey` | Static key for remote output | IN | | [BOLT #3](03-transactions.md) | | 14/15 | `payment_secret` | Node supports `payment_secret` field | IN9 | `var_onion_optin` | [Routing Onion Specification][bolt04] | | 16/17 | `basic_mpp` | Node can receive basic multi-part payments | IN9 | `payment_secret` | [BOLT #4][bolt04-mpp] | +| 17/18 | `option_dual_fund` | Use v2 of channel open, enables dual funding | IN9 | | [BOLT #2](02-peer-protocol.md) | ## Requirements From 5a748ae5a9dc3dac0af84e03fe05f74f487f0568 Mon Sep 17 00:00:00 2001 From: lisa neigut Date: Tue, 4 Dec 2018 16:01:45 -0800 Subject: [PATCH 02/44] peer: add v2 for open_channel First draft of flow for v2 of channel establishment. --- .aspell.en.pws | 16 ++ 02-peer-protocol.md | 413 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 429 insertions(+) diff --git a/.aspell.en.pws b/.aspell.en.pws index 15b8def16..051ae5bc0 100644 --- a/.aspell.en.pws +++ b/.aspell.en.pws @@ -114,6 +114,21 @@ delayedsig hopDataSize I'th segwit +SegWit +sizeof +varint +tlv +rbf +RBF +accepter +subtype +subsubtype +UTXO +utxo +scriptPubkey +counterparty's +RBFs +ack'd htlc htlcs ChaCha @@ -375,3 +390,4 @@ GitHub IRC bitmasks CSPRNG +workflow diff --git a/02-peer-protocol.md b/02-peer-protocol.md index 1f4f0a5ee..8738e4381 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -13,6 +13,15 @@ operation, and closing. * [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) + * [The `funding_compose` Message](#the-funding_compose-message) + * [The `commitment_signed2` Message](#the-commitment_signed2-message) + * [The `funding_signed2` Message](#the-funding_signed2-message) + * [The `funding_locked2` Message](#the-funding_locked2-message) + * [Kicking Off Replace-By-Fee: `init_rbf` Message](#kicking-off-replace-by-fee-init_rbf) + * [Acknowledging Replace-By-Fee `ack_rbf` Message](#acknowledging-replace-by-fee-ack_rbf) * [Channel Close](#channel-close) * [Closing Initiation: `shutdown`](#closing-initiation-shutdown) * [Closing Negotiation: `closing_signed`](#closing-negotiation-closing_signed) @@ -54,6 +63,11 @@ ids. 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 @@ -215,6 +229,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. @@ -417,6 +433,403 @@ funds are at risk. If the fundee were to remember the channel forever, this would create a Denial of Service risk; therefore, forgetting it is recommended (even if the promise of `push_msat` is significant). + +## Channel Establishment v2 + +This is the second version of the channel establishment protocol. +It extends version one to allow the non-`open_channel` participant +(the accepter) to contribute inputs to the funding transaction. + +The protocol is also expanded to include a mechanism for initiating RBF. + + +-------+ +-------+ + | |--(1)--- open_channel2 ----->| | + | |<-(2)-- accept_channel2 -----| | + | | | | + | |--(3)-- funding_compose ---->| | + | |<-(4)-- funding_compose -----| | + | | | | + --->| |--(5)-- commitment_signed -->| | + | | |<-(6)-- commitment_signed ---| | + | | A | | B | + | | |--(7)--- funding_signed2 ---->| | + | | |<-(8)--- funding_signed2 -----| | + | | | | | + | | |--(a)--- init_rbf ----------->| | + ----| |<-(b)--- ack_rbf ------------| | + | | | | + | |--(9)--- funding_locked2 ---->| | + | |<-(10)-- funding_locked2 -----| | + +-------+ +-------+ + + - where node A is 'opener' and node B is 'accepter' + +### The `open_channel2` Message + +This message initiates the v2 channel establishment workflow. + +1. type: 56 (`open_channel2`) +2. data: + * [`32`:`chain_hash`] + * [`32`:`temporary_channel_id`] + * [`8`:`push_msat`] + * [`8`:`funding_satoshis`] + * [`8`:`dust_limit_satoshis`] + * [`8`:`max_htlc_value_in_flight_msat`] + * [`8`:`channel_reserve_satoshis`] + * [`8`:`htlc_minimum_msat`] + * [`4`:`feerate_per_kw`] + * [`4`:`feerate_per_kw_funding`] + * [`2`:`to_self_delay`] + * [`2`:`max_accepted_htlcs`] + * [`33`:`funding_pubkey`] + * [`33`:`revocation_basepoint`] + * [`33`:`payment_basepoint`] + * [`33`:`delayed_payment_basepoint`] + * [`33`:`htlc_basepoint`] + * [`33`:`first_per_commitment_point`] + * [`1`:`channel_flags`] + * [`2`:`opening_tlv_len`] + * [`opening_tlv_len`:`opening_tlv`] + + +1. tlv: `opening_tlv` +2. types: + 1. type: 1 (`option_upfront_shutdown_script`) + 2. data: + * [`2`:`shutdown_len`] + * [`shutdown_len`:`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` + +#### Rationale + +`feerate_per_kw_funding`: fee rate that the opening node will pay +for the funding transaction. + + +### The `accept_channel2` Message + +This message contains information about a node and indicates its +acceptance of the new channel. + +1. type: 57 (`accept_channel2`) +2. data: + * [`32`:`temporary_channel_id`] + * [`8`:`dust_limit_satoshis`] + * [`8`:`max_htlc_value_in_flight_msat`] + * [`8`:`channel_reserve_satoshis`] + * [`8`:`htlc_minimum_msat`] + * [`4`:`minimum_depth`] + * [`2`:`to_self_delay`] + * [`2`:`max_accepted_htlcs`] + * [`33`:`funding_pubkey`] + * [`33`:`revocation_basepoint`] + * [`33`:`payment_basepoint`] + * [`33`:`delayed_payment_basepoint`] + * [`33`:`htlc_basepoint`] + * [`33`:`first_per_commitment_point`] + * [`2`:`opening_tlv_len`] + * [`opening_tlv_len`:`opening_tlv`] + +Rationale and Requirements are the same as listed above, +for [`accept_channel`](#the-accept_channel-message) + + +### The `funding_compose` Message + +This message exchanges the transaction input and output +information necessary to compose the funding transaction. + +1. type: 58 (`funding_compose`) +2. data: + * [`32`:`temporary_channel_id`] + * [`2`:`num_inputs`] + * [`num_inputs*input_info`] + * [`2`:`num_outputs`] + * [`num_outputs*output_info`] + +1. subtype: `input_info` +2. data: + * [`8`:`satoshis`] + * [`32`:`prevtx_txid`] + * [`4`:`prevtx_vout`] + * [`2`:`prevtx_scriptpubkey_len`] + * [`prevtx_scriptpubkey_len`:`prevtx_scriptpubkey`] + * [`2`:`max_witness_len`] + * [`2`:`scriptlen`] + * [`scriptlen`:`script`] + +1. subtype: `output_info` +2. data: + * [`8`:`satoshis`] + * [`2`:`scriptlen`] + * [`scriptlen`:`script`] + +#### Requirements + +The sending node: + - MUST ensure each `input_info` refers to a non-malleable (segwit) UTXO. + - MUST ensure the `output_info`.`script` is a standard script + - MUST NOT include the channel funding output. + - if is the `opener`: + - MUST NOT send zero inputs (`num_inputs` cannot be zero). + - MUST specify an output with value zero, which will be used + as the change address. + - if is the `accepter`: + - consider the `*put_limit` the total of `num_inputs` plus + `num_outputs' from `funding_compose`, with minimum 2. + - MUST NOT send `input_info`s or `output_info` which + exceeds the `*put_limit`. + - MAY send zero inputs and/or outputs. + +The receiving node: + - if the total `input_info`.`satoshis` is less than the total `output_info`.`satoshis` + - MUST fail the channel. + - if is the `opener`: + - MUST fail the channel if: + - the total count of `input_info`s and `output_info`s is greater than + the `[in|out]put_limit`. + - if has not yet sent a `funding_compose`: + - MUST send its `funding_compose` message. + - otherwise: + - MUST use the sent and received `input_info` and `output_info` + to create the funding transaction, using `max_witness_len` + for each `input_info` and `feerate_per_kw_funding` as specified in + `open_channel2`. + - MUST send `commitment_signed2`. + + +#### Rationale +Each node must have a complete set of the transaction inputs and outputs, +to derive the funding transaction. This avoids information +asymmetry between the nodes, as both sides share their input utxo set. + +`satoshis` is the value of the input or output. + +`prevtxid` and `prevtxoutnum` specify the input to be spent. +`prevtxid` is the hash of the transaction that this input is +specified in, `prevtxoutnum` its outpoint. + +`max_witness_len` is the total serialized length of the +witness data that will be supplied (e.g. sizeof(varint) + +sizeof(witness) for each) in `funding_signed2`. Used to compose the funding +transaction. + +`input_info`.`script` is the scriptPubkey data for the input. +NB: for native SegWit inputs (P2WPKH and P2WSH) inputs, the `script` field +will be empty. See [BIP141](https://github.com/bitcoin/bips/blob/master/bip-0141.mediawiki#examples). + +The opening node must include at least one output with `satoshis` value +of zero. This will be used for change, or discarded if its value is +be below `dust_limit_satoshis`. + +Change is calculated as the sum of the opener's `input_info`.`satoshis` +minus the estimated funding transaction size times the +`feerate_per_kw_funding` minus the `funding_satoshis` minus all other +`output_info`.`satoshis`. If the `change_satoshis` value is negative, +the difference is subtracted from `funding_satoshis`. + +``` +change_satoshis = sum(inputs.satoshis) - est_tx_kw * feerate_per_kw_funding - sum(outputs.satoshis) - funding_satoshis +``` + +`output_info`.`script` is the locking script for the output. + +The channel funding output is not exchanged, as it can be derived +independently. + +#### The `commitment_signed2` Message + +This message exchanges the counterparty's signature for the +first commitment transaction, so it can broadcast the funding +transaction knowing that the funds can be redeemed. + +1. type: 59 (`commitment_signed2`) +2. data: + See [`commitment_signed`](#commiting-updates-so-far-commitment_signed). + +#### Requirements: + +The sending node: + - MUST derive the `channel_id` from the SHA256( + `open_channel2`.`revocation_basepoint`|`accept_channel2`.`revocation_` + `basepoint`) + - MUST set signature to the valid signature, using its `funding_pubkey` + for the initial commitment transaction, as defined in [BOLT #3](03-transactions.md#per-commitment-secret-requirements). + - MUST set `num_htlcs` to zero. + +A receiving node: + - if the `num_htlcs` is not zero: + - MUST fail the channel. + - if sent in response to a `funding_compose` message: + - MUST respond with a `commitment_signed` message. + - otherwise: + - MUST respond with a `funding_signed2` message. + +#### Rationale +There are no HTLC's yet, so the number must be zero. FIXME: use this +for `will_fund_for_food` bonds? + +Note that the channel id for `open_channel2` is fixed as the SHA256 of the +concatenated revocation points, and will not update. This allows stable +channel tracking across RBFs and splicing attempts. + +### The `funding_signed2` Message + +This message exchanges the witness data for the inputs that were +originally sent in the `funding_compose` message. + +1. type: 60 (`funding_signed2`) +2. data: + * [`32`:`channel_id`] + * [`2`:`num_witnesses`] + * [`num_witnesses*witness_stack`] + +1. subtype: `witness_stack` +2. data: + * [`2`:`num_input_witness`] + * [`num_input_witness*witness_element`] + +1. subsubtype: `witness_element` +2. data: + * [`2`:`len`] + * [`len`:`witness`] + +#### Requirements +The sending node: + - MUST set `witness` to the serialized witness data for each of its + inputs, in funding transaction order. FIXME: link to funding tx order + - MUST remember the details of this funding transaction. + - MUST NOT send a `witness_stack` whose length exceeds its + previously indicated `max_witness_len`. + - if it has NOT received a valid `commitment_signed` message: + - MUST NOT send a `funding_signed2` message. + +The receiving node: + - if the `witness_stack` length exceeds `max_witness_len`: + - MUST error. + - if the recipient was the sender of `open_channel2`: + - SHOULD reply with its own `funding_signed2`. + - SHOULD apply `witness`es to the funding transaction and + broadcast it. + +#### Rationale +Exchanging witness data allows both sides to broadcast the funding +transaction. + +### The `funding_locked2` Message + +This message signals that the funding transaction has reached the appropriate +chain depth and is considered locked. An exchange of `funding_locked2` messages +concludes the channel establishment workflow. + +1. type: 61 (`funding_locked2`) +2. data: + * [`32`:`channel_id`] + * [`32`:`funding_tx_id`] + * [`33`:`next_per_commitment_point`] + +See [`funding_locked`](#the-funding_locked-message) for Requirements and +Rationale, with the following addition. + +#### Requirements + +The receiving node: + - if the `funding_tx_id` does not match the `funding_tx_id` of the funding + transaction it observed: + - MUST fail the channel. + +#### Rationale + +`funding_tx_id` is the transaction hash for the funding transaction that +is locked in. This is to confirm that both nodes are using the same +transaction for funding. (It is possible for them to diverge in the unlikely +case of a network partition concurrent with an RBF attempt.) + + +### Kicking Off Replace-By-Fee: `init_rbf` + +This message initiates the flow to create a replacement funding +transaction. It is sent by the channel opener, after the funding +transaction has been broadcast but before a `funding_locked2` message +is exchanged. + +Once an `init_rbf` message has been successfully ack'd by the accepter +node, the message flow returns to `commitment_signed` and proceeds as +indicated above. + +1. type: 62 (`init_rbf`) +2. data: + * [`32`:`channel_id`] + * [`8`:`funding_satoshis`] + * [`8`:`channel_reserve_satoshis`] + * [`4`:`feerate_per_kw`] + * [`4`:`feerate_per_kw_funding`] + * [`2`:`num_additional_inputs`] + * [`num_additional_inputs*input_info`] + * [`2`:`num_outputs`] + * [`num_outputs*output_info`] + +#### Requirements + +The sending node: + - MUST have sent `open_channel2`. + - MUST send a `feerate_per_kw_funding` greater than the most recently + negotiated rate. + - MUST update the `channel_reserve_satoshis` to reflect the new input balance. + - MAY update the `feerate_per_kw`, the commitment transaction feerate. + - MAY include additional inputs. + - MAY set the `num_inputs` to zero. + - MUST transmit all outputs. + - MUST include at least one output with the `satoshis` set to zero, + to be used as the change output. + +The receiving node: + - MUST return an error if: + - the `init_rbf` message does not include a change output + e.g. an `output_info` entry with `satoshis` set to zero. + - the `feerate_per_kw_funding` is not greater than the previously + negotiated rate. + - MAY return an error if: + - the `channel_reserve_satoshis` is not acceptable. + +#### Rationale +The sending node's half of the funding transaction will be composed with +all of the previously relayed inputs plus the ones included here. + +All outputs must be transmitted in the `init_rbf` message, including +ones communicated previously. + +If a valid `funding_locked2` message is received in the middle of an +RBF workflow, the RBF attempt MUST be abandoned. + + +### Acknowledging Replace-By-Fee `ack_rbf` + +This message acknowledges the start of an RBF workflow. + +1. type: 63 (`ack_rbf`) +2. data: + * [`32`:`channel_id`] + +#### Requirements + +The receiving node: + - MUST respond with a `commitment_signed` message for the + updated funding transaction. + +#### Rationale + +Signals to receiving node to proceed with exchanging commitment signatures. + + ## Channel Close Nodes can negotiate a mutual close of the connection, which unlike a From a119f07d23eff998de376f7dcd8d028d395fa938 Mon Sep 17 00:00:00 2001 From: lisa neigut Date: Tue, 5 Feb 2019 16:45:35 -0800 Subject: [PATCH 03/44] peer-protocol: remove commitment_signed2 message --- 02-peer-protocol.md | 38 +------------------------------------- 1 file changed, 1 insertion(+), 37 deletions(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index 8738e4381..7f7e8921d 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -17,7 +17,6 @@ operation, and closing. * [The `open_channel2` Message](#the-open_channel2-message) * [The `accept_channel2` Message](#the-accept_channel2-message) * [The `funding_compose` Message](#the-funding_compose-message) - * [The `commitment_signed2` Message](#the-commitment_signed2-message) * [The `funding_signed2` Message](#the-funding_signed2-message) * [The `funding_locked2` Message](#the-funding_locked2-message) * [Kicking Off Replace-By-Fee: `init_rbf` Message](#kicking-off-replace-by-fee-init_rbf) @@ -603,7 +602,7 @@ The receiving node: to create the funding transaction, using `max_witness_len` for each `input_info` and `feerate_per_kw_funding` as specified in `open_channel2`. - - MUST send `commitment_signed2`. + - MUST send `commitment_signed`. #### Rationale @@ -645,41 +644,6 @@ change_satoshis = sum(inputs.satoshis) - est_tx_kw * feerate_per_kw_funding - su The channel funding output is not exchanged, as it can be derived independently. -#### The `commitment_signed2` Message - -This message exchanges the counterparty's signature for the -first commitment transaction, so it can broadcast the funding -transaction knowing that the funds can be redeemed. - -1. type: 59 (`commitment_signed2`) -2. data: - See [`commitment_signed`](#commiting-updates-so-far-commitment_signed). - -#### Requirements: - -The sending node: - - MUST derive the `channel_id` from the SHA256( - `open_channel2`.`revocation_basepoint`|`accept_channel2`.`revocation_` - `basepoint`) - - MUST set signature to the valid signature, using its `funding_pubkey` - for the initial commitment transaction, as defined in [BOLT #3](03-transactions.md#per-commitment-secret-requirements). - - MUST set `num_htlcs` to zero. - -A receiving node: - - if the `num_htlcs` is not zero: - - MUST fail the channel. - - if sent in response to a `funding_compose` message: - - MUST respond with a `commitment_signed` message. - - otherwise: - - MUST respond with a `funding_signed2` message. - -#### Rationale -There are no HTLC's yet, so the number must be zero. FIXME: use this -for `will_fund_for_food` bonds? - -Note that the channel id for `open_channel2` is fixed as the SHA256 of the -concatenated revocation points, and will not update. This allows stable -channel tracking across RBFs and splicing attempts. ### The `funding_signed2` Message From 5b1e873abb2ec85f9aac4b63c4cb89a356af44d2 Mon Sep 17 00:00:00 2001 From: lisa neigut Date: Tue, 5 Feb 2019 16:53:24 -0800 Subject: [PATCH 04/44] transactions: add calculations for dual funded funding_tx Add calculations for fees and change outputs for funding transactions that are created via the v2 channel establishment (ie dual funded) protocol. --- .aspell.en.pws | 3 +- 03-transactions.md | 74 ++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 76 insertions(+), 1 deletion(-) diff --git a/.aspell.en.pws b/.aspell.en.pws index 051ae5bc0..81e8db06a 100644 --- a/.aspell.en.pws +++ b/.aspell.en.pws @@ -126,9 +126,10 @@ subsubtype UTXO utxo scriptPubkey -counterparty's RBFs ack'd +scriptlen +ints htlc htlcs ChaCha diff --git a/03-transactions.md b/03-transactions.md index c72bd0981..4641c7413 100644 --- a/03-transactions.md +++ b/03-transactions.md @@ -383,6 +383,39 @@ A node: - if the resulting fee rate is too low: - MAY fail the channel. +## Channel Establishment v2 Funding Transaction Fees + +For channel establishment v2, fees are paid by the opener (the node that sends the +`open_channel` message). Change, if any, is paid to the opener's change address, a zero value +output in their output set. + +A change output of value `change_satoshis` will be included if there is enough satoshi +remaining to pay for its inclusion without decreasing the amount of available `funding_satoshis`. + + change_satoshis = sum(inputs.satoshis) - est_tx_fee + - sum(outputs.satoshis) - funding_satoshis + + +### Calculating `est_tx_fee` + +The fee for a v2 funding transaction is calculated in up to two rounds. + - if the `opener` provided a change address, first: + - MUST calculate the `est_tx_fee` as: + 1. Multiply (funding_transaction_weight + witness_weight) by `feerate_per_kw_funding` + and divide by 1000 (rounding down). + 2. Confirm that `change_satoshis` is greater than zero. + - if the no change address is provided or the `change_satoshis` is less than or + equal to zero: + - MUST calculate the `est_tx_fee` without the change output, if provided as: + 1. Multiply (funding_transaction_weight - change_output_weight + + witness_weight) by `feerate_per_kw_funding` and divide by 1000 (rounding down). + 2. As there is no change_output, any remaining `change_satoshis` will be added to the fee. + - if the `change_satoshis` is less than zero: + - `funding_satoshis` will be decreased by the difference + + +Computation details are included in [Appendix A, Expected Weight of the Funding Transaction](#appendix-a-expected-weights). + ## Commitment Transaction Construction This section ties the previous sections together to detail the @@ -606,6 +639,47 @@ 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: 80 bytes + - value: 8 bytes + - var_int: 1 byte + - script_sig: 71 bytes + - OP_2: 1 byte + - OP_DATA: 1 byte (pub_key_alice length) + - pub_key_alice: 33 bytes + - OP_DATA: 1 byte (pub_key_bob length) + - pub_key_bob: 33 bytes + - OP_2: 1 byte + - OP_CHECKMULTISIG: 1 byte + +Multiplying non-witness data by 4 results in a weight of: + + // funding_transaction = 80 + num_inputs * 40 + num_outputs * 8 + // + sum(scriptlen) + sum(var_ints) + funding_transaction_weight = 4 * funding_transaction + + witness_weight = sum(max_witness_len) + + overall_weight = funding_transaction_weight + witness_weight + + ## Expected Weight of the Commitment Transaction The *expected weight* of a commitment transaction is calculated as follows: From 4b146561716caea8d527ee042a4ecbfc20ff51e3 Mon Sep 17 00:00:00 2001 From: lisa neigut Date: Thu, 7 Mar 2019 14:44:21 -0800 Subject: [PATCH 05/44] funding transaction: add test scripts for dual funding Add some test vectors and concrete examples of funding transaction composition for v2 Channel Establishment (dual funded) transactions. --- .aspell.en.pws | 9 ++ 02-peer-protocol.md | 5 +- 03-transactions.md | 222 ++++++++++++++++++++++++++++++++++++++++++++ tools/spellcheck.sh | 2 +- 4 files changed, 235 insertions(+), 3 deletions(-) diff --git a/.aspell.en.pws b/.aspell.en.pws index 81e8db06a..4668dc57f 100644 --- a/.aspell.en.pws +++ b/.aspell.en.pws @@ -121,14 +121,23 @@ tlv rbf RBF accepter +Accepter's +accepter's subtype subsubtype +redeemScript UTXO utxo scriptPubkey +scriptPubKey +scriptPubKeys RBFs ack'd scriptlen +btc +sats +prevoutnum +prevtxid ints htlc htlcs diff --git a/02-peer-protocol.md b/02-peer-protocol.md index 7f7e8921d..03756ac42 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -509,8 +509,9 @@ If nodes have negotiated `option_dual_fund`: #### Rationale -`feerate_per_kw_funding`: fee rate that the opening node will pay -for the funding transaction. +`feerate_per_kw_funding` 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). ### The `accept_channel2` Message diff --git a/03-transactions.md b/03-transactions.md index 4641c7413..34d1dfae2 100644 --- a/03-transactions.md +++ b/03-transactions.md @@ -35,6 +35,7 @@ This details the exact format of on-chain transactions, which both sides need to * [Generation Tests](#generation-tests) * [Storage Tests](#storage-tests) * [Appendix E: Key Derivation Test Vectors](#appendix-e-key-derivation-test-vectors) + * [Appendix F: Dual Funded Transaction Test Vectors](#appendix-f-dual-funded-transaction-test-vectors) * [References](#references) * [Authors](#authors) @@ -1638,6 +1639,227 @@ All of them use the following secrets (and thus the derived points): # => 0xd09ffff62ddb2297ab000cc85bcb4283fdeb6aa052affbc9dddcf33b61078110 revocationprivkey: 0xd09ffff62ddb2297ab000cc85bcb4283fdeb6aa052affbc9dddcf33b61078110 +# Appendix F: 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): + +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 `funding_compose.input_info` (inputs 0+1 above): +``` + num_inputs: 2 + input_info:[ + { + satoshis: 250000000, + prevtxid: 4303ca8ff10c6c345b9299672a66f111c5b81ae027cc5b0d4d39d09c66b032b9, + prevoutnum: 0, + max_witness_len: 75, + scriptlen: 0, + script:null + },{ + satoshis: 250000000, + prevtxid: 4303ca8ff10c6c345b9299672a66f111c5b81ae027cc5b0d4d39d09c66b032b9, + prevoutnum: 1, + max_witness_len: 75, + scriptlen: 34, + script:0020fd89acf65485df89797d9ba7ba7a33624ac4452f00db08107f34257d33e5b946 + } + ] +``` + +Expected Accepter's `funding_compose.input_info` (inputs 2+3 above): +``` + num_inputs: 2 + input_info:[ + { + satoshis: 250000000, + prevtxid: 4303ca8ff10c6c345b9299672a66f111c5b81ae027cc5b0d4d39d09c66b032b9, + prevoutnum: 2, + max_witness_len: 109, + scriptlen: 0, + script:null + },{ + satoshis: 250000000, + prevtxid: 4303ca8ff10c6c345b9299672a66f111c5b81ae027cc5b0d4d39d09c66b032b9, + prevoutnum: 3, + max_witness_len: 109, + scriptlen: 22, + script: 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 +``` + +Unsigned Funding Transaction: +``` +0200000004b932b0669cd0394d0d5bcc27e01ab8c511f1662a6799925b346c0cf18fca03430000000000ffffffffb932b0669cd0394d0d5bcc27e01ab8c511f1662a6799925b346c0cf18fca03430100000000ffffffffb932b0669cd0394d0d5bcc27e01ab8c511f1662a6799925b346c0cf18fca03430200000000ffffffffb932b0669cd0394d0d5bcc27e01ab8c511f1662a6799925b346c0cf18fca03430300000000ffffffff03ec7f0100000000001600141ca1cca8855bad6bc1ea5436edd8cff10b7e448b00c2eb0b0000000016001444cb0c39f93ecc372b5851725bd29d865d333b106081ad2f00000000220020297b92c238163e820b82486084634b4846b86a3c658d87b9384192e6bea98ec500000000 +``` + +Signed Funding Transaction: +``` +02000000000104b932b0669cd0394d0d5bcc27e01ab8c511f1662a6799925b346c0cf18fca03430000000000ffffffffb932b0669cd0394d0d5bcc27e01ab8c511f1662a6799925b346c0cf18fca03430100000023220020fd89acf65485df89797d9ba7ba7a33624ac4452f00db08107f34257d33e5b946ffffffffb932b0669cd0394d0d5bcc27e01ab8c511f1662a6799925b346c0cf18fca03430200000000ffffffffb932b0669cd0394d0d5bcc27e01ab8c511f1662a6799925b346c0cf18fca03430300000017160014fbb4db9d85fba5e301f4399e3038928e44e37d32ffffffff03ec7f0100000000001600141ca1cca8855bad6bc1ea5436edd8cff10b7e448b00c2eb0b0000000016001444cb0c39f93ecc372b5851725bd29d865d333b106081ad2f00000000220020297b92c238163e820b82486084634b4846b86a3c658d87b9384192e6bea98ec5022068656c6c6f2074686572652c2074686973206973206120626974636f6e2121212782012088a820add57dfe5277079d069ca4ad4893c96de91f88ffb981fdc6a2a34d5336c66aff87022068656c6c6f2074686572652c2074686973206973206120626974636f6e2121212782012088a820add57dfe5277079d069ca4ad4893c96de91f88ffb981fdc6a2a34d5336c66aff8702473044022019b89938002518da7ad949986400a1c1d908c310fc045c0d5edffe3015becaeb02200e84a0c6530f4dd949dcef70f06eaf1896a00ddd6a4f99eae402fcc5d095f5510121034695f5b7864c580bf11f9f8cb1a94eb336f2ce9ef872d2ae1a90ee276c7724840247304402200d62dc4a1778939194b357e0797c5895534d1016e53e2c92829ba7203cfa1ec0022074aa90671275262bd971008a36272b6f41cb167b8bcb1b5fe1cd41340f21899f0121034695f5b7864c580bf11f9f8cb1a94eb336f2ce9ef872d2ae1a90ee276c77248400000000 +``` + +Weight Count: +``` + Max Witness Len: 368* + Non-Witness Data Byte Count: 337 + Total Weight: 368 + 337 * 4 = 1716 +``` +\* The signatures calculated for this transaction come to 71-bytes. + + +## Fee Calculation +Assuming a total of 10 Bitcoin inputs, 5btc from each peer. + +Opener's `funding_satoshi` is `499900000` (4.999btc), with a single +change output provided. +Accepter `funding_satoshi` is `300000000` (3btc), with `200000000` (2btc) +to their change address. + +Output1 is Opener's change address output. +Output2 is the Accepter's output. +Output3 is the Channel Funding output. + +All fractional fees are rounded down. + +### Example A: Positive Change Value +With `feerate_per_kw_funding` communicated at `1000 sats/kw`: + +``` + Fee: 0.00001716 btc + Output1: 0.00098284 btc + Output2: 2.0 btc + Output3: 7.999 btc + + Opener (A) Starting Balance: 4.999 btc + Accepter (B) Starting Balance: 3 btc +``` + +### Example B: Negative Change on Round 1, Negative Change on Round 2 +With `feerate_per_kw_funding` communicated at `100k sats/kw`: + +Round1: +``` + Fee: 0.00171600 btc + Output1: -0.00071600 btc + Output2: 2.0 btc + Output3: 7.999 btc +``` + +Round2, Re-calculate transaction, with Output1 removed: + +``` + Max Witness Len: 368 + Non-Witness Data Byte Count: 306 + Total Weight: 1592 +``` + +``` + Fee: 0.00159200 btc + Output2: 2.0 btc + Output3: 7.99840800 btc + + Opener (A) Starting Balance: 4.99850800 btc + Accepter (B) Starting Balance: 3 btc +``` + +### Example C: Negative Change on Round 1, Positive Change on Round 2 +With `feerate_per_kw_funding` communicated at `60k sats/kw`: + +Round1: +``` + Fee: 0.00102960 btc + Output1: -0.00002960 btc + Output2: 2.0 btc + Output3: 7.999 btc +``` + +Round2: +``` + Max Witness Len: 368 + Non-Witness Data Byte Count: 306 + Total Weight: 1592 +``` + +``` + Fee: 0.00095520 btc + Output2: 2.0 btc + Output3: 7.99904480 btc + + Opener (A) Starting Balance: 4.99904480 btc + Accepter (B) Starting Balance: 3 btc +``` + + # References # Authors diff --git a/tools/spellcheck.sh b/tools/spellcheck.sh index c11bc1723..09e0bfa07 100755 --- a/tools/spellcheck.sh +++ b/tools/spellcheck.sh @@ -68,7 +68,7 @@ do -e 's/[a-fA-F0-9]\{20,\}//g' \ -e 's/^ .*_htlcs//g' \ -e 's/ ln\(bc\|tb\)[0-9munp]*1[qpzry9x8gf2tvdw0s3jn54khce6mua7l]\+//g' \ - -e 's/ \(bc\|tb\)1[qpzry9x8gf2tvdw0s3jn54khce6mua7l]\+//g' \ + -e 's/ \(bc\|tb\|bcrt\)1[qpzry9x8gf2tvdw0s3jn54khce6mua7l]\+//g' \ -e 's/[123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz]\{20,\}//g' < $f | aspell -l en_US --home-dir ${homedir} list) if [ -n "$WORDS" ]; then echo Misspelled words in $f: $WORDS >&2 From 8cc738fbd97f4c5aa542ffb6534e63f5a7b65982 Mon Sep 17 00:00:00 2001 From: lisa neigut Date: Thu, 7 Mar 2019 14:45:36 -0800 Subject: [PATCH 06/44] dual funding: change confusing *- wording to [] Update *-puts to be termed [in|out]puts. --- 02-peer-protocol.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index 03756ac42..f28370bf3 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -583,10 +583,10 @@ The sending node: - MUST specify an output with value zero, which will be used as the change address. - if is the `accepter`: - - consider the `*put_limit` the total of `num_inputs` plus + - consider the `[in|out]put_limit` the total of `num_inputs` plus `num_outputs' from `funding_compose`, with minimum 2. - MUST NOT send `input_info`s or `output_info` which - exceeds the `*put_limit`. + exceeds the `[in|out]put_limit`. - MAY send zero inputs and/or outputs. The receiving node: From bc25b0cec1ac6ec7aea78e4a1e944526f1a83187 Mon Sep 17 00:00:00 2001 From: lisa neigut Date: Thu, 7 Mar 2019 14:54:28 -0800 Subject: [PATCH 07/44] dual funding: add prevtx_scriptpubkey to `funding_compose` Only non-malleable/segwit outputs can be used as inputs for a dual-funded transaction. --- .aspell.en.pws | 1 - 02-peer-protocol.md | 10 +++++----- 2 files changed, 5 insertions(+), 6 deletions(-) diff --git a/.aspell.en.pws b/.aspell.en.pws index 4668dc57f..87f3a0f90 100644 --- a/.aspell.en.pws +++ b/.aspell.en.pws @@ -121,7 +121,6 @@ tlv rbf RBF accepter -Accepter's accepter's subtype subsubtype diff --git a/02-peer-protocol.md b/02-peer-protocol.md index f28370bf3..d6ef313d6 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -613,14 +613,14 @@ asymmetry between the nodes, as both sides share their input utxo set. `satoshis` is the value of the input or output. -`prevtxid` and `prevtxoutnum` specify the input to be spent. -`prevtxid` is the hash of the transaction that this input is -specified in, `prevtxoutnum` its outpoint. +`prevtx_txid`, `prevtx_vout`, and `prevtx_scriptpubkey` specify the output +to be spent. `prevtx_txid` is the hash of the transaction that this input is +an output of; `prevtx_vout` its outpoint; and `prevtx_scriptpubkey` the +corresponding `scriptPubKey` value. `max_witness_len` is the total serialized length of the witness data that will be supplied (e.g. sizeof(varint) + -sizeof(witness) for each) in `funding_signed2`. Used to compose the funding -transaction. +sizeof(witness) for each) in `funding_signed2`. `input_info`.`script` is the scriptPubkey data for the input. NB: for native SegWit inputs (P2WPKH and P2WSH) inputs, the `script` field From edab8c829d8bdaf8e32447b7a6d03d0e62bab02c Mon Sep 17 00:00:00 2001 From: lisa neigut Date: Thu, 7 Mar 2019 15:23:29 -0800 Subject: [PATCH 08/44] dual funding: update language around change outputs Couple of changes. First, make the inclusion of a change output optional on a funding transaction. Second, we should be measuring the inclusion of the change output against the `dust_limit_satoshi`, not zero. Finally, update language to indicate that any fees that eat through the 'change' amount (if included) will be deduced from the sum of the parties' `funding_satoshis`, e.g. the accepter will pay for the remainder of the fees in the case that the `funding_satoshis` of the opener are completely consumed by fee costs. --- 02-peer-protocol.md | 21 ++++++++++++--------- 03-transactions.md | 39 +++++++++++++++++++++------------------ 2 files changed, 33 insertions(+), 27 deletions(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index d6ef313d6..65b3af565 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -580,7 +580,7 @@ The sending node: - MUST NOT include the channel funding output. - if is the `opener`: - MUST NOT send zero inputs (`num_inputs` cannot be zero). - - MUST specify an output with value zero, which will be used + - MAY specify an output with value zero, which will be used as the change address. - if is the `accepter`: - consider the `[in|out]put_limit` the total of `num_inputs` plus @@ -590,6 +590,8 @@ The sending node: - MAY send zero inputs and/or outputs. The receiving node: + - MAY fail the channel if: + - the fee cost of the proposed funding transaction is deemed exorbitant. - if the total `input_info`.`satoshis` is less than the total `output_info`.`satoshis` - MUST fail the channel. - if is the `opener`: @@ -626,7 +628,7 @@ sizeof(witness) for each) in `funding_signed2`. NB: for native SegWit inputs (P2WPKH and P2WSH) inputs, the `script` field will be empty. See [BIP141](https://github.com/bitcoin/bips/blob/master/bip-0141.mediawiki#examples). -The opening node must include at least one output with `satoshis` value +The opening node may include one output with `satoshis` value of zero. This will be used for change, or discarded if its value is be below `dust_limit_satoshis`. @@ -634,11 +636,14 @@ Change is calculated as the sum of the opener's `input_info`.`satoshis` minus the estimated funding transaction size times the `feerate_per_kw_funding` minus the `funding_satoshis` minus all other `output_info`.`satoshis`. If the `change_satoshis` value is negative, -the difference is subtracted from `funding_satoshis`. +the difference is subtracted from `funding_satoshis`. In the case where +the fee entirely consumes the value of the opener's `funding_satoshis`, +the remainder will be subtracted from the accepter's `funding_satoshis`. +Either peer may fail the channel open if the resulting fee payment is +deemed exorbitant. -``` -change_satoshis = sum(inputs.satoshis) - est_tx_kw * feerate_per_kw_funding - sum(outputs.satoshis) - funding_satoshis -``` +A more in-depth discussion of fee payment and change handling can be +found in [BOLT-3, v2 Funding Transaction Fees](03-transactions.md#channel-establishment-v2-funding-transaction-fees). `output_info`.`script` is the locking script for the output. @@ -753,13 +758,11 @@ The sending node: - MAY include additional inputs. - MAY set the `num_inputs` to zero. - MUST transmit all outputs. - - MUST include at least one output with the `satoshis` set to zero, + - MAY include at least one output with the `satoshis` set to zero, to be used as the change output. The receiving node: - MUST return an error if: - - the `init_rbf` message does not include a change output - e.g. an `output_info` entry with `satoshis` set to zero. - the `feerate_per_kw_funding` is not greater than the previously negotiated rate. - MAY return an error if: diff --git a/03-transactions.md b/03-transactions.md index 34d1dfae2..6b661ad8a 100644 --- a/03-transactions.md +++ b/03-transactions.md @@ -386,16 +386,17 @@ A node: ## Channel Establishment v2 Funding Transaction Fees -For channel establishment v2, fees are paid by the opener (the node that sends the -`open_channel` message). Change, if any, is paid to the opener's change address, a zero value -output in their output set. +For channel establishment v2, fees are paid by the opener (the node that +sends the `open_channel` message). Change, if any, is paid to the +opener's change address, a zero value output in their output set. -A change output of value `change_satoshis` will be included if there is enough satoshi -remaining to pay for its inclusion without decreasing the amount of available `funding_satoshis`. +A change output of value `change_satoshis` will be included if its +value is greater than `dust_limit_satoshis`. +``` change_satoshis = sum(inputs.satoshis) - est_tx_fee - - sum(outputs.satoshis) - funding_satoshis - + - sum(outputs.satoshis) - sum(funding_satoshis) +``` ### Calculating `est_tx_fee` @@ -404,18 +405,20 @@ The fee for a v2 funding transaction is calculated in up to two rounds. - MUST calculate the `est_tx_fee` as: 1. Multiply (funding_transaction_weight + witness_weight) by `feerate_per_kw_funding` and divide by 1000 (rounding down). - 2. Confirm that `change_satoshis` is greater than zero. - - if the no change address is provided or the `change_satoshis` is less than or - equal to zero: - - MUST calculate the `est_tx_fee` without the change output, if provided as: + 2. Confirm that `change_satoshis` is greater than `dust_limit_satoshis`. + - if no change address is provided or `change_satoshis` is less + than or equal to the negotiated `dust_limit_satoshis`: + - MUST calculate the `est_tx_fee` without the change output (if provided) as: 1. Multiply (funding_transaction_weight - change_output_weight + - witness_weight) by `feerate_per_kw_funding` and divide by 1000 (rounding down). - 2. As there is no change_output, any remaining `change_satoshis` will be added to the fee. - - if the `change_satoshis` is less than zero: - - `funding_satoshis` will be decreased by the difference - - -Computation details are included in [Appendix A, Expected Weight of the Funding Transaction](#appendix-a-expected-weights). + witness_weight) by `feerate_per_kw_funding` and divide by + 1000 (rounding down). + 2. As there is no change_output, any remaining `change_satoshis` + will be added to the funding output, and credited to the opener's + initial channel balance. + - if the resulting `change_satoshis` is less than zero: + - sum(`funding_satoshis`) will be decreased by the difference. + +Computation details are included in [Appendix A](#appendix-a-expected-weights) and [Appendix F, Dual Funded Transaction Test Vectors](#appendix-f-dual-funded-transaction-test-vectors). ## Commitment Transaction Construction From f68563c3902210a8cf90a9bfdbbd1ebf7d8af6c9 Mon Sep 17 00:00:00 2001 From: lisa neigut Date: Thu, 7 Mar 2019 15:26:45 -0800 Subject: [PATCH 09/44] dual funding: locking script -> scriptPubKey --- 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 65b3af565..870dc921e 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -645,7 +645,7 @@ deemed exorbitant. A more in-depth discussion of fee payment and change handling can be found in [BOLT-3, v2 Funding Transaction Fees](03-transactions.md#channel-establishment-v2-funding-transaction-fees). -`output_info`.`script` is the locking script for the output. +`output_info`.`script` is the scriptPubKey for the output. The channel funding output is not exchanged, as it can be derived independently. From dbf14a6b959b0a820c3d3f74276b6f0d7fc1b41d Mon Sep 17 00:00:00 2001 From: lisa neigut Date: Tue, 2 Apr 2019 16:21:34 -0700 Subject: [PATCH 10/44] dual funding: use varint for tlv length --- 02-peer-protocol.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index 870dc921e..1ce72b020 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -488,7 +488,7 @@ This message initiates the v2 channel establishment workflow. * [`33`:`htlc_basepoint`] * [`33`:`first_per_commitment_point`] * [`1`:`channel_flags`] - * [`2`:`opening_tlv_len`] + * [`var_int`:`opening_tlv_len`] * [`opening_tlv_len`:`opening_tlv`] @@ -535,7 +535,7 @@ acceptance of the new channel. * [`33`:`delayed_payment_basepoint`] * [`33`:`htlc_basepoint`] * [`33`:`first_per_commitment_point`] - * [`2`:`opening_tlv_len`] + * [`var_int`:`opening_tlv_len`] * [`opening_tlv_len`:`opening_tlv`] Rationale and Requirements are the same as listed above, From 50a296417e6aae5e2683b2a28c2d3149489ef971 Mon Sep 17 00:00:00 2001 From: lisa neigut Date: Thu, 25 Apr 2019 11:35:11 -0700 Subject: [PATCH 11/44] fixup link --- 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 1ce72b020..70fa97214 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -64,7 +64,7 @@ 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 +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, From 8b89f2aca09c145780d839d077897084de474eca Mon Sep 17 00:00:00 2001 From: lisa neigut Date: Mon, 29 Apr 2019 16:43:29 -0700 Subject: [PATCH 12/44] transactions: add non input-output weight for funding transaction The weight calculation for the funding transaction for v2 channel establishment was missing the count of bytes in the transaction header e.g. locktime, version, input/output counts and segwit marker/version fields. This updates it to include them. --- 03-transactions.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/03-transactions.md b/03-transactions.md index 6b661ad8a..4adc876f1 100644 --- a/03-transactions.md +++ b/03-transactions.md @@ -675,9 +675,11 @@ The *expected weight* of a funding transaction is calculated as follows: 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 = 80 + num_inputs * 40 + num_outputs * 8 - // + sum(scriptlen) + sum(var_ints) - funding_transaction_weight = 4 * funding_transaction + // + sum(scriptlen) + sum(var_ints) + + funding_transaction_weight = 4 * (funding_transaction + transaction_fields) + segwit_fields witness_weight = sum(max_witness_len) From 3604294015a3b8f84d8b1a0be9d6245cf32f07ea Mon Sep 17 00:00:00 2001 From: lisa neigut Date: Mon, 29 Apr 2019 17:17:40 -0700 Subject: [PATCH 13/44] fixup: rename 'funding_tx_id' to 'funding_txid' Puts it inline with namings elsewhere. --- 02-peer-protocol.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index 70fa97214..a0164b20f 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -703,7 +703,7 @@ concludes the channel establishment workflow. 1. type: 61 (`funding_locked2`) 2. data: * [`32`:`channel_id`] - * [`32`:`funding_tx_id`] + * [`32`:`funding_txid`] * [`33`:`next_per_commitment_point`] See [`funding_locked`](#the-funding_locked-message) for Requirements and @@ -712,13 +712,13 @@ Rationale, with the following addition. #### Requirements The receiving node: - - if the `funding_tx_id` does not match the `funding_tx_id` of the funding + - if the `funding_txid` does not match the `funding_txid` of the funding transaction it observed: - MUST fail the channel. #### Rationale -`funding_tx_id` is the transaction hash for the funding transaction that +`funding_txid` is the transaction hash for the funding transaction that is locked in. This is to confirm that both nodes are using the same transaction for funding. (It is possible for them to diverge in the unlikely case of a network partition concurrent with an RBF attempt.) From 4b5be7b6b0617b4e71ffcfdc7ad0c647dee54490 Mon Sep 17 00:00:00 2001 From: lisa neigut Date: Mon, 29 Apr 2019 17:18:13 -0700 Subject: [PATCH 14/44] fixup: reorder `push_msat` so it's same as original `open_channel` keep ordering the same for fields btw `open_channel` and `open_channel2` --- 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 a0164b20f..5201f1530 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -471,8 +471,8 @@ This message initiates the v2 channel establishment workflow. 2. data: * [`32`:`chain_hash`] * [`32`:`temporary_channel_id`] - * [`8`:`push_msat`] * [`8`:`funding_satoshis`] + * [`8`:`push_msat`] * [`8`:`dust_limit_satoshis`] * [`8`:`max_htlc_value_in_flight_msat`] * [`8`:`channel_reserve_satoshis`] From 0928b7359718b19622f3d4a7ba64b11f5c48e8fe Mon Sep 17 00:00:00 2001 From: lisa neigut Date: Mon, 29 Apr 2019 17:18:56 -0700 Subject: [PATCH 15/44] fixup: include prev_scriptpubkey in example inputs Since a `prev_scriptpubkey` field was added, include it in example in the transaction Appendix. --- 03-transactions.md | 30 +++++++++++++++++++----------- 1 file changed, 19 insertions(+), 11 deletions(-) diff --git a/03-transactions.md b/03-transactions.md index 4adc876f1..6c75ea28c 100644 --- a/03-transactions.md +++ b/03-transactions.md @@ -1702,18 +1702,22 @@ Expected Opener's `funding_compose.input_info` (inputs 0+1 above): input_info:[ { satoshis: 250000000, - prevtxid: 4303ca8ff10c6c345b9299672a66f111c5b81ae027cc5b0d4d39d09c66b032b9, - prevoutnum: 0, + prev_txid: 4303ca8ff10c6c345b9299672a66f111c5b81ae027cc5b0d4d39d09c66b032b9, + prev_vout: 0, + prev_scriptpubkey_len: 34, + prev_scriptpubkey: 0020fd89acf65485df89797d9ba7ba7a33624ac4452f00db08107f34257d33e5b946, max_witness_len: 75, scriptlen: 0, - script:null + script: null },{ satoshis: 250000000, - prevtxid: 4303ca8ff10c6c345b9299672a66f111c5b81ae027cc5b0d4d39d09c66b032b9, - prevoutnum: 1, + prev_txid: 4303ca8ff10c6c345b9299672a66f111c5b81ae027cc5b0d4d39d09c66b032b9, + prev_vout: 1, + prev_scriptpubkey_len: 23, + prev_scriptpubkey: a9146a235d064786b49e7043e4a042d4cc429f7eb69487, max_witness_len: 75, scriptlen: 34, - script:0020fd89acf65485df89797d9ba7ba7a33624ac4452f00db08107f34257d33e5b946 + script: 0020fd89acf65485df89797d9ba7ba7a33624ac4452f00db08107f34257d33e5b946 } ] ``` @@ -1724,15 +1728,19 @@ Expected Accepter's `funding_compose.input_info` (inputs 2+3 above): input_info:[ { satoshis: 250000000, - prevtxid: 4303ca8ff10c6c345b9299672a66f111c5b81ae027cc5b0d4d39d09c66b032b9, - prevoutnum: 2, + prev_txid: 4303ca8ff10c6c345b9299672a66f111c5b81ae027cc5b0d4d39d09c66b032b9, + prev_vout: 2, + prev_scriptpubkey_len: 22, + prev_scriptpubkey: 0014fbb4db9d85fba5e301f4399e3038928e44e37d32, max_witness_len: 109, scriptlen: 0, - script:null + script: null },{ satoshis: 250000000, - prevtxid: 4303ca8ff10c6c345b9299672a66f111c5b81ae027cc5b0d4d39d09c66b032b9, - prevoutnum: 3, + prev_txid: 4303ca8ff10c6c345b9299672a66f111c5b81ae027cc5b0d4d39d09c66b032b9, + prev_vout: 3, + prev_scriptpubkey_len: 23, + prev_scriptpubkey: a9147ecd1b519326bc13b0ec716e469b58ed02b112a087, max_witness_len: 109, scriptlen: 22, script: 0014fbb4db9d85fba5e301f4399e3038928e44e37d32 From 895f94514ac9ce35acb47e461dbb9e7144f5444a Mon Sep 17 00:00:00 2001 From: lisa neigut Date: Mon, 29 Apr 2019 19:23:27 -0700 Subject: [PATCH 16/44] dual-funding: have the opener send the `contrib_count` at open simplifies the funding and reserve calculations later if the accepter knows at the outset how many inputs they'll be allowed to contribute to the funding transaction --- 02-peer-protocol.md | 25 +++++++++++++++++++++---- 1 file changed, 21 insertions(+), 4 deletions(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index 5201f1530..b56d01613 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -479,6 +479,7 @@ This message initiates the v2 channel establishment workflow. * [`8`:`htlc_minimum_msat`] * [`4`:`feerate_per_kw`] * [`4`:`feerate_per_kw_funding`] + * [`2`: `contrib_count`] * [`2`:`to_self_delay`] * [`2`:`max_accepted_htlcs`] * [`33`:`funding_pubkey`] @@ -506,6 +507,8 @@ Rationale and Requirements are the same as for [`open_channel`](#the-open_channe If nodes have negotiated `option_dual_fund`: - the opening node: - MUST not send `open_channel` + - MUST set the `contrib_count` to the total of `num_inputs` plus + `num_outputs' that will be included in `funding_compose`, with minimum 2. #### Rationale @@ -513,6 +516,9 @@ If nodes have negotiated `option_dual_fund`: 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). +`contrib_count` is the total number of inputs and outputs that the opener +will contribute to the funding transaction. This is sent so that the +accepter can configure appropriate funding values for their `accept_channel2` response. ### The `accept_channel2` Message @@ -522,6 +528,7 @@ acceptance of the new channel. 1. type: 57 (`accept_channel2`) 2. data: * [`32`:`temporary_channel_id`] + * [`8`:`funding_satoshis`] * [`8`:`dust_limit_satoshis`] * [`8`:`max_htlc_value_in_flight_msat`] * [`8`:`channel_reserve_satoshis`] @@ -539,8 +546,18 @@ acceptance of the new channel. * [`opening_tlv_len`:`opening_tlv`] Rationale and Requirements are the same as listed above, -for [`accept_channel`](#the-accept_channel-message) +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 +Accepter sends their `funding_satoshi` value here instead of allowing the opener to derive +it from their `funding_compose` response so that the opener can decide whether +to complete the opening without exposing their output set. ### The `funding_compose` Message @@ -583,10 +600,10 @@ The sending node: - MAY specify an output with value zero, which will be used as the change address. - if is the `accepter`: - - consider the `[in|out]put_limit` the total of `num_inputs` plus + - consider the `contrib_count` the total of `num_inputs` plus `num_outputs' from `funding_compose`, with minimum 2. - MUST NOT send `input_info`s or `output_info` which - exceeds the `[in|out]put_limit`. + exceeds the `contrib_count` limit. - MAY send zero inputs and/or outputs. The receiving node: @@ -597,7 +614,7 @@ The receiving node: - if is the `opener`: - MUST fail the channel if: - the total count of `input_info`s and `output_info`s is greater than - the `[in|out]put_limit`. + the `contrib_count`. - if has not yet sent a `funding_compose`: - MUST send its `funding_compose` message. - otherwise: From d2de360befd7267d926029a3f34c1a4ab7007dd9 Mon Sep 17 00:00:00 2001 From: lisa neigut Date: Mon, 29 Apr 2019 19:24:34 -0700 Subject: [PATCH 17/44] dual-funding: move the `channel_reserve_satoshi` field put `channel_reserve_satoshi` exchange into the `funding_compose` message, so that it can reflect the full channel balance, and not just the opener's funding. --- 02-peer-protocol.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index b56d01613..b1e2a78d6 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -475,7 +475,6 @@ This message initiates the v2 channel establishment workflow. * [`8`:`push_msat`] * [`8`:`dust_limit_satoshis`] * [`8`:`max_htlc_value_in_flight_msat`] - * [`8`:`channel_reserve_satoshis`] * [`8`:`htlc_minimum_msat`] * [`4`:`feerate_per_kw`] * [`4`:`feerate_per_kw_funding`] @@ -531,7 +530,6 @@ acceptance of the new channel. * [`8`:`funding_satoshis`] * [`8`:`dust_limit_satoshis`] * [`8`:`max_htlc_value_in_flight_msat`] - * [`8`:`channel_reserve_satoshis`] * [`8`:`htlc_minimum_msat`] * [`4`:`minimum_depth`] * [`2`:`to_self_delay`] @@ -567,6 +565,7 @@ information necessary to compose the funding transaction. 1. type: 58 (`funding_compose`) 2. data: * [`32`:`temporary_channel_id`] + * [`8`:`channel_reserve_satoshis`] * [`2`:`num_inputs`] * [`num_inputs*input_info`] * [`2`:`num_outputs`] @@ -630,6 +629,9 @@ Each node must have a complete set of the transaction inputs and outputs, to derive the funding transaction. This avoids information asymmetry between the nodes, as both sides share their input utxo set. +`channel_reserve_satoshis` is the minimum balance that the other node +must reserve for itself, out of the total channel balance. + `satoshis` is the value of the input or output. `prevtx_txid`, `prevtx_vout`, and `prevtx_scriptpubkey` specify the output From 25ca2b17700bcea08b6e5ea92c08d844d5e6db86 Mon Sep 17 00:00:00 2001 From: lisa neigut Date: Fri, 3 May 2019 18:44:04 -0700 Subject: [PATCH 18/44] dual-funding: add requirement for zero htlc's in commit_sig the commitment_signed message must not contain any htlc's during channel establishment. --- 02-peer-protocol.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index b1e2a78d6..5130f5c1d 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -669,6 +669,23 @@ found in [BOLT-3, v2 Funding Transaction Fees](03-transactions.md#channel-establ The channel funding output is not exchanged, as it can be derived independently. +### The `commitment_signed` Message + +Rationale and Requirements are the same as listed above, +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 channel. + +#### Rationale + +The first commitment transaction has no HTLC's in it. ### The `funding_signed2` Message From bcbf7c7023e0cf444a1a1fdbe899657ff9e9af2f Mon Sep 17 00:00:00 2001 From: lisa neigut Date: Fri, 3 May 2019 18:45:18 -0700 Subject: [PATCH 19/44] dual-funding: fixup, move the wording to the right place --- 02-peer-protocol.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index 5130f5c1d..49806a6ab 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -606,11 +606,11 @@ The sending node: - MAY send zero inputs and/or outputs. The receiving node: - - MAY fail the channel if: - - the fee cost of the proposed funding transaction is deemed exorbitant. - if the total `input_info`.`satoshis` is less than the total `output_info`.`satoshis` - MUST fail the channel. - if is the `opener`: + - MAY fail the channel if: + - the fee cost of the proposed funding transaction is deemed exorbitant. - MUST fail the channel if: - the total count of `input_info`s and `output_info`s is greater than the `contrib_count`. From e5af0d5cd084d65fc80f22c401d02c43fb730935 Mon Sep 17 00:00:00 2001 From: lisa neigut Date: Fri, 3 May 2019 18:45:47 -0700 Subject: [PATCH 20/44] dual-funding: add note about failing if contrib_count is wrong since we now require the opener to 'pre-send' the total number of inputs and outputs that they're going to be including in the funding tx, if the number of actual inputs and outputs that they send is less than this, we can fail the channel. we do this because we base our input selection on the number of inputs and outputs that they send. having a lower number means that we might be in violation of the rule so we fail this requirement also --- 02-peer-protocol.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index 49806a6ab..3922a85ee 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -608,6 +608,10 @@ The sending node: The receiving node: - if the total `input_info`.`satoshis` is less than the total `output_info`.`satoshis` - MUST fail the channel. + - if is the `accepter`: + - MAY fail the channel if: + - the total count of `input_infos` and `output_info`s is not equal to the + `contrib_count`. - if is the `opener`: - MAY fail the channel if: - the fee cost of the proposed funding transaction is deemed exorbitant. From e067a61655fa27b0c756a1757112ccacedf7271c Mon Sep 17 00:00:00 2001 From: lisa neigut Date: Fri, 3 May 2019 18:48:21 -0700 Subject: [PATCH 21/44] dual-funding: fixup egregious weight calculation in Appendix fixes incorrect calculation of funding output's weight. --- .aspell.en.pws | 1 + 03-transactions.md | 15 +++++---------- 2 files changed, 6 insertions(+), 10 deletions(-) diff --git a/.aspell.en.pws b/.aspell.en.pws index 87f3a0f90..d4444c74a 100644 --- a/.aspell.en.pws +++ b/.aspell.en.pws @@ -400,3 +400,4 @@ IRC bitmasks CSPRNG workflow +PUSHDATA diff --git a/03-transactions.md b/03-transactions.md index 6c75ea28c..44febe7bb 100644 --- a/03-transactions.md +++ b/03-transactions.md @@ -661,23 +661,18 @@ The *expected weight* of a funding transaction is calculated as follows: - var_int: ? bytes (dependent on `scriptlen`) - script_sig: `scriptlen` - funding_output: 80 bytes + funding_output: 43 bytes - value: 8 bytes - var_int: 1 byte - - script_sig: 71 bytes - - OP_2: 1 byte - - OP_DATA: 1 byte (pub_key_alice length) - - pub_key_alice: 33 bytes - - OP_DATA: 1 byte (pub_key_bob length) - - pub_key_bob: 33 bytes - - OP_2: 1 byte - - OP_CHECKMULTISIG: 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 = 80 + num_inputs * 40 + num_outputs * 8 + // funding_transaction = 43 + num_inputs * 40 + num_outputs * 8 // + sum(scriptlen) + sum(var_ints) + funding_transaction_weight = 4 * (funding_transaction + transaction_fields) + segwit_fields From 4db44fcad99c0f0095e2c9bc5645298d9455d687 Mon Sep 17 00:00:00 2001 From: lisa neigut Date: Mon, 6 May 2019 12:48:55 -0700 Subject: [PATCH 22/44] dual-funding: note about when we switch from temp to 'real' channel_id for v2 channel establishment we switch from the temporary channel_id to the channel_id derived from the funding_txid after both funding_compose messages have been exchanged, as at this point both opener/accepter have the ability to derive the funding_txid which is required for the channel_id. --- 02-peer-protocol.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index 3922a85ee..ccf529993 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -691,6 +691,9 @@ The receiving node: The first commitment transaction has no HTLC's in it. +Note that the `commitment_signed` message will include the `channel_id` derived from +the `funding_txid`, instead of the `temporary_node_id`. + ### The `funding_signed2` Message This message exchanges the witness data for the inputs that were From d8f3a11e6def35018ebf4d84422c66c0cec9d71d Mon Sep 17 00:00:00 2001 From: lisa neigut Date: Mon, 24 Jun 2019 11:09:34 -0700 Subject: [PATCH 23/44] fixup: spacing error with contrib-count --- 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 ccf529993..6f4717224 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -478,7 +478,7 @@ This message initiates the v2 channel establishment workflow. * [`8`:`htlc_minimum_msat`] * [`4`:`feerate_per_kw`] * [`4`:`feerate_per_kw_funding`] - * [`2`: `contrib_count`] + * [`2`:`contrib_count`] * [`2`:`to_self_delay`] * [`2`:`max_accepted_htlcs`] * [`33`:`funding_pubkey`] From 14b55f9c1f81e6a32357db4a78b9518719bae312 Mon Sep 17 00:00:00 2001 From: lisa neigut Date: Thu, 11 Jul 2019 11:17:53 -0500 Subject: [PATCH 24/44] dual-funding: remove the funding_locked2 message On further consideration, the channel_id encapsulates all of the necessary info to determine which funding transaction attempt that the funding_locked message pertains to --- 02-peer-protocol.md | 38 ++++---------------------------------- 1 file changed, 4 insertions(+), 34 deletions(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index 6f4717224..c5cdb6f88 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -18,7 +18,6 @@ operation, and closing. * [The `accept_channel2` Message](#the-accept_channel2-message) * [The `funding_compose` Message](#the-funding_compose-message) * [The `funding_signed2` Message](#the-funding_signed2-message) - * [The `funding_locked2` Message](#the-funding_locked2-message) * [Kicking Off Replace-By-Fee: `init_rbf` Message](#kicking-off-replace-by-fee-init_rbf) * [Acknowledging Replace-By-Fee `ack_rbf` Message](#acknowledging-replace-by-fee-ack_rbf) * [Channel Close](#channel-close) @@ -457,8 +456,8 @@ The protocol is also expanded to include a mechanism for initiating RBF. | | |--(a)--- init_rbf ----------->| | ----| |<-(b)--- ack_rbf ------------| | | | | | - | |--(9)--- funding_locked2 ---->| | - | |<-(10)-- funding_locked2 -----| | + | |--(9)--- funding_locked ----->| | + | |<-(10)-- funding_locked ------| | +-------+ +-------+ - where node A is 'opener' and node B is 'accepter' @@ -737,41 +736,12 @@ The receiving node: Exchanging witness data allows both sides to broadcast the funding transaction. -### The `funding_locked2` Message - -This message signals that the funding transaction has reached the appropriate -chain depth and is considered locked. An exchange of `funding_locked2` messages -concludes the channel establishment workflow. - -1. type: 61 (`funding_locked2`) -2. data: - * [`32`:`channel_id`] - * [`32`:`funding_txid`] - * [`33`:`next_per_commitment_point`] - -See [`funding_locked`](#the-funding_locked-message) for Requirements and -Rationale, with the following addition. - -#### Requirements - -The receiving node: - - if the `funding_txid` does not match the `funding_txid` of the funding - transaction it observed: - - MUST fail the channel. - -#### Rationale - -`funding_txid` is the transaction hash for the funding transaction that -is locked in. This is to confirm that both nodes are using the same -transaction for funding. (It is possible for them to diverge in the unlikely -case of a network partition concurrent with an RBF attempt.) - ### Kicking Off Replace-By-Fee: `init_rbf` This message initiates the flow to create a replacement funding transaction. It is sent by the channel opener, after the funding -transaction has been broadcast but before a `funding_locked2` message +transaction has been broadcast but before a `funding_locked` message is exchanged. Once an `init_rbf` message has been successfully ack'd by the accepter @@ -818,7 +788,7 @@ all of the previously relayed inputs plus the ones included here. All outputs must be transmitted in the `init_rbf` message, including ones communicated previously. -If a valid `funding_locked2` message is received in the middle of an +If a valid `funding_locked` message is received in the middle of an RBF workflow, the RBF attempt MUST be abandoned. From 363ca15a2f34f064fc375ab43c355f0d65a21d38 Mon Sep 17 00:00:00 2001 From: lisa neigut Date: Thu, 11 Jul 2019 11:19:18 -0500 Subject: [PATCH 25/44] fixup: update types to new represenations --- 02-peer-protocol.md | 152 ++++++++++++++++++++++---------------------- 1 file changed, 75 insertions(+), 77 deletions(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index c5cdb6f88..7b8a19e61 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -468,35 +468,34 @@ This message initiates the v2 channel establishment workflow. 1. type: 56 (`open_channel2`) 2. data: - * [`32`:`chain_hash`] - * [`32`:`temporary_channel_id`] - * [`8`:`funding_satoshis`] - * [`8`:`push_msat`] - * [`8`:`dust_limit_satoshis`] - * [`8`:`max_htlc_value_in_flight_msat`] - * [`8`:`htlc_minimum_msat`] - * [`4`:`feerate_per_kw`] - * [`4`:`feerate_per_kw_funding`] - * [`2`:`contrib_count`] - * [`2`:`to_self_delay`] - * [`2`:`max_accepted_htlcs`] - * [`33`:`funding_pubkey`] - * [`33`:`revocation_basepoint`] - * [`33`:`payment_basepoint`] - * [`33`:`delayed_payment_basepoint`] - * [`33`:`htlc_basepoint`] - * [`33`:`first_per_commitment_point`] - * [`1`:`channel_flags`] - * [`var_int`:`opening_tlv_len`] - * [`opening_tlv_len`:`opening_tlv`] - - -1. tlv: `opening_tlv` + * [`chain_hash`:`chain_hash`] + * [`32*byte`:`temporary_channel_id`] + * [`u64`:`funding_satoshis`] + * [`u64`:`push_msat`] + * [`u64`:`dust_limit_satoshis`] + * [`u64`:`max_htlc_value_in_flight_msat`] + * [`u64`:`htlc_minimum_msat`] + * [`u32`:`feerate_per_kw`] + * [`u32`:`feerate_per_kw_funding`] + * [`u16`:`contrib_count`] + * [`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`] + * [`byte`:`channel_flags`] + * [`opening_tlvs`:`opening_tlv`] + + +1. tlvs: `opening_tlvs` 2. types: 1. type: 1 (`option_upfront_shutdown_script`) 2. data: - * [`2`:`shutdown_len`] - * [`shutdown_len`:`shutdown_scriptpubkey`] + * [`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: @@ -525,22 +524,21 @@ acceptance of the new channel. 1. type: 57 (`accept_channel2`) 2. data: - * [`32`:`temporary_channel_id`] - * [`8`:`funding_satoshis`] - * [`8`:`dust_limit_satoshis`] - * [`8`:`max_htlc_value_in_flight_msat`] - * [`8`:`htlc_minimum_msat`] - * [`4`:`minimum_depth`] - * [`2`:`to_self_delay`] - * [`2`:`max_accepted_htlcs`] - * [`33`:`funding_pubkey`] - * [`33`:`revocation_basepoint`] - * [`33`:`payment_basepoint`] - * [`33`:`delayed_payment_basepoint`] - * [`33`:`htlc_basepoint`] - * [`33`:`first_per_commitment_point`] - * [`var_int`:`opening_tlv_len`] - * [`opening_tlv_len`:`opening_tlv`] + * [`32*byte`:`temporary_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`] + * [`opening_tlv`:`opening_tlv`] Rationale and Requirements are the same as listed above, for [`accept_channel`](#the-accept_channel-message) with the following additions. @@ -563,29 +561,29 @@ information necessary to compose the funding transaction. 1. type: 58 (`funding_compose`) 2. data: - * [`32`:`temporary_channel_id`] - * [`8`:`channel_reserve_satoshis`] - * [`2`:`num_inputs`] - * [`num_inputs*input_info`] - * [`2`:`num_outputs`] - * [`num_outputs*output_info`] + * [`32*byte`:`temporary_channel_id`] + * [`u64`:`channel_reserve_satoshis`] + * [`u16`:`num_inputs`] + * [`num_inputs*input_info`:`input_info`] + * [`u16`:`num_outputs`] + * [`num_outputs*output_info`:`output_info`] 1. subtype: `input_info` 2. data: - * [`8`:`satoshis`] - * [`32`:`prevtx_txid`] - * [`4`:`prevtx_vout`] - * [`2`:`prevtx_scriptpubkey_len`] - * [`prevtx_scriptpubkey_len`:`prevtx_scriptpubkey`] - * [`2`:`max_witness_len`] - * [`2`:`scriptlen`] - * [`scriptlen`:`script`] + * [`u64`:`satoshis`] + * [`sha256`:`prevtx_txid`] + * [`u32`:`prevtx_vout`] + * [`u16`:`prevtx_scriptpubkey_len`] + * [`prevtx_scriptpubkey_len*byte`:`prevtx_scriptpubkey`] + * [`u16`:`max_witness_len`] + * [`u16`:`scriptlen`] + * [`scriptlen*byte`:`script`] 1. subtype: `output_info` 2. data: - * [`8`:`satoshis`] - * [`2`:`scriptlen`] - * [`scriptlen`:`script`] + * [`u64`:`satoshis`] + * [`u16`:`scriptlen`] + * [`scriptlen*byte`:`script`] #### Requirements @@ -700,19 +698,19 @@ originally sent in the `funding_compose` message. 1. type: 60 (`funding_signed2`) 2. data: - * [`32`:`channel_id`] - * [`2`:`num_witnesses`] - * [`num_witnesses*witness_stack`] + * [`channel_id`:`channel_id`] + * [`u16`:`num_witnesses`] + * [`num_witnesses*witness_stack`:`witness_stack`] 1. subtype: `witness_stack` 2. data: - * [`2`:`num_input_witness`] - * [`num_input_witness*witness_element`] + * [`u16`:`num_input_witness`] + * [`num_input_witness*witness_element`:`witness_element`] -1. subsubtype: `witness_element` +1. subtype: `witness_element` 2. data: - * [`2`:`len`] - * [`len`:`witness`] + * [`u16`:`len`] + * [`len*byte`:`witness`] #### Requirements The sending node: @@ -750,15 +748,15 @@ indicated above. 1. type: 62 (`init_rbf`) 2. data: - * [`32`:`channel_id`] - * [`8`:`funding_satoshis`] - * [`8`:`channel_reserve_satoshis`] - * [`4`:`feerate_per_kw`] - * [`4`:`feerate_per_kw_funding`] - * [`2`:`num_additional_inputs`] - * [`num_additional_inputs*input_info`] - * [`2`:`num_outputs`] - * [`num_outputs*output_info`] + * [`channel_id`:`channel_id`] + * [`u64`:`funding_satoshis`] + * [`u64`:`channel_reserve_satoshis`] + * [`u32`:`feerate_per_kw`] + * [`u32`:`feerate_per_kw_funding`] + * [`u16`:`num_additional_inputs`] + * [`num_additional_inputs*input_info`:`input_info`] + * [`u16`:`num_outputs`] + * [`num_outputs*output_info`:`output_info`] #### Requirements @@ -798,7 +796,7 @@ This message acknowledges the start of an RBF workflow. 1. type: 63 (`ack_rbf`) 2. data: - * [`32`:`channel_id`] + * [`channel_id`:`channel_id`] #### Requirements From 04c9fd2fd13bc27a2e4e4a373029ea64edd60e9e Mon Sep 17 00:00:00 2001 From: lisa neigut Date: Mon, 15 Jul 2019 16:53:28 -0500 Subject: [PATCH 26/44] fixup: rename 'satoshis' so our checks work --- 02-peer-protocol.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index 7b8a19e61..672d22ddf 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -570,7 +570,7 @@ information necessary to compose the funding transaction. 1. subtype: `input_info` 2. data: - * [`u64`:`satoshis`] + * [`u64`:`input_satoshis`] * [`sha256`:`prevtx_txid`] * [`u32`:`prevtx_vout`] * [`u16`:`prevtx_scriptpubkey_len`] @@ -581,7 +581,7 @@ information necessary to compose the funding transaction. 1. subtype: `output_info` 2. data: - * [`u64`:`satoshis`] + * [`u64`:`output_satoshis`] * [`u16`:`scriptlen`] * [`scriptlen*byte`:`script`] From 65ee3dbe963d86ba65eb20147e739f009904ac39 Mon Sep 17 00:00:00 2001 From: lisa neigut Date: Mon, 15 Jul 2019 16:53:58 -0500 Subject: [PATCH 27/44] revert later: make opener->funder so BOLT checks pass --- 03-transactions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/03-transactions.md b/03-transactions.md index 44febe7bb..b564c3a42 100644 --- a/03-transactions.md +++ b/03-transactions.md @@ -943,7 +943,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). From eb7d5170a83cc5b9fb2e179bdba7e09a8eeb0e77 Mon Sep 17 00:00:00 2001 From: lisa neigut Date: Tue, 20 Aug 2019 19:06:51 -0500 Subject: [PATCH 28/44] fixup length count and update transaction with new data --- 03-transactions.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/03-transactions.md b/03-transactions.md index b564c3a42..fa0f581a7 100644 --- a/03-transactions.md +++ b/03-transactions.md @@ -1768,19 +1768,19 @@ address: bcrt1q99ae9s3czclgyzuzfpsggc6tfprts63uvkxc0wfcgxfwd04f3mzs3asq6l Unsigned Funding Transaction: ``` -0200000004b932b0669cd0394d0d5bcc27e01ab8c511f1662a6799925b346c0cf18fca03430000000000ffffffffb932b0669cd0394d0d5bcc27e01ab8c511f1662a6799925b346c0cf18fca03430100000000ffffffffb932b0669cd0394d0d5bcc27e01ab8c511f1662a6799925b346c0cf18fca03430200000000ffffffffb932b0669cd0394d0d5bcc27e01ab8c511f1662a6799925b346c0cf18fca03430300000000ffffffff03ec7f0100000000001600141ca1cca8855bad6bc1ea5436edd8cff10b7e448b00c2eb0b0000000016001444cb0c39f93ecc372b5851725bd29d865d333b106081ad2f00000000220020297b92c238163e820b82486084634b4846b86a3c658d87b9384192e6bea98ec500000000 +0200000004b932b0669cd0394d0d5bcc27e01ab8c511f1662a6799925b346c0cf18fca03430000000000ffffffffb932b0669cd0394d0d5bcc27e01ab8c511f1662a6799925b346c0cf18fca03430100000000ffffffffb932b0669cd0394d0d5bcc27e01ab8c511f1662a6799925b346c0cf18fca03430200000000ffffffffb932b0669cd0394d0d5bcc27e01ab8c511f1662a6799925b346c0cf18fca03430300000000ffffffff03ea7f0100000000001600141ca1cca8855bad6bc1ea5436edd8cff10b7e448b00c2eb0b0000000016001444cb0c39f93ecc372b5851725bd29d865d333b106081ad2f00000000220020297b92c238163e820b82486084634b4846b86a3c658d87b9384192e6bea98ec500000000 ``` Signed Funding Transaction: ``` -02000000000104b932b0669cd0394d0d5bcc27e01ab8c511f1662a6799925b346c0cf18fca03430000000000ffffffffb932b0669cd0394d0d5bcc27e01ab8c511f1662a6799925b346c0cf18fca03430100000023220020fd89acf65485df89797d9ba7ba7a33624ac4452f00db08107f34257d33e5b946ffffffffb932b0669cd0394d0d5bcc27e01ab8c511f1662a6799925b346c0cf18fca03430200000000ffffffffb932b0669cd0394d0d5bcc27e01ab8c511f1662a6799925b346c0cf18fca03430300000017160014fbb4db9d85fba5e301f4399e3038928e44e37d32ffffffff03ec7f0100000000001600141ca1cca8855bad6bc1ea5436edd8cff10b7e448b00c2eb0b0000000016001444cb0c39f93ecc372b5851725bd29d865d333b106081ad2f00000000220020297b92c238163e820b82486084634b4846b86a3c658d87b9384192e6bea98ec5022068656c6c6f2074686572652c2074686973206973206120626974636f6e2121212782012088a820add57dfe5277079d069ca4ad4893c96de91f88ffb981fdc6a2a34d5336c66aff87022068656c6c6f2074686572652c2074686973206973206120626974636f6e2121212782012088a820add57dfe5277079d069ca4ad4893c96de91f88ffb981fdc6a2a34d5336c66aff8702473044022019b89938002518da7ad949986400a1c1d908c310fc045c0d5edffe3015becaeb02200e84a0c6530f4dd949dcef70f06eaf1896a00ddd6a4f99eae402fcc5d095f5510121034695f5b7864c580bf11f9f8cb1a94eb336f2ce9ef872d2ae1a90ee276c7724840247304402200d62dc4a1778939194b357e0797c5895534d1016e53e2c92829ba7203cfa1ec0022074aa90671275262bd971008a36272b6f41cb167b8bcb1b5fe1cd41340f21899f0121034695f5b7864c580bf11f9f8cb1a94eb336f2ce9ef872d2ae1a90ee276c77248400000000 +02000000000104b932b0669cd0394d0d5bcc27e01ab8c511f1662a6799925b346c0cf18fca03430000000000ffffffffb932b0669cd0394d0d5bcc27e01ab8c511f1662a6799925b346c0cf18fca03430100000023220020fd89acf65485df89797d9ba7ba7a33624ac4452f00db08107f34257d33e5b946ffffffffb932b0669cd0394d0d5bcc27e01ab8c511f1662a6799925b346c0cf18fca03430200000000ffffffffb932b0669cd0394d0d5bcc27e01ab8c511f1662a6799925b346c0cf18fca03430300000017160014fbb4db9d85fba5e301f4399e3038928e44e37d32ffffffff03ea7f0100000000001600141ca1cca8855bad6bc1ea5436edd8cff10b7e448b00c2eb0b0000000016001444cb0c39f93ecc372b5851725bd29d865d333b106081ad2f00000000220020297b92c238163e820b82486084634b4846b86a3c658d87b9384192e6bea98ec5022068656c6c6f2074686572652c2074686973206973206120626974636f6e2121212782012088a820add57dfe5277079d069ca4ad4893c96de91f88ffb981fdc6a2a34d5336c66aff87022068656c6c6f2074686572652c2074686973206973206120626974636f6e2121212782012088a820add57dfe5277079d069ca4ad4893c96de91f88ffb981fdc6a2a34d5336c66aff870247304402204bd649762ff5620cd67b5b90a382dd528ae1e35063f3fdabc6f035df04bb17a502200afb3369cdf014615261e2ce2226b851809b19e678847c9780c7f25f151209cf0121034695f5b7864c580bf11f9f8cb1a94eb336f2ce9ef872d2ae1a90ee276c7724840247304402207c7e66be6518d5ad6b7f314fd392cfb7a3d980d9270cc3c0ec10e9fd752f20280220687233cbec066b71fa96434197e88e04dde2ccfd1b17c78e4d50e4bbcf6df1860121034695f5b7864c580bf11f9f8cb1a94eb336f2ce9ef872d2ae1a90ee276c77248400000000 ``` Weight Count: ``` - Max Witness Len: 368* + Max Witness Len: 368\* + 2 Segwit bytes (flag + marker) Non-Witness Data Byte Count: 337 - Total Weight: 368 + 337 * 4 = 1716 + Total Weight: 370 + 337 * 4 = 1718 ``` \* The signatures calculated for this transaction come to 71-bytes. From 3a3e4ffca511adef811b20707ff0634d0de4f3ba Mon Sep 17 00:00:00 2001 From: lisa neigut Date: Mon, 9 Sep 2019 11:24:26 -0500 Subject: [PATCH 29/44] df: remove contribution count, fix at 4. We fix the total permitted contribution from the acceptor node to 4, and remove it from the protocol. --- 02-peer-protocol.md | 20 +++++--------------- 1 file changed, 5 insertions(+), 15 deletions(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index 672d22ddf..a882623e2 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -477,7 +477,6 @@ This message initiates the v2 channel establishment workflow. * [`u64`:`htlc_minimum_msat`] * [`u32`:`feerate_per_kw`] * [`u32`:`feerate_per_kw_funding`] - * [`u16`:`contrib_count`] * [`u16`:`to_self_delay`] * [`u16`:`max_accepted_htlcs`] * [`point`:`funding_pubkey`] @@ -504,8 +503,6 @@ Rationale and Requirements are the same as for [`open_channel`](#the-open_channe If nodes have negotiated `option_dual_fund`: - the opening node: - MUST not send `open_channel` - - MUST set the `contrib_count` to the total of `num_inputs` plus - `num_outputs' that will be included in `funding_compose`, with minimum 2. #### Rationale @@ -513,9 +510,6 @@ If nodes have negotiated `option_dual_fund`: 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). -`contrib_count` is the total number of inputs and outputs that the opener -will contribute to the funding transaction. This is sent so that the -accepter can configure appropriate funding values for their `accept_channel2` response. ### The `accept_channel2` Message @@ -596,25 +590,21 @@ The sending node: - MAY specify an output with value zero, which will be used as the change address. - if is the `accepter`: - - consider the `contrib_count` the total of `num_inputs` plus - `num_outputs' from `funding_compose`, with minimum 2. - - MUST NOT send `input_info`s or `output_info` which - exceeds the `contrib_count` limit. + - consider the `contribution count` the total of `num_inputs` plus + `num_outputs' from `funding_compose`. + - MUST NOT send a `funding_compose` message where the `contribution count` + exceeds the limit of 4. - MAY send zero inputs and/or outputs. The receiving node: - if the total `input_info`.`satoshis` is less than the total `output_info`.`satoshis` - MUST fail the channel. - - if is the `accepter`: - - MAY fail the channel if: - - the total count of `input_infos` and `output_info`s is not equal to the - `contrib_count`. - if is the `opener`: - MAY fail the channel if: - the fee cost of the proposed funding transaction is deemed exorbitant. - MUST fail the channel if: - the total count of `input_info`s and `output_info`s is greater than - the `contrib_count`. + the `contribution count` limit of 4. - if has not yet sent a `funding_compose`: - MUST send its `funding_compose` message. - otherwise: From c06d7b783574ec976b25b66d6654b627e64548d8 Mon Sep 17 00:00:00 2001 From: lisa neigut Date: Mon, 9 Sep 2019 11:25:16 -0500 Subject: [PATCH 30/44] df: remove channel_reserve_satoshis from openchannel2 Fix the reserve to always be 1% of the channel balance, or the dust_limit, whichever is greater. This reduces the complexity around calculating the reserve balance. --- 02-peer-protocol.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index a882623e2..fd32a3529 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -510,6 +510,10 @@ If nodes have negotiated `option_dual_fund`: 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). +`channel_reserve_satoshi` has been omitted. The channel reserve is fixed at 1% of +the total channel balance (sum of `funding_satoshis` from `open_channel2` and `accept_channel2`) +or the `dust_limit_satoshis`, whichever is greater. + ### The `accept_channel2` Message @@ -548,6 +552,10 @@ Accepter sends their `funding_satoshi` value here instead of allowing the opener it from their `funding_compose` response so that the opener can decide whether to complete the opening without exposing their output set. +`channel_reserve_satoshi` has been omitted. The channel reserve is fixed at 1% of +the total channel balance (sum of `funding_satoshis` from `open_channel2` and `accept_channel2`) +or the `dust_limit_satoshis`, whichever is greater. + ### The `funding_compose` Message This message exchanges the transaction input and output @@ -556,7 +564,6 @@ information necessary to compose the funding transaction. 1. type: 58 (`funding_compose`) 2. data: * [`32*byte`:`temporary_channel_id`] - * [`u64`:`channel_reserve_satoshis`] * [`u16`:`num_inputs`] * [`num_inputs*input_info`:`input_info`] * [`u16`:`num_outputs`] @@ -620,9 +627,6 @@ Each node must have a complete set of the transaction inputs and outputs, to derive the funding transaction. This avoids information asymmetry between the nodes, as both sides share their input utxo set. -`channel_reserve_satoshis` is the minimum balance that the other node -must reserve for itself, out of the total channel balance. - `satoshis` is the value of the input or output. `prevtx_txid`, `prevtx_vout`, and `prevtx_scriptpubkey` specify the output @@ -740,7 +744,6 @@ indicated above. 2. data: * [`channel_id`:`channel_id`] * [`u64`:`funding_satoshis`] - * [`u64`:`channel_reserve_satoshis`] * [`u32`:`feerate_per_kw`] * [`u32`:`feerate_per_kw_funding`] * [`u16`:`num_additional_inputs`] @@ -754,7 +757,6 @@ The sending node: - MUST have sent `open_channel2`. - MUST send a `feerate_per_kw_funding` greater than the most recently negotiated rate. - - MUST update the `channel_reserve_satoshis` to reflect the new input balance. - MAY update the `feerate_per_kw`, the commitment transaction feerate. - MAY include additional inputs. - MAY set the `num_inputs` to zero. @@ -766,8 +768,6 @@ The receiving node: - MUST return an error if: - the `feerate_per_kw_funding` is not greater than the previously negotiated rate. - - MAY return an error if: - - the `channel_reserve_satoshis` is not acceptable. #### Rationale The sending node's half of the funding transaction will be composed with From 140ab5b752c4d7d708d3c994b1756e0816f0c1fa Mon Sep 17 00:00:00 2001 From: lisa neigut Date: Wed, 11 Sep 2019 17:32:44 -0500 Subject: [PATCH 31/44] df: add separate tlv type for accept_channel2 --- 02-peer-protocol.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index fd32a3529..3853bcf07 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -536,7 +536,14 @@ acceptance of the new channel. * [`point`:`delayed_payment_basepoint`] * [`point`:`htlc_basepoint`] * [`point`:`first_per_commitment_point`] - * [`opening_tlv`:`opening_tlv`] + * [`accept_tlvs`:`accept_tlv`] + +1. tlvs: `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. From 6ab67589f339e1b57f0842691ea20fa347ac7489 Mon Sep 17 00:00:00 2001 From: lisa neigut Date: Wed, 11 Sep 2019 17:33:12 -0500 Subject: [PATCH 32/44] df: remove funding_signed; replace with accepter_sigs Shorten the round trips required by only having the accepter send their sigs to the opener. This means only the opener is able to compose the funding transaction completely, and that only they are in control of publishing it, which is the same as current implementations. --- 02-peer-protocol.md | 49 ++++++++++++++++++++++++--------------------- 1 file changed, 26 insertions(+), 23 deletions(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index 3853bcf07..22033019b 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -441,23 +441,20 @@ It extends version one to allow the non-`open_channel` participant The protocol is also expanded to include a mechanism for initiating RBF. +-------+ +-------+ - | |--(1)--- open_channel2 ----->| | - | |<-(2)-- accept_channel2 -----| | + | |--(1)--- open_channel2 ----->| | + | |<-(2)--- accept_channel2 -----| | | | | | | |--(3)-- funding_compose ---->| | | |<-(4)-- funding_compose -----| | | | | | - --->| |--(5)-- commitment_signed -->| | - | | |<-(6)-- commitment_signed ---| | - | | A | | B | - | | |--(7)--- funding_signed2 ---->| | - | | |<-(8)--- funding_signed2 -----| | + --->| |--(5)-- commitment_signed -->| | + | | A |<-(6)-- accepter_sigs ----| B | | | | | | | | |--(a)--- init_rbf ----------->| | ----| |<-(b)--- ack_rbf ------------| | | | | | - | |--(9)--- funding_locked ----->| | - | |<-(10)-- funding_locked ------| | + | |--(7)--- funding_locked ----->| | + | |<-(8)--- funding_locked ------| | +-------+ +-------+ - where node A is 'opener' and node B is 'accepter' @@ -556,13 +553,14 @@ The accepting node: #### Rationale Accepter sends their `funding_satoshi` value here instead of allowing the opener to derive -it from their `funding_compose` response so that the opener can decide whether +it from their `funding_compose` response so that the opener can notionally decide whether to complete the opening without exposing their output set. `channel_reserve_satoshi` has been omitted. The channel reserve is fixed at 1% of the total channel balance (sum of `funding_satoshis` from `open_channel2` and `accept_channel2`) or the `dust_limit_satoshis`, whichever is greater. + ### The `funding_compose` Message This message exchanges the transaction input and output @@ -602,10 +600,10 @@ The sending node: - if is the `opener`: - MUST NOT send zero inputs (`num_inputs` cannot be zero). - MAY specify an output with value zero, which will be used - as the change address. + as the change address if applicable. - if is the `accepter`: - - consider the `contribution count` the total of `num_inputs` plus - `num_outputs' from `funding_compose`. + - consider the `contribution count` the total of their `num_inputs` plus + `num_outputs' - MUST NOT send a `funding_compose` message where the `contribution count` exceeds the limit of 4. - MAY send zero inputs and/or outputs. @@ -631,8 +629,7 @@ The receiving node: #### Rationale Each node must have a complete set of the transaction inputs and outputs, -to derive the funding transaction. This avoids information -asymmetry between the nodes, as both sides share their input utxo set. +to derive the funding transaction and subsequent commitment signatures. `satoshis` is the value of the input or output. @@ -673,6 +670,9 @@ independently. ### The `commitment_signed` Message +This message is sent by the opening node. It contains the signatures for +the first commitment transaction. + Rationale and Requirements are the same as listed above, for [`commitment_signed`](#commiting-updates-so-far-commitment_signed) with the following additions. @@ -692,14 +692,16 @@ The first commitment transaction has no HTLC's in it. Note that the `commitment_signed` message will include the `channel_id` derived from the `funding_txid`, instead of the `temporary_node_id`. -### The `funding_signed2` Message +### The `accepter_sigs` Message -This message exchanges the witness data for the inputs that were -originally sent in the `funding_compose` message. +This message is sent by the accepting node. It contains the witness data +for the inputs that were originally sent in the `funding_compose` message, plus +the signatures for the commitment transaction. -1. type: 60 (`funding_signed2`) +1. type: 60 (`accepter_sigs`) 2. data: * [`channel_id`:`channel_id`] + * [`signature`:`commitment_signature`] * [`u16`:`num_witnesses`] * [`num_witnesses*witness_stack`:`witness_stack`] @@ -715,6 +717,7 @@ originally sent in the `funding_compose` message. #### Requirements The sending node: + - MUST verify it has received valid commitment signatures from its peer - MUST set `witness` to the serialized witness data for each of its inputs, in funding transaction order. FIXME: link to funding tx order - MUST remember the details of this funding transaction. @@ -726,14 +729,14 @@ The sending node: The receiving node: - if the `witness_stack` length exceeds `max_witness_len`: - MUST error. - - if the recipient was the sender of `open_channel2`: - - SHOULD reply with its own `funding_signed2`. + - MUST verify it has received valid commitment signatures - SHOULD apply `witness`es to the funding transaction and broadcast it. #### Rationale -Exchanging witness data allows both sides to broadcast the funding -transaction. + +The accepting node sends both their comitment signatures and funding +transaction signatures. This completes the `open_channel2` dialogue. ### Kicking Off Replace-By-Fee: `init_rbf` From d1df2a1e36a5216f004b797e08e90e8eb4729d1b Mon Sep 17 00:00:00 2001 From: lisa neigut Date: Thu, 19 Sep 2019 18:10:03 -0500 Subject: [PATCH 33/44] update feature number briefly --- 09-features.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/09-features.md b/09-features.md index 69ad94377..8adad471c 100644 --- a/09-features.md +++ b/09-features.md @@ -18,7 +18,6 @@ features may be required for opening a channel, but not a requirement for use of the channel, so the presentation of those features depends on the feature itself. - The Context column decodes as follows: * `I`: presented in the `init` message. * `N`: presented in the `node_announcement` messages @@ -38,7 +37,7 @@ The Context column decodes as follows: | 12/13 | `option_static_remotekey` | Static key for remote output | IN | | [BOLT #3](03-transactions.md) | | 14/15 | `payment_secret` | Node supports `payment_secret` field | IN9 | `var_onion_optin` | [Routing Onion Specification][bolt04] | | 16/17 | `basic_mpp` | Node can receive basic multi-part payments | IN9 | `payment_secret` | [BOLT #4][bolt04-mpp] | -| 17/18 | `option_dual_fund` | Use v2 of channel open, enables dual funding | IN9 | | [BOLT #2](02-peer-protocol.md) | +| 28/29 | `option_dual_fund` | Use v2 of channel open, enables dual funding | IN9 | | [BOLT #2](02-peer-protocol.md) | ## Requirements From afbf8d2bbaf8c300258d6c93af4664bfdcd63354 Mon Sep 17 00:00:00 2001 From: lisa neigut Date: Tue, 15 Oct 2019 20:37:38 +0200 Subject: [PATCH 34/44] dual funding: break up funding composition messages Break funding_compose into 3 messages, to allow for asynchronous input and output construction. This is done to enable multi-party funding transaction construction --- 02-peer-protocol.md | 250 +++++++++++++++++++++++++++++++++----------- 1 file changed, 189 insertions(+), 61 deletions(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index 22033019b..898dfcb28 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -16,7 +16,9 @@ operation, and closing. * [Channel Establishment v2](#channel-establishment-v2) * [The `open_channel2` Message](#the-open_channel2-message) * [The `accept_channel2` Message](#the-accept_channel2-message) - * [The `funding_compose` Message](#the-funding_compose-message) + * [The `funding_add_input` Message](#the-funding_add_input-message) + * [The `funding_add_output` Message](#the-funding_add_output-message) + * [The `funding_add_complete` Message](#the-funding_add_complete-message) * [The `funding_signed2` Message](#the-funding_signed2-message) * [Kicking Off Replace-By-Fee: `init_rbf` Message](#kicking-off-replace-by-fee-init_rbf) * [Acknowledging Replace-By-Fee `ack_rbf` Message](#acknowledging-replace-by-fee-ack_rbf) @@ -444,17 +446,26 @@ The protocol is also expanded to include a mechanism for initiating RBF. | |--(1)--- open_channel2 ----->| | | |<-(2)--- accept_channel2 -----| | | | | | - | |--(3)-- funding_compose ---->| | - | |<-(4)-- funding_compose -----| | + | |--(3a)- funding_add_input -->| | + | |<-(3b)- funding_add_input ---| | + | |--(3c)- funding_add_input -->| | + | |--(3d)- funding_add_output ->| | + | |<-(3e)- funding_add_output --| | | | | | + | |--(4a)- funding_add_complete >| | + | |<-(4b)- funding_add_complete -| | + | A | | B | --->| |--(5)-- commitment_signed -->| | - | | A |<-(6)-- accepter_sigs ----| B | + | | |<-(6)-- commitment_signed ---| | + | | | | | + | | |--(7)-- funding_signed2 -->| | + | | |<-(8)-- funding_signed2 ---| | | | | | | | | |--(a)--- init_rbf ----------->| | ----| |<-(b)--- ack_rbf ------------| | | | | | - | |--(7)--- funding_locked ----->| | - | |<-(8)--- funding_locked ------| | + | |--(9)--- funding_locked ----->| | + | |<-(10)-- funding_locked ------| | +-------+ +-------+ - where node A is 'opener' and node B is 'accepter' @@ -561,22 +572,29 @@ the total channel balance (sum of `funding_satoshis` from `open_channel2` and `a or the `dust_limit_satoshis`, whichever is greater. -### The `funding_compose` Message +### Funding Composition +There are three messages which nodes use to communicate their input and output set +for a funding transaction: `funding_add_input`, `funding_add_output`, and `funding_add_complete`. + +To add inputs to a transaction, a node may send one or more `funding_add_input` messages. +To add outputs to a transaction, a node may send one or more `funding_add_output` messages. + +Once a node has relayed all of their inputs and output contributions, it sends +`funding_add_complete` to signal the completion of their contribution transmission. -This message exchanges the transaction input and output -information necessary to compose the funding transaction. +#### The `funding_add_input` Message -1. type: 58 (`funding_compose`) +This message contains information for inputs to a funding transaction. + +1. type: 58 (`funding_add_input`) 2. data: * [`32*byte`:`temporary_channel_id`] * [`u16`:`num_inputs`] * [`num_inputs*input_info`:`input_info`] - * [`u16`:`num_outputs`] - * [`num_outputs*output_info`:`output_info`] 1. subtype: `input_info` 2. data: - * [`u64`:`input_satoshis`] + * [`u64`:`sats`] * [`sha256`:`prevtx_txid`] * [`u32`:`prevtx_vout`] * [`u16`:`prevtx_scriptpubkey_len`] @@ -585,53 +603,43 @@ information necessary to compose the funding transaction. * [`u16`:`scriptlen`] * [`scriptlen*byte`:`script`] -1. subtype: `output_info` -2. data: - * [`u64`:`output_satoshis`] - * [`u16`:`scriptlen`] - * [`scriptlen*byte`:`script`] +##### Requirements -#### Requirements +The `accepter` node: + - MAY omit this message The sending node: + - MUST NOT send `funding_add_input` if it has already transmitted `funding_add_complete` + - MUST send this after `accept_channel2` has been exchanged, but before `funding_add_complete` + - MUST add all sent inputs to the funding transaction + - MUST NOT re-transmit inputs it has already received from the peer - MUST ensure each `input_info` refers to a non-malleable (segwit) UTXO. - - MUST ensure the `output_info`.`script` is a standard script - - MUST NOT include the channel funding output. - if is the `opener`: - - MUST NOT send zero inputs (`num_inputs` cannot be zero). - - MAY specify an output with value zero, which will be used - as the change address if applicable. + - MUST send at least one `funding_add_input` message + - MUST NOT send a total count of more than 64 inputs, across all `funding_add_input` messages. - if is the `accepter`: - - consider the `contribution count` the total of their `num_inputs` plus - `num_outputs' - - MUST NOT send a `funding_compose` message where the `contribution count` - exceeds the limit of 4. - - MAY send zero inputs and/or outputs. + - MAY omit this message + - MUST NOT send a total count of more than 16 inputs, across all `funding_add_input` messages. The receiving node: - - if the total `input_info`.`satoshis` is less than the total `output_info`.`satoshis` - - MUST fail the channel. + - MUST add all received inputs to the funding transaction + - MUST fail the channel if: + - it receives a duplicate input to one it sent previously + - if it receives this message after `funding_add_complete` is received. + - it receives an input that is malleable (P2SH/P2PKH) - if is the `opener`: - - MAY fail the channel if: - - the fee cost of the proposed funding transaction is deemed exorbitant. - MUST fail the channel if: - - the total count of `input_info`s and `output_info`s is greater than - the `contribution count` limit of 4. - - if has not yet sent a `funding_compose`: - - MUST send its `funding_compose` message. - - otherwise: - - MUST use the sent and received `input_info` and `output_info` - to create the funding transaction, using `max_witness_len` - for each `input_info` and `feerate_per_kw_funding` as specified in - `open_channel2`. - - MUST send `commitment_signed`. + - the total count of `input_info`s is greater than 16 + - is is the `accepter`: + - MUST fail the channel if: + - the total count of `input_info`s is greater than 64 -#### Rationale -Each node must have a complete set of the transaction inputs and outputs, +##### Rationale +Each node must have a complete set of the transaction inputs to derive the funding transaction and subsequent commitment signatures. -`satoshis` is the value of the input or output. +`sats` is the satoshi value of the input. `prevtx_txid`, `prevtx_vout`, and `prevtx_scriptpubkey` specify the output to be spent. `prevtx_txid` is the hash of the transaction that this input is @@ -642,15 +650,67 @@ corresponding `scriptPubKey` value. witness data that will be supplied (e.g. sizeof(varint) + sizeof(witness) for each) in `funding_signed2`. -`input_info`.`script` is the scriptPubkey data for the input. -NB: for native SegWit inputs (P2WPKH and P2WSH) inputs, the `script` field -will be empty. See [BIP141](https://github.com/bitcoin/bips/blob/master/bip-0141.mediawiki#examples). +`input_info`.`script` is the script signature field for the input. Only applicable +for P2SH-wrapped inputs. +Native SegWit inputs (P2WPKH and P2WSH) inputs, will have an empty `script` field +See [BIP141](https://github.com/bitcoin/bips/blob/master/bip-0141.mediawiki#examples). + +The `accepter` node may omit this message. + + +#### The `funding_add_output` Message + +This message contains information for outputs to a funding transaction. -The opening node may include one output with `satoshis` value +1. type: 60 (`funding_add_output`) +2. data: + * [`32*byte`:`temporary_channel_id`] + * [`u16`:`num_outputs`] + * [`num_outputs*output_info`:`output_info`] + +1. subtype: `output_info` +2. data: + * [`u64`:`sats`] + * [`u16`:`scriptlen`] + * [`scriptlen*byte`:`script`] + +##### Requirements + +Either node: + - MAY omit this message + +The sending node: + - MUST NOT send `funding_add_output` if it has already transmitted `funding_add_complete` + - MUST send this after `accept_channel2` has been exchanged, but before `funding_add_complete` + - MUST add all sent outputs to the funding transaction + - MUST ensure the `output_info`.`script` is a standard script + - MUST NOT include the channel funding output. + - if is the `opener`: + - MAY specify an output with value zero, which will be used + as the change address for any resulting funds after fees are deducted + - if is the `accepter`: + - MUST NOT send a total count of more than 8 outputs, across all `funding_add_output` messages. + +The receiving node: + - MUST add all received outputs to the funding transaction + - MUST fail the channel if + - it receives this message after receiving `funding_add_complete` + - if is the `opener`: + - MUST fail the channel if: + - receives a total count of more than 8 outputs, across all `funding_add_output`s + + +##### Rationale +Each node must have a complete set of the transaction outputs +to derive the funding transaction and subsequent commitment signatures. + +`sats` is the satoshi value of the output. + +The opening node may include one output with `sats` value of zero. This will be used for change, or discarded if its value is be below `dust_limit_satoshis`. -Change is calculated as the sum of the opener's `input_info`.`satoshis` +Change is calculated as the sum of the opener's `input_info`.`sats` minus the estimated funding transaction size times the `feerate_per_kw_funding` minus the `funding_satoshis` minus all other `output_info`.`satoshis`. If the `change_satoshis` value is negative, @@ -668,6 +728,65 @@ found in [BOLT-3, v2 Funding Transaction Fees](03-transactions.md#channel-establ The channel funding output is not exchanged, as it can be derived independently. + +#### The `funding_add_complete` Message + +This message signals the conclusion of a peer's funding transaction +contributions. + +1. type: 62 (`funding_add_complete`) +2. data: + * [`32*byte`:`temporary_channel_id`] + * [`u16`:`num_inputs`] + * [`u16`:`num_outputs`] + + +##### Requirements + +Both nodes: + - MUST send this message after `accept_channel2` has been sent/received. + +The sending node: + - MUST ensure that the `num_inputs` corresponds to the total sum of all `num_inputs` + sent in all `funding_add_input` messages that originated from them + - MUST ensure that the `num_outputs` corresponds to the total sum of all `num_outputs` + sent in all `funding_add_output` messages that originated from them + +The receiving node: + - MUST fail the channel if: + - the `num_inputs` does not correspond to the total sum of all `num_inputs` + received in all `funding_add_input` messages + - the `num_outputs` does not correspond to the total sum of all `num_outputs` + received in all `funding_add_output` messages + - the total satoshis of the senders inputs is less than their outputs plus + the funding_sats, specified earlier + - if is the `opener`: + - MAY fail the channel if: + - the fee cost of the proposed funding transaction is deemed exorbitant. + - if has not yet sent a `funding_add_complete`: + - MUST send its `funding_add_complete` message. + - otherwise: + - MUST use the sent and received `input_info` and `output_info` + to create the funding transaction, using `max_witness_len` + for each `input_info` and `feerate_per_kw_funding` as specified in + `open_channel2`. + - MUST send `commitment_signed`. + + +##### Rationale + +Each node must have a complete set of the transaction inputs and outputs, +to derive the funding transaction and subsequent commitment signatures. + +`funding_add_complete` concludes a node's transmission of its contributions +to the funding transaction, which serve as an early check that all +`funding_add_input` and `funding_add_output` messages have been received. + +Upon successful exchange of `funding_add_complete` messages, both nodes +should build the funding transaction and update their channel id +to be transmitted in `commitment_signed`. + + ### The `commitment_signed` Message This message is sent by the opening node. It contains the signatures for @@ -684,6 +803,10 @@ The sending node: The receiving node: - if the message has one or more HTLC's: - MUST fail the channel. + - if it has not already transmitted its `commitment_signed`: + - MUST send `commitment_signed` + - Otherwise: + - MUST send `funding_signed2` #### Rationale @@ -692,21 +815,22 @@ The first commitment transaction has no HTLC's in it. Note that the `commitment_signed` message will include the `channel_id` derived from the `funding_txid`, instead of the `temporary_node_id`. -### The `accepter_sigs` Message -This message is sent by the accepting node. It contains the witness data -for the inputs that were originally sent in the `funding_compose` message, plus -the signatures for the commitment transaction. +### The `funding_signed2` Message + +This message contains witness data for for the inputs that were +originally exchanged in `funding_add_input`. -1. type: 60 (`accepter_sigs`) +1. type: 64 (`funding_signed2`) 2. data: * [`channel_id`:`channel_id`] - * [`signature`:`commitment_signature`] * [`u16`:`num_witnesses`] * [`num_witnesses*witness_stack`:`witness_stack`] 1. subtype: `witness_stack` 2. data: + * [`sha256`:`prevtx_txid`] + * [`u32`:`prevtx_vout`] * [`u16`:`num_input_witness`] * [`num_input_witness*witness_element`:`witness_element`] @@ -718,8 +842,8 @@ the signatures for the commitment transaction. #### Requirements The sending node: - MUST verify it has received valid commitment signatures from its peer - - MUST set `witness` to the serialized witness data for each of its - inputs, in funding transaction order. FIXME: link to funding tx order + - MUST set `witness` to the serialized witness data for the input + corresponding to `prevtx_txid`:`prevtx_vout` - MUST remember the details of this funding transaction. - MUST NOT send a `witness_stack` whose length exceeds its previously indicated `max_witness_len`. @@ -735,9 +859,13 @@ The receiving node: #### Rationale -The accepting node sends both their comitment signatures and funding -transaction signatures. This completes the `open_channel2` dialogue. +Every node must transmit their complete set of witness data for +the inputs included in the funding transaction. + +`prevtx_txid` and `prevtx_vout` are the identifier for the input +which the witness data pertain to +`witness` is the data for a witness element in a witness stack ### Kicking Off Replace-By-Fee: `init_rbf` From a233f57e94a5e429a7b12c9773ecc7b37b2524f0 Mon Sep 17 00:00:00 2001 From: lisa neigut Date: Tue, 15 Oct 2019 20:50:12 +0200 Subject: [PATCH 35/44] dual-funding: fixup some wording on the RBF section --- 02-peer-protocol.md | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index 898dfcb28..f21e88f1c 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -898,21 +898,24 @@ The sending node: - MAY update the `feerate_per_kw`, the commitment transaction feerate. - MAY include additional inputs. - MAY set the `num_inputs` to zero. - - MUST transmit all outputs. - - MAY include at least one output with the `satoshis` set to zero, + - MUST transmit all outputs, excluding the channel funding output. + - MAY include at least one output with the `sats` set to zero, to be used as the change output. The receiving node: - MUST return an error if: - the `feerate_per_kw_funding` is not greater than the previously negotiated rate. + - MUST return an error, but not fail the channel if: + - it has already received a `funding_locked` message + #### Rationale The sending node's half of the funding transaction will be composed with all of the previously relayed inputs plus the ones included here. All outputs must be transmitted in the `init_rbf` message, including -ones communicated previously. +ones communicated previously, except for the channel funding output. If a valid `funding_locked` message is received in the middle of an RBF workflow, the RBF attempt MUST be abandoned. @@ -928,13 +931,19 @@ This message acknowledges the start of an RBF workflow. #### Requirements +The sending node: + - MUST NOT have already sent or received a `funding_locked` message + for this channel. + - MUST NOT have seen the previously signed funding transaction appear + in a block + The receiving node: - MUST respond with a `commitment_signed` message for the updated funding transaction. #### Rationale -Signals to receiving node to proceed with exchanging commitment signatures. +Signals to receiving node to proceed with commitment signature exchange. ## Channel Close From 5dd384af663e59db304e1c9cfbf7e60de3f62b3d Mon Sep 17 00:00:00 2001 From: lisa neigut Date: Mon, 28 Oct 2019 18:39:38 -0500 Subject: [PATCH 36/44] dual-funding: reduce total input/outputs from the accepter Further limit the total inputs/outputs allowed from a peer --- 02-peer-protocol.md | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index f21e88f1c..b417ce5af 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -629,10 +629,7 @@ The receiving node: - it receives an input that is malleable (P2SH/P2PKH) - if is the `opener`: - MUST fail the channel if: - - the total count of `input_info`s is greater than 16 - - is is the `accepter`: - - MUST fail the channel if: - - the total count of `input_info`s is greater than 64 + - the total count of `input_info`s is greater than 6 ##### Rationale @@ -697,7 +694,7 @@ The receiving node: - it receives this message after receiving `funding_add_complete` - if is the `opener`: - MUST fail the channel if: - - receives a total count of more than 8 outputs, across all `funding_add_output`s + - receives a total count of more than 3 outputs, across all `funding_add_output`s ##### Rationale From 40c0b8025d611b2e785f3e4daa95b12ae5e71f6a Mon Sep 17 00:00:00 2001 From: lisa neigut Date: Wed, 13 Nov 2019 15:15:13 -0600 Subject: [PATCH 37/44] fixup: wording, spelling and logic/duplication errors Reported-By: @darosior --- 02-peer-protocol.md | 17 +++++++---------- 1 file changed, 7 insertions(+), 10 deletions(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index b417ce5af..b891cb2ff 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -510,7 +510,7 @@ Rationale and Requirements are the same as for [`open_channel`](#the-open_channe If nodes have negotiated `option_dual_fund`: - the opening node: - - MUST not send `open_channel` + - MUST NOT send `open_channel` #### Rationale @@ -625,7 +625,7 @@ The receiving node: - MUST add all received inputs to the funding transaction - MUST fail the channel if: - it receives a duplicate input to one it sent previously - - if it receives this message after `funding_add_complete` is received. + - it receives this message after `funding_add_complete` is received. - it receives an input that is malleable (P2SH/P2PKH) - if is the `opener`: - MUST fail the channel if: @@ -652,8 +652,6 @@ for P2SH-wrapped inputs. Native SegWit inputs (P2WPKH and P2WSH) inputs, will have an empty `script` field See [BIP141](https://github.com/bitcoin/bips/blob/master/bip-0141.mediawiki#examples). -The `accepter` node may omit this message. - #### The `funding_add_output` Message @@ -694,7 +692,7 @@ The receiving node: - it receives this message after receiving `funding_add_complete` - if is the `opener`: - MUST fail the channel if: - - receives a total count of more than 3 outputs, across all `funding_add_output`s + - receives a total count of more than 8 outputs, across all `funding_add_output`s ##### Rationale @@ -705,7 +703,7 @@ to derive the funding transaction and subsequent commitment signatures. The opening node may include one output with `sats` value of zero. This will be used for change, or discarded if its value is -be below `dust_limit_satoshis`. +below `dust_limit_satoshis`. Change is calculated as the sum of the opener's `input_info`.`sats` minus the estimated funding transaction size times the @@ -756,7 +754,7 @@ The receiving node: - the `num_outputs` does not correspond to the total sum of all `num_outputs` received in all `funding_add_output` messages - the total satoshis of the senders inputs is less than their outputs plus - the funding_sats, specified earlier + the `funding_satoshis`, specified earlier - if is the `opener`: - MAY fail the channel if: - the fee cost of the proposed funding transaction is deemed exorbitant. @@ -815,7 +813,7 @@ the `funding_txid`, instead of the `temporary_node_id`. ### The `funding_signed2` Message -This message contains witness data for for the inputs that were +This message contains witness data for the inputs that were originally exchanged in `funding_add_input`. 1. type: 64 (`funding_signed2`) @@ -890,6 +888,7 @@ indicated above. The sending node: - MUST have sent `open_channel2`. + - MUST NOT have sent or received a `funding_locked` message. - MUST send a `feerate_per_kw_funding` greater than the most recently negotiated rate. - MAY update the `feerate_per_kw`, the commitment transaction feerate. @@ -903,8 +902,6 @@ The receiving node: - MUST return an error if: - the `feerate_per_kw_funding` is not greater than the previously negotiated rate. - - MUST return an error, but not fail the channel if: - - it has already received a `funding_locked` message #### Rationale From 761bc13f8de5cd2c9ac0c285a84d9deac01079ec Mon Sep 17 00:00:00 2001 From: lisa neigut Date: Thu, 14 Nov 2019 13:22:32 -0600 Subject: [PATCH 38/44] df: clarify handling of dust-limit for funding tx --- 02-peer-protocol.md | 4 ++++ 03-transactions.md | 3 ++- 2 files changed, 6 insertions(+), 1 deletion(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index b891cb2ff..e58a3b82c 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -755,6 +755,7 @@ The receiving node: received in all `funding_add_output` messages - the total satoshis of the senders inputs is less than their outputs plus the `funding_satoshis`, specified earlier + - the resulting `funding_output` value is less than the `dust_limit`. - if is the `opener`: - MAY fail the channel if: - the fee cost of the proposed funding transaction is deemed exorbitant. @@ -765,6 +766,9 @@ The receiving node: to create the funding transaction, using `max_witness_len` for each `input_info` and `feerate_per_kw_funding` as specified in `open_channel2`. + - if the `funding_output` of the resulting transaction is less than + the `dust_limit` ([BOLT #3: Calculating `est_tx_fee`](03-transactions.md#channel-establishment-v2-funding-transaction-fees)): + - MUST fail the channel - MUST send `commitment_signed`. diff --git a/03-transactions.md b/03-transactions.md index fa0f581a7..59ca07f98 100644 --- a/03-transactions.md +++ b/03-transactions.md @@ -416,7 +416,8 @@ The fee for a v2 funding transaction is calculated in up to two rounds. will be added to the funding output, and credited to the opener's initial channel balance. - if the resulting `change_satoshis` is less than zero: - - sum(`funding_satoshis`) will be decreased by the difference. + - `opener_funding` will be decreased by the difference. + Computation details are included in [Appendix A](#appendix-a-expected-weights) and [Appendix F, Dual Funded Transaction Test Vectors](#appendix-f-dual-funded-transaction-test-vectors). From c2de44fbd6851efdefeef06e5e5f1980a51103e3 Mon Sep 17 00:00:00 2001 From: lisa neigut Date: Thu, 21 Nov 2019 16:19:45 -0600 Subject: [PATCH 39/44] df: normalize type numbers --- 02-peer-protocol.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index e58a3b82c..0b8ff4c89 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -474,7 +474,7 @@ The protocol is also expanded to include a mechanism for initiating RBF. This message initiates the v2 channel establishment workflow. -1. type: 56 (`open_channel2`) +1. type: 64 (`open_channel2`) 2. data: * [`chain_hash`:`chain_hash`] * [`32*byte`:`temporary_channel_id`] @@ -528,7 +528,7 @@ or the `dust_limit_satoshis`, whichever is greater. This message contains information about a node and indicates its acceptance of the new channel. -1. type: 57 (`accept_channel2`) +1. type: 65 (`accept_channel2`) 2. data: * [`32*byte`:`temporary_channel_id`] * [`u64`:`funding_satoshis`] @@ -586,7 +586,7 @@ Once a node has relayed all of their inputs and output contributions, it sends This message contains information for inputs to a funding transaction. -1. type: 58 (`funding_add_input`) +1. type: 66 (`funding_add_input`) 2. data: * [`32*byte`:`temporary_channel_id`] * [`u16`:`num_inputs`] @@ -657,7 +657,7 @@ See [BIP141](https://github.com/bitcoin/bips/blob/master/bip-0141.mediawiki#exam This message contains information for outputs to a funding transaction. -1. type: 60 (`funding_add_output`) +1. type: 67 (`funding_add_output`) 2. data: * [`32*byte`:`temporary_channel_id`] * [`u16`:`num_outputs`] @@ -729,7 +729,7 @@ independently. This message signals the conclusion of a peer's funding transaction contributions. -1. type: 62 (`funding_add_complete`) +1. type: 68 (`funding_add_complete`) 2. data: * [`32*byte`:`temporary_channel_id`] * [`u16`:`num_inputs`] @@ -820,7 +820,7 @@ the `funding_txid`, instead of the `temporary_node_id`. This message contains witness data for the inputs that were originally exchanged in `funding_add_input`. -1. type: 64 (`funding_signed2`) +1. type: 69 (`funding_signed2`) 2. data: * [`channel_id`:`channel_id`] * [`u16`:`num_witnesses`] @@ -877,7 +877,7 @@ Once an `init_rbf` message has been successfully ack'd by the accepter node, the message flow returns to `commitment_signed` and proceeds as indicated above. -1. type: 62 (`init_rbf`) +1. type: 70 (`init_rbf`) 2. data: * [`channel_id`:`channel_id`] * [`u64`:`funding_satoshis`] @@ -923,7 +923,7 @@ RBF workflow, the RBF attempt MUST be abandoned. This message acknowledges the start of an RBF workflow. -1. type: 63 (`ack_rbf`) +1. type: 71 (`ack_rbf`) 2. data: * [`channel_id`:`channel_id`] From 8c92423e31a171c85753591910e1c0a718c41d71 Mon Sep 17 00:00:00 2001 From: lisa neigut Date: Mon, 25 Nov 2019 18:19:05 -0600 Subject: [PATCH 40/44] cleanup duplicative omit message --- 02-peer-protocol.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index 0b8ff4c89..7e1aec5c3 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -605,9 +605,6 @@ This message contains information for inputs to a funding transaction. ##### Requirements -The `accepter` node: - - MAY omit this message - The sending node: - MUST NOT send `funding_add_input` if it has already transmitted `funding_add_complete` - MUST send this after `accept_channel2` has been exchanged, but before `funding_add_complete` From 8aca867fc94ca37cb489fe87b9f11af4d174b8da Mon Sep 17 00:00:00 2001 From: lisa neigut Date: Mon, 25 Nov 2019 18:19:32 -0600 Subject: [PATCH 41/44] add note about ignoring bad funding_signed2 msg --- 02-peer-protocol.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index 7e1aec5c3..16834e5ef 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -852,6 +852,9 @@ The receiving node: - MUST verify it has received valid commitment signatures - 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 @@ -863,6 +866,10 @@ which the witness data pertain to `witness` is the data for a witness element in a witness stack +It is possible but a protocol error for an accepter node to +fail to send a `funding_signed2` message while also +successfully broadcasting the signed funding transaction. + ### Kicking Off Replace-By-Fee: `init_rbf` This message initiates the flow to create a replacement funding From a960a1b2c9312f682b1b5c3f6f43693d526c8b07 Mon Sep 17 00:00:00 2001 From: lisa neigut Date: Mon, 25 Nov 2019 18:22:46 -0600 Subject: [PATCH 42/44] fixup! remove invalid requirement --- 02-peer-protocol.md | 1 - 1 file changed, 1 deletion(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index 16834e5ef..386868f3c 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -849,7 +849,6 @@ The sending node: The receiving node: - if the `witness_stack` length exceeds `max_witness_len`: - MUST error. - - MUST verify it has received valid commitment signatures - SHOULD apply `witness`es to the funding transaction and broadcast it. - if has already sent or received a `funding_locked` message From 5800879c0cc4a3920b2635af35c973e3e4d7312c Mon Sep 17 00:00:00 2001 From: lisa neigut Date: Tue, 28 Jan 2020 10:50:57 -0800 Subject: [PATCH 43/44] fixup: remove redundant/verbose wording --- 02-peer-protocol.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index 386868f3c..4502e2bee 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -607,7 +607,6 @@ This message contains information for inputs to a funding transaction. The sending node: - MUST NOT send `funding_add_input` if it has already transmitted `funding_add_complete` - - MUST send this after `accept_channel2` has been exchanged, but before `funding_add_complete` - MUST add all sent inputs to the funding transaction - MUST NOT re-transmit inputs it has already received from the peer - MUST ensure each `input_info` refers to a non-malleable (segwit) UTXO. @@ -673,7 +672,6 @@ Either node: The sending node: - MUST NOT send `funding_add_output` if it has already transmitted `funding_add_complete` - - MUST send this after `accept_channel2` has been exchanged, but before `funding_add_complete` - MUST add all sent outputs to the funding transaction - MUST ensure the `output_info`.`script` is a standard script - MUST NOT include the channel funding output. From 2e4083893e67d5b44aa7509ea83f73e504990c2e Mon Sep 17 00:00:00 2001 From: lisa neigut Date: Tue, 28 Jan 2020 10:51:21 -0800 Subject: [PATCH 44/44] df: clarify that an input cannot be malleable and add new restriction Makes a non-malleable input more concise, and adds missing restriction that input must be confirmed, i.e. mined. --- 02-peer-protocol.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index 4502e2bee..ec7e835a8 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -622,7 +622,8 @@ The receiving node: - MUST fail the channel if: - it receives a duplicate input to one it sent previously - it receives this message after `funding_add_complete` is received. - - it receives an input that is malleable (P2SH/P2PKH) + - it receives an input that would create a malleable transaction id (e.g. pre-Segwit) + - it receives an unconfirmed input - if is the `opener`: - MUST fail the channel if: - the total count of `input_info`s is greater than 6