[taler-docs] branch master updated: use 451 if KYC is required, make EncryptedContract its own object

[gnunet]

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

grothoff pushed a commit to branch master
in repository docs.

The following commit(s) were added to refs/heads/master by this push:
     new 0a606a7  use 451 if KYC is required, make EncryptedContract its own 
object
0a606a7 is described below

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

    use 451 if KYC is required, make EncryptedContract its own object
---
 core/api-exchange.rst | 78 ++++++++++++++++++++++++++-------------------------
 1 file changed, 40 insertions(+), 38 deletions(-)

diff --git a/core/api-exchange.rst b/core/api-exchange.rst
index 50f7579..0a21f43 100644
--- 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;

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