diff --git a/24.md b/24.md new file mode 100644 index 0000000..72e6d7d --- /dev/null +++ b/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 +- amount= ++ currency=PHP&amount= +``` + +- 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.