taler-docs

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

post-reveal-melt.rst (4368B)

      1 .. http:post:: /reveal-melt
      2 
      3   Reveal previously committed values to the exchange, except for the values
      4   corresponding to the ``noreveal_index`` returned by the ``/melt`` step.
      5 
      6   The base URL for ``/reveal-melt``-request may differ from the main base URL of
      7   the exchange. Clients SHOULD respect the ``reveal_base_url`` returned for the
      8   coin during melt operations. The exchange MUST return a
      9   307 or 308 redirection to the correct base URL if the client failed to
     10   respect the ``reveal_base_url`` or if the allocation has changed.
     11 
     12   The request body is a `RevealMeltRequest`.
     13 
     14   This endpoint was introduced in this form in protocol **v32**.
     15 
     16   :http:statuscode:`200 OK`:
     17     The coin's' secret material matched the commitment and the original request was well-formed.
     18     The response body is a `RevealResponse`.
     19   :http:statuscode:`400 Bad Request`:
     20     The request body is malformed or a parameter is invalid.
     21     This response comes with a standard `ErrorDetail` response with
     22     codes of:
     23     - ``TALER_EC_GENERIC_PARAMETER_MALFORMED``
     24     - ``TALER_EC_EXCHANGE_REFRESHES_REVEAL_AGE_RESTRICTION_COMMITMENT_INVALID``
     25     - ``TALER_EC_EXCHANGE_REFRESHES_REVEAL_INVALID_RCH``
     26   :http:statuscode:`403 Forbidden`:
     27     A signature is invalid. Returned with a
     28     ``TALER_EC_EXCHANGE_REFRESHES_REVEAL_LINK_SIGNATURE_INVALID``.
     29     This response comes with a standard `ErrorDetail` response.
     30   :http:statuscode:`404 Not found`:
     31     The provided commitment is unknown. Returned with an error code of
     32     ``TALER_EC_EXCHANGE_REFRESHES_REVEAL_SESSION_UNKNOWN``.
     33   :http:statuscode:`409 Conflict`:
     34     There is a problem between the original commitment and the revealed secret data.
     35     The returned information is proof of the mismatch,
     36     and therefore rather verbose, as it includes most of the original /melt request,
     37     but of course expected to be primarily used for diagnostics.
     38 
     39     Returned with a code of
     40     ``TALER_EC_EXCHANGE_REFRESHES_REVEAL_INVALID_RCH``.
     41   :http:statuscode:`413 Request entity too large`:
     42     The uploaded body is to long, it exceeds the size limit.
     43     Returned with an error code of
     44     ``TALER_EC_GENERIC_UPLOAD_EXCEEDS_LIMIT``.
     45   :http:statuscode:`500 Internal server error`:
     46     The server had an internal problem handling the request.
     47     Error codes include:
     48     - ``TALER_EC_GENERIC_INTERNAL_INVARIANT_FAILURE``
     49     - ``TALER_EC_GENERIC_DB_STORE_FAILED``
     50     - ``TALER_EC_GENERIC_DB_FETCH_FAILED``
     51   :http:statuscode:`503 Service unvailable`:
     52     Returned with an error code of
     53     ``TALER_EC_EXCHANGE_GENERIC_KEYS_MISSING``.
     54 
     55   **Details:**
     56 
     57   Request body for a ``reveal-melt`` request
     58   contains a JSON object with the following fields:
     59 
     60   .. ts:def:: RevealMeltRequest
     61 
     62     interface RevealMeltRequest {
     63       // The refresh commitment from the ``/melt/`` step,
     64       // see `TALER_RefreshCommitmentP`.
     65       rc: HashCode;
     66 
     67       // @since v27
     68       // @deprecated **v32**
     69       // The disclosed kappa-1 signatures by the old coin's private key,
     70       // over Hash1a("Refresh", Cp, r, i), where Cp is the melted coin's public key,
     71       // r is the public refresh nonce from the metling step and i runs over the
     72       // _disclosed_ kappa-1 indices.
     73       signatures: CoinSignature[kappa-1];
     74 
     75       // @since **v32**
     76       // The batch seeds for the transfer private keys to reveal,
     77       // as they were generated for the previous `MeltRequest`.
     78       // That is, assuming an honest client who had generated
     79       // kappa many batch seeds via HKDF like this:
     80       //
     81       //   ``bs[] = HKDF(kappa*sizeof(HashCode),``
     82       //               ``"refresh-batch-seeds",``
     83       //               ``old_coin_priv,``
     84       //               ``refresh_seed)``,
     85       //
     86       // this field contains the entries in ``bs[]`` for all the indeces
     87       // *except* the ``noreveal_index``.
     88       batch_seeds: HashCode[kappa-1];
     89 
     90       // IFF the denomination of the old coin had support for age restriction,
     91       // the client MUST provide the original age commitment, i. e. the
     92       // vector of public keys, or omitted otherwise.
     93       // The size of the vector MUST be the number of age groups as defined by the
     94       // Exchange in the field ``.age_groups`` of the extension ``age_restriction``.
     95       age_commitment?: Edx25519PublicKey[];
     96 
     97     }
     98 
     99   .. ts:def:: RevealResponse
    100 
    101     type RevealResponse = WithdrawResponse;