commit 026d654b6cd70278d8b9752177faca811b09207a
parent 18d2d85c0ed4a7479709da571b08c36fcb23661d
Author: Özgür Kesim <oec-taler@kesim.org>
Date: Wed, 10 Dec 2025 19:40:55 +0100
[exchange] clearifications and marking out WIP for recoup operations
Diffstat:
| M | core/api-exchange.rst | | | 110 | ++++++++++++++++++++++++++++++++++++++++++++++++++++--------------------------- |
1 file changed, 72 insertions(+), 38 deletions(-)
diff --git a/core/api-exchange.rst b/core/api-exchange.rst
@@ -1992,8 +1992,8 @@ exchange.
------------------
-
.. _reveal-withdraw:
+
**Reveal-Withdraw**
This endpoint is called by the client after a call to `withdraw`_,
@@ -2985,9 +2985,12 @@ became minted, and proof ownership of the coin itself.
.. ts:def:: RecoupRefreshConfirmation
interface RecoupRefreshConfirmation {
- // TODO[oec]: What is needed here?
// Public key of the old coin that will receive the recoup.
old_coin_pub: EddsaPublicKey;
+
+ // The new balance of the old coin, after it has absorved
+ // the residual values of the coins from the request.
+ balance: Amount;
}
@@ -3480,9 +3483,9 @@ The GET request should come with the following HTTP headers:
| CoinDepositTransaction
| CoinMeltTransaction
| CoinRefundTransaction
- | CoinRecoupTransaction
- | CoinOldCoinRecoupTransaction
+ | CoinRecoupWithdrawTransaction
| CoinRecoupRefreshTransaction
+ | CoinRecoupRefreshReceiverTransaction
| CoinPurseDepositTransaction
| CoinPurseRefundTransaction
| CoinReserveOpenDepositTransaction;
@@ -3656,10 +3659,19 @@ The GET request should come with the following HTTP headers:
}
-.. ts:def:: CoinRecoupTransaction
- interface CoinRecoupTransaction {
- type: "RECOUP";
+.. note::
+
+ The `CoinRecoupWithdrawTransaction` interface defintion is WIP.
+ It will be fully specified and implemented with **vRECOUP**.
+
+.. ts:def:: CoinRecoupWithdrawTransaction
+
+ // This represents a transaction of a call to /recoup-withdraw
+ // where the coin's residual value has been credited to the
+ // original reserve, from which this coin was withdrawn.
+ interface CoinRecoupWithdrawTransaction {
+ type: "RECOUP-WITHDRAW";
// Offset of this entry in the reserve history.
// Useful to request incremental histories via
@@ -3709,37 +3721,18 @@ The GET request should come with the following HTTP headers:
}
-.. ts:def:: CoinOldCoinRecoupTransaction
-
- interface CoinOldCoinRecoupTransaction {
- type: "OLD-COIN-RECOUP";
- // Offset of this entry in the reserve history.
- // Useful to request incremental histories via
- // the "start" query parameter.
- history_offset: Integer;
-
- // The total amount of the coin's value restored
- // by this transaction.
- // The current coin value can thus be computed by
- // adding the amount to the coin's denomination value.
- amount: Amount;
-
- // Date when the operation was made.
- timestamp: Timestamp;
-
- // Signature by the exchange over a
- // `TALER_RecoupRefreshConfirmationPS`
- // of purpose ``TALER_SIGNATURE_EXCHANGE_CONFIRM_RECOUP_REFRESH``.
- exchange_sig: EddsaSignature;
-
- // Public key of the private key used to create 'exchange_sig'.
- exchange_pub: EddsaPublicKey;
+.. note::
- }
+ The `CoinRecoupRefreshTransaction` interface defintion is WIP.
+ It will be fully specified and implemented with **vRECOUP**.
.. ts:def:: CoinRecoupRefreshTransaction
+ // This represents a transaction of a call to /recoup-refresh
+ // where this coin was _part_ of the batch of coins whose
+ // residual values were credited to the original coin, from
+ // which also this coin was refresh from.
interface CoinRecoupRefreshTransaction {
type: "RECOUP-REFRESH";
@@ -3763,7 +3756,10 @@ The GET request should come with the following HTTP headers:
// Public key used to sign 'exchange_sig'.
exchange_pub: EddsaPublicKey;
- // FIXME-#9828: implementation returns old_coin_pub here
+ // The original coin, from which this coin was derived from
+ // in a call to /refresh, and which was then credited with
+ // the residual value of this coin in a call to /recoup-refresh.
+ old_coin_pub: EddsPublicKey;
// Signature by the coin over a `TALER_RecoupRequestPS`
// with purpose ``TALER_SIGNATURE_WALLET_COIN_RECOUP``.
@@ -3774,14 +3770,14 @@ The GET request should come with the following HTTP headers:
// that is important to fix the coin's denomination.
h_denom_pub: HashCode;
- // Coin blinding key that was used in the original withdraw request.
+ // Coin blinding key that was used in the original refresh request.
coin_blind: DenominationBlindingKeyP;
- // The hash of the withdraw commitment of the original withdraw
- // request that this coin was part of
+ // The hash of the refresh commitment of the original refresh
+ // request that this coin was derived from.
h_commitment: HashCode;
- // Coin's index in the original withdraw request, starting at 0
+ // Coin's index in the original refresh request, starting at 0
coin_index: Integer;
// Blinding factor of the revoked new coin.
@@ -3795,6 +3791,44 @@ The GET request should come with the following HTTP headers:
}
+
+.. note::
+
+ The `CoinRecoupRefreshReceiverTransaction` interface defintion is WIP.
+ It will be fully specified and implemented with **vRECOUP**.
+
+.. ts:def:: CoinRecoupRefreshReceiverTransaction
+
+ // This represents a transaction of a call to /recoup-refresh
+ // where this coin was the _receiver_ of the residual values
+ // from coins, that originated from a call to /refresh of this coin.
+ interface CoinRecoupRefreshReceiverTransaction {
+ type: "RECOUP-REFRESH-RECEIVER";
+
+ // Offset of this entry in the reserve history.
+ // Useful to request incremental histories via
+ // the "start" query parameter.
+ history_offset: Integer;
+
+ // The total amount of the coin's value restored
+ // by this transaction.
+ // The current coin value can thus be computed by
+ // adding the amount to the coin's denomination value.
+ amount: Amount;
+
+ // Date when the operation was made.
+ timestamp: Timestamp;
+
+ // Signature by the exchange over a
+ // `TALER_RecoupRefreshConfirmationPS`
+ // of purpose ``TALER_SIGNATURE_EXCHANGE_CONFIRM_RECOUP_REFRESH``.
+ exchange_sig: EddsaSignature;
+
+ // Public key of the private key used to create 'exchange_sig'.
+ exchange_pub: EddsaPublicKey;
+
+ }
+
.. ts:def:: CoinPurseDepositTransaction
interface CoinPurseDepositTransaction {
