LUD-21: Specify a payment amount in local unit of account

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
+- <callback><?|&>amount=<milliSatoshi>
++ <callback><?|&>amount=<philippinePeso>&currency=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.

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
 ---------------

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
 }