commit b30cbf78913adec206fb29f8822ef216f6734672
parent e999d7f56b6846762fc602ffa003c2df70286260
Author: Christian Grothoff <christian@grothoff.org>
Date: Tue, 10 Dec 2024 22:33:42 +0100
fix token logic design, fix some inconsistencies in exchange management API
Diffstat:
2 files changed, 86 insertions(+), 43 deletions(-)
diff --git 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
@@ -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
