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 <[email protected]>

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

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