diff options
Diffstat (limited to 'design-documents/035-regional-currencies.rst')
-rw-r--r-- | design-documents/035-regional-currencies.rst | 196 |
1 files changed, 196 insertions, 0 deletions
diff --git a/design-documents/035-regional-currencies.rst b/design-documents/035-regional-currencies.rst new file mode 100644 index 00000000..3d62dcc3 --- /dev/null +++ b/design-documents/035-regional-currencies.rst @@ -0,0 +1,196 @@ +DD 35: Regional currencies +########################## + +Summary +======= + +This design document discusses how the GNU Taler wallet can support both +regional currency deployments and official fiat currencies. + +Motivation +========== + +Digital cash in a Taler wallet always requires some kind of trust anchor that +backs its value, be it either an exchange directly or an auditor that vouches +for one or more exchanges. + +The currency code or symbol (EUR, USD, $, ...) is thus not enough to know what +a particular wallet balance really means. It also matters what exchange or +auditor is behind it. Thus the wallet needs some mechanism to allow users to +distinguish between an official deployment of a currency (say EUR in Europe) or +deployments of regional currencies. Regional currencies might have coinciding +currency names for different incompatible deployments (say, MANA to buy Club +Mate drinks at different hacker events with completely separate and independent +Taler deployments). + +Requirements +============ + +* Official deployments for fiat currencies should be supported without clutter +* Regional currencies should be easy to use as well +* It must be easy to integrate regional/official currencies with the existing + Taler auditor/exchange structure +* Wallet users should be able to see disagregated balance between global currencies + and regional currencies supported by different exchanges even if the currency + name is equal. +* Merchants should be able to accept regional and global currencies based on the + supported exchange list. + +Proposed Solution +================= + +Users usually do not want to see and verify the auditor/exchange URL for their +digital cash. The wallet thus needs to support some form of "scope" for +currencies that indicates the trust anchor for particular amounts and balances. + +The scope of a balance/amount gives the user additional information about the +meaning and trust anchor of a balance/amount. The scope is always local and +contextual to the wallet. Depending on the configuration, the wallet can show +different scope information for the exact same coins. + +A balance is in exactly one of three scopes: + +1. Global. An amount in the global scope is by default displayed without + any additional qualification on the currency. +2. Exchange-scoped. An exchange-scoped amount is always displayed with the + prettified base URL of the exchange. +3. Auditor-scoped. An auditor-scoped amount is always displayed with the + prettified base URL of the auditor. When multiple auditors are applicable, + either the one with the lexically smallest base URL is chosen, or the + one that the user/wallet has configured as the prefered one for the currency. + +Whenever the wallet reports an amount, scope information should be +present in the same message with the following format: + +.. code:: TypeScript + + type ScopeInfo = + | { kind: "global" } + | { kind: "exchange", baseUrl: string } + | { kind: "auditor", baseUrl: string }; + +Prettified base URLs +^^^^^^^^^^^^^^^^^^^^ + +The base URLs should be rendered without the ``https://`` and without +trailing slashes: + +* ``https://exchange.demo.taler.net/`` would be rendered as + ``exchange.demo.taler.net``. + +* ``http://ex1.demo.taler.net/`` would be rendered as + ``http://ex1.demo.taler.net``. + +* ``https://ex2.demo.taler.net/foo/bar/`` would be rendered as + ``ex2.demo.taler.net/foo/bar``. + + +Currency Scope Info in the Wallet +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +For each configured currency code, the wallet should store following information: + +* List of global-scope exchanges and currencies for the currency. When this is an empty list, + the currency will always be shown with exchange/auditor scope info. + +Examples +^^^^^^^^ + +The following example shows how a wallet would render balances with +global-scope EUR (i.e. a user would expect these to be "official" EUR that can +be used with multiple vendors in Europe), two exchange-scoped MANA balances and +one auditor-scoped MANA balance. + +.. code:: none + + Balances: + + 1.5 EUR + + 3 MANA ([exchange-icon] exchange.leipzig.ccc.de) + 3.3 MANA ([exchange-icon] exchange.berlin.ccc.de) + 5 MANA ([auditor-icon] auditor.ccc.it] + +Scope information in requests for payments +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +In wallet-to-merchant payments, the merchant specifies which exchanges and +auditors the merchant accepts. It is desirable that the wallet renders the +scope information for a requested amount in a similar way that a balance amount +would be rendered. + +The amount should always be shown in the scope that is compatible with the +merchant and that the wallet holds the highest amount in. + +Let's say a wallet has "auditor.ccc.it" as the global-scope auditor for MANA and holds +mana audited by this auditor. A merchant accepts MANA from this auditor as well +as from the exchange "mana.my-hackerspace.it". + +A payment request could then be rendered like this: + +.. code:: none + + Summary: Club Mate (5x) + Amount: MANA:50 + + +If a wallet (by a non-Italian hacker) would not have "auditor.ccc.it" as the +global-scope auditor for MANA, it would show as: + +.. code:: none + + Summary: Cart #123 at Foomerchant + Amount: MANA:123 ([auditor-icon] auditor.ccc.it) + + Other currencies supported by the merchant: + [exchange-icon] mana.my-hackerspace.it + +The last part should probably be hidden by default. There might be nicer ways to render +this, such as some hoverable (?) icon after the amount that shows details about what currencies the merchant +accepts. + +Wallet-core API for scope management +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +* ``listGlobalCurrencyExchanges`` lists all ``(currency, exchangeUrl, exchangePub)`` triples + where funds are considered to be in global scope (i.e. non-regional). +* ``listGlobalCurrencyAuditors`` lists all ``(currency, auditorUrl, auditorPub)`` triples + where funds are considered to be in global scope (i.e. non-regional). +* ``addGlobalCurrencyExchange`` and ``removeGlobalCurrencyExchange`` adds/removes a ``(currency, exchangeUrl, exchangePub)`` +* ``addGlobalCurrencyAuditor`` and ``removeGlobalCurrencyAuditor`` adds/removes a ``(currency, auditorUrl, auditorPub)`` + + +Implementation Breakdown +^^^^^^^^^^^^^^^^^^^^^^^^ + +* we need test currencies in each scope +* wallet-core needs to add scope information to balances response + and various other requests +* the UI needs to render those +* wallet-core needs to expose new requests to manage currency information +* the UI needs to allow the user to manage currency information + + +Alternatives +============ + +* Completely distinguish regional currencies (non-three-letter currency code) and official currencies + (three letter ISO currency code). This does not help with overlapping regional currency names, + we can't expect them to be unique. + +Drawbacks +========= + +* API and UI changes are required, but they can be made in an incremental and + backwards-compatible manner. +* Scope information could be attached to the currency code. + That's a bad idea, because the scope information is totally local to the wallet. + +Discussion / Q&A +================ + +* Should we allow users to customize how scopes are displayed (e.g. an alias + instead of the full prettified base URL?) +* Do we still need the auditor/exchange URLs with this proposal? +* How does this affect the insufficient balance details? Should we also take scopes + into account here? |