Add proposal for currencies on payRequest

21.md

@@ -31,15 +31,16 @@ type BaseResponse = {
 };
 
 type Currency = {
+  code: string, // Code of the currency, used as an ID for it. E.g.: BRL
   name: string, // Name of the currency. E.g.: Reais
   symbol: string, // Symbol of the currency. E.g.: R$
   displayDecimals: number, // Number of decimal places. E.g.: 2
-  price: number, // Number of currency per BTC. E.g.: 185000
+  multiplier: number, // Number of millisatoshis per smallets unit of currency. E.g.: 5405.405
   convertible?: bool // Whether the currency can be converted into.
 }
 
 type ExtendedResponse = BaseResponse & {
-  currencies: { [key: string]: Currency }
+  currencies: Currency[]
 }
 ```
 
@@ -50,24 +51,26 @@ type ExtendedResponse = BaseResponse & {
   "callback": "https://api.bipa.app/ln/request/invoice/kenu",
   "maxSendable": 1000000000,
   "minSendable": 1000,
-+ "currencies": {
-+   "BRL": {
++ "currencies": [
++   {
++     "code": "BRL",
 +     "name": "Real",
 +     "symbol": "R$",
 +     "displayDecimals": 2,
-+     "price": 185000,
++     "multiplier": 5404.405,
 +     "convertible": true
 +   }
-+ }
++ ]
 }
 ```
 
 - The inclusion of the `currencies` field implies the support of this extension
 - The inclusion of a `currency` implies it can be used for denomination of an amount
 - The inclusion of a `convertible currency` implies the `SERVICE` can quote and guarantee a price for given currency
 - The price returned on this response is not guaranteed by the `SERVICE` and is subject to change
-- The `key` of a `currency` will be used as an identifier for the next request
-- The `key` and other information must be according to [ISO-4217](https://en.wikipedia.org/wiki/ISO_4217) for currencies that are included in it
+- The `code` of a `currency` will be used as an identifier for the next request
+- The `code` and other information must be according to [ISO-4217](https://en.wikipedia.org/wiki/ISO_4217) for currencies that are included in it
+- The order of the `currencies` must be interpreted by the `WALLET` as the receiving user preference for a currency
 
 ### Wallet-side second request
 
@@ -89,10 +92,12 @@ In a more particular case, when user is denominating the amount in `CURRENCY`, b
 
 In another particular case, when the user is denominating the amount in millisatoshi, but wants it to be converted to `CURRENCY` on `SERVICE`.
 ```diff
-- <callback><?|&>amount=<milliSatoshi>
-+ <callback><?|&>amount=<milliSatoshi>&convert=<CURRENCY>
+- <callback><?|&>amount=<millisatoshi>
++ <callback><?|&>amount=<millisatoshi>&convert=<CURRENCY>
 ```
 
+Note that the amount provided in all requests is always in integer number denominated in the smallets possible unit of the selected currency. The smallest unit need to be um sync with the `displayDecimals` parameter, so the `WALLET` has all the needed information to receive input and show output properly.
+
 ### Service-side second response
 
 Upon receiving a currency denominated request from `WALLET`, the `SERVICE` must return a lightning invoice with an amount matching the converted rate from currency. The rate does not need to be the same as provided on the first response.
@@ -132,21 +137,23 @@ These examples show all the possible uses of this extension by a supporting `WAL
   "metadata": "...",
   "minSendable": 1000,
   "maxSendable": 1000000,
-  "currencies": {
-    "BRL": {
+  "currencies": [
+    {
+      "code": "BRL",
       "name": "Reais",
       "symbol": "R$",
       "displayDecimals": 2,
-      "price": 185000,
+      "multiplier": 5405.405,
       "convertible": true
     },
-    "USDT": {
+    {
+      "code": "USDT",
       "name": "Tether",
       "symbol": "₮",
-      "displayDecimals": 2,
-      "price": 38000
+      "displayDecimals": 6,
+      "multiplier": 26315.789
     }
-  }
+  ]
 }
 ```
 
@@ -162,36 +169,36 @@ These examples show all the possible uses of this extension by a supporting `WAL
 // GET bipa.app/callback?amount=538000&convert=BRL
 {
   "pr": "(invoice of 538 sats)",
-  "converted": 1
+  "converted": 100
 }
 ```
-#### Payer sends 1 BRL worth of BTC as BTC
+#### Payer sends 1 BRL (100 cents of BRL) worth of BTC as BTC
 ```json
-// GET bipa.app/callback?amount=1BRL
+// GET bipa.app/callback?amount=100BRL
 {
   "pr": "(invoice of 538 sats)"
 }
 ```
-#### Payer sends 1 BRL worth of BTC as BRL
+#### Payer sends 1 BRL (100 cents of BRL) worth of BTC as BRL
 ```json
-// GET bipa.app/callback?amount=1BRL&convert=BRL
+// GET bipa.app/callback?amount=100BRL&convert=BRL
 {
   "pr": "(invoice of 538 sats)",
-  "converted": 1
+  "converted": 100
 }
 ```
-#### Payer sends 1 BRL worth of BTC as USDT
+#### Payer sends 1 BRL (100 cents of BRL) worth of BTC as USDT (20 cents of USDT)
 ```json
-// GET bipa.app/callback?amount=1BRL&convert=USDT
+// GET bipa.app/callback?amount=100BRL&convert=USDT
 {
   "pr": "(invoice of 538 sats)",
-  "converted": 0.2
+  "converted": 200000
 }
 ```
-#### Payer sends 1 BRL worth of BTC to unsupported
+#### Payer sends 1 BRL (100 cents of BRL) worth of BTC to unsupported
 ```json
-// GET bipa.app/callback?amount=1BRL
-// ERROR, because 1BRL is not a number and can't
+// GET bipa.app/callback?amount=100BRL
+// ERROR, because 100BRL is not a number and can't
 // be interpret as milisatoshis by the unsupported service.
 ```