[taler-docs] branch master updated (e8f307fe -> a4f2424c)

[gnunet]

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

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

    from e8f307fe docs: add nonce2ecash docs
     new 807f2af5 add tokenfamilies api to merchant
     new 73ae1954 implement feedback on merchant api specification
     new e44c9f6b better naming for validity range
     new b95e8b15 remove can_issue_tokens (for now)
     new 5f82d484 add kind to token family
     new c04429f8 Merge branch 'master' into feature/tokens
     new 9d329e9f dd46:  remove old TODO
     new a018517b dd46: syntax fixes
     new 9b0678d5 dd46: shared type TokenClass for input and output tokens
     new 7af0b3eb Merge branch 'master' into feature/tokens
     new a4f2424c Merge branch 'feature/tokens'

The 11 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails.  The revisions
listed as "add" were already present in the repository and have only
been added to this reference.


Summary of changes:
 core/api-merchant.rst                     | 238 +++++++++++++++++++++++++++++-
 design-documents/046-mumimo-contracts.rst |  70 ++++-----
 2 files changed, 273 insertions(+), 35 deletions(-)

diff --git a/core/api-merchant.rst b/core/api-merchant.rst
index ebd5647d..c1bbf058 100644
--- a/core/api-merchant.rst
+++ b/core/api-merchant.rst
@@ -3127,7 +3127,7 @@ Adding webhooks
     The creation of the webhook is successsful.
 
   :http:statuscode:`404 Not found`:
-    The merchant instance is unknowm or it not in our data.
+    The merchant instance is unknown or it not in our data.
 
   .. ts:def:: WebhookAddDetails
 
@@ -3288,6 +3288,242 @@ Removing webhook
 
 
 
+----------------------------------------
+Token Families: Subscriptions, Discounts
+----------------------------------------
+
+This API provides functionalities for the issuance, management, and revocation
+of token families. Tokens facilitate the implementation of subscriptions and
+discounts, engaging solely the merchant and the user. Each token family
+encapsulates details pertaining to its respective tokens, guiding the 
merchant's
+backend on the appropriate processing and handling.
+
+
+Creating token families
+-----------------------
+
+.. http:post:: [/instances/$INSTANCES]/private/tokenfamilies
+
+  This is used to create a token family.
+
+  **Request:**
+
+  The request must be a `TokenFamilyCreateRequest`.
+
+  **Response:**
+
+  :http:statuscode:`204 No content`:
+    The token family was created successfully.
+
+  :http:statuscode:`404 Not found`:
+    The merchant backend is unaware of the instance.
+
+  .. ts:def:: TokenFamilyCreateRequest
+
+    interface TokenFamilyCreateRequest {
+
+      // Identifier for the token family consisting of unreserved characters
+      // according to RFC 3986.
+      slug: string;
+
+      // Human-readable name for the token family.
+      name: string;
+
+      // Human-readable description for the token family.
+      description: string;
+
+      // Optional map from IETF BCP 47 language tags to localized descriptions.
+      description_i18n?: { [lang_tag: string]: string };
+
+      // Start time of the token family's validity period.
+      // If not specified, merchant backend will use the current time.
+      valid_after?: Timestamp;
+
+      // End time of the token family's validity period.
+      valid_before: Timestamp;
+
+      // Validity duration of an issued token.
+      duration: RelativeTime;
+
+      // Kind of the token family.
+      kind: TokenFamilyKind;
+
+   }
+
+  .. ts:def:: TokenFamilyKind
+
+    enum TokenFamilyKind {
+      Discount = "discount",
+      Subscription = "subscription",
+    }
+
+
+Updating token families
+-----------------------
+
+.. http:patch:: 
[/instances/$INSTANCES]/private/tokenfamilies/$TOKEN_FAMILY_SLUG
+
+  This is used to update a token family.
+
+  **Request:**
+
+  The request must be a `TokenFamilyUpdateRequest`.
+
+  **Response:**
+
+  :http:statuscode:`200 OK`:
+    The token family was successsful updated. Returns a `TokenFamilyDetails`.
+
+  :http:statuscode:`404 Not found`:
+    The merchant backend is unaware of the token family or instance.
+
+  .. ts:def:: TokenFamilyUpdateRequest
+
+    interface TokenFamilyUpdateRequest {
+
+      // Human-readable name for the token family.
+      name: string;
+
+      // Human-readable description for the token family.
+      description: string;
+
+      // Optional map from IETF BCP 47 language tags to localized descriptions.
+      description_i18n: { [lang_tag: string]: string };
+
+      // 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;
+
+   }
+
+
+
+Inspecting token families
+-------------------------
+
+.. http:get:: [/instances/$INSTANCES]/private/tokenfamilies
+
+  This is used to list all configured token families for an instance.
+
+  **Response:**
+
+  :http:statuscode:`200 OK`:
+    The merchant backend has successfully returned all token families.
+    Returns a `TokenFamiliesList`.
+
+  :http:statuscode:`404 Not found`:
+    The merchant backend is unaware of the instance.
+
+  .. ts:def:: TokenFamiliesList
+
+    // TODO: Add pagination
+
+    interface TokenFamiliesList {
+
+      // All configured token families of this instance.
+      token_families: TokenFamilySummary[];
+
+   }
+
+  .. ts:def:: TokenFamilySummary
+
+    interface TokenFamilySummary {
+      // Identifier for the token family consisting of unreserved characters
+      // according to RFC 3986.
+      slug: string;
+
+      // Human-readable name for the token family.
+      name: string;
+
+      // Start time of the token family's validity period.
+      valid_after: Timestamp;
+
+      // End time of the token family's validity period.
+      valid_before: Timestamp;
+
+      // Kind of the token family.
+      kind: TokenFamilyKind;
+   }
+
+
+.. http:get:: [/instances/$INSTANCES]/private/tokenfamilies/$TOKEN_FAMILY_SLUG
+
+  This is used to get detailed information about a specific token family.
+
+  **Response:**
+
+  :http:statuscode:`200 OK`:
+    The merchant backend has successfully returned the detailed information
+    about a specific token family. Returns a `TokenFamilyDetails`.
+
+  :http:statuscode:`404 Not found`:
+    The merchant backend is unaware of the token family or instance.
+
+
+  The `TokenFamilyDetails` object describes a configured token family.
+
+  .. ts:def:: TokenFamilyDetails
+
+    interface TokenFamilyDetails {
+
+      // Identifier for the token family consisting of unreserved characters
+      // according to RFC 3986.
+      slug: string;
+
+      // Human-readable name for the token family.
+      name: string;
+
+      // Human-readable description for the token family.
+      description: string;
+
+      // Optional map from IETF BCP 47 language tags to localized descriptions.
+      description_i18n?: { [lang_tag: string]: string };
+
+      // 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;
+
+      // Kind of the token family.
+      kind: TokenFamilyKind;
+
+      // How many tokens have been issued for this family.
+      issued: Integer;
+
+      // How many tokens have been redeemed for this family.
+      redeemed: Integer;
+
+   }
+
+
+
+Deleting token families
+-----------------------
+
+.. http:delete:: 
[/instances/$INSTANCES]/private/tokenfamilies/$TOKEN_FAMILY_SLUG
+
+  This is used to delete a token family. Issued tokens of this family will not
+  be spendable anymore.
+
+  **Response:**
+
+  :http:statuscode:`204 No content`:
+    The backend has successfully deleted the token family.
+
+  :http:statuscode:`404 Not found`:
+    The merchant backend is unaware of the token family or instance.
+
+
+
 ------------------
 The Contract Terms
 ------------------
diff --git a/design-documents/046-mumimo-contracts.rst 
b/design-documents/046-mumimo-contracts.rst
index fcb7f2b1..5f1d1d98 100644
--- a/design-documents/046-mumimo-contracts.rst
+++ b/design-documents/046-mumimo-contracts.rst
@@ -62,8 +62,6 @@ We want Taler to support various interesting use-cases:
     acquired (i.e., not brought from home or stolen from a stack of dirty 
items)
     and incentivizes return after use.
 
-TODO: add more use-cases here!
-
 
 Proposed Solution
 =================
@@ -190,7 +188,7 @@ The contract terms v1 will have the following structure:
     extra?: any;
 
     // Fee limits and wire account details by currency.
-    limits: { [currency:string] : CurrencyLimit };
+    limits: { [currency: string]: CurrencyLimit };
   }
 
 .. ts:def:: CurrencyLimit
@@ -212,7 +210,7 @@ The contract terms v1 will have the following structure:
     // Maximum wire fee accepted by the merchant (customer share to be
     // divided by the ``wire_fee_amortization`` factor, and further reduced
     // if deposit fees are below ``max_fee``).  Default if missing is zero.
-    max_wire_fee: Amount;
+    max_wire_fee?: Amount;
 
     // Over how many customer transactions does the merchant expect to
     // amortize wire fees on average?  If the exchange's wire fee is
@@ -222,7 +220,7 @@ The contract terms v1 will have the following structure:
     // between the ``max_fee`` and the sum of the actual deposit fees.
     // Optional, default value if missing is 1.  0 and negative values are
     // invalid and also interpreted as 1.
-    wire_fee_amortization: number;
+    wire_fee_amortization?: number;
 
     // Exchanges that the merchant accepts for this currency.
     exchanges: Exchange[];
@@ -271,15 +269,15 @@ The contract terms v1 will have the following structure:
 
     // Map from authority labels to meta data abou the
     // respective token authority.
-    token_types: { [authority_label: TokenAuthority };
+    token_types: { [authority_label: string]: TokenAuthority };
 
   }
 
 .. ts:def:: ContractInput
 
   type ContractInput =
-    | ContractInputRation
-    | ContractInputToken;
+    ContractInputRation |
+    ContractInputToken;
 
 .. ts:def:: ContractInputRation
 
@@ -305,9 +303,9 @@ The contract terms v1 will have the following structure:
 
     type: "token";
 
-    // Hash over the public key used to sign the
-    // type of subscription token required.
-    h_issuer: HashCode;
+    // Label of the token authority in the
+    // 'token_types' map on the top-level.
+    authority_label: string;
 
     // Number of tokens of this type required.
     // Defaults to one if the field is not provided.
@@ -318,17 +316,17 @@ The contract terms v1 will have the following structure:
 .. ts:def:: ContractOutput
 
   type ContractOutput =
-    | ContractOutputCurrency
-    | ContractOutputTaxReceipt
-    | ContractOutputToken;
+    ContractOutputCoin |
+    ContractOutputTaxReceipt |
+    ContractOutputToken;
 
-.. ts:def:: ContractOutputCurrency
+.. ts:def:: ContractOutputCoin
 
-  interface ContractOutputCurrency {
+  interface ContractOutputCoin {
 
-    type: "currency";
+    type: "coins";
 
-    // Amount of currency that will be yielded.
+    // Amount of coins that will be yielded.
     // This excludes any applicable withdraw fees.
     brutto_yield: Amount;
 
@@ -360,24 +358,21 @@ The contract terms v1 will have the following structure:
     // 'token_types' map on the top-level.
     authority_label: string;
 
-    // Must a wallet understand this token type to
-    // process contracts that consume or yield it?
-    critical: boolean;
+    // Number of tokens to be yelded.
+    // Defaults to one if the field is not provided.
+    number?: Integer;
 
-    // Information about the class of token that will
-    // be yielded.
-    details: OutputTokenClass;
   }
 
-.. ts:def:: OutputTokenClass
+.. ts:def:: TokenClass
 
-  type OutputTokenClass =
-    | OutputTokenClassSubscription
-    | OutputTokenClassDiscount
+  type TokenClass =
+    TokenClassSubscription
+    | TokenClassDiscount
 
-.. ts:def:: OutputTokenClassSubscription
+.. ts:def:: TokenClassSubscription
 
-  interface OutputTokenClassSubscription {
+  interface TokenClassSubscription {
 
     class: "subscription";
 
@@ -396,9 +391,9 @@ The contract terms v1 will have the following structure:
 
   };
 
-.. ts:def:: OutputTokenClassDiscount
+.. ts:def:: TokenClassDiscount
 
-  interface OutputTokenClassDiscount {
+  interface TokenClassDiscount {
 
     class: "discount";
 
@@ -433,6 +428,13 @@ The contract terms v1 will have the following structure:
     // When will tokens signed by this key expire?
     token_expiration: Timestamp;
 
+    // Class-specific information of the token
+    details: TokenClass;
+
+    // Must a wallet understand this token type to
+    // process contracts that consume or yield it?
+    critical: boolean;
+
     // Number of tokens issued according to ASS authority
     // FIXME: this is still rather speculative in the design...
     ass?: Integer;
@@ -452,8 +454,8 @@ The contract terms v1 will have the following structure:
 .. ts:def:: TokenSignerPublicKey
 
   type TokenSignerPublicKey =
-    | DenomGroupRsa
-    | DenomGroupCs;
+    DenomGroupRsa |
+    DenomGroupCs;
 
 TODO: may want to do a deep copy and rename
 DenomGroup* to TokenSignerPublicKey* here.

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