[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[taler-docs] branch master updated: [reveal] seperate endpoints /reveal-
From: |
gnunet |
Subject: |
[taler-docs] branch master updated: [reveal] seperate endpoints /reveal-melt and /reveal-withdraw |
Date: |
Sat, 04 Jan 2025 13:44:35 +0100 |
This is an automated email from the git hooks/post-receive script.
oec pushed a commit to branch master
in repository docs.
The following commit(s) were added to refs/heads/master by this push:
new f8c6d544 [reveal] seperate endpoints /reveal-melt and /reveal-withdraw
f8c6d544 is described below
commit f8c6d544abbe032da3e7da3624d8b3a4887202b1
Author: Özgür Kesim <oec-taler@kesim.org>
AuthorDate: Sat Jan 4 13:43:10 2025 +0100
[reveal] seperate endpoints /reveal-melt and /reveal-withdraw
Instead of a single endpoint with optional fields,
we will introduce separate endpoints for the reveal
after /melt and /withdraw.
---
core/api-exchange.rst | 206 ++++++++++++++++++++++++++++----------------------
1 file changed, 116 insertions(+), 90 deletions(-)
diff --git a/core/api-exchange.rst b/core/api-exchange.rst
index 58028dcb..b167d3b8 100644
--- a/core/api-exchange.rst
+++ b/core/api-exchange.rst
@@ -1650,7 +1650,7 @@ Withdraw
:http:statuscode:`201 Created`:
The request was successful, and ``max_age`` was set.
The response is a `AgeWithdrawResponse`. The client is expected
- to call ``/reveal/$ACH`` next.
+ to call ``/reveal-withdraw/$ACH`` next.
Note that repeating exactly the same request will again yield the same
response, so if the network goes down during the transaction or before the
client can commit the coin signature to disk, the coin is not lost.
@@ -1812,7 +1812,7 @@ Withdraw
interface AgeWithdrawResponse {
// index of the commitments that the client doesn't
// have to disclose in the subsequent call to
- // ``/withdraw/$ACH/reveal``.
+ // ``/reveal-withdraw/$ACH``.
noreveal_index: Integer;
// Signature of `TALER_AgeWithdrawConfirmationPS` whereby
@@ -1983,6 +1983,11 @@ Batch Withdraw
Withdraw with Age Restriction
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. note::
+ This endpoint becomes deprecated starting with API version v24.
+ Use the ``/reserves/$RESERVE_PUB/withdraw`` endpoint instead,
+ see `Withdraw`_.
+
If the reserve was marked with a maximum age group, the client has to perform a
cut&choose protocol with the exchange. It first calls
``/reserves/$RESERVE_PUB/age-withdraw`` and commits to ``n*kappa`` coins. On
@@ -1994,11 +1999,6 @@ If so, the exchange will blindly sign ``n`` undisclosed
coins from the request.
.. http:post:: /reserves/$RESERVE_PUB/age-withdraw
- .. note::
- This endpoint becomes deprecated starting with API version v24.
- Use the ``/reserves/$RESERVE_PUB/withdraw`` endpoint instead,
- see `Withdraw`_.
-
Withdraw multiple coins *with age restriction* from the same reserve.
Note that the client should commit all of the request details, including the
private key of the coins and the blinding factors, to disk *before* issuing
@@ -2080,7 +2080,7 @@ If so, the exchange will blindly sign ``n`` undisclosed
coins from the request.
.. note::
This endpoint is deprecated starting with API version v24.
- It is renamed to ``/reveal/withdraw/$ACH``, see `Reveal`_.
+ It is renamed to ``/reveal-withdraw/$ACH``, see `Reveal`_.
The request and response objects are identical.
@@ -2089,9 +2089,9 @@ Reveal
------
.. note::
- This endpoint is available starting with API version v24.
+ These endpoints are available starting with API version v24.
-This endpoint is called by the client
+These endpoints are called by the client
#. after a call to `melt`_.
Now the client has to disclose --for each coin--
@@ -2107,32 +2107,22 @@ This endpoint is called by the client
and prove that the age restriction was set correctly.
-
-.. http:post:: /reveal/$RCH
+.. http:post:: /reveal-melt/$RCH
Reveal previously committed values to the exchange, except for the values
- corresponding to the ``noreveal_index`` returned by the ``/withdraw`` or
``/melt/`` steps.
- Depending on the prior call to either ``/melt`` or ``/withdraw``,
- the $RCH is calculated as follows:
+ corresponding to the ``noreveal_index`` returned by the ``/melt`` step.
- .. warning:: TODO: be more specific about the calculation of $RCH here:
+ ``$RCH`` is the hash over the melt commitment from the ``/melt/`` step,
+ i.e. the value of ``h_melt_commitment`` from that prior request.
- #. In case of `melt`_:
- $RCH is the hash over the melt commitment from the ``/melt/`` step,
- i.e. the value of ``h_melt_commitment`` from that request.
- #. In case of `Withdraw`_:
- $RCH is the running hash over all commitments from the former withdraw
request.
-
- Note that the value for $RCH is calculated independently by both sides
- and has never appeared *explicitly* in the protocol before.
-
-
- The base URL for ``/reveal``-request may differ from the main base URL of
+ The base URL for ``/reveal-melt``-request may differ from the main base URL
of
the exchange. Clients SHOULD respect the ``reveal_base_url`` returned for the
coin during melt operations. The exchange MUST return a
307 or 308 redirection to the correct base URL if the client failed to
respect the ``reveal_base_url`` or if the allocation has changed.
+ The request body is a `RevealMeltRequest`.
+
:http:statuscode:`200 OK`:
The coin's' secret material matched the commitment and the original
request was well-formed.
The response body is a `RevealResponse`.
@@ -2141,66 +2131,41 @@ This endpoint is called by the client
:http:statuscode:`409 Conflict`:
There is a problem between the original commitment and the revealed secret
data.
The returned information is proof of the mismatch,
- and therefore rather verbose, as it includes most of the original /melt or
/withdraw request,
+ and therefore rather verbose, as it includes most of the original /melt
request,
but of course expected to be primarily used for diagnostics.
The response body is a `RevealConflictResponse`.
- In case of reveal after a ``/withdraw`` request, i.e. for withdrawal with
age restriction,
- the following specific error codes can be returned:
-
- - An age commitment for at least one of the coins did not fulfill the
- required maximum age requirement of the corresponding reserve.
- Error code:
- ``TALER_EC_EXCHANGE_GENERIC_COIN_AGE_REQUIREMENT_FAILURE``.
- - The computation of the hash of the commitment with provided input does
- result in the value $ACH.
- Error code:
- ``TALER_EC_EXCHANGE_AGE_WITHDRAW_REVEAL_INVALID_HASH``
-
**Details:**
- Request body contains a JSON object with the following fields:
+ Request body for a ``reveal-melt`` request
+ contains a JSON object with the following fields:
- .. ts:def:: RevealRequest
+ .. ts:def:: RevealMeltRequest
- interface RevealRequest {
+ interface RevealMeltRequest {
// Array of ``(kappa - 1)`` disclosed batch secrets,
// from which for each of the n coins in a batch
// their coin master secret is derived,
// from which in turn their private key,
- // blinding, nonce (for Clause-Schnorr),
- // transfer private keys (in case of prior ``/melt``) and
- // age-restriction is calculated (in case of prior ``/withdraw``).
+ // blinding, nonce (for Clause-Schnorr) and
+ // transfer private keys (in case of prior ``/melt``).
//
// TODO: add details about the derivation.
- disclosed_batch_seeds: DisclosedBatchSeed[];
+ disclosed_batch_seeds: BatchSeed[];
- // If the prior request was ``/melt``,
- // this parameter MUST be set and is
- // the array of ``n`` entries of transfer public keys
+ // Array of ``n`` entries of transfer public keys
// (ephemeral ECDHE keys), each for the ``noreveal_index``.
- transfer_pubs?: EddsaPublicKey[];
+ transfer_pubs: EddsaPublicKey[];
- // If the prior request was ``/melt``,
- // this parameter MUST be set and is
- // the array of ``n`` signatures
- // made by the wallet using the old coin's private key,
+ // Array of ``n`` signatures made by the wallet
+ // using the old coin's private key,
// used later to verify the /refresh/link response from the exchange.
// Signs over a `TALER_CoinLinkSignaturePS`.
- link_sigs?: EddsaSignature[];
+ link_sigs: EddsaSignature[];
}
- .. ts:def:: DisclosedBatchSeed
-
- // For the reveal of n coins, contains the secret information
- // from which n coin specific secrets are derived from.
- // Details of the derivation depend of the specific sum type.
- type DisclosedBatchSeed = BatchSeed
- | AgeRestrictedBatchSeed;
-
-
.. ts:def:: BatchSeed
// The master seed material from which for n coins in a batch,
@@ -2213,6 +2178,87 @@ This endpoint is called by the client
type BatchSeed = string;
+ .. ts:def:: RevealResponse
+
+ type RevealResponse = WithdrawResponse;
+
+
+ .. ts:def:: RevealConflictResponse
+
+ interface RevealConflictResponse {
+ // Text describing the error.
+ hint: string;
+
+ // Detailed error code.
+ code: Integer;
+
+ // Commitment as calculated by the exchange from the revealed data.
+ rc_expected: HashCode;
+
+ }
+
+
+.. http:post:: /reveal-withdraw/$ACH
+
+ Reveal previously committed values to the exchange, except for the values
+ corresponding to the ``noreveal_index`` returned by the ``/withdraw`` step.
+
+ ``$ACH`` is the running hash over all commitments from the former withdraw
request.
+ Note that the value for $ACH is calculated independently by both sides
+ and has never appeared *explicitly* in the protocol before.
+
+ The base URL for ``/reveal-withdraw``-request may differ from the main base
URL of
+ the exchange. Clients SHOULD respect the ``reveal_base_url`` returned for the
+ coin during melt operations. The exchange MUST return a
+ 307 or 308 redirection to the correct base URL if the client failed to
+ respect the ``reveal_base_url`` or if the allocation has changed.
+
+ The request body is a `RevealWithdrawRequest`.
+
+ :http:statuscode:`200 OK`:
+ The coin's' secret material matched the commitment and the original
request was well-formed.
+ The response body is a `RevealResponse`.
+ :http:statuscode:`404 Not found`:
+ The provided commitment $RCH is unknown.
+ :http:statuscode:`409 Conflict`:
+ There is a problem between the original commitment and the revealed secret
data.
+ The returned information is proof of the mismatch,
+ and therefore rather verbose, as it includes most of the original
/withdraw request,
+ but of course expected to be primarily used for diagnostics.
+
+ The response body is a `RevealConflictResponse`.
+
+ The following specific error codes can be returned:
+
+ - An age commitment for at least one of the coins did not fulfill the
+ required maximum age requirement of the corresponding reserve.
+ Error code:
+ ``TALER_EC_EXCHANGE_GENERIC_COIN_AGE_REQUIREMENT_FAILURE``.
+ - The computation of the hash of the commitment with provided input does
+ result in the value $ACH.
+ Error code:
+ ``TALER_EC_EXCHANGE_AGE_WITHDRAW_REVEAL_INVALID_HASH``
+
+ **Details:**
+
+ Request body for a ``reveal-withdraw`` request
+ contains a JSON object with the following fields:
+
+ .. ts:def:: RevealWithdrawRequest
+
+ interface RevealWithdrawRequest {
+ // Array of ``(kappa - 1)`` disclosed batch secrets,
+ // from which for each of the n coins in a batch
+ // their coin master secret is derived,
+ // from which in turn their private key,
+ // blinding, nonce (for Clause-Schnorr) and
+ // age-restriction is calculated.
+ //
+ // TODO: add details about the derivation.
+ disclosed_batch_seeds: AgeRestrictedBatchSeed[];
+
+ }
+
.. ts:def:: AgeRestrictedBatchSeed
// The master seed material from which for n coins in a batch,
@@ -2249,26 +2295,6 @@ This endpoint is called by the client
new
Edx25519PublicKey("CH0VKFDZ2GWRWHQBBGEK9MWV5YDQVJ0RXEE0KYT3NMB69F0R96TG");
- .. ts:def:: RevealResponse
-
- type RevealResponse = WithdrawResponse;
-
-
- .. ts:def:: RevealConflictResponse
-
- interface RevealConflictResponse {
- // Text describing the error.
- hint: string;
-
- // Detailed error code.
- code: Integer;
-
- // Commitment as calculated by the exchange from the revealed data.
- rc_expected: HashCode;
-
- }
-
-
.. _reserve-history:
@@ -3535,9 +3561,9 @@ the API during normal operation.
// - the hash of the old age commitment
// - the value_with_fee
// - rms value, or NULL, if not applicable
- // - each entry in denom_h
+ // - each entry in denoms_h
// - each entry in coin_evs, depths first
- // - each of the required n*kappa transfer public keys (ephermeral
ECDHE keys).
+ // - each of the required n*kappa transfer public keys, depths first.
h_melt_commitment: HashCode;
// Signature by the `coin <coin-priv>` over the melt commitment.
@@ -3554,7 +3580,7 @@ the API during normal operation.
interface MeltResponse {
// Which of the ``kappa`` indices does the client not have to reveal
- // by calling the ``/reveal/refresh/`` endpoint.
+ // by calling the ``/reveal-melt/`` endpoint.
noreveal_index: Integer;
// Signature of `TALER_RefreshMeltConfirmationPS` whereby the exchange
@@ -3570,7 +3596,7 @@ the API during normal operation.
// Base URL to use for operations on the refresh context
// (so the reveal operation). If not given,
// the base URL is the same as the one used for this request.
- // Can be used if the base URL for ``/reveal/`` differs from that
+ // Can be used if the base URL for ``/reveal-melt/`` differs from that
// for ``/melt/``, i.e. for load balancing. Clients SHOULD
// respect the reveal_base_url if provided. Any HTTP server
// belonging to an exchange MUST generate a 307 or 308 redirection
@@ -3722,7 +3748,7 @@ the API during normal operation.
.. note::
This endpoint will become depreciated starting with version v24 of the
API.
- Use ``/reveal/refresh/$RCH`` then instead, see `Reveal`_.
+ Use ``/reveal-melt/$RCH`` then instead, see `Reveal`_.
Reveal previously committed values to the exchange, except for the values
corresponding to the ``noreveal_index`` returned by the ``/coins/``-melt
step.
--
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [taler-docs] branch master updated: [reveal] seperate endpoints /reveal-melt and /reveal-withdraw,
gnunet <=