commit 87ff7614592c4379fa755a7b0d0bd684b814b9ff
parent 47f79b7d523d05e8477e0efdba87676841988ba3
Author: Christian Grothoff <christian@grothoff.org>
Date: Mon, 7 Apr 2025 15:00:51 +0200
Merge branch 'master' of git+ssh://git.taler.net/taler-docs
Diffstat:
2 files changed, 116 insertions(+), 76 deletions(-)
diff --git a/core/api-common.rst b/core/api-common.rst
@@ -367,6 +367,11 @@ hashed data. See `base32`_.
// 32-byte nonce value, must only be used once.
type RefreshMasterSeed = string;
+.. ts:def:: BlindingMasterSeed
+
+ // 32-byte nonce value, must only be used once.
+ type BlindingMasterSeed = string;
+
.. ts:def:: Cs25519Point
// 32-byte value representing a point on Curve25519.
diff --git a/core/api-exchange.rst b/core/api-exchange.rst
@@ -1471,74 +1471,20 @@ 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``.
+ for ``/csr-withdraw`` and ``/csr-melt``.
.. http:post:: /blinding-prepare
@@ -1581,19 +1527,38 @@ Blinding Prepare
// Cipher type
cipher: "CS";
- // Nonces to be used by the exchange to derive
- // its private input from. Must not have ever
- // been used before.
- nonces: CSNonce[];
+ // The request type this blinding is for.
+ request: "withdraw" | "melt";
- // Hashes of the public keys of the denominations the
- // request relates to. The denomination MUST support
- // Clause-Schnorr signatures. The array MUST be of
- // same length as ``nonces``.
- denoms_h: HashCode[];
+ // Master seed for the Clause-Schnorr R-value creation.
+ // MUST not have been used in any prior request of this type.
+ seed: BlindingMasterSeed;
+
+ // Array of denominations and coin offsets for
+ // each of the fresh coins with a CS-cipher
+ // denomination.
+ // The coin_offset values MUST be strongly increasing.
+ nks: BlindingDenomNonce[];
}
+ .. ts:def:: BlindingDenomNonce
+
+ interface BlindingDenomNonce {
+
+ // Offset of this coin in the list of
+ // fresh coins. May not match the array offset
+ // as the fresh coins may include non-CS
+ // denominations as well.
+ coin_offset: Integer;
+
+ // Hash of the public key of the denomination the
+ // request relates to. Must be a CS denomination type.
+ denom_pub_hash: HashCode;
+ }
+
+
+
.. ts:def:: BlindingPrepareResponse
type BlindingPrepareResponse = BlindingPrepareResponseCS;
@@ -1618,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
~~~~~~~~~~~~
@@ -1826,6 +1854,13 @@ Withdraw
// age restriction.
max_age?: number;
+ // Master seed for the Clause-Schnorr R-value creation.
+ // MUST match the /blinding-prepare request.
+ // MUST NOT have been used in any prior withdraw request.
+ // MUST be present if one of the fresh coin's
+ // denominations is of type Clause-Schnorr.
+ blinding_seed?: BlindingMasterSeed;
+
// Array of blinded coin envelopes of type `CoinEnvelope`.
// If ``max_age`` is not set, MUST be n entries.
// If ``max_age`` is set, MUST be ``n*kappa`` entries,
@@ -2130,7 +2165,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``.
@@ -3564,12 +3599,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;
+ blinding_seed?: BlindingMasterSeed;
// Array of ``n`` new hash codes of denomination public keys
// for the new coins to order.
