From db3cfc7e4fad7fb842411eabf1cca3dae789a546 Mon Sep 17 00:00:00 2001 From: Eric P Date: Wed, 17 Sep 2025 23:02:04 -0500 Subject: [PATCH] Rewrite `lnaddress` with current information --- docs/examples/value/lnaddress.md | 84 +++++++++++++++----------------- 1 file changed, 38 insertions(+), 46 deletions(-) diff --git a/docs/examples/value/lnaddress.md b/docs/examples/value/lnaddress.md index 5626b70..498cfaf 100644 --- a/docs/examples/value/lnaddress.md +++ b/docs/examples/value/lnaddress.md @@ -1,65 +1,57 @@ -## The 'lnaddress' Recipient Type +# The 'lnaddress' Recipient Type -An `lnaddress` address is a -"[lightning address](https://github.com/andrerfneves/lightning-address/blob/master/DIY.md)" that resolves to the uri of -a payment options file which contains one or more payment destination addresses. For example, an `lnaddress` of -"johndoe@example.com" would be converted to the uri "https://example.com/.well-known/lnurlp/johndoe/options" which MUST -contain an appropriately formatted JSON file. +The `lnaddress` recipient type refers to a "[Lightning Address](https://github.com/andrerfneves/lightning-address/blob/master/DIY.md)", which is an email-like address used to resolve a recipient's `lnurlp` and `keysend` details from "well-known" URIs. -## Options File +The username and domain of the Lightning Address is used to construct the well-known URI, for example: -The payment options file MUST contain a JSON object that holds exactly one `options` array. The purpose of the payment -options file is to hold all the various payment receipt methods (and corresponding destination info for each) that a -user has available to them. It looks like this: +* [LNURLp](#lnurlp) info for "johndoe@example.com" would be located at the URI: "https://example.com/.well-known/lnurlp/johndoe". +* [Keysend](#keysend) info for "johndoe@example.com" would be located at the URI: "https://example.com/.well-known/keysend/johndoe". + +## LNURLp + +Provides information to request a BOLT11 invoice as defined by the [LUD-06: payRequest spec](https://github.com/lnurl/luds/blob/luds/06.md). ```json { + "tag": "payRequest", "status": "OK", - "options": [ - { - "type": "lnurlp", - "callback": "https://example.com/v1/lnurlp/johndoe/pay", - "minSendable": 1000, - "maxSendable": 1000000000000, - "metadata": "[[\"text/plain\",\"Pay @johndoe on example wallet\"]]", - "commentAllowed": 500 - }, - { - "type": "keysend", - "pubkey": "03b6f613e88bd874177c28c6ad83b3baba43c4c656f56be1f8df84669556054b79", - "customData": [ - { - "customKey": "906608", - "customValue": "01hIWsCYxdBJzlDvu5zpT3" - } - ] - } - ] + "callback": "https://example.com/lnurlp/johndoe/", + "minSendable": 1000, + "maxSendable": 16000000000, + "metadata": "[[\"text/plain\",\"Pay johndoe\"],[\"text/identifier\",\"johndoe@example.com\"]]", + "commentAllowed": 200 } ``` -### Options array +See [LUD-06](https://github.com/lnurl/luds/blob/luds/06.md) and [LUD-12](https://github.com/lnurl/luds/blob/luds/12.md) for more details. -Each member of the `options` array is a distinct payment method describing a payment destination for a user. The -properties available for an "option" depends on it's `type` and should be taken from the definition of that type as it -exists in the primary documentation. Using the above example, we can see that there are two payment options defined -for user John Doe - `lnurlp` and `keysend`. The structure and properties for `lnurlp` are defined -[here](https://github.com/lnurl/luds/blob/luds/06.md), while the structure and properties for `keysend` are defined -[here](#keysend-option). +## Keysend -## Keysend option +Provides public key and custom data fields needed to send a keysend payment. -The `keysend` payment option has a type of `keysend` and has the following properties: +```json +{ + "status": "OK", + "tag": "keysend", + "pubkey": "0123456789abcdeffedcba9876543210123456789abcdeffedcba9876543210123", + "customData": [ + { + "customKey": "696969", + "customValue": "1" + } + ] +} +``` + +### Fields -* `pubkey`(required) - The public address of the lightning node that will receive the keysend payment. -* `customData` - An array that contains two members: +* `tag` - Indicates a "keysend" response +* `status` - Status of response (either "OK" or "ERROR" with `reason` field) +* `pubkey` - The public address of the lightning node that will receive the keysend payment. +* `customData` - An array that contains routing info for the receiving node: * `customKey` - A text value that defines a routing key for the receiving node. * `customValue` - A text value that defines a routing value for the receiving node. The `customData` array is optional for cases where the receiving node is a front-end for a multi-wallet system. In this context, the `customKey` will be what the receiving system looks up inside the payment in order to -retreive the `customValue` which is a virtual wallet identifier. - -## BOLT12 option - -Under development... \ No newline at end of file +retrieve the `customValue` which is a virtual wallet identifier. \ No newline at end of file