document batch-withdraw endpoint

1 files changed, 85 insertions, 0 deletions

diff --git a/core/api-exchange.rst b/core/api-exchange.rst
index 22d7bd48..b6d6f8d7 100644
--- a/core/api-exchange.rst
+++ b/core/api-exchange.rst
@@ -1625,6 +1625,7 @@ exchange.
     coin is not lost.
   :http:statuscode:`403 Forbidden`:
     The signature is invalid.
+    This response comes with a standard `ErrorDetail` response.
   :http:statuscode:`404 Not found`:
     The denomination key or the reserve are not known to the exchange.  If the
     denomination key is unknown, this suggests a bug in the wallet as the
@@ -1781,12 +1782,96 @@ exchange.
       history: TransactionHistoryItem[]
     }
 
+
+
+
+.. http:post:: /reserves/$RESERVE_PUB/batch-withdraw
+
+  Withdraw multiple coins from the same reserve.  Note that the client should
+  commit all of the request details, including the private key of the coins and
+  the blinding factors, to disk *before* issuing this request, so that it can
+  recover the information if necessary in case of transient failures, like
+  power outage, network outage, etc.
+
+  **Request:** The request body must be a `BatchWithdrawRequest` object.
+
+  **Response:**
+
+  :http:statuscode:`200 OK`:
+    The request was successful, and the response is a `BatchWithdrawResponse`.
+    Note that repeating exactly the same request
+    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:`403 Forbidden`:
+    A signature is invalid.
+    This response comes with a standard `ErrorDetail` response.
+  :http:statuscode:`404 Not found`:
+    A denomination key or the reserve are not known to the exchange.  If the
+    denomination key is unknown, this suggests a bug in the wallet as the
+    wallet should have used current denomination keys from ``/keys``.
+    In this case, the response will be a `DenominationUnknownMessage`.
+    If the reserve is unknown, the wallet should not report a hard error yet, but
+    instead simply wait for up to a day, as the wire transaction might simply
+    not yet have completed and might be known to the exchange in the near future.
+    In this case, the wallet should repeat the exact same request later again
+    using exactly the same blinded coin.
+  :http:statuscode:`409 Conflict`:
+    The balance of the reserve is not sufficient to withdraw the coins of the indicated denominations.
+    The response is `WithdrawError` object.
+  :http:statuscode:`410 Gone`:
+    A requested denomination key is not yet or no longer valid.
+    It either before the validity start, past the expiration or was revoked. The response is a
+    `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:**
+
+  .. ts:def:: BatchWithdrawRequest
+
+    interface BatchWithdrawRequest {
+      // Array of requests for the individual coins to withdraw.
+      planchets: WithdrawRequest[];
+
+    }
+
+  .. ts:def:: BatchWithdrawResponse
+
+    interface BatchWithdrawResponse {
+      // Array of blinded signatures, in the same order as was
+      // given in the request.
+      ev_sigs: WithdrawResponse[];
+
+    }
+
+
 .. _delete-reserve:
 
 .. http:DELETE:: /reserves/$RESERVE_PUB
 
   Forcefully closes a reserve.
   The request header must contain an *Account-Request-Signature*.
+  Note: this endpoint is not currently implemented!
 
   **Request:**