From cc6f4326ee8d6d3fa39ed1eb30085a2bbc5cdf74 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rafa=C5=82=20Gawe=C5=82?= Date: Sun, 4 Feb 2024 11:13:22 +0100 Subject: [PATCH 1/8] Create 21.md --- 21.md | 47 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 47 insertions(+) create mode 100644 21.md diff --git a/21.md b/21.md new file mode 100644 index 0000000..59a159e --- /dev/null +++ b/21.md @@ -0,0 +1,47 @@ +LUD-21: `linkLightningAddress` base spec. +==================================== + +`author: rav3r, jackeveritt` + +--- + +## Linking lightning address to a service + +Today users are asked to provide a withdrawal Lightning invoice to a service. This requires some effort and is especially painful when users try to withdraw funds into mobile wallets while using a desktop website. Instead of asking for Lightning invoice a service could display a "withdraw" QR code which contains a specialized `LNURL`. + +### Wallet to service interaction flow: + +1. User scans a LNURL QR code or accesses an `lightning:LNURL..` link with `LN WALLET` and `LN WALLET` decodes LNURL. +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": "withdrawRequest", // type of LNURL + "callback": string, // The URL which LN SERVICE would accept a withdrawal Lightning invoice as query parameter + "k1": string, // Random or non-random string to identify the user's LN WALLET when using the callback URL + "defaultDescription": string, // A default withdrawal invoice description + "minWithdrawable": number, // Min amount (in millisatoshis) the user can withdraw from LN SERVICE, or 0 + "maxWithdrawable": number, // Max amount (in millisatoshis) the user can withdraw from LN SERVICE, or equal to minWithdrawable if the user has no choice over the amounts + } + ``` + or + + ```JSON + {"status": "ERROR", "reason": "error details..."} + ``` +4. `LN WALLET` Displays a withdraw dialog where user can specify an exact sum to be withdrawn which would be bounded by: + ``` + max can receive = min(maxWithdrawable, local estimation of how much can be routed into wallet) + min can receive = max(minWithdrawable, local minimal value allowed by wallet) + ``` +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 + &pr= // the payment request generated by the wallet + ``` +6. `LN SERVICE` sends a `{"status": "OK"}` or `{"status": "ERROR", "reason": "error details..."}` JSON response and then attempts to pay the invoices asynchronously. +7. `LN WALLET` awaits for incoming payment if response was successful. + +Note that service will withdraw funds to anyone who can provide a valid ephemeral `k1`. In order to harden this a service may require authorization (LNURL-auth, email link etc.) before displaying a withdraw QR. From 9cc600f69c47bab70f934f10bc8b02892abe2144 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rafa=C5=82=20Gawe=C5=82?= Date: Mon, 5 Feb 2024 12:31:20 +0100 Subject: [PATCH 2/8] Update 21.md --- 21.md | 11 ++++------- 1 file changed, 4 insertions(+), 7 deletions(-) diff --git a/21.md b/21.md index 59a159e..5a8ffe2 100644 --- a/21.md +++ b/21.md @@ -7,7 +7,7 @@ LUD-21: `linkLightningAddress` base spec. ## Linking lightning address to a service -Today users are asked to provide a withdrawal Lightning invoice to a service. This requires some effort and is especially painful when users try to withdraw funds into mobile wallets while using a desktop website. Instead of asking for Lightning invoice a service could display a "withdraw" QR code which contains a specialized `LNURL`. +Paying apps require users to provide a lighning address to the service. Manual enter is difficult and error-prone. Instead the service can ask them to link the lighning address via `LNURL`. ### Wallet to service interaction flow: @@ -16,12 +16,9 @@ Today users are asked to provide a withdrawal Lightning invoice to a service. Th 3. `LN WALLET` gets JSON response from `LN SERVICE` of form: ```Typescript { - "tag": "withdrawRequest", // type of LNURL - "callback": string, // The URL which LN SERVICE would accept a withdrawal Lightning invoice as query parameter - "k1": string, // Random or non-random string to identify the user's LN WALLET when using the callback URL - "defaultDescription": string, // A default withdrawal invoice description - "minWithdrawable": number, // Min amount (in millisatoshis) the user can withdraw from LN SERVICE, or 0 - "maxWithdrawable": number, // Max amount (in millisatoshis) the user can withdraw from LN SERVICE, or equal to minWithdrawable if the user has no choice over the amounts + "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 } ``` or From 34bba0d6d79bfb98155aaca3465d9571537ae1b9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rafa=C5=82=20Gawe=C5=82?= Date: Mon, 5 Feb 2024 12:36:41 +0100 Subject: [PATCH 3/8] Update 21.md --- 21.md | 16 ++++++---------- 1 file changed, 6 insertions(+), 10 deletions(-) diff --git a/21.md b/21.md index 5a8ffe2..bd13969 100644 --- a/21.md +++ b/21.md @@ -18,7 +18,8 @@ Paying apps require users to provide a lighning address to the service. Manual e { "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 + "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 } ``` or @@ -26,19 +27,14 @@ Paying apps require users to provide a lighning address to the service. Manual e ```JSON {"status": "ERROR", "reason": "error details..."} ``` -4. `LN WALLET` Displays a withdraw dialog where user can specify an exact sum to be withdrawn which would be bounded by: - ``` - max can receive = min(maxWithdrawable, local estimation of how much can be routed into wallet) - min can receive = max(minWithdrawable, local minimal value allowed by wallet) - ``` +4. `LN WALLET` displays a dialog: Would you like to share your lightning address (john@doe.com) with ? 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 - &pr= // the payment request generated by the wallet + &la= // user's lighning address ``` -6. `LN SERVICE` sends a `{"status": "OK"}` or `{"status": "ERROR", "reason": "error details..."}` JSON response and then attempts to pay the invoices asynchronously. -7. `LN WALLET` awaits for incoming payment if response was successful. +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 -Note that service will withdraw funds to anyone who can provide a valid ephemeral `k1`. In order to harden this a service may require authorization (LNURL-auth, email link etc.) before displaying a withdraw QR. +Note that service will set a lighning address to anyone who can provide a valid ephemeral `k1`. In order to harden this a service may require authorization (LNURL-auth, email link etc.) before displaying a withdraw QR. From d29549187f08b4d9b8349773a0e55cfad1df23bc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rafa=C5=82=20Gawe=C5=82?= Date: Mon, 5 Feb 2024 12:41:20 +0100 Subject: [PATCH 4/8] Update 21.md --- 21.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/21.md b/21.md index bd13969..73ba481 100644 --- a/21.md +++ b/21.md @@ -7,7 +7,7 @@ LUD-21: `linkLightningAddress` base spec. ## Linking lightning address to a service -Paying apps require users to provide a lighning address to the service. Manual enter is difficult and error-prone. Instead the service can ask them to link the lighning address via `LNURL`. +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: @@ -37,4 +37,4 @@ Paying apps require users to provide a lighning address to the service. Manual e ``` 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 -Note that service will set a lighning address to anyone who can provide a valid ephemeral `k1`. In order to harden this a service may require authorization (LNURL-auth, email link etc.) before displaying a withdraw QR. +Note that service will set a lighning 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. From 6254dfb6d75faa7607c123d66b7d602bf5ff6b23 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rafa=C5=82=20Gawe=C5=82?= Date: Mon, 5 Feb 2024 12:42:57 +0100 Subject: [PATCH 5/8] Update 21.md --- 21.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/21.md b/21.md index 73ba481..3058d52 100644 --- a/21.md +++ b/21.md @@ -27,7 +27,7 @@ Paying apps require users to provide a lighning address to the service. Manual e ```JSON {"status": "ERROR", "reason": "error details..."} ``` -4. `LN WALLET` displays a dialog: Would you like to share your lightning address (john@doe.com) with ? +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 ``` From affbb18c205a917096214ad5d171fd23c2af028b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rafa=C5=82=20Gawe=C5=82?= Date: Thu, 8 Feb 2024 09:34:46 +0100 Subject: [PATCH 6/8] Update 21.md --- 21.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/21.md b/21.md index 3058d52..2a62ca5 100644 --- a/21.md +++ b/21.md @@ -11,7 +11,7 @@ Paying apps require users to provide a lighning address to the service. Manual e ### Wallet to service interaction flow: -1. User scans a LNURL QR code or accesses an `lightning:LNURL..` link with `LN WALLET` and `LN WALLET` decodes LNURL. +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. 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 From 1e17d0ad83ab5269b94683e0a2775eb469bbda20 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rafa=C5=82=20Gawe=C5=82?= Date: Thu, 8 Feb 2024 09:37:57 +0100 Subject: [PATCH 7/8] Update 21.md --- 21.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/21.md b/21.md index 2a62ca5..fbc32ed 100644 --- a/21.md +++ b/21.md @@ -11,7 +11,7 @@ Paying apps require users to provide a lighning address to the service. Manual e ### 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. +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 From 249d21b19a5e4bfad91f517ab01728ddf14b8f62 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rafa=C5=82=20Gawe=C5=82?= Date: Thu, 23 May 2024 10:35:58 +0200 Subject: [PATCH 8/8] Update 21.md --- 21.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/21.md b/21.md index fbc32ed..9891be6 100644 --- a/21.md +++ b/21.md @@ -1,7 +1,7 @@ LUD-21: `linkLightningAddress` base spec. ==================================== -`author: rav3r, jackeveritt` +`author: rav3r` `author: jackeveritt` `author: TheBlueMatt` `author: andreneves` `discussion: https://t.me/lnurl/36910` --- @@ -20,6 +20,7 @@ Paying apps require users to provide a lighning address to the service. Manual e "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 @@ -36,5 +37,7 @@ Paying apps require users to provide a lighning address to the service. Manual e &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 lighning 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. + +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.