diff options
-rw-r--r-- | api-exchange.rst | 50 |
1 files changed, 49 insertions, 1 deletions
diff --git a/api-exchange.rst b/api-exchange.rst index c764b6b7..9a3111a1 100644 --- a/api-exchange.rst +++ b/api-exchange.rst @@ -649,7 +649,7 @@ denomination. .. code-block:: tsref interface CoinSpendHistoryItem { - // Either "DEPOSIT", "MELT", "REFUND" or "PAYBACK" + // Either "DEPOSIT", "MELT", "REFUND" or "PAYBACK", "REFRESH_PAYBACK" type: string; // The total amount of the coin's value absorbed (or restored in the case of a refund) by this transaction. @@ -681,6 +681,7 @@ denomination. melt_fee: Amount; // Commitment from the melt operation. + // Present if `type` is "MELT" or "REFRESH_PAYBACK" rc: TALER_RefreshCommitmentP; // Hash of the bank account from where we received the funds. @@ -711,6 +712,14 @@ denomination. // public key used to sign `exchange_sig`, only present if `exchange_sig` present. exchange_pub?: EddsaPublicKey; + + // Blinding factor of the revoked new coin, + // only present if `type` is "REFRESH_PAYBACK". + new_coin_blinding_secret: RsaBlindingKeySecret; + + // Blinded public key of the revoked new coin, + // only present if `type` is "REFRESH_PAYBACK". + new_coin_ev: RsaBlindingKeySecret; } ---------- @@ -913,6 +922,45 @@ the API during normal operation. } +.. http:post:: /refresh/payback + + When a fresh coin that was obtained via refresh is revoked, the refresh payback can be used + to revert the refresh and credit the old coin with the refreshed coin's value. + + :status 200 OK: + The old coin was successfully credited with the value of the revoked new coin. + :status 404 Not Found: + Either the refresh commitment has not been seen by the exchange before, + the old coin was not found among the refreshed coins, + or the blinded new coin's public key has not been seen and signed before + by the exchange. + :status 401 Unauthorized: + The blinding secret does not match the signature stored by the exchange + the new_coin_ev. + + **Details:** + + Request body contains a JSON object with the following fields: + + .. code-block:: tsref + + interface RefreshPaybackRequest { + // Public key of the old coin that should receive the + // refund for the refreshed coin. + old_coin_pub: RsaPublicKey; + + // Blinded public key of the coin of the revoked denomination. + new_coin_ev: CoinEnvelope; + + // Secret blinding factor of the new coin + new_coin_blinding_secret: RsaBlindingKeySecret; + + // Commitment that identifies the refresh operation. + // Redundant, but speeds up the exchange's database lookup. + rc: HashCode; + } + + .. http:get:: /refresh/link Link the old public key of a melted coin to the coin(s) that were exchangeed during the refresh operation. |