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