added definitions of policies for deposits

1 files changed, 118 insertions, 6 deletions

diff --git a/core/api-exchange.rst b/core/api-exchange.rst
index 03b0dd46..fb6572dc 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