[taler-docs] branch master updated: fix token logic design, fix some inconsistencies in exchange management API

[gnunet]

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

grothoff pushed a commit to branch master
in repository docs.

The following commit(s) were added to refs/heads/master by this push:
     new b30cbf78 fix token logic design, fix some inconsistencies in exchange 
management API
b30cbf78 is described below

commit b30cbf78913adec206fb29f8822ef216f6734672
Author: Christian Grothoff <christian@grothoff.org>
AuthorDate: Tue Dec 10 22:33:42 2024 +0100

    fix token logic design, fix some inconsistencies in exchange management API
---
 core/api-exchange.rst | 62 +++++++++++++++++++++++------------------------
 core/api-merchant.rst | 67 ++++++++++++++++++++++++++++++++++++++++++---------
 2 files changed, 86 insertions(+), 43 deletions(-)

diff --git a/core/api-exchange.rst b/core/api-exchange.rst
index 4981aca2..d46b552a 100644
--- a/core/api-exchange.rst
+++ b/core/api-exchange.rst
@@ -580,37 +580,6 @@ possibly by using HTTPS.
       lost?: boolean;
     }
 
-  .. ts:def:: DenominationKey
-
-    type DenominationKey =
-      | RsaDenominationKey
-      | CSDenominationKey;
-
-  .. ts:def:: RsaDenominationKey
-
-    interface RsaDenominationKey {
-      cipher: "RSA";
-
-      // 32-bit age mask.
-      age_mask: Integer;
-
-      // RSA public key
-      rsa_public_key: RsaPublicKey;
-    }
-
-  .. ts:def:: CSDenominationKey
-
-    interface CSDenominationKey {
-      cipher: "CS";
-
-      // 32-bit age mask.
-      age_mask: Integer;
-
-      // Public key of the denomination.
-      cs_public_key: Cs25519Point;
-
-    }
-
   Fees for any of the operations can be zero, but the fields must still be
   present. The currency of the ``fee_deposit``, ``fee_refresh`` and 
``fee_refund`` must match the
   currency of the ``value``.  Theoretically, the ``fee_withdraw`` could be in a
@@ -849,6 +818,37 @@ Management operations authorized by master key
 
     }
 
+      .. ts:def:: DenominationKey
+
+    type DenominationKey =
+      | RsaDenominationKey
+      | CSDenominationKey;
+
+  .. ts:def:: RsaDenominationKey
+
+    interface RsaDenominationKey {
+      cipher: "RSA";
+
+      // 32-bit age mask.
+      age_mask: Integer;
+
+      // RSA public key
+      rsa_pub: RsaPublicKey;
+    }
+
+  .. ts:def:: CSDenominationKey
+
+    interface CSDenominationKey {
+      cipher: "CS";
+
+      // 32-bit age mask.
+      age_mask: Integer;
+
+      // Public key of the denomination.
+      cs_pub: Cs25519Point;
+
+    }
+
   .. ts:def:: FutureSignKey
 
     interface FutureSignKey {
diff --git a/core/api-merchant.rst b/core/api-merchant.rst
index 5a77f80b..856adebe 100644
--- a/core/api-merchant.rst
+++ b/core/api-merchant.rst
@@ -4156,6 +4156,10 @@ Creating token families
       // Optional map from IETF BCP 47 language tags to localized descriptions.
       description_i18n?: { [lang_tag: string]: string };
 
+      // Additional meta data, such as the ``trusted_domains``
+      // or ``expected_domains``. Depends on the ``kind``.
+      extra_data?: object;
+
       // Start time of the token family's validity period.
       // If not specified, merchant backend will use the current time.
       valid_after?: Timestamp;
@@ -4166,9 +4170,19 @@ Creating token families
       // Validity duration of an issued token.
       duration: RelativeTime;
 
-      // Rounding granularity of generated keys. MUST be
-      // exactly a single year, month, day, hour or minute.
-      rounding: RelativeTime;
+      // Rounding granularity for the start validity of keys.
+      // The desired time is rounded down to a multiple of this
+      // granularity and then the ``start_offset`` is added to
+      // compute the actual start time of the token keys' validity.
+      // The end is then computed by adding the ``duration``.
+      // Must be 1 minute, 1 hour, 1 day, 1 week, 30 days, 90 days
+      // or 365 days (1 year).
+      validity_granularity: RelativeTime;
+
+      // Offset to add to the start time rounded to ``validity_granularity``
+      // to compute the actual start time for a key.
+      // Default is zero.
+      start_offset?: Integer;
 
       // Kind of the token family.
       kind: TokenFamilyKind;
@@ -4217,15 +4231,16 @@ Updating token families
       // Optional map from IETF BCP 47 language tags to localized descriptions.
       description_i18n: { [lang_tag: string]: string };
 
+      // Additional meta data, such as the ``trusted_domains``
+      // or ``expected_domains``. Depends on the ``kind``.
+      extra_data?: object;
+
       // Start time of the token family's validity period.
       valid_after: Timestamp;
 
       // End time of the token family's validity period.
       valid_before: Timestamp;
 
-      // Validity duration of an issued token.
-      duration: RelativeTime;
-
    }
 
 
@@ -4314,17 +4329,32 @@ Inspecting token families
       // Optional map from IETF BCP 47 language tags to localized descriptions.
       description_i18n?: { [lang_tag: string]: string };
 
+      // Additional meta data, such as the ``trusted_domains``
+      // or ``expected_domains``. Depends on the ``kind``.
+      extra_data?: object;
+
       // Start time of the token family's validity period.
+      // No token validities can start before this time
+      // (but they could be sold before).
       valid_after: Timestamp;
 
       // End time of the token family's validity period.
+      // No tokens will be accepted after this time.
       valid_before: Timestamp;
 
       // Validity duration of an issued token.
       duration: RelativeTime;
 
-      // Rounding granularity of generated keys.
-      rounding: RelativeTime;
+      // Rounding granularity for the start validity of keys.
+      // The desired time is rounded down to a multiple of this
+      // granularity and then the ``start_offset`` is added to
+      // compute the actual start time of the token keys' validity.
+      // The end is then computed by adding the ``duration``.
+      validity_granularity: RelativeTime;
+
+      // Offset to subtract from the start time rounded to 
``validity_granularity``
+      // to compute the actual start time for a key.
+      start_offset: RelativeTime;
 
       // Kind of the token family.
       kind: TokenFamilyKind;
@@ -4600,6 +4630,11 @@ The contract terms must have the following structure:
     // 'token_families' map on the top-level.
     token_family_slug: string;
 
+    // Index of the public key for this output token
+    // in the
+    `ContractTokenFamily` ``keys`` array.
+    key_index: integer;
+
     // Number of tokens to be issued.
     // Defaults to one if the field is not provided.
     number?: Integer;
@@ -4643,8 +4678,12 @@ The contract terms must have the following structure:
     // RSA public key.
     rsa_pub: RsaPublicKey;
 
-    // End time of this key's validity period.
-    valid_before: Timestamp;
+    // Start time of this key's signatures validity period.
+    signature_validity_start: Timestamp;
+
+    // End time of this key's signatures validity period.
+    signature_validity_end: Timestamp;
+
   }
 
 .. ts:def:: TokenIssueCsPublicKey
@@ -4655,8 +4694,12 @@ The contract terms must have the following structure:
     // CS public key.
     cs_pub: Cs25519Point;
 
-    // End time of this key's validity period.
-    valid_before: Timestamp;
+    // Start time of this key's signatures validity period.
+    signature_validity_start: Timestamp;
+
+    // End time of this key's signatures validity period.
+    signature_validity_end: Timestamp;
+
   }
 
 .. ts:def:: ContractTokenDetails

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