[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[taler-docs] branch master updated (fa7275c1 -> 49a8ce39)
From: |
gnunet |
Subject: |
[taler-docs] branch master updated (fa7275c1 -> 49a8ce39) |
Date: |
Thu, 16 Jan 2025 13:00:25 +0100 |
This is an automated email from the git hooks/post-receive script.
oec pushed a change to branch master
in repository taler-docs.
from fa7275c1 coreapi: clarify more payto types
new 63eaaa72 [exchange] refine recoup requests
new 49a8ce39 [exchange] cleanup from age-withdrawal
The 2 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
Summary of changes:
core/api-common.rst | 32 +++++++++++
core/api-exchange.rst | 153 +++++++-------------------------------------------
2 files changed, 52 insertions(+), 133 deletions(-)
diff --git a/core/api-common.rst b/core/api-common.rst
index 9f1f57a9..59d9f0c3 100644
--- a/core/api-common.rst
+++ b/core/api-common.rst
@@ -15,6 +15,7 @@
@author Christian Grothoff
@author Marcello Stanisci
+ @author Özgür Kesim
.. _http-common:
@@ -1245,6 +1246,37 @@ within the
struct TALER_AgeMask mask;
};
+
+.. _TALER_WithdrawConfirmationPS:
+
+.. sourcecode:: c
+
+ struct TALER_WithdrawConfirmationPS
+ {
+ /**
+ * Purpose is #TALER_SIGNATURE_EXCHANGE_CONFIRM_WITHDRAW. Signed by a
+ * `struct TALER_ExchangePublicKeyP` using EdDSA.
+ */
+ struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
+
+ /**
+ * Commitment made in the /reserves/$RESERVE_PUB/withdraw.
+ */
+ struct TALER_WithdrawCommitmentHashP h_commitment GNUNET_PACKED;
+
+ /**
+ * If age restriction does not apply to this withdrawal,
+ * (i.e. max_age was not set during the request)
+ * MUST be 0xFFFFFFFF.
+ * Otherwise (i.e. age restriction applies):
+ * index that the client will not have to reveal, in NBO,
+ * MUST be smaller than #TALER_CNC_KAPPA.
+ */
+ uint32_t noreveal_index GNUNET_PACKED;
+
+ };
+
+
.. _TALER_SingleWithdrawRequestPS:
.. sourcecode:: c
diff --git a/core/api-exchange.rst b/core/api-exchange.rst
index d2609536..77a71a80 100644
--- a/core/api-exchange.rst
+++ b/core/api-exchange.rst
@@ -14,6 +14,7 @@
TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
@author Christian Grothoff
+ @author Özgür Kesim
========================
The Exchange RESTful API
@@ -1805,7 +1806,7 @@ Withdraw
// ``/reveal-withdraw/$ACH``.
noreveal_index: Integer;
- // Signature of `TALER_AgeWithdrawConfirmationPS` whereby
+ // Signature of `TALER_WithdrawConfirmationPS` whereby
// the exchange confirms the ``noreveal_index``.
exchange_sig: EddsaSignature;
@@ -1969,111 +1970,6 @@ 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
-success, the exchange answers this request with an noreveal-index. The client
-then has to call ``/age-withdraw/$ACH/reveal`` to reveal all ``n*(kappa - 1)``
-coins along with their age commitments to proof that they were appropriate.
-If so, the exchange will blindly sign ``n`` undisclosed coins from the request.
-
-
-.. http:post:: /reserves/$RESERVE_PUB/age-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
- this request, so that it can recover the information if necessary in case of
- transient failures, like power outage, network outage, etc.
-
- **Request:** The request body must be a `AgeWithdrawRequest` object.
-
- **Response:**
-
- :http:statuscode:`200 OK`:
- The request was successful, and the response is a `AgeWithdrawResponse`.
- 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.
- :http:statuscode:`403 Forbidden`:
- A signature is invalid.
- This response comes with a standard `ErrorDetail` response.
- :http:statuscode:`409 Conflict`:
- One of two reasons occured:
-
- 1. The balance of the reserve is not sufficient to withdraw the coins of
the
- given amount. The response is a `WithdrawError` object.
-
- 2. The provided value for ``max_age`` is higher than the allowed value
- according to the reserve's birthday. The response comes with a standard
- `ErrorDetail` response with error-code
- ``TALER_EC_EXCHANGE_AGE_WITHDRAW_MAXIMUM_AGE_TOO_LARGE``
- and an additional field ``maximum_allowed_age`` for the maximum age (in
years)
- that the client can commit to in a call to ``/age-withdraw``
- :http:statuscode:`410 Gone`:
- A requested denomination key is not yet or no longer valid.
- It either before the validity start, past the expiration or was revoked.
- The response is a `DenominationExpiredMessage`. Clients must evaluate the
- error code provided to understand which of the cases this is and handle it
- accordingly.
- :http:statuscode:`451 Unavailable for Legal Reasons`:
- This reserve has received funds from a purse or the amount withdrawn
- exceeds another legal threshold and thus the reserve must
- be upgraded to an account (with KYC) before the withdraw can
- complete. Note that this response does NOT affirm that the
- withdraw will ultimately complete with the requested amount.
- The user should be redirected to the provided location to perform
- the required KYC checks to open the account before withdrawing.
- Afterwards, the request should be repeated.
- The response will be an `LegitimizationNeededResponse` object.
-
- .. ts:def:: AgeWithdrawRequest
-
- interface AgeWithdrawRequest {
- // Array of ``n`` hash codes of denomination public keys to order.
- // These denominations MUST support age restriction as defined in the
- // output to /keys.
- // The sum of all denomination's values and fees MUST be at most the
- // balance of the reserve. The balance of the reserve will be
- // immediatley reduced by that amount.
- denoms_h: HashCode[];
-
- // ``n`` arrays of ``kappa`` entries with blinded coin envelopes. Each
- // (toplevel) entry represents ``kappa`` canditates for a particular
- // coin. The exchange will respond with an index ``gamma``, which is
- // the index that shall remain undisclosed during the reveal phase.
- // The SHA512 hash $ACH over the blinded coin envelopes is the commitment
- // that is later used as the key to the reveal-URL.
- blinded_planchets: CoinEnvelope[][];
-
- // The maximum age to commit to. MUST be the same as the maximum
- // age in the reserve.
- max_age: number;
-
- // Signature of `TALER_AgeWithdrawRequestPS` created with
- // the `reserves's private key <reserve-priv>`
- // using purpose ``TALER_SIGNATURE_WALLET_RESERVE_AGE_WITHDRAW``.
- reserve_sig: EddsaSignature;
- }
-
-
-.. http:post:: /age-withdraw/$ACH/reveal
-
- .. note::
- This endpoint is deprecated starting with API version v24.
- It is renamed to ``/reveal-withdraw/$ACH``, see `Reveal`_.
- The request and response objects are identical.
-
-
------
Reveal
------
@@ -2353,7 +2249,6 @@ Reserve History
type TransactionHistoryItem =
| AccountSetupTransaction
| ReserveWithdrawTransaction
- | ReserveAgeWithdrawTransaction
| ReserveCreditTransaction
| ReserveClosingTransaction
| ReserveOpenRequestTransaction
@@ -2414,30 +2309,8 @@ Reserve History
// created with the reserve's private key.
reserve_sig: EddsaSignature;
- // Fee that is charged for withdraw.
- withdraw_fee: Amount;
- }
-
- .. ts:def:: ReserveAgeWithdrawTransaction
-
- interface ReserveAgeWithdrawTransaction {
- type: "AGEWITHDRAW";
-
- // Offset of this entry in the reserve history.
- // Useful to request incremental histories via
- // the "start" query parameter.
- history_offset: Integer;
-
- // Total Amount withdrawn.
- amount: Amount;
-
- // Commitment of all ``n*kappa`` blinded coins.
- h_commitment: HashCode;
-
- // Signature over a `TALER_AgeWithdrawRequestPS`
- // with purpose ``TALER_SIGNATURE_WALLET_RESERVE_AGE_WITHDRAW``
- // created with the reserve's private key.
- reserve_sig: EddsaSignature;
+ // The maximum age committed to, if applicable
+ max_age?: Integer;
// Fee that is charged for withdraw.
withdraw_fee: Amount;
@@ -2830,9 +2703,16 @@ Coin History
// that is important to fix the coin's denomination.
h_denom_pub: HashCode;
- // Coin blinding key.
+ // Coin blinding key that was used in the original withdraw request.
coin_blind: DenominationBlindingKeyP;
+ // The hash of the withdraw commitment of the original withdraw
+ // request that this coin was part of
+ h_commitment: HashCode;
+
+ // Coin's index in the original withdraw request, starting at 0
+ coin_index: Integer;
+
// Reserve receiving the recoup.
reserve_pub: EddsaPublicKey;
@@ -2904,9 +2784,16 @@ Coin History
// that is important to fix the coin's denomination.
h_denom_pub: HashCode;
- // Coin blinding key.
+ // Coin blinding key that was used in the original withdraw request.
coin_blind: DenominationBlindingKeyP;
+ // The hash of the withdraw commitment of the original withdraw
+ // request that this coin was part of
+ h_commitment: HashCode;
+
+ // Coin's index in the original withdraw request, starting at 0
+ coin_index: Integer;
+
// Signature by the exchange over a
// `TALER_RecoupRefreshConfirmationPS`
// of purpose ``TALER_SIGNATURE_EXCHANGE_CONFIRM_RECOUP_REFRESH``.
--
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.
- [taler-docs] branch master updated (fa7275c1 -> 49a8ce39),
gnunet <=