diff --git a/21.md b/21.md new file mode 100644 index 0000000..2bd4024 --- /dev/null +++ b/21.md @@ -0,0 +1,57 @@ +LUD-21: Pay in local unit of account. +================================================ + +`author: ethanrose` + +--- + +The idea here is to enable a merchant to receive an exact payment amount, in whatever currency their goods are priced in (i.e. their own fiat currency). A sender should be able to input the amount in the recipient's own unit of account. + +Typically this is for a point-of-sale use-case where a lightning service is acting as a bitcoin-to-fiat payment processor. Currently, a sender would have to use their own calculator to determine how many sats to pay, and the recipient inevitably would receive the close-but-wrong amount. This bad experience is a hinderance to adoption of lightning as a cross-border payment system. + +## 1. `currency` record in payRequest details + +If `SERVICE` wishes for a `WALLET` user to specify a payment amount in a different unit of account, it MUST alter its JSON response in the payRequest details response to include a `currency` object, as follows: + +```diff + { + "callback": String, + "maxSendable": number, + "minSendable": number, + "metadata": string, ++ "currency": { ++ "code": "PHP", ++ "name": "Philippine Pesos", ++ "symbol": "₱", ++ "minSendable": 1, ++ "maxSendable": 50000, ++ "multiplier": 64501 // estimated millisats per "unit" ++ }, + "tag": "payRequest", + } +``` + +NOTE: `SERVICE` must include a `multiplier` property. This is an estimate which helps the `WALLET` do frontend validation & set expectations for users. A simple helper for the `SERVICE` to calculate millisats `multiplier` from common BTC rates is: + +``` +10**11 / btcRate +``` + +## 2. User interface for specifying currency + +If there is a `currency` record in the initial response, `WALLET` must display a modified interface: +- The wallet must display the `currency.code` and/or `currency.name` instead of its default currency. +- The wallet must enforce `currency.minSendable` and `currency.maxSendable`. + +## 3. Including `currency` in callback parameters + +In the next step of the LNURL-Pay flow, `WALLET` must include a `currency` query parameter in the callback along with the `amount`: + +```diff +- amount= ++ amount=¤cy=PHP +``` + +## 4. User interface for reviewing & confirming the exchange rate + +- `WALLET` must display a confirmation screen so that the user can review/verify and "approve" or "confirm" the resulting invoice amount. diff --git a/README.md b/README.md index bd6fd25..c5d6888 100644 --- a/README.md +++ b/README.md @@ -25,6 +25,7 @@ These are all the individual documents describing each small piece of protocol t | [18][18] | Payer identity in `payRequest` protocol. | [Blixt][blixt], [cliché][cliche], [ZBD Discord][zbd], [ZBD Telegram][zbd] | | [19][19] | Pay link discoverable from withdraw link. | [Blixt][blixt], [CoinCorner][coincorner], [SimpleBitcoinWallet][sbw] | | [20][20] | Long payment description for pay protocol. | [Alby][alby], [Blixt][blixt], [Clams][clams], [cliché][cliche], [Phoenix][phoenix] | +| [21][21] | Pay in local unit of account. | [Pouch.ph][pouchph] [alby]: https://github.com/getAlby/lightning-browser-extension [bos]: https://github.com/alexbosworth/balanceofsatoshis @@ -210,6 +211,7 @@ Tools for developers [18]: 18.md [19]: 19.md [20]: 20.md +[21]: 21.md Dependency Tree --------------- diff --git a/dependencies.dot b/dependencies.dot index 867d762..2c4a60f 100644 --- a/dependencies.dot +++ b/dependencies.dot @@ -19,17 +19,19 @@ digraph { 18[label="18 payer identity"] 19[label="19 mutual discoverability"] 20[label="20 long description"] + 21[label="21 pay in local unit of account"] { 01 17 } -> { 02 03 04 06 07 } // base protocols depend on URL format 04 -> { 05 13 } // lnurl-auth seed generation methods 03 -> 08 // fast withdraw 03 -> 14 -> 15 // balanceCheck/balanceNotify - 06 -> 11 // disposable lnurl-pay - 06 -> 20 // long description 06 -> 09 -> 10 // lnurl-pay successAction + 06 -> 11 // disposable lnurl-pay 06 -> 12 // lnurl-pay comments + 06 -> 16 // paying to user@domain.com 06 -> 18 // lnurl-pay payer ids + 06 -> 20 // long description + 06 -> 21 // pay in local unit of account { 04 16 } -> 18 [style="dotted"] // loose relationship of payer id with lnurl-auth and lightning address - 06 -> 16 // paying to user@domain.com { 06 14 } -> 19 // mutually discoverable pay and withdraw links }