mirrors/lightning-bolts
1
0
Fork 0
mirror of https://github.com/lightning/bolts.git synced 2025-01-18 13:22:35 +01:00
Code Issues Projects Releases Wiki Activity

Rename funding_locked to channel_ready.

Browse Source 
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>
This commit is contained in:
Rusty Russell 2022-02-15 11:02:01 +10:30 committed by Matt Corallo
parent 7a812cf077
commit 34e9cd99db
3 changed files with 33 additions and 34 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

51
02-peer-protocol.md
View File

@ -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.

10
07-routing-gossip.md
View File

@ -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).

6
09-features.md
View File

@ -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