diff --git a/value/lnaddress.md b/value/lnaddress.md new file mode 100644 index 0000000..5626b70 --- /dev/null +++ b/value/lnaddress.md @@ -0,0 +1,65 @@ +## 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. + +## Options File + +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: + +```json +{ + "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" + } + ] + } + ] +} +``` + +### Options array + +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 option + +The `keysend` payment option has a type of `keysend` and has the following properties: + +* `pubkey`(required) - The public address of the lightning node that will receive the keysend payment. +* `customData` - An array that contains two members: + * `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 diff --git a/value/value.md b/value/value.md index d60e8e0..88c5ce6 100644 --- a/value/value.md +++ b/value/value.md @@ -487,7 +487,7 @@ and guest.
-### Appendix A - TLV Records and Extensions +### TLV Records and Extensions Lightning payments are performed using lightning messages as specified in [BOLT #1: Base Protocol](https://github.com/lightningnetwork/lightning-rfc/blob/master/01-messaging.md). @@ -502,7 +502,7 @@ the `customKey` and `customValue` attributes.
-### Appendix B - Payment Actions +### Payment Actions There are currently 3 payment "actions" that are defined in the BLIP-10 TLV extension that is embedded in the payment payload: "stream", "boost" and "auto". @@ -514,4 +514,18 @@ payload: "stream", "boost" and "auto". types of payments can contain textual messages (i.e. - a boostagram). * `auto` - This means the payment was an app initiated payment that recurs at a specific long-form interval such as weekly, monthly, yearly, etc. The user configures an interval and payment amount in the app and the app - then sends that amount at the specified time when each interval passes. \ No newline at end of file + then sends that amount at the specified time when each interval passes. + +
+ +### Value Recipient Address Types + +There are a few different available recipient address types: + +* `node` - The public address of a node. For instance, in the `lightning` value type this would represent a node's + public address. +* `lnaddress` - A so-called "lightning address", which takes the form of an email address that gets resolved into an + options file which holds the underlying destinations for payment. See the full document + [here](lnaddress.md) for explanation. + +More recipient address types will be added in the future. \ No newline at end of file diff --git a/value/valueslugs.txt b/value/valueslugs.txt index b42fe65..6a9b53a 100644 --- a/value/valueslugs.txt +++ b/value/valueslugs.txt @@ -1,6 +1,7 @@ bitcoin lightning keysend +lnaddress amp wallet node \ No newline at end of file