taler-docs

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

get-fountain-info.rst (2292B)

      1 .. http:get:: [/instances/$INSTANCE]/fountain/info
      2 
      3   Used by wallets to learn which token families they can withdraw
      4   from and to obtain the token family metadata and issue public
      5   keys needed to prepare blinded envelopes. Wallets re-poll this
      6   endpoint at the advertised ``poll_freq`` to learn about changed
      7   promotional grants.
      8   This endpoint is available since protocol **vTokenFountains**.
      9 
     10   The fountain secret authenticates the request via the
     11   ``Authorization: Bearer $FOUNTAIN_SECRET`` header; it is
     12   deliberately never placed in the URL to keep it out of server
     13   logs and proxies.
     14 
     15   **Response:**
     16 
     17   :http:statuscode:`200 OK`:
     18     The backend has successfully returned the fountain information.
     19     Returns a `FountainInfoResponse`.
     20   :http:statuscode:`401 Unauthorized`:
     21     The fountain secret is unknown. This includes deleted
     22     fountains: the wallet should report the access as revoked.
     23   :http:statuscode:`404 Not found`:
     24     A token family disappeared during issue-key resolution, returned with
     25     ``TALER_EC_MERCHANT_PRIVATE_POST_ORDERS_TOKEN_FAMILY_SLUG_UNKNOWN``.
     26   :http:statuscode:`500 Internal Server Error`:
     27     The server experienced an internal failure.
     28 
     29   **Details:**
     30 
     31   .. ts:def:: FountainInfoResponse
     32 
     33     interface FountainInfoResponse {
     34 
     35       // How often the wallet should re-poll this endpoint.
     36       poll_freq: RelativeTime;
     37 
     38       // Grants of this fountain, with the token family metadata
     39       // and issue keys needed to prepare blinded envelopes.
     40       // May be empty; this does not revoke the credential.
     41       grants: FountainWalletGrant[];
     42     }
     43 
     44   .. ts:def:: FountainWalletGrant
     45 
     46     interface FountainWalletGrant {
     47 
     48       // Slug of the token family.
     49       token_family_slug: Slug;
     50 
     51       // Maximum withdrawals per key validity period.
     52       tokens_per_period_limit: Integer;
     53 
     54       // Suggested number of tokens to hold per period.
     55       tokens_per_period_stash: Integer;
     56 
     57       // Number of key slots ahead the wallet may withdraw for.
     58       // Between 0 and 12 inclusive, in addition to the current slot.
     59       key_window_size: Integer;
     60 
     61       // Token family metadata including the currently valid
     62       // (and, within ``key_window_size``, upcoming) issue
     63       // public keys.
     64       token_family: ContractTokenFamily;
     65     }