[taler-docs] 06/15: finalizing age-withdraw api

[gnunet]

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

oec pushed a commit to branch master
in repository docs.

commit f099681119f1dd5fedefb167da3e8e7c23a60895
Author: Özgür Kesim <oec-taler@kesim.org>
AuthorDate: Mon Jan 9 17:57:17 2023 +0100

    finalizing age-withdraw api
---
 core/api-exchange.rst | 90 +++++++++++++++++++++++++++++----------------------
 1 file changed, 51 insertions(+), 39 deletions(-)

diff --git a/core/api-exchange.rst b/core/api-exchange.rst
index a4c6fab..ec47d15 100644
--- a/core/api-exchange.rst
+++ b/core/api-exchange.rst
@@ -2087,19 +2087,9 @@ If so, the exchange will blindly sign ``n`` undisclosed 
coins from the request.
   :http:statuscode:`403 Forbidden`:
     A signature is invalid.
     This response comes with a standard `ErrorDetail` response.
-  :http:statuscode:`404 Not found`:
-    A denomination key or the reserve are not known to the exchange.  If the
-    denomination key is unknown, this suggests a bug in the wallet as the
-    wallet should have used current denomination keys from ``/keys``.
-    In this case, the response will be a `DenominationUnknownMessage`.
-    If the reserve is unknown, the wallet should not report a hard error yet, 
but
-    instead simply wait for up to a day, as the wire transaction might simply
-    not yet have completed and might be known to the exchange in the near 
future.
-    In this case, the wallet should repeat the exact same request later again
-    using exactly the same blinded coin.
   :http:statuscode:`409 Conflict`:
     The balance of the reserve is not sufficient to withdraw the coins of the
-    indicated denominations.  The response is `WithdrawError` object.
+    given amount.  The response is a `WithdrawError` object.
   :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.
@@ -2122,14 +2112,18 @@ If so, the exchange will blindly sign ``n`` undisclosed 
coins from the request.
     interface AgeWithdrawRequest {
       // Commitment to the coins with age restriction.  This is the SHA512
       // hash value $ACH over all n*kappa `TALER_CoinPubHashP` values of all
-      // coins and their age commitments.
-      // It is also used in the subsequent call to /age-withdraw/$ACH/reveal.
+      // coins and their age commitments.  It is alter used as part of the URL
+      // in the subsequent call to /age-withdraw/$ACH/reveal.
       age_restricted_coins_commitment: HashCode;
 
-      // Array of ``n`` hash codes of denomination public keys to order.
-      // These denominations MUST support age restriction as defined in the
-      // output to ``/keys``.
-      denoms_h: HashCode[];
+      // The total amount that the client wants to withdraw from the reserve
+      // and must be at most the balance of the reserve.  The balance of the
+      // reserve will be immediatley reduced by that amount.
+      // In the subsequent call to /age-withdraw/$ACH/reveal, the client has to
+      // provide the list of denominations (with support for age restriction)
+      // that the coins shall be signed with.  The sum of the values of those
+      // denominations MUST equal this amount.
+      amount: Amount;
 
       // Signature of `TALER_AgeWithdrawRequestPS` created with
       // the `reserves's private key <reserve-priv>`
@@ -2178,23 +2172,37 @@ If so, the exchange will blindly sign ``n`` undisclosed 
coins from the request.
     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:`404 Not found`:
-    The commitment $ACH was not found.
+    The provided commitment $ACH is unknown.
   :http:statuscode:`409 Conflict`:
-    An age commitment for one of the coins did not fulfill the required maximum
-    age requirement of the corresponding reserve.  The response is an
-    `WithdrawError` object.
+    The reveal operation failed and the response is an `WithdrawError` object.
+    The error codes indicate one of two cases:
+
+    1. An age commitment for 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``.
+    2. The sum of all denominations in the request is not equal to the amount
+       that was given in the previous commitment via the call to
+       /reserves/$RESERVE_PUB/age-withdraw.  Error code:
+       ``TALER_EC_EXCHANGE_GENERIC_MISMATCH_OF_AMOUNT_AND_DENOMINATIONS``.
+
 
   .. ts:def:: WithdrawRevealRequest
 
     interface WithdrawRevealRequest {
-      // Array of ``n`` entries with blinded coins, matching the respective
-      // entries in ``denoms_h`` from the previous call to
-      // the /reserve/$RESERVE_PUB/age-withraw endpoint.  These are the
-      // non-desclosed coins from the previous commitment.
+      // 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 MUST equal the original amount
+      // of the previous commitment.
+      denoms_h: HashCode[];
+
+      // Array of ``n`` entries with blinded coins, which are the non-desclosed
+      // coins in the previous commitment. They match the respective entries
+      // in ``denoms_h``.
       coin_evs:  CoinEnvelope[];
 
-      // Array of ``n`` arrays of ``kappa - 1`` disclosed coin public keys
-      // together with their age commitments.
+      // Array of ``n`` arrays of ``kappa - 1`` disclosed coin private keys,
+      // from which the associated age commitments are also derived.
       disclosed_coins: DisclosedAgeRestrictedCoin[][];
 
     }
@@ -2202,24 +2210,22 @@ If so, the exchange will blindly sign ``n`` undisclosed 
coins from the request.
   .. ts:def:: DisclosedAgeRestrictedCoin
 
     interface DisclosedAgeRestrictedCoin {
-      // The coin's private key.
-      //
-      // The age commitment for this coin MUST be derived from this
-      // private key as follows:
+      // A coin's private key.  The associated age commitment for this coin
+      // MUST be derived from this private key as follows:
       //
       // For age group $AG from 1 up to
       //           <maximum age group as defined in the reserve>
       // (if they exist), set
-      //       seed = HDKF(coin_priv, "age-commitment", $AG)
-      //     p[$AG] = Edx25519_generate_private(seed)
+      //     seed = HDKF(coin_priv, "age-commitment", $AG)
+      //   p[$AG] = Edx25519_generate_private(seed)
       // and calculate the corresponding Edx25519PublicKey as
-      //     q[$AG] = Edx25519_public_from_private(p[$AG])
+      //   q[$AG] = Edx25519_public_from_private(p[$AG])
       //
-      // For age groups _larger_ than the maximum age group allowed
+      // For age groups $AG _larger_ than the maximum age group allowed
       // (if they exist), set
-      //     f[$AG] = HDKF(coin_priv, "age-factor", $AG)
+      //   f[$AG] = HDKF(coin_priv, "age-factor", $AG)
       // and calculate the corresponding Edx25519PublicKey as
-      //     q[$AG] = Edx25519_derive_public(PublishedBaseKey, f[$AG])
+      //   q[$AG] = Edx25519_derive_public(`PublishedAgeRestrictionBaseKey`, 
f[$AG])
       //
       // Finally, with coin_priv and age commitment (q[]), the exchange
       // will calculate the coin's public key coin_pub and use the
@@ -2229,9 +2235,15 @@ If so, the exchange will blindly sign ``n`` undisclosed 
coins from the request.
 
     }
 
-  .. ts:def:: BasePublicKey
+  .. ts:def:: PublishedAgeRestrictionBaseKey
 
-     type BasePublicKey = Edx25519PublicKey(...); // TODO: definition!
+    // The value for ``PublishedAgeRestrictionBaseKey`` is a randomly chosen
+    // `Edx25519PublicKey` for which the private key is not known to the 
clients.  It is
+    // used during the age-withdraw protocol so that clients can proof that 
they
+    // derived all public keys to age groups higher than their allowed maximum
+    // from this particular value.
+    const PublishedAgeRestrictionBaseKey =
+        new 
Edx25519PublicKey("DZJRF6HXN520505XDAWM8NMH36QV9J3VH77265WQ09EBQ76QSKCG");
 
 
 

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