taler-docs

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

post-fountain-withdraw.rst (3091B)

      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   **Request:**
     14 
     15   The request must be a `FountainWithdrawRequest`.
     16 
     17   **Response:**
     18 
     19   :http:statuscode:`200 OK`:
     20     The tokens were blind-signed.
     21     Returns a `FountainWithdrawResponse`.
     22   :http:statuscode:`400 Bad Request`:
     23     The request body is malformed.
     24     Returned with ``TALER_EC_GENERIC_PARAMETER_MALFORMED``.
     25   :http:statuscode:`401 Unauthorized`:
     26     The fountain secret is unknown. This includes deleted
     27     fountains: the wallet should report the access as revoked.
     28   :http:statuscode:`409 Conflict`:
     29     An entry refers to a token family without a matching grant,
     30     or its ``valid_at`` lies outside the grant's key window.
     31   :http:statuscode:`429 Too many requests`:
     32     The grant's ``tokens_per_period_limit`` is exhausted for the
     33     requested slot.
     34   :http:statuscode:`500 Internal Server Error`:
     35     The server experienced an internal failure.
     36 
     37   **Details:**
     38 
     39   .. ts:def:: FountainWithdrawRequest
     40 
     41     interface FountainWithdrawRequest {
     42 
     43       // The fountain's bearer credential.
     44       fountain_secret: string;
     45 
     46       // One entry per (granted token family, key slot) being
     47       // withdrawn from. At most one entry per such pair.
     48       grants: FountainGrantWithdrawal[];
     49     }
     50 
     51   .. ts:def:: FountainGrantWithdrawal
     52 
     53     interface FountainGrantWithdrawal {
     54 
     55       // Token family to withdraw from. Must match one of the
     56       // fountain's grants.
     57       token_family_slug: string;
     58 
     59       // Desired validity time of the tokens; selects the issue
     60       // key slot. Must lie within the grant's
     61       // ``key_window_size``. Defaults to "now".
     62       valid_at?: Timestamp;
     63 
     64       // Blinded envelopes to sign with the selected slot's issue
     65       // key, as in the pay protocol. The number of envelopes is
     66       // counted against the grant's ``tokens_per_period_limit``
     67       // for that slot.
     68       envelopes: TokenEnvelope[];
     69     }
     70 
     71   .. ts:def:: FountainWithdrawResponse
     72 
     73     interface FountainWithdrawResponse {
     74 
     75       // One entry per entry in the request's ``grants`` array,
     76       // in the same order.
     77       grants: FountainGrantWithdrawalResult[];
     78     }
     79 
     80   .. ts:def:: FountainGrantWithdrawalResult
     81 
     82     interface FountainGrantWithdrawalResult {
     83 
     84       // Token family these signatures belong to.
     85       token_family_slug: string;
     86 
     87       // Hash of the issue public key that was used, so the
     88       // wallet can associate the tokens with the right slot.
     89       h_issue: HashCode;
     90 
     91       // Blind signatures, in the same order as the ``envelopes``
     92       // of the request entry, as in the pay protocol
     93       // (`TokenIssueBlindSig`).
     94       blind_sigs: TokenIssueBlindSig[];
     95     }