[taler-docs] 01/02: -work on p2p docs

[gnunet]

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

grothoff pushed a commit to branch master
in repository docs.

commit 319cbc562b6b4627e4ec5ac23d8cb8a059d33409
Author: Christian Grothoff <christian@grothoff.org>
AuthorDate: Thu Jun 2 11:20:42 2022 +0200

    -work on p2p docs
---
 core/api-exchange.rst | 84 ++++++++++++++++++---------------------------------
 1 file changed, 29 insertions(+), 55 deletions(-)

diff --git a/core/api-exchange.rst b/core/api-exchange.rst
index b55fb6b..0a1a1f8 100644
--- a/core/api-exchange.rst
+++ b/core/api-exchange.rst
@@ -1121,7 +1121,7 @@ exchange.
       balance: Amount;
     }
 
-    
+
 .. http:post:: /reserves/$RESERVE_PUB/status
 
   Request information about a reserve or an account.
@@ -2990,23 +2990,16 @@ Refunds
 Wallet-to-wallet transfers
 --------------------------
 
-  .. note::
-
-     This is a draft API that is not yet implemented.
-
+.. http:GET:: /purses/$PURSE_PUB/merge
+.. http:GET:: /purses/$PURSE_PUB/deposit
 
-.. http:GET:: /purses/$PURSE_PUB
-
-  Obtain information about a purse. The request header must
-  contain a *Purse-Request-Signature*.  Endpoint used by
-  the party that did not create the purse.
-  TODO: maybe use POST to /purses/$PURSE_PUB/status instead?
+  Obtain information about a purse.  Depending on the suffix,
+  the long-polling (if any) will wait for either a merge or
+  a deposit event.
 
   **Request:**
 
-  *Purse-Request-Signature*: The client must provide Base-32 encoded EdDSA 
signature made with ``$PURSE_PRIV``, affirming its authorization to download 
the purse status.  The purpose used MUST be 
``TALER_SIGNATURE_PURSE_STATUS_REQUEST``.
-
-  :query merge_timeout_ms=NUMBER: *Optional.*  If specified,
+  :query timeout_ms=NUMBER: *Optional.*  If specified,
     the exchange
     will wait up to ``NUMBER`` milliseconds for completion
     of a merge operation before sending the HTTP response.
@@ -3014,9 +3007,6 @@ Wallet-to-wallet transfers
     the exchange
     will wait up to ``NUMBER`` milliseconds for completion
     of a deposit operation before sending the HTTP response.
-  :query contract=BOOLEAN: *Optional.*  If 'false' is specified,
-    the exchange will not return the encrypted contract, saving
-    bandwidth for clients that already know it.
 
   **Response:**
 
@@ -3024,11 +3014,10 @@ Wallet-to-wallet transfers
     The operation succeeded, the exchange provides details
     about the purse.
     The response will include a `PurseStatus` object.
-  :http:statuscode:`401 Unauthorized`:
-    The *Purse-Request-Signature* is invalid.
-    This response comes with a standard `ErrorDetail` response.
   :http:statuscode:`404 Not found`:
     The purse is unknown to the exchange.
+  :http:statuscode:`410 Gone`:
+    The purse expired before the deposit or merge was completed.
 
   **Details:**
 
@@ -3041,26 +3030,18 @@ Wallet-to-wallet transfers
       // exceeds 'merge_value_after_fees', and a
       // 'merge_request' exists for the purse, then the
       // purse will (have been) merged with the account.
-      total_deposit_amount: Amount;
-
-      // Indicative time by which the purse expires
-      // if it has not been merged into an account. At this
-      // point, all of the deposits made will be auto-refunded.
-      purse_expiration: Timestamp;
-
-      // Desired total amount to be merged into the reserve.
-      // (excludes fees).
-      merge_value_after_fees: Amount;
-
-      // Indicative time at which the exchange is answering the
-      // status request.  Used as part of 'exchange_sig'.
-      status_timestamp: Timestamp;
+      balance: Amount;
 
-      // Deposit fees charged so far to all deposited coins.
-      deposit_fees: Amount;
+      // Time of the merge, possibly "never".
+      merge_timestamp: Timestamp;
 
-      // SHA-512 hash of the contact of the purse.
-      h_contract_terms: HashCode;
+      // Time of the deposits being complete, possibly "never".
+      // Note that this time may not be "stable": once sufficient
+      // deposits have been made, is "now" before the purse
+      // expiration, and otherwise set to the purse expiration.
+      // However, this should also not be relied upon. The key
+      // property is that it is either "never" or in the past.
+      merge_timestamp: Timestamp;
 
       // EdDSA signature of the exchange over a
       // `TALER_PurseStatusResponseSignaturePS`
@@ -3071,19 +3052,6 @@ Wallet-to-wallet transfers
       // EdDSA public key exchange used for 'exchange_sig'.
       exchange_pub: EddsaPublicKey;
 
-      // EdDSA public key used to approve merges of this purse.
-      merge_pub: EddsaPublicKey;
-
-      // AES-GCM Encrypted contract terms using encryption
-      // key derived from DH of 'contract_pub' and the 'purse_pub'.
-      // Optional, may be omitted if not desired by the client.
-      e_contract_terms?: string;
-
-      // If a merge request was received, information about the
-      // merge request. Omitted if the purse has not yet received
-      // a merge request.
-      merge_request?: MergeRequest;
-
     }
 
 
@@ -3145,6 +3113,12 @@ Wallet-to-wallet transfers
 
     interface PurseRequest {
 
+      // Array of coins to deposit into the purse.
+      deposits: PurseDeposit[];
+    }
+
+    interface PurseDeposit {
+
       // EdDSA signature of the purse over a
       // `TALER_PurseRequestSignaturePS`
       // of purpose ``TALER_SIGNATURE_WALLET_PURSE_CREATE``
@@ -3168,7 +3142,7 @@ Wallet-to-wallet transfers
 
       // Minimum age of deposits made into the purse
       minimum_age: Integer;
-      
+
       // Indicative time by which the purse should expire
       // if it has not been merged into an account. At this
       // point, all of the deposits made will be auto-refunded.
@@ -3465,7 +3439,7 @@ Wallet-to-wallet transfers
   .. ts:def:: MergeAccepted
 
     interface MergeAccepted {
-    
+
       // Current balance in the purse.
       balance: Amount;
 
@@ -3542,9 +3516,9 @@ Wallet-to-wallet transfers
 
     }
 
-    
+
 -- TODO: API to deposit into existing purse
-    
+
 
 .. _exchange_wads:
 

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