Delivery of offered goods

.aspell.en.pws

@@ -386,3 +386,13 @@ csv
 CHECKSIGVERIFY
 IFDUP
 sats
+onionmsg
+Schnorr
+unblinded
+Merkle
+whitespace
+rata
+programatically
+parsable
+TLVs
+AUD

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.
@@ -231,9 +231,11 @@ The following convenience types are also defined:
 * `channel_id`: a 32-byte channel_id (see [BOLT #2](02-peer-protocol.md#definition-of-channel-id))
 * `sha256`: a 32-byte SHA2-256 hash
 * `signature`: a 64-byte bitcoin Elliptic Curve signature
+* `bip340sig`: a 64-byte bitcoin Elliptic Curve Schnorr signature as per [BIP-340](https://github.com/bitcoin/bips/blob/master/bip-0340.mediawiki)
 * `point`: a 33-byte Elliptic Curve point (compressed encoding as per [SEC 1 standard](http://www.secg.org/sec1-v2.pdf#subsubsection.2.3.3))
 * `short_channel_id`: an 8 byte value identifying a channel (see [BOLT #7](07-routing-gossip.md#definition-of-short-channel-id))
 * `bigsize`: a variable-length, unsigned integer similar to Bitcoin's CompactSize encoding, but big-endian.  Described in [BigSize](#appendix-a-bigsize-test-vectors).
+* `utf8`: a byte as part of a UTF-8 string.  A writer MUST ensure an array of these is a valid UTF-8 string, a reader MAY reject any messages containing an array of these which is not a valid UTF-8 string.
 
 ## Setup Messages
 

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,96 @@ 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. type: 64 (`invoice_request`)
+    2. data:
+        * [`...*byte`:`invoice_request`]
+    1. type: 66 (`invoice`)
+    2. data:
+        * [`...*byte`:`invoice`]
+    1. type: 68 (`invoice_error`)
+    2. data:
+        * [`...*byte`:`invoice_error`]
+
+
+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.

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,70 @@ 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 ignore any message which contains a `blinding` which it did not expect, or does not contain
+  a `blinding` when one is expected.
+- 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
+
+`blinding` is critical to the use of blinded paths: there are various
+means by which a blinded path is passed to a node.  The receipt of an
+expected `blinding` indicates that blinded path has been used: it is
+important that a node not accept unblinded messages when it is expecting
+a blinded message, as this implies the sender is probing to detect if
+the recipient is the terminus of the blinded path.
+
+Similarly, since blinded paths don't expire, a node could try to use
+a blinded path to send an unexpected message hoping for a response.
+
+`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>

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