taler-docs

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

post-melt.rst (10177B)


      1 .. http:post:: /melt
      2 
      3   "Melts" a coin.  Invalidates the coins and prepares for exchanging of fresh
      4   coins.  Taler uses a global parameter ``kappa`` for the cut-and-choose
      5   component of the protocol, for which this request is the commitment.  Thus,
      6   various arguments are given ``kappa``-times in this step.  At present ``kappa``
      7   is always 3.
      8 
      9   This endpoint was introduced in this form in protocol **v32**.
     10 
     11   Since protocol **v45**, the commitment
     12   :ref:`TALER_RefreshCommitmentP <TALER_RefreshCommitmentP>` over which
     13   ``confirm_sig`` is made includes the ``transfer_pubs``.  For
     14   compatibility with older clients, the exchange also accepts a
     15   ``confirm_sig`` over the commitment without them.
     16 
     17   :http:statuscode:`200 OK`:
     18     The request was successful.  The response body is `MeltResponse` in this case.
     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.
     22     Possible error codes include ``TALER_EC_GENERIC_PARAMETER_MALFORMED``,
     23     ``TALER_EC_EXCHANGE_GENERIC_CIPHER_MISMATCH``,
     24     ``TALER_EC_EXCHANGE_MELT_COIN_EXPIRED_NO_ZOMBIE``,
     25     ``TALER_EC_EXCHANGE_MELT_FEES_EXCEED_CONTRIBUTION``,
     26     ``TALER_EC_EXCHANGE_REFRESHES_REVEAL_AGE_RESTRICTION_COMMITMENT_INVALID``, or
     27     ``TALER_EC_EXCHANGE_REFRESHES_REVEAL_COST_CALCULATION_OVERFLOW``.
     28     A Clause-Schnorr envelope whose ``cs_nonce`` is not the one derived
     29     from ``blinding_seed`` is refused with
     30     ``TALER_EC_GENERIC_PARAMETER_MALFORMED`` (since **v46**).
     31   :http:statuscode:`403 Forbidden`:
     32     One of the signatures is invalid.
     33     This response comes with a standard `ErrorDetail` response.
     34     Possible error codes include
     35     ``TALER_EC_EXCHANGE_MELT_COIN_SIGNATURE_INVALID`` or
     36     ``TALER_EC_EXCHANGE_DENOMINATION_SIGNATURE_INVALID``.
     37   :http:statuscode:`404 Not found`:
     38     The exchange does not recognize the denomination key as belonging to the exchange,
     39     or the coin is unknown.
     40     If the denomination key is unknown, the response will be
     41     a `DenominationUnknownMessage`.
     42     Possible error codes include
     43     ``TALER_EC_EXCHANGE_GENERIC_DENOMINATION_KEY_UNKNOWN`` or
     44     ``TALER_EC_EXCHANGE_GENERIC_COIN_UNKNOWN``.
     45   :http:statuscode:`409 Conflict`:
     46     The operation is not allowed as the coin has insufficient
     47     residual value, or because the same public key of the coin has been
     48     previously used with a different denomination or a different age
     49     commitment.  Which case it is can be decided by looking at the error
     50     code: ``TALER_EC_EXCHANGE_GENERIC_INSUFFICIENT_FUNDS`` (response is a
     51     `MeltForbiddenResponse`),
     52     ``TALER_EC_EXCHANGE_GENERIC_COIN_CONFLICTING_DENOMINATION_KEY``
     53     (response is a `CoinDenominationConflictError`) or
     54     ``TALER_EC_EXCHANGE_GENERIC_COIN_CONFLICTING_AGE_HASH``
     55     (response is a `CoinAgeCommitmentConflictError`).
     56   :http:statuscode:`410 Gone`:
     57     The requested denomination key is no longer valid.
     58     It is past the expiration or was revoked. The response is a
     59     `DenominationGoneMessage`. Clients must evaluate
     60     the error code provided to understand which of the
     61     cases this is and handle it accordingly.
     62     Possible error codes include
     63     ``TALER_EC_EXCHANGE_GENERIC_DENOMINATION_EXPIRED`` or
     64     ``TALER_EC_EXCHANGE_GENERIC_DENOMINATION_REVOKED``.
     65   :http:statuscode:`412 Precondition Failed`:
     66     The requested denomination key is not yet valid.
     67     It is before the validity start time. The response is a
     68     `DenominationGoneMessage` with
     69     ``TALER_EC_EXCHANGE_GENERIC_DENOMINATION_VALIDITY_IN_FUTURE``.
     70   :http:statuscode:`500 Internal Server Error`:
     71     The server experienced an internal error.
     72     This response comes with a standard `ErrorDetail` response.
     73     Possible error codes include
     74     ``TALER_EC_GENERIC_DB_FETCH_FAILED``,
     75     ``TALER_EC_GENERIC_DB_INVARIANT_FAILURE``,
     76     ``TALER_EC_GENERIC_DB_COMMIT_FAILED``,
     77     ``TALER_EC_GENERIC_DB_START_FAILED``,
     78     ``TALER_EC_GENERIC_INTERNAL_INVARIANT_FAILURE``, or
     79     ``TALER_EC_EXCHANGE_REFRESHES_REVEAL_COST_CALCULATION_OVERFLOW``.
     80   :http:statuscode:`503 Service Unavailable`:
     81     The exchange currently has no signing keys available.
     82     This response comes with a standard `ErrorDetail` response with
     83     a code of ``TALER_EC_EXCHANGE_GENERIC_KEYS_MISSING``.
     84 
     85   **Details:**
     86 
     87   .. ts:def:: MeltRequest
     88 
     89     interface MeltRequest {
     90        // The old coin's public key
     91        old_coin_pub: CoinPublicKey;
     92 
     93        // Hash of the denomination public key of the old coin,
     94        // to determine total coin value.
     95        old_denom_pub_h: HashCode;
     96 
     97        // The hash of the age-commitment for the old coin. Only present
     98        // if the denomination has support for age restriction.
     99        old_age_commitment_h?: AgeCommitmentHash;
    100 
    101        // Signature over the old `coin public key <eddsa-coin-pub>` by the denomination.
    102        old_denom_sig: DenominationSignature;
    103 
    104        // Amount of the value of the old coin that should be melted as part of
    105        // this refresh operation, including melting fee.  I.e.:
    106        //        melting fee of the old coin
    107        //      + sum over all values of fresh coins
    108        //      + sum over all withdraw fees for the fresh coins
    109        value_with_fee: Amount;
    110 
    111        // @since v27
    112        // @deprecated **v32**
    113        // Seed from which the nonces for the n*κ coin candidates are derived from.
    114        //
    115        // @since **v32**
    116        // The ``refresh_seed`` is an opaque value to the exchange.
    117        // It is provided by the client and is verified with the ``confirm_sig`` below.
    118        // Its purpose is to ensure that the honest owner of the old coin
    119        // can replay a /melt request from data in the coin history,
    120        // provided by the exchange and including this value, in case a wallet
    121        // was restored into a state prior to the refresh operation.
    122        //
    123        // The honest owner of the old coin SHOULD use this value
    124        // and the old coin's private key to derive kappa many
    125        // 64-byte batch seeds (one for each cut-and-choose candidate)
    126        // like this, where ``HKDF(length, salt, key_material, context)``
    127        // is the HKDF of GNUnet (HMAC-SHA512 for the extraction,
    128        // HMAC-SHA256 for the expansion):
    129        //
    130        //   ``bs[] = HKDF(kappa*64,``
    131        //               ``"refresh-batch-seeds",``
    132        //               ``refresh_seed,``
    133        //               ``old_coin_priv)``
    134        //
    135        // These batch seeds (however constructed) are relevant in the
    136        // subsequent reveal step of the cut-and-choose.  Each of the
    137        // revealed seeds is expanded to a batch of ``n`` transfer private keys
    138        // (32-byte ECDHE private keys) via HKDF without context:
    139        //
    140        //   ``tp[k][] = HKDF(n*32,``
    141        //                  ``"refresh-transfer-private-keys",``
    142        //                  ``bs[k])``
    143        //
    144        // An individual coin's transfer private key at kappa-index k and
    145        // coin index i in the batch is then ``tp[k][i]``.  The corresponding
    146        // transfer _public_ keys are given in the field ``transfer_pubs``.
    147        refresh_seed: HashCode;
    148 
    149        // Master seed for the Clause-Schnorr R-value
    150        // creation. Must match the /blinding-prepare request.
    151        // Must not have been used in any prior melt request.
    152        // Must be present if one of the fresh coin's
    153        // denominations is of type Clause-Schnorr.
    154        // The ``cs_nonce`` of every Clause-Schnorr envelope in ``coin_evs``
    155        // must be derived from it, see `CSCoinEnvelope`.
    156        blinding_seed?: BlindingMasterSeed;
    157 
    158        // Array of ``n`` new hash codes of denomination public keys
    159        // for the new coins to order.
    160        denoms_h: HashCode[];
    161 
    162        // ``kappa`` arrays of ``n`` entries for blinded coin candidates,
    163        // each matching the respective entries in ``denoms_h``.
    164        coin_evs: CoinEnvelope[kappa][];
    165 
    166        // @since **v32**
    167        // ``kappa`` arrays of ``n`` entries of transfer public keys each.
    168        // These are ephemeral ECDHE keys that allow the owner of a coin
    169        // to (re-)obtain the derived coins from a refresh operation, f.e. should
    170        // the wallet state be restored from a backup, prior to the refresh operation.
    171        // The exchange keeps the ``n`` keys of the batch at ``noreveal_index``
    172        // and returns them in the coin history of the old coin, see
    173        // `CoinMeltTransaction`.
    174        transfer_pubs: EddsaPublicKey[kappa][];
    175 
    176        // Signature by the `coin <coin-priv>` over `TALER_RefreshMeltCoinAffirmationPS`.
    177        confirm_sig: EddsaSignature;
    178 
    179     }
    180 
    181   For details about the HKDF used to derive the new coin private keys and
    182   the blinding factors from ECDHE between the transfer public keys and
    183   the private key of the melted coin, please refer to the
    184   implementation in ``libtalerutil``.
    185 
    186   .. ts:def:: MeltResponse
    187 
    188     interface MeltResponse {
    189       // Which of the ``kappa`` indices does the client not have to reveal
    190       // by calling the ``/reveal-melt`` endpoint.
    191       noreveal_index: Integer;
    192 
    193       // Signature of `TALER_RefreshMeltConfirmationPS` whereby the exchange
    194       // affirms the successful melt and confirming the ``noreveal_index``.
    195       exchange_sig: EddsaSignature;
    196 
    197       // `Public EdDSA key <sign-key-pub>` of the exchange that was used to generate the signature.
    198       // Should match one of the exchange's signing keys from ``/keys``.  Again given
    199       // explicitly as the client might otherwise be confused by clock skew as to
    200       // which signing key was used.
    201       exchange_pub: EddsaPublicKey;
    202 
    203     }
    204 
    205   .. ts:def:: MeltForbiddenResponse
    206 
    207     interface MeltForbiddenResponse {
    208 
    209       // Must be TALER_EC_EXCHANGE_GENERIC_INSUFFICIENT_FUNDS.
    210       // (Since **v42**, a conflicting denomination is
    211       // reported with a `CoinDenominationConflictError` instead.)
    212       code: Integer;
    213 
    214       // A string explaining that the user tried to
    215       // double-spend.
    216       hint: string;
    217 
    218       // EdDSA public key of a coin being double-spent.
    219       coin_pub: EddsaPublicKey;
    220 
    221       // Hash of the public key of the denomination of the coin.
    222       h_denom_pub: HashCode;
    223 
    224     }