taler-docs

commit ffdda0098dcb0c7fa01065f456566344338703ef
parent d073c399163ca3529a8691f319f408b4deac6e86
Author: Özgür Kesim <oec@kesim.org>
Date:   Tue, 21 Jan 2025 16:21:56 +0100

[exchange] added /blinding-prepare endpoint

Diffstat:
M
core/api-exchange.rst
 | 
84
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

1 file changed, 84 insertions(+), 0 deletions(-)
diff --git a/core/api-exchange.rst b/core/api-exchange.rst
@@ -1549,9 +1549,93 @@ exchange.
     }
 
 
+Blinding Prepare
+~~~~~~~~~~~~~~~~
+
+.. note:: This endpoint is available since v24 of the API and is a substitute
+   for ``/csr-withdraw``.
+
+
+.. http:post:: /blinding-prepare
+
+  Obtain exchange-side input values in preparation for a
+  blinding step of multiple coins for certain denomination
+  cipher types, specifically at this point for Clause-Schnorr
+  blind signatures.
+
+  **Request:** The request body must be a `BlindingPrepareRequest` object.
+
+  **Response:**
+
+  :http:statuscode:`200 OK`:
+    The request was successful, and the response is a
+    `BlindingPrepareResponse`.  Note that repeating exactly the same request
+    will again yield the same response (assuming none of the denominations is
+    expired).
+  :http:statuscode:`404 Not found`:
+    A denomination key is not known to the exchange.  The response is a
+    `DenominationUnknownMessage`.
+  :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:: BlindingPrepareRequest
+
+    interface BlindingPrepareRequest {
+
+      // Nonces to be used by the exchange to derive
+      // its private inputs from. Must not have ever
+      // been used before.
+      nonces: CSNonce[];
+
+      // Hashes of the public keys of denominations the
+      // request relates to. Must be of the same length
+      // as ``nonces``.
+      denom_pub_hs: HashCode[];
+
+    }
+
+  .. ts:def:: BlindingPrepareResponse
+
+    type BlindingPrepareResponse = BlindingPrepareValue[];
+
+  .. ts:def:: BlindingPrepareValue
+
+    type BlindingPrepareValue =
+      | BlindingPrepareRSAValue
+      | BlindingPrepareCSValue;
+
+  .. ts:def:: BlindingPrepareRSAValue
+
+    interface  BlindingPrepareRSAValue{
+      cipher: "RSA";
+    }
+
+  .. ts:def:: BlindingPrepareCSValue
+
+    interface BlindingPrepareCSValue {
+      cipher: "CS";
+
+      // CSR R0 value
+      r_pub_0: CsRPublic;
+
+      // CSR R1 value
+      r_pub_1: CsRPublic;
+    }
+
+
+
 CSR-Withdraw
 ~~~~~~~~~~~~
 
+.. note:: This endpoint is deprecated starting with API version v24.
+   Use ``/blinding-prepare`` instead.
+
 .. http:post:: /csr-withdraw
 
   Obtain exchange-side input values in preparation for a