commit f060f500b5453502fcf42eafc199a39ce7220a4b parent 64b4f06b57c70d4e0fa6feab81ec20f155e0b9c2 Author: Florian Dold <dold@taler.net> Date: Tue, 10 Nov 2026 19:26:44 +0100 docs: remove unintended block quotes Diffstat:
45 files changed, 1361 insertions(+), 1359 deletions(-)
diff --git a/core/api-auditor.rst b/core/api-auditor.rst @@ -120,14 +120,14 @@ PATCH request. **Details:** - .. ts:def:: GenericAuditorMonitorPatchRequest +.. ts:def:: GenericAuditorMonitorPatchRequest - interface GenericAuditorMonitorPatchRequest { + interface GenericAuditorMonitorPatchRequest { - // If true, subsequent GET requests will not return this element by default - suppressed : boolean; + // If true, subsequent GET requests will not return this element by default + suppressed : boolean; - } + } .. _fee-time-inconsistency-list: diff --git a/core/api-exchange.rst b/core/api-exchange.rst @@ -619,9 +619,9 @@ Wallet-to-wallet transfers Wads ---- - .. note:: +.. note:: - This is a draft API that is not yet implemented. + This is a draft API that is not yet implemented. These endpoints are used to manage exchange-to-exchange payments in support of @@ -702,9 +702,9 @@ the identity of the person sending an invoice to the payer, and to (4) close a reserve before it would naturally expire and possibly (5) wire the funds to a designated account. - .. note:: +.. note:: - This section is about a proposed API. It is not implemented. See also DD 31. + This section is about a proposed API. It is not implemented. See also DD 31. .. include:: exchange/post-reserves-RESERVE_PUB-open.rst diff --git a/core/api-merchant.rst b/core/api-merchant.rst @@ -539,12 +539,12 @@ the challenges and completing or retrying the protected request. They must not attach challenge IDs to unrelated requests or reuse them for another instance, operation, or request body. - .. note:: +.. note:: - If all allowed attempts to solve the MFA challenge(s) fail, the endpoint - may start to return ``403 Forbidden`` until the issued challenges expire, - preventing the request from being completed for a while. In this case, - repeating the request with a different body may still be allowed! + If all allowed attempts to solve the MFA challenge(s) fail, the endpoint + may start to return ``403 Forbidden`` until the issued challenges expire, + preventing the request from being completed for a while. In this case, + repeating the request with a different body may still be allowed! .. ts:def:: ChallengeResponse @@ -1424,266 +1424,266 @@ The template contract is like the most raw form where many choices are still open or deferred. - .. ts:def:: TemplateContractDetails - - type TemplateContractDetails = (TemplateContractFixedOrder | TemplateContractInventoryCart | TemplateContractPaivana) & TemplateContractCommon; - - .. ts:def:: TemplateContractCommon - - interface TemplateContractCommon { - // Template type to apply. Defaults to "fixed-order" if omitted. - // Prescribes which interface has to be followed - // Since protocol **v25**. - template_type?: TemplateType; - - // Human-readable summary for the template. - summary?: string; - - // Required currency for payments to the template. - // This parameter is optional and should not be present - // if "amount" is given. - currency?: string; +.. ts:def:: TemplateContractDetails - // Lower bound (inclusive) on amounts the client gets to choose - // when instantiating this template. Excludes any tip. Only - // amounts the client had an influence on are checked against - // this bound: the amount given in the request for a "fixed-order" - // template, the total of the selected products for an - // "inventory-cart" template, and the amount of an editable choice - // for a "paivana" template. Requires "currency" to be given and - // to match, must be in the same currency as "max_amount", and - // must not exceed it. - // Since protocol **v34**. - min_amount?: Amount; + type TemplateContractDetails = (TemplateContractFixedOrder | TemplateContractInventoryCart | TemplateContractPaivana) & TemplateContractCommon; - // Upper bound (inclusive) on amounts the client gets to choose - // when instantiating this template. Excludes any tip. Checked - // against the same amounts as "min_amount". Requires "currency" - // to be given and to match. - // Since protocol **v34**. - max_amount?: Amount; +.. ts:def:: TemplateContractCommon - // Time available to pay before the order expires unpaid. If omitted or - // zero, the instance's default pay delay is used. "forever" is invalid. - pay_duration?: RelativeTime; - - // How long will customers have to access / read / pick-up - // the resource they are buying? Will turn into - // max_pickup_time in the contract for every template type, - // measured from order creation (not from payment or a repeat visit). - // Optional; if omitted or "forever", access has no deadline. - // Zero gives an immediately expired access window. - // Since protocol **v29**. - max_pickup_duration?: RelativeTime; - - // Minimum age buyer must have (in years). Default is 0. - minimum_age?: Integer; - - // Inventory-cart: request a tip during instantiation. - // Since protocol **v25**. - request_tip?: boolean; - } - - .. ts:def:: TemplateType + interface TemplateContractCommon { + // Template type to apply. Defaults to "fixed-order" if omitted. + // Prescribes which interface has to be followed + // Since protocol **v25**. + template_type?: TemplateType; + + // Human-readable summary for the template. + summary?: string; + + // Required currency for payments to the template. + // This parameter is optional and should not be present + // if "amount" is given. + currency?: string; + + // Lower bound (inclusive) on amounts the client gets to choose + // when instantiating this template. Excludes any tip. Only + // amounts the client had an influence on are checked against + // this bound: the amount given in the request for a "fixed-order" + // template, the total of the selected products for an + // "inventory-cart" template, and the amount of an editable choice + // for a "paivana" template. Requires "currency" to be given and + // to match, must be in the same currency as "max_amount", and + // must not exceed it. + // Since protocol **v34**. + min_amount?: Amount; + + // Upper bound (inclusive) on amounts the client gets to choose + // when instantiating this template. Excludes any tip. Checked + // against the same amounts as "min_amount". Requires "currency" + // to be given and to match. + // Since protocol **v34**. + max_amount?: Amount; + + // Time available to pay before the order expires unpaid. If omitted or + // zero, the instance's default pay delay is used. "forever" is invalid. + pay_duration?: RelativeTime; + + // How long will customers have to access / read / pick-up + // the resource they are buying? Will turn into + // max_pickup_time in the contract for every template type, + // measured from order creation (not from payment or a repeat visit). + // Optional; if omitted or "forever", access has no deadline. + // Zero gives an immediately expired access window. + // Since protocol **v29**. + max_pickup_duration?: RelativeTime; + + // Minimum age buyer must have (in years). Default is 0. + minimum_age?: Integer; - enum TemplateType { - FIXED_ORDER = "fixed-order", - INVENTORY_CART = "inventory-cart", - PAIVANA = "paivana" - } + // Inventory-cart: request a tip during instantiation. + // Since protocol **v25**. + request_tip?: boolean; + } - .. ts:def:: TemplateContractFixedOrder +.. ts:def:: TemplateType - interface TemplateContractFixedOrder { + enum TemplateType { + FIXED_ORDER = "fixed-order", + INVENTORY_CART = "inventory-cart", + PAIVANA = "paivana" + } - // The price is imposed by the merchant and cannot be changed by the customer. - // This parameter is optional. - amount?: Amount; +.. ts:def:: TemplateContractFixedOrder - } + interface TemplateContractFixedOrder { - .. ts:def:: TemplateContractInventoryCart + // The price is imposed by the merchant and cannot be changed by the customer. + // This parameter is optional. + amount?: Amount; - interface TemplateContractInventoryCart { + } - // Inventory-cart: allow any inventory item to be selected. - // Since protocol **v25**. - selected_all?: boolean; +.. ts:def:: TemplateContractInventoryCart - // Inventory-cart: only products in these categories are selectable. - // Since protocol **v25**. - selected_categories?: Integer[]; + interface TemplateContractInventoryCart { - // Inventory-cart: only these products are selectable. - // Since protocol **v25**. - selected_products?: string[]; + // Inventory-cart: allow any inventory item to be selected. + // Since protocol **v25**. + selected_all?: boolean; - // Inventory-cart: require exactly one selection entry. - // Since protocol **v25**. - choose_one?: boolean; + // Inventory-cart: only products in these categories are selectable. + // Since protocol **v25**. + selected_categories?: Integer[]; - // Inventory-cart: backend-provided payload with selectable data. - // Only present in ``GET /templates/$TEMPLATE_ID`` responses. - // Since protocol **v25**. - inventory_payload?: InventoryPayload; - } + // Inventory-cart: only these products are selectable. + // Since protocol **v25**. + selected_products?: string[]; - .. ts:def:: TemplateContractPaivana + // Inventory-cart: require exactly one selection entry. + // Since protocol **v25**. + choose_one?: boolean; - interface TemplateContractPaivana { + // Inventory-cart: backend-provided payload with selectable data. + // Only present in ``GET /templates/$TEMPLATE_ID`` responses. + // Since protocol **v25**. + inventory_payload?: InventoryPayload; + } - // POSIX extended regular expression over URLs for which - // this template is valid. Matched against the absolute - // URL, and anchored: it must match that URL in its - // entirety, not merely occur within it. - // Optional, if not given all URLs are accepted. - // Since protocol **v25**. - website_regex?: string; +.. ts:def:: TemplateContractPaivana - // Methods to pay for the contract. - choices: TemplateOrderChoice[]; - } + interface TemplateContractPaivana { - The backend only stores ``website_regex``; it is the paywall proxy - reading these templates that evaluates it. ``paivana-httpd`` matches - it against the **absolute** URL of the request (``BASE_URL`` or the - scheme and ``Host`` of the request, followed by the path) and anchors - it, so an expression written against the path alone, or meant as a - substring rule, will not apply. See :ref:`Paivana-Templates` in the - :doc:`Paivana operator manual <../taler-paivana-manual>` for the - matching rules and worked examples. - - If exactly one of the ``choices`` of a Paivana template has - ``editable_amount`` set, the template may also carry an ``amount`` in its - ``editable_defaults`` to tell the user interface to offer a single amount - field with that default; the client then submits it as the ``amount`` of - the `UsingTemplateCommonRequest`. With more than one editable choice, the - defaults are the ``amount`` values of the choices themselves and the client - must use ``choice_amounts``. + // POSIX extended regular expression over URLs for which + // this template is valid. Matched against the absolute + // URL, and anchored: it must match that URL in its + // entirety, not merely occur within it. + // Optional, if not given all URLs are accepted. + // Since protocol **v25**. + website_regex?: string; + + // Methods to pay for the contract. + choices: TemplateOrderChoice[]; + } + +The backend only stores ``website_regex``; it is the paywall proxy +reading these templates that evaluates it. ``paivana-httpd`` matches +it against the **absolute** URL of the request (``BASE_URL`` or the +scheme and ``Host`` of the request, followed by the path) and anchors +it, so an expression written against the path alone, or meant as a +substring rule, will not apply. See :ref:`Paivana-Templates` in the +:doc:`Paivana operator manual <../taler-paivana-manual>` for the +matching rules and worked examples. + +If exactly one of the ``choices`` of a Paivana template has +``editable_amount`` set, the template may also carry an ``amount`` in its +``editable_defaults`` to tell the user interface to offer a single amount +field with that default; the client then submits it as the ``amount`` of +the `UsingTemplateCommonRequest`. With more than one editable choice, the +defaults are the ``amount`` values of the choices themselves and the client +must use ``choice_amounts``. .. _template-choice: Template Choices ^^^^^^^^^^^^^^^^ - The `OrderChoice` object describes a possible choice within an order. The - choice is done by the wallet and consists of in- and outputs. In the example - of buying an article, the merchant could present the customer with the - choice to use a valid subscription token or pay using a gift - voucher. Available since protocol **v21**. - - .. ts:def:: OrderChoice - - interface OrderChoice { - // Total price for the choice. The exchange will subtract deposit - // fees from that amount before transferring it to the merchant. - amount: Amount; +The `OrderChoice` object describes a possible choice within an order. The +choice is done by the wallet and consists of in- and outputs. In the example +of buying an article, the merchant could present the customer with the +choice to use a valid subscription token or pay using a gift +voucher. Available since protocol **v21**. - // Optional tip amount. Must match the currency of ``amount``. - // Since protocol **v25**. - tip?: Amount; +.. ts:def:: OrderChoice - // Human readable description of the semantics of the choice - // within the contract to be shown to the user at payment. - description?: string; + interface OrderChoice { + // Total price for the choice. The exchange will subtract deposit + // fees from that amount before transferring it to the merchant. + amount: Amount; - // Map from IETF 47 language tags to localized descriptions. - description_i18n?: { [lang_tag: string]: string }; + // Optional tip amount. Must match the currency of ``amount``. + // Since protocol **v25**. + tip?: Amount; - // Inputs that must be provided by the customer, if this choice is selected. - // Defaults to empty array if not specified. - inputs?: OrderInput[]; + // Human readable description of the semantics of the choice + // within the contract to be shown to the user at payment. + description?: string; - // Outputs provided by the merchant, if this choice is selected. - // Defaults to empty array if not specified. - outputs?: OrderOutput[]; + // Map from IETF 47 language tags to localized descriptions. + description_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; - } + // Inputs that must be provided by the customer, if this choice is selected. + // Defaults to empty array if not specified. + inputs?: OrderInput[]; - A choice of a *template* contract may additionally allow the client to - replace the amount when the template is instantiated. + // Outputs provided by the merchant, if this choice is selected. + // Defaults to empty array if not specified. + outputs?: OrderOutput[]; - .. ts:def:: TemplateOrderChoice + // Maximum total deposit fee accepted by the merchant for this contract. + // Overrides defaults of the merchant instance. + max_fee?: Amount; + } - interface TemplateOrderChoice extends OrderChoice { - // If true, the client may replace "amount" when instantiating - // the template; "amount" then merely provides the default. The - // client may only change the value, never the currency. The - // resulting amount is subject to the "min_amount" and - // "max_amount" bounds of the template (if any). - // Defaults to false, in which case the amount is fixed by the - // merchant. - // Since protocol **v34**. - editable_amount?: boolean; - } +A choice of a *template* contract may additionally allow the client to +replace the amount when the template is instantiated. + +.. ts:def:: TemplateOrderChoice + + interface TemplateOrderChoice extends OrderChoice { + // If true, the client may replace "amount" when instantiating + // the template; "amount" then merely provides the default. The + // client may only change the value, never the currency. The + // resulting amount is subject to the "min_amount" and + // "max_amount" bounds of the template (if any). + // Defaults to false, in which case the amount is fixed by the + // merchant. + // Since protocol **v34**. + editable_amount?: boolean; + } - .. ts:def:: OrderInput +.. ts:def:: OrderInput - // For now, only token inputs are supported. - type OrderInput = OrderInputToken; + // For now, only token inputs are supported. + type OrderInput = OrderInputToken; - .. ts:def:: OrderInputToken +.. ts:def:: OrderInputToken - interface OrderInputToken { + interface OrderInputToken { - // Token input. - type: "token"; + // Token input. + type: "token"; - // Token family slug as configured in the merchant backend. Slug is unique - // across all configured tokens of a merchant. - token_family_slug: Slug; + // Token family slug as configured in the merchant backend. Slug is unique + // across all configured tokens of a merchant. + token_family_slug: Slug; - // How many units of the input are required. - // Defaults to 1 if not specified. Output with count == 0 are ignored by - // the merchant backend. - count?: Integer; + // How many units of the input are required. + // Defaults to 1 if not specified. Output with count == 0 are ignored by + // the merchant backend. + count?: Integer; - } + } - .. ts:def:: OrderOutput +.. ts:def:: OrderOutput - type OrderOutput = OrderOutputToken | OrderOutputTaxReceipt; + type OrderOutput = OrderOutputToken | OrderOutputTaxReceipt; - .. ts:def:: OrderOutputToken +.. ts:def:: OrderOutputToken - interface OrderOutputToken { + interface OrderOutputToken { - // Token output. - type: "token"; + // Token output. + type: "token"; - // Token family slug as configured in the merchant backend. Slug is unique - // across all configured tokens of a merchant. - token_family_slug: Slug; + // Token family slug as configured in the merchant backend. Slug is unique + // across all configured tokens of a merchant. + token_family_slug: Slug; - // How many units of the output are issued by the merchant. - // Defaults to 1 if not specified. Output with count == 0 are ignored by - // the merchant backend. - count?: Integer; + // How many units of the output are issued by the merchant. + // Defaults to 1 if not specified. Output with count == 0 are ignored by + // the merchant backend. + count?: Integer; - // When should the output token be valid. Can be specified if the - // desired validity period should be in the future (like selling - // a subscription for the next month). Optional. If not given, - // the validity is supposed to be "now" (time of order creation). - valid_at?: Timestamp; + // When should the output token be valid. Can be specified if the + // desired validity period should be in the future (like selling + // a subscription for the next month). Optional. If not given, + // the validity is supposed to be "now" (time of order creation). + valid_at?: Timestamp; - } + } - .. ts:def:: OrderOutputTaxReceipt +.. ts:def:: OrderOutputTaxReceipt - interface OrderOutputTaxReceipt { + interface OrderOutputTaxReceipt { - // Tax receipt output. - type: "tax-receipt"; + // Tax receipt output. + type: "tax-receipt"; - // Donation amount. Useful if the donation is only for - // part of the total. - // Optional, if not given the purchase total amount is - // assumed to be the donation amount. - amount?: Amount; - } + // Donation amount. Useful if the donation is only for + // part of the total. + // Optional, if not given the purchase total amount is + // assumed to be the donation amount. + amount?: Amount; + } .. _contract-base-terms: @@ -1814,120 +1814,120 @@ and basically present (or optional) all the time. Orders ^^^^^^ - The `Order` object represents the starting point for new `ContractTerms`. - After validating and sanitizing all inputs, the merchant backend will add - additional information to the order and create a new `ContractTerms` object - that will be stored in the database. - - .. ts:def:: Order +The `Order` object represents the starting point for new `ContractTerms`. +After validating and sanitizing all inputs, the merchant backend will add +additional information to the order and create a new `ContractTerms` object +that will be stored in the database. - type Order = ContractBaseTerms & (OrderV0 | OrderV1) & OrderCommon; +.. ts:def:: Order - .. ts:def:: OrderV0 + type Order = ContractBaseTerms & (OrderV0 | OrderV1) & OrderCommon; - interface OrderV0 { - // Optional, defaults to 0 if not set. - version?: 0; +.. ts:def:: OrderV0 - // Total price for the transaction, including tip. The exchange will - // subtract deposit fees from that amount before transferring it to - // the merchant. - amount: Amount; + interface OrderV0 { + // Optional, defaults to 0 if not set. + version?: 0; - // Optional tip amount. Must match the currency of ``amount``. - // Since protocol **v25**. - tip?: Amount; + // Total price for the transaction, including tip. 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; - } + // Optional tip amount. Must match the currency of ``amount``. + // Since protocol **v25**. + tip?: Amount; - .. ts:def:: OrderV1 + // Maximum total deposit fee accepted by the merchant for this contract. + // Overrides defaults of the merchant instance. + max_fee?: Amount; + } - interface OrderV1 { - // Version 1 order support discounts and subscriptions. - // https://docs.taler.net/design-documents/046-mumimo-contracts.html - // @since protocol **v21** - version: 1; +.. ts:def:: OrderV1 - // List of contract choices that the customer can select from. - // @since protocol **v21** - choices: OrderChoice[]; - } + interface OrderV1 { + // Version 1 order support discounts and subscriptions. + // https://docs.taler.net/design-documents/046-mumimo-contracts.html + // @since protocol **v21** + version: 1; + // List of contract choices that the customer can select from. + // @since protocol **v21** + choices: OrderChoice[]; + } - .. ts:def:: OrderCommon - interface OrderCommon { +.. ts:def:: OrderCommon - // List of products that are part of the purchase. - products?: ProductEntry[]; + interface OrderCommon { - // After this deadline has passed, no refunds will be accepted. - // Overrides deadline calculated from ``refund_delay`` in - // `PostOrderRequest`. - // A value of "never" is not allowed. - refund_deadline?: Timestamp; + // List of products that are part of the purchase. + products?: ProductEntry[]; - // After this deadline, the merchant won't accept payments for the contract. - // Overrides deadline calculated from default pay delay configured in - // merchant backend. - // A value of "never" is not allowed. - pay_deadline?: Timestamp; + // After this deadline has passed, no refunds will be accepted. + // Overrides deadline calculated from ``refund_delay`` in + // `PostOrderRequest`. + // A value of "never" is not allowed. + refund_deadline?: Timestamp; - // Transfer deadline for the exchange. Must be in the deposit permissions - // of coins used to pay for this order. - // Overrides deadline calculated from default wire transfer delay - // configured in merchant backend. Must be after refund deadline. - // A value of "never" is not allowed. - wire_transfer_deadline?: Timestamp; + // After this deadline, the merchant won't accept payments for the contract. + // Overrides deadline calculated from default pay delay configured in + // merchant backend. + // A value of "never" is not allowed. + pay_deadline?: Timestamp; + + // Transfer deadline for the exchange. Must be in the deposit permissions + // of coins used to pay for this order. + // Overrides deadline calculated from default wire transfer delay + // configured in merchant backend. Must be after refund deadline. + // A value of "never" is not allowed. + wire_transfer_deadline?: Timestamp; - // Payments for this order that were settled outside of Taler, - // for example in cash or by card. The ``amount`` field above (or - // the selected choice's ``amount`` for v1 orders) remains the - // amount paid with Taler; the full order total is the sum of that - // amount and all entries here. If present, all entries and (for - // v1 orders) all choices must use the currency of the Taler - // ``amount``. Never contains a ``taler`` entry. - // @since protocol **v42**. - amount_external?: ExternalPaymentInfo[]; + // Payments for this order that were settled outside of Taler, + // for example in cash or by card. The ``amount`` field above (or + // the selected choice's ``amount`` for v1 orders) remains the + // amount paid with Taler; the full order total is the sum of that + // amount and all entries here. If present, all entries and (for + // v1 orders) all choices must use the currency of the Taler + // ``amount``. Never contains a ``taler`` entry. + // @since protocol **v42**. + amount_external?: ExternalPaymentInfo[]; - } + } - .. ts:def:: ExternalPaymentInfo +.. ts:def:: ExternalPaymentInfo - interface ExternalPaymentInfo { - // External payment method, for example "cash" or "card". - // Must be a stable, non-empty identifier of ASCII - // alphanumerics and "-", and must never be "taler". - method: string; + interface ExternalPaymentInfo { + // External payment method, for example "cash" or "card". + // Must be a stable, non-empty identifier of ASCII + // alphanumerics and "-", and must never be "taler". + method: string; - // Identifier of the payment action within the order, unique - // among the entries of this ``amount_external`` array. - // Examples: "cash1", "card1", "card2". - id: string; + // Identifier of the payment action within the order, unique + // among the entries of this ``amount_external`` array. + // Examples: "cash1", "card1", "card2". + id: string; - // Amount covered by this payment action. Must use the same - // currency as the Taler ``amount`` of the order. - amount: Amount; + // Amount covered by this payment action. Must use the same + // currency as the Taler ``amount`` of the order. + amount: Amount; - // Additional method-specific fields for reconciliation or audit, - // for example a cashier number, terminal identifier or - // authorization code. These must be flat scalar values (no - // nested objects or arrays) so that the merchant portal can - // render ``amount_external`` as a generic table. - [field: string]: string | Amount | Integer | boolean | null; - } + // Additional method-specific fields for reconciliation or audit, + // for example a cashier number, terminal identifier or + // authorization code. These must be flat scalar values (no + // nested objects or arrays) so that the merchant portal can + // render ``amount_external`` as a generic table. + [field: string]: string | Amount | Integer | boolean | null; + } .. _product-entry: Product entries ^^^^^^^^^^^^^^^ - .. ts:def:: ProductEntry +.. ts:def:: ProductEntry - type ProductEntry = (ProductSold | MinimalInventoryProduct); + type ProductEntry = (ProductSold | MinimalInventoryProduct); The following `MinimalInventoryProduct` can be provided if the parts of the @@ -1942,31 +1942,31 @@ that the backend will NOT update the ``amount`` of the ``order``, so the frontend must already have calculated the total price --- including the ``inventory_products``. - .. ts:def:: MinimalInventoryProduct +.. ts:def:: MinimalInventoryProduct - // Note that if the frontend does give details beyond these, - // it will override those details (including price or taxes) - // that the backend would otherwise fill in via the inventory. - interface MinimalInventoryProduct { + // Note that if the frontend does give details beyond these, + // it will override those details (including price or taxes) + // that the backend would otherwise fill in via the inventory. + interface MinimalInventoryProduct { - // Which product is requested (here mandatory!). - product_id: Slug; + // Which product is requested (here mandatory!). + product_id: Slug; - // Legacy integer quantity. - // Deprecated since **v25**; - // defaults to 1 if both ``quantity`` and ``unit_quantity`` are absent. - quantity?: Integer; + // Legacy integer quantity. + // Deprecated since **v25**; + // defaults to 1 if both ``quantity`` and ``unit_quantity`` are absent. + quantity?: Integer; - // Preferred quantity string using "<integer>[.<fraction>]" syntax. - // @since **v25**; - unit_quantity?: string + // Preferred quantity string using "<integer>[.<fraction>]" syntax. + // @since **v25**; + unit_quantity?: string - // Money pot to use for this product, overrides value from - // the inventory if given. - // Since **v25**. - product_money_pot?: Integer; + // Money pot to use for this product, overrides value from + // the inventory if given. + // Since **v25**. + product_money_pot?: Integer; - } + } Clients must supply either ``quantity`` or ``unit_quantity`` when referencing inventory products. If both are missing the backend assumes a quantity of diff --git a/core/donau/get-charity-CHARITY_ID.rst b/core/donau/get-charity-CHARITY_ID.rst @@ -7,7 +7,6 @@ **Request:** *Charity-Signature*: - The client must provide Base-32 encoded EdDSA signature with ``$CHARITY_PRIV``, affirming the desire to obtain the charity status. Note that this is merely a simple authentication mechanism, diff --git a/core/exchange/get-contracts-CONTRACT_PUB.rst b/core/exchange/get-contracts-CONTRACT_PUB.rst @@ -21,17 +21,17 @@ **Details:** - .. ts:def:: ExchangeContractResponse + .. ts:def:: ExchangeContractResponse - interface ExchangeContractResponse { + interface ExchangeContractResponse { - // Public key of the purse into which payments must be - // made for this contract. - purse_pub: PursePublicKey; + // Public key of the purse into which payments must be + // made for this contract. + purse_pub: PursePublicKey; - // Signature over the contract - econtract_sig: PurseContractSignature; + // Signature over the contract + econtract_sig: PurseContractSignature; - // Encrypted contract. - econtract: EncryptedContract; - } + // Encrypted contract. + econtract: EncryptedContract; + } diff --git a/core/merchant/delete-private-token.rst b/core/merchant/delete-private-token.rst @@ -1,6 +1,6 @@ .. http:delete:: [/instances/$INSTANCE]/private/token - Delete the token presented in the authorization header. + Delete the token presented in the authorization header. **Required permission:** none; any client may revoke the access token it presents. diff --git a/core/merchant/delete-private-transfers-TID.rst b/core/merchant/delete-private-transfers-TID.rst @@ -1,7 +1,7 @@ .. http:delete:: [/instances/$INSTANCE]/private/transfers/$TID - Here, the TID is the 'transfer_serial_id' of the transfer - to delete. + Here, the TID is the 'transfer_serial_id' of the transfer + to delete. **Required permission:** ``transfers-write`` (see :ref:`Scopes <merchant-api-scopes>`) diff --git a/core/merchant/get-private-statistics-counter-SLUG.rst b/core/merchant/get-private-statistics-counter-SLUG.rst @@ -10,7 +10,7 @@ **Request:** - :query by: *Optional*. If set to "BUCKET", only statistics by bucket will be returned. If set to "INTERVAL", only statistics kept by interval will be returned. If not set or set to "ANY", both will be returned. + :query by: *Optional*. If set to "BUCKET", only statistics by bucket will be returned. If set to "INTERVAL", only statistics kept by interval will be returned. If not set or set to "ANY", both will be returned. **Response:** diff --git a/core/merchant/get-private-statistics-report-NAME.rst b/core/merchant/get-private-statistics-report-NAME.rst @@ -5,16 +5,16 @@ **MAY** support generating the report in various formats. The currently implemented value is: - * "transactions" (total revenue, total refunds, fees - as well as number of transactions), since **v25** + * "transactions" (total revenue, total refunds, fees + as well as number of transactions), since **v25** Reserved names for upcoming report implementations are: - * "money-pots" (changes to totals in money pots), - * "taxes" (amount of taxes withheld by tax class), planned for - **vTAXES**, - * "sales-funnel" (number and volume of orders - created, claimed, paid, refunded and settled). + * "money-pots" (changes to totals in money pots), + * "taxes" (amount of taxes withheld by tax class), planned for + **vTAXES**, + * "sales-funnel" (number and volume of orders + created, claimed, paid, refunded and settled). The overall endpoint family exists since protocol **v25**. @@ -27,11 +27,11 @@ Supported are the usual "application/json", but also "application/pdf". - :query granularity: *Optional*. Determines the bucket granularity - to return. Accepted are "hour", "day", "week", - "month", "quarter" and "year". Defaults to "month". - :query count: *Optional*. Number of buckets to return. Defaults depends - on the granularity. + :query granularity: *Optional*. Determines the bucket granularity + to return. Accepted are "hour", "day", "week", + "month", "quarter" and "year". Defaults to "month". + :query count: *Optional*. Number of buckets to return. Defaults depends + on the granularity. **Response:** diff --git a/core/merchant/patch-private-categories-CATEGORY_ID.rst b/core/merchant/patch-private-categories-CATEGORY_ID.rst @@ -7,7 +7,7 @@ **Request:** - The request is a `CategoryPatchRequest`. + The request is a `CategoryPatchRequest`. **Response:** diff --git a/core/merchant/post-private-accept-tos-early.rst b/core/merchant/post-private-accept-tos-early.rst @@ -17,7 +17,7 @@ **Request:** - The request body is a `TosAcceptedEarlyRequest`. + The request body is a `TosAcceptedEarlyRequest`. **Response:** diff --git a/core/merchant/post-private-accounts-H_WIRE-kycauth.rst b/core/merchant/post-private-accounts-H_WIRE-kycauth.rst @@ -19,7 +19,7 @@ **Request:** - The request must provide `exchange information <KycAuthExchangeSelectionRequest>`. + The request must provide `exchange information <KycAuthExchangeSelectionRequest>`. **Response:** diff --git a/core/merchant/post-private-categories.rst b/core/merchant/post-private-categories.rst @@ -7,7 +7,7 @@ **Request:** - The request is a `CategoryCreateRequest`. + The request is a `CategoryCreateRequest`. **Response:** diff --git a/core/merchant/post-private-transfers.rst b/core/merchant/post-private-transfers.rst @@ -9,7 +9,7 @@ **Request:** - The request must provide `transfer information <TransferInformation>`. + The request must provide `transfer information <TransferInformation>`. **Response:** diff --git a/deployments/tops.rst b/deployments/tops.rst @@ -2272,10 +2272,10 @@ properties and events from the filled-in form attributes. The AML Officer can ch * Assumptions: - * Properties are always calculated only based on new attributes and the previous properties. They are never calculated - from older attribute collections or the current rules. - * The AML officer can always override derived properties or events. - * In the future, we might derive *rules* from properties, but we don't do that right now. + * Properties are always calculated only based on new attributes and the previous properties. They are never calculated + from older attribute collections or the current rules. + * The AML officer can always override derived properties or events. + * In the future, we might derive *rules* from properties, but we don't do that right now. The derivation is defined in pseudo-code. The following special variables/functions are available: diff --git a/design-documents/015-merchant-backoffice-routing.rst b/design-documents/015-merchant-backoffice-routing.rst @@ -112,18 +112,18 @@ parameter (like order id or product id) it should be accessible from the Sidebar If the user has admin access, this entry points are available: - - /instances: Show the list of instances currently created - - /instance/new: Show an instance creation form +- /instances: Show the list of instances currently created +- /instance/new: Show an instance creation form Where admin or not, there is also this entry points: - - / : redirects to the instance settings page - - /update: instance setting page, renders a form and allow modifying it - - /products: list of instance products - - /product/$ID/update: product modification page - - /product/new : product creation page - - /orders : list of instance orders - - /transfers : list of transfers +- / : redirects to the instance settings page +- /update: instance setting page, renders a form and allow modifying it +- /products: list of instance products +- /product/$ID/update: product modification page +- /product/new : product creation page +- /orders : list of instance orders +- /transfers : list of transfers As an example: diff --git a/design-documents/023-taler-kyc.rst b/design-documents/023-taler-kyc.rst @@ -483,7 +483,6 @@ New endpoints **Request:** *Account-Owner-Signature*: - The client must provide Base-32 encoded EdDSA signature with ``$ACCOUNT_PRIV``, affirming the desire to obtain KYC data. Note that this is merely a simple authentication mechanism, the details of the @@ -1584,12 +1583,14 @@ expiration on ``success`` and also updates ``provider_user_id`` and For the webhook, we need a way to lookup ``h_payto`` by other data, so the KYC logic plugin API should be provided a method lookup with: - - inputs: - + ``provider_section`` - + ``provider_legitimization_id`` - - outputs: - + ``h_payto`` - + ``legitimization_process_row`` +- inputs: + + + ``provider_section`` + + ``provider_legitimization_id`` +- outputs: + + + ``h_payto`` + + ``legitimization_process_row`` OAuth 2.0 specifics diff --git a/design-documents/026-refund-fees.rst b/design-documents/026-refund-fees.rst @@ -35,37 +35,37 @@ enable customers to effectively obtain the deposit fee. Requirements ============ - * If the refund and refresh fees are zero, it should be possible for - consumers to get 100% of their digital cash back on refunds. - * This should not result in a problematic situation where merchants - conspire with consumers and issue minuscule refunds to allow consumers - to work around deposit fees. +* If the refund and refresh fees are zero, it should be possible for + consumers to get 100% of their digital cash back on refunds. +* This should not result in a problematic situation where merchants + conspire with consumers and issue minuscule refunds to allow consumers + to work around deposit fees. Proposed Solution ================= - * Only waive the deposit fee for full refunds where for the - specific coin (!) the refunded amount is the total value of the - refunded deposit. +* Only waive the deposit fee for full refunds where for the + specific coin (!) the refunded amount is the total value of the + refunded deposit. Alternatives ============ - * Only waive the deposit fee for full refunds where for the - specific coin the refunded amount is the total value of the - denomination of the coin. This may slightly simplify the - logic, but has the problem that it does not enable 100% - refunds if the original payment already required a refresh - because the coin's value exceeded the paid amount. - * Waive the deposit fee on any (including partial) refund. - This creates a bad incentive structure if combined refresh - and refund fees are below deposit fees. +* Only waive the deposit fee for full refunds where for the + specific coin the refunded amount is the total value of the + denomination of the coin. This may slightly simplify the + logic, but has the problem that it does not enable 100% + refunds if the original payment already required a refresh + because the coin's value exceeded the paid amount. +* Waive the deposit fee on any (including partial) refund. + This creates a bad incentive structure if combined refresh + and refund fees are below deposit fees. Drawbacks ========= - * We need to update and test an already complex fee calculation - logic. +* We need to update and test an already complex fee calculation + logic. Discussion / Q&A diff --git a/design-documents/029-mobile-ui.rst b/design-documents/029-mobile-ui.rst @@ -26,11 +26,11 @@ The wallet user should be able to easily send and receive money to and from othe Requirements ============ - * It should work even if the user does not have other communication channel - * Use the swipe up (to send) and swipe down (to request) gesture as other apps do - * It should be able to request payment before any withdraw (currency still unknown) - * It should support multi-device - * The user may opt-in to be findable through a registry service +* It should work even if the user does not have other communication channel +* Use the swipe up (to send) and swipe down (to request) gesture as other apps do +* It should be able to request payment before any withdraw (currency still unknown) +* It should support multi-device +* The user may opt-in to be findable through a registry service Proposed Solution ================= diff --git a/design-documents/031-invoicing.rst b/design-documents/031-invoicing.rst @@ -37,30 +37,30 @@ This design addresses bugs #7269 and #7274. Requirements ============ - * Effectively limit the number of open purses created by each individual - (or require purse fees if limit is exceeded). +* Effectively limit the number of open purses created by each individual + (or require purse fees if limit is exceeded). - * Ensure user has done KYC before doing a merge. - (Assuming the exchange does KYC at all.) +* Ensure user has done KYC before doing a merge. + (Assuming the exchange does KYC at all.) - * Use information from KYC process to help payer identify payee. +* Use information from KYC process to help payer identify payee. - * Reasonable UX and overall design impact. +* Reasonable UX and overall design impact. - * Wallets may want to pay for the reserve with coins - (reserve fresh, not created via bank transfer). +* Wallets may want to pay for the reserve with coins + (reserve fresh, not created via bank transfer). Unclear in the current proposal are: - * Here (and in other places!), the payment of the KYC - fee remains, eh, obscure. This should probably be - part of the KYC endpoints, and not for each - KYC-trigger. +* Here (and in other places!), the payment of the KYC + fee remains, eh, obscure. This should probably be + part of the KYC endpoints, and not for each + KYC-trigger. - * Proposed table structure does not properly capture - if user paid extra for more purses (I could open - for 3 years, then pay for 5x purses in year 1, but - should not automatically get 5x purses in years 2/3). +* Proposed table structure does not properly capture + if user paid extra for more purses (I could open + for 3 years, then pay for 5x purses in year 1, but + should not automatically get 5x purses in years 2/3). Proposed Solution @@ -78,26 +78,26 @@ receive the funds). The solution needs three new tables for: - * account creation data: +* account creation data: - - serial - - timestamp - - signature affirming desire to create account - - KYC requirement row + - serial + - timestamp + - signature affirming desire to create account + - KYC requirement row - * account creation payment data: +* account creation payment data: - - serial (for replication) - - coin signature (affirming payment) - - amount contributed - - account creation link (serial row ID) + - serial (for replication) + - coin signature (affirming payment) + - amount contributed + - account creation link (serial row ID) - * reserve closure request data: +* reserve closure request data: - - serial (for replication) - - timestamp - - reserve signature - - target account payto:// URI + - serial (for replication) + - timestamp + - reserve signature + - target account payto:// URI Specifically, the solution involves three new endpoints: @@ -105,61 +105,61 @@ Specifically, the solution involves three new endpoints: Opening reserves ---------------- - * This new endpoint ``/reserves/$RID/open`` allows the user to - pay (for a year) to create a fixed number of purses and - to keep the reserve ``open`` (preventing auto-close); the - endpoint typically triggers a first (balance-independent) - KYC process (451) for a new KYC operation ``invoicing`` - (unless KYC is off). +* This new endpoint ``/reserves/$RID/open`` allows the user to + pay (for a year) to create a fixed number of purses and + to keep the reserve ``open`` (preventing auto-close); the + endpoint typically triggers a first (balance-independent) + KYC process (451) for a new KYC operation ``invoicing`` + (unless KYC is off). - * Upon completion of the ``invoicing`` KYC, the wallet - must again try to ``/open``. If successful, the wallet - may be asked to pay the annual fee (402). However, - usually the wallet should be aware of the fee, and already - have included a suitable deposit in the POST to the endpoint. +* Upon completion of the ``invoicing`` KYC, the wallet + must again try to ``/open``. If successful, the wallet + may be asked to pay the annual fee (402). However, + usually the wallet should be aware of the fee, and already + have included a suitable deposit in the POST to the endpoint. - * Once the annual fee is paid, the now open - reserve is set to a non-zero counter of allowed concurrently - open purses, and the expiration time of the reserve is bumped - to the end of the time period for which the fee was paid. +* Once the annual fee is paid, the now open + reserve is set to a non-zero counter of allowed concurrently + open purses, and the expiration time of the reserve is bumped + to the end of the time period for which the fee was paid. Reserve Attestation ------------------- - * This new endpoint ``/reserves/$RID/attest`` allows the user to - obtain exchange-signed KYC information about themselves. - This will basically be a list of (GANA standardized) attributes - and exchange signatures. The user can then choose which of - these attributes to include when invoicing. The available - set of attributes may differ depending on the KYC providers - configured and the attributes returned by the KYC logic. - We may choose to not use any fancy cryptography here, and - simply sign the different attributes individually. However, - we should always sign over the ``$RID`` to ensure that the - resulting signatures are meaningful. - - * When receiving an invoice (PULL payment request), we may want to - mandate a certain minimal set of attributes that *should* always - be included, and if that is absent warn the receiver that the - sender of the invoice did not properly identify themselves. - - * By making this a new endpoint, the client can re-request - the signatures on-demand. This is useful if we use the - EdDSA online signatures of the exchange, which likely expire - long before the user changes their attributes. +* This new endpoint ``/reserves/$RID/attest`` allows the user to + obtain exchange-signed KYC information about themselves. + This will basically be a list of (GANA standardized) attributes + and exchange signatures. The user can then choose which of + these attributes to include when invoicing. The available + set of attributes may differ depending on the KYC providers + configured and the attributes returned by the KYC logic. + We may choose to not use any fancy cryptography here, and + simply sign the different attributes individually. However, + we should always sign over the ``$RID`` to ensure that the + resulting signatures are meaningful. + +* When receiving an invoice (PULL payment request), we may want to + mandate a certain minimal set of attributes that *should* always + be included, and if that is absent warn the receiver that the + sender of the invoice did not properly identify themselves. + +* By making this a new endpoint, the client can re-request + the signatures on-demand. This is useful if we use the + EdDSA online signatures of the exchange, which likely expire + long before the user changes their attributes. Closing reserves ---------------- - * This new endpoint ``/reserves/$RID/close`` allows the user to - force-close a reserve that has not yet expired. This is useful - in case invoices have been paid into the reserve and the - user wants to get their money out. The ``close`` endpoint - must be provided with an appropriate payto://-URI as - reserves that were filled by P2P merge operations may not - already have an associated bank account (empty ``reserves_in`` - table). +* This new endpoint ``/reserves/$RID/close`` allows the user to + force-close a reserve that has not yet expired. This is useful + in case invoices have been paid into the reserve and the + user wants to get their money out. The ``close`` endpoint + must be provided with an appropriate payto://-URI as + reserves that were filled by P2P merge operations may not + already have an associated bank account (empty ``reserves_in`` + table). Alternatives diff --git a/design-documents/032-brandt-vickrey-auctions.rst b/design-documents/032-brandt-vickrey-auctions.rst @@ -37,11 +37,11 @@ process. We expect the design to be useful for three primary use-cases: - * Auctions in the style of Ebay (consumer goods) +* Auctions in the style of Ebay (consumer goods) - * Auctions for commodities and stock trading +* Auctions for commodities and stock trading - * Auctions in currency exchange, including crypto-currencies +* Auctions in currency exchange, including crypto-currencies We do not consider the use-case of high-value art auctions, as here the Taler payment system is likely unsuitable for the high transaction values, the @@ -59,32 +59,32 @@ auction (duration, price ranges, conditions of the sale, etc.) is considered out-of-scope for the Taler protocol. Taler is only used to escrow a payment once participants have decided to make a bid on an aution. - * Support libbrandt-style SMC multiparty computation to determine - auction winner. No party is trusted to learn the bids during - the bidding phase, including the exchange. This implies that - participants have to always escrow the largest possible amount - in the auction, even if their actual bid is much lower. +* Support libbrandt-style SMC multiparty computation to determine + auction winner. No party is trusted to learn the bids during + the bidding phase, including the exchange. This implies that + participants have to always escrow the largest possible amount + in the auction, even if their actual bid is much lower. - * Integrate nicely with existing exchange functionality, including - minimal changes to existing endpoints and introducing as few new - endpoints as reasonable. +* Integrate nicely with existing exchange functionality, including + minimal changes to existing endpoints and introducing as few new + endpoints as reasonable. - * Verifiablity of the auction outcome by the exchange and the - auditor. There is not supposed to be any trusted third party. - Naturally, when selling real-world goods, external enforcement - of the transfer of the good may be required. +* Verifiablity of the auction outcome by the exchange and the + auditor. There is not supposed to be any trusted third party. + Naturally, when selling real-world goods, external enforcement + of the transfer of the good may be required. - * Guaranteed payment. If the auction is successful (there were at - least two bidders), the seller must unconditionally receive the - payment. +* Guaranteed payment. If the auction is successful (there were at + least two bidders), the seller must unconditionally receive the + payment. - * Participants pay fees (possibly even just for participation), - to ensure only truly interested parties with skin in the game - participate (protection against denial-of-service attacks). +* Participants pay fees (possibly even just for participation), + to ensure only truly interested parties with skin in the game + participate (protection against denial-of-service attacks). - * To ensure participants can perform the required computations - in each round, the number of bidders on an auction may need - to be limited. +* To ensure participants can perform the required computations + in each round, the number of bidders on an auction may need + to be limited. @@ -94,33 +94,33 @@ Proposed Solution We will for now consider five types of parties involved in the auction: - * A seller, who is offering an item and who sets some basic - rules for the auction (like the price range, duration of - rounds, delivery conditions, seller's bank account, - auction operator, etc.). - - * A number of bidders, who make bids on the auction, with - the highest bidder winnig the auction and paying the - second highest price to the seller. - - * An auction operator, who collects messages from the seller - and the bidders and ultimately announces the (then universally - verifiable) outcome. In the original paper of Brand, this - would be the ``blackboard``. The auction operator may - also facilitate the discovery of auctions, but this is out - of scope. The auction operator may charge fees for setting - up and running an auction. However, from the Taler perspective, - paying an auction operator to run an auction is the same - as paying any other merchant and thus out of scope for this - design document. - - * An exchange that supports the ``policy_vickrey_auction`` extension and - holds the funds for bids in escrow for the duration of the auction. Upon - completion of the auction, the exchange pays the seller from the auction's - winner and refunds the other bidders. - - * An auditor that verifies that the exchange made the payments - correctly. +* A seller, who is offering an item and who sets some basic + rules for the auction (like the price range, duration of + rounds, delivery conditions, seller's bank account, + auction operator, etc.). + +* A number of bidders, who make bids on the auction, with + the highest bidder winnig the auction and paying the + second highest price to the seller. + +* An auction operator, who collects messages from the seller + and the bidders and ultimately announces the (then universally + verifiable) outcome. In the original paper of Brand, this + would be the ``blackboard``. The auction operator may + also facilitate the discovery of auctions, but this is out + of scope. The auction operator may charge fees for setting + up and running an auction. However, from the Taler perspective, + paying an auction operator to run an auction is the same + as paying any other merchant and thus out of scope for this + design document. + +* An exchange that supports the ``policy_vickrey_auction`` extension and + holds the funds for bids in escrow for the duration of the auction. Upon + completion of the auction, the exchange pays the seller from the auction's + winner and refunds the other bidders. + +* An auditor that verifies that the exchange made the payments + correctly. The high-level protocol for a bidder's interaction with the auction operator and the Taler exchange is already described in Teich's thesis in Figure 3.2: @@ -171,17 +171,17 @@ refunds the bids from the losing bidders, pays the price to the seller from the winner (minus auction fee), and partially refunds the winner the difference between the escrowed amount and the winning bid. - .. note:: +.. note:: - Partial refunds are currently implemented using the ``refunds`` table. - The refunds table requires refund message signatures by the merchant's - public key. Thus, this table will need to be generalized to include - some indicator as to whether the refund signature is valid or - whether some other mechanism justified the refund. The most trivial - way would probably be to allow NULL values for the signature. However, - likely a link to the extension transcript should then be stored in - another column to make it easier for the auditor to look for - "alternative" justifications in those cases. + Partial refunds are currently implemented using the ``refunds`` table. + The refunds table requires refund message signatures by the merchant's + public key. Thus, this table will need to be generalized to include + some indicator as to whether the refund signature is valid or + whether some other mechanism justified the refund. The most trivial + way would probably be to allow NULL values for the signature. However, + likely a link to the extension transcript should then be stored in + another column to make it easier for the auditor to look for + "alternative" justifications in those cases. In case participants are identified as malicious, the auction meta data should specify the penalty those participants must pay to the seller. Again, the @@ -197,74 +197,74 @@ Transcripts A transcript of a Brandt-Vickrey auction is the JSON encoding of an object of type ``BrandtVickreyAuctionTranscript``. - .. code-block:: typescript +.. code-block:: typescript - // This structure defines the transcript of an auction of Brandt-Vickrey kind. - interface BrandtVickreyAuctionTranscript { - // The auction definition. - auction: BrandtVickreyAuction; + // This structure defines the transcript of an auction of Brandt-Vickrey kind. + interface BrandtVickreyAuctionTranscript { + // The auction definition. + auction: BrandtVickreyAuction; - // The public keys of the bidders, in Crockford Base32 encoding. - bidders: EddsaPublicKey[]; + // The public keys of the bidders, in Crockford Base32 encoding. + bidders: EddsaPublicKey[]; - // Signatures of the auction in Crockford Base32 encoding. - // One signature per bidder. - signatures: EddsaSignature[]; + // Signatures of the auction in Crockford Base32 encoding. + // One signature per bidder. + signatures: EddsaSignature[]; - // List of policy hash codes that identify policy details associated with - // each bidder. Those codes were generated by the policy extension - // policy_brandt_vickrey_auction during the deposit of coins for this - // auction. - policy_hash_codes: HashCode[]; + // List of policy hash codes that identify policy details associated with + // each bidder. Those codes were generated by the policy extension + // policy_brandt_vickrey_auction during the deposit of coins for this + // auction. + policy_hash_codes: HashCode[]; - // The transcript of all messages received by the seller. - transcript: BrandtVickreyAuctionMessage[]; + // The transcript of all messages received by the seller. + transcript: BrandtVickreyAuctionMessage[]; - // Optionally, the seller can provide the winners it had calculated. - winners?: BrandtVickreyAuctionWinner[]; + // Optionally, the seller can provide the winners it had calculated. + winners?: BrandtVickreyAuctionWinner[]; - // The signature over the hash of this JSON object, without the - // key ``sig`` and in normalized form, basically over - // H(auction, bidders, signatures, transcripts, winners?) - // It is signed by the private key that corresponds to the public key - // in `BrandtVickreyAuction`.``pubkey``. - // This signature is in Crockford Base32 encoding. - sig: EddsaSignature; - } + // The signature over the hash of this JSON object, without the + // key ``sig`` and in normalized form, basically over + // H(auction, bidders, signatures, transcripts, winners?) + // It is signed by the private key that corresponds to the public key + // in `BrandtVickreyAuction`.``pubkey``. + // This signature is in Crockford Base32 encoding. + sig: EddsaSignature; + } - .. code-block:: typescript +.. code-block:: typescript - interface BrandtVickreyAuctionMessage { - // The index of the bidder into the - // `BrandtVickreyAuctionTranscript`.``bidders`` array. - bidder: number; + interface BrandtVickreyAuctionMessage { + // The index of the bidder into the + // `BrandtVickreyAuctionTranscript`.``bidders`` array. + bidder: number; - // The raw message in Crockford Base32 encoding. - msg: string; + // The raw message in Crockford Base32 encoding. + msg: string; - // The signature over the message. The signature is in Crockford Base32 - // encoding. It must be signed by the private key corresponding to the - // bidder's public key in `BrandtVickreyAuctionTranscript`.``bidders``. - sig: EddsaSignature; - } + // The signature over the message. The signature is in Crockford Base32 + // encoding. It must be signed by the private key corresponding to the + // bidder's public key in `BrandtVickreyAuctionTranscript`.``bidders``. + sig: EddsaSignature; + } - .. code-block:: typescript +.. code-block:: typescript - interface BrandtVickreyAuctionWinner { - // The index of the bidder into the - // `BrandtVickreyAuctionTranscript`.bidder array. - bidder: number; + interface BrandtVickreyAuctionWinner { + // The index of the bidder into the + // `BrandtVickreyAuctionTranscript`.bidder array. + bidder: number; - // The index of the winning price into the - // `BrandtVickreyAuction`.prices array. - price_idx: number; + // The index of the winning price into the + // `BrandtVickreyAuction`.prices array. + price_idx: number; - // The winning price - price: Amount; - } + // The winning price + price: Amount; + } Alternatives @@ -312,13 +312,13 @@ could still deanonymize themselves to the auctioneer with the objective of the auction operator then suppressing messages from other (anonymous) participants and thereby possibly excluding higher bids from those users. - .. note:: +.. note:: - As described above, the Master's thesis of Markus Teich proposes to - address the issue of bidders dropping out of the protocol by fining them, - for example by keeping (some of) the escrowed funds. This may work, but - only if we assume that the auction operator is not maliciously dropping - messages from some bidders. + As described above, the Master's thesis of Markus Teich proposes to + address the issue of bidders dropping out of the protocol by fining them, + for example by keeping (some of) the escrowed funds. This may work, but + only if we assume that the auction operator is not maliciously dropping + messages from some bidders. diff --git a/design-documents/041-wallet-balance-amount-definitions.rst b/design-documents/041-wallet-balance-amount-definitions.rst @@ -289,47 +289,47 @@ Peer Push Credit ~~~~~~~~~~~~~~~~ - ``instructed_amount`` = p2pContract.amount +``instructed_amount`` = p2pContract.amount - ``coins`` = select-coin-for-operation(credit, mode, raw_amount) +``coins`` = select-coin-for-operation(credit, mode, raw_amount) - ``raw_amount`` = instructed_amount +``raw_amount`` = instructed_amount - ``effective_amount`` = instructed_amount - coins.withdrawal_fee +``effective_amount`` = instructed_amount - coins.withdrawal_fee - .. note:: - In the case that the withdrawal_fee of the coin selection for the push-credit amount - is higher than the wire_fee of the exchange, can the wallet ask the exchange to make - a wire transfer of the purse instead of proceeding? +.. note:: + In the case that the withdrawal_fee of the coin selection for the push-credit amount + is higher than the wire_fee of the exchange, can the wallet ask the exchange to make + a wire transfer of the purse instead of proceeding? Peer Pull Debit ~~~~~~~~~~~~~~~ - ``instructed_amount`` = p2pContract.amount +``instructed_amount`` = p2pContract.amount - ``coins`` = select-coin-for-operation(debit, mode, raw_amount) +``coins`` = select-coin-for-operation(debit, mode, raw_amount) - ``raw_amount`` = instructed_amount +``raw_amount`` = instructed_amount - ``effective_amount`` = instructed_amount + coins.deposit_fee + coins.refresh_fee + wire.transfer_fee +``effective_amount`` = instructed_amount + coins.deposit_fee + coins.refresh_fee + wire.transfer_fee Refund ~~~~~~ - ``instructed_amount`` = refund.amount +``instructed_amount`` = refund.amount - ``raw_amount`` = instructed_amount +``raw_amount`` = instructed_amount - ``effective_amount`` = instructed_amount - refund_fee - refresh_fee +``effective_amount`` = instructed_amount - refund_fee - refresh_fee - .. note:: - There may be the case that the merchant should refund all the value of the purchase - and that may include paying for the refund_fee. +.. note:: + There may be the case that the merchant should refund all the value of the purchase + and that may include paying for the refund_fee. - Is there a way that the merchant can initiate a refund of purchase + refund_fee so - the wallet will get the same effective_amount? + Is there a way that the merchant can initiate a refund of purchase + refund_fee so + the wallet will get the same effective_amount? diff --git a/design-documents/045-kyc-inheritance.rst b/design-documents/045-kyc-inheritance.rst @@ -38,9 +38,9 @@ There are two reasons that motivate our proposal: of his or her child and at the same time provide appropriate birthday information. That way, the child can withdraw money from its reserve - - with appropriate and evolving age-restriction always in place, + - with appropriate and evolving age-restriction always in place, - - no further age-commitment interaction with the parent. + - no further age-commitment interaction with the parent. With the ability to attest KYC transitively, we can reduce the cost of ownership of long-term reserves and enable the principle of subsidiarity, diff --git a/design-documents/046-mumimo-contracts.rst b/design-documents/046-mumimo-contracts.rst @@ -33,48 +33,48 @@ Requirements We want Taler to support various interesting use-cases: - - Unlinkable, uncopyable subscriptions without accounts (reader can pay with - Taler to subscribe to online publication, read unlimited number of - articles during a certain period, transfer subscription to other devices, - maintain unlinkability / full anonymity amongst all anonymous - subscribers). - - - Coupons, discounts and stamps -- like receiving a discount on a product, - product basket or subscription -- based on previous purchase(s). Again, - with unlinkability and anonymity (modulo there being other users eligible - for the discount). - - - Subscription tokens lost (due to loss of device without backup) should - be recoverable from any previous backup of the subscription. - - - Currency conversion, that is exchanging one currency for another. - - - Donations, including privacy-preserving tax receipts that prove that the - user donated to an entity that is eligible for tax-deductions but without - revealing which entity the user donated to. At the same time, the entity - issuing the tax receipt must be transparent (to the state) with respect to - the amount of tax-deductable donations it has received. - - - Throttled political donations where each individual is only allowed to - donate anonymously up to a certain amount per year or election cycle. - - - Unlinkable gifts -- enabling the purchase of digital goods (such as - articles, albums, etc.) to be consumed by a third party. For example, a - newspaper subscription may include a fixed number of articles that can be - gifted to others each week, all while maintaining unlinkability and - anonymity between the giver and the recipient. - - - Temporally-constrained, unlinkable event ticketing. Allowing visitors to - use Taler to purchase a ticket for an event. This ticket grants entry and - exit privileges to the event location during a specified time window, while - preserving the anonymity of the ticket holder (within the group of all the - ticket holders). - - - Event deposit systems. A deposit mechanism for events where customers - receive a token alongside their cup or plate, which they are expected to - return. This system validates that the cup or plate was legitimately - acquired (i.e., not brought from home or stolen from a stack of dirty items) - and incentivizes return after use. +- Unlinkable, uncopyable subscriptions without accounts (reader can pay with + Taler to subscribe to online publication, read unlimited number of + articles during a certain period, transfer subscription to other devices, + maintain unlinkability / full anonymity amongst all anonymous + subscribers). + +- Coupons, discounts and stamps -- like receiving a discount on a product, + product basket or subscription -- based on previous purchase(s). Again, + with unlinkability and anonymity (modulo there being other users eligible + for the discount). + +- Subscription tokens lost (due to loss of device without backup) should + be recoverable from any previous backup of the subscription. + +- Currency conversion, that is exchanging one currency for another. + +- Donations, including privacy-preserving tax receipts that prove that the + user donated to an entity that is eligible for tax-deductions but without + revealing which entity the user donated to. At the same time, the entity + issuing the tax receipt must be transparent (to the state) with respect to + the amount of tax-deductable donations it has received. + +- Throttled political donations where each individual is only allowed to + donate anonymously up to a certain amount per year or election cycle. + +- Unlinkable gifts -- enabling the purchase of digital goods (such as + articles, albums, etc.) to be consumed by a third party. For example, a + newspaper subscription may include a fixed number of articles that can be + gifted to others each week, all while maintaining unlinkability and + anonymity between the giver and the recipient. + +- Temporally-constrained, unlinkable event ticketing. Allowing visitors to + use Taler to purchase a ticket for an event. This ticket grants entry and + exit privileges to the event location during a specified time window, while + preserving the anonymity of the ticket holder (within the group of all the + ticket holders). + +- Event deposit systems. A deposit mechanism for events where customers + receive a token alongside their cup or plate, which they are expected to + return. This system validates that the cup or plate was legitimately + acquired (i.e., not brought from home or stolen from a stack of dirty items) + and incentivizes return after use. Proposed Solution @@ -474,10 +474,10 @@ 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:: +.. note:: - We can probably spec this rather nicely if we first change the - batch-withdraw API to only use a single reserve signature. + We can probably spec this rather nicely if we first change the + 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 <taler_depositrequestps>`. @@ -605,9 +605,9 @@ Anastasis-style logic. Wallets should collect tax receipts by year and offer an export functionality. The export should generate either - (a) a JSON file, - (b) a PDF (with QR codes), or - (c) a series of screens with QR codes. +(a) a JSON file, +(b) a PDF (with QR codes), or +(c) a series of screens with QR codes. Wallets may only implement some of the above options due to resource constraints. @@ -635,9 +635,9 @@ Once an RA is added to a wallet, it should automatically try to withdraw the maximum amount of ration coins it is eligible for. Available rations should be shown below the subscriptions by RA (if any). - ..note:: +.. note:: - RAs are considered an idea for future work and not part of our current timeline. + RAs are considered an idea for future work and not part of our current timeline. Limited Donations per Capita (future work) @@ -648,32 +648,32 @@ for donations to political parties), an RA can be used to issue donation rations that limit the amount of donations that can be made for the respective period. - ..note:: +.. note:: - RAs are considered an idea for future work and not part of our current timeline. + RAs are considered an idea for future work and not part of our current timeline. Definition of Done ================== - - [ ] Merchant backend support for multiple currencies - - [x] Merchant backend support for consuming and issuing tokens - - [ ] Merchant SPA support for configuring new tokens of different types - - [x] Wallet-core support for contract format v1 - - [ ] Wallet-core filters for feasible contracts and automatic subscription execution - - [ ] Wallet-GUIs (WebEx, Android, iOS) render all new contract types - - [ ] Wallet-GUIs (WebEx, Android, iOS) allow users to select between multiple contracts - - [x] Implemented wire formats documented in the normative API specifications - - [ ] Token anonymity set size (ASS) authority implemented and documented - - [ ] Merchants report anonymity set size increases to ASS authority - - [ ] Wallets process anonymity set size reports from ASS authority - - [x] Bachelor thesis written on applications and design - - [x] Academic paper written on DONAU (requirements, design, implementation) - - [x] DONAU implemented and documented - - [ ] DONAU receipt-validation application completed - - [x] Integration tests exist in wallet-core - - [ ] Deliverables accepted by EC +- [ ] Merchant backend support for multiple currencies +- [x] Merchant backend support for consuming and issuing tokens +- [ ] Merchant SPA support for configuring new tokens of different types +- [x] Wallet-core support for contract format v1 +- [ ] Wallet-core filters for feasible contracts and automatic subscription execution +- [ ] Wallet-GUIs (WebEx, Android, iOS) render all new contract types +- [ ] Wallet-GUIs (WebEx, Android, iOS) allow users to select between multiple contracts +- [x] Implemented wire formats documented in the normative API specifications +- [ ] Token anonymity set size (ASS) authority implemented and documented +- [ ] Merchants report anonymity set size increases to ASS authority +- [ ] Wallets process anonymity set size reports from ASS authority +- [x] Bachelor thesis written on applications and design +- [x] Academic paper written on DONAU (requirements, design, implementation) +- [x] DONAU implemented and documented +- [ ] DONAU receipt-validation application completed +- [x] Integration tests exist in wallet-core +- [ ] Deliverables accepted by EC While rationing is part of the design, we expect the actual implementation to be done much later and thus should not consider it part of the "DONE" part. diff --git a/design-documents/047-stefan.rst b/design-documents/047-stefan.rst @@ -36,10 +36,10 @@ fees for equivalent transactions. Requirements ============ - - keep the logarithmic nature of the fees (proportionally high fees - for tiny amounts, medium fees for medium amounts, low fees for large amounts) - - same purchase, same perceived price; prices are predictable for users - - enable merchants to easily cover all fees in most cases +- keep the logarithmic nature of the fees (proportionally high fees + for tiny amounts, medium fees for medium amounts, low fees for large amounts) +- same purchase, same perceived price; prices are predictable for users +- enable merchants to easily cover all fees in most cases Proposed Solution @@ -154,12 +154,12 @@ do their own internal actual coin selection to minimize fees. Definition of Done ================== - - [x] exchange modified - - [x] merchant understands STEFAN curve in backend - - [ ] merchant SPA has configuration option to enable use of STEFAN-curves - - [ ] wallet-core uses STEFAN-curves to compute display fees - - [ ] wallet-core supports annual reconcilliation transaction - - [ ] wallet GUIs use STEFAN-curves when comparing exchange fee structures +- [x] exchange modified +- [x] merchant understands STEFAN curve in backend +- [ ] merchant SPA has configuration option to enable use of STEFAN-curves +- [ ] wallet-core uses STEFAN-curves to compute display fees +- [ ] wallet-core supports annual reconcilliation transaction +- [ ] wallet GUIs use STEFAN-curves when comparing exchange fee structures Alternatives diff --git a/design-documents/048-wallet-exchange-lifecycle.rst b/design-documents/048-wallet-exchange-lifecycle.rst @@ -89,11 +89,11 @@ Update Status Examples: - * The exchange updated to a new protocol version that is incompatible with the wallet - * The exchange advertises a new master public key. This might be a temporary - configuration issue or malicious attack. - * The exchange only advertises outdated denomination keys, making new withdrawals - impossible. + * The exchange updated to a new protocol version that is incompatible with the wallet + * The exchange advertises a new master public key. This might be a temporary + configuration issue or malicious attack. + * The exchange only advertises outdated denomination keys, making new withdrawals + impossible. * ``ready``: Exchange is useable. * ``ready-update``: Exchange is useable, but currently being updated. If it is discovered that the information from the exchange is indeed too outdated (unknown signing key in response, @@ -142,11 +142,11 @@ for ``/terms``, so that the wallet can already download the full response (not j Definition of Done ================== - * [x] states implemented in wallet-core - * [x] exchange management specified on a UI level - * [ ] WebExtension implementation verified against the full DD - * [x] Android wallet exchange deletion implemented - * [ ] iOS wallet implementation verified against the full DD +* [x] states implemented in wallet-core +* [x] exchange management specified on a UI level +* [ ] WebExtension implementation verified against the full DD +* [x] Android wallet exchange deletion implemented +* [ ] iOS wallet implementation verified against the full DD Discussion / Q&A ================ diff --git a/design-documents/050-libeufin-nexus.rst b/design-documents/050-libeufin-nexus.rst @@ -42,25 +42,25 @@ subsystems, and it would be good to combine some of them. Requirements ============ - * Easy to use, high-level abstraction over EBICS details - * Reduce complexity, no multi-account, multi-connection support - * No general EBICS client, Taler-specific logic - * Support for Taler facade, including bouncing of transactions with malformed subject - * Clear separation between configuration and runtime, minimal runtime footprint - * No built-in cron-jobs, background tasks runnable via systemd (one-shot and persistent mode) - * Configuration style same as other GNUnet/Taler components - * No private keys in database, as in other Taler components - * Enable future unified implementation with Depolymerization to share database and REST API logic +* Easy to use, high-level abstraction over EBICS details +* Reduce complexity, no multi-account, multi-connection support +* No general EBICS client, Taler-specific logic +* Support for Taler facade, including bouncing of transactions with malformed subject +* Clear separation between configuration and runtime, minimal runtime footprint +* No built-in cron-jobs, background tasks runnable via systemd (one-shot and persistent mode) +* Configuration style same as other GNUnet/Taler components +* No private keys in database, as in other Taler components +* Enable future unified implementation with Depolymerization to share database and REST API logic Proposed Solution ================= Split up Nexus into four components: - * nexus-ebics-setup: register account with EBICS server and perform key generation and exchange - * nexus-ebics-fetch: obtain wire transfers and payment status from EBICS server - * nexus-ebics-submit: send payment initiation messages to EBICS server - * nexus-httpd: serve Taler REST APIs (wire gateway API, revenue API) to Taler clients and implement facade logic +* nexus-ebics-setup: register account with EBICS server and perform key generation and exchange +* nexus-ebics-fetch: obtain wire transfers and payment status from EBICS server +* nexus-ebics-submit: send payment initiation messages to EBICS server +* nexus-httpd: serve Taler REST APIs (wire gateway API, revenue API) to Taler clients and implement facade logic All four components should read a simple INI-style configuration file, possibly with component-specific sections. @@ -114,20 +114,20 @@ File contents: BANK_PUBLIC_KEYS_FILE JSON with 3 fields: - * bank_encryption_public_key (base32) - * bank_authentication_public_key (base32) - * accepted (boolean) +* bank_encryption_public_key (base32) +* bank_authentication_public_key (base32) +* accepted (boolean) File contents: CLIENT_PRIVATE_KEYS_FILE ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ JSON with: - * signature_private_key (base32) - * encryption_private_key (base32) - * authentication_private_key (base32) - * submitted_ini (boolean) - * submitted_hia (boolean) +* signature_private_key (base32) +* encryption_private_key (base32) +* authentication_private_key (base32) +* submitted_ini (boolean) +* submitted_hia (boolean) Database schema --------------- @@ -174,136 +174,136 @@ nexus-ebics-setup The ebics-setup tool performs the following: - * Checks if the require configuration options are present and well-formed - (like the file names), if not exits with an error message. Given - --check-full-config, also sanity-check the configuration options of the - other subsystems. +* Checks if the require configuration options are present and well-formed + (like the file names), if not exits with an error message. Given + --check-full-config, also sanity-check the configuration options of the + other subsystems. - * Checks if the private keys file exists, if not creates new private keys - with flags "not submitted". +* Checks if the private keys file exists, if not creates new private keys + with flags "not submitted". - * If any private key flags are set to "not submitted" or a command-line - override is given (--force-keys-resubmission), attempt to submit the - corresponding client public keys to the bank. If the bank accepts the - client public key, update the flags to "submitted". +* If any private key flags are set to "not submitted" or a command-line + override is given (--force-keys-resubmission), attempt to submit the + corresponding client public keys to the bank. If the bank accepts the + client public key, update the flags to "submitted". - * If a public key was submitted or if a command-line override - (--generate-registration-pdf) is given, generate a PDF with the public key - for the user to print and send to the bank. +* If a public key was submitted or if a command-line override + (--generate-registration-pdf) is given, generate a PDF with the public key + for the user to print and send to the bank. - * Checks if the public keys of the bank already exist on disk, if not try to - download them with a flag "not accepted". If downloading fails, display a - message asking the user to register the private keys (and give override - options for re-submission of private keys or re-generation of the - registration PDF). +* Checks if the public keys of the bank already exist on disk, if not try to + download them with a flag "not accepted". If downloading fails, display a + message asking the user to register the private keys (and give override + options for re-submission of private keys or re-generation of the + registration PDF). - * If we just downloaded public keys, display the corresponding public keys - (or fingerprints) to the user and ask the user to interactively confirm to - accept them (or auto-accept via --auto-accept-keys). If the user accepted - the public key, update the flag to "accepted". +* If we just downloaded public keys, display the corresponding public keys + (or fingerprints) to the user and ask the user to interactively confirm to + accept them (or auto-accept via --auto-accept-keys). If the user accepted + the public key, update the flag to "accepted". nexus-ebics-fetch ----------------- - * Fetches by default all incoming and outgoing bank transactions and error - messages and inserts them into the Postgres database tables (including - updating the initiated outgoing transaction table). First, considers the - last transactions in the database and fetches statements from that day - forward (inclusive). Afterwards, fetches reports and when the day rolls - over (before committing any transactions with the next day!) also fetches a - final statement of the previous day, thus ensuring we get a statement - every day plus intra-day reports. +* Fetches by default all incoming and outgoing bank transactions and error + messages and inserts them into the Postgres database tables (including + updating the initiated outgoing transaction table). First, considers the + last transactions in the database and fetches statements from that day + forward (inclusive). Afterwards, fetches reports and when the day rolls + over (before committing any transactions with the next day!) also fetches a + final statement of the previous day, thus ensuring we get a statement + every day plus intra-day reports. - .. note:: + .. note:: - (1) "from that day forward (inclusive)" must **not** rely on EBICS returning - the unseen messages: that's because they might **already** be downloaded but - never made it to the database. + (1) "from that day forward (inclusive)" must **not** rely on EBICS returning + the unseen messages: that's because they might **already** be downloaded but + never made it to the database. - (2) "and when the day rolls over". When does a day roll over? => A day rolls - over when the current time is at least on the day after the transaction with the - most recent timestamp that's stored in the database. + (2) "and when the day rolls over". When does a day roll over? => A day rolls + over when the current time is at least on the day after the transaction with the + most recent timestamp that's stored in the database. - (3) "Afterwards, fetches reports". This must happen **only after** any possible - previous statement got downloaded. + (3) "Afterwards, fetches reports". This must happen **only after** any possible + previous statement got downloaded. - To summarize: at any point in time the database must contain (the content of) any - possible statement up to the current time, plus any possible report up to the current - time (in case that's not covered by any statement so far). + To summarize: at any point in time the database must contain (the content of) any + possible statement up to the current time, plus any possible report up to the current + time (in case that's not covered by any statement so far). - * Bounces transactions with mal-formed wire transfer subjects. +* Bounces transactions with mal-formed wire transfer subjects. - * Optionally logs EBICS messages to disk, one per file, based on - configuration. Filenames must include the timestamp of the download. The - date must be in the path and the time of day at the beginning of the - filename. This will facilitate easy deletion of logs. +* Optionally logs EBICS messages to disk, one per file, based on + configuration. Filenames must include the timestamp of the download. The + date must be in the path and the time of day at the beginning of the + filename. This will facilitate easy deletion of logs. - * Optionally only fetches reports (--only-reports) or statements (--only-statements) - or only error messages (--only-failures). +* Optionally only fetches reports (--only-reports) or statements (--only-statements) + or only error messages (--only-failures). - * Optionally terminates after one fetch (--transient) or re-fetches based - on the configured frequency. +* Optionally terminates after one fetch (--transient) or re-fetches based + on the configured frequency. - * Terminates hard (with error code) if incoming transactions are not in the - expected (configured) currency. +* Terminates hard (with error code) if incoming transactions are not in the + expected (configured) currency. nexus-ebics-submit ------------------ - * Generates a payment initiation message for all client-initiated outgoing - transactions that have not yet been initiated. If the server accepts the - message, sets the initiated flag in the table to true. The EBICS order ID - is set to the lowest initiated_outgoing_transaction_id in the transaction - set modulo 2^20 encoded in BASE36. The payment information ID is set to - the initiated_outgoing_transaction_id of each transaction as a text - string. The message identification is set to the lowest - initiated_outgoing_transaction_id plus ("-") the highest - initiated_outgoing_transaction_id as a text string. +* Generates a payment initiation message for all client-initiated outgoing + transactions that have not yet been initiated. If the server accepts the + message, sets the initiated flag in the table to true. The EBICS order ID + is set to the lowest initiated_outgoing_transaction_id in the transaction + set modulo 2^20 encoded in BASE36. The payment information ID is set to + the initiated_outgoing_transaction_id of each transaction as a text + string. The message identification is set to the lowest + initiated_outgoing_transaction_id plus ("-") the highest + initiated_outgoing_transaction_id as a text string. - * Optionally terminates after one fetch (--transient) or re-submits based - on the configured frequency. +* Optionally terminates after one fetch (--transient) or re-submits based + on the configured frequency. - * If configured frequency is zero (default), listens to notifications from - nexus-httpd for insertions of outgoing payment initiation records. +* If configured frequency is zero (default), listens to notifications from + nexus-httpd for insertions of outgoing payment initiation records. nexus-httpd ----------- - * Offers REST APIs as per configuration. +* Offers REST APIs as per configuration. - * Listens to notifications from nexus-ebics-fetch to run facade-logic and - wake-up long pollers. +* Listens to notifications from nexus-ebics-fetch to run facade-logic and + wake-up long pollers. - * Offers a *new* REST API to list failed (initiated outgoing) transactions - and allows the user to re-initiate those transactions (by creating new - records in the initiated outgoing transactions table). Also allows the - user to set the "hidden" flag on failed transactions to not show them - anymore. +* Offers a *new* REST API to list failed (initiated outgoing) transactions + and allows the user to re-initiate those transactions (by creating new + records in the initiated outgoing transactions table). Also allows the + user to set the "hidden" flag on failed transactions to not show them + anymore. Definition of Done ================== - * [x] Code implemented - * [ ] Migration of all historical exchange and merchant test cases verified - * [x] Man pages updated - * [x] Manual updated - * [ ] Testing with actual banks, including error handling and idempotency, documented - * [ ] Testing against a maintained server-side EBICS mock verified - * [ ] Coverage across the intended ISO 20022 message variants documented +* [x] Code implemented +* [ ] Migration of all historical exchange and merchant test cases verified +* [x] Man pages updated +* [x] Manual updated +* [ ] Testing with actual banks, including error handling and idempotency, documented +* [ ] Testing against a maintained server-side EBICS mock verified +* [ ] Coverage across the intended ISO 20022 message variants documented Alternatives ============ - * Only run Taler on top of Bitcoin. +* Only run Taler on top of Bitcoin. Drawbacks ========= - * Uses EBICS. +* Uses EBICS. Discussion / Q&A ================ diff --git a/design-documents/051-fractional-digits.rst b/design-documents/051-fractional-digits.rst @@ -32,11 +32,11 @@ There was already a specification for ScopedCurrencyInfo - which got renamed to We need three core characteristics for fractional digits for each currency: - e) the number of fractional digits e in [0..8] the user may 'e'nter in a TextInputField +e) the number of fractional digits e in [0..8] the user may 'e'nter in a TextInputField - n) the number of fractional digits n in [0..8] to be rendered as 'n'ormal characters (same font and size as the integer digits). All additional fractional digits will be rendered as SuperScriptDigits as known from gas filling stations. The UI should never round or truncate any amount, but always render all existing digits (except trailing zeroes, see c). +n) the number of fractional digits n in [0..8] to be rendered as 'n'ormal characters (same font and size as the integer digits). All additional fractional digits will be rendered as SuperScriptDigits as known from gas filling stations. The UI should never round or truncate any amount, but always render all existing digits (except trailing zeroes, see c). - z) the number of fractional digits z in [0..8] to be rendered as trailing 'z'eroes (including SuperScript digits). E.g. if z = 2 (and n = 2), then render $5 as ``$ 5.00``. If z = 3 (and n = 2), then render $5 as ``$ 5.00⁰`` with two normal trailing zeroes and one superscript trailing zero. +z) the number of fractional digits z in [0..8] to be rendered as trailing 'z'eroes (including SuperScript digits). E.g. if z = 2 (and n = 2), then render $5 as ``$ 5.00``. If z = 3 (and n = 2), then render $5 as ``$ 5.00⁰`` with two normal trailing zeroes and one superscript trailing zero. The values e, n, and z are independent from each other. Each could be any value from 0 to 8. However, when a user enters an amount, s/he should be able to input @@ -82,34 +82,34 @@ merchant SPA --- independently of any particular exchange being used --- how the merchant SPA should render amounts. Hence, the information will need to be provisioned by all three services. - .. code-block:: swift - - public struct CurrencySpecification: Codable, Sendable { - // e.g. “Japanese Yen” or "Bitcoin (Mainnet)" - let name: String - // how many digits the user may enter after the decimal separator - let fractional_input_digits: Int - // €,$,£: 2; some arabic currencies: 3, ¥: 0 - let fractional_normal_digits: Int - // usually same as fractionalNormalDigits, but e.g. might be 2 for ¥ - let fractional_trailing_zero_digits: Int - // specifies whether the keys in `alt_unit_names' are symbols - // (e.g. €, k€) or names (e.g. BTC, mBTC), so that apps can decide - // how to render it (e.g. EUR 10 vs €10) - let alt_unit_names_are_symbols: Bool - // map of powers of 10 to alternative currency names / symbols, - // must always have an entry under "0" that defines the base name, - // e.g. "0 : €" or "3 : k€". For BTC, would be "0 : BTC, -3 : mBTC". - // This way, we can also communicate the currency symbol to be used. - let alt_unit_names: [Int : String] - - // An array of common amounts that should be turned into - // display buttons in dialogs where the user might like - // a short-cut. The array should have four entries, but - // may have fewer or more entries. Wallets may omit - // later entries in the array. - let common_amounts: [Amount] - } +.. code-block:: swift + + public struct CurrencySpecification: Codable, Sendable { + // e.g. “Japanese Yen” or "Bitcoin (Mainnet)" + let name: String + // how many digits the user may enter after the decimal separator + let fractional_input_digits: Int + // €,$,£: 2; some arabic currencies: 3, ¥: 0 + let fractional_normal_digits: Int + // usually same as fractionalNormalDigits, but e.g. might be 2 for ¥ + let fractional_trailing_zero_digits: Int + // specifies whether the keys in `alt_unit_names' are symbols + // (e.g. €, k€) or names (e.g. BTC, mBTC), so that apps can decide + // how to render it (e.g. EUR 10 vs €10) + let alt_unit_names_are_symbols: Bool + // map of powers of 10 to alternative currency names / symbols, + // must always have an entry under "0" that defines the base name, + // e.g. "0 : €" or "3 : k€". For BTC, would be "0 : BTC, -3 : mBTC". + // This way, we can also communicate the currency symbol to be used. + let alt_unit_names: [Int : String] + + // An array of common amounts that should be turned into + // display buttons in dialogs where the user might like + // a short-cut. The array should have four entries, but + // may have fewer or more entries. Wallets may omit + // later entries in the array. + let common_amounts: [Amount] + } (Note: decimal_separator, group_separator and is_currency_name_leading were removed from this struct since they should always be taken from the user's @@ -133,51 +133,51 @@ Each currency should be specified in its own subsystem-independent currency, with the section name prefixed with "currency-". In that section. The map could be given directly in JSON. For example: - .. code-block:: ini - - [currency-euro] - ENABLED = YES - name = "Euro" - code = "EUR" - fractional_input_digits = 2 - fractional_normal_digits = 2 - fractional_trailing_zero_digits = 2 - alt_unit_names_are_symbols = YES - alt_unit_names = {"0":"€"} - common_amounts = EUR:10 EUR:25 EUR:50 EUR:100 - - [currency-japanese-yen] - ENABLED = YES - name = "Japanese Yen" - code = "JPY" - fractional_input_digits = 2 - fractional_normal_digits = 0 - fractional_trailing_zero_digits = 2 - alt_unit_names_are_symbols = YES - alt_unit_names = {"0":"¥"} - common_amounts = JPY:500 JPY:1000 JPY:5000 JPY:10000 - - [currency-bitcoin-mainnet] - ENABLED = NO - name = "Bitcoin (Mainnet)" - code = "BITCOINBTC" - fractional_input_digits = 8 - fractional_normal_digits = 3 - fractional_trailing_zero_digits = 0 - alt_unit_names_are_symbols = NO - alt_unit_names = {"0":"BTC","-3":"mBTC"} - common_amounts = BITCOINBTC:0.001 BITCOINBTC:0.01 BITCOINBTC:0.02 BITCOINBTC:0.025 - - [currency-ethereum] - ENABLED = NO - name = "WAI-ETHER (Ethereum)" - code = "EthereumWAI" - fractional_input_digits = 0 - fractional_normal_digits = 0 - fractional_trailing_zero_digits = 0 - alt_unit_names_are_symbols = NO - alt_unit_names = {"0":"WAI","3":"KWAI","6":"MWAI","9":"GWAI","12":"Szabo","15":"Finney","18":"Ether","21":"KEther","24":"MEther"} - common_amounts = EthereumWAI:0.001 EthereumWAI:0.01 +.. code-block:: ini + + [currency-euro] + ENABLED = YES + name = "Euro" + code = "EUR" + fractional_input_digits = 2 + fractional_normal_digits = 2 + fractional_trailing_zero_digits = 2 + alt_unit_names_are_symbols = YES + alt_unit_names = {"0":"€"} + common_amounts = EUR:10 EUR:25 EUR:50 EUR:100 + + [currency-japanese-yen] + ENABLED = YES + name = "Japanese Yen" + code = "JPY" + fractional_input_digits = 2 + fractional_normal_digits = 0 + fractional_trailing_zero_digits = 2 + alt_unit_names_are_symbols = YES + alt_unit_names = {"0":"¥"} + common_amounts = JPY:500 JPY:1000 JPY:5000 JPY:10000 + + [currency-bitcoin-mainnet] + ENABLED = NO + name = "Bitcoin (Mainnet)" + code = "BITCOINBTC" + fractional_input_digits = 8 + fractional_normal_digits = 3 + fractional_trailing_zero_digits = 0 + alt_unit_names_are_symbols = NO + alt_unit_names = {"0":"BTC","-3":"mBTC"} + common_amounts = BITCOINBTC:0.001 BITCOINBTC:0.01 BITCOINBTC:0.02 BITCOINBTC:0.025 + + [currency-ethereum] + ENABLED = NO + name = "WAI-ETHER (Ethereum)" + code = "EthereumWAI" + fractional_input_digits = 0 + fractional_normal_digits = 0 + fractional_trailing_zero_digits = 0 + alt_unit_names_are_symbols = NO + alt_unit_names = {"0":"WAI","3":"KWAI","6":"MWAI","9":"GWAI","12":"Szabo","15":"Finney","18":"Ether","21":"KEther","24":"MEther"} + common_amounts = EthereumWAI:0.001 EthereumWAI:0.01 Implementation considerations @@ -210,12 +210,12 @@ Definition of Done DoD is not satisfied yet, a user-facing feature **must** be behind a feature flag or dev-mode flag.) - * [x] Configuration (INI) format finalized and documented in the - ``taler.conf`` man page - * [x] Endpoints of libeufin-bank, fakebank, exchange and merchant return the information - * [x] SPAs use the information to render amounts - * [x] Wallet-core passes rendering information to wallet UIs - * [x] Cashier, Android PoS, WebExtension, Android and iOS Wallet render amounts accordingly +* [x] Configuration (INI) format finalized and documented in the + ``taler.conf`` man page +* [x] Endpoints of libeufin-bank, fakebank, exchange and merchant return the information +* [x] SPAs use the information to render amounts +* [x] Wallet-core passes rendering information to wallet UIs +* [x] Cashier, Android PoS, WebExtension, Android and iOS Wallet render amounts accordingly Alternatives diff --git a/design-documents/053-wallet-ui.rst b/design-documents/053-wallet-ui.rst @@ -1283,14 +1283,14 @@ the final amount currency. Initial amount label by operation: - * payment -> Price - * deposit -> Send - * peer-pull-credit -> Invoice - * peer-pull-debit -> Invoice - * peer-push-debit -> Send - * peer-push-credit -> Transfer - * withdrawal -> Transfer - * refund -> Refund +* payment -> Price +* deposit -> Send +* peer-pull-credit -> Invoice +* peer-pull-debit -> Invoice +* peer-push-debit -> Send +* peer-push-credit -> Transfer +* withdrawal -> Transfer +* refund -> Refund .. _cta-accept-tos-ref: diff --git a/design-documents/055-wallet-problem-report.rst b/design-documents/055-wallet-problem-report.rst @@ -113,5 +113,5 @@ Discussion / Q&A * When is a report amended vs a new report created? - * example: Exchange stops offering denomination D1. Later, it stops offering D2. - Are two reports generated or is the first report changed? + * example: Exchange stops offering denomination D1. Later, it stops offering D2. + Are two reports generated or is the first report changed? diff --git a/design-documents/062-pq-refresh.rst b/design-documents/062-pq-refresh.rst @@ -217,30 +217,30 @@ parameter ``κ`` for the cut-and-choose component of the protocol, for which this request is the commitment. Thus, various arguments are given ``κ``-times in this step. At present ``κ`` is always 3. - :http:statuscode:`200 OK`: - The request was successful. The response body is `MeltResponse` in this case. - :http:statuscode:`403 Forbidden`: - One of the signatures (by the old coin or the denomination signature over - the old coin) is invalid. - :http:statuscode:`404 Not found`: - The exchange does not recognize the denomination key as belonging to the exchange, - or it is past the legal expiration time (and thus forgotten entirely). - If the denomination key is unknown, the response will be - a `DenominationUnknownMessage`. - :http:statuscode:`409 Conflict`: - The operation is not allowed as the coin has insufficient - residual value, or because the same public key of the coin has been - previously used with a different denomination. Which case it is - can be decided by looking at the error code - (``TALER_EC_EXCHANGE_GENERIC_INSUFFICIENT_FUNDS`` or - ``TALER_EC_EXCHANGE_GENERIC_COIN_CONFLICTING_DENOMINATION_KEY``). - The response is `MeltForbiddenResponse` in both cases. - :http:statuscode:`410 Gone`: - The requested denomination key is not yet or no longer valid. - It either before the validity start, past the expiration or was revoked. - The response is a `DenominationGoneMessage`. - Clients must evaluate the error code provided to understand which of the - cases this is and handle it accordingly. +:http:statuscode:`200 OK`: + The request was successful. The response body is `MeltResponse` in this case. +:http:statuscode:`403 Forbidden`: + One of the signatures (by the old coin or the denomination signature over + the old coin) is invalid. +:http:statuscode:`404 Not found`: + The exchange does not recognize the denomination key as belonging to the exchange, + or it is past the legal expiration time (and thus forgotten entirely). + If the denomination key is unknown, the response will be + a `DenominationUnknownMessage`. +:http:statuscode:`409 Conflict`: + The operation is not allowed as the coin has insufficient + residual value, or because the same public key of the coin has been + previously used with a different denomination. Which case it is + can be decided by looking at the error code + (``TALER_EC_EXCHANGE_GENERIC_INSUFFICIENT_FUNDS`` or + ``TALER_EC_EXCHANGE_GENERIC_COIN_CONFLICTING_DENOMINATION_KEY``). + The response is `MeltForbiddenResponse` in both cases. +:http:statuscode:`410 Gone`: + The requested denomination key is not yet or no longer valid. + It either before the validity start, past the expiration or was revoked. + The response is a `DenominationGoneMessage`. + Clients must evaluate the error code provided to understand which of the + cases this is and handle it accordingly. Wire Formats diff --git a/design-documents/067-merchant-self-provisioning.rst b/design-documents/067-merchant-self-provisioning.rst @@ -174,10 +174,10 @@ Integration Tests These are scenarios that we consider basic and we should have an integration test for every one of them to know that the spec is implemented properly: - - A merchant doing an account's registration should get an email/phone notification with the comfirmation code. The merchant account should be in created state and only after using the confirmation code the account can be activated. - - A merchant with an activated account can call "forgot password". Merchant should get a notification with the confirmation code that can be used to call the endpoint to change the password. A new login the with new password needs to be tested. - - An user that makes an amount of request above the threshold should get 429 for "sign up" or "forgot password" endpoints. - - A merchant that doesn't have an activated account may be able to set and change all the configuration. But backend won't take any action with it (for example, it won't check KYC status). It may be also possible to delete the instance. +- A merchant doing an account's registration should get an email/phone notification with the comfirmation code. The merchant account should be in created state and only after using the confirmation code the account can be activated. +- A merchant with an activated account can call "forgot password". Merchant should get a notification with the confirmation code that can be used to call the endpoint to change the password. A new login the with new password needs to be tested. +- An user that makes an amount of request above the threshold should get 429 for "sign up" or "forgot password" endpoints. +- A merchant that doesn't have an activated account may be able to set and change all the configuration. But backend won't take any action with it (for example, it won't check KYC status). It may be also possible to delete the instance. Related Efforts diff --git a/design-documents/074-merchant-backend-simplification.rst b/design-documents/074-merchant-backend-simplification.rst @@ -248,22 +248,24 @@ Screens (in improved version): * overview screen with list of bank accounts - * Wire method (iban / x-taler-bank - * Account ("<iban> · <name>" / "<account name> · <host>") - * Host should not contain http(s):// - * Owner's name - * Readiness (show emoji, text on hover) - - * ✅ Ok - * ⚠️ Action Required - * ❌ Not working - * "Wire transfers" button => takes use to wire transfers page, with account selected - * "Edit" button - * "Delete" button + * Wire method (iban / x-taler-bank + * Account ("<iban> · <name>" / "<account name> · <host>") + + * Host should not contain http(s):// + * Owner's name + * Readiness (show emoji, text on hover) + + * ✅ Ok + * ⚠️ Action Required + * ❌ Not working + * "Wire transfers" button => takes use to wire transfers page, with account selected + * "Edit" button + * "Delete" button On click of a row with a bank account: Expand to show details Details of an expanded row: + * list of exchanges that require an action * Button "Show all exchanges" @@ -377,11 +379,11 @@ Suggested restructuring: * For PoS access tokens * For turnstile, wordpress, etc. - * ``About`` + * ``About`` - * Version of UI - * Version of merchant backend - * backend base URL + * Version of UI + * Version of merchant backend + * backend base URL Sidebar Simplification diff --git a/design-documents/078-taxes.rst b/design-documents/078-taxes.rst @@ -82,19 +82,19 @@ for taxes/accounting with a feature for user-interfaces of sales people. * Add a ``product_group`` table with: - (0) product group serial number - (1) instance ID (foreign key) - (2) product group name (unique with instance ID) - (3) product group description + (0) product group serial number + (1) instance ID (foreign key) + (2) product group name (unique with instance ID) + (3) product group description * Expand ``inventory_products`` table with: - (1) product group serial number (foreign key), allow NULL for default - (2) price_is_net boolean flag to indicate if the given price is the net - price and all taxes should be added on top of it, or if it is a - fixed retail price and the merchant covers all applicable taxes, - at the expense of profits if taxes vary (for example, to preserve - the price structure even if taxes vary between dine-in and take-out). + (1) product group serial number (foreign key), allow NULL for default + (2) price_is_net boolean flag to indicate if the given price is the net + price and all taxes should be added on top of it, or if it is a + fixed retail price and the merchant covers all applicable taxes, + at the expense of profits if taxes vary (for example, to preserve + the price structure even if taxes vary between dine-in and take-out). Phase 2: Money pots @@ -118,11 +118,11 @@ statistics. * Add a ``money_pot`` table with: - (0) money pot serial number - (1) instance ID (foreign key) - (2) money pot name (unique with instance ID) - (3) money pot description - (4) money pot total amount + (0) money pot serial number + (1) instance ID (foreign key) + (2) money pot name (unique with instance ID) + (3) money pot description + (4) money pot total amount * Code should update statistics whenever the money pot total amount is incremented. @@ -139,21 +139,21 @@ given product or order. * Add a ``tax_class`` table with: - (0) tax class serial number - (1) instance ID (foreign key) - (2) tax class name (unique with instance ID) - (3) tax rate (percentage), for taxes charged per value - (4) charge amount (multiplied with quantity of the product, - for example for tourist overnight tax per night, - for taxes charged per unit and not per value) - (5) tax description - (6) i18n description - (7) calculation mode (net total, cummulative) - (8) rounding mode (up, down, nearest) - (9) rounding unit (amount) - (10) money pot (where to accumulate taxes paid under this tax class). - to track known tax rules. - Unique should be "instance+tax class name". + (0) tax class serial number + (1) instance ID (foreign key) + (2) tax class name (unique with instance ID) + (3) tax rate (percentage), for taxes charged per value + (4) charge amount (multiplied with quantity of the product, + for example for tourist overnight tax per night, + for taxes charged per unit and not per value) + (5) tax description + (6) i18n description + (7) calculation mode (net total, cummulative) + (8) rounding mode (up, down, nearest) + (9) rounding unit (amount) + (10) money pot (where to accumulate taxes paid under this tax class). + to track known tax rules. + Unique should be "instance+tax class name". * When "rounding up" is used, round up from net to gross, but round down from gross to net. Similarly, when "rounding down" is used, diff --git a/frags/drupal-paivana-manual.rst b/frags/drupal-paivana-manual.rst @@ -71,11 +71,11 @@ fulfillment URL. Clearing cookies forgets paid access, but GNU Taler wallet's repurchase detection will restore the cookie if the user attempts to pay for the same article again. - .. note:: +.. note:: - This feature likely does not interact well with expiration - periods for article purchases. This is a bug that will - require further work to fully address. See #11443. + This feature likely does not interact well with expiration + periods for article purchases. This is a bug that will + require further work to fully address. See #11443. Installation diff --git a/frags/wordpress-paivana-manual.rst b/frags/wordpress-paivana-manual.rst @@ -76,11 +76,11 @@ same fulfillment URL. Clearing cookies forgets paid access, but GNU Taler wallet's repurchase detection will restore the cookie if the user attempts to pay for the same article again. - .. note:: +.. note:: - This feature likely does not interact well with expiration - periods for article purchases. This is a bug that will - require further work to fully address. See #11443. + This feature likely does not interact well with expiration + periods for article purchases. This is a bug that will + require further work to fully address. See #11443. Installation diff --git a/manpages/taler-exchange-offline.1.rst b/manpages/taler-exchange-offline.1.rst @@ -252,59 +252,59 @@ as the first argument to the subcommand. Afterwards, optional arguments can be given: - * ``conversion-url`` $URL: specifies that using this bank account is subject - to currency conversion. $URL must be the address of a currency conversion - REST API that allows merchants and wallets to determine the current - conversion rate. - - * ``open-banking-gateway`` $URL: specifies an - URL where wallets can find an open banking gateway to - initiate wire transfers when withdrawing digital cash - from this exchange. Optional (as obviously not every - exchange will have an open banking gateway attached). - - * ``prepared-transfer-url`` $URL: specifies a - Prepared transfer API base URL where wallets and merchants can - request (short) wire transfer subjects to wire funds to this - exchange without having to encode the full public key. - See also design document 80. - - * ``display-hint`` $PRIORITY $LABEL: specifies that this bank account should - be shown to the user with the given numeric $PRIORITY (higher is earlier, zero is hidden for manual withdrawal) - and with the given $LABEL. This is useful to ensure that if an exchange - has multiple bank accounts, we can show the user those that are most likely - useful first, and give them appropriately labeled hints for selecting other - accounts as well. A display hint is optional, if missing the priority is 1 - and the wallet must pick some appropriate label itself somehow. - - * ``credit-restriction`` $TYPE [$ARGS]: Specifies that there are - restrictions in place when crediting this bank account. Details depend on - the restriction $TYPE. This argument may be given multiple times, in which - case debitor accounts must satisfy all restrictions. Restriction types are - discussed below. - - * ``debit-restriction`` $TYPE [$ARGS]: Specifies that there are restrictions - in place when receiving money from the exchange. Wallets and merchants - must check that their target bank account satisfies these restrictions - before sending deposit requests to the exchange. Details depend on the - restriction $TYPE. This argument may be given multiple times, in which - case debitor accounts must satisfy all restrictions. Restriction types are - discussed below. +* ``conversion-url`` $URL: specifies that using this bank account is subject + to currency conversion. $URL must be the address of a currency conversion + REST API that allows merchants and wallets to determine the current + conversion rate. + +* ``open-banking-gateway`` $URL: specifies an + URL where wallets can find an open banking gateway to + initiate wire transfers when withdrawing digital cash + from this exchange. Optional (as obviously not every + exchange will have an open banking gateway attached). + +* ``prepared-transfer-url`` $URL: specifies a + Prepared transfer API base URL where wallets and merchants can + request (short) wire transfer subjects to wire funds to this + exchange without having to encode the full public key. + See also design document 80. + +* ``display-hint`` $PRIORITY $LABEL: specifies that this bank account should + be shown to the user with the given numeric $PRIORITY (higher is earlier, zero is hidden for manual withdrawal) + and with the given $LABEL. This is useful to ensure that if an exchange + has multiple bank accounts, we can show the user those that are most likely + useful first, and give them appropriately labeled hints for selecting other + accounts as well. A display hint is optional, if missing the priority is 1 + and the wallet must pick some appropriate label itself somehow. + +* ``credit-restriction`` $TYPE [$ARGS]: Specifies that there are + restrictions in place when crediting this bank account. Details depend on + the restriction $TYPE. This argument may be given multiple times, in which + case debitor accounts must satisfy all restrictions. Restriction types are + discussed below. + +* ``debit-restriction`` $TYPE [$ARGS]: Specifies that there are restrictions + in place when receiving money from the exchange. Wallets and merchants + must check that their target bank account satisfies these restrictions + before sending deposit requests to the exchange. Details depend on the + restriction $TYPE. This argument may be given multiple times, in which + case debitor accounts must satisfy all restrictions. Restriction types are + discussed below. The following types of credit- and debit-restrictions are supported: - * ``deny``: A $TYPE of ``deny`` means that this bank account cannot be used - for the given operation. ``deny`` takes no further arguments. +* ``deny``: A $TYPE of ``deny`` means that this bank account cannot be used + for the given operation. ``deny`` takes no further arguments. - * ``regex`` $EXPR $HINT $JSON: A $TYPE of ``regex`` means that the partner's - bank account ``payto``-URI representation must follow a certain regular - expression given in $EXPR where the syntax follows posix-egrep, but - without support for character classes, GNU extensions, back-references or - intervals. See - `Findutils Manual <https://www.gnu.org/software/findutils/manual/html_node/find_html/posix_002degrep-regular-expression-syntax.html>`_ - for a description of the posix-egrep syntax. The $HINT must be a - human-readable description of the $EXPR. $JSON should be a JSON array - mapping IETF BCP 47 language tags to localized versions of $HINT. +* ``regex`` $EXPR $HINT $JSON: A $TYPE of ``regex`` means that the partner's + bank account ``payto``-URI representation must follow a certain regular + expression given in $EXPR where the syntax follows posix-egrep, but + without support for character classes, GNU extensions, back-references or + intervals. See + `Findutils Manual <https://www.gnu.org/software/findutils/manual/html_node/find_html/posix_002degrep-regular-expression-syntax.html>`_ + for a description of the posix-egrep syntax. The $HINT must be a + human-readable description of the $EXPR. $JSON should be a JSON array + mapping IETF BCP 47 language tags to localized versions of $HINT. The subcommand takes no inputs from ``stdin`` or other subcommands. @@ -364,13 +364,13 @@ must be given in the usual Taler format of ``CURRENCY:NUMBER.FRACTION``. The arguments provided must include: - (1) Calendar year for which the fee applies, 'now' for the current year. - (2) History fee charged when inquiring about non-recent account history (not implemented, use zero!) - (3) Account fee charged for opening an account (not supported by wallet, use zero!) - (4) Purse fee. How much will the exchange charge for an abandoned purse. Also the minimum amount that can be in a purse that is not associated with an account. (Not well supported by wallets, use zero!) - (5) Purse timeout. How long does the exchange keep information about a purse around after it expired or was successfully merged? - (6) How long will the exchange preserve an account history. - (7) Number of free purses per account. (Irrelevant if purse fee is zero). +(1) Calendar year for which the fee applies, 'now' for the current year. +(2) History fee charged when inquiring about non-recent account history (not implemented, use zero!) +(3) Account fee charged for opening an account (not supported by wallet, use zero!) +(4) Purse fee. How much will the exchange charge for an abandoned purse. Also the minimum amount that can be in a purse that is not associated with an account. (Not well supported by wallets, use zero!) +(5) Purse timeout. How long does the exchange keep information about a purse around after it expired or was successfully merged? +(6) How long will the exchange preserve an account history. +(7) Number of free purses per account. (Irrelevant if purse fee is zero). The subcommand takes no inputs from ``stdin`` or other subcommands. @@ -384,11 +384,11 @@ enable-partner This subcommand informs an exchange about the wad fee and frequency to apply to a partner exchange. The arguments provided must include: - (1) Partner exchange base URL. - (2) Partner exchange master public key. - (3) Calendar year for which the fee applies, 'now' for the current year. - (4) Wad frequency, in minutes (for example, '30'). - (5) Wad fee (for example, 'KUDOS:0.1'). +(1) Partner exchange base URL. +(2) Partner exchange master public key. +(3) Calendar year for which the fee applies, 'now' for the current year. +(4) Wad frequency, in minutes (for example, '30'). +(5) Wad fee (for example, 'KUDOS:0.1'). aml-enable @@ -399,9 +399,9 @@ if 'rw' is given, the power to make AML decisions. The arguments provided must include: - (1) AML staff member public key (in base32 encoding) - (2) AML staff member legal name - (3) 'ro' or 'rw' to set access to read-only or read-write +(1) AML staff member public key (in base32 encoding) +(2) AML staff member legal name +(3) 'ro' or 'rw' to set access to read-only or read-write aml-disable @@ -411,8 +411,8 @@ Disable AML officer's account. Also updates the legal name. The arguments provided must include: - (1) AML staff member public key (in base32 encoding) - (2) AML staff member legal name +(1) AML staff member public key (in base32 encoding) +(2) AML staff member legal name add-partner @@ -423,11 +423,11 @@ between users of these exchanges. The arguments provided must include: - (1) Master public key of the partner exchange. - (2) Base URL of the partner exchange API. - (3) Wad fee to charge. - (4) Wad transfer frequency. - (5) Year for which the above options are to be configured, 'now' for the current year. +(1) Master public key of the partner exchange. +(2) Base URL of the partner exchange API. +(3) Wad fee to charge. +(4) Wad transfer frequency. +(5) Year for which the above options are to be configured, 'now' for the current year. upload diff --git a/manpages/taler-exchange-wire-gateway-client.1.rst b/manpages/taler-exchange-wire-gateway-client.1.rst @@ -39,10 +39,10 @@ expected to be used during testing or for diagnostics. You can do one of the following four operations during one invocation. - (1) Execute wire transfer from the exchange to consumer account (**-C**). - (2) Execute wire transfer from consumer account to the exchange (**-D**). - (3) Inspect credit history of the exchange (**-i**). - (4) Inspect debit history of the exchange (**-o**). +(1) Execute wire transfer from the exchange to consumer account (**-C**). +(2) Execute wire transfer from consumer account to the exchange (**-D**). +(3) Inspect credit history of the exchange (**-i**). +(4) Inspect debit history of the exchange (**-o**). Doing more than one of these at a time will result in an error. Note, however, that the **-C** and **-D** options also can be used to act as filters diff --git a/manpages/taler-exchange.conf.5.rst b/manpages/taler-exchange.conf.5.rst @@ -557,9 +557,9 @@ AGE_GROUPS zero'th group begins implicitly at 0. For example ``"10:18"`` defines three groups: - 1. Group 0: ages 0 through 9 (inclusive) - 2. Group 1: ages 10 through 17 (inclusive) - 3. Group 2: ages 18 and above + 1. Group 0: ages 0 through 9 (inclusive) + 2. Group 1: ages 10 through 17 (inclusive) + 3. Group 2: ages 18 and above If not given the default value ``"8:10:12:14:16:18:21"`` is used. diff --git a/manpages/taler-merchant.conf.5.rst b/manpages/taler-merchant.conf.5.rst @@ -346,9 +346,9 @@ The merchant backend can be used to fetch and submit periodic reports. The submission is handled using report generators. These are binaries that receive the main report from standard input (stdin), and are told: - * the mime type using a "-m" command-line option, - * the report target address using a "-t" command-line option, and - * a report description using a "-d" command-line option. +* the mime type using a "-m" command-line option, +* the report target address using a "-t" command-line option, and +* a report description using a "-d" command-line option. The report generators should return 0 on success. Custom report generators are configured using configuration sections [report-generator-$NAME], where $NAME diff --git a/system-administration/debian-repos.rst b/system-administration/debian-repos.rst @@ -27,8 +27,8 @@ supported distribution, right now we have one for Debian and one for Ubuntu. Systems should use: - - ``deb https://deb.taler.net/apt/debian trixie main`` for stable - - ``deb https://deb.taler.net/apt/debian trixie-testing main`` for testing +- ``deb https://deb.taler.net/apt/debian trixie main`` for stable +- ``deb https://deb.taler.net/apt/debian trixie-testing main`` for testing or equivalent for Ubuntu noble. diff --git a/taler-auditor-manual.rst b/taler-auditor-manual.rst @@ -243,12 +243,12 @@ on different machines) to run Taler auditor components. While it is possible to skip some of these entirely, or to run all of them as the same user, this is not recommended for security. The recommended set of users includes: - * auditor --- runs the main auditing process and HTTP backend - * sync --- synchronizes the ingres database with the production database - * helper --- runs taler-auditor-offline download and upload commands - * auditor-ingres --- imports database from exchange production system - * auditor-wire --- imports wire transfer data from bank production system - * offline --- manages the offline key, on a separate *offline* machine +* auditor --- runs the main auditing process and HTTP backend +* sync --- synchronizes the ingres database with the production database +* helper --- runs taler-auditor-offline download and upload commands +* auditor-ingres --- imports database from exchange production system +* auditor-wire --- imports wire transfer data from bank production system +* offline --- manages the offline key, on a separate *offline* machine It is suggested that you setup the first five users on the target system(s) using: @@ -260,8 +260,8 @@ using: Additionally, there are two canonical system users of relevance (which your distribution would typically create for you): - * www-data --- runs the HTTPS frontend (usually nginx or Apache) - * postgres --- runs the PostgreSQL database +* www-data --- runs the HTTPS frontend (usually nginx or Apache) +* postgres --- runs the PostgreSQL database Databases and users @@ -269,10 +269,10 @@ Databases and users We recommend using the following databases for the auditor: - * exchange-ingres --- synchronized exchange database over the network - * exchange-production --- local copy of exchange database with trusted schema - * auditor --- auditor production database with current state of the audit - * libeufin --- local state of the auditor-wire tool for the bank transfer data import +* exchange-ingres --- synchronized exchange database over the network +* exchange-production --- local copy of exchange database with trusted schema +* auditor --- auditor production database with current state of the audit +* libeufin --- local state of the auditor-wire tool for the bank transfer data import As the *postgres* user, you can create these databases using: @@ -446,15 +446,15 @@ also need (read-only) access to a (recent, current, synchronized) copy of the exchange's database. The configuration options are the same that are also used when configuring the exchange' database: - .. code-block:: ini +.. code-block:: ini - [exchange] - ... - DB = postgres - ... + [exchange] + ... + DB = postgres + ... - [exchangedb-postgres] - CONFIG = postgres:///exchangedemo + [exchangedb-postgres] + CONFIG = postgres:///exchangedemo Legal conditions for using the service @@ -848,18 +848,18 @@ during schema-changing database upgrades as without coordination the database replication or ``taler-auditor-sync`` will likely experience problematic failures. In general, we recommend: - * halting the exchange business logic, - * allowing the replication and ``taler-auditor-sync`` to complete - (see also the **-t** option of ``taler-auditor-sync``) - * completing a ``taler-audit`` run against the old schema - * migrating the exchange schema (``taler-exchange-dbinit``) of - the master database, possibly the ingres database and the - auditor's production copy - * migrating the auditor database (``taler-auditor-dbinit``) - * resuming database replication between the exchange's master - database and the auditor's ingres copy - * resuming ``taler-auditor-sync`` - * resuming the regular exchange and auditor business logic +* halting the exchange business logic, +* allowing the replication and ``taler-auditor-sync`` to complete + (see also the **-t** option of ``taler-auditor-sync``) +* completing a ``taler-audit`` run against the old schema +* migrating the exchange schema (``taler-exchange-dbinit``) of + the master database, possibly the ingres database and the + auditor's production copy +* migrating the auditor database (``taler-auditor-dbinit``) +* resuming database replication between the exchange's master + database and the auditor's ingres copy +* resuming ``taler-auditor-sync`` +* resuming the regular exchange and auditor business logic Regardless, the above is merely the general rule. Please review the specific release notes to ensure this procedure is correct for the specific upgrade. diff --git a/taler-exchange-manual.rst b/taler-exchange-manual.rst @@ -342,15 +342,15 @@ Before you start To deploy this with a real bank, you need: - * IBAN of the bank account to use - * BIC of the bank - * EBICS host, user and partner IDs +* IBAN of the bank account to use +* BIC of the bank +* EBICS host, user and partner IDs Information to write down during the installation: - * LibEuFin Nexus superuser password - * Taler facade base URL - * exchange Nexus username and password +* LibEuFin Nexus superuser password +* Taler facade base URL +* exchange Nexus username and password @@ -906,9 +906,9 @@ The :ref:`Taler Wire Gateway <taler-wire-gateway-http-api>` is an API that connects the Taler exchange to the underlying core banking system. There are several implementations of wire gateways: - * `Project deploymerization <https://git.taler.net/taler/depolymerization/files.html>`_ implements a wire gateway on top of Bitcoin or Ethereum - * The :ref:`libeufin-bank <libeufin-bank>` provides a wire gateway interface on top of a regional currency bank - * The **taler-fakebank-run** command is an in-memory bank simulator with a wire gateway interface for testing +* `Project deploymerization <https://git.taler.net/taler/depolymerization/files.html>`_ implements a wire gateway on top of Bitcoin or Ethereum +* The :ref:`libeufin-bank <libeufin-bank>` provides a wire gateway interface on top of a regional currency bank +* The **taler-fakebank-run** command is an in-memory bank simulator with a wire gateway interface for testing .. FIXME :ref:`libeufin-nexus <libeufin-nexus>` is an implementation of the Wire Gateway API for the EBICS protocol. Add to list above once nexus implements the TWG directly! @@ -916,8 +916,8 @@ Before continuing, you need to decide which wire gateway you want to use, and install and configure it on your system. Afterwards, you need to have two key pieces of information from that setup: - * The username and password to access the exchange's account in the system. - * The ``payto://`` URI of that account (see `RFC 8905 <https://www.rfc-editor.org/rfc/rfc8905>`_). +* The username and password to access the exchange's account in the system. +* The ``payto://`` URI of that account (see `RFC 8905 <https://www.rfc-editor.org/rfc/rfc8905>`_). If you use the libeufin-bank, you need to set a special configuration option because the taler-exchange-wire-gateway-client does not yet support token @@ -1188,13 +1188,13 @@ without offline keys its not fully operational. To make the exchange HTTP service fully operational, the following steps involving the offline signing machine must be completed: - 1. The public keys of various online keys used by the exchange service are exported - via a management HTTP API. - 2. The offline signing system validates this request and signs it. - Additionally, the offline signing system signs policy messages - to configure the exchange's bank accounts and associated fees. - 3. The messages generated by the offline signing system are uploaded - via the management API of the exchange HTTP service. +1. The public keys of various online keys used by the exchange service are exported + via a management HTTP API. +2. The offline signing system validates this request and signs it. + Additionally, the offline signing system signs policy messages + to configure the exchange's bank accounts and associated fees. +3. The messages generated by the offline signing system are uploaded + via the management API of the exchange HTTP service. A typical minimal setup would look something like this: diff --git a/taler-kyc-manual.rst b/taler-kyc-manual.rst @@ -62,12 +62,12 @@ in transactions at certain points. Taler permits an exchange to require know-your-customer (KYC) or know-your-business (KYB) data under the following circumstances: - * Customer withdraws money over a threshold - * Wallet receives (via refunds) money resulting in a balance over a threshold - * Wallet receives money via P2P payments over a threshold - * Merchant receives money over a threshold - * Merchant deposits digital cash over a threshold (**planned feature, bug 9040**) - * Reserve is "opened" for invoicing (**planned feature**) +* Customer withdraws money over a threshold +* Wallet receives (via refunds) money resulting in a balance over a threshold +* Wallet receives money via P2P payments over a threshold +* Merchant receives money over a threshold +* Merchant deposits digital cash over a threshold (**planned feature, bug 9040**) +* Reserve is "opened" for invoicing (**planned feature**) Any of the above requests can trigger the KYC process, which can be illustrated as follows: @@ -571,58 +571,58 @@ condition triggers: The operation types of KYC rules refer to the following scenarios: - * **AGGREGATION**: Triggered when an exchange is about to do a - wire transfer to a merchant. Such wire transfers typically have - aggregated multiple smaller deposits, and thus enforcing KYC rules - at aggregation time is more efficient than checking individual - deposits. Plus, checking at the aggregation level is likely to - render structuring inherently ineffective. - Enforced by the exchange. - - * **BALANCE**: Triggered whenever the balance of a wallet is increased. - Can only be used with a timeframe of zero, as this is about the absolute - amount that can be stored at any time in a compliant wallet. - Enforced by the wallet. - - * **CLOSE**: Triggered when a reserve is closed (explicitly by a wallet - or implicitly by timeout). Use with caution, as this may prevent - an exchange from returning funds that were not withdrawn to users. - Enforced by the exchange. - (Note: This rule is so far not used in production - anywhere, thus likely not tested well yet.) - - * **DEPOSIT**: Sets a limit on the amount that can be deposited by - a merchant into their bank account. Can be used with a timeframe - of zero to effectively set another transaction limit that additionally - only applies to deposits (and not P2P payments), or with a non-zero - timeframe to limit the amount a merchant can deposit over time. - Usually used with a limit of zero to enforce merchant onboarding - prior to first payment processing. Inefficient to enforce limits - later, usually for merchants that have been onboarded **AGGREGATION** - limits should be set instead. - Enforced by the exchange. - - * **MERGE**: Triggered when a user received digital cash from another - wallet. - Enforced by the exchange. - - * **REFUND**: Limit on the amount that can be refunded per - transaction by a compliant merchant to a compliant wallet. - Can only be used with a timeframe of zero, as this is about - the amount that can be funded on an individual purchase. - Enforced both wallet-side and merchant-side (enforcement by - the exchange could be implemented in the future, but is - tricky as the exchange sees refunds per coin and not per - purchase). - - * **TRANSACTION**: Refers to all transactions of a wallet where digital - cash is spent. Can be used with a timeframe of zero to set a transaction - limit, or with a non-zero timeframe to limit the spending rate over time. - Applies to spending money both in P2P and merchant transactions. - Enforced by wallets and merchants. - - * **WITHDRAW**: Triggered when a user withdraws digital cash from their - bank account. Enforced by the exchange. +* **AGGREGATION**: Triggered when an exchange is about to do a + wire transfer to a merchant. Such wire transfers typically have + aggregated multiple smaller deposits, and thus enforcing KYC rules + at aggregation time is more efficient than checking individual + deposits. Plus, checking at the aggregation level is likely to + render structuring inherently ineffective. + Enforced by the exchange. + +* **BALANCE**: Triggered whenever the balance of a wallet is increased. + Can only be used with a timeframe of zero, as this is about the absolute + amount that can be stored at any time in a compliant wallet. + Enforced by the wallet. + +* **CLOSE**: Triggered when a reserve is closed (explicitly by a wallet + or implicitly by timeout). Use with caution, as this may prevent + an exchange from returning funds that were not withdrawn to users. + Enforced by the exchange. + (Note: This rule is so far not used in production + anywhere, thus likely not tested well yet.) + +* **DEPOSIT**: Sets a limit on the amount that can be deposited by + a merchant into their bank account. Can be used with a timeframe + of zero to effectively set another transaction limit that additionally + only applies to deposits (and not P2P payments), or with a non-zero + timeframe to limit the amount a merchant can deposit over time. + Usually used with a limit of zero to enforce merchant onboarding + prior to first payment processing. Inefficient to enforce limits + later, usually for merchants that have been onboarded **AGGREGATION** + limits should be set instead. + Enforced by the exchange. + +* **MERGE**: Triggered when a user received digital cash from another + wallet. + Enforced by the exchange. + +* **REFUND**: Limit on the amount that can be refunded per + transaction by a compliant merchant to a compliant wallet. + Can only be used with a timeframe of zero, as this is about + the amount that can be funded on an individual purchase. + Enforced both wallet-side and merchant-side (enforcement by + the exchange could be implemented in the future, but is + tricky as the exchange sees refunds per coin and not per + purchase). + +* **TRANSACTION**: Refers to all transactions of a wallet where digital + cash is spent. Can be used with a timeframe of zero to set a transaction + limit, or with a non-zero timeframe to limit the spending rate over time. + Applies to spending money both in P2P and merchant transactions. + Enforced by wallets and merchants. + +* **WITHDRAW**: Triggered when a user withdraws digital cash from their + bank account. Enforced by the exchange. Configuration of AML programs @@ -1039,16 +1039,16 @@ customers), use "--test". The tool operates by decrypting all of the KYC attributes from the exchange database and passes them to a helper program which must then determine - * which sanction list record matches best, - * how well that sanction list record matches, and - * how certain the tool is that the match is accurate. +* which sanction list record matches best, +* how well that sanction list record matches, and +* how certain the tool is that the match is accurate. Based on this assessment by the helper program, **taler-exchange-sanctionlist** will then either - * freeze the account and flag it for investigation (likely match), - * only flag the account for investigation (possible match), or - * allow the account to continue as normal (no match) +* freeze the account and flag it for investigation (likely match), +* only flag the account for investigation (possible match), or +* allow the account to continue as normal (no match) To avoid the same account being flagged repeatedly for investigation due to a false-positive match with the sanction list, AML staff can @@ -1105,22 +1105,22 @@ Generic Errors Templates A number of templates are used for generic errors. These are: - * kyc-proof-already-done (KYC process already completed) - * kyc-bad-request (400 Bad Request) - * kyc-proof-endpoint-unknown (404 Not Found for KYC logic) - * kyc-proof-internal-error (500 Internal Server Error) - * kyc-proof-target-unknown (404 Not Found for KYC operation) +* kyc-proof-already-done (KYC process already completed) +* kyc-bad-request (400 Bad Request) +* kyc-proof-endpoint-unknown (404 Not Found for KYC logic) +* kyc-proof-internal-error (500 Internal Server Error) +* kyc-proof-target-unknown (404 Not Found for KYC operation) All of these templates are instantiated using the following information: - * ec: Integer; numeric Taler error code, should be shown to indicate the - error compactly for reporting to developers +* ec: Integer; numeric Taler error code, should be shown to indicate the + error compactly for reporting to developers - * hint: String; human-readable Taler error code, should be shown for the - user to understand the error +* hint: String; human-readable Taler error code, should be shown for the + user to understand the error - * message: String; optional, extended human-readable text provided to elaborate - on the error, should be shown to provide additional context +* message: String; optional, extended human-readable text provided to elaborate + on the error, should be shown to provide additional context kycaid-invalid-request @@ -1131,17 +1131,17 @@ The KYCaid plugin does not support requests to the This template is instantiated using the following information: - * ec: Integer; numeric Taler error code, should be shown to indicate the - error compactly for reporting to developers +* ec: Integer; numeric Taler error code, should be shown to indicate the + error compactly for reporting to developers - * hint: String; human-readable Taler error code, should be shown for the - user to understand the error +* hint: String; human-readable Taler error code, should be shown for the + user to understand the error - * error: String; error code from the server +* error: String; error code from the server - * error_details: String; optional error description from the server +* error_details: String; optional error description from the server - * error_uri: optional URI with further details about the error from the server +* error_uri: optional URI with further details about the error from the server @@ -1154,11 +1154,11 @@ properly authenticated (HTTP 403 Forbidden). This template is instantiated using the following information: - * ec: Integer; numeric Taler error code, should be shown to indicate the - error compactly for reporting to developers +* ec: Integer; numeric Taler error code, should be shown to indicate the + error compactly for reporting to developers - * hint: String; human-readable Taler error code, should be shown for the - user to understand the error +* hint: String; human-readable Taler error code, should be shown for the + user to understand the error oauth2-authorization-failure @@ -1169,15 +1169,15 @@ code provided was invalid (HTTP 403 Forbidden). This template is instantiated using the following information: - * ec: Integer; numeric Taler error code, should be shown to indicate the - error compactly for reporting to developers +* ec: Integer; numeric Taler error code, should be shown to indicate the + error compactly for reporting to developers - * hint: String; human-readable Taler error code, should be shown for the - user to understand the error +* hint: String; human-readable Taler error code, should be shown for the + user to understand the error - * error: String; error code from the server +* error: String; error code from the server - * error_message: String; error message from the server +* error_message: String; error message from the server oauth2-authorization-failure-malformed @@ -1188,15 +1188,15 @@ a malformed response (HTTP 502 Bad Gateway). This template is instantiated using the following information: - * ec: Integer; numeric Taler error code, should be shown to indicate the - error compactly for reporting to developers +* ec: Integer; numeric Taler error code, should be shown to indicate the + error compactly for reporting to developers - * hint: string; human-readable Taler error code, should be shown for the - user to understand the error +* hint: string; human-readable Taler error code, should be shown for the + user to understand the error - * debug: boolean; true if we are running in debug mode and are allowed to return HTML with potentially sensitive information +* debug: boolean; true if we are running in debug mode and are allowed to return HTML with potentially sensitive information - * server_response: Object; could be NULL; this includes the (malformed) OAuth2 server response, it should be shown to the user if "debug" is true +* server_response: Object; could be NULL; this includes the (malformed) OAuth2 server response, it should be shown to the user if "debug" is true oauth2-bad-request @@ -1206,13 +1206,13 @@ The client made an invalid request (HTTP 400 Bad Request). This template is instantiated using the following information: - * ec: Integer; numeric Taler error code, should be shown to indicate the - error compactly for reporting to developers +* ec: Integer; numeric Taler error code, should be shown to indicate the + error compactly for reporting to developers - * hint: String; human-readable Taler error code, should be shown for the - user to understand the error +* hint: String; human-readable Taler error code, should be shown for the + user to understand the error - * message: String; additional error message elaborating on what was bad about the request +* message: String; additional error message elaborating on what was bad about the request oauth2-conversion-failure @@ -1223,19 +1223,19 @@ format failed (HTTP 502 Bad Gateway). This template is instantiated using the following information: - * ec: Integer; numeric Taler error code, should be shown to indicate the - error compactly for reporting to developers +* ec: Integer; numeric Taler error code, should be shown to indicate the + error compactly for reporting to developers - * hint: string; human-readable Taler error code, should be shown for the - user to understand the error +* hint: string; human-readable Taler error code, should be shown for the + user to understand the error - * debug: boolean; true if we are running in debug mode and are allowed to return HTML with potentially sensitive information +* debug: boolean; true if we are running in debug mode and are allowed to return HTML with potentially sensitive information - * converter: String; name of the conversion command that failed which was used by the Exchange +* converter: String; name of the conversion command that failed which was used by the Exchange - * attributes: Object; attributes returned by the conversion command, often NULL (after all, conversion failed) +* attributes: Object; attributes returned by the conversion command, often NULL (after all, conversion failed) - * message: error message elaborating on the conversion failure +* message: error message elaborating on the conversion failure oauth2-provider-failure @@ -1246,13 +1246,13 @@ provider (HTTP 502 Bad Gateway). This template is instantiated using the following information: - * ec: Integer; numeric Taler error code, should be shown to indicate the - error compactly for reporting to developers +* ec: Integer; numeric Taler error code, should be shown to indicate the + error compactly for reporting to developers - * hint: String; human-readable Taler error code, should be shown for the - user to understand the error +* hint: String; human-readable Taler error code, should be shown for the + user to understand the error - * message: String; could be NULL; text elaborating on the details of the failure +* message: String; could be NULL; text elaborating on the details of the failure oauth2-state-invalid @@ -1264,13 +1264,13 @@ so the request was ignored (HTTP 403 Forbidden). This template is instantiated using the following information: - * ec: Integer; numeric Taler error code, should be shown to indicate the - error compactly for reporting to developers +* ec: Integer; numeric Taler error code, should be shown to indicate the + error compactly for reporting to developers - * hint: String; human-readable Taler error code, should be shown for the - user to understand the error +* hint: String; human-readable Taler error code, should be shown for the + user to understand the error - * message: String; additional error message elaborating on what was wrong +* message: String; additional error message elaborating on what was wrong persona-exchange-unauthorized @@ -1280,15 +1280,15 @@ The Persona server refused our request (HTTP 403 Forbidden from Persona, returne This template is instantiated using the following information: - * ec: Integer; numeric Taler error code, should be shown to indicate the - error compactly for reporting to developers +* ec: Integer; numeric Taler error code, should be shown to indicate the + error compactly for reporting to developers - * hint: String; human-readable Taler error code, should be shown for the - user to understand the error +* hint: String; human-readable Taler error code, should be shown for the + user to understand the error - * data: Object; data returned from Persona service, optional +* data: Object; data returned from Persona service, optional - * persona_http_status: Integer; HTTP status code returned by Persona +* persona_http_status: Integer; HTTP status code returned by Persona persona-load-failure @@ -1298,15 +1298,15 @@ The Persona server refused our request (HTTP 429 Too Many Requests from Persona, This template is instantiated using the following information: - * ec: Integer; numeric Taler error code, should be shown to indicate the - error compactly for reporting to developers +* ec: Integer; numeric Taler error code, should be shown to indicate the + error compactly for reporting to developers - * hint: String; human-readable Taler error code, should be shown for the - user to understand the error +* hint: String; human-readable Taler error code, should be shown for the + user to understand the error - * data: Object; data returned from Persona service, optional +* data: Object; data returned from Persona service, optional - * persona_http_status: Integer; HTTP status code returned by Persona +* persona_http_status: Integer; HTTP status code returned by Persona persona-exchange-unpaid @@ -1316,15 +1316,15 @@ The Persona server refused our request (HTTP 402 Payment Required from Persona, This template is instantiated using the following information: - * ec: Integer; numeric Taler error code, should be shown to indicate the - error compactly for reporting to developers +* ec: Integer; numeric Taler error code, should be shown to indicate the + error compactly for reporting to developers - * hint: String; human-readable Taler error code, should be shown for the - user to understand the error +* hint: String; human-readable Taler error code, should be shown for the + user to understand the error - * data: Object; data returned from Persona service, optional +* data: Object; data returned from Persona service, optional - * persona_http_status: Integer; HTTP status code returned by Persona +* persona_http_status: Integer; HTTP status code returned by Persona @@ -1335,15 +1335,15 @@ The Persona server refused our request (HTTP 400, 403, 409, 422 from Persona, re This template is instantiated using the following information: - * ec: Integer; numeric Taler error code, should be shown to indicate the - error compactly for reporting to developers +* ec: Integer; numeric Taler error code, should be shown to indicate the + error compactly for reporting to developers - * hint: String; human-readable Taler error code, should be shown for the - user to understand the error +* hint: String; human-readable Taler error code, should be shown for the + user to understand the error - * data: Object; data returned from Persona service, optional +* data: Object; data returned from Persona service, optional - * persona_http_status: Integer; HTTP status code returned by Persona +* persona_http_status: Integer; HTTP status code returned by Persona persona-invalid-response @@ -1354,15 +1354,15 @@ unexpected way; returned as a HTTP 502 Bad Gateway. This template is instantiated using the following information: - * ec: Integer; numeric Taler error code, should be shown to indicate the - error compactly for reporting to developers +* ec: Integer; numeric Taler error code, should be shown to indicate the + error compactly for reporting to developers - * hint: string; human-readable Taler error code, should be shown for the - user to understand the error +* hint: string; human-readable Taler error code, should be shown for the + user to understand the error - * debug: boolean; true if we are running in debug mode and are allowed to return HTML with potentially sensitive information +* debug: boolean; true if we are running in debug mode and are allowed to return HTML with potentially sensitive information - * server_response: Object; could be NULL; this includes the (malformed) OAuth2 server response, it should be shown to the user if "debug" is true +* server_response: Object; could be NULL; this includes the (malformed) OAuth2 server response, it should be shown to the user if "debug" is true persona-network-timeout @@ -1372,15 +1372,15 @@ The Persona server refused our request (HTTP 408 from Persona, returned as a HTT This template is instantiated using the following information: - * ec: Integer; numeric Taler error code, should be shown to indicate the - error compactly for reporting to developers +* ec: Integer; numeric Taler error code, should be shown to indicate the + error compactly for reporting to developers - * hint: String; human-readable Taler error code, should be shown for the - user to understand the error +* hint: String; human-readable Taler error code, should be shown for the + user to understand the error - * data: Object; data returned from Persona service, optional +* data: Object; data returned from Persona service, optional - * persona_http_status: Integer; HTTP status code returned by Persona +* persona_http_status: Integer; HTTP status code returned by Persona persona-kyc-failed @@ -1390,11 +1390,11 @@ The Persona server indicated a problem with the KYC process, saying it was not c This template is instantiated using the following information: - * persona_inquiry_id: String; internal ID of the inquiry within Persona, useful for further diagnostics by staff +* persona_inquiry_id: String; internal ID of the inquiry within Persona, useful for further diagnostics by staff - * data: Object; could be NULL; this includes the server response, it contains extensive diagnostics, see Persona documentation on their ``/api/v1/inquiries/$ID``. +* data: Object; could be NULL; this includes the server response, it contains extensive diagnostics, see Persona documentation on their ``/api/v1/inquiries/$ID``. - * persona_http_status: Integer; HTTP status code returned by Persona +* persona_http_status: Integer; HTTP status code returned by Persona persona-provider-failure ------------------------ @@ -1403,12 +1403,12 @@ The Persona server refused our request (HTTP 500 from Persona, returned as a HTT This template is instantiated using the following information: - * ec: Integer; numeric Taler error code, should be shown to indicate the - error compactly for reporting to developers +* ec: Integer; numeric Taler error code, should be shown to indicate the + error compactly for reporting to developers - * hint: String; human-readable Taler error code, should be shown for the - user to understand the error +* hint: String; human-readable Taler error code, should be shown for the + user to understand the error - * data: Object; data returned from Persona service, optional +* data: Object; data returned from Persona service, optional - * persona_http_status: Integer; HTTP status code returned by Persona +* persona_http_status: Integer; HTTP status code returned by Persona diff --git a/taler-merchant-manual.rst b/taler-merchant-manual.rst @@ -132,15 +132,15 @@ controlled via a bearer token (to be set in the HTTP "Authorization" header). All instances share the same *database*, top-level HTTP(S) address and the main Taler configuration (especially the accepted *currency* and *exchanges*). - .. note:: +.. note:: - This documentation does not use the term "user" or "username" in - conjunction with instances as that might create confusion between - instances with paying customers using the system. We also do not use the - term "account" in conjunction with instances, as that might cause - confusion with bank accounts. That said, conceptually it is of course - acceptable to consider instances to be the "users" or "accounts" of a - merchant backend and the bearer token is equivalent to a passphrase. + This documentation does not use the term "user" or "username" in + conjunction with instances as that might create confusion between + instances with paying customers using the system. We also do not use the + term "account" in conjunction with instances, as that might cause + confusion with bank accounts. That said, conceptually it is of course + acceptable to consider instances to be the "users" or "accounts" of a + merchant backend and the bearer token is equivalent to a passphrase. .. _instance-bank-account: @@ -664,7 +664,7 @@ section, the following options need to be configured: [merchant-exchange-kudos] MASTER_KEY = "GNRJCH0HYKN59939JC0CJ2JDC7ZNEBSATJFF00CVS3WPG4TQEA7G" - You can find out this key by running ``curl https://exchange.demo.taler.net/keys | jq .master_public_key``. + You can find out this key by running ``curl https://exchange.demo.taler.net/keys | jq .master_public_key``. - The ``CURRENCY`` option specifies the exchange’s currency. For the Taler demonstrator, use: @@ -785,9 +785,9 @@ should return some basic configuration status data about the service. Please note that your backend might then be globally reachable without any access control. You can either: - * Use the ``--auth=$TOKEN`` command-line option to **taler-merchant-httpd** to set an access token to be provided in an ``Authorization: Bearer $TOKEN`` HTTP header. Note that this can be used at anytime to override access control, but remains only in effect until a first instance is created or an existing instance authentication setting is modified. - * Set the ``TALER_MERCHANT_TOKEN`` environment variable to ``$TOKEN`` for the same effect. This method has the advantage of ``$TOKEN`` not being visible as a command-line interface to other local users on the same machine. - * Set up an instance with an authentication token before some unauthorized person has a chance to access the backend. As the backend is useless without any instance and the chances of remote attackers during the initial configuration is low, this is probably sufficient for most use-cases. Still, keep the first two scenarios in mind in case you ever forget your access token! +* Use the ``--auth=$TOKEN`` command-line option to **taler-merchant-httpd** to set an access token to be provided in an ``Authorization: Bearer $TOKEN`` HTTP header. Note that this can be used at anytime to override access control, but remains only in effect until a first instance is created or an existing instance authentication setting is modified. +* Set the ``TALER_MERCHANT_TOKEN`` environment variable to ``$TOKEN`` for the same effect. This method has the advantage of ``$TOKEN`` not being visible as a command-line interface to other local users on the same machine. +* Set up an instance with an authentication token before some unauthorized person has a chance to access the backend. As the backend is useless without any instance and the chances of remote attackers during the initial configuration is low, this is probably sufficient for most use-cases. Still, keep the first two scenarios in mind in case you ever forget your access token! Production systems should additionally be configured to bind to a UNIX domain socket and use TLS for improved network privacy, see :ref:`Secure setup <Secure-setup>`. @@ -961,29 +961,29 @@ fee amount for each order it creates. Finally, you need to specify several settings relating to default deadlines. - (1) The "Default payment delay" specifies when an offer expires. The - customer basically has this amount of time to pay, or the backend will - refuse the payment and require the customer to get a new quote. - - (2) The "Default refund delay" specifies how long the customer may receive - refunds. The refund period is cumulative on top of the "Default payment - delay". Thus, the refund period ends independently of when the customer - actually paid for the order. The exchange will **not** wire the funds to the - merchant before the refund deadline lapses, as after the funds have been - wired refunds using Taler are no longer possible. - - (3) The "Default wire transfer delay" specifies how soon the exchange - **must** wire the funds **after** the refund deadline. The delay is again - cumulative on top of the "Default payment delay" and the "Default refund - delay". However, the resulting time is still not the actual wire - deadline, as first the "Default wire rounding interval" is also considered. - - (4) The "Default wire rounding interval" specifies to what period the - wire deadline should be rounded up to. The ultimate wire deadline is - computed by adding the default payment, rounding and wire delays to - the current time and rounding the resulting timestamp to the - "Default wire rounding interval". Typical values include - end-of-day, end-of-week, end-of-month, end-of-quarter or end-of-year. +(1) The "Default payment delay" specifies when an offer expires. The + customer basically has this amount of time to pay, or the backend will + refuse the payment and require the customer to get a new quote. + +(2) The "Default refund delay" specifies how long the customer may receive + refunds. The refund period is cumulative on top of the "Default payment + delay". Thus, the refund period ends independently of when the customer + actually paid for the order. The exchange will **not** wire the funds to the + merchant before the refund deadline lapses, as after the funds have been + wired refunds using Taler are no longer possible. + +(3) The "Default wire transfer delay" specifies how soon the exchange + **must** wire the funds **after** the refund deadline. The delay is again + cumulative on top of the "Default payment delay" and the "Default refund + delay". However, the resulting time is still not the actual wire + deadline, as first the "Default wire rounding interval" is also considered. + +(4) The "Default wire rounding interval" specifies to what period the + wire deadline should be rounded up to. The ultimate wire deadline is + computed by adding the default payment, rounding and wire delays to + the current time and rounding the resulting timestamp to the + "Default wire rounding interval". Typical values include + end-of-day, end-of-week, end-of-month, end-of-quarter or end-of-year. .. note:: @@ -1653,32 +1653,32 @@ Page shown to request the user to make a payment. This template is instantiated using the following information: - * taler_pay_uri: String; the ``taler://pay/`` URI that must be given - to the wallet to initiate the payment +* taler_pay_uri: String; the ``taler://pay/`` URI that must be given + to the wallet to initiate the payment - * taler_pay_qrcode_svg: Image; an SVG image of the QR code with the - ``taler_pay_uri``. +* taler_pay_qrcode_svg: Image; an SVG image of the QR code with the + ``taler_pay_uri``. - * order_summary: String; a text summarizing the order +* order_summary: String; a text summarizing the order - * order_status_url: URL of the merchant backend where the order status - can be found, useful for long-polling to check if the order has been paid +* order_status_url: URL of the merchant backend where the order status + can be found, useful for long-polling to check if the order has been paid - * order_id: String; the merchant's identifier for the order +* order_id: String; the merchant's identifier for the order - * merchant_name: String; the configured display name of the merchant - instance +* merchant_name: String; the configured display name of the merchant + instance - * order_amount: Optional amount; the amount to pay when the order has one - payment option or the wallet has selected an option +* order_amount: Optional amount; the amount to pay when the order has one + payment option or the wallet has selected an option - * multiple_payment_options: Boolean; true when the wallet must select one - of multiple payment options and no single amount can be displayed yet +* multiple_payment_options: Boolean; true when the wallet must select one + of multiple payment options and no single amount can be displayed yet - * claimed: Boolean; true after a wallet has claimed the order but before - payment has completed +* claimed: Boolean; true after a wallet has claimed the order but before + payment has completed - * pay_deadline: Timestamp; the deadline for completing the payment +* pay_deadline: Timestamp; the deadline for completing the payment offer_refund @@ -1688,31 +1688,31 @@ Page shown to offer a customer a refund. This template is instantiated using the following information: - * taler_refund_uri: String; the ``taler://refund/`` URI that must be given - to the wallet to initiate collection of the refund +* taler_refund_uri: String; the ``taler://refund/`` URI that must be given + to the wallet to initiate collection of the refund - * taler_refund_qrcode_svg: Image; an SVG image of the QR code with the - ``taler_refund_uri``. +* taler_refund_qrcode_svg: Image; an SVG image of the QR code with the + ``taler_refund_uri``. - * refund_amount: Amount; how much did the merchant refund +* refund_amount: Amount; how much did the merchant refund - * refund_taken: Amount; how much did the customer already take back in refunds +* refund_taken: Amount; how much did the customer already take back in refunds - * order_summary: String; a text summarizing the order +* order_summary: String; a text summarizing the order - * refund_remaining: Amount; how much is still available for the wallet to - collect +* refund_remaining: Amount; how much is still available for the wallet to + collect - * has_refund_taken: Boolean; true when part of the refund was already - collected +* has_refund_taken: Boolean; true when part of the refund was already + collected - * order_id: String; the merchant's identifier for the order +* order_id: String; the merchant's identifier for the order - * merchant_name: String; the configured display name of the merchant - instance +* merchant_name: String; the configured display name of the merchant + instance - * order_status_url: Authenticated URL of the merchant backend where the - refund status can be long-polled +* order_status_url: Authenticated URL of the merchant backend where the + refund status can be long-polled @@ -1724,30 +1724,30 @@ no payment is required and no refund is present. This template is instantiated using the following information: - * order_summary: String; a text summarizing the order +* order_summary: String; a text summarizing the order - * contract_terms: Object; the full contract terms (should probably - not be shown in full!) +* contract_terms: Object; the full contract terms (should probably + not be shown in full!) - * refund_amount: Amount; how much did the merchant refund +* refund_amount: Amount; how much did the merchant refund - * refund_taken: Amount; how much did the customer already take back in refunds +* refund_taken: Amount; how much did the customer already take back in refunds - * order_amount: Amount; the amount paid for the selected payment option +* order_amount: Amount; the amount paid for the selected payment option - * order_id: String; the merchant's identifier for the order +* order_id: String; the merchant's identifier for the order - * merchant_name: String; the configured display name of the merchant - instance +* merchant_name: String; the configured display name of the merchant + instance - * has_refund: Boolean; true when the merchant granted a refund for this - order +* has_refund: Boolean; true when the merchant granted a refund for this + order - * fulfillment_message: Optional string; localized message to show after - successful payment +* fulfillment_message: Optional string; localized message to show after + successful payment - * fulfillment_url: Optional URL; destination where the customer can - continue to the purchased product or service +* fulfillment_url: Optional URL; destination where the customer can + continue to the purchased product or service Static files ------------