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: