From d41cc1ec12851abe064fdec3939a142769bff61c Mon Sep 17 00:00:00 2001 From: Rusty Russell Date: Thu, 12 Aug 2021 14:24:41 +0930 Subject: [PATCH 1/6] Explicitly allow funding_locked early, and support alias scids. This lets you add your brand new channel to routehints, and also means you can use a routehinted channel even if you (later?) have a real channel. This supports both trusted and untrusted zero-conf channels: in the trusted case you can use it immediately like any other channel, and for the untrusted case you simply use any push_msat they gave you for outgoing payments, but fail incoming. Signed-off-by: Rusty Russell --- 02-peer-protocol.md | 64 +++++++++++++++++++++++++++++++++++++++------ 09-features.md | 2 ++ 2 files changed, 58 insertions(+), 8 deletions(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index 445b1f54b..01b0956e2 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -465,25 +465,61 @@ is negotiated. This message indicates that the funding transaction has reached the `minimum_depth` asked for in `accept_channel`. Once both nodes have sent this, the channel enters normal operating mode. +Nodes which have funded the channel, or trust their peers to have +done, or wish to use `push_msat` from other side's opening (without +accepting incoming HTLCs) can simply start using the channel instantly +by sending `funding_locked`. + + 1. type: 36 (`funding_locked`) 2. data: * [`channel_id`:`channel_id`] * [`point`:`next_per_commitment_point`] + * [`funding_locked_tlvs`:`tlvs`] + +1. `tlv_stream`: `funding_locked_tlvs` +2. types: + 1. type: 1 (`short_channel_id`) + 2. data: + * [`short_channel_id`:`alias`] #### Requirements -The sender MUST: - - NOT send `funding_locked` unless outpoint of given by `funding_txid` and +The sender: + - MUST NOT send `funding_locked` unless outpoint of given by `funding_txid` and `funding_output_index` in the `funding_created` message pays exactly `funding_satoshis` to the scriptpubkey specified in [BOLT #3](03-transactions.md#funding-transaction-output). - - wait until the funding transaction has reached `minimum_depth` before - sending this message. - - set `next_per_commitment_point` to the per-commitment point to be used - for the following commitment transaction, derived as specified in + - MUST set `next_per_commitment_point` to the per-commitment point to be used + for commitment transaction #1, derived as specified in [BOLT #3](03-transactions.md#per-commitment-secret-requirements). + - if `option_scid_alias` was negotiated: + - MUST set `short_channel_id` `alias`. + - otherwise: + - SHOULD set `short_channel_id` `alias`. + - if it sets `alias`: + - if the `announce_channel` bit was set in `open_channel`: + - SHOULD initially set `alias` to value not related to the real `short_channel_id`. + - otherwise: + - MUST set `alias` to a value not related to the real `short_channel_id`. + - MUST NOT send the same `alias` for multiple peers or use an alias which + collides with a `short_channel_id` of a channel on the same node. + - MUST always recognize the `alias` as a `short_channel_id` for incoming HTLCs to this channel. + - if `option_scid_alias` was negotiated and `announce_channel` bit was not set in `open_channel`: + - MUST NOT allow incoming HTLCs to this channel using the real `short_channel_id` + - MAY send multiple `funding_locked` messages with different `alias` values. + - otherwise: + - MUST wait until the funding transaction has reached `minimum_depth` before sending this message. + + +The sender: A non-funding node (fundee): - SHOULD forget the channel if it does not see the correct funding - transaction after a timeout of 2016 blocks. + transaction after a timeout of 2016 blocks. + +The receiver: + - MAY use any of the `alias` it received, in BOLT 11 `r` fields. + - if `option_scid_alias` was negotiated and the `announce_channel` bit was not set in `open_channel`: + - MUST NOT use the real `short_channel_id` in BOLT 11 `r` fields. From the point of waiting for `funding_locked` onward, either node MAY send an `error` and fail the channel if it does not receive a required response from the @@ -501,6 +537,17 @@ to broadcast the commitment transaction to get his funds back and open a new channel. To avoid this, the funder should ensure the funding transaction confirms in the next 2016 blocks. +The `alias` here is both required for routing (since there real +short_channel_id is unknown until confirmation), and useful to provide +one or more aliases, even once there is a real `short_channel_id` for +a public channel. + +While a node can send multiple `alias`, it must remember all of the +ones it has sent so it can use them should they be requested by +incoming HTLCs. The recipient only need remember one, for use in +`r` route hints in BOLT 11 invoices. + + ## Channel Close Nodes can negotiate a mutual close of the connection, which unlike a @@ -1369,7 +1416,8 @@ A node: sent and received: - MUST retransmit `funding_locked`. - otherwise: - - MUST NOT retransmit `funding_locked`. + - MUST NOT retransmit `funding_locked`, but MAY send `funding_locked` with + a different `short_channel_id` `alias` field. - upon reconnection: - MUST ignore any redundant `funding_locked` it receives. - if `next_commitment_number` is equal to the commitment number of diff --git a/09-features.md b/09-features.md index 814094f0d..a2f3d7670 100644 --- a/09-features.md +++ b/09-features.md @@ -42,6 +42,7 @@ The Context column decodes as follows: | 22/23 | `option_anchors_zero_fee_htlc_tx` | Anchor commitment type with zero fee HTLC transactions | IN | `option_static_remotekey` | [BOLT #3][bolt03-htlc-tx], [lightning-dev][ml-sighash-single-harmful]| | 26/27 | `option_shutdown_anysegwit` | Future segwit versions allowed in `shutdown` | IN | | [BOLT #2][bolt02-shutdown] | | 44/45 | `option_channel_type` | Node supports the `channel_type` field in open/accept | IN | | [BOLT #2](02-peer-protocol.md#the-open_channel-message) | +| 46/47 | `option_scid_alias` | Supply channel aliases for routing | IN | | [BOLT #2][bolt02-funding-locked] | | 48/49 | `option_payment_metadata` | Payment metadata in tlv record | 9 | | [BOLT #11](11-payment-encoding.md#tagged-fields) ## Definitions @@ -90,6 +91,7 @@ This work is licensed under a [Creative Commons Attribution 4.0 International Li [bolt02-open]: 02-peer-protocol.md#the-open_channel-message [bolt03-htlc-tx]: 03-transactions.md#htlc-timeout-and-htlc-success-transactions [bolt02-shutdown]: 02-peer-protocol.md#closing-initiation-shutdown +[bolt02-funding-locked]: 02-peer-protocol.md#the-funding_locked-message [bolt04]: 04-onion-routing.md [bolt07-sync]: 07-routing-gossip.md#initial-sync [bolt07-query]: 07-routing-gossip.md#query-messages From faa6c413b95de39edbf794e02ace0b144b88bcc7 Mon Sep 17 00:00:00 2001 From: Rusty Russell Date: Tue, 19 Oct 2021 14:13:37 +1030 Subject: [PATCH 2/6] BOLT 2: Restore minimum_depth requirement, but explicitly allow 0. And weaken it: the opener doesn't need to respect it. Note also that the `funding_locked`-can-change-alias refers to the same peer. Signed-off-by: Rusty Russell --- 02-peer-protocol.md | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index 01b0956e2..7978044e0 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -346,6 +346,7 @@ the `open_channel` message. The sender: - SHOULD set `minimum_depth` to a number of blocks it considers reasonable to avoid double-spending of the funding transaction. + - MAY set `minimum_depth` to zero if it trusts the peer. - MUST set `channel_reserve_satoshis` greater than or equal to `dust_limit_satoshis` from the `open_channel` message. - MUST set `dust_limit_satoshis` less than or equal to `channel_reserve_satoshis` from the `open_channel` message. - if it sets `channel_type`: @@ -465,11 +466,9 @@ is negotiated. This message indicates that the funding transaction has reached the `minimum_depth` asked for in `accept_channel`. Once both nodes have sent this, the channel enters normal operating mode. -Nodes which have funded the channel, or trust their peers to have -done, or wish to use `push_msat` from other side's opening (without -accepting incoming HTLCs) can simply start using the channel instantly -by sending `funding_locked`. - +Note that `minimum_depth` can be 0 if the accepter trusts the opener, +in which case this message is a misnomer. The opener is free to send this +message at any time (since it presumably trusts itself). 1. type: 36 (`funding_locked`) 2. data: @@ -488,13 +487,16 @@ by sending `funding_locked`. The sender: - MUST NOT send `funding_locked` unless outpoint of given by `funding_txid` and `funding_output_index` in the `funding_created` message pays exactly `funding_satoshis` to the scriptpubkey specified in [BOLT #3](03-transactions.md#funding-transaction-output). + - if it is not the node opening the channel: + - SHOULD wait until the funding transaction has reached `minimum_depth` before + sending this message. - MUST set `next_per_commitment_point` to the per-commitment point to be used for commitment transaction #1, derived as specified in [BOLT #3](03-transactions.md#per-commitment-secret-requirements). - if `option_scid_alias` was negotiated: - MUST set `short_channel_id` `alias`. - otherwise: - - SHOULD set `short_channel_id` `alias`. + - MAY set `short_channel_id` `alias`. - if it sets `alias`: - if the `announce_channel` bit was set in `open_channel`: - SHOULD initially set `alias` to value not related to the real `short_channel_id`. @@ -505,7 +507,7 @@ The sender: - MUST always recognize the `alias` as a `short_channel_id` for incoming HTLCs to this channel. - if `option_scid_alias` was negotiated and `announce_channel` bit was not set in `open_channel`: - MUST NOT allow incoming HTLCs to this channel using the real `short_channel_id` - - MAY send multiple `funding_locked` messages with different `alias` values. + - MAY send multiple `funding_locked` messages to the same peer with different `alias` values. - otherwise: - MUST wait until the funding transaction has reached `minimum_depth` before sending this message. @@ -547,7 +549,6 @@ ones it has sent so it can use them should they be requested by incoming HTLCs. The recipient only need remember one, for use in `r` route hints in BOLT 11 invoices. - ## Channel Close Nodes can negotiate a mutual close of the connection, which unlike a From 7aa76b67b261d56310c37910d95d9934357380bd Mon Sep 17 00:00:00 2001 From: Rusty Russell Date: Tue, 26 Oct 2021 06:33:35 +1030 Subject: [PATCH 3/6] BOLT 2: add channel_type for option_scid_alias Allows upgrade in future. Signed-off-by: Rusty Russell --- 02-peer-protocol.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index 7978044e0..dca06f889 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -207,12 +207,15 @@ definitions they reuse even feature bits, but they are not an arbitrary combination (they represent the persistent features which affect the channel operation). -The currently defined types are: +The currently defined basic types are: - no features (no bits set) - `option_static_remotekey` (bit 12) - `option_anchor_outputs` and `option_static_remotekey` (bits 20 and 12) - `option_anchors_zero_fee_htlc_tx` and `option_static_remotekey` (bits 22 and 12) +Each basic type has the following variations allowed: + - `option_scid_alias` (bit 46) + #### Requirements The sending node: @@ -239,6 +242,8 @@ The sending node: - MUST set it to a defined type representing the type it wants. - MUST use the smallest bitmap possible to represent the channel type. - SHOULD NOT set it to a type containing a feature which was not negotiated. + - if `announce_channel` is `true` (not `0`): + - MUST NOT send `channel_type` with the `option_scid_alias` bit set. The sending node SHOULD: - set `to_self_delay` sufficient to ensure the sender can irreversibly spend a commitment transaction output, in case of misbehavior by the receiver. @@ -505,7 +510,7 @@ The sender: - MUST NOT send the same `alias` for multiple peers or use an alias which collides with a `short_channel_id` of a channel on the same node. - MUST always recognize the `alias` as a `short_channel_id` for incoming HTLCs to this channel. - - if `option_scid_alias` was negotiated and `announce_channel` bit was not set in `open_channel`: + - if `channel_type` has `option_scid_alias` set: - MUST NOT allow incoming HTLCs to this channel using the real `short_channel_id` - MAY send multiple `funding_locked` messages to the same peer with different `alias` values. - otherwise: @@ -520,7 +525,7 @@ A non-funding node (fundee): The receiver: - MAY use any of the `alias` it received, in BOLT 11 `r` fields. - - if `option_scid_alias` was negotiated and the `announce_channel` bit was not set in `open_channel`: + - if `channel_type` has `option_scid_alias` set: - MUST NOT use the real `short_channel_id` in BOLT 11 `r` fields. From the point of waiting for `funding_locked` onward, either node MAY From f8e5c92fb54e45ebebba366268996e4399117d44 Mon Sep 17 00:00:00 2001 From: Rusty Russell Date: Tue, 9 Nov 2021 13:42:14 +1030 Subject: [PATCH 4/6] channel_update: make sure we use alias scids correctly. Signed-off-by: Rusty Russell --- 04-onion-routing.md | 9 +++++++++ 07-routing-gossip.md | 2 ++ 2 files changed, 11 insertions(+) diff --git a/04-onion-routing.md b/04-onion-routing.md index 2d360d356..e35cc7f0b 100644 --- a/04-onion-routing.md +++ b/04-onion-routing.md @@ -1114,6 +1114,15 @@ An _intermediate hop_ MUST NOT, but the _final node_: - if the `amt_to_forward` does NOT correspond with the `incoming_htlc_amt` from the final node's HTLC: - MUST return a `final_incorrect_htlc_amount` error. + - if it returns a `channel_update`: + - MUST set `short_channel_id` to the `short_channel_id` used by the incoming onion. + +### Rationale + +In the case of multiple short_channel_id aliases, the `channel_update` +`short_channel_id` should refer to the one the original sender is +expecting, to both avoid confusion and to avoid leaking information +about other aliases (or the real location of the channel UTXO). ## Receiving Failure Codes diff --git a/07-routing-gossip.md b/07-routing-gossip.md index d89287e8e..5aa3f5dad 100644 --- a/07-routing-gossip.md +++ b/07-routing-gossip.md @@ -449,6 +449,8 @@ The origin node: - MAY create a `channel_update` to communicate the channel parameters to the channel peer, even though the channel has not yet been announced (i.e. the `announce_channel` bit was not set). + - MUST set the `short_channel_id` to either an `alias` it has + received from the peer, or the real channel `short_channel_id`. - MUST NOT forward such a `channel_update` to other peers, for privacy reasons. - Note: such a `channel_update`, one not preceded by a From 7a812cf077061fcfa4ca7d5abe36cc8a14959939 Mon Sep 17 00:00:00 2001 From: Rusty Russell Date: Tue, 15 Feb 2022 10:42:28 +1030 Subject: [PATCH 5/6] Make zeroconf a channel type, and acceptance indicates trust. Signed-off-by: Rusty Russell --- 02-peer-protocol.md | 12 ++++++++---- 09-features.md | 1 + 2 files changed, 9 insertions(+), 4 deletions(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index dca06f889..667b3c6de 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -215,6 +215,7 @@ The currently defined basic types are: Each basic type has the following variations allowed: - `option_scid_alias` (bit 46) + - `option_zeroconf` (bit 50) #### Requirements @@ -281,7 +282,9 @@ are not valid secp256k1 pubkeys in compressed format. - the funder's amount for the initial commitment transaction is not sufficient for full [fee payment](03-transactions.md#fee-payment). - both `to_local` and `to_remote` amounts for the initial commitment transaction are less than or equal to `channel_reserve_satoshis` (see [BOLT 3](03-transactions.md#commitment-transaction-outputs)). - `funding_satoshis` is greater than or equal to 2^24 and the receiver does not support `option_support_large_channel`. - - It supports `channel_type`, `channel_type` was set, and the `type` is not suitable. + - It supports `channel_type` and `channel_type` was set: + - if `type` is not suitable. + - if `type` includes `option_zeroconf` and it does not trust the sender to open an unconfirmed channel. The receiving node MUST NOT: - consider funds received, using `push_msat`, to be received until the funding transaction has reached sufficient depth. @@ -349,9 +352,10 @@ The `temporary_channel_id` MUST be the same as the `temporary_channel_id` in the `open_channel` message. The sender: - - SHOULD set `minimum_depth` to a number of blocks it considers reasonable to -avoid double-spending of the funding transaction. - - MAY set `minimum_depth` to zero if it trusts the peer. + - if `channel_type` includes `option_zeroconf`: + - MUST set `minimum_depth` to zero. + - otherwise: + - SHOULD set `minimum_depth` to a number of blocks it considers reasonable to avoid double-spending of the funding transaction. - MUST set `channel_reserve_satoshis` greater than or equal to `dust_limit_satoshis` from the `open_channel` message. - MUST set `dust_limit_satoshis` less than or equal to `channel_reserve_satoshis` from the `open_channel` message. - if it sets `channel_type`: diff --git a/09-features.md b/09-features.md index a2f3d7670..5f322ca8d 100644 --- a/09-features.md +++ b/09-features.md @@ -44,6 +44,7 @@ The Context column decodes as follows: | 44/45 | `option_channel_type` | Node supports the `channel_type` field in open/accept | IN | | [BOLT #2](02-peer-protocol.md#the-open_channel-message) | | 46/47 | `option_scid_alias` | Supply channel aliases for routing | IN | | [BOLT #2][bolt02-funding-locked] | | 48/49 | `option_payment_metadata` | Payment metadata in tlv record | 9 | | [BOLT #11](11-payment-encoding.md#tagged-fields) +| 50/51 | `option_zeroconf` | Understands zeroconf channel types | IN | `option_scid_alias` | [BOLT #2][bolt02-funding-locked] | ## Definitions From 34e9cd99dba8d2f562bc63500bacae4b50223a98 Mon Sep 17 00:00:00 2001 From: Rusty Russell Date: Tue, 15 Feb 2022 11:02:01 +1030 Subject: [PATCH 6/6] Rename `funding_locked` to `channel_ready`. And `next_per_commitment_point` to explictly `second_per_commitment_point`; this is particularly important since `channel_ready` can be retransmitted after the channel has been in use, for example. Signed-off-by: Rusty Russell --- 02-peer-protocol.md | 51 ++++++++++++++++++++++---------------------- 07-routing-gossip.md | 10 ++++----- 09-features.md | 6 +++--- 3 files changed, 33 insertions(+), 34 deletions(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index 667b3c6de..4fc760f96 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -12,7 +12,7 @@ operation, and closing. * [The `accept_channel` Message](#the-accept_channel-message) * [The `funding_created` Message](#the-funding_created-message) * [The `funding_signed` Message](#the-funding_signed-message) - * [The `funding_locked` Message](#the-funding_locked-message) + * [The `channel_ready` Message](#the-channel_ready-message) * [Channel Close](#channel-close) * [Closing Initiation: `shutdown`](#closing-initiation-shutdown) * [Closing Negotiation: `closing_signed`](#closing-negotiation-closing_signed) @@ -70,8 +70,8 @@ must broadcast the funding transaction to the Bitcoin network. After the `funding_signed` message is sent/received, both sides should wait for the funding transaction to enter the blockchain and reach the specified depth (number of confirmations). After both sides have sent -the `funding_locked` message, the channel is established and can begin -normal operation. The `funding_locked` message includes information +the `channel_ready` message, the channel is established and can begin +normal operation. The `channel_ready` message includes information that will be used to construct channel authentication proofs. @@ -82,8 +82,8 @@ that will be used to construct channel authentication proofs. | A |--(3)-- funding_created --->| B | | |<-(4)-- funding_signed -----| | | | | | - | |--(5)--- funding_locked ---->| | - | |<-(6)--- funding_locked -----| | + | |--(5)--- channel_ready ---->| | + | |<-(6)--- channel_ready -----| | +-------+ +-------+ - where node A is 'funder' and node B is 'fundee' @@ -471,21 +471,20 @@ use `option_static_remotekey`, `option_anchor_outputs` or `option_static_remotekey`, and the superior one is favored if more than one is negotiated. -### The `funding_locked` Message +### The `channel_ready` Message -This message indicates that the funding transaction has reached the `minimum_depth` asked for in `accept_channel`. Once both nodes have sent this, the channel enters normal operating mode. +This message (which used to be called `funding_locked`) indicates that the funding transaction has sufficient confirms for channel use. Once both nodes have sent this, the channel enters normal operating mode. -Note that `minimum_depth` can be 0 if the accepter trusts the opener, -in which case this message is a misnomer. The opener is free to send this -message at any time (since it presumably trusts itself). +Note that the opener is free to send this message at any time (since it presumably trusts itself), but the +accepter would usually wait until the funding has reached the `minimum_depth` asked for in `accept_channel`. -1. type: 36 (`funding_locked`) +1. type: 36 (`channel_ready`) 2. data: * [`channel_id`:`channel_id`] - * [`point`:`next_per_commitment_point`] - * [`funding_locked_tlvs`:`tlvs`] + * [`point`:`second_per_commitment_point`] + * [`channel_ready_tlvs`:`tlvs`] -1. `tlv_stream`: `funding_locked_tlvs` +1. `tlv_stream`: `channel_ready_tlvs` 2. types: 1. type: 1 (`short_channel_id`) 2. data: @@ -494,12 +493,12 @@ message at any time (since it presumably trusts itself). #### Requirements The sender: - - MUST NOT send `funding_locked` unless outpoint of given by `funding_txid` and + - MUST NOT send `channel_ready` unless outpoint of given by `funding_txid` and `funding_output_index` in the `funding_created` message pays exactly `funding_satoshis` to the scriptpubkey specified in [BOLT #3](03-transactions.md#funding-transaction-output). - if it is not the node opening the channel: - SHOULD wait until the funding transaction has reached `minimum_depth` before sending this message. - - MUST set `next_per_commitment_point` to the per-commitment point to be used + - MUST set `second_per_commitment_point` to the per-commitment point to be used for commitment transaction #1, derived as specified in [BOLT #3](03-transactions.md#per-commitment-secret-requirements). - if `option_scid_alias` was negotiated: @@ -516,7 +515,7 @@ The sender: - MUST always recognize the `alias` as a `short_channel_id` for incoming HTLCs to this channel. - if `channel_type` has `option_scid_alias` set: - MUST NOT allow incoming HTLCs to this channel using the real `short_channel_id` - - MAY send multiple `funding_locked` messages to the same peer with different `alias` values. + - MAY send multiple `channel_ready` messages to the same peer with different `alias` values. - otherwise: - MUST wait until the funding transaction has reached `minimum_depth` before sending this message. @@ -532,7 +531,7 @@ The receiver: - if `channel_type` has `option_scid_alias` set: - MUST NOT use the real `short_channel_id` in BOLT 11 `r` fields. -From the point of waiting for `funding_locked` onward, either node MAY +From the point of waiting for `channel_ready` onward, either node MAY send an `error` and fail the channel if it does not receive a required response from the other node after a reasonable timeout. @@ -598,7 +597,7 @@ along with the `scriptpubkey` it wants to be paid to. A sending node: - if it hasn't sent a `funding_created` (if it is a funder) or a `funding_signed` (if it is a fundee): - MUST NOT send a `shutdown` - - MAY send a `shutdown` before a `funding_locked`, i.e. before the funding transaction has reached `minimum_depth`. + - MAY send a `shutdown` before a `channel_ready`, i.e. before the funding transaction has reached `minimum_depth`. - if there are updates pending on the receiving node's commitment transaction: - MUST NOT send a `shutdown`. - MUST NOT send an `update_add_htlc` after a `shutdown`. @@ -620,7 +619,7 @@ A receiving node: - SHOULD send an `error` and fail the channel. - if the `scriptpubkey` is not in one of the above forms: - SHOULD send a `warning`. - - if it hasn't sent a `funding_locked` yet: + - if it hasn't sent a `channel_ready` yet: - MAY reply to a `shutdown` message with a `shutdown` - once there are no outstanding updates on the peer, UNLESS it has already sent a `shutdown`: - MUST reply to a `shutdown` message with a `shutdown` @@ -770,7 +769,7 @@ the closing transaction will likely never reach miners. ## Normal Operation -Once both nodes have exchanged `funding_locked` (and optionally [`announcement_signatures`](07-routing-gossip.md#the-announcement_signatures-message)), the channel can be used to make payments via Hashed Time Locked Contracts. +Once both nodes have exchanged `channel_ready` (and optionally [`announcement_signatures`](07-routing-gossip.md#the-announcement_signatures-message)), the channel can be used to make payments via Hashed Time Locked Contracts. Changes are sent in batches: one or more `update_` messages are sent before a `commitment_signed` message, as in the following diagram: @@ -1424,12 +1423,12 @@ The sending node: A node: - if `next_commitment_number` is 1 in both the `channel_reestablish` it sent and received: - - MUST retransmit `funding_locked`. + - MUST retransmit `channel_ready`. - otherwise: - - MUST NOT retransmit `funding_locked`, but MAY send `funding_locked` with + - MUST NOT retransmit `channel_ready`, but MAY send `channel_ready` with a different `short_channel_id` `alias` field. - upon reconnection: - - MUST ignore any redundant `funding_locked` it receives. + - MUST ignore any redundant `channel_ready` it receives. - if `next_commitment_number` is equal to the commitment number of the last `commitment_signed` message the receiving node has sent: - MUST reuse the same commitment number for its next `commitment_signed`. @@ -1497,7 +1496,7 @@ atomic: if it doesn't complete, it starts again. The only exception is if the `funding_signed` message is sent but not received. In this case, the funder will forget the channel, and presumably open a new one upon reconnection; meanwhile, the other node will eventually forget -the original channel, due to never receiving `funding_locked` or seeing +the original channel, due to never receiving `channel_ready` or seeing the funding transaction on-chain. There's no acknowledgment for `error`, so if a reconnect occurs it's @@ -1533,7 +1532,7 @@ commitment number 0 is created during opening. `commitment_signed` for commitment number 1 is send and then the revocation for commitment number 0 is received. -`funding_locked` is implicitly acknowledged by the start of normal +`channel_ready` is implicitly acknowledged by the start of normal operation, which is known to have begun after a `commitment_signed` has been received — hence, the test for a `next_commitment_number` greater than 1. diff --git a/07-routing-gossip.md b/07-routing-gossip.md index 5aa3f5dad..8b74fdc5c 100644 --- a/07-routing-gossip.md +++ b/07-routing-gossip.md @@ -85,7 +85,7 @@ The `announcement_signatures` message is created by constructing a `channel_anno A node: - if the `open_channel` message has the `announce_channel` bit set AND a `shutdown` message has not been sent: - MUST send the `announcement_signatures` message. - - MUST NOT send `announcement_signatures` messages until `funding_locked` + - MUST NOT send `announcement_signatures` messages until `channel_ready` has been sent and received AND the funding transaction has at least six confirmations. - otherwise: - MUST NOT send the `announcement_signatures` message. @@ -104,8 +104,8 @@ A recipient node: `error` and fail the channel. - if it has sent AND received a valid `announcement_signatures` message: - SHOULD queue the `channel_announcement` message for its peers. - - if it has not sent funding_locked: - - MAY defer handling the announcement_signatures until after it has sent funding_locked + - if it has not sent `channel_ready`: + - MAY defer handling the announcement_signatures until after it has sent `channel_ready` - otherwise: - MUST ignore it. @@ -167,7 +167,7 @@ The origin node: - for the _Bitcoin blockchain_: - MUST set `chain_hash` value (encoded in hex) equal to `6fe28c0ab6f1b372c1a6a246ae63f74f931e8365e15a089c68d6190000000000`. - MUST set `short_channel_id` to refer to the confirmed funding transaction, - as specified in [BOLT #2](02-peer-protocol.md#the-funding_locked-message). + as specified in [BOLT #2](02-peer-protocol.md#the-channel_ready-message). - Note: the corresponding output MUST be a P2WSH, as described in [BOLT #3](03-transactions.md#funding-transaction-output). - MUST set `node_id_1` and `node_id_2` to the public keys of the two nodes operating the channel, such that `node_id_1` is the lexicographically-lesser of the @@ -445,7 +445,7 @@ or `node_id_2` otherwise. ### Requirements The origin node: - - MUST NOT send a created `channel_update` before `funding_locked` has been received. + - MUST NOT send a created `channel_update` before `channel_ready` has been received. - MAY create a `channel_update` to communicate the channel parameters to the channel peer, even though the channel has not yet been announced (i.e. the `announce_channel` bit was not set). diff --git a/09-features.md b/09-features.md index 5f322ca8d..f237864f6 100644 --- a/09-features.md +++ b/09-features.md @@ -42,9 +42,9 @@ The Context column decodes as follows: | 22/23 | `option_anchors_zero_fee_htlc_tx` | Anchor commitment type with zero fee HTLC transactions | IN | `option_static_remotekey` | [BOLT #3][bolt03-htlc-tx], [lightning-dev][ml-sighash-single-harmful]| | 26/27 | `option_shutdown_anysegwit` | Future segwit versions allowed in `shutdown` | IN | | [BOLT #2][bolt02-shutdown] | | 44/45 | `option_channel_type` | Node supports the `channel_type` field in open/accept | IN | | [BOLT #2](02-peer-protocol.md#the-open_channel-message) | -| 46/47 | `option_scid_alias` | Supply channel aliases for routing | IN | | [BOLT #2][bolt02-funding-locked] | +| 46/47 | `option_scid_alias` | Supply channel aliases for routing | IN | | [BOLT #2][bolt02-channel-ready] | | 48/49 | `option_payment_metadata` | Payment metadata in tlv record | 9 | | [BOLT #11](11-payment-encoding.md#tagged-fields) -| 50/51 | `option_zeroconf` | Understands zeroconf channel types | IN | `option_scid_alias` | [BOLT #2][bolt02-funding-locked] | +| 50/51 | `option_zeroconf` | Understands zeroconf channel types | IN | `option_scid_alias` | [BOLT #2][bolt02-channel-ready] | ## Definitions @@ -92,7 +92,7 @@ This work is licensed under a [Creative Commons Attribution 4.0 International Li [bolt02-open]: 02-peer-protocol.md#the-open_channel-message [bolt03-htlc-tx]: 03-transactions.md#htlc-timeout-and-htlc-success-transactions [bolt02-shutdown]: 02-peer-protocol.md#closing-initiation-shutdown -[bolt02-funding-locked]: 02-peer-protocol.md#the-funding_locked-message +[bolt02-channel-ready]: 02-peer-protocol.md#the-channel_ready-message [bolt04]: 04-onion-routing.md [bolt07-sync]: 07-routing-gossip.md#initial-sync [bolt07-query]: 07-routing-gossip.md#query-messages