commit 66fd86c4b60a9a220b2a425ce46896f96f0573d7
parent 18405edc4344c98b8d30f182c684da2134ffec7f
Author: Özgür Kesim <oec-taler@kesim.org>
Date: Mon, 7 Apr 2025 14:27:49 +0200
[exchange] added introduction to /blinding-prepare
Diffstat:
| M | core/api-exchange.rst | | | 141 | ++++++++++++++++++++++++++++++++++++++++++------------------------------------- |
1 file changed, 75 insertions(+), 66 deletions(-)
diff --git a/core/api-exchange.rst b/core/api-exchange.rst
@@ -1471,71 +1471,17 @@ This part of the API is for the use by auditors interacting with the exchange.
}
-.. _exchange-withdrawal:
-
-----------
-Withdrawal
-----------
-
-This API is used by the wallet to obtain digital coins.
-
-When transferring money to the exchange such as via SEPA transfers, the exchange creates
-a *reserve*, which keeps the money from the customer. The customer must
-specify an EdDSA reserve public key as part of the transfer, and can then
-withdraw digital coins using the corresponding private key. All incoming and
-outgoing transactions are recorded under the corresponding public key by the
-exchange.
-
-.. note::
-
- Eventually the exchange will need to advertise a policy for how long it will
- keep transaction histories for inactive or even fully drained reserves. We
- will therefore need some additional handler similar to ``/keys`` to
- advertise those terms of service.
-
-
-.. http:get:: /reserves/$RESERVE_PUB
-
- Request summary information about a reserve.
-
- **Request:**
-
- :query timeout_ms=MILLISECONDS: *Optional.* If specified, the exchange will wait up to MILLISECONDS for incoming funds before returning a 404 if the reserve does not yet exist.
-
- **Response:**
- :http:statuscode:`200 OK`:
- The exchange responds with a `ReserveSummary` object; the reserve was known to the exchange.
- :http:statuscode:`404 Not found`:
- The reserve key does not belong to a reserve known to the exchange.
-
- **Details:**
-
- .. ts:def:: ReserveSummary
-
- interface ReserveSummary {
- // Balance left in the reserve.
- balance: Amount;
-
- // Full payto URI of the bank account that
- // (most recently) funded this reserve.
- // Useful as a hint for deposit operations for wallets.
- // Missing if this reserve was only filled via P2P merges.
- // @since protocol **v23**.
- last_origin?: string;
-
- // If set, proof of age restriction is required and age restriction needs
- // to be set for each coin to this value during the withdrawal from this reserve.
- // The client then MUST use a denomination with support for age restriction enabled
- // for the withdrawal and MUST set an appropriate value for ``max_age``
- // The value represents a valid age group from the list of permissible
- // age groups as defined by the exchange's output to /keys.
- maximum_age_group?: number;
- }
+----------------
+Blinding Prepare
+----------------
+Certain denomination cipher types, such as Clause-Schnorr, require input values
+from the exchange-side as preparation for the blinding of the coins. See the
+Bachelor thesis of Gian Demarmels and Lucien Heuzeveldt,
+`Adding Schnorr’s Blind Signature in Taler <https://www.taler.net/papers/cs-thesis.pdf>`_,
+for details.
-Blinding Prepare
-~~~~~~~~~~~~~~~~
.. note:: This endpoint is available since v26 of the API and is a substitute
for ``/csr-withdraw`` and ``/csr-melt``.
@@ -1637,6 +1583,69 @@ Blinding Prepare
+.. _exchange-withdrawal:
+
+----------
+Withdrawal
+----------
+
+This API is used by the wallet to obtain digital coins.
+
+When transferring money to the exchange such as via SEPA transfers, the exchange creates
+a *reserve*, which keeps the money from the customer. The customer must
+specify an EdDSA reserve public key as part of the transfer, and can then
+withdraw digital coins using the corresponding private key. All incoming and
+outgoing transactions are recorded under the corresponding public key by the
+exchange.
+
+.. note::
+
+ Eventually the exchange will need to advertise a policy for how long it will
+ keep transaction histories for inactive or even fully drained reserves. We
+ will therefore need some additional handler similar to ``/keys`` to
+ advertise those terms of service.
+
+
+.. http:get:: /reserves/$RESERVE_PUB
+
+ Request summary information about a reserve.
+
+ **Request:**
+
+ :query timeout_ms=MILLISECONDS: *Optional.* If specified, the exchange will wait up to MILLISECONDS for incoming funds before returning a 404 if the reserve does not yet exist.
+
+ **Response:**
+
+ :http:statuscode:`200 OK`:
+ The exchange responds with a `ReserveSummary` object; the reserve was known to the exchange.
+ :http:statuscode:`404 Not found`:
+ The reserve key does not belong to a reserve known to the exchange.
+
+ **Details:**
+
+ .. ts:def:: ReserveSummary
+
+ interface ReserveSummary {
+ // Balance left in the reserve.
+ balance: Amount;
+
+ // Full payto URI of the bank account that
+ // (most recently) funded this reserve.
+ // Useful as a hint for deposit operations for wallets.
+ // Missing if this reserve was only filled via P2P merges.
+ // @since protocol **v23**.
+ last_origin?: string;
+
+ // If set, proof of age restriction is required and age restriction needs
+ // to be set for each coin to this value during the withdrawal from this reserve.
+ // The client then MUST use a denomination with support for age restriction enabled
+ // for the withdrawal and MUST set an appropriate value for ``max_age``
+ // The value represents a valid age group from the list of permissible
+ // age groups as defined by the exchange's output to /keys.
+ maximum_age_group?: number;
+ }
+
+
CSR-Withdraw
~~~~~~~~~~~~
@@ -2149,7 +2158,7 @@ These endpoints are called by the client
// transfer private keys (in case of prior ``/melt``).
//
// TODO: add details about the derivation.
- disclosed_batch_seeds: BatchSeed[];
+ disclosed_batch_seeds: BatchSeed[TALER_CNC_KAPPA-1];
// Array of ``n`` entries of transfer public keys
// (ephemeral ECDHE keys), each for the ``noreveal_index``.
@@ -3583,12 +3592,12 @@ the API during normal operation.
// this refresh operation, including melting fee.
value_with_fee: Amount;
- // Master seed for the Clause-schnorr R-value
- // creation. Must match the /csr-melt request.
+ // Master seed for the Clause-Schnorr R-value
+ // creation. Must match the /blinding-prepare request.
// Must not have been used in any prior melt request.
// Must be present if one of the fresh coin's
// denominations is of type Clause-Schnorr.
- rms?: RefreshMasterSeed;
+ cs_seed?: BlindingMasterSeed;
// Array of ``n`` new hash codes of denomination public keys
// for the new coins to order.
