blip-0037: Bolt 12 encoded wallet node_id

README.md

@@ -17,11 +17,12 @@ published here.
 For more detail on the process, please read [bLIP-0001](./blip-0001.md) and
 [bLIP-0002](./blip-0002.md).
 
-| Number                   | Title                     | Author                      | Status |
-|--------------------------|---------------------------|-----------------------------|--------|
-| [1](./blip-0001.md)      | bLIP Process              | Ryan Gentry                 | Active |
-| [2](./blip-0002.md)      | Reserved Values           | Bastien Teinturier          | Active |
-| [3](./blip-0003.md)      | Keysend                   | Valentine Wallace           | Active |
-| [10](./blip-0010.md)     | Podcasting 2.0            | Satoshis Stream             | Active |
-| [11](./blip-0011.md)     | NameDesc                  | Hampus Sjöberg              | Active |
-| [17](./blip-0017.md)     | Hosted Channels           | Anton Kumaigorodskiy        | Active |
+| Number                   | Title                          | Author                      | Status |
+|--------------------------|--------------------------------|-----------------------------|--------|
+| [1](./blip-0001.md)      | bLIP Process                   | Ryan Gentry                 | Active |
+| [2](./blip-0002.md)      | Reserved Values                | Bastien Teinturier          | Active |
+| [3](./blip-0003.md)      | Keysend                        | Valentine Wallace           | Active |
+| [10](./blip-0010.md)     | Podcasting 2.0                 | Satoshis Stream             | Active |
+| [11](./blip-0011.md)     | NameDesc                       | Hampus Sjöberg              | Active |
+| [17](./blip-0017.md)     | Hosted Channels                | Anton Kumaigorodskiy        | Active |
+| [37](./blip-0037.md)     | Bolt 12 encoded wallet node_id | Bastien Teinturier          | Active |

blip-0037.md

@@ -0,0 +1,121 @@
+```
+bLIP: 37
+Title: Bolt 12 encoded wallet `node_id`
+Status: Active
+Author: Bastien Teinturier <[email protected]>
+Created: 2024-07-02
+License: CC0
+```
+
+## Abstract
+
+[Bolt 12](https://github.com/lightning/bolts/pull/798) introduces a new
+`sciddir_or_pubkey` field that can be used to identify the introduction node of
+a blinded path. This is primarily used to reduce the size of encoded offers,
+but this encoding trick can be extended to carry more information about the
+node it's referencing. We introduce an additional prefix to this field to tag
+`node_id`s that belong to mobile wallets.
+
+## Copyright
+
+This bLIP is licensed under the CC0 license.
+
+## Motivation
+
+When relaying a payment or an onion message, wallet providers usually want to
+offer additional features to mobile wallets. Encoding the information that the
+next node is a mobile wallet directly inside the onion payload makes it easy
+for the relaying node to efficiently insert additional steps before relaying
+(such as trying to wake-up the wallet if it is offline) without negatively
+impacting relay to normal nodes.
+
+## Specification
+
+We allow `sciddir_or_pubkey` to start with `0x04` or `0x05` followed by 32
+bytes, in which case it encodes the compressed public key of a wallet node
+when replacing the leading `0x04` by `0x02` or `0x05` by `0x03`.
+
+We also extend the `next_node_id` TLV field in `encrypted_recipient_data`
+included in blinded paths to contain an `sciddir_or_pubkey` instead of a
+plain public key.
+
+### Requirements
+
+A wallet node creating a blinded path:
+
+- If its service provider supports decoding wallet `node_id`s:
+  - SHOULD set `encrypted_recipient_data.next_node_id` for that node to:
+    - If the wallet's `node_id` has an even y-coordinate:
+      - `0x04` followed by the public key's x-coordinate.
+    - Otherwise:
+      - `0x05` followed by the public key's x-coordinate.
+
+A node relaying an onion message:
+
+- If `encrypted_recipient_data.next_node_id` starts with `0x04` or `0x05`:
+  - MUST treat the next node as a mobile wallet node.
+  - MUST compute that node's public key by replacing the leading byte by:
+    - `0x02` if it contains `0x04`.
+    - `0x03` if it contains `0x05`.
+
+A node relaying a blinded payment:
+
+- If `encrypted_recipient_data.short_channel_id` is not set:
+  - If `encrypted_recipient_data.next_node_id` is set and starts with `0x04` or `0x05`:
+    - MUST treat the next node as a mobile wallet node.
+    - MUST compute that node's public key by replacing the leading byte by:
+      - `0x02` if it contains `0x04`.
+      - `0x03` if it contains `0x05`.
+  - Otherwise:
+    - MUST reject the payment.
+
+### Rationale
+
+We don't define a feature bit to indicate reader support: this should be
+explicitly defined by other features that rely on this encoding, such as
+waking up mobile wallet nodes using push notifications.
+
+### Test vectors
+
+The following test vectors describe how the `sciddir_or_pubkey` field is
+encoded in various scenarios:
+
+```json
+[
+  {
+    "sciddir": {
+      "isNode1": true,
+      "scid": "890123x456x0"
+    },
+    "encoded": "00 0d950b0001c80000"
+  },
+  {
+    "sciddir": {
+      "isNode1": false,
+      "scid": "789012x3456x5"
+    },
+    "encoded": "01 0c0a14000d800005"
+  },
+  {
+    "standard_node_id": "022d3b15cea00ee4a8e710b082bef18f0f3409cc4e7aff41c26eb0a4d3ab20dd73",
+    "encoded": "022d3b15cea00ee4a8e710b082bef18f0f3409cc4e7aff41c26eb0a4d3ab20dd73"
+  },
+  {
+    "standard_node_id": "03ba3c458e3299eb19d2e07ae86453f4290bcdf8689707f0862f35194397c45922",
+    "encoded": "03ba3c458e3299eb19d2e07ae86453f4290bcdf8689707f0862f35194397c45922"
+  },
+  {
+    "wallet_node_id": "022d3b15cea00ee4a8e710b082bef18f0f3409cc4e7aff41c26eb0a4d3ab20dd73",
+    "encoded": "042d3b15cea00ee4a8e710b082bef18f0f3409cc4e7aff41c26eb0a4d3ab20dd73"
+  },
+  {
+    "wallet_node_id": "03ba3c458e3299eb19d2e07ae86453f4290bcdf8689707f0862f35194397c45922",
+    "encoded": "05ba3c458e3299eb19d2e07ae86453f4290bcdf8689707f0862f35194397c45922"
+  }
+]
+```
+
+## Reference Implementations
+
+- eclair: <https://github.com/ACINQ/eclair/pull/2867>
+- lightning-kmp: <https://github.com/ACINQ/lightning-kmp/pull/652>