taler-docs

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

get-max-deposit-amount.rst (4326B)

      1 .. ts:op:: getMaxDepositAmount
      2   :read-only:
      3 
      4   Query the maximum amount that can currently be deposited in the given
      5   currency.
      6 
      7   **Request:**
      8 
      9   The request body must be a `GetMaxDepositAmountRequest` object.  When
     10   ``depositPaytoUri`` is omitted, wire-method eligibility, account
     11   restrictions and wire fees cannot be reflected in the response.
     12 
     13   **Response:**
     14 
     15   On success, the result is a `GetMaxDepositAmountResponse` object.
     16 
     17   **Details:**
     18 
     19   The result distinguishes the maximum that can be deposited
     20   immediately (``material``) from the maximum that also includes the
     21   expected outputs of pending refresh operations (``available``).
     22   ``exchangeDiagnostics`` gives, for every ready same-currency
     23   exchange, the per-exchange maximums and the reasons why the exchange
     24   cannot serve the deposit.
     25 
     26 .. ts:def:: GetMaxDepositAmountRequest
     27 
     28   interface GetMaxDepositAmountRequest {
     29     // Currency to deposit.
     30     currency: string;
     31 
     32     // Target bank account to deposit into.  When omitted, wire-method
     33     // eligibility, account restrictions and wire fees cannot be
     34     // reflected in the response.
     35     depositPaytoUri?: string;
     36 
     37     // Restrict the deposit to a certain scope.
     38     restrictScope?: ScopeInfo;
     39   }
     40 
     41 .. ts:def:: GetMaxDepositAmountResponse
     42 
     43   interface GetMaxDepositAmountResponse {
     44     // Maximum that can be deposited immediately.
     45     material: DepositMaximum;
     46 
     47     // Maximum including expected outputs of pending refresh
     48     // operations.
     49     available: DepositMaximum;
     50 
     51     // Eligibility and maximum amounts for every ready same-currency
     52     // exchange.
     53     exchangeDiagnostics: Record<string, DepositExchangeDiagnostics>;
     54   }
     55 
     56 .. ts:def:: DepositMaximum
     57 
     58   // Maximum amounts and fees for one coherent deposit coin selection.
     59   interface DepositMaximum {
     60     // Gross target amount passed to checkDeposit or
     61     // createDepositGroup.
     62     instructedAmount: AmountString;
     63 
     64     // Total balance effect on the wallet: instructed amount plus fees
     65     // paid by the customer and the cost of refreshing any change.
     66     effectiveAmount: AmountString;
     67 
     68     // Amount expected to reach the destination account: instructed
     69     // amount minus fees covered by the counterparty.
     70     rawAmount: AmountString;
     71 
     72     // Total fees incurred by this deposit selection.
     73     fees: DepositGroupFees;
     74   }
     75 
     76 .. ts:def:: DepositExchangeDiagnostics
     77 
     78   interface DepositExchangeDiagnostics {
     79     // Maximum that can be deposited immediately.
     80     material: DepositMaximum;
     81 
     82     // Maximum including expected outputs of pending refresh
     83     // operations.
     84     available: DepositMaximum;
     85 
     86     // Eligibility failures, in deterministic evaluation order.
     87     reasons: DepositEligibilityReason[];
     88   }
     89 
     90 .. ts:def:: DepositEligibilityReason
     91 
     92   // Reason why a ready, same-currency exchange cannot serve a deposit.
     93   type DepositEligibilityReason =
     94     | { type: "direct-deposit-disabled" }
     95     | { type: "scope-restricted"; scopeInfo: ScopeInfo }
     96     | { type: "wire-method-unsupported"; wireMethod: string }
     97     | { type: "wire-fee-unavailable"; wireMethod: string }
     98     | {
     99         type: "deposit-account-restricted";
    100         wireMethod: string;
    101         accountRestrictions: Record<string, AccountRestriction[]>;
    102       };
    103 
    104 .. ts:def:: DepositEligibilityReasonType
    105 
    106   type DepositEligibilityReasonType =
    107     "direct-deposit-disabled"
    108     | "scope-restricted"
    109     | "wire-method-unsupported"
    110     | "wire-fee-unavailable"
    111     | "deposit-account-restricted";
    112 
    113 .. ts:def:: AccountRestriction
    114 
    115   type AccountRestriction =
    116     | RegexAccountRestriction
    117     | DenyAllAccountRestriction;
    118 
    119 .. ts:def:: RegexAccountRestriction
    120 
    121   // Accounts interacting with this type of account restriction must
    122   // have a payto://-URI matching the given regex.
    123   interface RegexAccountRestriction {
    124     type: "regex";
    125 
    126     // Regular expression that the payto://-URI of the partner account
    127     // must follow (posix-egrep, without support for character
    128     // classes, GNU extensions, back-references or intervals).
    129     payto_regex: string;
    130 
    131     // Hint for a human to understand the restriction.
    132     human_hint: string;
    133 
    134     // Map from IETF BCP 47 language tags to localized human hints.
    135     human_hint_i18n?: InternationalizedString;
    136   }
    137 
    138 .. ts:def:: DenyAllAccountRestriction
    139 
    140   interface DenyAllAccountRestriction {
    141     type: "deny";
    142   }