post-recoup-refresh.rst (9399B)
1 .. http:post:: /recoup-refresh 2 3 Demand that coins of revoked denominations, which originated from 4 one particular call to :http:post:`/melt </melt>` and 5 :http:post:`/reveal-melt </reveal-melt>`, be paid back to the old coin 6 they were refreshed from. 7 8 All coins in one request MUST originate from the same refresh operation. 9 The client identifies that operation by the public key of the old coin and 10 the refresh commitment ``rc`` of the original melt request. As with 11 :http:post:`/recoup-withdraw </recoup-withdraw>`, the client discloses the 12 secret material of the coins to be recouped and provides the envelope 13 hashes of the other coins of the same operation, so that the exchange can 14 recompute the hash over the batch of coins it signed and compare it with 15 the commitment it stored. 16 17 The residual value of each disclosed coin is credited to the old coin. 18 The old coin may then be spent or melted again, even if the deposit 19 expiration of its denomination has passed in the meantime (a "zombie" 20 coin). The refresh fee paid in the original operation is **not** 21 recouped. 22 23 The exchange only accepts this request for coins of denominations that 24 are listed in the ``recoup`` field of :http:get:`/keys </keys>`. 25 26 This endpoint was introduced in protocol **v42** and replaces the 27 former ``/coins/$COIN_PUB/recoup-refresh`` endpoint. 28 29 **Request:** 30 31 The request body must be a `RecoupRefreshRequest` object. 32 33 **Response:** 34 35 :http:statuscode:`200 OK`: 36 The request was successful and the response is a 37 `RecoupRefreshResponse`. Repeating exactly the same request 38 yields the same response (the signature may differ if the exchange 39 has rotated its signing key in the meantime), so if the network goes 40 down before the client can commit the result to disk, the recoup is 41 not lost. 42 :http:statuscode:`400 Bad Request`: 43 The request body is malformed or a parameter is invalid. 44 This response comes with a standard `ErrorDetail` response. 45 Possible error codes include ``TALER_EC_GENERIC_PARAMETER_MALFORMED`` 46 (also used if ``coin_data`` does not contain at least one disclosed 47 coin) and ``TALER_EC_EXCHANGE_RECOUP_REFRESH_BATCH_SIZE_MISMATCH`` 48 (the number of entries in ``coin_data`` differs from the number of 49 coins the exchange signed in the original refresh operation). 50 :http:statuscode:`403 Forbidden`: 51 A signature is invalid. 52 This response comes with a standard `ErrorDetail` response. 53 Possible error codes include 54 ``TALER_EC_EXCHANGE_RECOUP_REFRESH_SIGNATURE_INVALID`` (a ``coin_sig``) 55 or ``TALER_EC_EXCHANGE_DENOMINATION_SIGNATURE_INVALID`` 56 (a ``denom_sig``). 57 :http:statuscode:`404 Not found`: 58 One of the following reasons occurred: 59 60 1. A denomination key is unknown. The response is a 61 `DenominationUnknownMessage` with error code 62 ``TALER_EC_EXCHANGE_GENERIC_DENOMINATION_KEY_UNKNOWN``. 63 2. The exchange has no record of a refresh operation for the given 64 ``rc``, or the operation found was not a refresh of 65 ``old_coin_pub``. This response comes with a standard `ErrorDetail` 66 response with error code 67 ``TALER_EC_EXCHANGE_RECOUP_REFRESH_MELT_NOT_FOUND``. 68 :http:statuscode:`409 Conflict`: 69 One of the following reasons occurred: 70 71 1. The hash the exchange recomputed over the ``coin_data`` array does 72 not match the commitment of the refresh operation, so at least one 73 disclosed coin was not part of it. This response comes with a 74 standard `ErrorDetail` response with error code 75 ``TALER_EC_EXCHANGE_RECOUP_REFRESH_COMMITMENT_MISMATCH``. 76 2. The denomination of a disclosed coin differs from the denomination 77 recorded for that position of the refresh operation. This 78 response comes with a standard `ErrorDetail` response with error code 79 ``TALER_EC_EXCHANGE_RECOUP_REFRESH_DENOMINATION_MISMATCH``. 80 3. A disclosed coin has no residual value left. The response is a 81 `DepositDoubleSpendError` with error code 82 ``TALER_EC_EXCHANGE_GENERIC_INSUFFICIENT_FUNDS``. 83 4. The same coin public key was previously used with a different 84 denomination or age commitment. The response is a 85 `CoinDenominationConflictError` with error code 86 ``TALER_EC_EXCHANGE_GENERIC_COIN_CONFLICTING_DENOMINATION_KEY`` 87 or a `CoinAgeCommitmentConflictError` with error code 88 ``TALER_EC_EXCHANGE_GENERIC_COIN_CONFLICTING_AGE_HASH``. 89 90 In all of these cases nothing is credited, not even for the other 91 coins in the request. 92 :http:statuscode:`410 Gone`: 93 The denomination of a disclosed coin is not eligible for recoup. 94 The response is a `DenominationGoneMessage` with error code 95 ``TALER_EC_EXCHANGE_GENERIC_DENOMINATION_EXPIRED`` (past the deposit 96 expiration) or ``TALER_EC_EXCHANGE_RECOUP_REFRESH_NOT_ELIGIBLE`` (the 97 denomination was not revoked). 98 :http:statuscode:`412 Precondition Failed`: 99 The denomination of a disclosed coin is not yet valid. 100 The response is a `DenominationGoneMessage` with error code 101 ``TALER_EC_EXCHANGE_GENERIC_DENOMINATION_VALIDITY_IN_FUTURE``. 102 :http:statuscode:`413 Request entity too large`: 103 The uploaded body is to long, it exceeds the size limit. 104 Returned with an error code of 105 ``TALER_EC_GENERIC_UPLOAD_EXCEEDS_LIMIT``. 106 :http:statuscode:`500 Internal Server Error`: 107 The exchange encountered an internal error. 108 This response comes with a standard `ErrorDetail` response. 109 Possible error codes include 110 ``TALER_EC_EXCHANGE_RECOUP_REFRESH_BLINDING_FAILED``, 111 ``TALER_EC_GENERIC_DB_FETCH_FAILED``, 112 ``TALER_EC_GENERIC_DB_COMMIT_FAILED``, or 113 ``TALER_EC_GENERIC_DB_INVARIANT_FAILURE``. 114 :http:statuscode:`502 Bad gateway`: 115 The exchange could not reach its signing helper to create 116 the confirmation signatures. Returned with an error code of 117 ``TALER_EC_EXCHANGE_SIGNKEY_HELPER_UNAVAILABLE``. 118 Wallets should retry the request (with some delay) at a later time. 119 :http:statuscode:`503 Service Unavailable`: 120 The exchange currently has no signing keys available. 121 This response comes with a standard `ErrorDetail` response with 122 a code of ``TALER_EC_EXCHANGE_GENERIC_KEYS_MISSING``. 123 124 **Details:** 125 126 .. ts:def:: RecoupRefreshRequest 127 128 interface RecoupRefreshRequest { 129 // Public key of the old coin that was melted. 130 // The recouped value is credited to this coin. 131 old_coin_pub: CoinPublicKey; 132 133 // The refresh commitment of the original melt request, 134 // see `TALER_RefreshCommitmentP`. This identifies the 135 // refresh operation. 136 rc: HashCode; 137 138 // Exactly one entry per coin the exchange signed in the 139 // refresh operation, that is the ``n`` coins of the batch at 140 // the ``noreveal_index`` returned in the `MeltResponse`, in the 141 // order of the original request. 142 // At least one entry MUST be a `RecoupedCoin` and its 143 // ``coin_sig`` MUST be created with purpose 144 // ``TALER_SIGNATURE_WALLET_COIN_RECOUP_REFRESH``. 145 coin_data: RecoupCoinData[]; 146 } 147 148 Note that for denominations of cipher type Clause-Schnorr the client 149 does not need to provide the session nonce or the R-value pair: the 150 exchange derives the nonce from the ``blinding_seed`` of the original 151 melt request and the coin's position in ``coin_data`` (exactly as the 152 wallet does for a melt), and it stored the R-values it returned in 153 :http:post:`/blinding-prepare </blinding-prepare>`. 154 155 The exchange processes the request as 156 :http:post:`/recoup-withdraw </recoup-withdraw>` does, with the refresh 157 operation looked up under ``rc``, the hash over ``coin_data`` compared 158 against the hash of the batch at the ``noreveal_index``, and the 159 residual value of every disclosed coin credited to ``old_coin_pub`` 160 in one database transaction. 161 162 .. ts:def:: RecoupRefreshResponse 163 164 interface RecoupRefreshResponse { 165 // Public key of the old coin that was credited. 166 old_coin_pub: CoinPublicKey; 167 168 // The refresh commitment of the refresh operation, as in the request. 169 rc: HashCode; 170 171 // Time when the exchange accepted the recoup. All coins 172 // of one request share this timestamp. 173 timestamp: Timestamp; 174 175 // Total amount credited to the old coin, that is the sum 176 // of the ``amount`` values in ``recoups``. 177 total_amount: Amount; 178 179 // One entry per `RecoupedCoin` in the request, in the same order. 180 recoups: RecoupedCoinResult[]; 181 182 // Signature over `TALER_RecoupRefreshBatchConfirmationPS` with 183 // purpose ``TALER_SIGNATURE_EXCHANGE_CONFIRM_RECOUP_REFRESH_BATCH``, 184 // affirming the recoup of all coins in ``recoups``. 185 exchange_sig: EddsaSignature; 186 187 // Public key used to create ``exchange_sig``. 188 // Should match one of the exchange's signing keys from ``/keys``. 189 exchange_pub: EddsaPublicKey; 190 } 191 192 The coin histories report each recouped coin individually, see 193 `CoinRecoupRefreshTransaction` for the recouped coin and 194 `CoinRecoupRefreshReceiverTransaction` for the old coin. Those entries 195 carry a signature per coin over :ref:`TALER_RecoupRefreshConfirmationPS <TALER_RecoupRefreshConfirmationPS>`, 196 which the exchange creates when a history is requested; the batch 197 signature above is only part of the response to this request.