taler-docs

Documentation for GNU Taler components, APIs and protocols
Log | Files | Refs | README | LICENSE

get-currency-specification.rst (2812B)

      1 .. ts:op:: getCurrencySpecification
      2   :read-only:
      3 
      4   Get the currency specification (input and rendering rules) for a
      5   currency scope.
      6 
      7   **Request:**
      8 
      9     The request must be a `GetCurrencySpecificationRequest` object.
     10 
     11   **Response:**
     12 
     13     On success, the result is a `GetCurrencySpecificationResponse`
     14     object.
     15 
     16   **Details:**
     17 
     18     The specification recorded for the given scope is returned.  For
     19     the demonstration currencies ``KUDOS`` and ``TESTKUDOS``, a
     20     hard-coded specification is returned.  When no specification is
     21     known for the scope, a default with two fractional digits
     22     derived from the currency name is returned.
     23 
     24 .. ts:def:: GetCurrencySpecificationRequest
     25 
     26   interface GetCurrencySpecificationRequest {
     27     scope: ScopeInfo;
     28   }
     29 
     30 .. ts:def:: GetCurrencySpecificationResponse
     31 
     32   interface GetCurrencySpecificationResponse {
     33     currencySpecification: CurrencySpecification;
     34   }
     35 
     36 .. ts:def:: ScopeInfo
     37 
     38   // Currency scope, discriminated on the "type" field.
     39   type ScopeInfo =
     40     | ScopeInfoGlobal
     41     | ScopeInfoExchange
     42     | ScopeInfoAuditor
     43     | ScopeInfoExchangeLegacyKeys;
     44 
     45 .. ts:def:: ScopeInfoGlobal
     46 
     47   type ScopeInfoGlobal = {
     48     type: ScopeType.Global;
     49     currency: string;
     50   };
     51 
     52 .. ts:def:: ScopeInfoExchange
     53 
     54   type ScopeInfoExchange = {
     55     type: ScopeType.Exchange;
     56     currency: string;
     57     url: string;
     58   };
     59 
     60 .. ts:def:: ScopeInfoAuditor
     61 
     62   type ScopeInfoAuditor = {
     63     type: ScopeType.Auditor;
     64     currency: string;
     65     url: string;
     66   };
     67 
     68 .. ts:def:: ScopeInfoExchangeLegacyKeys
     69 
     70   type ScopeInfoExchangeLegacyKeys = {
     71     type: ScopeType.ExchangeLegacyKeys;
     72     currency: string;
     73     url: string;
     74 
     75     // The superseded key the funds were issued under.
     76     masterPub: string;
     77   };
     78 
     79 .. ts:def:: ScopeType
     80 
     81   enum ScopeType {
     82     Global = "global",
     83     Exchange = "exchange",
     84     Auditor = "auditor",
     85 
     86     // Funds issued under a master public key the exchange has
     87     // since replaced.
     88     ExchangeLegacyKeys = "exchange-legacy-keys",
     89   }
     90 
     91 .. ts:def:: CurrencySpecification
     92 
     93   // Input and rendering rules for a currency (see DD51).
     94   interface CurrencySpecification {
     95     // Name of the currency.
     96     name: string;
     97 
     98     // How many digits the user may enter after the decimal
     99     // separator.
    100     num_fractional_input_digits: Integer;
    101 
    102     // Number of fractional digits to render in normal font and
    103     // size.
    104     num_fractional_normal_digits: Integer;
    105 
    106     // Number of fractional digits to render always, padding with
    107     // zeros if needed.
    108     num_fractional_trailing_zero_digits: Integer;
    109 
    110     // Map of powers of 10 to alternative currency names / symbols;
    111     // always has an entry under "0" with the base name, e.g.
    112     // "0 => €" or "3 => k€".
    113     alt_unit_names: { [log10: string]: string };
    114 
    115     common_amounts?: AmountString[];
    116   }