[taler-docs] branch master updated: fixes to API docs and design document

[gnunet]

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

christian-blaettler pushed a commit to branch master
in repository docs.

The following commit(s) were added to refs/heads/master by this push:
     new 9366601b fixes to API docs and design document
9366601b is described below

commit 9366601b7697e971cecf04c9a2952feaafd34607
Author: Christian Blättler <blatc2@bfh.ch>
AuthorDate: Wed Jun 12 23:07:29 2024 +0200

    fixes to API docs and design document
---
 core/api-common.rst                       | 11 +++-
 core/api-merchant.rst                     | 23 +-------
 design-documents/046-mumimo-contracts.rst | 95 +++++++++----------------------
 3 files changed, 40 insertions(+), 89 deletions(-)

diff --git a/core/api-common.rst b/core/api-common.rst
index 2201458a..224c2307 100644
--- a/core/api-common.rst
+++ b/core/api-common.rst
@@ -592,7 +592,7 @@ Unblinded coin
   // The type of a coin's unblinded signature depends on the cipher that was 
used
   // for signing with a denomination key.
   // Note that for now, only RSA is supported.
-  type UnblindedSignature = RsaUnblindedSignature;
+  type UnblindedSignature = RsaUnblindedSignature | CsUnblindedSignature;
 
 .. ts:def:: RsaUnblindedSignature
 
@@ -601,6 +601,15 @@ Unblinded coin
     rsa_signature: RsaSignature;
   }
 
+.. ts:def:: CsUnblindedSignature
+  // Note, this is here for the sake of completeness, but not yet supported
+  interface CsUnblindedSignature {
+    cipher: "CS";
+
+    cs_signature_r: Cs25519Point;
+    cs_signature_s: Cs25519Scalar;
+  }
+
 
 .. _signature:
 
diff --git a/core/api-merchant.rst b/core/api-merchant.rst
index ccf597ce..a06c57b7 100644
--- a/core/api-merchant.rst
+++ b/core/api-merchant.rst
@@ -380,9 +380,6 @@ Making the payment
       // Blind signature made by the merchant.
       blind_sig: TokenIssueBlindSig;
 
-      // Hash of the token issue public key.
-      h_issue: HashCode;
-
     }
 
   .. ts:def:: TokenIssueBlindSig
@@ -401,7 +398,7 @@ Making the payment
   .. ts:def:: CSTokenIssueBlindSig
 
     interface CSTokenIssueBlindSig {
-      type: "CS";
+      cipher: "CS";
 
       // Signer chosen bit value, 0 or 1, used
       // in Clause Blind Schnorr to make the
@@ -482,30 +479,14 @@ Making the payment
       // issue public key of the merchant.
       ub_sig: UnblindedSignature;
 
-      // The hash of the token issue public key of the token being using
-      // in this request.
-      h_issue: HashCode;
-
     }
 
   .. ts:def:: TokenEnvelope
 
-    interface TokenEnvelope {
-
-      // Blinded token use public key.
-      token_ev: BlindedTokenEnvelope;
-
-      // Hash of the token issue public key.
-      h_issue: HashCode;
-
-    }
-
-  .. ts:def:: BlindedTokenEnvelope
-
     // This type depends on the cipher used to sign token families. This is
     // configured by the merchant and defined for each token family in the
     // contract terms.
-    type BlindedTokenEnvelope = RSATokenEnvelope | CSTokenEnvelope;
+    type TokenEnvelope = RSATokenEnvelope | CSTokenEnvelope;
 
   .. ts:def:: RSATokenEnvelope
 
diff --git a/design-documents/046-mumimo-contracts.rst 
b/design-documents/046-mumimo-contracts.rst
index 3b581b3e..df265141 100644
--- a/design-documents/046-mumimo-contracts.rst
+++ b/design-documents/046-mumimo-contracts.rst
@@ -90,14 +90,11 @@ New Contract Terms Format
 
 The contract terms v1 will have the following structure:
 
-.. ts:def:: ContractTermsV1
-
   interface ContractTermsV1 {
-
     // This is version 1, the previous contract terms SHOULD
     // be indicated using "0", but in v0 specifying the version
     // is optional.
-    version: "1";
+    version: 1;
 
     // Unique, free-form identifier for the proposal.
     // Must be unique within a merchant instance.
@@ -202,7 +199,7 @@ The contract terms v1 will have the following structure:
 
     // Map from token family slugs to meta data about the
     // respective token family.
-    token_families: { [token_family_slug: string]: TokenFamily };
+    token_families: { [token_family_slug: string]: ContractTokenFamily };
 
     // Extra data that is only interpreted by the merchant frontend.
     // Useful when the merchant needs to store extra information on a
@@ -211,13 +208,9 @@ The contract terms v1 will have the following structure:
 
     // Exchanges that the merchant accepts for this currency.
     exchanges: Exchange[];
-
   }
 
-.. ts:def:: ContractChoice
-
   interface ContractChoice {
-
     // Price to be paid for this choice. Could be 0.
     // The price is in addition to other instruments,
     // such as rations and tokens.
@@ -235,11 +228,8 @@ The contract terms v1 will have the following structure:
 
     // Maximum total deposit fee accepted by the merchant for this contract.
     max_fee: Amount;
-
   }
 
-.. ts:def:: ContractInput
-
   type ContractInput =
     | ContractInputRation
     | ContractInputToken;
@@ -247,7 +237,6 @@ The contract terms v1 will have the following structure:
 .. ts:def:: ContractInputRation
 
   interface ContractInputRation {
-
     type: "coin";
 
     // Price to be paid for the transaction.
@@ -259,13 +248,11 @@ The contract terms v1 will have the following structure:
 
     // Base URL of the ration authority.
     ration_authority_url: string;
-
   };
 
 .. ts:def:: ContractInputToken
 
   interface ContractInputToken {
-
     type: "token";
 
     // Slug of the token family in the
@@ -279,7 +266,6 @@ The contract terms v1 will have the following structure:
     // Number of tokens of this type required.
     // Defaults to one if the field is not provided.
     number?: Integer;
-
   };
 
 .. ts:def:: ContractOutput
@@ -292,7 +278,6 @@ The contract terms v1 will have the following structure:
 .. ts:def:: ContractOutputCoin
 
   interface ContractOutputCoin {
-
     type: "coins";
 
     // Amount of coins that will be yielded.
@@ -302,25 +287,21 @@ The contract terms v1 will have the following structure:
     // Base URL of the exchange that will issue the
     // coins.
     exchange_url: string;
-
   };
 
 .. ts:def:: ContractOutputTaxReceipt
 
   interface ContractOutputTaxReceipt {
-
     type: "tax-receipt";
 
     // Base URL of the donation authority that will
     // issue the tax receipt.
     donau_url: string;
-
   };
 
 .. ts:def:: ContractOutputToken
 
   interface ContractOutputToken {
-
     type: "token";
 
     // Slug of the token family in the
@@ -334,19 +315,13 @@ The contract terms v1 will have the following structure:
     // Number of tokens to be issued.
     // Defaults to one if the field is not provided.
     number?: Integer;
-
   }
 
-.. ts:def:: TokenClass
-
-  type TokenClass =
-    | TokenClassSubscription
-    | TokenClassDiscount
-
-.. ts:def:: TokenClassSubscription
-
-  interface TokenClassSubscription {
+  type ContractTokenDetails =
+    | ContractSubscriptionTokenDetails
+    | ContractDiscountTokenDetails
 
+  interface ContractSubscriptionTokenDetails {
     class: "subscription";
 
     // Array of domain names where this subscription
@@ -355,13 +330,10 @@ The contract terms v1 will have the following structure:
     // if the respective contract says so).  May contain
     // "*" for any domain or subdomain.
     trusted_domains: string[];
-
   };
 
-.. ts:def:: TokenClassDiscount
-
-  interface TokenClassDiscount {
 
+  interface ContractDiscountTokenDetails {
     class: "discount";
 
     // Array of domain names where this discount token
@@ -373,14 +345,12 @@ The contract terms v1 will have the following structure:
     // may be attaching different semantics (like get 20%
     // discount for my competitors 30% discount token).
     expected_domains: string[];
-
   };
 
 
-.. ts:def:: TokenFamily
-
-  interface TokenFamily {
+.. ts:def:: ContractTokenFamily
 
+  interface ContractTokenFamily {
     // Human-readable name of the token family.
     name: string;
 
@@ -392,10 +362,10 @@ The contract terms v1 will have the following structure:
     description_i18n?: { [lang_tag: string]: string };
 
     // Public keys used to validate tokens issued by this token family.
-    keys: TokenSignerPublicKeyGroup;
+    keys: TokenIssuePublicKey[];
 
     // Class-specific information of the token
-    details: TokenClass;
+    details: ContractTokenDetails;
 
     // Must a wallet understand this token type to
     // process contracts that consume or yield it?
@@ -413,48 +383,39 @@ The contract terms v1 will have the following structure:
     // Signature affirming the ass by the ASS authority.
     // FIXME: this is still rather speculative in the design...
     ass_sig?: EddsaSignature;
-
   };
 
 
-.. ts:def:: TokenSignerPublicKeyGroup
+  type TokenIssuePublicKey =
+    | TokenIssueRsaPublicKey
+    | TokenIssueCsPublicKey;
 
-  type TokenSignerPublicKeyGroup =
-    | TokenSignerPublicKeyGroupRsa
-    | TokenSignerPublicKeyGroupCs;
 
-.. ts:def:: TokenSignerPublicKeyGroupRsa
-
-  interface TokenSignerPublicKeyGroupRsa {
+  interface TokenIssueRsaPublicKey {
     cipher: "RSA";
 
-    public_keys: {
-      // RSA public key.
-      rsa_pub: RsaPublicKey;
+    // RSA public key.
+    rsa_pub: RsaPublicKey;
 
-      // Start time of this key's validity period.
-      valid_after: Timestamp;
+    // Start time of this key's validity period.
+    valid_after: Timestamp;
 
-      // End time of this key's validity period.
-      valid_before: Timestamp;
-    }[];
+    // End time of this key's validity period.
+    valid_before: Timestamp;
   }
 
-.. ts:def:: TokenSignerPublicKeyGroupCs
 
-  interface TokenSignerPublicKeyGroupCs {
+  interface TokenIssueCsPublicKey {
     cipher: "CS";
 
-    public_keys: {
-      // CS public key.
-      cs_pub: Cs25519Point;
+    // CS public key.
+    cs_pub: Cs25519Point;
 
-      // Start time of this key's validity period.
-      valid_after: Timestamp;
+    // Start time of this key's validity period.
+    valid_after: Timestamp;
 
-      // End time of this key's validity period.
-      valid_before: Timestamp;
-    }[];
+    // End time of this key's validity period.
+    valid_before: Timestamp;
   }
 
 

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