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