Link wallet LUD

21.md

@@ -0,0 +1,43 @@
+LUD-21: `linkLightningAddress` base spec.
+====================================
+
+`author: rav3r` `author: jackeveritt` `author: TheBlueMatt` `author: andreneves` `discussion: https://t.me/lnurl/36910`
+
+---
+
+## Linking lightning address to a service
+
+Paying apps require users to provide a lighning address to the service. Manual entry is difficult and error-prone. Instead the service can ask them to link the lighning address via `LNURL`.
+
+### Wallet to service interaction flow:
+
+1. User scans a LNURL QR code or accesses an `lnurll:LNURL..` link with `LN WALLET` and `LN WALLET` decodes LNURL. LNURL is raw URL (not bech32-encoded) as described in [LUD-17](https://github.com/lnurl/luds/blob/luds/17.md).
+2. `LN WALLET` makes a GET request to `LN SERVICE` using the decoded LNURL.
+3. `LN WALLET` gets JSON response from `LN SERVICE` of form:
+    ```Typescript
+    {
+        "tag": "linkLightningAddress", // type of LNURL
+        "callback": string, // The URL which LN SERVICE would accept a lighning address as query parameter
+        "k1": string, // Random or non-random string to identify the user's LN WALLET when using the callback URL,
+        "serviceName": string // Name of the service to be displayed to the user
+        "redirect": string // Optional. A deep link URL that the user's LN WALLET can use to redirect back to the LN SERVICE 
+    }
+    ```
+    or
+
+    ```JSON
+    {"status": "ERROR", "reason": "error details..."}
+    ```
+4. `LN WALLET` displays a dialog: Would you like to share your lightning address ([email protected]) with `serviceName`?
+5. Once accepted by the user, `LN WALLET` sends a GET to `LN SERVICE` in the form of
+    ```
+    <callback>
+      <?|&> // either '?' or '&' depending on whether there is a query string already in the callback
+       k1=<k1> // the k1 specified in the response above
+      &la=<lighning address> // user's lighning address
+    ```
+6. `LN SERVICE` sends a `{"status": "OK"}` or `{"status": "ERROR", "reason": "error details..."}` JSON response and then `LN WALLET` informs the user about the success or failure of the operation
+7. If the `LN SERVICE` sent the optional `redirect` field in the payload in step 3, the `LN WALLET` can ask the user if they want to return to the `LN SERVICE` and if so, open the URL to redirect the user back.
+
+
+Note: that service will set a lightning address for valid ephemeral `k1`, thus a service should make sure it is unguessable. In order to harden this a service may require authorization (LNURL-auth, email link etc.) before displaying a link QR.