[taler-docs] branch master updated: remove legacy single-coin deposit API, add new coin history API

[gnunet]

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 6b6ccd40 remove legacy single-coin deposit API, add new coin history 
API
6b6ccd40 is described below

commit 6b6ccd40ba6a197d4172a0fd5c19fcb32c1a3a8e
Author: Christian Grothoff <christian@grothoff.org>
AuthorDate: Sun Sep 17 12:21:48 2023 +0200

    remove legacy single-coin deposit API, add new coin history API
---
 .gitignore            |   1 +
 core/api-exchange.rst | 562 ++++++++++++++++++++------------------------------
 2 files changed, 228 insertions(+), 335 deletions(-)

diff --git a/.gitignore b/.gitignore
index 1015d1cc..3894837d 100644
--- a/.gitignore
+++ b/.gitignore
@@ -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

-- 
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.