[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[taler-docs] branch master updated: -specify batch-deposit endpoint
From: |
gnunet |
Subject: |
[taler-docs] branch master updated: -specify batch-deposit endpoint |
Date: |
Fri, 01 Jul 2022 19:20:17 +0200 |
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 9bfd2a5 -specify batch-deposit endpoint
9bfd2a5 is described below
commit 9bfd2a58a950feefed8a5ffe640b1a3c33a1e26b
Author: Christian Grothoff <grothoff@gnunet.org>
AuthorDate: Fri Jul 1 19:07:04 2022 +0200
-specify batch-deposit endpoint
---
core/api-exchange.rst | 141 ++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 141 insertions(+)
diff --git a/core/api-exchange.rst b/core/api-exchange.rst
index 0a18335..1223086 100644
--- a/core/api-exchange.rst
+++ b/core/api-exchange.rst
@@ -2441,6 +2441,147 @@ denomination.
}
+.. http:POST:: /batch-deposit
+
+ Deposit multiple coins and ask the exchange to transfer the given
:ref:`amount`
+ into the merchant's bank account. This API is used by the merchant to redeem
+ the digital coins.
+
+ **Request:**
+
+ The request body must be a `BatchDepositRequest` object.
+
+ **Response:**
+
+ :http:statuscode:`200 OK`:
+ The operation succeeded, the exchange confirms that no double-spending took
+ place. The response will include a `BatchDepositSuccess` object.
+ :http:statuscode:`403 Forbidden`:
+ One of the signatures is invalid.
+ This response comes with a standard `ErrorDetail` response.
+ :http:statuscode:`404 Not found`:
+ Either one of the denomination keys is not recognized (expired or invalid),
+ or the wire type is not recognized.
+ If a denomination key is unknown, the response will be
+ a `DenominationUnknownMessage`.
+ :http:statuscode:`409 Conflict`:
+ The deposit operation has either failed because a coin has insufficient
+ residual value, or because the same public key of a coin has been
+ previously used with a different denomination. 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``).
+ The fields of the response are the same in both cases.
+ The request should not be repeated again with this coin.
+ In this case, the response is a `DepositDoubleSpendError` with
+ an additional `coin_pub` field specifying the public key of the
+ coin that was double-spent.
+ :http:statuscode:`410 Gone`:
+ The 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.
+
+ **Details:**
+
+ .. ts:def:: BatchDepositRequest
+
+ interface DepositRequest {
+
+ // The merchant's account details.
+ merchant_payto_uri: string;
+
+ // The salt is used to hide the ``payto_uri`` from customers
+ // when computing the ``h_wire`` of the merchant.
+ wire_salt: WireSalt;
+
+ // SHA-512 hash of the contract of the merchant with the customer.
Further
+ // details are never disclosed to the exchange.
+ h_contract_terms: HashCode;
+
+ // Timestamp when the contract was finalized.
+ timestamp: Timestamp;
+
+ // Indicative time by which the exchange undertakes to transfer the
funds to
+ // the merchant, in case of successful payment. A wire transfer deadline
of 'never'
+ // is not allowed.
+ wire_transfer_deadline: Timestamp;
+
+ // EdDSA `public key of the merchant <merchant-pub>`, so that the client
can identify the
+ // merchant for refund requests.
+ merchant_pub: EddsaPublicKey;
+
+ // Date until which the merchant can issue a refund to the customer via
the
+ // exchange, to be omitted if refunds are not allowed.
+ refund_deadline?: Timestamp;
+ }
+
+ .. ts:def:: DepositRequest
+
+ interface DepositRequest {
+ // EdDSA public key of the coin being deposited.
+ coin_pub: EddsaPublicKey;
+
+ // Hash of denomination RSA key with which the coin is signed.
+ denom_pub_hash: HashCode;
+
+ // Exchange's unblinded RSA signature of the coin.
+ ub_sig: DenominationSignature;
+
+ // Amount to be deposited, can be a fraction of the
+ // coin's total value.
+ contribution: Amount;
+
+ // Signature over `TALER_DepositRequestPS`, made by the customer with the
+ // `coin's private key <coin-priv>`.
+ coin_sig: EddsaSignature;
+ }
+
+ The deposit operation succeeds if the coin is valid for making a deposit and
+ has enough residual value that has not already been deposited or melted.
+
+ .. ts:def:: BatchDepositSuccess
+
+ interface BatchDepositSuccess {
+ // Optional base URL of the exchange for looking up wire transfers
+ // associated with this transaction. If not given,
+ // the base URL is the same as the one used for this request.
+ // Can be used if the base URL for ``/transactions/`` differs from that
+ // for ``/coins/``, i.e. for load balancing. Clients SHOULD
+ // respect the ``transaction_base_url`` if provided. Any HTTP server
+ // belonging to an exchange MUST generate a 307 or 308 redirection
+ // to the correct base URL should a client uses the wrong base
+ // URL, or if the base URL has changed since the deposit.
+ transaction_base_url?: string;
+
+ // Timestamp when the deposit was received by the exchange.
+ exchange_timestamp: Timestamp;
+
+ // `Public EdDSA key of the exchange <sign-key-pub>` that was used to
+ // generate the signature.
+ // Should match one of the exchange's signing keys from ``/keys``. It
is given
+ // explicitly as the client might otherwise be confused by clock skew as
to
+ // which signing key was used.
+ exchange_pub: EddsaPublicKey;
+
+ // Array of deposit confirmation signatures from the exchange
+ // Entries must be in the same order the coins were given
+ // in the batch deposit request.
+ exchange_sigs[]: DepositConfirmationSignature;
+ }
+
+ .. ts:def:: DepositConfirmationSignature
+
+ interface DepositConfirmationSignature {
+ // The EdDSA signature of `TALER_DepositConfirmationPS` using a current
+ // `signing key of the exchange <sign-key-priv>` affirming the successful
+ // deposit and that the exchange will transfer the funds after the refund
+ // deadline, or as soon as possible if the refund deadline is zero.
+ exchange_sig: EddsaSignature;
+ }
+
+
----------
Refreshing
----------
--
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [taler-docs] branch master updated: -specify batch-deposit endpoint,
gnunet <=