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