diff --git a/21.md b/21.md new file mode 100644 index 0000000..9891be6 --- /dev/null +++ b/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 (john@doe.com) with `serviceName`? +5. Once accepted by the user, `LN WALLET` sends a GET to `LN SERVICE` in the form of + ``` + + // either '?' or '&' depending on whether there is a query string already in the callback + k1= // the k1 specified in the response above + &la= // 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.