From 4ea5d93b8bbe6424f0bf484dd9ac986c83d27d00 Mon Sep 17 00:00:00 2001 From: Özgür Kesim Date: Tue, 4 Oct 2022 20:46:58 +0200 Subject: added definitions of policies for deposits --- core/api-exchange.rst | 124 +++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 118 insertions(+), 6 deletions(-) (limited to 'core/api-exchange.rst') 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_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 -- cgit v1.2.3