taler-docs

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

get-balances.rst (6568B)


      1 .. ts:op:: getBalances
      2   :read-only:
      3 
      4   Get current wallet balance.
      5 
      6   Balances are reported per *scope* (`ScopeInfo`): funds held globally
      7   for a currency, at a particular exchange, under a particular auditor
      8   or under a superseded exchange master key are reported as separate
      9   balances.
     10 
     11   **Request:**
     12 
     13   This operation takes no arguments (an empty object).
     14 
     15   **Response:**
     16 
     17   On success, the result is a `BalancesResponse` object.
     18 
     19   **Details:**
     20 
     21   Each balance distinguishes three amounts.  ``available`` is the
     22   balance available for spending from transactions in their final state,
     23   plus amounts expected to become available from pending refreshes.
     24   ``pendingIncoming`` is the expected positive delta to the available
     25   balance once pending operations (such as withdrawals or incoming peer
     26   payments) reach the "done" state.  ``pendingOutgoing`` is the amount
     27   currently allocated to spend operations that could still be aborted,
     28   in which case part of the amount may be recovered.
     29 
     30 .. ts:def:: BalancesResponse
     31 
     32   interface BalancesResponse {
     33     // Electronic cash balances, per currency scope.
     34     balances: WalletBalance[];
     35 
     36     // Does the user have money from an exchange other than demo or test?
     37     haveProdBalance: boolean;
     38 
     39     // Summary of donations, per donau/year/currency.
     40     donauSummary?: DonauSummaryItem[];
     41   }
     42 
     43 .. ts:def:: WalletBalance
     44 
     45   interface WalletBalance {
     46     // True when funds in this scope are at risk of expiring.
     47     hasExpirationRisk?: boolean;
     48 
     49     // Scope of the funds covered by this balance.
     50     scopeInfo: ScopeInfo;
     51 
     52     // Balance available for spending, including amounts
     53     // expected from pending refreshes.
     54     available: AmountString;
     55 
     56     // Expected positive delta to the available balance
     57     // from pending operations.
     58     pendingIncoming: AmountString;
     59 
     60     // Amount allocated to spend operations that could still be aborted.
     61     pendingOutgoing: AmountString;
     62 
     63     // Pending KYC or confirmation steps affecting this balance.
     64     flags: BalanceFlag[];
     65 
     66     // Available URLs for pages that list
     67     // where money in this scope can be spent.
     68     shoppingUrls?: string[];
     69 
     70     // Are p2p payments disabled for this scope?
     71     disablePeerPayments?: boolean;
     72 
     73     // Are wallet deposits disabled for this scope?
     74     disableDirectDeposits?: boolean;
     75   }
     76 
     77 .. ts:op:: getBalanceRefreshInfo
     78   :read-only:
     79 
     80   Takes ``{ scopeInfo: ScopeInfo }`` and returns the current
     81   `WalletRefreshInfo` for the requested balance, or ``null`` if that balance
     82   no longer exists. The request waits for a fresh calculation. The annual
     83   cost bound can be unavailable when the wallet lacks sufficient information.
     84 
     85 .. ts:op:: observeBalanceRefreshInfo
     86 
     87   Takes ``{ scopeInfo: ScopeInfo, observationId: string }`` and returns
     88   an empty object. Install the notification listener before registering.
     89   The ID follows the same uniqueness and lifetime rules as
     90   :ts:op:`observeTransaction`. The initial report and subsequent distinct
     91   reports arrive as `BalanceRefreshSnapshotNotification` snapshots. A null
     92   report ends the observation when the scope is absent. Use
     93   :ts:op:`stopObservation` when the view closes.
     94 
     95 .. ts:def:: WalletRefreshInfo
     96 
     97   interface WalletRefreshInfo {
     98     risks: CashExpirationRisk[];
     99     recoveries: CashRenewalNotice[];
    100     annualCostBound: AnnualRefreshCostBound;
    101   }
    102 
    103 .. ts:def:: CashExpirationRisk
    104 
    105   interface CashExpirationRisk {
    106     exchangeBaseUrl: string;
    107     exchangeMasterPub: string;
    108     amount: AmountString;
    109     earliestDepositExpiration: TalerProtocolTimestamp;
    110     reason:
    111       | "pending"
    112       | "connectivity"
    113       | "exchange-error"
    114       | "no-replacement"
    115       | "checking"
    116       | "invalid-lifetime";
    117   }
    118 
    119 .. ts:def:: CashRenewalNotice
    120 
    121   interface CashRenewalNotice {
    122     warningId: string;
    123     exchangeBaseUrl: string;
    124     exchangeMasterPub: string;
    125     amount: AmountString;
    126     oldDepositExpiration: TalerProtocolTimestamp;
    127     newDepositExpiration: TalerProtocolTimestamp;
    128     // Earliest emergency threshold of the renewed coins.
    129     nextRelevantDate: TalerProtocolTimestamp;
    130   }
    131 
    132 .. ts:def:: AnnualRefreshCostBound
    133 
    134   // Conditional on stable, continuously available compatible
    135   // offerings and timely reveal.
    136   type AnnualRefreshCostBound = {
    137     horizonDays: 365;
    138     projection: "stable-current-offerings";
    139   } & (
    140     | {
    141         status: "available";
    142         amount: AmountString;
    143       }
    144     | {
    145         status: "unavailable";
    146         reasons: string[];
    147       }
    148   );
    149 
    150 .. ts:def:: ScopeInfo
    151 
    152   // Scope of a balance; identifies the trust domain
    153   // the funds belong to.
    154   type ScopeInfo =
    155     | ScopeInfoGlobal
    156     | ScopeInfoExchange
    157     | ScopeInfoAuditor
    158     | ScopeInfoExchangeLegacyKeys;
    159 
    160 .. ts:def:: ScopeInfoGlobal
    161 
    162   // Funds held with an exchange that is globally
    163   // trusted for the currency.
    164   type ScopeInfoGlobal = {
    165     type: "global";
    166     currency: string;
    167   };
    168 
    169 .. ts:def:: ScopeInfoExchange
    170 
    171   // Funds held at one particular exchange.
    172   type ScopeInfoExchange = {
    173     type: "exchange";
    174     currency: string;
    175     url: string;
    176   };
    177 
    178 .. ts:def:: ScopeInfoAuditor
    179 
    180   // Funds whose denominations are audited by a globally
    181   // trusted auditor.
    182   type ScopeInfoAuditor = {
    183     type: "auditor";
    184     currency: string;
    185     url: string;
    186   };
    187 
    188 .. ts:def:: ScopeInfoExchangeLegacyKeys
    189 
    190   // Funds issued under a master public key that the exchange has
    191   // since replaced; never pooled with funds under the current key.
    192   type ScopeInfoExchangeLegacyKeys = {
    193     type: "exchange-legacy-keys";
    194     currency: string;
    195     url: string;
    196     // The superseded key the funds were issued under.
    197     masterPub: string;
    198   };
    199 
    200 .. ts:def:: BalanceFlag
    201 
    202   // Flag marking a pending KYC, AML or confirmation step for
    203   // the incoming or outgoing funds of a balance.
    204   type BalanceFlag =
    205     | "incoming-kyc"
    206     | "incoming-aml"
    207     | "incoming-confirmation"
    208     | "outgoing-kyc";
    209 
    210 .. ts:def:: DonauSummaryItem
    211 
    212   interface DonauSummaryItem {
    213     // Base URL of the donau service.
    214     donauBaseUrl: string;
    215 
    216     // Legal domain of the donau service (if available).
    217     legalDomain?: string;
    218 
    219     // Year of the donation(s).
    220     year: number;
    221 
    222     // Sum of donation receipts received from merchants
    223     // in the applicable year.
    224     amountReceiptsAvailable: AmountString;
    225 
    226     // Sum of donation receipts already submitted to the
    227     // donau in the applicable year.
    228     amountReceiptsSubmitted: AmountString;
    229 
    230     // Amount of the latest available statement.  Missing
    231     // if no statement was requested yet.
    232     amountStatement?: AmountString;
    233   }