currency-spec.rst (2944B)
1 .. 2 This file is part of GNU TALER. 3 Copyright (C) 2014-2024 Taler Systems SA 4 5 TALER is free software; you can redistribute it and/or modify it under the 6 terms of the GNU Affero General Public License as published by the Free Software 7 Foundation; either version 2.1, or (at your option) any later version. 8 9 TALER is distributed in the hope that it will be useful, but WITHOUT ANY 10 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR 11 A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details. 12 13 You should have received a copy of the GNU Affero General Public License along with 14 TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/> 15 16 @author Florian Dold 17 @author Christian Grothoff 18 @author Marc Stibane 19 20 21 CURRENCY SPECIFICATIONS 22 ----------------------- 23 24 Sections with a name of the form “[currency-$NAME]” (where "$NAME" could 25 be any unique string) are used to specify details about how currencies 26 should be handled (and in particularly rendered) by the user interface. 27 A detailed motivation for this section can be found in DD51. 28 Different components can have different rules for the same currency. For 29 example, a bank or merchant may decide to render Euros or Dollars with 30 always exactly two fractional decimals, while an Exchange for the same 31 currency may support additional decimals. The required options in each 32 currency specification section are: 33 34 ENABLED 35 Set to YES or NO. If set to NO, the currency specification 36 section is ignored. Can be used to disable currencies or 37 select alternative sections for the same CODE with different 38 choices. 39 40 CODE 41 Code name for the currency. Can be at most 11 characters, 42 only the letters A-Z are allowed. Primary way to identify 43 the currency in the protocol. 44 45 NAME 46 Long human-readable name for the currency. No restrictions, 47 but should match the official name in English. 48 49 FRACTIONAL_INPUT_DIGITS 50 Number of fractional digits that users are allowed to enter 51 manually in the user interface. 52 53 FRACTIONAL_NORMAL_DIGITS 54 Number of fractional digits that will be rendered normally 55 (in terms of size and placement). Digits shown beyond this 56 number will typically be rendered smaller and raised (if 57 possible). 58 59 FRACTIONAL_TRAILING_ZERO_DIGITS 60 Number of fractional digits to pad rendered amounts with 61 even if these digits are all zero. For example, use 2 to 62 render 1 USD as $1.00. 63 64 ALT_UNIT_NAMES 65 JSON map determining how to encode very large or very tiny 66 amounts in this currency. Maps a base10 logarithm to the 67 respective currency symbol. Must include at least an 68 entry for 0 (currency unit). For example, use 69 {"0":"€"} for Euros or "{"0":"$"} for Dollars. You could 70 additionally use {"0":"€","3":"k€"} to render 3000 EUR 71 as 3k€. For BTC a typical map would be 72 {"0":"BTC","-3":"mBTC"}, informing the UI to render small 73 amounts in milli-Bitcoin (mBTC).