BOLT 7: variable message onion message support.

rustyrussell · rustyrussell · commit c573e04676fa · 2021-04-16T14:41:14.000+09:30
These use onion encoding for simple one-way messaging: there are no error returns.

Any reply is done with an enclosed blinded path.

Note that this defines the message system, not the contents of messages
(e.g. invoice requests from offers).

Signed-off-by: Rusty Russell &lt;rusty@rustcorp.com.au&gt;
diff --git a/01-messaging.md b/01-messaging.md
@@ -49,7 +49,7 @@ The messages are grouped logically into five groups, ordered by the most signifi
   - Setup & Control (types `0`-`31`): messages related to connection setup, control, supported features, and error reporting (described below)
   - Channel (types `32`-`127`): messages used to setup and tear down micropayment channels (described in [BOLT #2](02-peer-protocol.md))
   - Commitment (types `128`-`255`): messages related to updating the current commitment transaction, which includes adding, revoking, and settling HTLCs as well as updating fees and exchanging signatures (described in [BOLT #2](02-peer-protocol.md))
-  - Routing (types `256`-`511`): messages containing node and channel announcements, as well as any active route exploration (described in [BOLT #7](07-routing-gossip.md))
+  - Routing (types `256`-`511`): messages containing node and channel announcements, as well as any active route exploration or messaging (described in [BOLT #7](07-routing-gossip.md))
   - Custom (types `32768`-`65535`): experimental and application-specific messages
 
 The size of the message is required by the transport layer to fit into a 2-byte unsigned int; therefore, the maximum possible size is 65535 bytes.
diff --git a/04-onion-routing.md b/04-onion-routing.md
@@ -51,6 +51,7 @@ A node:
     * [Legacy HopData Payload Format](#legacy-hop_data-payload-format)
     * [TLV Payload Format](#tlv_payload-format)
     * [Basic Multi-Part Payments](#basic-multi-part-payments)
+    * [Onion Messages](#onion-messages)
   * [Accepting and Forwarding a Payment](#accepting-and-forwarding-a-payment)
     * [Payload for the Last Node](#payload-for-the-last-node)
     * [Non-strict Forwarding](#non-strict-forwarding)
@@ -367,6 +368,86 @@ otherwise meets the amount criterion (eg. some other failure, or
 invoice timeout), however if it were to fulfill only some of them,
 intermediary nodes could simply claim the remaining ones.
 
+### Onion Messages
+
+Onion messages have an onion with an alternate `hop_payload`
+format: a `bigsize` followed by a `onionmsg_payload`.  Note that there
+is no legacy format, thus a `bigsize` of 0 means no payload.
+
+1. tlvs: `onionmsg_payload`
+2. types:
+    1. type: 4 (`next_node_id`)
+    2. data:
+        * [`point`:`node_id`]
+    1. type: 6 (`next_short_channel_id`)
+    2. data:
+        * [`short_channel_id`:`short_channel_id`]
+    1. type: 8 (`reply_path`)
+    2. data:
+        * [`point`:`blinding`]
+        * [`...*onionmsg_path`:`path`]
+    1. type: 10 (`enctlv`)
+    2. data:
+        * [`...*byte`:`enctlv`]
+    1. type: 12 (`blinding`)
+    2. data:
+        * [`point`:`blinding`]
+
+1. tlvs: `encmsg_tlvs`
+2. types:
+    1. type: 4 (`next_node_id`)
+    2. data:
+        * [`point`:`node_id`]
+    1. type: 6 (`next_short_channel_id`)
+    2. data:
+        * [`short_channel_id`:`short_channel_id`]
+
+1. subtype: `onionmsg_path`
+2. data:
+    * [`point`:`node_id`]
+    * [`u16`:`enclen`]
+    * [`enclen*byte`:`enctlv`]
+
+#### Requirements
+
+The writer:
+- For the non-final nodes' `onionmsg_payload`:
+  - MUST include exactly one of `next_short_channel_id`, `next_node_id`
+    or `enctlv` indicating the next node.
+- For the final node's `onionmsg_payload`:
+  - if the final node is permitted to reply:
+    - MUST set `reply_path` `blinding` to the initial blinding factor for the `next_node_id`
+    - For the first `reply_path` `path`:
+      - MUST set `node_id` to the first node in the reply path.
+    - For the remaining `reply_path` `path`:
+      - MUST set `node_id` to the blinded node id to encrypt the onion hop for.
+    - Within `reply_path` `path`:
+      - MUST encrypt `enctlv` as detailed in (FIXME: reference to t-bast's blinded path section:
+        `ChaChaPoly-1305` encryption using an all-zero nonce).
+      - MUST set `enctlv` to a valid `encmsg_tlvs` containing exactly one of either
+        `next_node_id` or `next_short_channel_id`.
+  - otherwise:
+    - MUST NOT set `reply_path`.
+
+The reader:
+- if `enctlv` is present:
+  - MUST extract the shared secret from the given `blinding` parameter and decrypt `enctlv`.
+  - MUST drop the message if `enctlv` is not a valid TLV.
+  - MUST use `next_short_channel_id` or `next_node_id` from `enctlv`.
+- Otherwise:
+  - MUST use `next_short_channel_id` or `next_node_id` from  `onionmsg_payload`.
+
+- if it is not the final node according to the onion encryption:
+  - if `next_short_channel_id` or `next_node_id` is found:
+    - SHOULD forward the message using `onion_message` to the indicated peer if possible.
+
+- otherwise:
+  - if it wants to send a reply:
+    - MUST create an onion encoding using `reply_path`.
+    - MUST send the reply via `onion_message` to the node indicated by
+        the first element of `reply_path` `path` using `reply_path` `blinding`.
+
+
 # Accepting and Forwarding a Payment
 
 Once a node has decoded the payload it either accepts the payment locally, or forwards it to the peer indicated as the next hop in the payload.
diff --git a/07-routing-gossip.md b/07-routing-gossip.md
@@ -1,4 +1,4 @@
-# BOLT #7: P2P Node and Channel Discovery
+# BOLT #7: P2P Node and Channel Discovery and Onion Messages
 
 This specification describes simple node discovery, channel discovery, and channel update mechanisms that do not rely on a third-party to disseminate the information.
 
@@ -33,6 +33,7 @@ To support channel and node discovery, three *gossip messages* are supported:
   * [HTLC Fees](#htlc-fees)
   * [Pruning the Network View](#pruning-the-network-view)
   * [Recommendations for Routing](#recommendations-for-routing)
+  * [Onion Messages](#onion-messages)
   * [References](#references)
 
 ## Definition of `short_channel_id`
@@ -1119,7 +1120,58 @@ A->D's `update_add_htlc` message would be:
 And D->C's `update_add_htlc` would again be the same as B->C's direct payment
 above.
 
-## References
+# Onion Messages
+
+Onion messages allow peers to use existing connections to query for
+invoices (see [BOLT 12](12-offer-encoding.md)).  Like gossip messages,
+they are not associated with a particular local channel.  Like HTLCs,
+they use [BOLT 4](04-onion-routing.md#onion-messages) protocol for
+end-to-end encryption.
+
+Onion messages are unreliable: in particular, they are designed to
+be cheap to process and require no storage to forward.  As a result,
+there is no error returned from intermediary nodes.
+
+To enable messaging via blinded paths, there is an optional `blinding`
+parameter which allows decryption of the `enctlv` field inside the
+`onionmsg`'s `onionmsg_payload`.
+
+## The `onion_message` Message
+
+1. type: 385 (`onion_message`) (`option_onion_messages`)
+2. data:
+    * [`u16`:`len`]
+    * [`len*byte`:`onionmsg`]
+    * [`onion_message_tlvs`:`onion_message_tlvs`]
+
+1. tlvs: `onion_message_tlvs`
+2. types:
+    1. type: 2 (`blinding`)
+    2. data:
+        * [`point`:`blinding`]
+
+## Requirements
+
+The writer:
+- MUST populate the per-hop payloads as described in [BOLT 4](04-onion-routing.md#onion-messages).
+- SHOULD retry via a different route if it expects a response and
+  doesn't receive one after a reasonable period.
+- SHOULD set `len` to 1366 or 32834.
+
+The reader:
+- MUST handle the per-hop payloads as described in [BOLT 4](04-onion-routing.md#onion-messages).
+- SHOULD accept onion messages from peers without an established channel.
+- MAY rate-limit messages by dropping them.
+
+## Rationale
+
+`len` allows larger messages to be sent than the standard 1300 bytes
+allowed for an HTLC onion, but this should be used sparingly as it is
+reduces anonymity set, hence the recommendation that it either look
+like an HTLC onion, or if larger, be a fixed size.
+
+
+# References
 
 1. <a id="reference-1">[RFC 1950 "ZLIB Compressed Data Format Specification version 3.3](https://www.ietf.org/rfc/rfc1950.txt)</a>
 2. <a id="reference-2">[Maximum Compression Factor](https://zlib.net/zlib_tech.html)</a>
diff --git a/09-features.md b/09-features.md
@@ -40,6 +40,7 @@ The Context column decodes as follows:
 | 18/19 | `option_support_large_channel`   | Can create large channels                                 | IN       |                   | [BOLT #2](02-peer-protocol.md#the-open_channel-message) |
 | 20/21 | `option_anchor_outputs`          | Anchor outputs                                            | IN       | `option_static_remotekey` | [BOLT #3](03-transactions.md)         |
 | 22/23 | `option_anchors_zero_fee_htlc_tx` | Anchor commitment type with zero fee HTLC transactions   | IN       |                   | [BOLT #3][bolt03-htlc-tx], [lightning-dev][ml-sighash-single-harmful]|
+| 102/103 | `option_onion_messages`        | Can forward onion messages                                | IN9        |                   | [BOLT #7](07-routing-gossip.md#onion-messages) |
 
 ## Requirements
 
