[taler-docs] 02/02: Added transcript definition for BrandtVickrey

[gnunet]

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

oec pushed a commit to branch master
in repository docs.

commit 5212b29fec72cb1358bf3ace97881ba20c95120e
Author: Özgür Kesim <oec-taler@kesim.org>
AuthorDate: Thu Oct 6 11:31:33 2022 +0200

    Added transcript definition for BrandtVickrey
---
 core/api-exchange.rst                    | 66 ++++++++++++++++++++---
 design-documents/024-age-restriction.rst |  2 +-
 design-documents/032-auctions.rst        | 91 ++++++++++++++++++++++++++++----
 3 files changed, 140 insertions(+), 19 deletions(-)

diff --git a/core/api-exchange.rst b/core/api-exchange.rst
index 3c5e799..bd5b750 100644
--- a/core/api-exchange.rst
+++ b/core/api-exchange.rst
@@ -2131,6 +2131,11 @@ proof to the seller for the escrow of sufficient fund.
       // 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 
+      // `ExchangeKeysExtensionsResponse` response to the ``/keys`` endpoint.
       policy?: DepositPolicy;
 
       // Signature over `TALER_DepositRequestPS`, made by the customer with the
@@ -2170,7 +2175,7 @@ proof to the seller for the escrow of sufficient fund.
 
     type DepositPolicy =
     | PolicyRefund
-    | PolicyBrandtVickeryAuction
+    | PolicyBrandtVickreyAuction
     | PolicyEscrow;
 
   .. ts:def:: PolicyRefund
@@ -2191,14 +2196,14 @@ proof to the seller for the escrow of sufficient fund.
       deadline: Timestamp;
     }
 
-  .. ts:def:: PolicyBrandtVickeryAuction
+  .. 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 PolicyBrandtVickeryAuction {
-      type: "brandt_vickery_auction";
+    interface PolicyBrandtVickreyAuction {
+      type: "brandt_vickrey_auction";
 
       // Public key of this bidder.
       //
@@ -2206,9 +2211,15 @@ proof to the seller for the escrow of sufficient fund.
       // 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;
+
       // Date until the auction must have been successfully executed and
       // a valid transcript provided to the 
-      // ``/extensions/policy_brandt-vickery-auction``-endpoint of the
+      // ``/extensions/policy_brandt-vickrey-auction``-endpoint of the
       // exchange.
       //
       // [If the auction has not been executed by then] OR [has been executed
@@ -2223,6 +2234,47 @@ proof to the seller for the escrow of sufficient fund.
       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.
+      type: integer;
+
+      // 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.
+      public: boolean;
+
+      // The public key of the seller.
+      pubkey: EddsaPublicKey;
+
+      // The seller's account details.
+      payto_uri: string;
+    }
+
+
   .. ts:def:: PolicyEscrow
 
     // CAVEAT: THIS IS STILL WORK IN PROGRESS
@@ -2723,7 +2775,7 @@ proof to the seller for the escrow of sufficient fund.
       // Array of deposit confirmation signatures from the exchange
       // Entries must be in the same order the coins were given
       // in the batch deposit request.
-      exchange_sigs[]: DepositConfirmationSignature;
+      exchange_sigs: DepositConfirmationSignature[];
     }
 
   .. ts:def:: DepositConfirmationSignature
@@ -4182,7 +4234,7 @@ Wallet-to-wallet transfers
 
      // AgeCommitment is an array of public keys, one for each age group of the
      // age-restricted denomination.
-     type AgeCommitment = []Edx25519PublicKey;
+     type AgeCommitment = Edx25519PublicKey[];
 
   .. ts:def:: Attestation
 
diff --git a/design-documents/024-age-restriction.rst 
b/design-documents/024-age-restriction.rst
index 6b1004f..b394a42 100644
--- a/design-documents/024-age-restriction.rst
+++ b/design-documents/024-age-restriction.rst
@@ -151,7 +151,7 @@ registering the extension ``age_restriction`` with a value 
type
    interface ConfigAgeRestriction {
       // The age groups.  This field is mandatory and binding in the sense
       // that its value is taken into consideration when signing the
-      // denominations in `ExchangeKeysResponse`.``age_restricted_denoms``.
+      // age restricted denominations in the `ExchangeKeysResponse`
       age_groups: AgeGroups;
    }
 
diff --git a/design-documents/032-auctions.rst 
b/design-documents/032-auctions.rst
index 3d8ccf0..d81f848 100644
--- a/design-documents/032-auctions.rst
+++ b/design-documents/032-auctions.rst
@@ -98,10 +98,10 @@ the auction:
     as paying any other merchant and thus out of scope for this
     design document.
 
-  * An exchange that supports the ``auction`` extension and holds
-    the funds for bids in escrow for the duration of the auction.
-    Upon completion of the auction, the exchange pays the seller
-    from the auction's winner and refunds the other bidders.
+  * An exchange that supports the ``policy_vickrey_auction`` extension and
+    holds the funds for bids in escrow for the duration of the auction.  Upon
+    completion of the auction, the exchange pays the seller from the auction's
+    winner and refunds the other bidders.
 
   * An auditor that verifies that the exchange made the payments
     correctly.
@@ -140,13 +140,14 @@ 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/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/policy_auction`` request.  The fees should
-be covered by the seller.  We note that the transcript inherently contains the
+operator POSTs the resulting transcript to a new 
+``/extensions/policy_brandt_vickrey_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/policy_brandt_vickrey_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
@@ -174,6 +175,74 @@ transactions.
 The auditor of the exchange can again simulate the auction protocol and can
 thus confirm that the exchange's ultimate transactions were correct.
 
+Transcripts
+^^^^^^^^^^^
+
+A transcript of a Brandt-Vickrey auction is the JSON encoding of an object of
+type `BrandtVickreyAuctionTranscript`.
+
+.. ts:def:: BrandtVickreyAuctionTranscript
+
+    // This structure defines the transcript of an auction of Brandt-Vickory 
kind.
+    interface BrandtVickreyAuctionTranscript {
+      // The auction definition.
+      auction: BrandtVickreyAuction;
+
+      // The public keys of the bidders, in Crockford Base32 encoding.
+      bidders: EddsaPublicKey[];
+
+      // Signatures of the auction in Crockford Base32 encoding.
+      // One signature per bidder.
+      signatures: EddsaSignature[];
+
+      // The transcript of all messages received by the seller.
+      transcript: BrandtVickreyAuctionMessage[];
+
+      // Optionally, the seller can provide the winners it had calculated.
+      winners?: BrandtVickreyAuctionWinner[];
+
+      // The signature over the hash of this JSON object, without the
+      // key ``sig`` and in normalized form, basically over
+      //   H(auction, bidders, signatures, transcripts, winners?)
+      // It is signed by the private key that corresponds to the public key
+      // in `BrandtVickreyAuction`.``pubkey``.
+      // This signature is in Crockford Base32 encoding.
+      sig: EddsaSignature;
+    }
+
+
+.. ts:def:: BrandtVickreyAuctionMessage
+
+   interface BrandtVickreyAuctionMessage {
+     // The index of the bidder into the
+     // `BrandtVickreyAuctionTranscript`.``bidders`` array.
+     bidder: number;
+
+     // The raw message in Crockford Base32 encoding.
+     msg: string;
+
+     // The signature over the message.  The signature is in Crockford Base32
+     // encoding.  It must be signed by the private key corresponding to the
+     // bidder's public key in `BrandtVickreyAuctionTranscript`.``bidders``.
+     sig: EddsaSignature;
+   }
+
+
+
+.. ts:def:: BrandtVickreyAuctionWinner
+
+   interface BrandtVickreyAuctionWinner {
+     // The index of the bidder into the
+     // `BrandtVickreyAuctionTranscript`.bidder array.
+     bidder: number;
+
+     // The index of the winning price into the
+     // `BrandtVickreyAuction`.prices array.
+     price_idx: number;
+
+     // The winning price
+     price: Amount;
+   }
 
 
 Alternatives

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