commit 1b1ff77b7179430ee488d8eab8d4fb95cade49cd
parent dc45f01e348440e50582a7718b412bd3c290d696
Author: Christian Blättler <blatc2@bfh.ch>
Date: Tue, 11 Jun 2024 17:50:59 +0200
update merchant api
Diffstat:
| M | core/api-merchant.rst | | | 228 | ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++------- |
1 file changed, 209 insertions(+), 19 deletions(-)
diff --git a/core/api-merchant.rst b/core/api-merchant.rst
@@ -3997,6 +3997,9 @@ Creating token families
// Validity duration of an issued token.
duration: RelativeTime;
+ // Rounding granularity of generated keys.
+ rounding: RelativeTime;
+
// Kind of the token family.
kind: TokenFamilyKind;
@@ -4145,14 +4148,17 @@ Inspecting token families
// Validity duration of an issued token.
duration: RelativeTime;
+ // Rounding granularity of generated keys.
+ rounding: 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;
+ // How many tokens have been used for this family.
+ used: Integer;
}
@@ -4190,12 +4196,45 @@ The contract terms must have the following structure:
.. ts:def:: ContractTerms
- interface ContractTerms {
- // If this field is omitted, version 0 is assumed.
+ type ContractTerms = (ContractTermsV1 | ContractTermsV0) & ContractTermsCommon;
+
+.. ts:def:: ContractTermsV1
+
+ interface ContractTermsV1 {
// Version 1 supports the ``choices`` array, see
- // https://docs.taler.net/design-documents/046-mumimo-contracts.html
- version?: 0 | 1;
+ // https://docs.taler.net/design-documents/046-mumimo-contracts.html.
+ // @since protocol **vSUBSCRIBE**
+ version: 1;
+
+ // List of contract choices that the customer can select from.
+ // @since protocol **vSUBSCRIBE**
+ choices: ContractChoice[];
+
+ // Map of storing metadata and issue keys of
+ // token families referenced in this contract.
+ // @since protocol **vSUBSCRIBE**
+ token_families: { [token_family_slug: string]: ContractTokenFamily };
+ }
+
+.. ts:def:: ContractTermsV0
+
+ interface ContractTermsV0 {
+ // Defaults to version 0.
+ version?: 0;
+
+ // Total price for the transaction.
+ // The exchange will subtract deposit fees from that amount
+ // before transferring it to the merchant.
+ amount: Amount;
+
+ // Maximum total deposit fee accepted by the merchant for this contract.
+ // Overrides defaults of the merchant instance.
+ max_fee: Amount;
+ }
+
+.. ts:def:: ContractTermsCommon
+ interface ContractTermsCommon {
// Human-readable description of the whole purchase.
summary: string;
@@ -4210,15 +4249,6 @@ The contract terms must have the following structure:
// encoded in it (such as a short product identifier and timestamp).
order_id: string;
- // List of contract choices that the customer can select from.
- // @since protocol **vSUBSCRIBE**
- choices: ContractChoice[];
-
- // Total price for the transaction.
- // The exchange will subtract deposit fees from that amount
- // before transferring it to the merchant.
- amount: Amount;
-
// URL where the same contract could be ordered again (if
// available). Returned also at the public order endpoint
// for people other than the actual buyer (hence public,
@@ -4256,10 +4286,6 @@ The contract terms must have the following structure:
// messages.
fulfillment_message_i18n?: { [lang_tag: string]: string };
- // Maximum total deposit fee accepted by the merchant for this contract.
- // Overrides defaults of the merchant instance.
- max_fee: Amount;
-
// List of products that are part of the purchase (see `Product`).
products: Product[];
@@ -4344,6 +4370,170 @@ The contract terms must have the following structure:
}
+.. 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.
+ // The exchange will subtract deposit fees from that amount
+ // before transferring it to the merchant.
+ amount: Amount;
+
+ // List of inputs the wallet must provision (all of them) to
+ // satisfy the conditions for the contract.
+ inputs: ContractInput[];
+
+ // List of outputs the merchant promises to yield (all of them)
+ // once the contract is paid.
+ outputs: ContractOutput[];
+
+ // Maximum total deposit fee accepted by the merchant for this contract.
+ max_fee: Amount;
+ }
+
+.. ts:def:: ContractInput
+
+ // For now, only tokens are supported as inputs.
+ type ContractInput = ContractInputToken;
+
+.. ts:def:: ContractInputToken
+
+ interface ContractInputToken {
+ type: "token";
+
+ // Slug of the token family in the
+ // 'token_families' map on the order.
+ token_family_slug: string;
+
+ // Start of the validity period of the token. This is used to find the
+ // matching public key within the token family.
+ valid_after: Timestamp;
+
+ // Number of tokens of this type required.
+ // Defaults to one if the field is not provided.
+ number?: Integer;
+ };
+
+.. ts:def:: ContractOutput
+
+ // For now, only tokens are supported as outputs.
+ type ContractOutput = ContractOutputToken;
+
+.. ts:def:: ContractOutputToken
+
+ interface ContractOutputToken {
+ type: "token";
+
+ // Slug of the token family in the
+ // 'token_families' map on the top-level.
+ token_family_slug: string;
+
+ // Start of the validity period of the token. This is used to find the
+ // matching public key within the token family.
+ valid_after: Timestamp;
+
+ // Number of tokens to be issued.
+ // Defaults to one if the field is not provided.
+ number?: Integer;
+ }
+
+.. ts:def:: ContractTokenFamily
+
+ interface ContractTokenFamily {
+ // Human-readable name of the token family.
+ name: string;
+
+ // Human-readable description of the semantics of
+ // this token family (for display).
+ description: string;
+
+ // Map from IETF BCP 47 language tags to localized descriptions.
+ description_i18n?: { [lang_tag: string]: string };
+
+ // Public keys used to validate tokens issued by this token family.
+ keys: TokenIssuePublicKey[];
+
+ // Kind-specific information of the token
+ details: ContractTokenDetails;
+
+ // Must a wallet understand this token type to
+ // process contracts that use or issue it?
+ critical: boolean;
+ };
+
+.. ts:def:: TokenIssuePublicKey
+
+ type TokenIssuePublicKey =
+ | TokenIssueRsaPublicKey
+ | TokenIssueCsPublicKey;
+
+.. ts:def:: TokenIssueRsaPublicKey
+
+ interface TokenIssueRsaPublicKey {
+ cipher: "RSA";
+
+ // RSA public key.
+ rsa_pub: RsaPublicKey;
+
+ // Start time of this key's validity period.
+ valid_after: Timestamp;
+
+ // End time of this key's validity period.
+ valid_before: Timestamp;
+ }
+
+.. ts:def:: TokenIssueCsPublicKey
+
+ interface TokenIssueCsPublicKey {
+ cipher: "CS";
+
+ // CS public key.
+ cs_pub: Cs25519Point;
+
+ // Start time of this key's validity period.
+ valid_after: Timestamp;
+
+ // End time of this key's validity period.
+ valid_before: Timestamp;
+ }
+
+.. ts:def:: ContractTokenDetails
+
+ type ContractTokenDetails =
+ | ContractSubscriptionTokenDetails
+ | ContractDiscountTokenDetails;
+
+.. ts:def:: ContractSubscriptionTokenDetails
+
+ interface ContractSubscriptionTokenDetails {
+ class: "subscription";
+
+ // Array of domain names where this subscription
+ // can be safely used (e.g. the issuer warrants that
+ // these sites will re-issue tokens of this type
+ // if the respective contract says so). May contain
+ // "*" for any domain or subdomain.
+ trusted_domains: string[];
+ };
+
+.. ts:def:: ContractDiscountTokenDetails
+
+ interface ContractDiscountTokenDetails {
+ class: "discount";
+
+ // Array of domain names where this discount token
+ // is intended to be used. May contain "*" for any
+ // domain or subdomain. Users should be warned about
+ // sites proposing to consume discount tokens of this
+ // type that are not in this list that the merchant
+ // is accepting a coupon from a competitor and thus
+ // may be attaching different semantics (like get 20%
+ // discount for my competitors 30% discount token).
+ expected_domains: string[];
+ };
+
+
The wallet must select an exchange that either the merchant accepts directly by
listing it in the exchanges array, or for which the merchant accepts an auditor
that audits that exchange by listing it in the auditors array.
