diff options
Diffstat (limited to 'design-documents/046-mumimo-contracts.rst')
| -rw-r--r-- | design-documents/046-mumimo-contracts.rst | 122 |
1 files changed, 44 insertions, 78 deletions
diff --git a/design-documents/046-mumimo-contracts.rst b/design-documents/046-mumimo-contracts.rst index 8cb35316..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. @@ -107,13 +104,6 @@ The contract terms v1 will have the following structure: // encoded in it (such as a short product identifier and timestamp). order_id: string; - // Price to be paid for the transaction. 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. - price: 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, @@ -209,24 +199,24 @@ 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 // contract without storing it separately in their database. extra?: any; - // Maximum total deposit fee accepted by the merchant for this contract. - max_fee: Amount; - // 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. + // 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. @@ -236,10 +226,10 @@ The contract terms v1 will have the following structure: // once the contract is paid. outputs: ContractOutput[]; + // 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,23 +248,24 @@ 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 - // 'token_families' map on the top-level. + // '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 @@ -288,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. @@ -298,50 +287,41 @@ 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 // 'token_families' map on the top-level. token_family_slug: string; - // Start of the validity period of the token. + // 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 yelded. + // 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 @@ -350,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 @@ -368,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; @@ -387,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? @@ -408,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 TokenSignerPublicKeyGroup = - | TokenSignerPublicKeyGroupRsa - | TokenSignerPublicKeyGroupCs; + type TokenIssuePublicKey = + | TokenIssueRsaPublicKey + | TokenIssueCsPublicKey; -.. 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; } |