commit 0d4ce0e1b6e62655552be8de29d90b9e3a5677f0 parent 716bfcc1c083c4a987e833dc845d078103cad4bf Author: bohdan-potuzhnyi <bohdan.potuzhnyi@gmail.com> Date: Wed, 29 Oct 2025 11:41:31 +0100 Merge branch 'master' of ssh://git.taler.net/taler-docs Diffstat:
34 files changed, 976 insertions(+), 238 deletions(-)
diff --git a/checklists/checklist-release.rst b/checklists/checklist-release.rst @@ -5,6 +5,42 @@ GNU Taler Release Checklist <input type="checkbox"> + +Released components (repositories, dependency toposorted): + +- |releasecheck| taler-typescript-core.git +- |releasecheck| taler-twister.git +- |releasecheck| libeufin.git +- |releasecheck| exchange.git +- |releasecheck| donau.git +- |releasecheck| merchant.git +- |releasecheck| taler-mdb.git +- |releasecheck| sync.git +- taler-ios.git (no source release) +- taler-android.git (no source release) +- taler-merchant-demos.git (no source release) + + +Overall release process: + +- |releasecheck| Tag candidate tag of components that passed local checks (``x.y.z-dev.n``) +- (future) Run local CI for each package +- (future) Run build and integration test harness in sandcastle-ng +- |releasecheck| Bump version of components (via ``contrib/bump``) +- |releasecheck| Tag release of components that passed local checks (``x.y.z``) +- |releasecheck| Deploy on ``test.taler.net`` +- |releasecheck| Test ``test.taler.net`` +- |releasecheck| Deploy on ``demo.taler.net`` +- |releasecheck| Test ``demo.taler.net`` +- |releasecheck| Build Debian staging packages (via ``packaging-ng``) +- |releasecheck| Deploy in staging environments (``rusty`` etc.) +- |releasecheck| Test staging environments (``rusty`` etc.) +- |releasecheck| Promote Debian packages (via ``packaging-ng``) +- |releasecheck| Upload to GNU mirrors +- |releasecheck| Announce release +- |releasecheck| Deploy in production environments + + For exchange: - |releasecheck| no compiler warnings at "-Wall" with gcc diff --git a/core/api-corebank.rst b/core/api-corebank.rst @@ -34,13 +34,14 @@ it provides features for local/regional currencies. Version History --------------- -The current protocol version is ``v10``. +The current protocol version is ``v11``. Android cashier app is currently targeting ``v9``. **Version history:** -* ``v10`` (in development): Update two factor authentication API to match Merchant Backend API +* ``v11``: Add observability API +* ``v10``: Update two factor authentication API to match Merchant Backend API Config ------ @@ -48,7 +49,7 @@ Config .. http:get:: /config Return the protocol version and configuration information about the bank. - This specification corresponds to ``current`` protocol being version **v10**. + This specification corresponds to ``current`` protocol being version **v11**. **Response:** @@ -152,7 +153,7 @@ The user ``admin`` is a special, hard-coded username. Some requests require the interface TokenRequest { // Scope for the token. - scope: "readonly" | "readwrite" | "revenue" | "wiregateway"; + scope: "readonly" | "readwrite" | "revenue" | "wiregateway" | "observability"; // Custom token validity duration duration?: RelativeTime; @@ -1898,3 +1899,10 @@ Endpoints for Integrated Sub-APIs All endpoints under this prefix are specified by the :doc:`GNU Taler Conversion Info API </core/api-bank-conversion-info>`. + +.. http:any:: /taler-observability/* + + Since **v11** + + All endpoints under this prefix are specified + by the :doc:`GNU Taler Observability API </core/api-observability>`. diff --git a/core/api-exchange.rst b/core/api-exchange.rst @@ -187,7 +187,7 @@ possibly by using HTTPS. // digital cash issued by this exchange. // @since protocol **v21**. shopping_url?: string; - + // Open banking gateway base URL where wallets can // initiate wire transfers to withdraw // digital cash from this exchange. @@ -1719,45 +1719,76 @@ exchange. response, so if the network goes down during the transaction or before the client can commit the coins signature to disk, the coins are not lost. :http:statuscode:`403 Forbidden`: - A signature is invalid. - This response comes with a standard `ErrorDetail` response. + A signature is invalid. This is usually the reserve signature. + This response comes with a standard `ErrorDetail` response with + a code of ``TALER_EC_EXCHANGE_WITHDRAW_RESERVE_SIGNATURE_INVALID``. :http:statuscode:`404 Not found`: - A denomination key or the reserve are not known to the exchange. If the - denomination key is unknown, this suggests a bug in the wallet as the - wallet should have used current denomination keys from ``/keys``. - In this case, the response will be a `DenominationUnknownMessage`. - If the reserve is unknown, the wallet should not report a hard error yet, but - instead simply wait for up to a day, as the wire transaction might simply - not yet have completed and might be known to the exchange in the near future. - In this case, the wallet should repeat the exact same request later again - using exactly the same blinded coins. + One of the following reasons occured: + + 1. The reserve is unknown. The response comes with a standard + `ErrorDetail` response with error-code + ``TALER_EC_EXCHANGE_GENERIC_RESERVE_UNKNOWN``. + If the reserve is unknown, the wallet should not report a + hard error, but instead long-poll for the reserve status to wait + for the wire transfer to complete. + Once the wire transfer has arrived, + the wallet should repeat the exact same request later again, + possibly using exactly the same blinded coins. + 2. A denomination keyis not known to the exchange. + The response comes with a standard + `ErrorDetail` response with error-code + ``TALER_EC_EXCHANGE_GENERIC_DENOMINATION_KEY_UNKNOWN``. + This suggests the wallet has outdated ``/keys`` and + should fetch the latest ``/keys``. :http:statuscode:`409 Conflict`: One of the following reasons occured: - 1. The balance of the reserve is not sufficient to withdraw the coins of the - indicated denominations. The response is `WithdrawError` object. - - 2. The reserve has a birthday set and requires the request to provide a ``max_age`` - value. - The response comes with a standard `ErrorDetail` response with error-code - ``TALER_EC_EXCHANGE_RESERVES_AGE_RESTRICTION_REQUIRED`` - and an additional field ``maximum_allowed_age`` for the maximum age (in years) - that the client can commit to in a call to ``/withdraw``, this time - with ``max_age`` set accordingly and ``coin_evs`` being an array - of ``n*kappa`` elements of type `CoinEnvelope`. - - 3. the provided value for ``max_age`` is higher than the allowed value - according to the reserve's birthday. The response comes with a standard - `ErrorDetail` response with error-code - ``TALER_EC_EXCHANGE_AGE_WITHDRAW_MAXIMUM_AGE_TOO_LARGE`` - and an additional field ``maximum_allowed_age`` for the maximum age (in years) - that the client can commit to in a call to ``/withdraw`` + 1. The balance of the reserve is not sufficient to withdraw the + coins of the indicated denominations. + The response is `WithdrawError` object with an error code of + ``TALER_EC_EXCHANGE_WITHDRAW_INSUFFICIENT_FUNDS``. An operation + withdrawing less money should succeed. + 2. The reserve has a birthday set and requires the request to + provide a ``max_age`` value. + The response comes with a standard `ErrorDetail` response with + an error-code of + ``TALER_EC_EXCHANGE_RESERVES_AGE_RESTRICTION_REQUIRED`` + and an additional field ``maximum_allowed_age`` for the + maximum age (in years) + that the client can commit to in a call to ``/withdraw``, this time + with ``max_age`` set accordingly and ``coin_evs`` being an array + of ``n*kappa`` elements of type `CoinEnvelope`. + 3. The provided value for ``max_age`` is higher than the allowed value + according to the reserve's birthday. The response comes with a + standard `ErrorDetail` response with error-code + ``TALER_EC_EXCHANGE_AGE_WITHDRAW_MAXIMUM_AGE_TOO_LARGE`` + and an additional field ``maximum_allowed_age`` for the maximum + age (in years) that the client can commit to in a call + to ``/withdraw``. + 4. The request uses a nonce value that was previously seen by + the exchange for a different request. As nonces must be unique, + the request is rejected. This can only happen with some cipher + types that use nonces. :http:statuscode:`410 Gone`: - A 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. + A requested denomination key is no longer valid. There are two cases: + + 1. The denomination key is past its expiration. + The response is a `DenominationGoneMessage` with a code of + ``TALER_EC_EXCHANGE_GENERIC_DENOMINATION_EXPIRED``. + 2. The denominatoin key was revoked. The response is a + plain `ErrorDetail` with a code of + ``TALER_EC_EXCHANGE_GENERIC_DENOMINATION_REVOKED``. + :http:statuscode:`412 Precondition Failed`: + A requested denomination key is not yet valid. + It is before the validity start time. + The response is a `DenominationGoneMessage` with + ``TALER_EC_EXCHANGE_GENERIC_DENOMINATION_VALIDITY_IN_FUTURE``. + A common case might be a difference in the current time between + wallet and exchange. The wallet could probably just wait a bit and + retry. Checking the server's ``Date:`` header should allow the + wallet to figure out how long to wait. Alternatively, the wallet + could try with an the previous denomination key generation. + Note: this is a bit of an abuse of the HTTP status code. :http:statuscode:`451 Unavailable for Legal Reasons`: This reserve has received funds from a purse or the amount withdrawn exceeds another legal threshold and thus the reserve must @@ -1778,6 +1809,21 @@ exchange. on the case. :http:statuscode:`501 Not implemented`: The client has provided a cipher that is not supported. + :http:statuscode:`502 Bad gateway`: + This indicates the exchange could not communicate with an + external process. This usually means the exchange could + not talk to one of its secmod helpers. + Here, a standard error message with a code of + ``TALER_EC_EXCHANGE_SIGNKEY_HELPER_UNAVAILABLE`` + is returned. + Wallets should retry the requests (with some delays) at + a later time. + :http:statuscode:`503 Service Unavailable`: + This primarily happens when the exchange currently has no + denomination signing keys at all, for example because the + offline signature did not yet happen. In this case, a standard + error message with a code of + ``TALER_EC_EXCHANGE_GENERIC_KEYS_MISSING`` is returned. **Details:** diff --git a/core/api-merchant.rst b/core/api-merchant.rst @@ -125,7 +125,7 @@ of that instance. Currently, the ``/private/auth/`` API supports two main authentication methods in the ``InstanceAuthConfigurationMessage``: -* ``external``: (*@deprecated since v20*) With this method, no checks are done by the merchant backend. +* ``external``: (@deprecated since **v20**) With this method, no checks are done by the merchant backend. Instead, a reverse proxy / API gateway must do all authentication/authorization checks. * ``token`` (**@since v19**): With this method, the client must provide an authorization header that contains a bearer token when accessing a protected endpoint in the form @@ -135,14 +135,14 @@ Currently, the ``/private/auth/`` API supports two main authentication methods i A login token is commonly only valid for a limited period of time and scoped to specific permissions. If the ``$INSTANCE_PASSWORD`` is lost, the administrator can set a password using the ``taler-merchant-passwd`` command-line tool. -* ``token`` (*@deprecated since v19*): With this method, the client must provide an authentication token in +* ``token`` (@deprecated since **v19**): With this method, the client must provide an authentication token in the format ``secret-token: $INSTANCE_PASSWORD``. The behaviour is then equivalent to the ``token`` method above. Any API may be accessed using the bearer authentication ``secret-token: $INSTANCE_PASSWORD``. Notice that this behaviour is deprecated and will be phased out in favor of login tokens. For testing, the service may be started with the configuration option ``DISABLED_AUTHENTICATION = YES`` -in section ``[merchant]`` (@since v20). +in section ``[merchant]`` (@since **v20**). Scopes ^^^^^^ @@ -172,7 +172,7 @@ such as the implemented version of the protocol and the currency used. .. http:get:: /config Return the protocol version and currency supported by this merchant backend. - This specification corresponds to ``current`` protocol being version **v21**. + This specification corresponds to ``current`` protocol being version **v23**. **Response:** @@ -217,7 +217,7 @@ such as the implemented version of the protocol and the currency used. currencies: { currency : CurrencySpecification}; // Array of exchanges trusted by the merchant. - // Since protocol **v6**. + // @since **v6**. exchanges: ExchangeConfigInfo[]; // Set when the merchant supports @@ -229,22 +229,83 @@ such as the implemented version of the protocol and the currency used. // extension and can thus issue donation receipts. // Should primarily be used to control the SPA's CRUD // functionality for Donau. - // Since protocol **v21** + // @since **v21** have_donau: boolean; // Tan channels that are required // to be confirmed for an instance to // be useable. - // Since protocol **v21** + // @since **v21** mandatory_tan_channels?: TanChannel[]; + // Space-separated list of enabled payment target types. + // Useful if the SPA should not show allow adding other + // types of bank accounts. "*" is used to represent no + // restriction. + // @since **v22** + payment_target_types: string; + + // Regular expression representing further restrictions + // on allowed payment targets. Any "payto://"-URI supplied + // for a bank account must match the given regular expression. + // For example, "payto://iban/CH.*" would restrict the system + // to only Swiss bank accounts. + // Optional, no restrictions are imposed if the field is + // absent. + // @since **v22** + // CAUTION: Likely to be removed/deprecated, + // as we'll want an array of restrictions with the + // same format as the exchange uses, as this allows + // proper i18n and spec/code reuse. + payment_target_regex? string; + + // Default payment delay for new instances. + // This is the default to use for new instances, see the instance value for + // the instance-specific default. + // @since **v22** + default_pay_delay: RelativeTime; + + // If the frontend does NOT specify a refund deadline, how long should + // refunds be allowed by default? + // This is the default to use for new instances, see the instance value for + // the instance-specific default. + // @since **v22** + default_refund_delay: RelativeTime; + + // Default wire transfer delay for new instances. + // This is the default to use for new instances, see the instance value for + // the instance-specific default. + // @since **v22** + default_wire_transfer_delay: RelativeTime; + + // Default interval to which wire deadlines computed by + // adding the wire_transfer_delay on top of the refund + // deadline should be rounded up to. + // @since **v23** + default_wire_transfer_rounding_interval: RoundingInterval; } + .. ts:def:: TanChannel + enum TanChannel { SMS = "sms", EMAIL = "email" } + .. ts:def:: RoundingInterval + + enum RoundingInterval { + NONE = "none", + SECOND = "second", + MINUTE = "minute", + HOUR = "hour", + DAY = "day", + WEEK = "week", + MONTH = "month", + QUARTER = "quarter", + YEAR = "year" + } + .. ts:def:: ExchangeConfigInfo interface ExchangeConfigInfo { @@ -1314,14 +1375,24 @@ Setting up instances The request must be a `InstanceConfigurationMessage`. + :query token_validity_ms=DURATION: *Optional*. + Pass a non-zero DURATION in milliseconds to get a + refreshable login token for the SPA with the + given validity duration in the response. @since **v21**. + **Response:** + :http:statuscode:`200 Ok`: + The backend has successfully created the instance. Body will + be an `LoginTokenSuccessResponse` with a refreshable + login token for the SPA as requested. @since **v21**. :http:statuscode:`202 Accepted`: 2FA is required for this operation, usually to validate the email and/or phone numbers provided for the instance. This returns the `ChallengeResponse`. @since **v21** - :http:statuscode:`204 No content`: - The backend has successfully created the instance. + :http:statuscode:`204 No Content`: + The backend has successfully created the instance. No login + token was requested, so nothing is returned. :http:statuscode:`409 Conflict`: This instance already exists, but with other configuration options. Use "PATCH" to update an instance configuration. Alternatively, @@ -1330,6 +1401,7 @@ Setting up instances would be if a deleted but not purged instance is known under this ID to the backend. + .. http:post:: /instances/$INSTANCE/forgot-password Same as ``/management/instances/$INSTANCE/private/auth`` it will update the password of the instance but @@ -1425,16 +1497,32 @@ Setting up instances // Can always be overridden by the frontend on a per-order basis. use_stefan: boolean; - // If the frontend does NOT specify an execution date, how long should - // we tell the exchange to wait to aggregate transactions before - // executing the wire transfer? This delay is added to the current - // time when we generate the advisory execution time for the exchange. - default_wire_transfer_delay: RelativeTime; - // If the frontend does NOT specify a payment deadline, how long should // offers we make be valid by default? - default_pay_delay: RelativeTime; + // Optional @since **v22** (before the setting was mandatory). + // If not provided, the global merchant default will be used. + default_pay_delay?: RelativeTime; + + // If the frontend does NOT specify a refund deadline, how long should + // refunds be allowed by default? Added on top of the + // payment deadline. + // @since **v22** + default_refund_delay?: RelativeTime; + // If the frontend does NOT specify an execution date, how long should + // we tell the exchange to wait to aggregate transactions before + // executing the wire transfer? This delay is added on top of + // the refund deadline and afterwards subject to rounding + // via the ``default_wire_transfer_rounding_interval``. + // Optional @since **v22** (before the setting was mandatory). + // If not provided, the global merchant default will be used. + default_wire_transfer_delay?: RelativeTime; + + // How far should the wire deadline (if computed with the help of + // the ``default_wire_transfer_delay``) be rounded up to compute + // the ultimate wire deadline? + // @since **v22**, defaults to no rounding if not given. + default_wire_transfer_rounding_interval?: RoundingInterval; } .. http:post:: /management/instances/$INSTANCE/auth @@ -1466,7 +1554,7 @@ Setting up instances .. ts:def:: InstanceAuthConfigToken - // @since v19 + // @since **v19** interface InstanceAuthConfigToken { // The API is accessible through API tokens. // Tokens are retrieved from the /private/token @@ -1483,7 +1571,7 @@ Setting up instances .. ts:def:: InstanceAuthConfigTokenOLD - // @deprecated since v19 + // @deprecated since **v19** interface InstanceAuthConfigTokenOLD { // The API is accessible through API tokens. // Tokens are retrieved from the /private/token @@ -1497,7 +1585,7 @@ Setting up instances .. ts:def:: InstanceAuthConfigExternal - // @deprecated since v20 + // @deprecated since **v20** interface InstanceAuthConfigExternal { // The mechant backend does not do // any authentication checks. Instead an API @@ -1722,16 +1810,31 @@ Setting up instances // Can always be overridden by the frontend on a per-order basis. use_stefan: boolean; - // If the frontend does NOT specify an execution date, how long should - // we tell the exchange to wait to aggregate transactions before - // executing the wire transfer? This delay is added to the current - // time when we generate the advisory execution time for the exchange. - default_wire_transfer_delay: RelativeTime; - // If the frontend does NOT specify a payment deadline, how long should // offers we make be valid by default? - default_pay_delay: RelativeTime; + // Optional @since **v22** (before the setting was mandatory). + // If not provided, the previous setting will now simply be preserved. + default_pay_delay?: RelativeTime; + + // If the frontend does NOT specify a refund deadline, how long should + // refunds be allowed by default? Added on top of the payment deadline. + // @since **v22** + default_refund_delay?: RelativeTime; + // If the frontend does NOT specify an execution date, how long should + // we tell the exchange to wait to aggregate transactions before + // executing the wire transfer? This delay is added on top of + // the refund deadline and afterwards subject to rounding + // via the ``default_wire_transfer_rounding_interval``. + // Optional @since **v22** (before the setting was mandatory). + // If not provided, the previous setting will now simply be preserved. + default_wire_transfer_delay?: RelativeTime; + + // How far should the wire deadline (if computed with the help of + // the ``default_wire_transfer_delay``) be rounded up to compute + // the ultimate wire deadline? + // @since **v22**, defaults to no rounding if not given. + default_wire_transfer_rounding_interval?: RoundingInterval; } @@ -1857,15 +1960,28 @@ Inspecting instances // Can always be overridden by the frontend on a per-order basis. use_stefan: boolean; + // If the frontend does NOT specify a payment deadline, how long should + // offers we make be valid by default? Added to the order creation + // time. + default_pay_delay: RelativeTime; + + // If the frontend does NOT specify a refund deadline, how long should + // refunds be allowed by default? Added to the payment deadline. + // @since **v22** + default_refund_delay: RelativeTime; + // If the frontend does NOT specify an execution date, how long should // we tell the exchange to wait to aggregate transactions before - // executing the wire transfer? This delay is added to the current - // time when we generate the advisory execution time for the exchange. + // executing the wire transfer? This delay is added to the + // refund deadline and subject to rounding to the + // ``default_wire_transfer_rounding_interval``. default_wire_transfer_delay: RelativeTime; - // If the frontend does NOT specify a payment deadline, how long should - // offers we make be valid by default? - default_pay_delay: RelativeTime; + // Default interval to which wire deadlines computed by + // adding the wire_transfer_delay on top of the refund + // deadline should be rounded up to. + // @since **v23** + default_wire_transfer_rounding_interval: RoundingInterval; // Authentication configuration. // Does not contain the token when token auth is configured. diff --git a/core/api-observability.rst b/core/api-observability.rst @@ -0,0 +1,73 @@ +.. + This file is part of GNU TALER. + + Copyright (C) 2025 Taler Systems SA + + TALER is free software; you can redistribute it and/or modify it under the + terms of the GNU Affero General Public License as published by the Free Software + Foundation; either version 2.1, or (at your option) any later version. + + TALER is distributed in the hope that it will be useful, but WITHOUT ANY + WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR + A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details. + + You should have received a copy of the GNU Affero General Public License along with + TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/> + +.. target audience: developer, core developer + +.. _observability-api: + +======================= +Taler Observability API +======================= + +.. contents:: Table of Contents + :local: + +Introduction +------------ + +This section describes the API offered by many Taler components. The API is +used to track the internal state of a Taler component. + +Config +------ + +.. http:get:: /config + + Return the protocol version and configuration information about the bank. + This specification corresponds to ``current`` protocol being version **v0**. + + **Response:** + + :http:statuscode:`200 OK`: + Response is a `Config`. + + **Details:** + + .. ts:def:: Config + + interface Config { + // Name of the API. + name: "taler-observability"; + + // libtool-style representation of the Bank protocol version, see + // https://www.gnu.org/software/libtool/manual/html_node/Versioning.html#Versioning + // The format is "current:revision:age". + version: string; + } + +Metrics +------- + +.. http:get:: /metrics + + Exposes application metrics in the Prometheus exposition format. These metrics can be scraped by Prometheus or other monitoring systems for observability, alerting, and analysis. + + **Response:** + + :http:statuscode:`200 Ok`: + Response woth metrics in the Prometheus text format. + :http:statuscode:`401 Unauthorized`: + Authentication failed, likely the credentials are wrong. +\ No newline at end of file diff --git a/core/api-taldir.rst b/core/api-taldir.rst @@ -23,12 +23,12 @@ Directory RESTful API ===================== This is the API for the Taler Directory (TalDir) service which allows Taler wallets to -securely associate an inbox service (URL and public key) with the address of a -messaging service used by the wallet's user. Wallets can also lookup the +securely associate an inbox service (URL and public key) with the alias of a +wallet's user. Wallets can also lookup the inbox of other users. This will enable wallets to make wallet-to-wallet payments to distant wallets where the target user is only identified by their -address in a messaging service. Examples for messaging services include E-mail -and SMS. +alias. Examples for aliases include E-mail and phone numbers but also +social handles. The service in principle allows registration of any valid URI as inbox service. For Taler, the URI is a link to a :ref:`mailbox <api-mailbox>`. @@ -68,18 +68,18 @@ Configuration information // Name of the protocol. name: "taler-directory"; - // Supported registration methods - methods: TaldirMethod[]; + // Supported alias types + alias_types: TaldirAliasType[]; // fee for one month of registration monthly_fee: Amount; } - .. ts:def:: TaldirMethod + .. ts:def:: TaldirAliasType - interface TaldirMethod { - // Name of the method, e.g. "email" or "sms". + interface TaldirAliasType { + // Name of the alias type, e.g. "email" or "sms". name: string; // per challenge fee @@ -87,16 +87,16 @@ Configuration information } --------------------- -Address registration --------------------- +------------------ +Alias registration +------------------ -.. http:post:: /register/$METHOD +.. http:post:: /register/$ALIASTYPE - Endpoint to register, extend or modify the registration for an address in + Endpoint to register, extend or modify the registration for an alias in the directory. - Here, $METHOD is the type of address to register, e.g. "email", or "phone". - Supported methods are listed in the VersionResponse. + Here, $ALIASTYPE is the type of alias to register, e.g. "email", or "phone". + Supported alias types are listed in the VersionResponse. Note that duration should be given as a multiple of a month in microseconds. If the duration is not a multiple of a month it will be rounded to the nearest multiple. Halfway values will be rounded away from zero. @@ -114,10 +114,10 @@ Address registration .. ts:def:: IdentityMessage interface IdentityMessage { - // Address, in $METHOD-specific format - address: string; + // Alias, in $ALIASTYPE-specific format + alias: string; - // Target URI to associate with this address. + // Target URI to associate with this alias. target_uri: string; // For how long should the registration last/be extended. @@ -128,21 +128,21 @@ Address registration **Response** :http:statuscode:`200 Ok` - Registration already exists for this address for the specified duration. + Registration already exists for this alias for the specified duration. Returns for how long this registration is paid for. The response format is given by `AlreadyPaidResponse`_. :http:statuscode:`202 Accepted` Registration was initiated, the client should check for receiving - a challenge at the address where registration was attempted. + a challenge at the alias where registration was attempted. :http:statuscode:`402 Payment Required` Client needs to make a Taler payment before proceeding. See standard Taler payment procedure. :http:statuscode:`404 Not found` - The TalDir service does not support the specified method. + The TalDir service does not support the specified alias type. This response comes with a standard `ErrorDetail` response. :http:statuscode:`429 Too Many Requests`: The client exceeded the number of allowed attempts for initiating - a challenge for this address in the given timeframe. + a challenge for this alias in the given timeframe. The response format is given by `RateLimitedResponse`_. .. _RateLimitedResponse: @@ -172,7 +172,7 @@ Address registration } -.. http:get:: /register/$H_ADDRESS/$PINTAN?address=$ADDRESS +.. http:get:: /register/$H_ALIAS/$PINTAN?alias=$ALIAS Endpoint that generates an HTML Web site with a link for completing the registration. Useful to open the registration challenge in a browser (say if @@ -193,20 +193,20 @@ Address registration a concurrent registration of a different public key, and the user might accidentally authorize the registration of the public key of a different wallet. - ``$H_ADDRESS`` is the SHA-512 hash of a prefix-free encoding of the - address to be registered in Crockford Base32 encoding, specifically: - ``SHA-512(len($METHOD)+len($ADDRESS)||$METHOD||$ADDRESS)`` - The service verifies that ``$ADDRESS`` is, in fact, the preimage of ``$H_ADDRESS`` - and ``$ADDRESS`` as well as the ``inbox_uri`` are displayed to the user + ``$H_ALIAS`` is the SHA-512 hash of a prefix-free encoding of the + alias to be registered in Crockford Base32 encoding, specifically: + ``SHA-512(len($ALIASTYPE)+len($ALIAS)||$ALIASTYPE||$ALIAS)`` + The service verifies that ``$ALIAS`` is, in fact, the preimage of ``$H_ALIAS`` + and ``$ALIAS`` as well as the ``inbox_uri`` are displayed to the user for verification. -.. http:post:: /$H_ADDRESS +.. http:post:: /$H_ALIAS This request is the last step of a registration, proving to the TalDir that - the user of the wallet is indeed able to receive messages at the specified - address. - ``$H_ADDRESS`` is the SHA-512 hash of a prefix-free encoding of the - address to be registered in Crockford Base32 encoding. + the user of the wallet is indeed able to receive messages for the specified + alias. + ``$H_ALIAS`` is the SHA-512 hash of a prefix-free encoding of the + alias to be registered in Crockford Base32 encoding. **Request** @@ -228,21 +228,21 @@ Address registration :http:statuscode:`403 Forbidden`: The ``solution`` is invalid. Retrying immediately is allowed. :http:statuscode:`404 Not found`: - The address is unknown (original registration attempt may have expired). + The alias is unknown (original registration attempt may have expired). :http:statuscode:`429 Too Many Requests`: The client exceeded the number of allowed attempts for solving - a challenge for this address in the given timeframe. + a challenge for this alias in the given timeframe. --------------- -Address lookup --------------- +------------ +Alias lookup +------------ -.. http:get:: /$H_ADDRESS +.. http:get:: /$H_ALIAS Lookup the target URI associated with - an address in the TalDir. Here, - ``$H_ADDRESS`` is the SHA-512 hash of a prefix-free encoding of the - address to be registered in Crockford base32 encoding. + an alias in the TalDir. Here, + ``$H_ALIAS`` is the SHA-512 hash of a prefix-free encoding of the + alias to be registered in Crockford base32 encoding. **Response** @@ -252,14 +252,14 @@ Address lookup :http:statuscode:`200 Ok`: Registration information returned, of type `MailboxDetailResponse` :http:statuscode:`404 Not found`: - The address is unknown (original registration may have expired). + The alias is unknown (original registration may have expired). .. _MailboxDetailResponse: .. ts:def:: MailboxDetailResponse interface MailboxDetailResponse { - // Target URI to associate with this address. + // Target URI to associate with this alias. target_uri: string; diff --git a/core/index.rst b/core/index.rst @@ -47,6 +47,7 @@ describe the JSON objects used in our REST APIs. api-mailbox index-bank-apis api-donau + api-observability .. toctree:: :hidden: diff --git a/design-documents/068-tokens-roadmap.rst b/design-documents/068-tokens-roadmap.rst @@ -72,6 +72,48 @@ Types of tokens: * normally grouped under asset token ("history" for corporate actions) * in notificiation state: dismiss, auto-dismiss after some time + +Wallet UI Screenshots (Donau Integration) +========================================= + +Donau setup screen +~~~~~~~~~~~~~~~~~~ + +.. image:: ../screenshots/wallet/donau/donau-setup-android.png + :width: 50% + +Balances view +~~~~~~~~~~~~~ + +.. image:: ../screenshots/wallet/donau/balances-android.png + :width: 50% + +Donation statement +~~~~~~~~~~~~~~~~~~ + +.. image:: ../screenshots/wallet/donau/donation-statement-android.png + :width: 50% + +Tax receipt available +~~~~~~~~~~~~~~~~~~~~~ + +.. image:: ../screenshots/wallet/donau/payment-android.png + :width: 50% + +Tax receipt not available +~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. image:: ../screenshots/wallet/donau/payment-notavailable-android.png + :width: 50% + +Select Donau service +~~~~~~~~~~~~~~~~~~~~ + +.. image:: ../screenshots/wallet/donau/select-donau-android.png + :width: 50% + + + Plan for Merchant Backend ========================= @@ -161,6 +203,46 @@ Test Plan * Asset tokenization: TBD / will be deployed on demo via merchant +Donations: donations.demo.taler.net +=================================== + +Donate page +~~~~~~~~~~~~ + +.. image:: ../screenshots/donau/donate-web.png + +Payment method selection +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. image:: ../screenshots/donau/payment-method-web.png + +Taler Pay +~~~~~~~~~ + +.. image:: ../screenshots/donau/taler-pay.png + +Receipt page +~~~~~~~~~~~~ + +.. image:: ../screenshots/donau/receipt-web.png + + +Donau Verify UI +=============== + +Donau verification (input) +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. image:: ../screenshots/donau/donau-verify.png + :width: 50% + +Donau verification (verified) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. image:: ../screenshots/donau/donau-verified.png + :width: 50% + + Definition of Done ================== diff --git a/design-documents/070-alias-directory-mailbox.rst b/design-documents/070-alias-directory-mailbox.rst @@ -4,10 +4,10 @@ DD 70: Alias Lookup and Mailbox Summary ======= -GNU Taler is a payment system that makes privacy-friendly online transactions +GNU Taler is a payment system that makes privacy-contactly online transactions fast and easy. This project will facilitate the support of peer-to-peer payments (P2P) for the -GNU Taler payment system between users by implementing a privacy-friendly +GNU Taler payment system between users by implementing a privacy-contactly directory service and lightweight inbox service (TALer DIRectory). The services will allow users to securely associate their online identities (such as email addresses, phone numbers, X/Twitter/Mastodon handles or other suitable verifiable addresses and accounts) with their wallet @@ -27,7 +27,7 @@ To enable peer-to-peer payments for the GNU Taler payment system between users such a directory service and lightweight inbox service are also required. We believe that the estimated development costs from the ECB tender are unreasonably and unexplicably high. We can demostrate how an efficient, -privacy-friendly and lean service that offers this kind of functionality can be +privacy-contactly and lean service that offers this kind of functionality can be developed within this proposal at a fraction of the cost of the "Alias Lookup Service": @@ -110,7 +110,7 @@ Alias Management Alice opens ``Settings -> Aliases`` to manage her aliases. The UI shows all registered aliases with expiration times. The UI allows Alice to delete registrations (or disable auto-renewal) and renew a registration pre-emptively before it expires. -Alice may use this screen to display a QR code of her mailbox URI, see also :ref:`Friends Management <dd-13-us-friends-mgmt>`. +Alice may use this screen to display a QR code of her mailbox URI, see also :ref:`Contacts Management <dd-13-us-contacts-mgmt>`. This may require separation into two or three stories. @@ -120,14 +120,14 @@ Send Payment Request Prerequisites: Bob has installed Taler Wallet, Bob knows one of Alice's aliases Bob wants to request money from Alice. -He opens his Taler wallet and opens ``Taler Button->Send`` screen from the menu. +He opens his Taler wallet and opens ``Taler Button->Receive`` screen from the menu. A screen that allows to create a payment request is shown to Bob. Once Bob has entered all necessary details, a payment request (:ref:`DD 13 <dd-13>`) is created and the screen with QR code is shown. -This screen now also allows to send the request to a friend by using the friend list. -The *Request from Friend* screen brings up the friends list to select a friend. -Bob may also import a friend here ad-hoc, see :ref:`Friends Management <dd-13-us-friends-mgmt>`. -Bob selects the friend and the request is sent to Alice. +This screen now also allows to send the request to a contact by using the contact list. +The *Request from Contact* screen brings up the contacts list to select a contact. +Bob may also import a contact here ad-hoc, see :ref:`Contacts Management <dd-13-us-contacts-mgmt>`. +Bob selects the contact and the request is sent to Alice. **Technical Note**: This will trigger the wallet to send the payment request to Alice's Mailbox URI through the :ref:`Mailbox API <api-mailbox>`. The message format is still TBD. @@ -148,7 +148,7 @@ The new payment request by Bob is received by the Wallet and it notifies Alice. **Technical Note**: Notice request is *NEW*. This requires requests to have unique IDs. Also, maybe notifications should happen even if the ID is already seen, but the message is new. -Alice interacts with the notification or manually browses to ``Mailbox``. +Alice interacts with the notification or manually browses to ``Settings->Mailbox``. **TODO**: Does this exist / make sense? @@ -161,27 +161,27 @@ She may also decline to pay. **Note**: When are local messages deleted? -.. _dd-13-us-friends-mgmt: +.. _dd-13-us-contacts-mgmt: -Friends Management +Contacts Management ----------------- Prerequisites: Alice has installed Taler Wallet -Alice opens ``Settings->Friends``. -The list of friends is empty in the beggining. -There is a button to *Add a friend* which opens a UI. +Alice opens ``Settings->Contacts``. +The list of contacts is empty in the beggining. +There is a button to *Add a contact* which opens a UI. The UI consists of a search input and an Alias type selector. -Alice selects the Alias type (e.g. GitHub or Email) and inputs a friends Alias. +Alice selects the Alias type (e.g. GitHub or Email) and inputs a contacts Alias. **Technical Note**: This will initiate a lookup request using the :ref:`Taldir API <api-taldir>`. -If no results were found, Alice cannot import this friend. -If found, Alice will be able to import this friend into the friend list. +If no results were found, Alice cannot import this contact. +If found, Alice will be able to import this contact into the contact list. -Alternatively, the friend can also be imported using a QR code, see :ref:`Alias Management <dd-13-us-alias-mgmt>`. +Alternatively, the contact can also be imported using a QR code, see :ref:`Alias Management <dd-13-us-alias-mgmt>`. - **Technical Note**: The wallet periodically performs lookups for friends where their Taldir registrations have expired and refresh accordingly. + **Technical Note**: The wallet periodically performs lookups for contacts where their Taldir registrations have expired and refresh accordingly. Send Money ---------- @@ -189,18 +189,18 @@ Send Money Prerequisites: Alice has installed Taler Wallet, Alice has registered an Alias. Bob wants to directly send money to Alice (e.g. PayPal style). -He opens his Taler wallet and opens ``Taler Button->Receive``. +He opens his Taler wallet and opens ``Taler Button->Send``. A screen that allows to create a payment offer is shown to Bob. Once Bob has entered all necessary details, the payment offer is created and the screen with the QR code is shown. -There, he selects the *Receive from Friend*. -The *Receive from Friend* screen consists of a search input and an Alias type selector. -This screen now also allows to send the request to a friend by using the friend list. -Bob selects *Send to Friend*. -The *Send to Friend* screen brings up the friends list to select a friend. +There, he selects the *Send to Contact*. +The *Send to Contact* screen consists of a search input and an Alias type selector. +This screen now also allows to send the request to a contact by using the contact list. +Bob selects *Send to Contact*. +The *Send to Contact* screen brings up the contacts list to select a contact. - **Note**: At this point, Bob may now also import a friend here ad-hoc, see :ref:`Friends Management <dd-13-us-friends-mgmt>`. + **Note**: At this point, Bob may now also import a contact here ad-hoc, see :ref:`Contacts Management <dd-13-us-contacts-mgmt>`. -Bob selects the friend and the payment offer is sent to Alice. +Bob selects the contact and the payment offer is sent to Alice. **Technical Note**: The offer is sent to Alice's Mailbox URI through the :ref:`Mailbox API <api-mailbox>`. @@ -208,7 +208,19 @@ This request may fail, for example if Alice's Mailbox is full. **Note**: Sending messages via Mailbox API may incur fees. So does creating a purse in the offer. This should probably be done in a single user action. - **Note**: Should mailbox be used to notify Alice of payment? A: Yes +Resend Payment Request +---------------------- + + Prerequisites: Bos has already sent a payment request to Alice + +Bob may want to resend a payment request if it expired or if Alice lost the request. + + **Technical Note**: This does not mean that the request can get lost in transit. It means that it is possible that Alice lost her phone and needed to setup her Wallet again. + +Bob opens ``Settings->Mailbox`` and selects a payment request he wants to send again. +Bob can initiate to resend this payment request with a button. + + **Technical Note**: This likely implies the creation of a new payment request, with the same detail of the already sent request. Sending the same request again is probably not a good idea. This, however, requires a new field to the contract terms (``idempotency_nonce``?) that we keep identical between both requests. That way, the receiving wallet can detect that it is a duplicate and act accordingly --- if already paid, ignore, if hard-rejected/banned ignore, and if merely expired show again. Open Questions diff --git a/design-documents/071-auto-refresh.rst b/design-documents/071-auto-refresh.rst @@ -0,0 +1,138 @@ +DD 71: Auto-refresh +################### + +Summary +======= + +This document describes when the wallet should automatically refresh +non-dirty coins. + + +Motivation +========== + +The wallet must refresh non-dirty coins before they expire, least the +user looses the money. However, this should not be done too early to +avoid refresh fees and/or excessive load on the exchange. On the other +hand, we need to be careful to not hold off for too long and risk +the wallet not going online before the expiration time. + +We note that there obviously is no perfect solution, as at least in +principle the user could always not restart the wallet until the +expiration time. + + +Requirements +============ + +* Do not loose funds under most conditions +* Do not cause clearly avoidable refresh operations +* Try to educate the user if they are about to get into trouble +* Independently of any specific approach, the wallet + MUST spend those coins first that are earliest to + their expiration time within their equivalence class + as that is always the best way to avoid expiration. +* While lifetimes of denominations are often identical, + that may not always be the case. Theoretically, an + exchange could significantly increase or decrease the + deposit period at any time. The solution should + take this into consideration. + + +Proposed Solution +================= + +1. For each denomination, consider if a refresh would + lengthen the expiration date by more than a factor + of four (4x), that is if the deposit expiration time + of the denomination(s) we could currently withdraw + is more than 4x as long as what remains for the + denomination. If so, refresh + all coins of that denomination. + + + ..note:: + + This basically suggests that a refresh + would have a significant positive **impact**. + +2. For each denomination, consider if the remaining + deposit period is less than **6** months, if the + refresh fee would be zero, and if after refreshing + the deposit expiration time would exceed **12** months, + and if we are not on battery power. If so, refresh + all coins of that denomination. + + ..note:: + + This is again a significant impact, and it is basically + gratis for the user. + +3. For each denomination, consider if the remaining + deposit period is less than **3** months, and if + after refreshing the deposit expiration time would + be larger. If so, refresh all coins of that denomination. + If afterwards the expiration time exceeds **12** months, + show the user a warning: + + "This wallet was offline for too long. Make sure to + start it at least every **3 months** to avoid the + risk of loosing funds to expiration." + + ..note:: + + This is basically a last-minute effort (unless we have + an exchange with extremely short expiration periods). + We do not like getting into this situation, so it is + time to educate the user. + +4. Explicitly show a warning in the balances list of + the respective currency if the remaining deposit + period for any coin drops below 90 days. + Distinguish in the warning key causes: + 1) "We are offline and cannot expand the validity period." + 2) "The payment service provider does not offer longer + validity periods." + + ..note:: + + This should prevent us from getting into trouble if + e-cash is lost anyway. + + +Definition of Done +================== + +* Implemented in wallet-core +* Changes to interactions for signalling warnings to GUIs +* dev-experiments exist to trigger special alerts to users +* GUIs have been designed and tested + + +Alternatives +============ + +The wallet currently implements simple rules for auto-refresh: + +1. After 75% of a denomination's "deposit lifespan" has passed, + we do "auto-refresh check" for all coins of the exchange + +2. During this auto-refresh check, all coins that are >50% into + their deposit lifespan are auto-refreshed. + +This is risky as it does not consider absolute lifespans or user +behavior. + + +Drawbacks +========= + +* This approach does not (yet) consider user behavior. We could + theoretically learn from that. + + + +Discussion / Q&A +================ + +(This should be filled in with results from discussions on mailing lists / personal communication.) diff --git a/design-documents/index.rst b/design-documents/index.rst @@ -82,4 +82,5 @@ Design documents that start with "XX" are considered deprecated. 068-tokens-roadmap 069-exchange-base-url-completion 070-alias-directory-mailbox + 070-auto-refresh 999-template diff --git a/frags/list-of-dependencies.rst b/frags/list-of-dependencies.rst @@ -22,7 +22,7 @@ - GNU libmicrohttpd >= 0.9.71 -- GNUnet >= 0.20 (from `source tarball <http://ftpmirror.gnu.org/gnunet/>`__) +- GNUnet >= 0.25.2 (from `source tarball <http://ftpmirror.gnu.org/gnunet/>`__) - Python3 with ``jinja2`` diff --git a/libeufin/bank-manual.rst b/libeufin/bank-manual.rst @@ -129,13 +129,13 @@ libeufin-bank supports two-factor authentication. libeufin-bank uses helper scri SMS TAN channel +++++++++++++++ -The default ``libeufin-tan-sms.sh`` script is based on the `Telesign <https://www.telesign.com>`_ SMS provider. It requires an additional ``AUTH_TOKEN`` environment variable for `Telesign Basic authentication <https://developer.telesign.com/enterprise/docs/authentication#basic-authentication>`_. +The default ``libeufin-tan-sms.sh`` script is based on the `Telesign <https://www.telesign.com>`_ SMS provider. It requires an additional ``TELESIGN_AUTH_TOKEN`` environment variable for `Telesign Basic authentication <https://developer.telesign.com/enterprise/docs/authentication#basic-authentication>`_. To test your setup run: .. code-block:: console - $ AUTH_TOKEN=$TELESIGN_TOKEN + $ TELESIGN_AUTH_TOKEN=$TELESIGN_TOKEN $ echo "Test 1234" | libeufin-tan-sms.sh $PHONE If you received an SMS containing "Test 1234" you can enable this channel in the config: @@ -144,7 +144,7 @@ If you received an SMS containing "Test 1234" you can enable this channel in the [libeufin-bank] TAN_SMS = libeufin-tan-sms.sh - TAN_SMS_ENV = "AUTH_TOKEN=$TELESIGN_TOKEN" + TAN_SMS_ENV = "TELESIGN_AUTH_TOKEN=$TELESIGN_TOKEN" Mail TAN channel ++++++++++++++++ diff --git a/libeufin/nexus-manual.rst b/libeufin/nexus-manual.rst @@ -360,7 +360,7 @@ If your bank does not support the EBICS protocol, but has an interface for impor Sending payments ---------------- -To obtain PAIN files for pending initiated outgoing transactions in a `payments.zip` file, you can run : +To obtain PAIN files for pending initiated outgoing transactions in a ``payments.zip`` file, you can run : .. code-block:: console diff --git a/manpages/libeufin-bank.conf.5.rst b/manpages/libeufin-bank.conf.5.rst @@ -145,11 +145,7 @@ DATABASE OPTIONS Setting the database belongs to the “[libeufin-bankdb-postgres]” section and the following value. -CONFIG - PostgreSQL connection string. - -SQL_DIR - Where are the SQL files to setup our tables? +.. include:: frags/common-db-options.rs SEE ALSO ======== diff --git a/manpages/libeufin-nexus.conf.5.rst b/manpages/libeufin-nexus.conf.5.rst @@ -147,17 +147,7 @@ The following configuration value(s) belong to the “[nexus-httpd-wire-gateway- ENABLED Whether to serve the Wire Gateway API. -AUTH_METHOD - Authentication scheme, this can either be ``basic``, ``bearer`` or ``none``. - -USERNAME - User name for ``basic`` authentication scheme. - -PASSWORD - Password for ``basic`` authentication scheme. - -TOKEN - Token for ``bearer`` authentication scheme. +.. include:: frags/common-api-options.rst HTTP REVENUE API OPTIONS ------------------------ @@ -167,28 +157,25 @@ The following configuration value(s) belong to the “[nexus-httpd-revenue-api] ENABLED Whether to serve the Revenue API. -AUTH_METHOD - Authentication scheme, this can either be ``basic``, ``bearer`` or ``none``. +.. include:: frags/common-api-options.rst -USERNAME - User name for ``basic`` authentication scheme. +HTTP OBSERVABILITY API OPTIONS +------------------------------ -PASSWORD - Password for ``basic`` authentication scheme. +The following configuration value(s) belong to the “[nexus-httpd-observability-api]” section. + +ENABLED + Whether to serve the Observability API. + +.. include:: frags/common-api-options.rst -TOKEN - Token for ``bearer`` authentication scheme. DATABASE OPTIONS ---------------- Setting the database belongs to the “[libeufin-nexusdb-postgres]” section and the following value. -CONFIG - PostgreSQL connection string. - -SQL_DIR - Where are the SQL files to setup our tables? +.. include:: frags/common-db-options.rs SEE ALSO ======== diff --git a/manpages/taler-magnet-bank.conf.5.rst b/manpages/taler-magnet-bank.conf.5.rst @@ -70,7 +70,7 @@ The following configuration value(s) belong to the “[magnet-bank-httpd-wire-ga ENABLED Whether to serve the Wire Gateway API. -.. include:: frags/common-api-optio +.. include:: frags/common-api-options.rst HTTP REVENUE API OPTIONS ------------------------ @@ -80,7 +80,7 @@ The following configuration value(s) belong to the “[magnet-bank-httpd-revenue ENABLED Whether to serve the Revenue API. -.. include:: frags/common-api-optio +.. include:: frags/common-api-options.rst DATABASE OPTIONS ---------------- diff --git a/manpages/taler-merchant-passwd.1.rst b/manpages/taler-merchant-passwd.1.rst @@ -6,7 +6,7 @@ taler-merchant-passwd(1) Name ==== - **taler-merchant-passwd** - reset password of existing instance + **taler-merchant-passwd** - reset password of existing instance and/or create admin instance Synopsis @@ -29,6 +29,11 @@ of existing Taler instances. The password must either be specified as the last command-line argument or in the TALER_MERCHANT_PASSWORD environment variable. +Usually, the instance for which the password is being set must +already exist. However, as a special exception, if the instance +specified is the "admin" instance, then it is created (with +sensible defaults) if it does not yet exist. + Its options are as follows: **-c** *FILENAME* \| **--config=**\ \ *FILENAME* @@ -40,7 +45,7 @@ Its options are as follows: **-i** *NAME* \| **--instance**\ \ *NAME* Specifies the name of the instance for which the password should be - updated. If not given, the "default" instance is modified. + updated. If not given, the "admin" instance is modified. **-L** *LOGLEVEL* \| **--loglevel=**\ \ *LOGLEVEL* Specifies the log level to use. Accepted values are: ``DEBUG``, ``INFO``, diff --git a/manpages/taler-merchant.conf.5.rst b/manpages/taler-merchant.conf.5.rst @@ -176,6 +176,43 @@ LEGAL_PRESERVATION How long do we keep data in the database for tax audits after the transaction has completed? Default is 10 years. +DEFAULT_PAY_DELAY + What is the default payment delay for new instances. This is how long the + customer has to pay the order before the offer expires. + This backend default can be changed per-instance and then still overridden per-order. + Defaults to one day if not specified in the configuration. + +DEFAULT_REFUND_DELAY + What is the default refund delay for new instances. This is how long the + merchant can grant refunds to the customer. Is added on top of the + payment deadline (for an actual order). + This backend default can be changed per-instance and then still overridden per-order. + If the order overrides the wire transfer deadline and does not + specify a refund deadline and if the DEFAULT_REFUND_DELAY would + imply a longer refund deadline, then the wire transfer deadline + is used for the refund deadline. + Defaults to 15 days if not specified in the configuration. + +DEFAULT_WIRE_TRANSFER_DELAY + What is the default wire transfer delay for new instances. This is how long the + exchange has to settle the payment with a wire transfer, enabling refunds and aggregation + of multiple transfers to happen until this time. + The value given is added on top of the refund deadline and is then + subject to rounding as per DEFAULT_WIRE_TRANSFER_ROUNDING_INTERVAL. + This backend default can be changed per-instance and then still overridden per-order. + Defaults to one month if not specified in the configuration. + +DEFAULT_WIRE_TRANSFER_ROUNDING_INTERVAL + Specifies to what time interval a wire transfer deadline computed + via the DEFAULT_WIRE_TRANSFER_DELAY should be rounded up. Supported + values are NONE, SECOND, MINUTE, HOUR, DAY, WEEK, MONTH, QUARTER and + YEAR, each implying that wire transfer deadline computed + should be rounded up to the respective end of the next interval + using the local timezone of the merchant backend. + This backend default can be changed per-instance. + Rounding does not apply if the wire deadline is overridden per-order. + Defaults to NONE (no rounding up) if not specified in the configuration. + FORCE_AUDIT Force the merchant to report every transaction to the auditor (if the exchange has an auditor)? Default is ``NO``. @@ -196,6 +233,14 @@ HELPER_EMAIL STRICT_PROTOCOL_V19 Set to YES to strictly enforce protocol version 19 or later. Transient option for development. +PAYMENT_TARGET_TYPES + Space-separated list of allowed payment target types (like bitcoin, iban or x-taler-bank). + Defaults to "*" which means no restrictions if not specified. + +PAYMENT_TARGET_REGEX + POSIX regular expression imposing additional restrictions on the "payto://"-URIs allowed + for bank accounts of instances of this system. For example, "payto://iban/CH.*" would + restrict the system to only Swiss IBAN accounts. Optional, no restrictions if not set. MERCHANT KYCCHECK OPTIONS ------------------------- diff --git a/screenshots/donau/donate-web.png b/screenshots/donau/donate-web.png Binary files differ. diff --git a/screenshots/donau/donau-verified.png b/screenshots/donau/donau-verified.png Binary files differ. diff --git a/screenshots/donau/donau-verify.png b/screenshots/donau/donau-verify.png Binary files differ. diff --git a/screenshots/donau/payment-method-web.png b/screenshots/donau/payment-method-web.png Binary files differ. diff --git a/screenshots/donau/receipt-web.png b/screenshots/donau/receipt-web.png Binary files differ. diff --git a/screenshots/donau/taler-pay.png b/screenshots/donau/taler-pay.png Binary files differ. diff --git a/screenshots/wallet/donau/balances-android.png b/screenshots/wallet/donau/balances-android.png Binary files differ. diff --git a/screenshots/wallet/donau/donation-statement-android.png b/screenshots/wallet/donau/donation-statement-android.png Binary files differ. diff --git a/screenshots/wallet/donau/donau-setup-android.png b/screenshots/wallet/donau/donau-setup-android.png Binary files differ. diff --git a/screenshots/wallet/donau/payment-android.png b/screenshots/wallet/donau/payment-android.png Binary files differ. diff --git a/screenshots/wallet/donau/payment-notavailable-android.png b/screenshots/wallet/donau/payment-notavailable-android.png Binary files differ. diff --git a/screenshots/wallet/donau/select-donau-android.png b/screenshots/wallet/donau/select-donau-android.png Binary files differ. diff --git a/taler-developer-manual.rst b/taler-developer-manual.rst @@ -888,100 +888,185 @@ There is also the possibility to trigger builds manually, but this is only reserved to "admin" users. -Internationalization +Internationalisation ==================== -Internationalization (a.k.a "Translation") is handled with Weblate (https://weblate.org) via our instance at https://weblate.taler.net/ . +Internationalisation (a.k.a "translation") is handled with Weblate (https://weblate.org) via our instance at https://weblate.taler.net/ organised as so-called *strings* in a bunch of Git repositories. -At this time, this system is still very new for Taler.net and this documentation may be incorrect and is certainly incomplete. - -Who can Register +Who can register ---------------- -At this time, anyone can register an account at https://weblate.taler.net/ to create translations. Registered users default to the **Users** and **Viewers** privilege level. +At this time, anyone can register an account at https://weblate.taler.net/ to create translations. Registered users default to the **Users** and **Viewers** privilege levels. -About Privilege Levels +About privilege levels ---------------------- This is the breakdown of privilege levels in Weblate: -* **Users**/**Viewers** = Can log in, view Translations (*applies to new users*) +* **Viewers** = Have access to translations and can view them but are not entitled to translate -* **Reviewers** = Can contribute Translations to existing *Components* +* **Users** = Can log in and perform translations (*applies to new users*) -* **Managers** = Can create new *Components* of existing *Projects* +* **Reviewers** = Can contribute translations to existing *components* and review translations -* **Superusers** = Can create new *Projects* +* **Managers** = Can create new *components* of existing *projects* -Upgrading Privileges --------------------- +* **Superusers** = Can create new *projects*, moreover they manage Weblate's settings and repository maintenance, can edit all user accounts, deactivate users, trigger commits from Weblate's local repositories with pushes to Git and perform backups of language files + +How to contribute with your translation +--------------------------------------- + +1 - Log into https://weblate.taler.net + +2 - Navigate to *Projects* and *Browse all projects* + +3 - Choose the *project* you wish to contribute to + +4 - Choose the *component* you wish to contribute to + +5 - Find the language you want to translate into + +6 - Find a phrase and translate it + +7 - While translating, take into consideration at each string to translate + +* the comments + +* the context + +* the string location in the source code + +* the "nearby strings" in Weblate as one of the sorting options on the translation form + +* "other languages" as another sorting option to compare strings in a way translatologists would do + +* if applicable, the history of string changes and the message ID or key of a string + +8 - **Always test your translations in the actual apps** after they have been pushed by the platform to the apps + +9 - Be aware of ambiguities and immediately **report inconsistencies or bugs** by using Mantis bug tickets + +10 - If you want to contribute your translation in a language which does not yet exist in a Taler component, navigate to the *component* you want to translate for and click "Start new translation" to begin. In case you require a privilege upgrade, please contact a *Superuser* with your request. Currently, *Superusers* are Christian, Florian, Martin, and Stefan. + +Translation standards and practices +----------------------------------- + +1 - *Developers*, Weblate *reviewers* and *managers* MUST look into **design documents** for the specific component or software project, like e.g. for the Taler wallets DD53 https://docs.taler.net/design-documents/053-wallet-ui.html and stick close to the documentation, especially the **text to use** and **text to avoid** + +2 - To every ambiguous string *developers* MUST add **context** or **comments** to the strings on Weblate + +3 - *Developers*, Weblate *reviewers* and *managers* SHOULD add **screenshots** where needed to the strings on Weblate -To upgrade from **Users**/**Viewers**, a superuser must manually augment your privileges. At this time, superusers are Christian, Florian, and Buck. +4 - Weblate *managers* MUST take care of **checks** in the translations overview and keep the repositories consistent and up-to-date, t.i. to perform regularly **synchronisation** between Git and Weblate repositories and vice-versa -How to Create a Project +5 - *Weblate admins* MUST set the **commit and push rules** to *manual* only, and when asked, set the license to *GPLv3 or later* + +6 - You MAY also wish to refer to https://docs.weblate.org/ and to the ``README files`` in components like web pages to find out more specific variables if prompted + +How to create a project ----------------------- -The *GNU Taler* project is probably the correct project for most Components and Translations falling under this guide. Please contact a superuser if you need another Project created. +The *GNU Taler* project is probably the correct project for most Weblate components and Taler-related translations. Please contact a *Superuser* if you need another project created. -How to Create a Component +How to create a component ------------------------- -Reference: https://docs.weblate.org/en/weblate-4.0.3/admin/projects.html#component-configuration +Reference: https://docs.weblate.org/en/weblate-5.13.2/admin/projects.html#component-configuration -In Weblate, a *Component* is a subset of a *Project* and each Component contains N translations. A Component is generally associated with a Git repo. +In Weblate, a *component* is a subset of a *project* and each component contains N translations. A component is generally associated with a Git repository. -To create a Component, log into https://weblate.taler.net/ with your *Manager* or higher credentials and choose **+ Add** from the upper-right corner. +To create a component, log into https://weblate.taler.net/ with your credentials for a *Manager* privilege level (or higher) and choose **+ Add** from the upper-right corner. -What follows is a sort of Wizard. You can find detailed docs at https://docs.weblate.org/. Here are some important notes about connecting your Component to the Taler Git repository: +What follows is a sort of Wizard. You can find detailed docs at https://docs.weblate.org/. Here are some important notes about connecting your component to the Taler Git repository: -Under *https://weblate.taler.net/create/component/vcs/*: +On the component level, choose *Operations* from the menu bar, select *Settings*, then add at the tab *Basic* these settings: -* **Source code repository** - Generally ``git+ssh://git@git.taler.net/<reponame>```. Check with ``git remote -v``. +* **Component name** - The distinctive name of the software project, e.g. ``Main web site`` -* **Repository branch** - Choose the correct branch to draw from and commit to. +* **Translation license** - Choose *GNU Affero General Public License v3.0 or Later* -* **Repository push URL** - This is generally ``git+ssh://git@git.taler.net/<reponame>``` Check with ``git remote -v``. +* **Contributor license agreement** - left empty as the *Translation license* defaults -* **Repository browser** - This is the www URL of the Git repo's file browser. Example ``https://git.taler.net/<repositoryname>.git/tree/{{filename}}?h={{branch}}#n{{line}}`` where ``<repositoryname>`` gets replaced but ``{{filename}}`` and other items in braces are actual variables in the string. +* **Source string bug reporting address** - This requires an email address of the Weblate admin or *Superuser* in charge or just ``languages@taler.net`` -* **Merge style** - *Rebase*, in line with GNU Taler development procedures +* **Priority** - Generally ``Medium`` -* **Translation license** - *GNU Affero General Public License v3.0 or Later* +* **Restricted component** - ``deactivated`` -* **Adding new translation** - Decide how to handle adding new translations +* **Share in projects** - ``deactivated`` -How to Create a Translation ---------------------------- +* **Use as a glossary** - ``deactivated`` -1 - Log into https://weblate.taler.net +At the tab *Translation* settings are generally: -2 - Navigate to *Projects* > *Browse all projects* +* **Turn on suggestions** - ``activated`` -3 - Choose the *Project* you wish to contribute to. +* **Allow translation propagation** - ``activated`` -4 - Choose the *Component* you wish to contribute to. +* **Contribute to project translation memory** - ``activated`` -5 - Find the language you want to translate into. Click "Translate" on that line. +* **Secondary language** - Leave empty (respectively ``--------`` ) -6 - Find a phrase and translate it. +At the tab *Version control* ( *https://weblate.taler.net/create/component/vcs/* ) settings require variables as follows: -You may also wish to refer to https://docs.weblate.org/ . +* **Version Control System** - Generally ``Git`` -Translation Standards and Practices ------------------------------------ +* **Source code repository** - Generally ``git+ssh://git@git.taler.net/<repositoryname>.git``, check with ``git remote -v`` + +* **Repository branch** - Choose the correct branch to draw from and commit to which is generally ``master`` + +* **Repository push URL** - Generally ``git+ssh://git@git.taler.net/<repositoryname>.git``, check with ``git remote -v`` + +* **Push branch** - Choose the correct branch to push to, this is generally ``master`` + +* **Repository browser** - Normally, this field is left empty. If you are required to have this field pointing to the www URL of the Git repo's file browser, it could be filled with ``https://git.taler.net/<repositoryname>.git/tree/{{filename}}?h={{branch}}#n{{line}}`` where ``<repositoryname>`` gets replaced but ``{{filename}}`` and other items in braces are actual variables in the string + +* **Push on commit** - ``deactivated`` + +* **Age of changes to commit** - 24 (hours after which any pending changes will be committed to the VCS) + +* **Merge style** - Generally ``Rebase``, in line with GNU Taler development procedures + +* **Lock on error** - ``activated`` + +At the tab *Commit messages* you can leave the defaults: + +* **Commit message when translating** has the most important message: +Translated using Weblate ({{ language_name }}) +Currently translated at {{ stats.translated_percent }}% ({{ stats.translated }} of {{ stats.all }} strings) +Translation: {{ project_name }}/{{ component_name }} +Translate-URL: {{ url }} + +At the tab *Files* + +* **File format** - Mostly ``gettext PO file`` for web pages, ``Android String Resource`` for Android app strings, ``XLIFF 1.2 translation file`` for iOS apps, or ``TermBase eXchange file`` for some of the glossaries + +* **Language filter** - Dependent on the respective folder structure of the project, for structures used with gettext PO files mostly ``locale/*/LC_MESSAGES/messages.po`` + +* **Language filter** - Generally ``^[^.]+$`` + +* **Source language** - ``English`` + +* **Monolingual translations / Monolingual base language file** - Leave empty + +* **Edit base file** - ``deactivated`` + +* **Intermediate language file** - Leave empty + +* **Template for new translations** - Dependent on the respective folder structure of the project, for structures used with gettext PO files ``locale/messages.pot`` -By default, our Weblate instance is set to accept translations in English, French, German, Italian, Russian, Spanish, and Portuguese. If you want to contribute a translation in a different language, navigate to the *Component* you want to translate for, and click "Start new translation" to begin. If you require a privilege upgrade, please contact a superuser with your request. +* **Adding new translation** - Generally ``Create new language file`` -When asked, set the license to GPLv3 or later. +* **Language code style** - Generally ``Default based on the file format`` -Set commit/push to manual only. +* **Screenshot file mask** - Leave empty (unless we do not dispose of a dedicated screenshot folder with a path relative to repository root) -GPG Signing of Translations +GPG signing of translations --------------------------- -weblate.taler.net signs GPG commits with the GPG key CD33CE35801462FA5EB0B695F2664BF474BFE502, and the corresponding public key can be found at https://weblate.taler.net/keys/. +Weblate signs its GPG commits with the GPG key CD33CE35801462FA5EB0B695F2664BF474BFE502, and the corresponding public key can be found at https://weblate.taler.net/keys/. -This means that contributions made through weblate will not be signed with the individual contributor's key when they are checked into the Git repository, but with the weblate key. +This means that contributions made through Weblate will not be signed with the individual contributor's key when they are checked into the Git repository but with Weblate's public key. diff --git a/taler-merchant-manual.rst b/taler-merchant-manual.rst @@ -399,6 +399,16 @@ There is no need to actually run a Taler exchange to use the Taler merchant backend -- all the merchant needs from the Taler exchange is a few headers and libraries! +.. note:: + + There is an additional **optional** dependency that you could install to + obtain support for tax-deductable donations. This is only useful for + charities and only in countries with tax authorities that operate a Donau to + register charities and accept Taler-style digitally signed donation + statements. As of right now, we are pretty sure that list is right now + empty. But, if you want to experiment with Taler-style donation statmenets, + you need to install Donau after the exchange and before the merchant. + .. include:: frags/install-before-check.rst .. include:: frags/installing-taler-merchant.rst @@ -502,8 +512,8 @@ To run the Taler backend on TCP port 9966 (the default), use: Currency ^^^^^^^^ -Which currency the Web shop deals in, i.e. “EUR” or “USD”, is -specified using the option +Which currency the SPA uses by default is +specified using the option: .. code-block:: ini @@ -511,7 +521,7 @@ specified using the option CURRENCY = EUR # or USD, ... When testing with the Taler demonstration exchange at -https://exchange.demo.taler.net/ you must set this +https://exchange.demo.taler.net/ you probably want to set this value to ``KUDOS``: .. code-block:: ini @@ -519,6 +529,11 @@ value to ``KUDOS``: [MERCHANT] CURRENCY = KUDOS +The merchant backend is already multi-currency capable, and will allow you to +create orders in all currencies for which an exchange is configured, not just +the default currency. However, the Web interface does not yet offer +multi-currency support and often only supports using the default currency. + .. note:: When using the Debian/Ubuntu packages, these options should be @@ -553,17 +568,20 @@ DBMS-specific options to access the database. been created, so you can just run the tool without any arguments and should have a working database configuration. + Please make sure you did not create a taler merchant database manually before running + this command or it will fail with SQL errors. + For the ``postgres`` backend, you need to specify: .. code-block:: ini [merchantdb-postgres] - CONFIG = "postgres:///talermerchant" + CONFIG = "postgres:///taler-merchant" This option specifies a PostgreSQL access path, typically using the format ``postgres:///$DBNAME``, where ``$DBNAME`` is the name of the PostgreSQL -database you want to use (here, ``talermerchant`` on the local machine). +database you want to use (here, ``taler-merchant`` on the local machine). Suppose ``$USER`` is the name of the user who will run the backend process (usually ``taler-merchant-httpd``). Then, you need to first run: @@ -706,6 +724,13 @@ merchant backend as ``$USER`` using (to provide a trivial example): $ taler-merchant-wirewatch & $ taler-merchant-depositcheck & $ taler-merchant-exchangekeyupdate & + $ taler-merchant-reconciliation & + +.. note:: + + If you compiled the merchant backend with support for donation + statements via Donau, you need to additionally launch + ``taler-merchant-donaukeyupdate``. To ensure these processes run always in the background and also after rebooting, you should use systemd, cron or some other init system of your @@ -822,9 +847,17 @@ interface. Alternatively, you can also use the ``wget`` commands given below. Regardless of which approach you use, the first step for using the backend involves the creation of the ``admin`` instance. The ``admin`` instance can also create, configure or delete other instances, similar to the ``root`` -account on UNIX. When no instance exists and ``taler-merchant-httpd`` was -started without the ``--auth`` option, then the backend is reachable without -any access control (unless you configured some in the reverse proxy). +account on UNIX. When no instance exists, then the backend is reachable +without any access control (unless you configured some in the reverse proxy). + +.. note:: + + If you created a non-admin instance first, you cannot create an ``admin`` + instance via the SPA anymore. In this case, you can only create an + administrative account by using the command-line. By invoking + ``taler-merchant-passwd --instance=admin $PASSWORD`` you can set both the + password and create an ``admin`` instance if it does not yet exist. + However, for non-admin instances, you can only set the password with this tool. The following documentation shows how to handle any instance. Thus, if you want to have multiple instances, you may need to perform the steps multiple @@ -865,6 +898,76 @@ and the desired access token, click ``confirm``. You can change the instance settings later via the ``Settings`` entry in the menu on the left. +Instance settings +----------------- + +The settings dialog allows you to select an image to be used as a logo +for your shop. Wallets may use that logo when showing contracts to +highlight to customers which shop they are buying from. + +The settings dialog allows you to specify the address of your business +and the jurisdiction the shop is under. Both will be embedded into the +contracts and may be shown by the Taler wallet to customers that want +to know these details. + +You must also configure whether you intend to pay transaction fees, +or whether the customer is required to pay for any payment fees. If +you do not cover the fees, the fees will be shown separately to the +customer and added to the total of each order, which may discourage +consumers from using the Taler payment method. The specific +magnitude of the fees cannot be configured here, as it depends on +the amount of the order and is dynamically computed. Regardless of +what you specify here, the front-end can override the acceptable +fee amount for each order it creates. + +.. note:: + + Details on the acceptable fee calcuation + are described in the Taler design document 47. + +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 cummulative 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 + cummulative 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:: + + The wire deadline is rounded using the local timezone of the Taler merchant + backend server, so if you want end-of-day payments make sure to run your + merchant backend in your own timezone. + +Specifying larger values for the wire transfer delay and the wire rounding +interval allows the exchange to aggregate more payments into larger wire +transfers. The exchange is required by the protocol to initiate the wire +transfer **before** the wire transfer deadline. + +All of the computed deadlines (payment, refund and wire transfer) +are just defaults and can be modified by frontends for any +specific order. + + Instance setup without the Web interface ---------------------------------------- @@ -883,8 +986,9 @@ interface create a file ``instance.json`` with an "auth": { "method" : "external"} , "jurisdiction": { "country" : "zz" }, "use_stefan": true, - "default_wire_transfer_delay": { "d_ms" : 1209600000 }, "default_pay_delay": { "d_ms" : 1209600000 } + "default_refund_delay": { "d_ms" : 1209600000 } + "default_wire_transfer_delay": { "d_ms" : 1209600000 }, } The ``name`` field will be shown as the name of your shop. The ``address`` diff --git a/wallet/wallet-core.md b/wallet/wallet-core.md @@ -303,6 +303,8 @@ export interface GetDonauStatementsResponse { ```typescript export interface DonauStatementItem { total: AmountString; + year: number; + legalDomain: string; uri: string; donationStatementSig: EddsaSignatureString; donauPub: EddsaPublicKeyString; @@ -1306,7 +1308,7 @@ export interface CheckPayTemplateRequest { ``` ```typescript export type CheckPayTemplateReponse = { - templateDetails: TalerMerchantApi.WalletTemplateDetails; + templateDetails: WalletTemplateDetails; supportedCurrencies: string[]; };
