035-regional-currencies.rst (7726B)
1 DD 35: Regional currencies 2 ########################## 3 4 :Design status: Accepted 5 :Implementation status: Partial 6 :DD shepherd: TBD 7 :Historical contributors: Florian Dold, Sebastian 8 :First published: 2023-02-06 9 :Last substantive change: 2024-02-06 10 :Implementation evidence: taler-typescript-core (2023-02-12), taler-android (2023-11-29), taler-ios (2024-02-10) 11 :Normative references: ``wallet/wallet-core.md`` 12 13 Summary 14 ======= 15 16 This design document discusses how the GNU Taler wallet can support both 17 regional currency deployments and official fiat currencies. 18 19 Motivation 20 ========== 21 22 Digital cash in a Taler wallet always requires some kind of trust anchor that 23 backs its value, be it either an exchange directly or an auditor that vouches 24 for one or more exchanges. 25 26 The currency code or symbol (EUR, USD, $, ...) is thus not enough to know what 27 a particular wallet balance really means. It also matters what exchange or 28 auditor is behind it. Thus the wallet needs some mechanism to allow users to 29 distinguish between an official deployment of a currency (say EUR in Europe) or 30 deployments of regional currencies. Regional currencies might have coinciding 31 currency names for different incompatible deployments (say, MANA to buy Club 32 Mate drinks at different hacker events with completely separate and independent 33 Taler deployments). 34 35 Requirements 36 ============ 37 38 * Official deployments for fiat currencies should be supported without clutter 39 * Regional currencies should be easy to use as well 40 * It must be easy to integrate regional/official currencies with the existing 41 Taler auditor/exchange structure 42 * Wallet users should be able to see disagregated balance between global currencies 43 and regional currencies supported by different exchanges even if the currency 44 name is equal. 45 * Merchants should be able to accept regional and global currencies based on the 46 supported exchange list. 47 48 Proposed Solution 49 ================= 50 51 Users usually do not want to see and verify the auditor/exchange URL for their 52 digital cash. The wallet thus needs to support some form of "scope" for 53 currencies that indicates the trust anchor for particular amounts and balances. 54 55 The scope of a balance/amount gives the user additional information about the 56 meaning and trust anchor of a balance/amount. The scope is always local and 57 contextual to the wallet. Depending on the configuration, the wallet can show 58 different scope information for the exact same coins. 59 60 A balance is in exactly one of three scopes: 61 62 1. Global. An amount in the global scope is by default displayed without 63 any additional qualification on the currency. 64 2. Exchange-scoped. An exchange-scoped amount is always displayed with the 65 prettified base URL of the exchange. 66 3. Auditor-scoped. An auditor-scoped amount is always displayed with the 67 prettified base URL of the auditor. When multiple auditors are applicable, 68 either the one with the lexically smallest base URL is chosen, or the 69 one that the user/wallet has configured as the prefered one for the currency. 70 71 Whenever the wallet reports an amount, scope information should be 72 present in the same message with the following format: 73 74 .. code:: TypeScript 75 76 type ScopeInfo = 77 | { kind: "global" } 78 | { kind: "exchange", baseUrl: string } 79 | { kind: "auditor", baseUrl: string }; 80 81 Prettified base URLs 82 ^^^^^^^^^^^^^^^^^^^^ 83 84 The base URLs should be rendered without the ``https://`` and without 85 trailing slashes: 86 87 * ``https://exchange.demo.taler.net/`` would be rendered as 88 ``exchange.demo.taler.net``. 89 90 * ``http://ex1.demo.taler.net/`` would be rendered as 91 ``http://ex1.demo.taler.net``. 92 93 * ``https://ex2.demo.taler.net/foo/bar/`` would be rendered as 94 ``ex2.demo.taler.net/foo/bar``. 95 96 97 Currency Scope Info in the Wallet 98 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 99 100 For each configured currency code, the wallet should store following information: 101 102 * List of global-scope exchanges and currencies for the currency. When this is an empty list, 103 the currency will always be shown with exchange/auditor scope info. 104 105 Examples 106 ^^^^^^^^ 107 108 The following example shows how a wallet would render balances with 109 global-scope EUR (i.e. a user would expect these to be "official" EUR that can 110 be used with multiple vendors in Europe), two exchange-scoped MANA balances and 111 one auditor-scoped MANA balance. 112 113 .. code:: none 114 115 Balances: 116 117 1.5 EUR 118 119 3 MANA ([exchange-icon] exchange.leipzig.ccc.de) 120 3.3 MANA ([exchange-icon] exchange.berlin.ccc.de) 121 5 MANA ([auditor-icon] auditor.ccc.it] 122 123 Scope information in requests for payments 124 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 125 126 In wallet-to-merchant payments, the merchant specifies which exchanges and 127 auditors the merchant accepts. It is desirable that the wallet renders the 128 scope information for a requested amount in a similar way that a balance amount 129 would be rendered. 130 131 The amount should always be shown in the scope that is compatible with the 132 merchant and that the wallet holds the highest amount in. 133 134 Let's say a wallet has "auditor.ccc.it" as the global-scope auditor for MANA and holds 135 mana audited by this auditor. A merchant accepts MANA from this auditor as well 136 as from the exchange "mana.my-hackerspace.it". 137 138 A payment request could then be rendered like this: 139 140 .. code:: none 141 142 Summary: Club Mate (5x) 143 Amount: MANA:50 144 145 146 If a wallet (by a non-Italian hacker) would not have "auditor.ccc.it" as the 147 global-scope auditor for MANA, it would show as: 148 149 .. code:: none 150 151 Summary: Cart #123 at Foomerchant 152 Amount: MANA:123 ([auditor-icon] auditor.ccc.it) 153 154 Other currencies supported by the merchant: 155 [exchange-icon] mana.my-hackerspace.it 156 157 The last part should probably be hidden by default. There might be nicer ways to render 158 this, such as some hoverable (?) icon after the amount that shows details about what currencies the merchant 159 accepts. 160 161 Wallet-core API for scope management 162 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 163 164 * ``listGlobalCurrencyExchanges`` lists all ``(currency, exchangeUrl, exchangePub)`` triples 165 where funds are considered to be in global scope (i.e. non-regional). 166 * ``listGlobalCurrencyAuditors`` lists all ``(currency, auditorUrl, auditorPub)`` triples 167 where funds are considered to be in global scope (i.e. non-regional). 168 * ``addGlobalCurrencyExchange`` and ``removeGlobalCurrencyExchange`` adds/removes a ``(currency, exchangeUrl, exchangePub)`` 169 * ``addGlobalCurrencyAuditor`` and ``removeGlobalCurrencyAuditor`` adds/removes a ``(currency, auditorUrl, auditorPub)`` 170 171 172 Implementation Breakdown 173 ^^^^^^^^^^^^^^^^^^^^^^^^ 174 175 * we need test currencies in each scope 176 * wallet-core needs to add scope information to balances response 177 and various other requests 178 * the UI needs to render those 179 * wallet-core needs to expose new requests to manage currency information 180 * the UI needs to allow the user to manage currency information 181 182 183 Alternatives 184 ============ 185 186 * Completely distinguish regional currencies (non-three-letter currency code) and official currencies 187 (three letter ISO currency code). This does not help with overlapping regional currency names, 188 we can't expect them to be unique. 189 190 Drawbacks 191 ========= 192 193 * API and UI changes are required, but they can be made in an incremental and 194 backwards-compatible manner. 195 * Scope information could be attached to the currency code. 196 That's a bad idea, because the scope information is totally local to the wallet. 197 198 Discussion / Q&A 199 ================ 200 201 * Should we allow users to customize how scopes are displayed (e.g. an alias 202 instead of the full prettified base URL?) 203 * Do we still need the auditor/exchange URLs with this proposal? 204 * How does this affect the insufficient balance details? Should we also take scopes 205 into account here?