taler-docs

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

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.