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 <rusty@rustcorp.com.au>
lightning · May 30, 2022 · 34e9cd9 · 34e9cd9
1 parent 7a812cf
commit 34e9cd9
Show file tree

Hide file tree

Showing 3 changed files with 33 additions and 34 deletions.
diff --git 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
@@ -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
@@ -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