diff options
-rw-r--r-- | core/api-common.rst | 6 | ||||
-rw-r--r-- | core/api-exchange.rst | 124 | ||||
-rw-r--r-- | design-documents/006-extensions.rst | 5 | ||||
-rw-r--r-- | 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 848d580d..848c6c67 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 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 diff --git a/design-documents/006-extensions.rst b/design-documents/006-extensions.rst index 576809ad..f70b8449 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 0f144988..3d8ccf0a 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:: |