LUD-XX: Currencies

24.md

@@ -0,0 +1,81 @@
+LUD-24: `currencies` base spec.
+=======================================
+
+`author: ethanrose` `author: lsunsi` `author: lorenzolfm` `author: jklein24`
+
+---
+
+## Support for LNURL-pay currencies
+
+This document describes an extension to the [payRequest](https://github.com/lnurl/luds/blob/luds/06.md) base specification that allows the `WALLET` to send money to a `SERVICE` while denominating the amount in a different currency. The features proposed enable many use cases including:
+
+- Bitcoin-settled cash remittances
+- Merchant bitcoin acceptance
+- Lightning address aliases for bank & mobile money accounts
+- Cross-border payroll
+
+
+The main features provided by this extension are:
+- `SERVICE` **MAY** provide `WALLET` with a list of supported currencies.
+- `WALLET` **MAY** allow user to request an invoice for an amount denominated in a supported currency in place of millisats.
+
+
+### 1. `currencies` array in payRequest details
+
+`SERVICE` must alter its JSON response to the first request to include a `currencies` field, as follows:
+
+```diff
+{
+  "tag": "payRequest",
+  "callback": string,
+  "maxSendable": number,
+  "minSendable": number,
+  "metadata": string,
++ "currencies": [
++   {
++     "code": "PHP",
++     "name": "Philippine Pesos",
++     "symbol": "₱",
++     "decimals": 2,
++     "minSendable": 1,
++     "maxSendable": 50000,
++     "multiplier": 64501 // (optional)
++   }
++ ]
+}
+```
+
+- The inclusion of the `currencies` field indicates the support of this extension
+- The `multiplier` may be included for informational purposes, not a guaranteed rate
+- The `code` of a `currency` must be unique
+- The order of the `currencies` may be interpreted by the `WALLET` as the receiving user preference for a currency
+
+
+### 2. Wallet interface
+
+If there is a `currency` record, `WALLET` should display a modified interface:
+- Display currency symbol and code
+- If there are multiple currency options, allow user to select/change currencies
+- Validate "decimals" count for user amount input
+
+
+### 3. Including `currency` in callback parameters
+
+```diff
+- <callback><?|&>amount=<number>
++ <callback><?|&>currency=PHP&amount=<numberInSmallestUnit>
+```
+
+- Amount must be in SMALLEST UNIT INTEGER (wallet should use `decimals` value to modify amount)
+- If `currency` param is omitted, the `amount` will be interpreted as millisatoshis (base spec)
+
+
+### 4. Service processing
+
+`SERVICE` response is unchanged.
+
+`SERVICE` may optionally lock-in a rate and auto-convert to the specified currency, but that is a `SERVICE` / recipient decision, not relevant to the `WALLET` / sender.
+
+### 5. User interface for reviewing & confirming the exchange rate
+
+`WALLET` must display a confirmation screen so that the user can review and confirm the invoice amount.