taler-docs

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

post-reveal-melt.rst (3659B)


      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 :http:post:`/melt </melt>` step.
      5 
      6   The request body is a `RevealMeltRequest`.
      7 
      8   This endpoint was introduced in this form in protocol **v32**.
      9 
     10   :http:statuscode:`200 OK`:
     11     The coin's' secret material matched the commitment and the original request was well-formed.
     12     The response body is a `RevealResponse`.
     13   :http:statuscode:`400 Bad Request`:
     14     The request body is malformed or a parameter is invalid.
     15     This response comes with a standard `ErrorDetail` response with
     16     codes of:
     17 
     18     - ``TALER_EC_GENERIC_PARAMETER_MALFORMED``
     19     - ``TALER_EC_EXCHANGE_REFRESHES_REVEAL_AGE_RESTRICTION_COMMITMENT_INVALID``
     20     - ``TALER_EC_EXCHANGE_REFRESHES_REVEAL_INVALID_RCH``, if the revealed
     21       secrets do not match the commitment of the original melt request
     22 
     23   :http:statuscode:`403 Forbidden`:
     24     A signature is invalid. Returned with a
     25     ``TALER_EC_EXCHANGE_REFRESHES_REVEAL_LINK_SIGNATURE_INVALID``.
     26     This response comes with a standard `ErrorDetail` response.
     27   :http:statuscode:`404 Not found`:
     28     The provided commitment is unknown. Returned with an error code of
     29     ``TALER_EC_EXCHANGE_REFRESHES_REVEAL_SESSION_UNKNOWN``.
     30   :http:statuscode:`413 Request entity too large`:
     31     The uploaded body is to long, it exceeds the size limit.
     32     Returned with an error code of
     33     ``TALER_EC_GENERIC_UPLOAD_EXCEEDS_LIMIT``.
     34   :http:statuscode:`500 Internal server error`:
     35     The server had an internal problem handling the request.
     36     Error codes include:
     37     - ``TALER_EC_GENERIC_INTERNAL_INVARIANT_FAILURE``
     38     - ``TALER_EC_GENERIC_DB_STORE_FAILED``
     39     - ``TALER_EC_GENERIC_DB_FETCH_FAILED``
     40   :http:statuscode:`503 Service Unavailable`:
     41     Returned with an error code of
     42     ``TALER_EC_EXCHANGE_GENERIC_KEYS_MISSING``.
     43 
     44   **Details:**
     45 
     46   Request body for a ``reveal-melt`` request
     47   contains a JSON object with the following fields:
     48 
     49   .. ts:def:: RevealMeltRequest
     50 
     51     interface RevealMeltRequest {
     52       // The refresh commitment from the ``/melt/`` step,
     53       // see `TALER_RefreshCommitmentP`.
     54       rc: HashCode;
     55 
     56       // @since v27
     57       // @deprecated **v32**
     58       // The disclosed kappa-1 signatures by the old coin's private key,
     59       // over Hash1a("Refresh", Cp, r, i), where Cp is the melted coin's public key,
     60       // r is the public refresh nonce from the metling step and i runs over the
     61       // _disclosed_ kappa-1 indices.
     62       signatures: CoinSignature[kappa-1];
     63 
     64       // @since **v32**
     65       // The batch seeds for the transfer private keys to reveal,
     66       // as they were generated for the previous `MeltRequest`.
     67       // That is, assuming an honest client who had generated
     68       // kappa many batch seeds via HKDF like this:
     69       //
     70       //   ``bs[] = HKDF(kappa*sizeof(HashCode),``
     71       //               ``"refresh-batch-seeds",``
     72       //               ``old_coin_priv,``
     73       //               ``refresh_seed)``,
     74       //
     75       // this field contains the entries in ``bs[]`` for all the indeces
     76       // *except* the ``noreveal_index``.
     77       batch_seeds: HashCode[kappa-1];
     78 
     79       // IFF the denomination of the old coin had support for age restriction,
     80       // the client MUST provide the original age commitment, i. e. the
     81       // vector of public keys, or omitted otherwise.
     82       // The size of the vector MUST be the number of age groups configured by
     83       // the exchange for age restriction.
     84       age_commitment?: Edx25519PublicKey[];
     85 
     86     }
     87 
     88   .. ts:def:: RevealResponse
     89 
     90     type RevealResponse = WithdrawResponse;