RFC: Onion messages (previously "directed messages")

01-messaging.md

@@ -56,7 +56,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.

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)
@@ -366,6 +367,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 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.

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.
 
@@ -31,6 +31,7 @@ multiple `node_announcement` messages, in order to update the node information.
   * [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`
@@ -1105,6 +1106,47 @@ 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.
 
+# 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 return 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:
+    * [`1366*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.
+
+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.
+
 ## References
 
 1. <a id="reference-1">[RFC 1950 "ZLIB Compressed Data Format Specification version 3.3](https://www.ietf.org/rfc/rfc1950.txt)</a>

09-features.md

@@ -38,6 +38,8 @@ The Context column decodes as follows:
 | 14/15 | `payment_secret`                 | Node supports `payment_secret` field                      | IN9      | `var_onion_optin` | [Routing Onion Specification][bolt04] |
 | 16/17 | `basic_mpp`                      | Node can receive basic multi-part payments                | IN9      | `payment_secret`  | [BOLT #4][bolt04-mpp]                 |
 | 18/19 | `option_support_large_channel`   | Can create large channels                                 | INC+     |                   | [BOLT #2](02-peer-protocol.md#the-open_channel-message) |
+| 102/103 | `option_onion_messages`        | Can forward onion messages                                | INC-     |                   | [BOLT #7](07-routing-gossip.md#onion-messages) |
+
 
 ## Requirements