[taler-docs] branch master updated: added definitions of policies for deposits

[gnunet]

This is an automated email from the git hooks/post-receive script.

oec pushed a commit to branch master
in repository docs.

The following commit(s) were added to refs/heads/master by this push:
     new 4ea5d93  added definitions of policies for deposits
4ea5d93 is described below

commit 4ea5d93b8bbe6424f0bf484dd9ac986c83d27d00
Author: Özgür Kesim <oec-taler@kesim.org>
AuthorDate: Tue Oct 4 20:46:58 2022 +0200

    added definitions of policies for deposits
---
 core/api-common.rst                 |   6 +-
 core/api-exchange.rst               | 124 ++++++++++++++++++++++++++++++++++--
 design-documents/006-extensions.rst |   5 +-
 design-documents/032-auctions.rst   |  22 +++----
 4 files changed, 136 insertions(+), 21 deletions(-)

diff --git a/core/api-common.rst b/core/api-common.rst
index 848d580..848c6c6 100644
--- a/core/api-common.rst
+++ b/core/api-common.rst
@@ -616,7 +616,7 @@ uses 512-bit hash codes (64 bytes).
 
 .. sourcecode:: c
 
-   struct TALER_ExtensionContractHash {
+   struct TALER_ExtensionsPolicyHash {
      struct GNUNET_HashCode hash;
    };
 
@@ -840,7 +840,7 @@ within the
     struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
     struct TALER_PrivateContractHash h_contract_terms;
     struct TALER_AgeCommitmentHash h_age_commitment;
-    struct TALER_ExtensionContractHash h_extensions;
+    struct TALER_ExtensionsPolicyHash h_policy;
     struct TALER_MerchantWireHash h_wire;
     struct TALER_DenominationHash h_denom_pub;
     struct GNUNET_TIME_AbsoluteNBO timestamp;
@@ -860,7 +860,7 @@ within the
     struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
     struct TALER_PrivateContractHash h_contract_terms;
     struct TALER_MerchantWireHash h_wire;
-    struct TALER_ExtensionContractHash h_extensions;
+    struct TALER_ExtensionsPolicyHash h_policy;
     struct GNUNET_TIME_AbsoluteNBO timestamp;
     struct GNUNET_TIME_AbsoluteNBO refund_deadline;
     struct TALER_AmountNBO amount_without_fee;
diff --git a/core/api-exchange.rst b/core/api-exchange.rst
index 03b0dd4..fb6572d 100644
--- a/core/api-exchange.rst
+++ b/core/api-exchange.rst
@@ -2018,12 +2018,20 @@ exchange.
 Deposit
 -------
 
-Deposit operations are requested by a merchant during a transaction. For the
-deposit operation, 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.
+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:
 
@@ -2081,6 +2089,7 @@ denomination.
       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
@@ -2111,8 +2120,16 @@ denomination.
 
       // 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.
+      policy?: DepositPolicy;
+
       // Signature over `TALER_DepositRequestPS`, made by the customer with the
       // `coin's private key <coin-priv>`.
       coin_sig: EddsaSignature;
@@ -2146,6 +2163,93 @@ denomination.
 
     }
 
+  .. ts:def:: DepositPolicy
+
+    type DepositPolicy =
+    | PolicyRefund
+    | PolicyAuction
+    | PolicyEscrow;
+
+  .. ts:def:: PolicyRefund
+
+    // 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 PolicyRefund {
+      type: "refund";
+
+      // 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:: PolicyAuction
+
+    // 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 PolicyAuction {
+      type: "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_key: EddsaPublicKey;
+
+      // Signature of the ``h_contract_terms`` from the `DepositRequest`
+      // (here, the hash of the auction information), signed by the bidder's
+      // private key.
+      h_auction_sig: EddsaSignature;
+
+      // Date until the auction must have been successfully executed and
+      // a valid transcript provided to the ``/extensions/policy_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 coins will not be
+      // transfered to the seller and can be refreshed by the owner of the
+      // coin.
+      //
+      // If this bidder won the auction, the winning price/amount from the
+      // outcome will substracted from the coin and transered to the seller.
+      // For any potentially remaining value, the bidder can refresh the coin
+      // to retrieve change.
+      deadline: Timestamp;
+    }
+
+  .. ts:def:: PolicyEscrow
+
+    // 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 PolicyEscrow {
+      type: "escrow";
+
+      // 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_key: EddsaPublicKey;
+
+      // Earliest date before the deposit can be claimed by the merchant.
+      // Any attempts to claim this deposit before that date is ignored.
+      // Must lie before the date specified in ``not_after``.
+      not_before: Timestamp;
+
+      // 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.
+      // Must lie after the date specified in ``not_before``.
+      not_after: 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.
@@ -2560,7 +2664,15 @@ denomination.
 
       // 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 batch-deposit.
+      // This might be a refund, auction or escrow policy.
+      policy?: DepositPolicy;
     }
 
   .. ts:def:: BatchDepositRequestCoin
diff --git a/design-documents/006-extensions.rst 
b/design-documents/006-extensions.rst
index 576809a..f70b844 100644
--- a/design-documents/006-extensions.rst
+++ b/design-documents/006-extensions.rst
@@ -18,6 +18,7 @@ of 2021 and 2022:
 * Peer-to-peer payments
 * Anonymous age-restriction
 * Escrow service for anonymous auctions
+* A general escrow service
 
 We call a feature an *extension* when it is *optional* for either the
 exchange, wallet or merchant to enable and support it. (However, enabling
@@ -180,7 +181,9 @@ this:
    AGE_GROUPS = "8:10:12:14:16:18:21"
 
 
-* TODO: Add examples for p2p.
+   [exchange-extension-policy_auction]
+   ENABLED = true
+   REPLAY_PROGRAM = "/usr/local/bin/taler-exchange-auction_replay"
 
 
 Merchant
diff --git a/design-documents/032-auctions.rst 
b/design-documents/032-auctions.rst
index 0f14498..3d8ccf0 100644
--- a/design-documents/032-auctions.rst
+++ b/design-documents/032-auctions.rst
@@ -140,19 +140,19 @@ bid.
 
 The auction operator then runs the auction protocol with all participants
 until conclusion. Once the winner and price have been determined, the auction
-operator POSTs the resulting transcript to a new ``/extensions/auction``
+operator POSTs the resulting transcript to a new ``/extensions/policy_auction``
 endpoint of the exchange.  Here, the extension-specific logic stores the
 transcript in its database (in a new table) and then simulates the auction
-again (using libbrandt), again determining the winner and price.  The
-extension configuration (and thus ``/keys``) may stipendulate some fee(s)
-charged by the exchange to handle the ``/extensions/auction`` request.  The
-fees should be covered by the seller.  We note that the transcript inherently
-contains the deposit confirmations originally issued by the exchange for the
-auction. So, the exchange can identify all of the coins that were escrowed (it
-should also double-check that the coins were escrowed for the correct
-auction).  It then refunds the bids from the loosing bidders, pays the price
-to the seller from the winner (minus auction fee), and partially refunds the
-winner the difference between the escrowed amount and the winning bid.
+again (using libbrandt), again determining the winner and price.  The extension
+configuration (and thus ``/keys``) may stipendulate some fee(s) charged by the
+exchange to handle the ``/extensions/policy_auction`` request.  The fees should
+be covered by the seller.  We note that the transcript inherently contains the
+deposit confirmations originally issued by the exchange for the auction. So,
+the exchange can identify all of the coins that were escrowed (it should also
+double-check that the coins were escrowed for the correct auction).  It then
+refunds the bids from the loosing bidders, pays the price to the seller from
+the winner (minus auction fee), and partially refunds the winner the difference
+between the escrowed amount and the winning bid.
 
   .. note::
 

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