-update documentation

1 files changed, 54 insertions, 22 deletions

diff --git a/core/api-exchange.rst b/core/api-exchange.rst
index 75ed171a..955121af 100644
--- a/core/api-exchange.rst
+++ b/core/api-exchange.rst
@@ -303,7 +303,7 @@ possibly by using HTTPS.
       // 32-bit age mask.
       age_mask: Integer;
 
-      // FIXME: tbd
+      cs_public_key: FIXME;
 
     }
 
@@ -1439,22 +1439,22 @@ exchange.
     interface WithdrawPrepareRequest {
 
        nks: WithdrawPrepareDenomNonce[];
-    
+
     }
 
   .. ts:def:: WithdrawPrepareDenomNonce
 
     interface WithdrawPrepareDenomNonce {
-      
+
       // Random client-side nonce
       nonce: FIXME;
-      
+
       // Hash of the public key of the denomination the
       // request relates to.
       denom_pub_hash: Hash;
     }
 
-    
+
   .. ts:def:: WithdrawPrepareResponse
 
     interface WithdrawPrepareResponse {
@@ -1462,21 +1462,34 @@ exchange.
       // order that was used in the request.
       ewvs: ExchangeWithdrawValue[];
     }
-    
+
   .. ts:def:: ExchangeWithdrawValue
 
-    interface ExchangeWithdrawValue {
-      
+    type ExchangeWithdrawValue =
+      | ExchangeRsaWithdrawValue
+      | ExchangeCsWithdrawValue;
+
+  .. ts:def:: ExchangeRsaWithdrawValue
+
+    interface ExchangeRsaWithdrawValue {
+      cipher: "RSA";
+    }
+
+  .. ts:def:: ExchangeCsWithdrawValue
+
+    interface ExchangeCsWithdrawValue {
+      cipher: "CS";
+
       // CSR R0 value
-      r_pub_0: FIXME;
-      
+      r_pub_0: CsRPublic;
+
       // CSR R1 value
-      r_pub_1: FIXME;
+      r_pub_1: CsRPublic;
     }
-  
 
 
-  
+
+
 .. http:post:: /reserves/$RESERVE_PUB/withdraw
 
   Withdraw a coin of the specified denomination.  Note that the client should
@@ -1615,7 +1628,9 @@ exchange.
     interface CSBlindedDenominationSignature {
       type: "CS";
 
-      // FIXME: tbd
+      b: FIXME;
+
+      s: FIXME;
 
     }
 
@@ -1827,7 +1842,9 @@ denomination.
     interface CSDenominationSignature {
       type: "CS";
 
-      // FIXME: tbd
+      cs_signature_r: FIXME;
+
+      cs_signature_s: FIXME:
 
     }
 
@@ -2402,9 +2419,7 @@ the API during normal operation.
   **Response:**
 
   :http:statuscode:`200 OK`:
-    All commitments were revealed successfully.  The exchange returns an array,
-    typically consisting of only one element, in which each each element contains
-    information about a melting session that the coin was used in.
+    All commitments were revealed successfully.  The exchange returns an array (typically consisting of only one element), in which each each element of the array contains a `LinkResponse` entry with information about a melting session that the coin was used in.
   :http:statuscode:`404 Not found`:
     The exchange has no linkage data for the given public key, as the coin has not
     yet been involved in a refresh operation.
@@ -2435,6 +2450,14 @@ the API during normal operation.
       // Blinded coin.
       coin_ev : CoinEnvelope;
 
+      // Values contributed by the exchange during the
+      // withdraw operation (see /csr).
+      ewv: ExchangeWithdrawValue;
+
+      // Offset of this coin in the refresh operation.
+      // Input needed to derive the private key.
+      coin_idx: Integer;
+
       // Signature made by the old coin over the refresh request.
       // Signs over a `TALER_CoinLinkSignaturePS`.
       link_sig: EddsaSignature;
@@ -2513,13 +2536,17 @@ in using this API.
       // Signature over the `coin public key <eddsa-coin-pub>` by the denomination.
       denom_sig: DenominationSignature;
 
-      // Coin's blinding factor.
-      coin_blind_key_secret: DenominationBlindingKeySecret;
+      // Exchange-contributed values during the refresh
+      // operation (see /csr).
+      ewv: ExchangeWithdrawValue;
 
       // Signature of `TALER_RecoupRequestPS` created with
       // the `coin's private key <coin-priv>`.
       coin_sig: EddsaSignature;
 
+      // Coin's blinding factor.
+      coin_blind_key_secret: DenominationBlindingKeySecret;
+
     }
 
 
@@ -2588,12 +2615,17 @@ in using this API.
       // Signature over the `coin public key <eddsa-coin-pub>` by the denomination.
       denom_sig: DenominationSignature;
 
-      // Coin's blinding factor.
-      coin_blind_key_secret: DenominationBlindingKeySecret;
+      // Exchange-contributed values during the refresh
+      // operation (see /csr).
+      ewv: ExchangeWithdrawValue;
 
       // Signature of `TALER_RecoupRefreshRequestPS` created with
       // the `coin's private key <coin-priv>`.
       coin_sig: EddsaSignature;
+
+      // Coin's blinding factor.
+      coin_blind_key_secret: DenominationBlindingKeySecret;
+
     }