Clarify onion spec: part 1 (the uncontroversial bits) #1181

rustyrussell · 2024-07-11T02:48:42Z

@t-bast suggested splitting this off from #1179. It's basically cleanups and formalization, plus renaming blinding to path_key to unconfuse me.

Remove realm references.
Proper requirements for onion decryption (though not encryption), and refer from both places it's needed.
Rename blinding to path_key.

This cleanup is a side-effect of this comment on my post about reworking our code, indicating I'm not the only one who finds it confusing:

https://iris.to/note1yjs79epjx9t54ynhnu9akar4uuz5rem2vluunnksdaq2gnhmjnksvnjkag

3 July
Great summary, but I wish I would've seen this before finishing my initial rough implementation for
#electrum last week :) Getting a full picture of the spec requires quite a lot of trawling through PRs and scattered snippets of pseudocode.

The concatenation of route to introduction point and the blinded path took some time to grasp, but the test vectors in the PR are a nice validation target to work towards.

This was from the legacy onion, and is no longer present. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>

There's currently a *description* of how to decrypt an onion, and some requirements in forwarding. But it also applies to onion messages, so: 1. Turn the description into actual enumerated requirements. 2. Ensure the description covers both payload and messaging onions. 3. Include both methods to apply the blinding tweak. 4. Leave the actual handling of the extracted payload (payment vs messaging onion) to those specific sections (e.g. reporting failure) Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>

…tlc/onion message requirements. This ties it together, saying what to use as associated data, blinding, and what to do on failure. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>

Sure, it's used to derive a secret for blinding, but it's also used to derive the key for encrypted_recipient_data. It's not used as a blinding factor *directly*. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>

t-bast · 2024-07-11T09:32:07Z

That part is indeed uncontroversial and much needed, thanks for doing this! There are a few nits here and there, that I fixed in t-bast@1a9849c if you'd like to cherry-pick. Otherwise, here is the detailed patch. I took this opportunity to bring the LateX rendering fixes from #1158 and #1169 which weren't making progress.

From 1a9849c3f92f1ab1bf42f722f376fd0797901b36 Mon Sep 17 00:00:00 2001
From: t-bast <bastien@acinq.fr>
Date: Thu, 11 Jul 2024 11:27:22 +0200
Subject: [PATCH] Clean-up nits

This commit doesn't change the logic at all, it simply:

- removes `realm` from onion test vector
- cleans-up markdown formatting and indents
- fixes typos and missing parenthesis
- consistently uses `_` instead of `-` for field names
- fixes math formatting (including changes from #1169 and #1158)
---
 02-peer-protocol.md                          |  4 +-
 04-onion-routing.md                          | 59 ++++++++++----------
 bolt04/blinded-onion-message-onion-test.json | 18 +++---
 bolt04/blinded-payment-onion-test.json       | 16 +++---
 bolt04/onion-error-test.json                 | 10 ++--
 bolt04/route-blinding-test.json              |  8 +--
 6 files changed, 57 insertions(+), 58 deletions(-)

diff --git a/02-peer-protocol.md b/02-peer-protocol.md
index 2ae0d07..27b01fe 100644
--- a/02-peer-protocol.md
+++ b/02-peer-protocol.md
@@ -2130,14 +2130,14 @@ A node:
     - MUST NOT send an `update_fulfill_htlc`, `update_fail_htlc`, or
 `update_fail_malformed_htlc`.
   - When failing an incoming HTLC:
-    - If `current_path_key_point` is set in the onion payload and it is not the
+    - If `current_path_key` is set in the onion payload and it is not the
       final node:
       - MUST send an `update_fail_htlc` error using the `invalid_onion_blinding`
         failure code for any local or downstream errors.
       - SHOULD use the `sha256_of_onion` of the onion it received.
       - MAY use an all zero `sha256_of_onion`.
       - SHOULD add a random delay before sending `update_fail_htlc`.
-    - If `path_key_point` is set in the incoming `update_add_htlc`:
+    - If `path_key` is set in the incoming `update_add_htlc`:
       - MUST send an `update_fail_malformed_htlc` error using the
         `invalid_onion_blinding` failure code for any local or downstream errors.
       - SHOULD use the `sha256_of_onion` of the onion it received.
diff --git a/04-onion-routing.md b/04-onion-routing.md
index ba500db..c5a157d 100644
--- a/04-onion-routing.md
+++ b/04-onion-routing.md
@@ -321,7 +321,7 @@ The reader:
       - MUST return an error if incoming `cltv_expiry` < `outgoing_cltv_value`.
       - MUST return an error if incoming `cltv_expiry` < `current_block_height` + `min_final_cltv_expiry_delta`.
   - Otherwise (it is not part of a blinded route):
-    - MUST return an error if `path_key` is set in the incoming `update_add_htlc` or `current_pass` is present.
+    - MUST return an error if `path_key` is set in the incoming `update_add_htlc` or `current_path_key` is present.
     - MUST return an error if `amt_to_forward` or `outgoing_cltv_value` are not present.
     - if it is not the final node:
       - MUST return an error if:
@@ -495,20 +495,20 @@ may contain the following TLV fields:
 A recipient $`N_r`$ creating a blinded route $`N_0 \rightarrow N_1 \rightarrow ... \rightarrow N_r`$ to itself:
 
 - MUST create a blinded node ID $`B_i`$ for each node using the following algorithm:
-  - $`e_0 /leftarrow {0;1}^256`$ ($`e_0`$ SHOULD be obtained via CSPRG)
+  - $`e_0 \leftarrow \{0;1\}^{256}`$ ($`e_0`$ SHOULD be obtained via CSPRNG)
   - $`E_0 = e_0 \cdot G`$
   - For every node in the route:
     - let $`N_i = k_i * G`$ be the `node_id` ($`k_i`$ is $`N_i`$'s private key)
-    - $`ss_i = SHA256(e_i * N_i) = SHA256(k_i * E_i)$` (ECDH shared secret known only by $`N_r`$ and $`N_i`$)
+    - $`ss_i = SHA256(e_i * N_i) = SHA256(k_i * E_i)`$ (ECDH shared secret known only by $`N_r`$ and $`N_i`$)
     - $`B_i = HMAC256(\text{"blinded\_node\_id"}, ss_i) * N_i`$ (blinded `node_id` for $`N_i`$, private key known only by $`N_i`$)
     - $`rho_i = HMAC256(\text{"rho"}, ss_i)`$ (key used to encrypt the payload for $`N_i`$ by $`N_r`$)
     - $`e_{i+1} = SHA256(E_i || ss_i) * e_i`$ (ephemeral private path key, only known by $`N_r`$)
     - $`E_{i+1} = SHA256(E_i || ss_i) * E_i`$ (`path_key`. NB: $`N_i`$ MUST NOT learn $`e_i`$)
 - MAY replace $`E_{i+1}`$ with a different value, but if it does:
-  - MUST set `encrypted_data_tlv[i].next_path_key_override` to `$E_{i+1}$`
+  - MUST set `encrypted_data_tlv[i].next_path_key_override` to $`E_{i+1}`$
 - MAY store private data in `encrypted_data_tlv[r].path_id` to verify that the route is used in the right context and was created by them
 - SHOULD add padding data to ensure all `encrypted_data_tlv[i]` have the same length
-- MUST encrypt each `encrypted_data_tlv[i]` with ChaCha20-Poly1305 using the corresponding `rho_i` key and an all-zero nonce to produce `encrypted_recipient_data[i]`
+- MUST encrypt each `encrypted_data_tlv[i]` with ChaCha20-Poly1305 using the corresponding $`rho_i`$ key and an all-zero nonce to produce `encrypted_recipient_data[i]`
 - MUST communicate the blinded node IDs $`B_i`$ and `encrypted_recipient_data[i]` to the sender
 - MUST communicate the real node ID of the introduction point $`N_0`$ to the sender
 - MUST communicate the first `path_key` $`E_0`$ to the sender
@@ -518,7 +518,7 @@ A reader:
 - If it receives `path_key` ($`E_i`$) from the prior peer:
   - MUST use $`b_i`$ instead of its private key $`k_i`$ to decrypt the onion.
     Note that the node may instead tweak the onion ephemeral key with
-    $`HMAC256(\text{"blinded\_node\_id}", ss_i)`$ which achieves the same result.
+    $`HMAC256(\text{"blinded\_node\_id"}, ss_i)`$ which achieves the same result.
 - Otherwise:
   - MUST use $`k_i`$ to decrypt the onion, to extract `current_path_key` ($`E_i`$).
 - MUST compute:
@@ -557,7 +557,7 @@ keys of the nodes in the route with random public keys while letting senders
 choose what data they put in the onion for each hop. Blinded routes are also
 reusable in some cases (e.g. onion messages).
 
-Each node in the blinded route needs to receive `E_i` to be able to decrypt
+Each node in the blinded route needs to receive $`E_i`$ to be able to decrypt
 the onion and the `encrypted_data` payload. Protocols that use route blinding
 must specify how this value is propagated between nodes.
 
@@ -570,7 +570,7 @@ The final recipient must verify that the blinded route is used in the right
 context (e.g. for a specific payment) and was created by them. Otherwise a
 malicious sender could create different blinded routes to all the nodes that
 they suspect could be the real recipient and try them until one accepts the
-message. The recipient can protect against that by storing `E_r` and the
+message. The recipient can protect against that by storing $`E_r`$ and the
 context (e.g. a `payment_hash`), and verifying that they match when receiving
 the onion. Otherwise, to avoid additional storage cost, it can put some private
 context information in the `path_id` field (e.g. the `payment_preimage`) and
@@ -617,7 +617,7 @@ sent across.
 
 Nodes implementing non-strict forwarding are able to make real-time assessments
 of channel bandwidths with a particular peer, and use the channel that is
-locally-optimal. 
+locally-optimal.
 
 For example, if the channel specified by `short_channel_id` connecting A and B
 does not have enough bandwidth at forwarding time, then A is able use a
@@ -857,9 +857,10 @@ func NewOnionPacket(paymentPath []*btcec.PublicKey, sessionKey *btcec.PrivateKey
 
 # Onion Decryption
 
-There are two kinds of `onion_packet` we use: 
+There are two kinds of `onion_packet` we use:
+
 1. `onion_routing_packet` in `update_add_htlc` for payments, which contains a `payload` TLV (see [Adding an HTLC](02-peer-protocol.md#adding-an-htlc-update_add_htlc))
-2. `onion_message_packet` on `onion_message` for messages, which contains a `onionmsg_tlv` TLV (see [Onion Messages](#onion-messages)
+2. `onion_message_packet` in `onion_message` for messages, which contains an `onionmsg_tlv` TLV (see [Onion Messages](#onion-messages))
 
 Those sections specify the `associated_data` to use, the `path_key` (if any), the extracted payload format and handling (including how to determine the next peer, if any), and how to handle errors.  The processing itself is identical.
 
@@ -871,26 +872,26 @@ A reader:
   - if `public_key` is not a valid pubkey:
     - MUST abort processing the packet and fail.
   - if the onion is for a payment:
-  - if `hmac` has previously been received:
-    - if the preimage is known:
-      - MAY immediately redeem the HTLC using the preimage.
-    - otherwise:
-      - MUST abort processing the packet and fail.
+    - if `hmac` has previously been received:
+      - if the preimage is known:
+        - MAY immediately redeem the HTLC using the preimage.
+      - otherwise:
+        - MUST abort processing the packet and fail.
   - if `path_key` is specified:
-    - Calculate the `blinding_ss` as ECDH(`path_key`, `node-privkey`)
+    - Calculate the `blinding_ss` as ECDH(`path_key`, `node_privkey`).
     - Either:
-      - Tweak `public_key` by multiplying by $`HMAC256(\text{"blinded\_node\_id"}, blinding\_ss)`$
+      - Tweak `public_key` by multiplying by $`HMAC256(\text{"blinded\_node\_id"}, blinding\_ss)`$.
     - or (equivalently):
-      - Tweak its own `node-privkey` below by multiplying by $`HMAC256(\text{"blinded\_node\_id"}, blinding\_ss)`$
- - Derive the shared secret `ss` as ECDH(`public_key`, `node-privkey`) (see [Shared Secret](#shared-secret))
+      - Tweak its own `node_privkey` below by multiplying by $`HMAC256(\text{"blinded\_node\_id"}, blinding\_ss)`$.
+  - Derive the shared secret `ss` as ECDH(`public_key`, `node_privkey`) (see [Shared Secret](#shared-secret)).
   - Derive `mu` as $`HMAC256(\text{"mu"}, ss)`$ (see [Key Generation](#key-generation)).
-  - Derive the HMAC as $`HMAC256(mu, hop_payloads || associated_data)`$
+  - Derive the HMAC as $`HMAC256(mu, hop\_payloads || associated\_data)`$.
   - MUST use a constant time comparison of the computed HMAC and `hmac`.
   - If the computed HMAC and `hmac` differ:
     - MUST abort processing the packet and fail.
   - Derive `rho` as $`HMAC256(\text{"rho"}, ss)`$ (see [Key Generation](#key-generation)).
   - Derive `bytestream` of twice the length of `hop_payloads` using `rho` (see [Pseudo Random Byte Stream](pseudo-random-byte-stream)).
-  - Set `unwrapped_payloads` to the XOR of `hop_payloads` and `bytestream`
+  - Set `unwrapped_payloads` to the XOR of `hop_payloads` and `bytestream`.
   - Remove a `bigsize` from the front of `unwrapped_payloads` as `payload_length`.  If that is malformed:
     - MUST abort processing the packet and fail.
   - If the `payload_length` is less than two:
@@ -904,22 +905,20 @@ A reader:
   - If `unwrapped_payloads` is smaller than `hop_payloads`:
     - MUST abort processing the packet and fail.
   - If `next_hmac` is not all-zero (not the final node):
-    - Derive `blinding_tweak` as $`SHA256(public_key || ss)`$ (see [Blinding Ephemeral Onion Keys](#blinding-ephemeral-onion-keys))
+    - Derive `blinding_tweak` as $`SHA256(public\_key || ss)`$ (see [Blinding Ephemeral Onion Keys](#blinding-ephemeral-onion-keys)).
     - SHOULD forward an onion to the next peer with:
-      - `version` set to 0
-      - `public_key` set to the incoming `public_key` multiplied by `blinding_tweak`
-      - `hop_payloads` set to the `unwrapped_payloads`, truncated to the incoming `hop_payloads` size
-      - `hmac` set to `next_hmac`
+      - `version` set to 0.
+      - `public_key` set to the incoming `public_key` multiplied by `blinding_tweak`.
+      - `hop_payloads` set to the `unwrapped_payloads`, truncated to the incoming `hop_payloads` size.
+      - `hmac` set to `next_hmac`.
     - If it cannot forward:
       - MUST fail.
   - Otherwise (all-zero `next_hmac`):
     - This is the final destination of the onion.
 
-
 ## Rationale
 
-In the case where blinded paths are used, the sender did not actually encrypt this onion for our node_id, but for a tweaked version: we can derive the tweak used from `path_key` which is given alongside the onion.  Then we either tweak our node private key the same way to decrypt the onion, or tweak to the onion ephemeral key which is mathematically equivalent.
-
+In the case where blinded paths are used, the sender did not actually encrypt this onion for our `node_id`, but for a tweaked version: we can derive the tweak used from `path_key` which is given alongside the onion.  Then we either tweak our node private key the same way to decrypt the onion, or tweak to the onion ephemeral key which is mathematically equivalent.
 
 # Filler Generation
 
diff --git a/bolt04/blinded-onion-message-onion-test.json b/bolt04/blinded-onion-message-onion-test.json
index f66660c..fe5191e 100644
--- a/bolt04/blinded-onion-message-onion-test.json
+++ b/bolt04/blinded-onion-message-onion-test.json
@@ -6,12 +6,12 @@
     "hops": [
       {
         "alias": "Alice",
-        "comment": "Alice->Bob: note next_blinding_override to match that give by Dave for Bob",
-        "blinding_secret": "6363636363636363636363636363636363636363636363636363636363636363",
+        "comment": "Alice->Bob: note next_path_key_override to match that give by Dave for Bob",
+        "path_key_secret": "6363636363636363636363636363636363636363636363636363636363636363",
         "tlvs": {
           "next_node_id": "0324653eac434488002cc06bbfb7f10fe18991e35f9fe4302dbea6d2353dc0ab1c",
-          "next_blinding_override": "031b84c5567b126440995d3ed5aaba0565d71e1834604819ff9c17f5e9d5dd078f",
-          "blinding_override_secret": "0101010101010101010101010101010101010101010101010101010101010101"
+          "next_path_key_override": "031b84c5567b126440995d3ed5aaba0565d71e1834604819ff9c17f5e9d5dd078f",
+          "path_key_override_secret": "0101010101010101010101010101010101010101010101010101010101010101"
         },
         "encrypted_data_tlv": "04210324653eac434488002cc06bbfb7f10fe18991e35f9fe4302dbea6d2353dc0ab1c0821031b84c5567b126440995d3ed5aaba0565d71e1834604819ff9c17f5e9d5dd078f",
         "ss": "c04d2a4c518241cb49f2800eea92554cb543f268b4c73f85693541e86d649205",
@@ -26,7 +26,7 @@
       {
         "alias": "Bob",
         "comment": "Bob->Carol",
-        "blinding_secret": "0101010101010101010101010101010101010101010101010101010101010101",
+        "path_key_secret": "0101010101010101010101010101010101010101010101010101010101010101",
         "tlvs": {
           "next_node_id": "027f31ebc5462c1fdce1b737ecff52d37d75dea43ce11c74d25aa297165faa2007",
           "unknown_tag_561": "123456"
@@ -44,7 +44,7 @@
       {
         "alias": "Carol",
         "comment": "Carol->Dave",
-        "blinding_secret": "f7ab6dca6152f7b6b0c9d7c82d716af063d72d8eef8816dfc51a8ae828fa7dce",
+        "path_key_secret": "f7ab6dca6152f7b6b0c9d7c82d716af063d72d8eef8816dfc51a8ae828fa7dce",
         "tlvs": {
           "padding": "0000000000",
           "next_node_id": "032c0b7cf95324a07d05398b240174dc0c2be444d96b159aa6c7f7b1e668680991"
@@ -62,7 +62,7 @@
       {
         "alias": "Dave",
         "comment": "Dave is final node, hence path_id",
-        "blinding_secret": "5de52bb427cc148bf23e509fdc18012004202517e80abcfde21612ae408e6cea",
+        "path_key_secret": "5de52bb427cc148bf23e509fdc18012004202517e80abcfde21612ae408e6cea",
         "tlvs": {
           "padding": "",
           "path_id": "deadbeefbadc0ffeedeadbeefbadc0ffeedeadbeefbadc0ffeedeadbeefbadc0",
@@ -82,8 +82,8 @@
   },
   "route": {
     "comment": "The resulting blinded route Alice to Dave.",
-    "introduction_node_id": "02eec7245d6b7d2ccb30380bfbe2a3648cd7a942653f5aa340edcea1f283686619",
-    "blinding": "031195a8046dcbb8e17034bca630065e7a0982e4e36f6f7e5a8d4554e4846fcd99",
+    "first_node_id": "02eec7245d6b7d2ccb30380bfbe2a3648cd7a942653f5aa340edcea1f283686619",
+    "first_path_key": "031195a8046dcbb8e17034bca630065e7a0982e4e36f6f7e5a8d4554e4846fcd99",
     "hops": [
       {
         "blinded_node_id": "02d1c3d73f8cac67e7c5b6ec517282d5ba0a52b06a29ec92ff01e12decf76003c1",
diff --git a/bolt04/blinded-payment-onion-test.json b/bolt04/blinded-payment-onion-test.json
index 97406fb..aa6c5b6 100644
--- a/bolt04/blinded-payment-onion-test.json
+++ b/bolt04/blinded-payment-onion-test.json
@@ -14,8 +14,8 @@
         },
         "blinded_route": {
             "comment": "This section contains a blinded route that the sender will use for his payment, usually obtained from a Bolt 12 invoice.",
-            "introduction_node_id": "0324653eac434488002cc06bbfb7f10fe18991e35f9fe4302dbea6d2353dc0ab1c",
-            "blinding": "024d4b6cd1361032ca9bd2aeb9d900aa4d45d9ead80ac9423374c451a7254d0766",
+            "first_node_id": "0324653eac434488002cc06bbfb7f10fe18991e35f9fe4302dbea6d2353dc0ab1c",
+            "first_path_key": "024d4b6cd1361032ca9bd2aeb9d900aa4d45d9ead80ac9423374c451a7254d0766",
             "hops": [
                 {
                     "alias": "Bob",
@@ -57,7 +57,7 @@
                     "pubkey": "0324653eac434488002cc06bbfb7f10fe18991e35f9fe4302dbea6d2353dc0ab1c",
                     "payload": "740a4fcd7b00ff9c09ed28102b210ac73aa12d63e90852cebc496c49f57c499a2888b49f2e72b19446f7e60a818aa2938d8c625415b992b8928a7321edb8f7cea40de362bed082ad51acc6156dca5532fb680c21024d4b6cd1361032ca9bd2aeb9d900aa4d45d9ead80ac9423374c451a7254d0766",
                     "tlvs": {
-                        "current_blinding_point": "024d4b6cd1361032ca9bd2aeb9d900aa4d45d9ead80ac9423374c451a7254d0766",
+                        "current_path_key": "024d4b6cd1361032ca9bd2aeb9d900aa4d45d9ead80ac9423374c451a7254d0766",
                         "encrypted_recipient_data": {
                             "padding": "0000000000000000000000000000000000000000000000000000000000000000",
                             "short_channel_id": "0x0x1",
@@ -83,7 +83,7 @@
                     "tlvs": {
                         "encrypted_recipient_data": {
                             "short_channel_id": "0x0x2",
-                            "next_blinding_override": "031b84c5567b126440995d3ed5aaba0565d71e1834604819ff9c17f5e9d5dd078f",
+                            "next_path_key_override": "031b84c5567b126440995d3ed5aaba0565d71e1834604819ff9c17f5e9d5dd078f",
                             "payment_relay": {
                                 "cltv_expiry_delta": 75,
                                 "fee_proportional_millionths": 150,
@@ -158,25 +158,25 @@
                 "alias": "Bob",
                 "onion": "000280caa47c2a0ea677f6a77529e46caa04212153a8d5f829bee1e7339b17e2e2a9a3461d10472364a4ff12344beb6df96fb0c38ec47d1e956ddff5a665190fcca5ed02c3a3903fd8bbd4a4b95b197867c378b67b08f0624cfe80734ba512869c0fa22099beb1f6f1ea325b07ce7449736d7ffad79178b428d8ea2d7bc6578f12dbd788ef933f3b5ba352797c41f6786c3820c96726acf8bddf2cfa5d9c617d2b0bd5ab7b93f7964c98f44cf47db8422f47d11100236a29579f1cafcd38bd979814e1d2bf6d625edf50e1e21bfaf6268e3180dd7aafd3892da281c6dd53c1c366d0fdaf670b6ad84a38d6e8a3f4a80d132d686fd3b7443bc2250023bdb9303190f74c9220481cf99da30b5ec2bdb5a49028f5014e3eaeaa48429a0c78ebd3bb7c7d582c22b7d547cd269f0c4490373a81bf92687e73dac2075b4bda189ce0be225f5f510655e37a6e724a1415bede0a076b92a882cc2a82878ba67aaedf71454eb42b7f8638df8e21d5f708006e5112e2dc0a4afbcfed9f2c7959be812853ca8e313fbc99a0f38f1ee4479c96ccb836632b0808401db159bd2637f7a664013241e4664e994a0a9a3940115a702c60381e66d291e1ade1be2802e1226e311e3201a7c9682b6bc4354caff3d439adb1dfee53ad3fb3dd5e169d64796853bb323129f41213b166a7cac00f728c3e33bd7e59aa2ac0d1341cdb1532b507a0f446e51022a882ac16405442347b70f78c9b6e122f8e70096a4fae4c0405db5b869e0b7b59b09519c4dbf4d4980483906e837da0bee93f668ffaad37d6a4764211a02f95ad2dc2d942c198796741c20a3baf8efb5a53bd9c1a0148318d60a97d0013ab63269097ea295d62c1426d064f0b31c02e74a348ee0509998e701069f5a1e0c1086aed38d2ec87da69fb57a992d88ace3b4a16b0960f5a94936e2e684a9926cf4f911969a2a5d31fed0c7616d30197848253170e51274278873b11f3f5cc1b04b14aa5812524e4d86cbf08306c2aa671288324d7a009b2be533b1d7d0ce6defeeb630b86a9655f1e6424fcb559ed67457c115fba0d0719374802ea68fab299fd3f273be86fa3d2e7456020db2f47c6ec16c21ce6ec65de495e20af1941a5dcd65d910c1cb93f22e1318c173c645c81aed681c9704a8a541ac3d6ff604f46d0260468acbfec1b771b9eb8cd49a2124468dae786571895a569aae18438eaee6343ab2634823119fa2439634645d12e3b4a748b9cc0398b8416a834eb5d9e5cf619bbfaba4894d1c574c738caf530d0862f4cc75eb52bd3921d2d9edb09940edb1e3776423b0046d870ccdcc5d61f72e0440b97a93eeef21fb246a779d339be301a5971400749d6cc9911dfbf9de8ae86fac83c860fdd0e2bfa40af37c99d50e50fd6e5ae86597a201112ed404042b55e132f243dec481a2adc1d5e4b71e1efdea806ea900b2907ce877742d5ecf700ff3640f737863d0dd7207e462ee8d0e17d52047a88ae7446f419560d23968bf64957949e36953155b0ac2511c66be2890b4036329a21e132efb635297a64431899e0c351e50c6682c9b4d79b5d122466d02cd84f206369417d9c194a9349d3c631d72eb7857a9cd542906fc02ad6cdcf9bcf25ace3d826b6623fa5164351e14d3f0de5c8445a2ba3aae26595d0e31c3e307c1d56d4274f61f056145c1b8d6880872b9b10a8bfa4a923cad2edbcf5c50eba48936ed2bcc0be60eb721a74b46704aaae5ad24e2797852195dfacbb30a777d33b63d4dc4f35cfbe5e88fd1944c55a54fd53581446ea061ad29f4671da819ad7488c5dfc700f5f7a1b2af0d6a6e9d9ffc570a6d3209614ab4dc43728f3f0cd7eb4ce36ccd98936bbcbd32627384434bd01e9c0f93b2a5173fba184685e19b9af78afe876aa4e4b4242382b293133771d95a2bd83fa9c62",
                 "node_privkey": "4242424242424242424242424242424242424242424242424242424242424242",
-                "next_blinding": "034e09f450a80c3d252b258aba0a61215bf60dda3b0dc78ffb0736ea1259dfd8a0"
+                "next_path_key": "034e09f450a80c3d252b258aba0a61215bf60dda3b0dc78ffb0736ea1259dfd8a0"
             },
             {
                 "alias": "Carol",
                 "onion": "000288b48876fb0dc0d7375233ccaf2910dc0dc81ba52e5a7906f00d75e0d58dbd4bb7c2714870529410735f0951e72cbe981e2e167c0d8f3de33a36e39e78465aea2acad1e23c78b6fd342d63e37d214c912b4a0be344618f779138edc1b42a5ca3218ca2fea4be427f6cd0d387160db2bf6c2ba8e82941c8cf3626bd6bed7187f633012ef49df38f6b12963cb639e9eed1b9d269dcebcbd0b25287aa536ec85e7320b02e193122199a745ccbaaebd37f5d4b71f52f9b50feeb793eeef56924a046bc5e7003f6253e0284a8d3fe2e42c3564050f1e753cd32cc258ac0ffa6e05eecad5ba1286f78252e60dd884a65405ab673a85ba52adfa65c1086d4bb37ba2e0848adb2b04379775ad798492b14e8997f30ffa9cf5d432bdf5b246fce008fd876399beed827db58195f4f6192f6ff4ec63cb17fdcb497cb7aec26846a71dd8dca02fc3bb14dd7231a4d62a981bec54b71eb20331096dfa214a0ff4489ee96db663826ae8c850e9f06baa52a47b8eb576363f97e742aab2dc616acc6e74588e1d2ac16694febc90abaf5b1c684163c0e615a68d32633f01934adc8c6bf91fa3fd7aad033b7596d60402494e45e2c1632c40f7bfbd88a81a896a1d28ed6338c83e1eeaa467945d59998eb456c95f94bf1892e8f326ec2d5e0196b7073f106febc6ab8ca5bcc23f77ffc819bc1b5debce418ccc7d8391bbf33bceee6110beba170121bd99f54c956e64970bdab31227b03ee0ea3f01fbd9bd74015f6f82d04fab072e8f85f4370d09f41ee3e48eb959767bd989abb4eea42c4daa0437a7f747d7f9b70eb87b9f9b0b6f283b8205912601a432999b8869fd9fe5bad3572edac24da7184f9298f21ff60923db277264d29c846dd2f228f6fc53b6b60364237de64773f803f174ed10229c374f603ccc5fd3a62cb413ffe6f5630dc646bb33f231b2350537ec39e5d3f2fe1a1cb019ed0b18ad14019cad27afcca8ad70387ca110394c0432774f1aa1fa404b2e086c84a55388d3bd102501c78ef925cce89d76fa04c3f20f2d1f0ce507ac8b37b7913e3949ba12bbc5a4f6bac37c2415622d365bc8b83709a28e3d46f3850c89a3ff4d027fef6e3e4ce5c6c85f663c7eaec3c9730106fb82f53249a905533cfabee812aae51965b24b42f7ab471967bc8e73354e69141ee26a1f03684d5fb9c256a34de8257210e0390dd3962db521ae0a3bdab28300610ab2a634b699e5f092da5a061609ef6414bd805c8171f54ad6f285fb64ce0becca0b61188badcf8ef21190dad629e3fb3e89f55ebba829919540ebf5f8ae4283836d3c9133c1ca3365f6b9394916730411650686e0c2ab9c53b6cda9efdd5cfcb53ba9b6962bb6aa49d0a83a87460b60a9c7d2643ee99afe652883795f14014ec5df61b1e30c041c1fa6487f3c82f1ded5f83ffbef5017e197b7fb77be3b36e284a15e57d45bf9316dcaf97eb78ee4642b731ba05c5063bce1333fab4af6da97c80a96ee599b4df823efbedc250c0abba9783da7ddf2414b2a4774ff2880a7dc6791103e18b8631e39743cf9e87aed71700daa5dc72fdae520324741f92ea3d510ff555dea5e45f15cda87272d4559a12d4777680acb06993840e3c748da82c16cae556015fb2acd0335da11a3388575394048ab71199793ab706abc9d68add2075d79a5cc0f779845ee8b98951be61fd293d6c15b9d4653935bf17cf50bd31f8b79e60dba0e7fd6864754fd94262485a4f65e7eb3e1922f51b1a4dd2b4fd2c20d94d1213fbe90bd603dfc7e15176382e3ce0f43f980d44d23bf3c57f54a15f42c171a8f2511e28ac178c6f01396e50397a57ffb09c5e6c315bd3ae7983577c1a0386c6d5d9a2223438e321b0fedfdee58fa452d57dc11a256834bb49ac9deeec88e4bf563c7340f44a240caec941c7e50f09cf",
                 "node_privkey": "4343434343434343434343434343434343434343434343434343434343434343",
-                "next_blinding": "031b84c5567b126440995d3ed5aaba0565d71e1834604819ff9c17f5e9d5dd078f"
+                "next_path_key": "031b84c5567b126440995d3ed5aaba0565d71e1834604819ff9c17f5e9d5dd078f"
             },
             {
                 "alias": "Dave",
                 "onion": "0003f25471c0f2ff549a7fd7859100306bb6c294c209f34c77f782897f184b967c498efc246bdb8e060a6d1cf8dd0d4d732e33311fb96c9e9f1274005fa3d08b41704a1b7224c6300a7caead7baa0a8263eba2e0de6956ee8e4a1958264f47e4cf20d194eb576f5bd249ee4fece563f80fd76dc3eaca8f956188406d83195752b5c90c4b2a5e7ac3a8d5c62b17b551aff48ef6842a7e9326832c9a4a2fd415011150a9e71beb901fd9747bac8add1c694b612730dc86b5b19a0bbbc675947a953316e3303d7b30c182f94def9206671edac9a3ec3e52d28fc28247a1c73ab751bf61c82c3950f617e758f79bd0ba294defb20466eaf1e801462046baad3aec3e5b8868a7b037f23d73a47a7e74c77107334f37388cff863e452820c61d89728fa75c84bc7cdfc06dcdd1911f5f803353926d073efd65251380e174913aae03318ea5b6f0ec83998c55ab99bef62803ea2da9f6d1ea892b90efc4f8ffb685a5201a781da2e6ac5923645638c9709ae32171a00c0cd3d8c7eedfb06b4eedc7d3e566987e2e3805a038f21d78ded5d6c7137a5e8e592f3180ee4d5f4e1289176f67fc38690d0958bc82e240b72b10577f340f1e14b8633f0b6d9729ff4618be2a972400a015a871ba33be70335f652a8d70f2bd32421d6ac2af781d667dad787d6aef4505a15d046579e46eebe757444cffca6d0610f0dd36a7ce57af969bd0c3f7006298ef406a25f689daf58f875d44d2423ebf195b503f11c37c506ea6abe50a463f7bb5e9b964604d832724de768513f6b38bf71715e1feea8a6e86797788d487146891564919da1372016ed8f08c7fcbff66a4a65a3d0fcd8e3daac6eba41f5d65ef2d8075364a9e78b3a273549f6eac4abb72e912e237990367e0d43e89945f8ac3907be5a6c662139485a50cb5ce3f0ba08586c39f6c515368ec3f91b72295f1b7a73a9df322ae9a45d363d6c616be3300083764cbdee31221f25a318f095feacb09f957c96db30fccca47a0215b576c3ed925a0bad05d6400abe318c11f36628c387a4ee38832182cd44b3cd48e5422c1f1e3b57218dfe72c611f5415127720e60f6e2400607e61841b76de1704bcbeb0daf1377ccb2253916de2b6d490bb71ba0a44fea2e94f2423d723934557d5905e01b2b80232a884e258d46dc92ea11e0818d0ece5b914f02049866e151801ab8c9aea155479b354dc91151fb9ba43277458f9760dd859faaa139e3b9ab36a1dbc36a93ef2c90598b20cb30ef3c4f23a2d6178b4d1da668fb328a25d84d30a132d9f2a6a988cbe2e5c2be01cb6db4b4725a50d6cdacf5fb083e7d650a25bec1407fbc047d26076c7596429a29606ad527e97ef0824ad6c1b05831a3e5b71c63a528918a3301cdd4061fc1fcce3da601961f2602a2b002ac8404125c2d52666263858a923e197efcda873c32d86897352e4f2264ad6a1b48acc0fe78ff55cb442cb2bb5fa2880810e1d00aa0247057fb80b7ed36cf9647af41b44ee4a63ee2d6f652526404572520a7d2d9dcde4e62df0c3be89f8471550594cdd16a51a9cacc58729c092c68506162fe65edc2314055d389f724ced189d826a546b5c4d08a43d977b3cf033de5760b71a7cc38ee5851592031aafb467a89b3b6c7ed67b15d44c48d6baedce3e95e08ec7c55038f3eba90ccb900895734f0fb7efe54961ce493369cc56416898a9bed7c2482871c15a7f1eb5ed17c33657fc31333539c2dfb59461af09e7049228113b5c9feea5a6e9959c18c51b19c90995afb9c76f2c0c820964cd7989c993a73925818a656c6a18dcd1a1e3782b2eae06dd5a41250ec2d1c203626ab9920c1673339eff04b1eb0cab85ef5909f571f9b83cdf21697c9f5cfa1c76e7bca955510e2126b3bb989a4ac21cf948f965e48bc363d2997437797b4f770e8b65",
                 "node_privkey": "4444444444444444444444444444444444444444444444444444444444444444",
-                "next_blinding": "03e09038ee76e50f444b19abf0a555e8697e035f62937168b80adf0931b31ce52a"
+                "next_path_key": "03e09038ee76e50f444b19abf0a555e8697e035f62937168b80adf0931b31ce52a"
             },
             {
                 "alias": "Eve",
                 "onion": "0002ef43c4dfe9aee14248c445406ac7980474ce106c504d9025f57963739130adfd06eb26201baee8866af2d1b7a7ab26595349dad002af0590193aaa8f400ab394f5994ec831aeeecb64421c566e3556cbdd7e7e50deb1fc49fd5e007308ab6494415514abff978899623f9b6065ca1e243bb78170118e8b8c8b53b750b59cc1ec017d167adbb3aabab7c2d84fbf94f5d827239f4c2b9d2c3cfe68fe5641f25e386202a4b6edff2a71e700229df7230c8ca31bd5588f04799e9640c9c20a47cba713f3cc5ad3202e14bb520880f2a8409d8e7835cae21b48a651c2d47fe6af785889ab98f1416f6e4ad67a66ae681e9a8828bad3f9b6890221c4a7ec80531d6b63eb30843f613ce644795bc8bcee60e8f7b36f3fd04de762f103c52efaf36a2f3bbbaac482d6271dc4180c10bcc076c04d06ea7fd8fb6a647e0e10523b05da2d89e4139fb55c2315cd01bdcbd57587fef8442d7ff5620630fd2d2e79739d90be811bf2cba60415d6cba2cea14ba1859f3122cd905c4e12e3e2a1ab6fab54b2ec40e434626e2d3c3195c02c82a8bd64d226c2328ac72ca12197d9908eaf54333717448ce6ed73adc0ac05e2ee1d735131d87918beb8995993dc8f63fe10f2c8eba2be7ab8bb44d9f78f59ef3e4c180bd75e4eef2381450c6f0480d543997305f1d07815993b5aca8d88d474966d9abec93bb069a16aa2da75b87f94576e01d08a17d3e0e3d0370f010733a7d7affb12cdf94c259a62607fce71003535c4727305de5ff7bba3840922844b3a45f62c29715fccf440517ef121450f6962396fba9b07036d085582405dcae6ee95964b66bc7c85b8d02d90091500db3cebf6de584f86b7b55335a8c9aa26381b00747f055cc458a2cadfccf9c29702bf941447beaca6583cca09492a57d4b03b2ca00dbaf41dfd6a9b249381626a7debe475735a7e39e77a363eccf14669046f656cc09ad448da8d8b545e6a604f46dc481786d09a94c63cf23f49ba367d2929466364dbce2a8ffce3dadf8f4cef8a56e1fefa1a3304a953fe83018e57d8a95694b02d994fea2630a9a3d5f1e2f6d6142d503ec4152871f7122d7e566a03261f554639e7a759e0e73846f71d5cace37d91336fc9ca9396bf64ca2cf45fa2db779b3b5c63b04f1c0c1fb79fdfcf5a82b0202df934ae1720a7ce1e047cbec3f82737b50168c974f4623cacce87e3f5bd5232caca7956d28ffedcf11ac5998662c5f6b13c6126584ca2e894d3fcbad4d130bbe22e88a135e0020cdd43853e0b3af3800e9544854d211e873cf68ab683578d501d69ec5dc7fce42ac436d58243880c1b88227b0681c6c9dd8a8ad0793202b15ab63b787b748e258da3e68d0e649fc4ac081a71de8adbc891c113d5f722686b6ac4ed9e3cc247bc4a4643416f480627e9de20f7307f434a499f5c6951c2e8b3ff51d455bf65ceb5ee3dee47b968ac2642e13d8a68f903b73627c2e75788fecca5836371a908eea4f1ea44db2315bc185f77e478efeaaa4da2da13fe7aeaa79ed1d04876a8b2b7b333c5de8c4c9a50274c2eb7b9bd2a3630c57173174781fc9785235f830cefa1c82080eaffdef257f18eedc9ddfd25a696a11a3dc56cd836be72f5f4a2cbb6316d5d3b1ad91a7ec7d877f28d2c29a5525b0b24362699281b0e3b48f38caf1085045fe9089f9e6fb29e4b47aa4cecf68c9bf72073469bd9beeea5e88bfe554cb6a81231149ba7fe7784c154fd8b0f9179ecdf1e9fd5c2939ec1ab16df9cbe9359101ebce933d4f65d3f66f87afaecfe9c046b52f4878b6c430329df7bd879fba8864fcbd9b782bf545734699b9b5a66b466dcedc0c9368803b5b0f1232950cef398ad3e057a5db964bd3e5c8a5717b30b41601a4f11ad63afe404cb6f1e8ea5fd7a8e085b65ca5136146febf4d47928dcc9a9e0",
                 "node_privkey": "4545454545454545454545454545454545454545454545454545454545454545",
-                "next_blinding": "038fc6859a402b96ce4998c537c823d6ab94d1598fca02c788ba5dd79fbae83589"
+                "next_path_key": "038fc6859a402b96ce4998c537c823d6ab94d1598fca02c788ba5dd79fbae83589"
             }
         ]
     }
diff --git a/bolt04/onion-error-test.json b/bolt04/onion-error-test.json
index 7d416b4..ddb1edf 100644
--- a/bolt04/onion-error-test.json
+++ b/bolt04/onion-error-test.json
@@ -5,31 +5,31 @@
     "failure_message": "2002",
     "hops": [
       {
-        "realm": 0,
+        "version": 0,
         "pubkey": "02eec7245d6b7d2ccb30380bfbe2a3648cd7a942653f5aa340edcea1f283686619",
         "hop_shared_secret": "53eb63ea8a3fec3b3cd433b85cd62a4b145e1dda09391b348c4e1cd36a03ea66",
         "ammag_key": "3761ba4d3e726d8abb16cba5950ee976b84937b61b7ad09e741724d7dee12eb5"
       },
       {
-        "realm": 0,
+        "version": 0,
         "pubkey": "0324653eac434488002cc06bbfb7f10fe18991e35f9fe4302dbea6d2353dc0ab1c",
         "hop_shared_secret": "a6519e98832a0b179f62123b3567c106db99ee37bef036e783263602f3488fae",
         "ammag_key": "59ee5867c5c151daa31e36ee42530f429c433836286e63744f2020b980302564"
       },
       {
-        "realm": 0,
+        "version": 0,
         "pubkey": "027f31ebc5462c1fdce1b737ecff52d37d75dea43ce11c74d25aa297165faa2007",
         "hop_shared_secret": "3a6b412548762f0dbccce5c7ae7bb8147d1caf9b5471c34120b30bc9c04891cc",
         "ammag_key": "1bf08df8628d452141d56adfd1b25c1530d7921c23cecfc749ac03a9b694b0d3"
       },
       {
-        "realm": 0,
+        "version": 0,
         "pubkey": "032c0b7cf95324a07d05398b240174dc0c2be444d96b159aa6c7f7b1e668680991",
         "hop_shared_secret": "21e13c2d7cfe7e18836df50872466117a295783ab8aab0e7ecc8c725503ad02d",
         "ammag_key": "cd9ac0e09064f039fa43a31dea05f5fe5f6443d40a98be4071af4a9d704be5ad"
       },
       {
-        "realm": 0,
+        "version": 0,
         "pubkey": "02edabbd16b41c8371b92ef2f04c1185b4f03b6dcd52ba9b78d9d7c89c8f221145",
         "hop_shared_secret": "b5756b9b542727dbafc6765a49488b023a725d631af688fc031217e90770c328",
         "um_key": "4da7f2923edce6c2d85987d1d9fa6d88023e6c3a9c3d20f07d3b10b61a78d646",
diff --git a/bolt04/route-blinding-test.json b/bolt04/route-blinding-test.json
index c69cc72..4dbfde3 100644
--- a/bolt04/route-blinding-test.json
+++ b/bolt04/route-blinding-test.json
@@ -34,12 +34,12 @@
                 "blinded_node_id": "03da173ad2aee2f701f17e59fbd16cb708906d69838a5f088e8123fb36e89a2c25"
             },
             {
-                "comment": "Notice the next_blinding_override tlv in Carol's payload, indicating that Bob concatenated his route with another blinded route starting at Dave.",
+                "comment": "Notice the next_path_key_override tlv in Carol's payload, indicating that Bob concatenated his route with another blinded route starting at Dave.",
                 "alias": "Carol",
                 "node_id": "027f31ebc5462c1fdce1b737ecff52d37d75dea43ce11c74d25aa297165faa2007",
                 "tlvs": {
                     "short_channel_id": "0x0x1105",
-                    "next_blinding_override": "031b84c5567b126440995d3ed5aaba0565d71e1834604819ff9c17f5e9d5dd078f",
+                    "next_path_key_override": "031b84c5567b126440995d3ed5aaba0565d71e1834604819ff9c17f5e9d5dd078f",
                     "payment_relay": {
                         "cltv_expiry_delta": 48,
                         "fee_proportional_millionths": 100,
@@ -117,8 +117,8 @@
     },
     "route": {
         "comment": "This section contains the resulting blinded route, which can then be used inside onion messages or payments.",
-        "introduction_node_id": "0324653eac434488002cc06bbfb7f10fe18991e35f9fe4302dbea6d2353dc0ab1c",
-        "blinding": "024d4b6cd1361032ca9bd2aeb9d900aa4d45d9ead80ac9423374c451a7254d0766",
+        "first_node_id": "0324653eac434488002cc06bbfb7f10fe18991e35f9fe4302dbea6d2353dc0ab1c",
+        "first_path_key": "024d4b6cd1361032ca9bd2aeb9d900aa4d45d9ead80ac9423374c451a7254d0766",
         "hops": [
             {
                 "blinded_node_id": "03da173ad2aee2f701f17e59fbd16cb708906d69838a5f088e8123fb36e89a2c25",
--

04-onion-routing.md

This commit doesn't change the logic at all, it simply: - removes `realm` from onion test vector - cleans-up markdown formatting and indents - fixes typos and missing parenthesis - consistently uses `_` instead of `-` for field names - fixes math formatting (including changes from lightning#1169 and lightning#1158)

rustyrussell · 2024-07-17T01:10:26Z

As agreed on the call, I've added @t-bast cleanups and am applying now. Will rebase #1182 next...

rustyrussell added 4 commits July 10, 2024 10:22

BOLT 4: remove obsolete references to realm

79f3d0f

This was from the legacy onion, and is no longer present. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>

BOLT 2, BOLT 4: refer to the onion decryption section in update_add_h…

47d9cce

…tlc/onion message requirements. This ties it together, saying what to use as associated data, blinding, and what to do on failure. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>

BOLT 2, 4: rename blinding to path_key.

5193cbb

Sure, it's used to derive a secret for blinding, but it's also used to derive the key for encrypted_recipient_data. It's not used as a blinding factor *directly*. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>

rustyrussell mentioned this pull request Jul 11, 2024

Clarify onions part 2: a bit deeper rework #1182

Merged

t-bast mentioned this pull request Jul 12, 2024

Lightning Specification Meeting 2024/07/15 #1183

Closed

22 tasks

Roasbeef reviewed Jul 12, 2024

View reviewed changes

04-onion-routing.md Show resolved Hide resolved

ProofOfKeags approved these changes Jul 16, 2024

View reviewed changes

rustyrussell merged commit 3fffab3 into lightning:master Jul 17, 2024

This was referenced Jul 17, 2024

Typo fixes #1169

Merged

BOLT-04: replace quotation marks used in math expressions #1158

Closed

t-bast mentioned this pull request Jul 29, 2024

Trampoline onion format (Feature 56/57) #836

Open

t-bast mentioned this pull request Sep 18, 2024

Bolt4: clarify packet forwarding blinding #1012

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Clarify onion spec: part 1 (the uncontroversial bits) #1181

Clarify onion spec: part 1 (the uncontroversial bits) #1181

rustyrussell commented Jul 11, 2024

t-bast commented Jul 11, 2024

rustyrussell commented Jul 17, 2024

Clarify onion spec: part 1 (the uncontroversial bits) #1181

Clarify onion spec: part 1 (the uncontroversial bits) #1181

Conversation

rustyrussell commented Jul 11, 2024

t-bast commented Jul 11, 2024

rustyrussell commented Jul 17, 2024