taler-docs

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

post-fountain-withdraw.rst (4619B)

      1 .. http:post:: [/instances/$INSTANCE]/fountain/withdraw
      2 
      3   Used by wallets to withdraw blind-signed tokens for any subset of
      4   the fountain's grants in a single request. The request is
      5   structured per grant: each entry addresses one granted token
      6   family and one key slot, and carries the envelopes to sign
      7   against that grant's limits.
      8   This endpoint is available since protocol **vTokenFountains**.
      9 
     10   The fountain secret travels in the request body, never in the
     11   URL.
     12 
     13   A wallet may retry a withdrawal with the same ``grants`` array and
     14   fountain credential. The backend identifies a completed withdrawal
     15   by its canonical JSON hash within that fountain and returns the
     16   original grant results, without consuming quota again. Keep the
     17   envelopes, array order, and ``valid_at`` values (including omission)
     18   unchanged when retrying; JSON whitespace and object member order do
     19   not matter.
     20 
     21   A completed result is retained in full until the latest issue-key expiry
     22   among all entries of that withdrawal, even if some entries expire earlier.
     23   This holds across changes to the grants or the key window of the fountain.
     24   Afterwards the result may be garbage collected, and a repeated request is
     25   treated as a new one; deleting the fountain drops its results at once.
     26   Quota consumption, issued-token records and the replay result are
     27   committed together before a successful response is sent.
     28 
     29   **Request:**
     30 
     31   The request must be a `FountainWithdrawRequest`.
     32 
     33   At most 64 token envelopes may be submitted in total across all grants
     34   in one request. Exceeding this limit returns ``400 Bad Request`` with
     35   ``TALER_EC_GENERIC_PARAMETER_MALFORMED``.
     36 
     37   **Response:**
     38 
     39   :http:statuscode:`200 OK`:
     40     The tokens were blind-signed.
     41     Returns a `FountainWithdrawResponse`.
     42   :http:statuscode:`400 Bad Request`:
     43     The request body is malformed.
     44     Returned with ``TALER_EC_GENERIC_PARAMETER_MALFORMED``.
     45   :http:statuscode:`401 Unauthorized`:
     46     The fountain secret is unknown. This includes deleted
     47     fountains: the wallet should report the access as revoked.
     48   :http:statuscode:`404 Not found`:
     49     A token family or issue key disappeared during processing, returned with
     50     ``TALER_EC_MERCHANT_PRIVATE_POST_ORDERS_TOKEN_FAMILY_SLUG_UNKNOWN``
     51     or ``TALER_EC_MERCHANT_GENERIC_TOKEN_KEY_UNKNOWN``.
     52   :http:statuscode:`409 Conflict`:
     53     An entry refers to a token family without a matching grant,
     54     or its ``valid_at`` lies outside the grant's key window.
     55   :http:statuscode:`429 Too many requests`:
     56     The grant's ``tokens_per_period_limit`` is exhausted for the
     57     requested slot.
     58   :http:statuscode:`500 Internal Server Error`:
     59     The server experienced an internal failure.
     60 
     61   **Details:**
     62 
     63   .. ts:def:: FountainWithdrawRequest
     64 
     65     interface FountainWithdrawRequest {
     66 
     67       // The fountain's bearer credential.
     68       fountain_secret: string;
     69 
     70       // One entry per (granted token family, key slot) being
     71       // withdrawn from. At most one entry per such pair.
     72       grants: FountainGrantWithdrawal[];
     73     }
     74 
     75   .. ts:def:: FountainGrantWithdrawal
     76 
     77     interface FountainGrantWithdrawal {
     78 
     79       // Token family to withdraw from. Must match one of the
     80       // fountain's grants.
     81       token_family_slug: Slug;
     82 
     83       // Desired validity time of the tokens; selects the issue
     84       // key slot. Must lie within the grant's
     85       // ``key_window_size``. Defaults to "now".
     86       valid_at?: Timestamp;
     87 
     88       // Blinded envelopes to sign with the selected slot's issue
     89       // key, as in the pay protocol. The number of envelopes is
     90       // counted against the grant's ``tokens_per_period_limit``
     91       // for that slot.
     92       // Must be nonempty; the entire request may contain at most 64 envelopes.
     93       envelopes: TokenEnvelope[];
     94     }
     95 
     96   .. ts:def:: FountainWithdrawResponse
     97 
     98     interface FountainWithdrawResponse {
     99 
    100       // One entry per entry in the request's ``grants`` array,
    101       // in the same order.
    102       grants: FountainGrantWithdrawalResult[];
    103     }
    104 
    105   .. ts:def:: FountainGrantWithdrawalResult
    106 
    107     interface FountainGrantWithdrawalResult {
    108 
    109       // Token family these signatures belong to.
    110       token_family_slug: Slug;
    111 
    112       // Hash of the issue public key that was used, so the
    113       // wallet can associate the tokens with the right slot.
    114       h_issue: HashCode;
    115 
    116       // Blind signatures, in the same order as the ``envelopes``
    117       // of the request entry. Uses the same format as token_sigs
    118       // in the order payment response: each entry wraps a
    119       // TokenIssueBlindSig in a blind_sig field.
    120       token_sigs: SignedTokenEnvelope[];
    121     }