The lnaddress recipient type #576

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...

value/value.md

@@ -487,7 +487,7 @@ and guest.
 
 <br>
 
-### 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.
 
 <br>
 
-### 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.
+             then sends that amount at the specified time when each interval passes.
+
+<br>
+
+### 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.

value/valueslugs.txt

@@ -1,6 +1,7 @@
 bitcoin
 lightning
 keysend
+lnaddress
 amp
 wallet
 node