From 9bcd38bb77f935f9eaf83d86e2b1df900c11e563 Mon Sep 17 00:00:00 2001
From: Christian Grothoff <christian@grothoff.org>
Date: Sat, 15 Oct 2022 15:37:26 +0200
Subject: -work on p2p/reserve control API specs

---
 core/api-exchange.rst | 46 ++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 40 insertions(+), 6 deletions(-)

(limited to 'core/api-exchange.rst')

diff --git a/core/api-exchange.rst b/core/api-exchange.rst
index 17196f19..7fc86a2d 100644
--- a/core/api-exchange.rst
+++ b/core/api-exchange.rst
@@ -2364,7 +2364,8 @@ proof to the seller for the escrow of sufficient fund.
       | CoinOldCoinRecoupTransaction
       | CoinRecoupRefreshTransaction
       | CoinPurseDepositTransaction
-      | CoinPurseRefundTransaction;
+      | CoinPurseRefundTransaction
+      | CoinReserveOpenDepositTransaction;
 
 
   .. ts:def:: CoinDepositTransaction
@@ -2579,7 +2580,7 @@ proof to the seller for the escrow of sufficient fund.
  .. ts:def:: CoinPurseDepositTransaction
 
     interface CoinPurseDepositTransaction {
-      type: "PURSE_DEPOSIT";
+      type: "PURSE-DEPOSIT";
 
       // The total amount of the coin's value absorbed
       // by this transaction.
@@ -2613,7 +2614,7 @@ proof to the seller for the escrow of sufficient fund.
  .. ts:def:: CoinPurseRefundTransaction
 
     interface CoinPurseRefundTransaction {
-      type: "PURSE_REFUND";
+      type: "PURSE-REFUND";
 
       // The total amount of the coin's value restored
       // by this transaction.
@@ -2644,6 +2645,27 @@ proof to the seller for the escrow of sufficient fund.
 
     }
 
+ .. ts:def:: CoinReserveOpenDepositTransaction
+
+    interface CoinReserveOpenDepositTransaction {
+      type: "RESERVE-OPEN-DEPOSIT";
+
+      // The total amount of the coin's value absorbed
+      // by this transaction.
+      // Note that this means the amount given includes
+      // the deposit fee.
+      coin_contribution: Amount;
+
+      // Signature of the reserve open operation being paid for.
+      reserve_sig: EddsaSignature;
+
+      // Signature by the coin over a
+      // `TALER_ReserveOpenDepositSignaturePS` of
+      // purpose ``TALER_SIGNATURE_RESERVE_OPEN_DEPOSIT``.
+      coin_sig: EddsaSignature;
+
+    }
+
 
 .. http:POST:: /batch-deposit
 
@@ -4578,12 +4600,24 @@ naturally expire and possibly (5) wire the funds to a designated account.
   :http:statuscode:`200 OK`:
     The exchange responds with a `ReserveOpenResponse` object.
   :http:statuscode:`402 Payment Required`:
-    The exchange responds with a `ReserveOpenFailure` object.
+    The exchange responds with a `ReserveOpenFailure` object when
+    the payment offered is insufficient for the requested operation.
   :http:statuscode:`403 Forbidden`:
     The *TALER_SIGNATURE_WALLET_RESERVE_OPEN* signature is invalid.
     This response comes with a standard `ErrorDetail` response.
   :http:statuscode:`404 Not found`:
     The reserve key does not belong to a reserve known to the exchange.
+  :http:statuscode:`409 Conflict`:
+    The balance of the reserve or of a coin was insufficient.
+    Which case it is can be decided by looking at the error code
+    (``TALER_EC_EXCHANGE_GENERIC_INSUFFICIENT_FUNDS`` or
+    ``TALER_EC_EXCHANGE_GENERIC_COIN_CONFLICTING_DENOMINATION_KEY`` or
+    ``TALER_EC_EXCHANGE_OPEN_INSUFFICIENT_FUNDS``).
+    The specific fields of the response depend on the error code
+    and include the signatures (and what was signed over) proving the
+    conflict.
+    The response is `WithdrawError` object or a `DepositDoubleSpendError`
+    depending on the error type.
   :http:statuscode:`451 Unavailable For Legal Reasons`:
     This account has not yet passed the KYC checks.
     The client must pass KYC checks before the reserve can be opened.
@@ -4683,7 +4717,7 @@ naturally expire and possibly (5) wire the funds to a designated account.
     }
 
 
-.. http:get:: /reserves/$RESERVE_PUB/attest
+.. http:get:: /reserves-attest/$RESERVE_PUB
 
   Request list of available KYC attributes about the owner of a reserve.
   Used as a preliminary step to find out which subsets of attributes the
@@ -4710,7 +4744,7 @@ naturally expire and possibly (5) wire the funds to a designated account.
     }
 
 
-.. http:post:: /reserves/$RESERVE_PUB/attest
+.. http:post:: /reserves-attest/$RESERVE_PUB
 
   Request signed KYC information about the owner of a reserve.
   This can be used by a reserve owner to include a proof
-- 
cgit v1.2.3