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".
@@ -515,3 +515,17 @@ payload:  "stream", "boost" and "auto".
 * `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.
+
+<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