-update documentation

1 files changed, 98 insertions, 29 deletions

diff --git a/core/api-exchange.rst b/core/api-exchange.rst
index 955121af..ac8c44b2 100644
--- a/core/api-exchange.rst
+++ b/core/api-exchange.rst
@@ -1,6 +1,6 @@
 ..
   This file is part of GNU TALER.
-  Copyright (C) 2014-2021 Taler Systems SA
+  Copyright (C) 2014-2022 Taler Systems SA
 
   TALER is free software; you can redistribute it and/or modify it under the
   terms of the GNU Affero General Public License as published by the Free Software
@@ -303,7 +303,8 @@ possibly by using HTTPS.
       // 32-bit age mask.
       age_mask: Integer;
 
-      cs_public_key: FIXME;
+      // Public key of the denomination.
+      cs_public_key: Cs25519Point;
 
     }
 
@@ -1409,7 +1410,7 @@ exchange.
     }
 
 
-.. http:post:: /csr
+.. http:post:: /csr-withdraw
 
   Obtain exchange-side input values in preparation for a
   withdraw step for certain denomination cipher types,
@@ -1438,30 +1439,21 @@ exchange.
 
     interface WithdrawPrepareRequest {
 
-       nks: WithdrawPrepareDenomNonce[];
-
-    }
-
-  .. ts:def:: WithdrawPrepareDenomNonce
-
-    interface WithdrawPrepareDenomNonce {
-
-      // Random client-side nonce
-      nonce: FIXME;
+      // Nonce to be used by the exchange to derive
+      // its private inputs from. Must not have ever
+      // been used before.
+      nonce: CSNonce;
 
       // Hash of the public key of the denomination the
       // request relates to.
       denom_pub_hash: Hash;
-    }
 
+    }
 
   .. ts:def:: WithdrawPrepareResponse
 
-    interface WithdrawPrepareResponse {
-      // Responses for each request, in the same
-      // order that was used in the request.
-      ewvs: ExchangeWithdrawValue[];
-    }
+    type WithdrawPrepareResponse
+      | ExchangeWithdrawValue;
 
   .. ts:def:: ExchangeWithdrawValue
 
@@ -1487,9 +1479,6 @@ exchange.
       r_pub_1: CsRPublic;
     }
 
-
-
-
 .. http:post:: /reserves/$RESERVE_PUB/withdraw
 
   Withdraw a coin of the specified denomination.  Note that the client should
@@ -1628,9 +1617,13 @@ exchange.
     interface CSBlindedDenominationSignature {
       type: "CS";
 
-      b: FIXME;
+      // Signer chosen bit value, 0 or 1, used
+      // in Clause Blind Schnorr to make the
+      // ROS problem harder.
+      b: Integer;
 
-      s: FIXME;
+      // Blinded scalar calculated from c_b.
+      s: Cs25519Scalar;
 
     }
 
@@ -1842,9 +1835,11 @@ denomination.
     interface CSDenominationSignature {
       type: "CS";
 
-      cs_signature_r: FIXME;
+      // R value component of the signature.
+      cs_signature_r: Cs25519Point;
 
-      cs_signature_s: FIXME:
+      // s value component of the signature.
+      cs_signature_s: Cs25519Scalar:
 
     }
 
@@ -2202,6 +2197,73 @@ using the ``/refresh/link`` request.  While ``/refresh/link`` must be implemente
 the exchange to achieve taxability, wallets do not really ever need that part of
 the API during normal operation.
 
+
+.. http:post:: /csr-melt
+
+  Obtain exchange-side input values in preparation for a
+  melt step for certain denomination cipher types,
+  specifically at this point for Clause-Schnorr blind
+  signatures.
+
+  **Request:** The request body must be a `MeltPrepareRequest` object.
+
+  **Response:**
+
+  :http:statuscode:`200 OK`:
+    The request was successful, and the response is a `MeltPrepareResponse`.  Note that repeating exactly the same request
+    will again yield the same response (assuming none of the denomination is expired).
+  :http:statuscode:`404 Not found`:
+    A denomination key is not known to the exchange.
+  :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.
+
+  **Details:**
+
+  .. ts:def:: MeltPrepareRequest
+
+    interface WithdrawPrepareRequest {
+
+      // Master seed for the Clause-schnorr R-value
+      // creation.
+      // Must not have been used in any prior request.
+      rms: RefreshMasterSeed;
+
+      // Array of denominations and coin offsets for
+      // each of the fresh coins with a CS-cipher
+      // denomination.
+      nks: MeltPrepareDenomNonce[];
+
+    }
+
+  .. ts:def:: MeltPrepareDenomNonce
+
+    interface MeltPrepareDenomNonce {
+
+      // 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: Hash;
+    }
+
+
+  .. ts:def:: MeltPrepareResponse
+
+    interface MeltPrepareResponse {
+      // Responses for each request, in the same
+      // order that was used in the request.
+      ewvs: ExchangeWithdrawValue[];
+    }
+
+
 .. _refresh:
 .. http:post:: /coins/$COIN_PUB/melt
 
@@ -2262,6 +2324,13 @@ the API during normal operation.
       // See also ``TALER_refresh_get_commitment()``.
       rc: TALER_RefreshCommitmentP;
 
+      // Master seed for the Clause-schnorr R-value
+      // creation. Must match the /csr-melt 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;
+
     }
 
   For details about the HKDF used to derive the new coin private keys and
@@ -2451,7 +2520,7 @@ the API during normal operation.
       coin_ev : CoinEnvelope;
 
       // Values contributed by the exchange during the
-      // withdraw operation (see /csr).
+      // withdraw operation (see /csr-melt).
       ewv: ExchangeWithdrawValue;
 
       // Offset of this coin in the refresh operation.
@@ -2537,7 +2606,7 @@ in using this API.
       denom_sig: DenominationSignature;
 
       // Exchange-contributed values during the refresh
-      // operation (see /csr).
+      // operation (see /csr-withdraw).
       ewv: ExchangeWithdrawValue;
 
       // Signature of `TALER_RecoupRequestPS` created with
@@ -2616,7 +2685,7 @@ in using this API.
       denom_sig: DenominationSignature;
 
       // Exchange-contributed values during the refresh
-      // operation (see /csr).
+      // operation (see /csr-melt).
       ewv: ExchangeWithdrawValue;
 
       // Signature of `TALER_RecoupRefreshRequestPS` created with