From 9bfd2a58a950feefed8a5ffe640b1a3c33a1e26b Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Fri, 1 Jul 2022 19:07:04 +0200 Subject: -specify batch-deposit endpoint --- core/api-exchange.rst | 141 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 141 insertions(+) (limited to 'core/api-exchange.rst') diff --git a/core/api-exchange.rst b/core/api-exchange.rst index 0a18335c..1223086d 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 `, 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_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 ` 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 ` 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 ---------- -- cgit v1.2.3