diff options
author | Christian Grothoff <christian@grothoff.org> | 2023-09-17 12:21:48 +0200 |
---|---|---|
committer | Christian Grothoff <christian@grothoff.org> | 2023-09-17 12:21:53 +0200 |
commit | 6b6ccd40ba6a197d4172a0fd5c19fcb32c1a3a8e (patch) | |
tree | 0f098a1af6e462a4363b6cb4d39180775715cee1 | |
parent | 53860c38cd349fcf541410f25af36b2d6ef04d58 (diff) | |
download | docs-6b6ccd40ba6a197d4172a0fd5c19fcb32c1a3a8e.tar.gz docs-6b6ccd40ba6a197d4172a0fd5c19fcb32c1a3a8e.tar.bz2 docs-6b6ccd40ba6a197d4172a0fd5c19fcb32c1a3a8e.zip |
remove legacy single-coin deposit API, add new coin history API
-rw-r--r-- | .gitignore | 1 | ||||
-rw-r--r-- | core/api-exchange.rst | 562 |
2 files changed, 228 insertions, 335 deletions
@@ -10,3 +10,4 @@ images/arch-api.png images/coin.png images/deposit.png images/reserve.png +*.png diff --git a/core/api-exchange.rst b/core/api-exchange.rst index b5559f5a..71a15454 100644 --- a/core/api-exchange.rst +++ b/core/api-exchange.rst @@ -2634,354 +2634,39 @@ If so, the exchange will blindly sign ``n`` undisclosed coins from the request. } -.. _deposit-par: - -------- -Deposit -------- - -Deposit operations are requested f.e. by a merchant during a transaction or a -bidder during an auction. - -For the deposit operation during purchase, the merchant has to obtain the -deposit permission for a coin from their customer who owns the coin. When -depositing a coin, the merchant is credited an amount specified in the deposit -permission, possibly a fraction of the total coin's value, minus the deposit -fee as specified by the coin's denomination. - -For auctions, a bidder performs an deposit operation and provides all relevant -information for the auction policy (such as timeout and public key as bidder) -and can use the ``exchange_sig`` field from the `DepositSuccess` message as a -proof to the seller for the escrow of sufficient fund. - +.. _coin-history: -.. _deposit: - -.. http:POST:: /coins/$COIN_PUB/deposit +------------ +Coin History +------------ - Deposit the given coin and ask the exchange to transfer the given :ref:`amount` - to the merchant's bank account. This API is used by the merchant to redeem - the digital coins. +.. http:GET:: /coins/$COIN_PUB - The base URL for ``/coins/``-requests may differ from the main base URL of the - exchange. The exchange MUST return a 307 or 308 redirection to the correct - base URL if this is the case. + Obtain the transaction history of a coin. Used only in special cases, like + when the exchange claims a double-spending error and the wallet does not + believe it. Usually, the wallet knows the transaction history of each coin + and thus has no need to inquire. **Request:** - The request body must be a `DepositRequest` object. + If possible, clients should set an "If-none-match" HTTP header based on a + previous "Etag" returned by the exchange. **Response:** :http:statuscode:`200 OK`: The operation succeeded, the exchange confirms that no double-spending took - place. The response will include a `DepositSuccess` object. - :http:statuscode:`403 Forbidden`: - One of the signatures is invalid. - This response comes with a standard `ErrorDetail` response. + place. The response will include a `CoinHistoryResponse` object. + :http:statuscode:`304 Not modified`: + The coin history has not changed since the previous query (detected via Etag + in "If-none-match" header). :http:statuscode:`404 Not found`: - Either the denomination key is not recognized (expired or invalid), - or the wire type is not recognized. - If the denomination key is unknown, the response will be - a `DenominationUnknownMessage`. - :http:statuscode:`409 Conflict`: - The deposit operation has either failed because the coin has insufficient - residual value, or because the same public key of the coin has been - previously used with a different denomination. It is also a conflict - to use the same coin multiple times (with different amounts) for the - same contract. Which case it is - can be decided by looking at the error code - (``TALER_EC_EXCHANGE_DEPOSIT_CONFLICTING_CONTRACT`` (same coin used in different ways), - ``TALER_EC_EXCHANGE_GENERIC_INSUFFICIENT_FUNDS`` (balance insufficient) or - ``TALER_EC_EXCHANGE_GENERIC_COIN_CONFLICTING_DENOMINATION_KEY`` - (same coin public key, but different denomination)). - The fields of the response are still evolving (see bug 7267), - for now the format of the response is a `DepositDoubleSpendError`. - The request should not be repeated again with this coin. - :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:: DepositRequest - - interface DepositRequest { - // Amount to be deposited, can be a fraction of the - // coin's total value. - contribution: Amount; - - // The merchant's account details. - // In case of an auction policy, it refers to the seller. - 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; - - // Hash of denomination RSA key with which the coin is signed. - denom_pub_hash: HashCode; - - // IFF the corresponding denomination has support for - // age restriction enabled, this field MUST contain the SHA256 - // value of the age commitment that MUST have been provided during the - // purchase. - age_commitment_hash?: AgeCommitmentHash; - - // Exchange's unblinded RSA signature of the coin. - ub_sig: DenominationSignature; - - // 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. - // - // THIS FIELD WILL BE DEPRICATED, once the refund mechanism becomes a - // policy via extension. - 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. - // - // THIS FIELD WILL BE DEPRICATED, once the refund mechanism becomes a - // policy via extension. - refund_deadline?: Timestamp; - - // CAVEAT: THIS IS WORK IN PROGRESS - // (Optional) policy for the deposit. - // This might be a refund, auction or escrow policy. - // - // Note that support for policies is an optional feature of the exchange. - // Optional features are so called "extensions" in Taler. The exchange - // provides the list of supported extensions, including policies, in the - // `ExtensionsManifestsResponse` response to the ``/keys`` endpoint. - policy?: DepositPolicy; - - // Signature over `TALER_DepositRequestPS`, made by the customer with the - // `coin's private key <coin-priv>`. - coin_sig: EddsaSignature; - } - - .. ts:def:: DenominationSignature - - type DenominationSignature = - | RsaDenominationSignature - | CSDenominationSignature; - - .. ts:def:: RsaDenominationSignature - - interface RsaDenominationSignature { - cipher: "RSA"; - - // RSA signature - rsa_signature: RsaSignature; - } - - .. ts:def:: CSDenominationSignature - - interface CSDenominationSignature { - type: "CS"; - - // R value component of the signature. - cs_signature_r: Cs25519Point; - - // s value component of the signature. - cs_signature_s: Cs25519Scalar: - - } - - .. ts:def:: DepositPolicy - - type DepositPolicy = - | PolicyMerchantRefund - | PolicyBrandtVickreyAuction - | PolicyEscrowedPayment; - - .. ts:def:: PolicyMerchantRefund - - // CAVEAT: THIS IS STILL WORK IN PROGRESS. - // This policy is optional and might not be supported by the exchange. - // If it does, the exchange MUST show support for this policy in the - // ``extensions`` field in the response to ``/keys``. - interface PolicyMerchantRefund { - type: "merchant_refund"; - - // 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 ``/extensions/policy_refund``-endpoint of the exchange. - deadline: Timestamp; - } - - .. ts:def:: PolicyBrandtVickreyAuction - - // CAVEAT: THIS IS STILL WORK IN PROGRESS. - // This policy is optional and might not be supported by the exchange. - // If it does, the exchange MUST show support for this policy in the - // ``extensions`` field in the response to ``/keys``. - interface PolicyBrandtVickreyAuction { - type: "brandt_vickrey_auction"; - - // Public key of this bidder. - // - // The bidder uses this key to sign the auction information and - // the messages it sends to the seller during the auction. - bidder_pub: EddsaPublicKey; - - // Hash of the auction terms - // - // The hash should be taken over a normalized JSON object of type - // `BrandtVickreyAuction`. - h_auction: HashCode; - - // The amount that this bidder commits to for this auction - // - // This amount can be larger than the contribution of a single coin. - // The bidder can increase funding of this auction policy by using - // sufficiently many coins during the deposit operation (single or batch) - // with the same policy. - commitment: Amount; - - // Date until the auction must have been successfully executed and - // a valid transcript provided to the - // ``/extensions/policy_brandt_vickrey_auction``-endpoint of the - // exchange. - // - // [If the auction has not been executed by then] OR [has been executed - // before then, but this bidder did not win], the coin's value doesn't - // change and the owner can refresh the coin. - // - // If this bidder won the auction, the winning price/amount from the - // outcome will be substracted from the coin and transfered to the - // merchant's ``payout_uri`` from the deposit request (minus a potential - // auction fee). For any remaining value, the bidder can refresh the - // coin to retrieve change. - deadline: Timestamp; - } - - .. ts:def:: BrandtVickreyAuction - - // CAVEAT: THIS IS STILL WORK IN PROGRESS. - // This structure defines an auction of Brandt-Vickory kind. - // It is used for the `PolicyBrandtVickreyAuction`. - interface BrandtVickreyAuction { - // Start date of the auction - time_start: Timestamp; - - // Maximum duration per round. There are four rounds in an auction of - // Brandt-Vickrey kind. - time_round: RelativeTime; - - // This integer m refers to the (m+1)-type of the Brandt-Vickrey-auction. - // - Type 0 refers to an auction with one highest-price winner, - // - Type 1 refers to an auction with one winner, paying the second - // highest price, - // - Type 2 refers to an auction with two winners, paying - // the third-highest price, - // - etc. - auction_type: number; - - // The vector of prices for the Brandt-Vickrey auction. The values MUST - // be in strictly increasing order. - prices: Amount[]; - - // The type of outcome of the auction. - // In case the auction is declared public, each bidder can calculate the - // winning price. This field is not relevant for the replay of a - // transcript, as the transcript must be provided by the seller who sees - // the winner(s) and winning price of the auction. - outcome_public: boolean; - - // The public key of the seller. - pubkey: EddsaPublicKey; - - // The seller's account details. - payto_uri: string; - } - - - .. ts:def:: PolicyEscrowedPayment - - // CAVEAT: THIS IS STILL WORK IN PROGRESS - // This policy is optional and might not be supported by the exchange. - // If it does, the exchange MUST show support for this policy in the - // ``extensions`` field in the response to ``/keys``. - interface PolicyEscrowedPayment { - type: "escrowed_payment"; - - // Public key of this trustor, the owner of the coins. - // - // To claim the deposit, the merchant must provide the valid signature - // of the ``h_contract_terms`` field from the deposit, signed by _this_ - // key, to the ``/extensions/policy_escrow``-endpoint of the exchange, - // after the date specified in ``not_before`` and before the date - // specified in ``not_after``. - trustor_pub: EddsaPublicKey; - - // Latest date by which the deposit must be claimed. If the deposit - // has not been claimed by that date, the deposited coins can be - // refreshed by the (still) owner. - deadline: Timestamp; - } - - - 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:: DepositSuccess - - interface DepositSuccess { - // 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; - - // 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; - - // `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; - } - - .. ts:def:: DepositDoubleSpendError + The coin public key is not (yet) known to the exchange. - interface DepositDoubleSpendError { - // The string constant "insufficient funds". - hint: string; + .. ts:def:: CoinHistoryResponse - // Transaction history for the coin that is - // being double-spended. + interface CoinHistoryResponse { + // Transaction history for the coin. history: CoinSpendHistoryItem[]; } @@ -2999,7 +2684,6 @@ proof to the seller for the escrow of sufficient fund. | CoinPurseRefundTransaction | CoinReserveOpenDepositTransaction; - .. ts:def:: CoinDepositTransaction interface CoinDepositTransaction { @@ -3294,6 +2978,29 @@ proof to the seller for the escrow of sufficient fund. } +.. _deposit-par: + +------- +Deposit +------- + +Deposit operations are requested f.e. by a merchant during a transaction or a +bidder during an auction. + +For the deposit operation during purchase, the merchant has to obtain the +deposit permission for a coin from their customer who owns the coin. When +depositing a coin, the merchant is credited an amount specified in the deposit +permission, possibly a fraction of the total coin's value, minus the deposit +fee as specified by the coin's denomination. + +For auctions, a bidder performs an deposit operation and provides all relevant +information for the auction policy (such as timeout and public key as bidder) +and can use the ``exchange_sig`` field from the `DepositSuccess` message as a +proof to the seller for the escrow of sufficient fund. + + +.. _deposit: + .. http:POST:: /batch-deposit Deposit multiple coins and ask the exchange to transfer the given :ref:`amount` @@ -3403,6 +3110,170 @@ proof to the seller for the escrow of sufficient fund. coin_sig: EddsaSignature; } + .. ts:def:: DenominationSignature + + type DenominationSignature = + | RsaDenominationSignature + | CSDenominationSignature; + + .. ts:def:: RsaDenominationSignature + + interface RsaDenominationSignature { + cipher: "RSA"; + + // RSA signature + rsa_signature: RsaSignature; + } + + .. ts:def:: CSDenominationSignature + + interface CSDenominationSignature { + type: "CS"; + + // R value component of the signature. + cs_signature_r: Cs25519Point; + + // s value component of the signature. + cs_signature_s: Cs25519Scalar: + + } + + .. ts:def:: DepositPolicy + + type DepositPolicy = + | PolicyMerchantRefund + | PolicyBrandtVickreyAuction + | PolicyEscrowedPayment; + + .. ts:def:: PolicyMerchantRefund + + // CAVEAT: THIS IS STILL WORK IN PROGRESS. + // This policy is optional and might not be supported by the exchange. + // If it does, the exchange MUST show support for this policy in the + // ``extensions`` field in the response to ``/keys``. + interface PolicyMerchantRefund { + type: "merchant_refund"; + + // 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 ``/extensions/policy_refund``-endpoint of the exchange. + deadline: Timestamp; + } + + .. ts:def:: PolicyBrandtVickreyAuction + + // CAVEAT: THIS IS STILL WORK IN PROGRESS. + // This policy is optional and might not be supported by the exchange. + // If it does, the exchange MUST show support for this policy in the + // ``extensions`` field in the response to ``/keys``. + interface PolicyBrandtVickreyAuction { + type: "brandt_vickrey_auction"; + + // Public key of this bidder. + // + // The bidder uses this key to sign the auction information and + // the messages it sends to the seller during the auction. + bidder_pub: EddsaPublicKey; + + // Hash of the auction terms + // + // The hash should be taken over a normalized JSON object of type + // `BrandtVickreyAuction`. + h_auction: HashCode; + + // The amount that this bidder commits to for this auction + // + // This amount can be larger than the contribution of a single coin. + // The bidder can increase funding of this auction policy by using + // sufficiently many coins during the deposit operation (single or batch) + // with the same policy. + commitment: Amount; + + // Date until the auction must have been successfully executed and + // a valid transcript provided to the + // ``/extensions/policy_brandt_vickrey_auction``-endpoint of the + // exchange. + // + // [If the auction has not been executed by then] OR [has been executed + // before then, but this bidder did not win], the coin's value doesn't + // change and the owner can refresh the coin. + // + // If this bidder won the auction, the winning price/amount from the + // outcome will be substracted from the coin and transfered to the + // merchant's ``payout_uri`` from the deposit request (minus a potential + // auction fee). For any remaining value, the bidder can refresh the + // coin to retrieve change. + deadline: Timestamp; + } + + .. ts:def:: BrandtVickreyAuction + + // CAVEAT: THIS IS STILL WORK IN PROGRESS. + // This structure defines an auction of Brandt-Vickory kind. + // It is used for the `PolicyBrandtVickreyAuction`. + interface BrandtVickreyAuction { + // Start date of the auction + time_start: Timestamp; + + // Maximum duration per round. There are four rounds in an auction of + // Brandt-Vickrey kind. + time_round: RelativeTime; + + // This integer m refers to the (m+1)-type of the Brandt-Vickrey-auction. + // - Type 0 refers to an auction with one highest-price winner, + // - Type 1 refers to an auction with one winner, paying the second + // highest price, + // - Type 2 refers to an auction with two winners, paying + // the third-highest price, + // - etc. + auction_type: number; + + // The vector of prices for the Brandt-Vickrey auction. The values MUST + // be in strictly increasing order. + prices: Amount[]; + + // The type of outcome of the auction. + // In case the auction is declared public, each bidder can calculate the + // winning price. This field is not relevant for the replay of a + // transcript, as the transcript must be provided by the seller who sees + // the winner(s) and winning price of the auction. + outcome_public: boolean; + + // The public key of the seller. + pubkey: EddsaPublicKey; + + // The seller's account details. + payto_uri: string; + } + + + .. ts:def:: PolicyEscrowedPayment + + // CAVEAT: THIS IS STILL WORK IN PROGRESS + // This policy is optional and might not be supported by the exchange. + // If it does, the exchange MUST show support for this policy in the + // ``extensions`` field in the response to ``/keys``. + interface PolicyEscrowedPayment { + type: "escrowed_payment"; + + // Public key of this trustor, the owner of the coins. + // + // To claim the deposit, the merchant must provide the valid signature + // of the ``h_contract_terms`` field from the deposit, signed by _this_ + // key, to the ``/extensions/policy_escrow``-endpoint of the exchange, + // after the date specified in ``not_before`` and before the date + // specified in ``not_after``. + trustor_pub: EddsaPublicKey; + + // Latest date by which the deposit must be claimed. If the deposit + // has not been claimed by that date, the deposited coins can be + // refreshed by the (still) owner. + deadline: Timestamp; + } + 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. @@ -3446,6 +3317,27 @@ proof to the seller for the escrow of sufficient fund. exchange_sig: EddsaSignature; } + .. ts:def:: DepositDoubleSpendError + + interface DepositDoubleSpendError { + + // Must be TALER_EC_EXCHANGE_GENERIC_INSUFFICIENT_FUNDS + code: Integer; + + // A string explaining that the user tried to + // double-spend. + hint: string; + + // EdDSA public key of a coin being double-spent. + coin_pub: EddsaPublicKey; + + // Transaction history for the coin that is + // being double-spended. + // DEPRECATED! Will be removed soon. Use + // GET /coins/$COIN_PUB to get the history! + history: CoinSpendHistoryItem[]; + } + ---------- Refreshing |