[taler-docs] 02/02: [exchange] cleanup from age-withdrawal

[gnunet]

This is an automated email from the git hooks/post-receive script.

oec pushed a commit to branch master
in repository taler-docs.

commit 49a8ce39da740f6b4a38092b98c872978144d866
Author: Özgür Kesim <oec-taler@kesim.org>
AuthorDate: Thu Jan 16 12:59:29 2025 +0100

    [exchange] cleanup from age-withdrawal
    
    Remove structs and endpoints not needed anymore,
    since /age-withdraw is being dropped.
---
 core/api-common.rst   |  32 ++++++++++++
 core/api-exchange.rst | 135 ++------------------------------------------------
 2 files changed, 36 insertions(+), 131 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 d20ed37b..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;

-- 
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.