diff options
Diffstat (limited to 'design-documents/046-mumimo-contracts.rst')
| -rw-r--r-- | design-documents/046-mumimo-contracts.rst | 172 |
1 files changed, 68 insertions, 104 deletions
diff --git a/design-documents/046-mumimo-contracts.rst b/design-documents/046-mumimo-contracts.rst index 5bc3d25a..714b5822 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 ================= @@ -145,6 +143,33 @@ The contract terms v1 will have the following structure: // More info about the merchant (same as in v0). merchant: Merchant; + // Human-readable description of the contract. + summary: string; + + // Map from IETF BCP 47 language tags to localized summaries. + summary_i18n?: { [lang_tag: string]: string }; + + // URL that will show that the order was successful after + // it has been paid for. Optional. When POSTing to the + // merchant, the placeholder "${ORDER_ID}" will be + // replaced with the actual order ID (useful if the + // order ID is generated server-side and needs to be + // in the URL). + // Note that this placeholder can only be used once. + // Either fulfillment_url or fulfillment_message must be specified. + fulfillment_url?: string; + + // Message shown to the customer after paying for the order. + // Either fulfillment_url or fulfillment_message must be specified. + fulfillment_message?: string; + + // Map from IETF BCP 47 language tags to localized fulfillment + // messages. + fulfillment_message_i18n?: { [lang_tag: string]: string }; + + // List of products that are part of the purchase (see `Product`). + products: Product[]; + // After this deadline has passed, no refunds will be accepted. refund_deadline: Timestamp; @@ -184,83 +209,27 @@ The contract terms v1 will have the following structure: // signing the deposit confirmation. choices: ContractChoice[]; + // Map from authority labels to meta data about the + // respective token authority. + token_types: { [authority_label: string]: TokenAuthority }; + // 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; - // Fee limits and wire account details by currency. - limits: { [currency:string] : CurrencyLimit }; - } - -.. ts:def:: CurrencyLimit - - interface CurrencyLimit { - - // The hash of the merchant instance's wire details. - h_wire: HashCode; - - // Wire transfer method identifier for the wire method associated with ``h_wire``. - // The wallet may only select exchanges via a matching auditor if the - // exchange also supports this wire method. - // The wire transfer fees must be added based on this wire transfer method. - wire_method: string; - // Maximum total deposit fee accepted by the merchant for this contract. max_fee: Amount; - // 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; - - // Over how many customer transactions does the merchant expect to - // amortize wire fees on average? If the exchange's wire fee is - // above ``max_wire_fee``, the difference is divided by this number - // to compute the expected customer's contribution to the wire fee. - // The customer's contribution may further be reduced by the difference - // 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; - // Exchanges that the merchant accepts for this currency. exchanges: Exchange[]; } - .. ts:def:: ContractChoice interface ContractChoice { - // Human-readable description of the choice. - summary: string; - - // Map from IETF BCP 47 language tags to localized summaries. - summary_i18n?: { [lang_tag: string]: string }; - - // URL that will show that the order was successful after - // it has been paid for. Optional. When POSTing to the - // merchant, the placeholder "${ORDER_ID}" will be - // replaced with the actual order ID (useful if the - // order ID is generated server-side and needs to be - // in the URL). - // Note that this placeholder can only be used once. - // Either fulfillment_url or fulfillment_message must be specified. - fulfillment_url?: string; - - // Message shown to the customer after paying for the order. - // Either fulfillment_url or fulfillment_message must be specified. - fulfillment_message?: string; - - // Map from IETF BCP 47 language tags to localized fulfillment - // messages. - fulfillment_message_i18n?: { [lang_tag: string]: string }; - - // List of products that are part of the purchase (see `Product`). - products: Product[]; - // List of inputs the wallet must provision (all of them) to // satisfy the conditions for the contract. inputs: ContractInput[]; @@ -269,17 +238,13 @@ The contract terms v1 will have the following structure: // once the contract is paid. outputs: ContractOutput[]; - // Map from authority labels to meta data abou the - // respective token authority. - token_types: { [authority_label: TokenAuthority }; - } .. ts:def:: ContractInput type ContractInput = - | ContractInputRation - | ContractInputToken; + ContractInputRation | + ContractInputToken; .. ts:def:: ContractInputRation @@ -305,9 +270,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 +283,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 +325,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 +358,9 @@ The contract terms v1 will have the following structure: }; -.. ts:def:: OutputTokenClassDiscount +.. ts:def:: TokenClassDiscount - interface OutputTokenClassDiscount { + interface TokenClassDiscount { class: "discount"; @@ -433,6 +395,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 +421,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. @@ -472,10 +441,7 @@ consumes an available discount token, that contract should be moved up in the list. Which specific alternative contract was chosen by the user is indicated in the -subcontract index field of the :ref:`TALER_DepositRequestPS`. - -FIXME-DOLD: Should we also sign over this in the -:ref:`TALER_DepositConfirmationPS`? +subcontract index field of the :ref:`TALER_DepositRequestPS <taler_depositrequestps>`. Output Commitments @@ -483,8 +449,9 @@ Output Commitments When a contract has outputs, the wallet must send an array of blinded tokens, coins or tax receipts together with the payment request. The order in the -array must match the order in the outputs field of the contract. For currency outputs, one array element must include all of the required planchets for a batch withdrawal, -but of course not the reserve signature. +array must match the order in the outputs field of the contract. For currency +outputs, one array element must include all of the required planchets for a +batch withdrawal, but of course not the reserve signature. .. note:: @@ -492,10 +459,7 @@ but of course not the reserve signature. batch-withdraw API to only use a single reserve signature. This array of blinded values is hashed to create the output commitment hash -(``h_outputs``) in the :ref:`TALER_DepositRequestPS`. - -FIXME-DOLD: Should we also sign over this in the -:ref:`TALER_DepositConfirmationPS`? +(``h_outputs``) in the :ref:`TALER_DepositRequestPS <taler_depositrequestps>`. |