taler-docs

commit 0a606a7fd226069769a9bcc02657ba1e1b2c3be9
parent a56ad32ef8f5cb5ad558cd9a8a45b842642f2e4b
Author: Christian Grothoff <christian@grothoff.org>
Date:   Sun,  5 Jun 2022 00:42:54 +0200

use 451 if KYC is required, make EncryptedContract its own object

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

1 file changed, 40 insertions(+), 38 deletions(-)
diff --git a/core/api-exchange.rst b/core/api-exchange.rst
@@ -1623,25 +1623,6 @@ exchange.
     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:`202 Accepted`:
-    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 `KycNeededRedirect` object.
-
-    Implementation note: internally, we need to
-    distinguish between upgrading the reserve to an
-    account (due to P2P payment) and identifying the
-    owner of the origin bank account (due to exceeding
-    the withdraw amount threshold), as we need to create
-    a different payto://-URI for the KYC check depending
-    on the case.
-
   :http:statuscode:`403 Forbidden`:
     The signature is invalid.
   :http:statuscode:`404 Not found`:
@@ -1663,6 +1644,25 @@ exchange.
     `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 `KycNeededRedirect` object.
+
+    Implementation note: internally, we need to
+    distinguish between upgrading the reserve to an
+    account (due to P2P payment) and identifying the
+    owner of the origin bank account (due to exceeding
+    the withdraw amount threshold), as we need to create
+    a different payto://-URI for the KYC check depending
+    on the case.
+
 
   **Details:**
 
@@ -3240,13 +3240,7 @@ Wallet-to-wallet transfers
       // Optional encrypted contract, in case the buyer is
       // proposing the contract and thus establishing the
       // purse with the payment.
-      econtract?: string;
-
-      // Signature over the contract.
-      econtract_sig?: EddsaSignature;
-
-      // Ephemeral public key for the DH operation to decrypt the contract.
-      contract_pub?: EddsaPublicKey;
+      econtract?: EncryptedContract;
 
       // EdDSA public key used to approve merges of this purse.
       merge_pub: EddsaPublicKey;
@@ -3273,6 +3267,21 @@ Wallet-to-wallet transfers
 
     }
 
+  .. ts:def:: EncryptedContract
+
+    interface EncryptedContract {
+
+      // Encrypted contract.
+      econtract: string;
+
+      // Signature over the (encrypted) contract.
+      econtract_sig: EddsaSignature;
+
+      // Ephemeral public key for the DH operation to decrypt the encrypted contract.
+      contract_pub: EddsaPublicKey;
+
+    }
+
   .. ts:def:: PurseDeposit
 
     interface PurseDeposit {
@@ -3394,17 +3403,16 @@ Wallet-to-wallet transfers
     interface PurseContractConflict {
       code: TALER_EC_EXCHANGE_PURSE_ECONTRACT_CONFLICTING_META_DATA;
 
-      // Encrypted contract.
-      econtract: string;
+      // Hash of the encrypted contract.
+      h_econtract: HashCode;
 
       // Signature over the contract.
       econtract_sig: EddsaSignature;
 
       // Ephemeral public key for the DH operation to decrypt the contract.
-      pub_ckey: EddsaPublicKey;
-    }
-
+      contract_pub: EddsaPublicKey;
 
+    }
 
 
 .. http:POST:: /purses/$PURSE_PUB/merge
@@ -3578,13 +3586,7 @@ Wallet-to-wallet transfers
       // Optional encrypted contract, in case the buyer is
       // proposing the contract and thus establishing the
       // purse with the payment.
-      econtract?: string;
-
-      // Signature over the contract.
-      econtract_sig?: EddsaSignature;
-
-      // Ephemeral public key for the DH operation to decrypt the contract.
-      contract_pub?: EddsaPublicKey;
+      econtract?: EncryptedContract;
 
       // EdDSA public key used to approve merges of this purse.
       merge_pub: EddsaPublicKey;