From 561f6288e70dcc07184a0b33d295742cd4c64fa3 Mon Sep 17 00:00:00 2001 From: t-bast Date: Wed, 3 Jul 2024 11:35:51 +0200 Subject: [PATCH] blip-0037: Bolt 12 encoded wallet `node_id` [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. 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. --- README.md | 17 ++++---- blip-0037.md | 121 +++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 130 insertions(+), 8 deletions(-) create mode 100644 blip-0037.md diff --git a/README.md b/README.md index bba6b55..2621495 100644 --- a/README.md +++ b/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 | diff --git a/blip-0037.md b/blip-0037.md new file mode 100644 index 0000000..301e00c --- /dev/null +++ b/blip-0037.md @@ -0,0 +1,121 @@ +``` +bLIP: 37 +Title: Bolt 12 encoded wallet `node_id` +Status: Active +Author: Bastien Teinturier +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: +- lightning-kmp: