From 807f2af5879037f15c317fe62056b9493d935fc2 Mon Sep 17 00:00:00 2001 From: Christian Blättler Date: Tue, 24 Oct 2023 07:49:09 +0200 Subject: add tokenfamilies api to merchant --- core/api-merchant.rst | 214 +++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 211 insertions(+), 3 deletions(-) diff --git a/core/api-merchant.rst b/core/api-merchant.rst index 142e83f8..af757225 100644 --- a/core/api-merchant.rst +++ b/core/api-merchant.rst @@ -318,7 +318,7 @@ Making the payment // Custom inputs from the wallet for the contract. wallet_data?: Object; - + // The session for which the payment is made (or replayed). // Only set for session-based payments. session_id?: string; @@ -3311,7 +3311,7 @@ Adding templates // The user may specify any amount, but it must be // in this currency. // This parameter is optional and should not be present - // if "amount" is given. + // if "amount" is given. currency?: string; // The price is imposed by the merchant and cannot be changed by the customer. @@ -3512,7 +3512,7 @@ Adding webhooks The creation of the webhook is successsful. :http:statuscode:`404 Not found`: - The merchant instance is unknowm or it not in our data. + The merchant instance is unknown or it not in our data. .. ts:def:: WebhookAddDetails @@ -3673,6 +3673,214 @@ Removing webhook +---------------------------------------- +Token Families: Subscriptions, Discounts +---------------------------------------- + +This API provides functionalities for the issuance, management, and revocation +of token families. Tokens facilitate the implementation of subscriptions and +discounts, engaging solely the merchant and the user. Each token family +encapsulates details pertaining to its respective tokens, guiding the merchant's +backend on the appropriate processing and handling. + + +Creating token families +----------------------- + +.. http:post:: [/instances/$INSTANCES]/private/tokenfamilies + + This is used to create a token family. + + **Request:** + + The request must be a `TokenFamilyCreateRequest`. + + **Response:** + + :http:statuscode:`200 OK`: + The token family was created successfully. Returns a `TokenFamilyDetails`. + + :http:statuscode:`404 Not found`: + The merchant backend is unaware of the instance. + + .. ts:def:: TokenFamilyCreateRequest + + interface TokenFamilyCreateRequest { + + // Human-readable name for the token family. + name: string; + + // Human-readable description for the token family. + description: string; + + // Optional map from IETF BCP 47 language tags to localized descriptions. + description_i18n?: { [lang_tag: string]: string }; + + // Start time of the token family's validity period. + // If not specified, merchant backend will use the current time. + start_time?: Timestamp; + + // End time of the token family's validity period. + // If not specified, token family is valid indefinitely. + expiration_time?: Timestamp; + + // Validity duration of an issued token. + duration: RelativeTime; + + // Kind of the token family. + kind: TokenFamilyKind; + + } + + .. ts:def:: TokenFamilyKind + + enum TokenFamilyKind { + Discount = "discount", + Subscription = "subscription", + } + + +Updating token families +----------------------- + +.. http:patch:: [/instances/$INSTANCES]/private/tokenfamilies/$TOKEN_FAMILY_ID + + This is used to update a token family. + + **Request:** + + The request must be a `TokenFamilyUpdateRequest`. Only fields that are not + undefined are updated. + + **Response:** + + :http:statuscode:`200 OK`: + The token family was successsful updated. Returns a `TokenFamilyDetails`. + + :http:statuscode:`404 Not found`: + The merchant backend is unaware of the token family or instance. + + .. ts:def:: TokenFamilyUpdateRequest + + interface TokenFamilyUpdateRequest { + + // Human-readable name for the token family. + name?: string; + + // Human-readable description for the token family. + description?: string; + + // Optional map from IETF BCP 47 language tags to localized descriptions. + description_i18n?: { [lang_tag: string]: string }; + + // Validity duration of an issued token. + duration?: RelativeTime; + + // Kind of the token family. + kind?: TokenFamilyKind; + + // Indicates whether the token family can still issue tokens. Note: + // Already issued tokens will be valid, regardless of this setting. + can_issue_tokens?: boolean; + + } + + + +Inspecting token families +------------------------- + +.. http:get:: [/instances/$INSTANCES]/private/tokenfamilies + + This is used to list all configured token families for an instance. + + **Response:** + + :http:statuscode:`200 OK`: + The merchant backend has successfully returned all token families. + Returns a `TokenFamiliesList`. + + :http:statuscode:`404 Not found`: + The merchant backend is unaware of the instance. + + .. ts:def:: TokenFamiliesList + + interface TokenFamiliesList { + + // All configured token families of this instance. + token_families: TokenFamilyDetails[]; + + } + + The `TokenFamilyDetails` object describes a configured token family. + + .. ts:def:: TokenFamilyDetails + + interface TokenFamilyDetails { + + // Human-readable name for the token family. + name: string; + + // Human-readable description for the token family. + description: string; + + // Optional map from IETF BCP 47 language tags to localized descriptions. + description_i18n?: { [lang_tag: string]: string }; + + // Start time of the token family's validity period. + start_time: Timestamp; + + // End time of the token family's validity period. + expiration: Timestamp; + + // Validity duration of an issued token. + duration: RelativeTime; + + // Kind of the token family. + kind: TokenFamilyKind; + + // How many tokens have been issued for this family. + issued: Integer; + + // How many tokens have been redeemed for this family. + redeemed: Integer; + + } + + +.. http:get:: [/instances/$INSTANCES]/private/tokenfamilies/$TOKEN_FAMILY_ID + + This is used to get detailed information about a specific token family. + + **Response:** + + :http:statuscode:`200 OK`: + The merchant backend has successfully returned the detailed information + about a specific token family. Returns a `TokenFamilyDetails`. + + :http:statuscode:`404 Not found`: + The merchant backend is unaware of the token family or instance. + + + +Deleting token families +----------------------- + +.. http:delete:: [/instances/$INSTANCES]/private/tokenfamilies/$TOKEN_FAMILY_ID + + This is used to delete a token family. Issued tokens of this family will not + be spendable anymore. + + **Response:** + + :http:statuscode:`204 No content`: + The backend has successfully deleted the token family. + + :http:statuscode:`404 Not found`: + The merchant backend is unaware of the token family or instance. + + + ------------------ The Contract Terms ------------------ -- cgit v1.2.3 From 73ae19544b21e81bbe24ea835131e0fba305f9e0 Mon Sep 17 00:00:00 2001 From: Christian Blättler Date: Tue, 14 Nov 2023 15:54:06 +0100 Subject: implement feedback on merchant api specification --- core/api-merchant.rst | 97 +++++++++++++++++++++++++++++++++++---------------- 1 file changed, 66 insertions(+), 31 deletions(-) diff --git a/core/api-merchant.rst b/core/api-merchant.rst index af757225..6e1b1f52 100644 --- a/core/api-merchant.rst +++ b/core/api-merchant.rst @@ -3697,8 +3697,8 @@ Creating token families **Response:** - :http:statuscode:`200 OK`: - The token family was created successfully. Returns a `TokenFamilyDetails`. + :http:statuscode:`204 No content`: + The token family was created successfully. :http:statuscode:`404 Not found`: The merchant backend is unaware of the instance. @@ -3707,6 +3707,10 @@ Creating token families interface TokenFamilyCreateRequest { + // Identifier for the token family consisting of unreserved characters + // according to RFC 3986. + slug: string; + // Human-readable name for the token family. name: string; @@ -3721,12 +3725,16 @@ Creating token families start_time?: Timestamp; // End time of the token family's validity period. - // If not specified, token family is valid indefinitely. - expiration_time?: Timestamp; + expiration_time: Timestamp; // Validity duration of an issued token. duration: RelativeTime; + // TODO: How should this be implemented? + // Indicates whether the token family can still issue tokens. Note: + // Already issued tokens will be valid, regardless of this setting. + // can_issue_tokens: boolean; + // Kind of the token family. kind: TokenFamilyKind; @@ -3743,14 +3751,13 @@ Creating token families Updating token families ----------------------- -.. http:patch:: [/instances/$INSTANCES]/private/tokenfamilies/$TOKEN_FAMILY_ID +.. http:patch:: [/instances/$INSTANCES]/private/tokenfamilies/$TOKEN_FAMILY_SLUG This is used to update a token family. **Request:** - The request must be a `TokenFamilyUpdateRequest`. Only fields that are not - undefined are updated. + The request must be a `TokenFamilyUpdateRequest`. **Response:** @@ -3765,23 +3772,27 @@ Updating token families interface TokenFamilyUpdateRequest { // Human-readable name for the token family. - name?: string; + name: string; // Human-readable description for the token family. - description?: string; + description: string; // Optional map from IETF BCP 47 language tags to localized descriptions. - description_i18n?: { [lang_tag: string]: string }; + description_i18n: { [lang_tag: string]: string }; - // Validity duration of an issued token. - duration?: RelativeTime; + // Start time of the token family's validity period. + start_time: Timestamp; - // Kind of the token family. - kind?: TokenFamilyKind; + // End time of the token family's validity period. + expiration_time: Timestamp; + + // Validity duration of an issued token. + duration: RelativeTime; + // TODO: How should this be implemented? // Indicates whether the token family can still issue tokens. Note: // Already issued tokens will be valid, regardless of this setting. - can_issue_tokens?: boolean; + // can_issue_tokens: boolean; } @@ -3805,19 +3816,57 @@ Inspecting token families .. ts:def:: TokenFamiliesList + // TODO: Add pagination + interface TokenFamiliesList { // All configured token families of this instance. - token_families: TokenFamilyDetails[]; + token_families: TokenFamilySummary[]; } + .. ts:def:: TokenFamilySummary + + interface TokenFamilySummary { + // Identifier for the token family consisting of unreserved characters + // according to RFC 3986. + slug: string; + + // Human-readable name for the token family. + name: string; + + // Start time of the token family's validity period. + start_time: Timestamp; + + // End time of the token family's validity period. + expiration: Timestamp; + } + + +.. http:get:: [/instances/$INSTANCES]/private/tokenfamilies/$TOKEN_FAMILY_SLUG + + This is used to get detailed information about a specific token family. + + **Response:** + + :http:statuscode:`200 OK`: + The merchant backend has successfully returned the detailed information + about a specific token family. Returns a `TokenFamilyDetails`. + + :http:statuscode:`404 Not found`: + The merchant backend is unaware of the token family or instance. + + The `TokenFamilyDetails` object describes a configured token family. .. ts:def:: TokenFamilyDetails interface TokenFamilyDetails { + // Identifier for the token family consisting of unreserved characters + // according to RFC 3986. + slug: string; + // Human-readable name for the token family. name: string; @@ -3848,25 +3897,11 @@ Inspecting token families } -.. http:get:: [/instances/$INSTANCES]/private/tokenfamilies/$TOKEN_FAMILY_ID - - This is used to get detailed information about a specific token family. - - **Response:** - - :http:statuscode:`200 OK`: - The merchant backend has successfully returned the detailed information - about a specific token family. Returns a `TokenFamilyDetails`. - - :http:statuscode:`404 Not found`: - The merchant backend is unaware of the token family or instance. - - Deleting token families ----------------------- -.. http:delete:: [/instances/$INSTANCES]/private/tokenfamilies/$TOKEN_FAMILY_ID +.. http:delete:: [/instances/$INSTANCES]/private/tokenfamilies/$TOKEN_FAMILY_SLUG This is used to delete a token family. Issued tokens of this family will not be spendable anymore. -- cgit v1.2.3 From e44c9f6b7ed5cf4ad8a621aadc7a105faf14b18e Mon Sep 17 00:00:00 2001 From: Christian Blättler Date: Tue, 21 Nov 2023 08:20:23 +0100 Subject: better naming for validity range --- core/api-merchant.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/core/api-merchant.rst b/core/api-merchant.rst index 6e1b1f52..c370e297 100644 --- a/core/api-merchant.rst +++ b/core/api-merchant.rst @@ -3722,10 +3722,10 @@ Creating token families // Start time of the token family's validity period. // If not specified, merchant backend will use the current time. - start_time?: Timestamp; + valid_after?: Timestamp; // End time of the token family's validity period. - expiration_time: Timestamp; + valid_before: Timestamp; // Validity duration of an issued token. duration: RelativeTime; @@ -3781,10 +3781,10 @@ Updating token families description_i18n: { [lang_tag: string]: string }; // Start time of the token family's validity period. - start_time: Timestamp; + valid_after: Timestamp; // End time of the token family's validity period. - expiration_time: Timestamp; + valid_before: Timestamp; // Validity duration of an issued token. duration: RelativeTime; @@ -3836,10 +3836,10 @@ Inspecting token families name: string; // Start time of the token family's validity period. - start_time: Timestamp; + valid_after: Timestamp; // End time of the token family's validity period. - expiration: Timestamp; + valid_before: Timestamp; } @@ -3877,10 +3877,10 @@ Inspecting token families description_i18n?: { [lang_tag: string]: string }; // Start time of the token family's validity period. - start_time: Timestamp; + valid_after: Timestamp; // End time of the token family's validity period. - expiration: Timestamp; + valid_before: Timestamp; // Validity duration of an issued token. duration: RelativeTime; -- cgit v1.2.3 From b95e8b15f04f60c85faa723d270bba0d9d165a53 Mon Sep 17 00:00:00 2001 From: Christian Blättler Date: Tue, 21 Nov 2023 15:21:29 +0100 Subject: remove can_issue_tokens (for now) --- core/api-merchant.rst | 10 ---------- 1 file changed, 10 deletions(-) diff --git a/core/api-merchant.rst b/core/api-merchant.rst index c370e297..bee59155 100644 --- a/core/api-merchant.rst +++ b/core/api-merchant.rst @@ -3730,11 +3730,6 @@ Creating token families // Validity duration of an issued token. duration: RelativeTime; - // TODO: How should this be implemented? - // Indicates whether the token family can still issue tokens. Note: - // Already issued tokens will be valid, regardless of this setting. - // can_issue_tokens: boolean; - // Kind of the token family. kind: TokenFamilyKind; @@ -3789,11 +3784,6 @@ Updating token families // Validity duration of an issued token. duration: RelativeTime; - // TODO: How should this be implemented? - // Indicates whether the token family can still issue tokens. Note: - // Already issued tokens will be valid, regardless of this setting. - // can_issue_tokens: boolean; - } -- cgit v1.2.3 From 5f82d484feaa6b41371226cb3239a68a14caa8a3 Mon Sep 17 00:00:00 2001 From: Christian Blättler Date: Tue, 19 Dec 2023 17:55:15 +0100 Subject: add kind to token family --- core/api-merchant.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/core/api-merchant.rst b/core/api-merchant.rst index bee59155..b984819a 100644 --- a/core/api-merchant.rst +++ b/core/api-merchant.rst @@ -3830,6 +3830,9 @@ Inspecting token families // End time of the token family's validity period. valid_before: Timestamp; + + // Kind of the token family. + kind: TokenFamilyKind; } -- cgit v1.2.3 From ba11950f168e73aab72e4ff61683688bfdd7eb7e Mon Sep 17 00:00:00 2001 From: Florian Dold Date: Mon, 22 Jan 2024 21:35:24 +0100 Subject: DD35: management API --- design-documents/035-regional-currencies.rst | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/design-documents/035-regional-currencies.rst b/design-documents/035-regional-currencies.rst index 0b4553e6..8be7ea49 100644 --- a/design-documents/035-regional-currencies.rst +++ b/design-documents/035-regional-currencies.rst @@ -144,6 +144,16 @@ The last part should probably be hidden by default. There might be nicer ways t this, such as some hoverable (?) icon after the amount that shows details about what currencies the merchant accepts. +Wallet-core API for scope management +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +* ``listGlobalCurrencyExchanges`` lists all ``(currency, exchangeUrl, exchangePub)`` triples + where funds are considered to be in global scope (i.e. non-regional). +* ``listGlobalCurrencyAuditors`` lists all ``(currency, auditorUrl, auditorPub)`` triples + where funds are considered to be in global scope (i.e. non-regional). +* ``addGlobalCurrencyExchange`` and ``removeGlobalCurrencyExchange`` adds/removes a ``(currency, exchangeUrl, exchangePub)`` +* ``addGlobalCurrencyAuditor`` and ``removeGlobalCurrencyAuditor`` adds/removes a ``(currency, auditorUrl, auditorPub)`` + Implementation Breakdown ^^^^^^^^^^^^^^^^^^^^^^^^ -- cgit v1.2.3 From bdc58f018a4023f0640922da4fb5d282d7615069 Mon Sep 17 00:00:00 2001 From: Antoine A <> Date: Tue, 23 Jan 2024 14:48:19 +0100 Subject: Update libeufin manpages --- frags/libeufin-config-cli.rst | 8 +++++++- libeufin/nexus-manual.rst | 5 ----- manpages/libeufin-bank.1.rst | 10 ++++++++++ manpages/libeufin-nexus.1.rst | 22 +++++++++++++++++----- manpages/libeufin-nexus.conf.5.rst | 21 --------------------- 5 files changed, 34 insertions(+), 32 deletions(-) diff --git a/frags/libeufin-config-cli.rst b/frags/libeufin-config-cli.rst index 0852c2aa..3974aea8 100644 --- a/frags/libeufin-config-cli.rst +++ b/frags/libeufin-config-cli.rst @@ -19,6 +19,8 @@ It takes two arguments, the section name and the option name Print short help on options. **-c** \| **--config** *FILENAME* Specifies the configuration file. +**-L** \| **--log** *LOGLEVEL* + Configure logging to use LOGLEVEL. **-f** \| **--filename** Interpret value as path with dollar-expansion. @@ -31,6 +33,8 @@ This command dump the configuration. Print short help on options. **-c** \| **--config** *FILENAME* Specifies the configuration file. +**-L** \| **--log** *LOGLEVEL* + Configure logging to use LOGLEVEL. config pathsub -------------- @@ -42,4 +46,6 @@ It takes one argument, a path expresion. **-h** \| **--help** Print short help on options. **-c** \| **--config** *FILENAME* - Specifies the configuration file. \ No newline at end of file + Specifies the configuration file. +**-L** \| **--log** *LOGLEVEL* + Configure logging to use LOGLEVEL. \ No newline at end of file diff --git a/libeufin/nexus-manual.rst b/libeufin/nexus-manual.rst index bc4ca471..0fab068b 100644 --- a/libeufin/nexus-manual.rst +++ b/libeufin/nexus-manual.rst @@ -71,8 +71,6 @@ The frequency **may** be specified as [nexus-submit] frequency = 5m - # Optional, but useful to check what Nexus sends to the bank - submissions_log_directory = $LIBEUFIN_DATA_HOME/uploads The supported time units are ``s`` (seconds), ``m`` (minutes), ``h`` (hours). @@ -166,9 +164,6 @@ be stored. [nexus-postgres] config = postgres:///nexus - [nexus-fetch] - # Optional, but usefull against data loss. - statement_log_directory = $LIBEUFIN_DATA_HOME/downloads Assuming that ``$config_file`` contains any required option, the following command would download any unseen notifications (as camt.054 files). diff --git a/manpages/libeufin-bank.1.rst b/manpages/libeufin-bank.1.rst index 60176ef0..5b8c3721 100644 --- a/manpages/libeufin-bank.1.rst +++ b/manpages/libeufin-bank.1.rst @@ -57,6 +57,8 @@ Its options are as follows: Print short help on options. **-c** \| **--config** *FILENAME* Specifies the configuration file. +**-L** \| **--log** *LOGLEVEL* + Configure logging to use LOGLEVEL. **-r** \| **--reset** If present, deletes any database table (WARNING: potential data loss) @@ -72,6 +74,8 @@ Its options are as follows: Print short help on options. **-c** \| **--config** *FILENAME* Specifies the configuration file. +**-L** \| **--log** *LOGLEVEL* + Configure logging to use LOGLEVEL. create-account -------------- @@ -84,6 +88,8 @@ Its options are as follows: Print short help on options. **-c** \| **--config** *FILENAME* Specifies the configuration file. +**-L** \| **--log** *LOGLEVEL* + Configure logging to use LOGLEVEL. **-u** \| **--username** *USERNAME* Account unique username. **-p** \| **--password** *PASSWORD* @@ -119,6 +125,8 @@ Its options are as follows: Print short help on options. **-c** \| **--config** *FILENAME* Specifies the configuration file. +**-L** \| **--log** *LOGLEVEL* + Configure logging to use LOGLEVEL. **--name** *NAME* Legal name of the account owner. **--public** *true|false* @@ -145,6 +153,8 @@ Its options are as follows: Print short help on options. **-c** \| **--config** *FILENAME* Specifies the configuration file. +**-L** \| **--log** *LOGLEVEL* + Configure logging to use LOGLEVEL. .. include:: ../frags/libeufin-config-cli.rst diff --git a/manpages/libeufin-nexus.1.rst b/manpages/libeufin-nexus.1.rst index 17ddd1ec..70a137b3 100644 --- a/manpages/libeufin-nexus.1.rst +++ b/manpages/libeufin-nexus.1.rst @@ -48,9 +48,11 @@ This command creates the client keys, if they aren't found already on the disk, Its options are as follows: **-h** \| **--help** - Prints short help on options. -**-c** \| **--config** \ ‌\ *FILENAME* + Print short help on options. +**-c** \| **--config** *FILENAME* Specifies the configuration file. +**-L** \| **--log** *LOGLEVEL* + Configure logging to use LOGLEVEL. **--force-keys-resubmission** Resubmits the client keys. If no keys were found, it creates and submits them. **--auto-accept-keys** @@ -68,8 +70,10 @@ Its options are as follows: **-h** \| **--help** Print short help on options. -**-c** \| **--config** \ ‌\ *FILENAME* +**-c** \| **--config** *FILENAME* Specifies the configuration file. +**-L** \| **--log** *LOGLEVEL* + Configure logging to use LOGLEVEL. **-r** \| **--reset** If present, deletes any database table (WARNING: potential data loss) @@ -83,8 +87,11 @@ Its options are as follows: **-h** \| **--help** Print short help on options. -**-c** \| **--config** \ ‌\ *FILENAME* +**-c** \| **--config** *FILENAME* Specifies the configuration file. +**-L** \| **--log** *LOGLEVEL* + Configure logging to use LOGLEVEL. + Uploaded documents will be stored *before* being submitted to the bank. This directory would contain several directories, each named after the ``YYYY-MM-DD/submit`` format. The pain.001 file would then be named in the following schema: ``$microseconds_pain.001.xml``. **--transient** This flag, enabled by default, causes the command to check the database and submit only once, and then return. @@ -96,8 +103,13 @@ This subcommand downloads banking records via EBICS and stores them into the dat **-h** \| **--help** Print short help on options. -**-c** \| **--config** \ ‌\ *FILENAME* +**-c** \| **--config** *FILENAME* Specifies the configuration file. +**-L** \| **--log** *LOGLEVEL* + Configure logging to use LOGLEVEL. +**--debug-ebics** *SAVEDIR* + Log EBICS content at SAVEDIR. + Downloaded documents will be stored *before* being ingested in the database. This directory would contain several directories, each named after the ``YYYY-MM-DD/fetch`` format. The stored files would then be named after the following schema: ``$microseconds_$filename``. Exception to this naming scheme are the HAC responses, since they do not get any filename assigned by the ZIP archive (they are sent unzipped). Their naming scheme is: ``$microseconds_HAC_response.pain.002.xml``. **--transient** This flag, enabled by default, causes the command to perform one download and return. **--pinned-start** diff --git a/manpages/libeufin-nexus.conf.5.rst b/manpages/libeufin-nexus.conf.5.rst index 5bb9df2a..1ebe8b67 100644 --- a/manpages/libeufin-nexus.conf.5.rst +++ b/manpages/libeufin-nexus.conf.5.rst @@ -156,16 +156,6 @@ FREQUENCY Duration value to instruct the ``ebics-submit`` subcommand how much to wait before checking the database again to find new unsubmitted payments. -SUBMISSIONS_LOG_DIRECTORY - Optional value to define the path where the pain.001 documents gets stored *before* - being submitted to the bank. This directory would contain several directories, - each named after the YYYY-MM-DD format. The pain.001 file would then be named in - the following schema: ``$submissionTimestampMicroseconds_requestUid_$requestUid_pain.001.xml``. - ``$requestUid`` is the same value that constitutes the pain.001 ``MsgIg`` element. - In the event that one log file would be overridden, ``ebics-submit`` fails without - overriding it. - - EBICS FETCH OPTIONS ------------------- @@ -175,17 +165,6 @@ FREQUENCY Duration value to instruct the ``ebics-fetch`` subcommand how often it should download from the bank. -STATEMENT_LOG_DIRECTORY - Optional value to define the path where the downloaded documents would be stored - *before* being ingested in the database. This directory would contain several - directories, each named after the YYYY-MM-DD format. The stored files would then - be named after the following schema: - ``$downloadTimestampMicroseconds_$filenameAsGivenByTheBank``. In case one log file - would be overridden, ``ebics-fetch`` fails without overriding it. - Exception to this naming scheme are the HAC responses, since they do not get any - filename assigned by the ZIP archive (they are sent unzipped). Their naming scheme - is: ``$downloadTimestampMicroseconds_HAC_response.pain.002.xml`` - SEE ALSO ======== -- cgit v1.2.3 From 93d0d8373e3f7bbf2d7a3cb1be492d9c1b277c7f Mon Sep 17 00:00:00 2001 From: Antoine A <> Date: Tue, 23 Jan 2024 20:47:29 +0100 Subject: Update Revenue and WireGateway API --- core/api-bank-revenue.rst | 56 +++++++++++++++++++++++++++++++---------------- core/api-bank-wire.rst | 27 +++++++++++++++++++++++ 2 files changed, 64 insertions(+), 19 deletions(-) diff --git a/core/api-bank-revenue.rst b/core/api-bank-revenue.rst index 05daa40b..0ccc7123 100644 --- a/core/api-bank-revenue.rst +++ b/core/api-bank-revenue.rst @@ -22,6 +22,34 @@ Taler Bank Revenue HTTP API This section describes an API offered by libeufin-nexus and libeufin-bank. The API is used by the merchant (or other parties) to query for incoming transactions to their account. +.. http:get:: /config + + Return the protocol version and configuration information about the bank. + This specification corresponds to ``current`` protocol being version **0**. + + **Response:** + + :http:statuscode:`200 OK`: + The exchange responds with a `RevenueConfig` object. This request should + virtually always be successful. + + **Details:** + + .. ts:def:: RevenueConfig + + interface RevenueConfig { + // Name of the API. + name: "taler-revenue"; + + // 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; + + // Currency used by this gateway. + currency: string; + } + -------------- Authentication @@ -36,14 +64,9 @@ Querying the transaction history .. http:get:: /history - Return a list of transactions made from an exchange to the merchant. - - Incoming transactions must contain a valid wire transfer identifier and - exchange base URL. If a bank transaction does not conform to the right - syntax, the wire gateway must not report it to the merchant via this - endpoint. + Return a list of transactions made to an account. - The bank account of the merchant is determined via the base URL and/or the + The bank account is determined via the base URL and/or the user name in the ``Authorization`` header. In fact, the transaction history might come from a "virtual" account, where multiple real bank accounts are merged into one history. @@ -93,23 +116,21 @@ Querying the transaction history **Details:** - .. ts:def:: MerchantIncomingHistory + .. ts:def:: RevenueIncomingHistory - interface MerchantIncomingHistory { + interface RevenueIncomingHistory { // Array of incoming transactions. - incoming_transactions : MerchantIncomingBankTransaction[]; + incoming_transactions : RevenueIncomingBankTransaction[]; // Payto URI to identify the receiver of funds. - // This must be one of the merchant's bank accounts. // Credit account is shared by all incoming transactions // as per the nature of the request. credit_account: string; - } - .. ts:def:: MerchantIncomingBankTransaction + .. ts:def:: RevenueIncomingBankTransaction - interface MerchantIncomingBankTransaction { + interface RevenueIncomingBankTransaction { // Opaque identifier of the returned record. row_id: SafeUint64; @@ -122,9 +143,6 @@ Querying the transaction history // Payto URI to identify the sender of funds. debit_account: string; - // Base URL of the exchange where the transfer originated form. - exchange_url: string; - - // The wire transfer identifier. - wtid: WireTransferIdentifierRawP; + // The wire transfer subject. + subject: string; } diff --git a/core/api-bank-wire.rst b/core/api-bank-wire.rst index 86422626..eb7920f9 100644 --- a/core/api-bank-wire.rst +++ b/core/api-bank-wire.rst @@ -24,6 +24,33 @@ well as by the auditor to query incoming and outgoing transactions. This API is currently implemented by the Taler Demo Bank, as well as by LibEuFin (work in progress). +.. http:get:: /config + + Return the protocol version and configuration information about the bank. + This specification corresponds to ``current`` protocol being version **0**. + + **Response:** + + :http:statuscode:`200 OK`: + The exchange responds with a `WireConfig` object. This request should + virtually always be successful. + + **Details:** + + .. ts:def:: WireConfig + + interface WireConfig { + // Name of the API. + name: "taler-wire-gateway"; + + // 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; + + // Currency used by this gateway. + currency: string; + } -------------- Authentication -- cgit v1.2.3 From 968813951b4c10005f12ec15afafab97c0e8ee68 Mon Sep 17 00:00:00 2001 From: Florian Dold Date: Tue, 23 Jan 2024 21:55:12 +0100 Subject: dd39: document decision --- design-documents/039-taler-browser-integration.rst | 39 +++++++++++++++++----- 1 file changed, 30 insertions(+), 9 deletions(-) diff --git a/design-documents/039-taler-browser-integration.rst b/design-documents/039-taler-browser-integration.rst index 71feb1c6..2ca24de4 100644 --- a/design-documents/039-taler-browser-integration.rst +++ b/design-documents/039-taler-browser-integration.rst @@ -81,11 +81,32 @@ Requirements should work smoothly with future browsers that have native, built-in support for Taler payments. +Proposed Solution +================= + +.. note:: + + As of 2023-01-23, we've decided to go ahead with the approach + described in this section. + +Now +^^^ + +* Handling ``taler://`` URIs by overriding the onclick handler of ``a`` HTML elements. + This requires excessive permissions but would be a viable work-around, + at least on pages that opt in with a special ```` tag. + It does not work in all use-cases, for example when a navigation + to a ``taler://`` URI is initiated programmatically or by pasting + the URI in the browser's address bar. + +* Handling a ``taler://`` URI by putting it directly in a meta tag that causes the + wallet to get triggered *on page load*. -Alternatives -============ -* JavaScript API: The WebExtension could inject a JavaScript API into Websites +Future (post-1.0) +^^^^^^^^^^^^^^^^^ + +* JavaScript API: The WebExtension can inject a JavaScript API into Websites that allow interacting with the Taler wallet. This is the approach taken by the MetaMask crypto wallet. It requires excessive permissions, may break some Websites (https://github.com/brave/browser-laptop/issues/13711) and @@ -100,12 +121,12 @@ Alternatives if the Website does not know the extension's ID. Hard-coding the extension IDs would violate the "no vendor lock-in requirement". -* Handling ``taler://`` URIs by overriding the onclick handler of ``a`` HTML elements. - This requires excessive permissions but would be a viable work-around, - at least on pages that opt in with a special ```` tag. - It does not work in all use-cases, for example when a navigation - to a ``taler://`` URI is initiated programmatically or by pasting - the URI in the browser's address bar. + + + +Other Alternatives +================== + * Triggering interactions with the ``taler://`` URI in a ``Taler:`` HTTP header. This approach would allow browsers with native Taler support -- cgit v1.2.3 From b386faed01df759843ad5bbccf22972dd553e96b Mon Sep 17 00:00:00 2001 From: Antoine A <> Date: Tue, 23 Jan 2024 22:51:31 +0100 Subject: Improve nexus documentation --- frags/ebics-setup.rst | 27 ++++++++------------------- libeufin/regional-manual.rst | 4 +++- 2 files changed, 11 insertions(+), 20 deletions(-) diff --git a/frags/ebics-setup.rst b/frags/ebics-setup.rst index c6ff5143..8d822e8e 100644 --- a/frags/ebics-setup.rst +++ b/frags/ebics-setup.rst @@ -1,4 +1,3 @@ - When you sign up for an EBICS-enabled bank account, the bank will provide you with various credentials. Those must be provided in the ``/etc/libeufin/libeufin-nexus.conf`` configuration file together with the @@ -22,10 +21,6 @@ The following snippet shows the mandatory configuration values: USER_ID = myuser PARTNER_ID = myorg - # Key files - BANK_PUBLIC_KEYS_FILE = ${LIBEUFIN_HOME}/bank-keys.json - CLIENT_PRIVATE_KEYS_FILE = ${LIBEUFIN_HOME}/subscriber-keys.json - # Account information IBAN = myiban BIC = mybic @@ -35,29 +30,23 @@ The following snippet shows the mandatory configuration values: Refer to the manpage ``libeufin-nexus.conf(5)`` for the full array of configuration values. -Assuming that the configuration file exists at ``$config_file``, the following -command would start the EBICS setup process. The files CLIENT_PRIVATE_KEYS_FILE -and BANK_PUBLIC_KEYS_FILE would be created at the CWD. Adjust their path to your -setup ('$HOME' is currently not supported along paths). +.. note:: + If you want to use existing client keys, copy the JSON file to the configured path ``CLIENT_PRIVATE_KEYS_FILE`` (``/var/lib/libeufin-nexus/client-ebics-keys.json`` by default) before running the commands. + +Assuming that the configuration file exists at ``$config_file``, the following command would start the EBICS setup process. .. code-block:: console libeufin-nexus ebics-setup -c $config_file -If the previous command succeeded, the subscriber keys reached the bank, but the setup -**should** fail with an ``EBICS_INVALID_USER_STATE`` error code. That happens because -the client tries to download the bank keys *before* having confirmed the subscriber keys -via the traditional post service. +If the previous command failed when running EBICS INI with an error code ``EBICS_INVALID_USER_STATE``, you need to confirm your keys to your bank to activate your account. -To that purpose, the previous run should have left a PDF document that the subscriber can -print, sign, and send to the bank to confirm their subscriber keys. Look for the message -looking like ``PDF file with keys hex encoding created at: /tmp/libeufin-nexus-keys-$timestamp.pdf``. +To that purpose, the previous run should have left a PDF document that you can print, sign and send to the bank. Look for the message that looks like ``PDF file with keys hex encoding created at: /tmp/libeufin-nexus-keys-$timestamp.pdf``. -Once the bank received and approved such printed document, run the same command again, in -order to download the bank keys and let the user accept them. +Once the bank has received and approved this printed documents, run the same command again to download and accept the bank keys. .. code-block:: console libeufin-nexus ebics-setup -c $config_file -The setup is considered finished once the user accepts the bank keys. \ No newline at end of file +The setup is considered finished once the bank keys are accepted. \ No newline at end of file diff --git a/libeufin/regional-manual.rst b/libeufin/regional-manual.rst index e497e8c9..97b39a7d 100644 --- a/libeufin/regional-manual.rst +++ b/libeufin/regional-manual.rst @@ -150,6 +150,8 @@ tested with the Postfinance (CHF). Please note that banks tend to have their own dialects of finance messages and thus other retail banks may or may not work. Contact us if you need support for another bank or core banking protocol. +.. _regional-ebics-setup: + EBICS setup +++++++++++ @@ -169,7 +171,7 @@ Prerequisites This step assumes that you already have a working regional currency bank and have successfully connected to a backing fiat bank account. -Follow the instructions from :ref:`EBICS subscriber setup `. +Follow the instructions from :ref:`EBICS setup `. Configuration ------------- -- cgit v1.2.3 From 4c60ed435413607769fe48115a7ab44335efb78b Mon Sep 17 00:00:00 2001 From: Florian Dold Date: Tue, 23 Jan 2024 23:40:24 +0100 Subject: dd39: expand on proposed solution --- design-documents/039-taler-browser-integration.rst | 92 ++++++++++++++-------- 1 file changed, 61 insertions(+), 31 deletions(-) diff --git a/design-documents/039-taler-browser-integration.rst b/design-documents/039-taler-browser-integration.rst index 2ca24de4..029ca6d4 100644 --- a/design-documents/039-taler-browser-integration.rst +++ b/design-documents/039-taler-browser-integration.rst @@ -89,38 +89,68 @@ Proposed Solution As of 2023-01-23, we've decided to go ahead with the approach described in this section. -Now -^^^ - -* Handling ``taler://`` URIs by overriding the onclick handler of ``a`` HTML elements. - This requires excessive permissions but would be a viable work-around, - at least on pages that opt in with a special ```` tag. - It does not work in all use-cases, for example when a navigation - to a ``taler://`` URI is initiated programmatically or by pasting - the URI in the browser's address bar. - -* Handling a ``taler://`` URI by putting it directly in a meta tag that causes the - wallet to get triggered *on page load*. - - -Future (post-1.0) -^^^^^^^^^^^^^^^^^ - -* JavaScript API: The WebExtension can inject a JavaScript API into Websites - that allow interacting with the Taler wallet. This is the approach taken by - the MetaMask crypto wallet. It requires excessive permissions, may break - some Websites (https://github.com/brave/browser-laptop/issues/13711) and - requires merchants to include extra JavaScript. - - * This type of interaction is useful for Single Page Apps and - might be provided by the GNU Taler wallet reference implementation, - at least when the user grants additional permissions. - * Unfortunately, browsers currently do not provide a safe way - for the communication between a WebExtension and the page - without excessive permissions. This especially applies - if the Website does not know the extension's ID. Hard-coding - the extension IDs would violate the "no vendor lock-in requirement". +Overview +^^^^^^^^ +The following integration approaches between Websites and the Taler Wallet webextension +are provided: + +1. Directly triggering a ``taler://...`` URI on page load (via a meta tag). +2. Overriding ```` tags to trigger the wallet. + The onclick handler (which must call preventDefault) can implement behavior + that happens only when the webextension is not available. +3. Future (possibly post-1.0): A ``window.taler`` JavaScript API that is injected + into every page that requests it via a meta tag. This is useful for SPAs that + want to programmatically trigger the Taler wallet. + + +Usage +^^^^^ + +To directly trigger the handling of a ``taler://`` URI on page load, the following meta tag can be used: + +.. code:: + + + + +To enable additional communication features between a website and the GNU Taler Wallet webextension, the page must +include the following meta tag: + +.. code:: + + + +where ``$features`` is a comma-separated list of features. + +The following features are supported: + +* ``uri`` will hijack anchor elements (````) and replace their onclick handler + with a different handler that lets the webexension wallet handle the ``taler://`` URI. +* (future): ``api`` will inject the ``window.taler`` API into the page + + +Caveats and Comments +^^^^^^^^^^^^^^^^^^^^ + +* Anchor tag hijacking does not work in all use-cases, for example when a navigation +to a ``taler://`` URI is initiated programmatically or by pasting +the URI in the browser's address bar. + +* The ``window.taler`` API injection may break some websites + (https://github.com/brave/browser-laptop/issues/13711). + +* All these approaches require excessive permissions, as unfortunately, + browsers currently do not provide a safe way for the communication between a + WebExtension and the page without excessive permissions. This especially + applies if the Website does not know the extension's ID. Hard-coding the + extension IDs would violate the "no vendor lock-in requirement". + +* A neat feature of the anchor hijacking is that the ``taler://`` URI can be always be copied + in the browser (via "copy link address"). Clicking the link always results in either: + * The native URI handler, if no Taler Wallet webextension is installed and no onclick handler is defined + * The execution of the websites onclick handler if no Taler Wallet webextension is installed + * Triggering the webextension wallet to handle the ``taler://`` URI. -- cgit v1.2.3 From 905ffc59c7d0b70cfab7cc829bd843df680d854a Mon Sep 17 00:00:00 2001 From: Florian Dold Date: Wed, 24 Jan 2024 15:07:16 +0100 Subject: dd39: remove confusing example/suggestion --- design-documents/039-taler-browser-integration.rst | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/design-documents/039-taler-browser-integration.rst b/design-documents/039-taler-browser-integration.rst index 029ca6d4..e34a8d00 100644 --- a/design-documents/039-taler-browser-integration.rst +++ b/design-documents/039-taler-browser-integration.rst @@ -54,13 +54,7 @@ The problems with individual browsers are: either. Another issue is that Websites can't easily find out whether a browser -extension handling the ``taler://`` protocol is installed. To avoid using this -information for fingerprinting, anchors could provide an alternative ``href`` -in case the main one is not handled, such as: - -.. code:: html - - ... +extension handling the ``taler://`` protocol is installed. Requirements ============ @@ -184,6 +178,10 @@ Other Alternatives the Web Payments API would not support the withdrawal flow (``taler://withdraw`` URIs). +* Browsers could provide anchor elements with a fallback when the protocol isn't supported, such as + ``...``. + + Related Work and References =========================== -- cgit v1.2.3 From 4362ba6cc4044b22ff53f1a63611b6c42b55209f Mon Sep 17 00:00:00 2001 From: Sebastian Date: Wed, 24 Jan 2024 11:20:55 -0300 Subject: comment on window.taler injection --- design-documents/039-taler-browser-integration.rst | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/design-documents/039-taler-browser-integration.rst b/design-documents/039-taler-browser-integration.rst index e34a8d00..b7cd346c 100644 --- a/design-documents/039-taler-browser-integration.rst +++ b/design-documents/039-taler-browser-integration.rst @@ -121,6 +121,7 @@ The following features are supported: * ``uri`` will hijack anchor elements (````) and replace their onclick handler with a different handler that lets the webexension wallet handle the ``taler://`` URI. + * (future): ``api`` will inject the ``window.taler`` API into the page @@ -142,11 +143,14 @@ the URI in the browser's address bar. * A neat feature of the anchor hijacking is that the ``taler://`` URI can be always be copied in the browser (via "copy link address"). Clicking the link always results in either: + * The native URI handler, if no Taler Wallet webextension is installed and no onclick handler is defined * The execution of the websites onclick handler if no Taler Wallet webextension is installed * Triggering the webextension wallet to handle the ``taler://`` URI. - +* Future ``window.taler`` injection should be based on user preferences on + sites where the user has explicitly accepted to disclose that is owner of a + Taler wallet. Other Alternatives ================== -- cgit v1.2.3 From c19624f05f5d6be77d74fa3bf12abed8d92df668 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Sun, 28 Jan 2024 18:06:23 +0100 Subject: restructure a bit to avoid confusing duplication of section titles: --- core/api-corebank.rst | 68 +++++++++++++++++++++-------------------------- taler-merchant-manual.rst | 7 +++-- 2 files changed, 33 insertions(+), 42 deletions(-) diff --git a/core/api-corebank.rst b/core/api-corebank.rst index 87c4f969..d1cca6f2 100644 --- a/core/api-corebank.rst +++ b/core/api-corebank.rst @@ -66,7 +66,7 @@ Config **Response:** - :http:statuscode:`200 OK`: + :http:statuscode:`200 OK`: Response is a `Config`. **Details:** @@ -86,7 +86,7 @@ Config // If 'false' some parts of the API are not supported and return 501 allow_conversion: boolean; - // If 'true' anyone can register + // If 'true' anyone can register // If 'false' only admin can allow_registrations: boolean; @@ -104,7 +104,7 @@ Config // Default debt limit for newly created accounts default_debit_threshold: Amount; - + // Currency used by this bank. currency: string; @@ -298,7 +298,7 @@ Account Management .. http:patch:: /accounts/$USERNAME/auth Allows changing the account's password. - + **Request:** @@ -332,13 +332,13 @@ Account Management Show those accounts whose histories are publicly visible. For example, accounts from donation receivers. As such, this request is unauthenticated. - + **Request:** :query delta: *Optional.* Takes value of the form ``N (-N)``, so that at most ``N`` values strictly older (younger) than ``start`` are returned. Defaults to ``-20`` to return the last 20 entries. - :query start: *Optional.* + :query start: *Optional.* Row number threshold, see ``delta`` for its interpretation. Defaults to smallest or biggest row id possible according to ``delta`` sign. :query filter_name: *Optional.* Pattern to filter on the account legal name. Given @@ -388,7 +388,7 @@ Account Management :query delta: *Optional.* Takes value of the form ``N (-N)``, so that at most ``N`` values strictly older (younger) than ``start`` are returned. Defaults to ``-20`` to return the last 20 entries. - :query start: *Optional.* + :query start: *Optional.* Row number threshold, see ``delta`` for its interpretation. Defaults to smallest or biggest row id possible according to ``delta`` sign. :query filter_name: *Optional.* Pattern to filter on the account legal name. Given @@ -531,7 +531,7 @@ Transactions :query delta: *Optional.* Takes value of the form ``N (-N)``, so that at most ``N`` values strictly older (younger) than ``start`` are returned. Defaults to ``-20`` to return the last 20 entries. - :query start: *Optional.* + :query start: *Optional.* Row number threshold, see ``delta`` for its interpretation. Defaults to smallest or biggest row id possible according to ``delta`` sign. :query long_poll_ms: Optional number to express how many milliseconds the server should wait for at least one result to be shown. If not given, the server @@ -697,16 +697,16 @@ Taler Withdrawals **Response:** - :http:statuscode:`204 No content`: + :http:statuscode:`204 No content`: The withdrawal operation has been aborted. :http:statuscode:`404 Not found`: The withdrawal operation was not found. - :http:statuscode:`409 Conflict`: + :http:statuscode:`409 Conflict`: The withdrawal operation has been confirmed previously and can't be aborted. .. http:get:: /withdrawals/$WITHDRAWAL_ID - Retrieve public information about ``WITHDRAWAL_ID`` withdrawal operation. + Retrieve public information about ``WITHDRAWAL_ID`` withdrawal operation. Does not require further authentication as knowledge of ``WITHDRAWAL_ID`` serves as an authenticator. @@ -878,7 +878,7 @@ Cashouts :query delta: *Optional.* Takes value of the form ``N (-N)``, so that at most ``N`` values strictly older (younger) than ``start`` are returned. Defaults to ``-20`` to return the last 20 entries. - :query start: *Optional.* + :query start: *Optional.* Row number threshold, see ``delta`` for its interpretation. Defaults to smallest or biggest row id possible according to ``delta`` sign. **Response:** @@ -915,7 +915,7 @@ Cashouts :query delta: *Optional.* Takes value of the form ``N (-N)``, so that at most ``N`` values strictly older (younger) than ``start`` are returned. Defaults to ``-20`` to return the last 20 entries. - :query start: *Optional.* + :query start: *Optional.* Row number threshold, see ``delta`` for its interpretation. Defaults to smallest or biggest row id possible according to ``delta`` sign. .. note:: @@ -980,7 +980,7 @@ Cashouts // Info of the last successful transmission of the TAN challenge. tan_info: string; } - + .. ts:def:: Challenge interface Challenge { @@ -988,7 +988,7 @@ Cashouts // operation. challenge_id: string; } - + .. ts:def:: TanChannel enum TanChannel { @@ -1025,7 +1025,7 @@ Cashouts * ``TALER_EC_BANK_TAN_CHALLENGE_EXPIRED`` : expired TAN. :http:statuscode:`429 Too many requests`: Too many failed confirmation attempts, a new TAN must be requested. - + Monitor ------- @@ -1060,7 +1060,7 @@ Monitor **Response:** - :http:statuscode:`200 OK`: + :http:statuscode:`200 OK`: The bank responds with `MonitorResponse`. :http:statuscode:`400 Bad Request`: This error may indicate that the *which* parameter is not appropriate for the selected *timeframe*. For example, timeframe=month and which=20 would result in this error. @@ -1073,7 +1073,7 @@ Monitor factors to serve different views to their users. .. ts:def:: MonitorResponse - + // Union discriminated by the "type" field. type MonitorResponse = | MonitorNoConversion @@ -1089,7 +1089,7 @@ Monitor // bank account. talerInCount: Integer; - // Overall volume that has been paid to a Taler + // Overall volume that has been paid to a Taler // exchange by another bank account. talerInVolume: Amount; @@ -1097,7 +1097,7 @@ Monitor // bank account. talerOutCount: Integer; - // Overall volume that has been paid by a Taler + // Overall volume that has been paid by a Taler // exchange to another bank account. talerOutVolume: Amount; } @@ -1108,7 +1108,7 @@ Monitor interface MonitorWithConversion { type: "with-conversions"; - // How many cashin operations were confirmed by a + // How many cashin operations were confirmed by a // wallet owner. Note: wallet owners // are NOT required to be customers of the libeufin-bank. cashinCount: Integer; @@ -1136,7 +1136,7 @@ Monitor // bank account. talerInCount: Integer; - // Overall volume that has been paid to a Taler + // Overall volume that has been paid to a Taler // exchange by another bank account. talerInVolume: Amount; @@ -1144,14 +1144,14 @@ Monitor // bank account. talerOutCount: Integer; - // Overall volume that has been paid by a Taler + // Overall volume that has been paid by a Taler // exchange to another bank account. talerOutVolume: Amount; } -Taler Bank Integration API --------------------------- +Endpoints for Integrated Sub-APIs +--------------------------------- .. http:any:: /taler-integration/* @@ -1159,8 +1159,6 @@ Taler Bank Integration API :doc:`GNU Taler bank integration API `. This API handles the communication with Taler wallets. -Taler Wire Gateway API ----------------------- .. http:any:: /accounts/$USERNAME/taler-wire-gateway/* @@ -1169,31 +1167,25 @@ Taler Wire Gateway API The endpoints are only available for accounts configured with ``is_taler_exchange=true``. -Taler Revenue API ------------------ .. http:any:: /accounts/$USERNAME/taler-revenue/* All endpoints under this prefix are specified by the :doc:`GNU Taler Revenue API `. -Taler Conversion Info API -------------------------- .. http:any:: /conversion-info/* All endpoints under this prefix are specified by the :doc:`GNU Taler Conversion Info API `. -EBICS Host ----------- - -The Taler bank can be configured to serve bank account transactions and allow -payment initiations via the EBICS protocol. - -This is an optional feature, not all implementations of the API support it. .. http:post:: /ebicshost EBICS base URL. This URL allows clients to make EBICS requests to one of the configured EBICS hosts. + + The Taler bank can be configured to serve bank account transactions and + allow payment initiations via the EBICS protocol. + + This is an optional feature, not all implementations of the API support it. diff --git a/taler-merchant-manual.rst b/taler-merchant-manual.rst index 4959dd48..d2b5a675 100644 --- a/taler-merchant-manual.rst +++ b/taler-merchant-manual.rst @@ -273,7 +273,7 @@ the backend does not have access to the incoming wire transfers of the merchant's bank account. In this case, merchants should manually provide the backend with wire *transfer* data that specifies the *wire transfer subject* and the amount that was received. Given this information, the backend can -detect and report any irregularities that might arise. +detect and report any irregularities that might arise. Rewards ------- @@ -774,7 +774,7 @@ interface create a file ``instance.json`` with an { "id" : "default", - "name": "example.com", + "name": "Example Inc.", "address": { "country" : "zz" }, "auth": { "method" : "external"} , "jurisdiction": { "country" : "zz" }, @@ -855,8 +855,7 @@ automatically import them into the list of wire transfers. Note that setting up a revenue API endpoint will usually require you to first ask your bank for EBICS access and to setup libeufin to provide the revenue API endpoint. The taler-bank used by regional currency setups also provides -a revenue API endpoint. - +a revenue API endpoint at ``$BANK_URL/accounts/$ACCOUNT_NAME/taler-revenue/``. .. _Secure-setup: -- cgit v1.2.3 From 11cca8ce6cf02d2e3261d9842e65f4b3a5f3334b Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Sun, 28 Jan 2024 18:56:36 +0100 Subject: add -T/-p options to man pages --- manpages/taler-merchant-depositcheck.1.rst | 6 ++++++ manpages/taler-merchant-exchange.1.rst | 6 ++++++ manpages/taler-merchant-webhook.1.rst | 6 ++++++ manpages/taler-merchant-wirewatch.1.rst | 10 ++++++++++ 4 files changed, 28 insertions(+) diff --git a/manpages/taler-merchant-depositcheck.1.rst b/manpages/taler-merchant-depositcheck.1.rst index d0af4cda..e243f0d2 100644 --- a/manpages/taler-merchant-depositcheck.1.rst +++ b/manpages/taler-merchant-depositcheck.1.rst @@ -18,6 +18,7 @@ Synopsis [**-h** | **--help**] [**-L** *LOGLEVEL* | **--loglevel=**\ ‌\ *LOGLEVEL*] [**-l** *FILENAME* | **--logfile=**\ ‌\ *FILENAME*] +[**-T** *USEC* | **--timetravel**\ \ *USEC*] [**-t** | **--test**] [**-v** | **--version**] @@ -53,6 +54,11 @@ Its options are as follows: if different processes are used to watch multiple bank accounts (for the same instance or different instances). +**-T** *USEC* \| **--timetravel=**\ \ *USEC* + Modify the system time by *USEC* microseconds. + *USEC* may be prefixed with ``+`` or ``-`` (e.g. ``-T +300``). + This option is intended for debugging/testing only. + **-t** \| **--test** Run in test mode. Only runs until the current list of bank transactions are all imported. diff --git a/manpages/taler-merchant-exchange.1.rst b/manpages/taler-merchant-exchange.1.rst index 6e18028e..de2b571f 100644 --- a/manpages/taler-merchant-exchange.1.rst +++ b/manpages/taler-merchant-exchange.1.rst @@ -17,6 +17,7 @@ Synopsis [**-h** | **--help**] [**-L** *LOGLEVEL* | **--loglevel=**\ ‌\ *LOGLEVEL*] [**-l** *FILENAME* | **--logfile=**\ ‌\ *FILENAME*] +[**-T** *USEC* | **--timetravel**\ \ *USEC*] [**-t** | **--test**] [**-v** | **--version**] @@ -48,6 +49,11 @@ Its options are as follows: **-l** *FILENAME* \| **--logfile=**\ ‌\ *FILENAME* Send logging output to *FILENAME*. +**-T** *USEC* \| **--timetravel=**\ \ *USEC* + Modify the system time by *USEC* microseconds. + *USEC* may be prefixed with ``+`` or ``-`` (e.g. ``-T +300``). + This option is intended for debugging/testing only. + **-t** \| **--test** Run in test mode. Only runs until the current list of bank transactions have all been checked. diff --git a/manpages/taler-merchant-webhook.1.rst b/manpages/taler-merchant-webhook.1.rst index 314c574a..c3a71509 100644 --- a/manpages/taler-merchant-webhook.1.rst +++ b/manpages/taler-merchant-webhook.1.rst @@ -17,6 +17,7 @@ Synopsis [**-h** | **--help**] [**-L** *LOGLEVEL* | **--loglevel=**\ ‌\ *LOGLEVEL*] [**-l** *FILENAME* | **--logfile=**\ ‌\ *FILENAME*] +[**-T** *USEC* | **--timetravel**\ \ *USEC*] [**-t** | **--test**] [**-v** | **--version**] @@ -43,6 +44,11 @@ Its options are as follows: **-l** *FILENAME* \| **--logfile=**\ ‌\ *FILENAME* Send logging output to *FILENAME*. +**-T** *USEC* \| **--timetravel=**\ \ *USEC* + Modify the system time by *USEC* microseconds. + *USEC* may be prefixed with ``+`` or ``-`` (e.g. ``-T +300``). + This option is intended for debugging/testing only. + **-t** \| **--test** Run in test mode. Only runs until there are no more webhooks to be executed. diff --git a/manpages/taler-merchant-wirewatch.1.rst b/manpages/taler-merchant-wirewatch.1.rst index 54daa767..e2f9d1df 100644 --- a/manpages/taler-merchant-wirewatch.1.rst +++ b/manpages/taler-merchant-wirewatch.1.rst @@ -17,6 +17,8 @@ Synopsis [**-h** | **--help**] [**-L** *LOGLEVEL* | **--loglevel=**\ ‌\ *LOGLEVEL*] [**-l** *FILENAME* | **--logfile=**\ ‌\ *FILENAME*] +[**-p** | **--persist**] +[**-T** *USEC* | **--timetravel**\ \ *USEC*] [**-t** | **--test**] [**-v** | **--version**] @@ -44,11 +46,19 @@ Its options are as follows: **-l** *FILENAME* \| **--logfile=**\ ‌\ *FILENAME* Send logging output to *FILENAME*. +**-p** \| **--persist** + Run in persist mode. Does not exit when the account configuration changes. Useful when not running under systemd. + **-s** *SECTION* \| **--section=**\ \ *SECTION* Configuration section to use. Default is taler-merchant-wirewatch. Needed if different processes are used to watch multiple bank accounts (for the same instance or different instances). +**-T** *USEC* \| **--timetravel=**\ \ *USEC* + Modify the system time by *USEC* microseconds. + *USEC* may be prefixed with ``+`` or ``-`` (e.g. ``-T +300``). + This option is intended for debugging/testing only. + **-t** \| **--test** Run in test mode. Only runs until the current list of bank transactions are all imported. -- cgit v1.2.3 From 86bc04b9c4fe93d6bd0d5b4ae7a8ceb8d3706399 Mon Sep 17 00:00:00 2001 From: Florian Dold Date: Tue, 30 Jan 2024 22:56:46 +0100 Subject: expand otp_key docs --- core/api-merchant.rst | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/core/api-merchant.rst b/core/api-merchant.rst index ffaef0a2..d0102240 100644 --- a/core/api-merchant.rst +++ b/core/api-merchant.rst @@ -3137,7 +3137,11 @@ to validate that a customer made a payment. // Human-readable description for the device. otp_device_description: string; - // A base64-encoded key + // A key encoded with RFC 3548 Base32. + // IMPORTANT: This is not using the typical + // Taler base32-crockford encoding. + // Instead it uses the RFC 3548 encoding to + // be compatible with the TOTP standard. otp_key: string; // Algorithm for computing the POS confirmation. -- cgit v1.2.3 From cffab8d7b3315c731ce0102ce084736771fc550d Mon Sep 17 00:00:00 2001 From: Florian Dold Date: Tue, 30 Jan 2024 23:12:21 +0100 Subject: expand otp docs --- core/api-merchant.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/core/api-merchant.rst b/core/api-merchant.rst index d0102240..c6e4535b 100644 --- a/core/api-merchant.rst +++ b/core/api-merchant.rst @@ -3145,6 +3145,9 @@ to validate that a customer made a payment. otp_key: string; // Algorithm for computing the POS confirmation. + // 0: No algorithm (no pos confirmation will be generated) + // 1: Without amounts (typical OTP device) + // 2: With amounts (special-purpose OTP device) otp_algorithm: Integer; // Counter for counter-based OTP devices. -- cgit v1.2.3 From 2b46ac8d738dc39c2199a05a01402d25f3e5f9cf Mon Sep 17 00:00:00 2001 From: Florian Dold Date: Wed, 31 Jan 2024 00:11:48 +0100 Subject: update wallet-core docs --- wallet/wallet-core.md | 428 ++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 378 insertions(+), 50 deletions(-) diff --git a/wallet/wallet-core.md b/wallet/wallet-core.md index 2e34fb4f..449dfbbb 100644 --- a/wallet/wallet-core.md +++ b/wallet/wallet-core.md @@ -15,8 +15,10 @@ This file is auto-generated from [wallet-core](https://git.taler.net/wallet-core * [ConvertWithdrawalAmountOp](#convertwithdrawalamountop) ### Managing Transactions * [GetTransactionsOp](#gettransactionsop) +* [ListAssociatedRefreshesOp](#listassociatedrefreshesop) * [TestingGetSampleTransactionsOp](#testinggetsampletransactionsop) * [GetTransactionByIdOp](#gettransactionbyidop) +* [GetWithdrawalTransactionByUriOp](#getwithdrawaltransactionbyuriop) * [RetryPendingNowOp](#retrypendingnowop) * [DeleteTransactionOp](#deletetransactionop) * [RetryTransactionOp](#retrytransactionop) @@ -37,12 +39,20 @@ This file is auto-generated from [wallet-core](https://git.taler.net/wallet-core * [ConfirmPayOp](#confirmpayop) * [StartRefundQueryForUriOp](#startrefundqueryforuriop) * [StartRefundQueryOp](#startrefundqueryop) +### Global Currency management +* [ListGlobalCurrencyAuditorsOp](#listglobalcurrencyauditorsop) +* [ListGlobalCurrencyExchangesOp](#listglobalcurrencyexchangesop) +* [AddGlobalCurrencyExchangeOp](#addglobalcurrencyexchangeop) +* [AddGlobalCurrencyAuditorOp](#addglobalcurrencyauditorop) +* [RemoveGlobalCurrencyExchangeOp](#removeglobalcurrencyexchangeop) +* [RemoveGlobalCurrencyAuditorOp](#removeglobalcurrencyauditorop) ### Rewards * [PrepareTipOp](#preparetipop) * [AcceptTipOp](#accepttipop) ### Exchange Management * [ListExchangesOp](#listexchangesop) * [ListExchangesForScopedCurrencyOp](#listexchangesforscopedcurrencyop) +* [PrepareWithdrawExchangeOp](#preparewithdrawexchangeop) * [AddExchangeOp](#addexchangeop) * [UpdateExchangeEntryOp](#updateexchangeentryop) * [ListKnownBankAccountsOp](#listknownbankaccountsop) @@ -51,7 +61,9 @@ This file is auto-generated from [wallet-core](https://git.taler.net/wallet-core * [SetExchangeTosAcceptedOp](#setexchangetosacceptedop) * [GetExchangeTosOp](#getexchangetosop) * [GetExchangeDetailedInfoOp](#getexchangedetailedinfoop) -* [ListCurrenciesOp](#listcurrenciesop) +* [GetExchangeEntryByUrlOp](#getexchangeentrybyurlop) +* [GetExchangeResourcesOp](#getexchangeresourcesop) +* [DeleteExchangeOp](#deleteexchangeop) * [GetCurrencySpecificationOp](#getcurrencyspecificationop) ### Deposits * [GenerateDepositGroupTxIdOp](#generatedepositgrouptxidop) @@ -398,6 +410,20 @@ export interface TransactionsRequest { ``` +### ListAssociatedRefreshesOp +```typescript +/** + * List refresh transactions associated with another transaction. + */ +export type ListAssociatedRefreshesOp = { + op: WalletApiOperation.ListAssociatedRefreshes; + request: ListAssociatedRefreshesRequest; + response: ListAssociatedRefreshesResponse; +}; +// ListAssociatedRefreshes = "listAssociatedRefreshes" + +``` + ### TestingGetSampleTransactionsOp ```typescript /** @@ -429,6 +455,23 @@ export interface TransactionByIdRequest { ``` +### GetWithdrawalTransactionByUriOp +```typescript +export type GetWithdrawalTransactionByUriOp = { + op: WalletApiOperation.GetWithdrawalTransactionByUri; + request: WithdrawalTransactionByURIRequest; + response: TransactionWithdrawal | undefined; +}; +// GetWithdrawalTransactionByUri = "getWithdrawalTransactionByUri" + +``` +```typescript +export interface WithdrawalTransactionByURIRequest { + talerWithdrawUri: string; +} + +``` + ### RetryPendingNowOp ```typescript export type RetryPendingNowOp = { @@ -554,7 +597,7 @@ export type ResumeTransactionOp = { export type GetWithdrawalDetailsForAmountOp = { op: WalletApiOperation.GetWithdrawalDetailsForAmount; request: GetWithdrawalDetailsForAmountRequest; - response: ManualWithdrawalDetails; + response: WithdrawalDetailsForAmount; }; // GetWithdrawalDetailsForAmount = "getWithdrawalDetailsForAmount" @@ -568,10 +611,12 @@ export interface GetWithdrawalDetailsForAmountRequest { ``` ```typescript -export interface ManualWithdrawalDetails { +export interface WithdrawalDetailsForAmount { /** * Did the user accept the current version of the exchange's * terms of service? + * + * @deprecated the client should query the exchange entry instead */ tosAccepted: boolean; /** @@ -591,18 +636,22 @@ export interface ManualWithdrawalDetails { /** * Ways to pay the exchange. * - * @deprecated in favor of withdrawalAccountList + * @deprecated in favor of withdrawalAccountsList */ paytoUris: string[]; /** * Ways to pay the exchange, including accounts that require currency conversion. */ - withdrawalAccountList: WithdrawalExchangeAccountDetails[]; + withdrawalAccountsList: WithdrawalExchangeAccountDetails[]; /** * If the exchange supports age-restricted coins it will return * the array of ages. */ ageRestrictionOptions?: number[]; + /** + * Scope info of the currency withdrawn. + */ + scopeInfo: ScopeInfo; } ``` @@ -624,16 +673,28 @@ export type GetWithdrawalDetailsForUriOp = { export interface GetWithdrawalDetailsForUriRequest { talerWithdrawUri: string; restrictAge?: number; + notifyChangeFromPendingTimeoutMs?: number; } ``` ```typescript export interface WithdrawUriInfoResponse { + operationId: string; + status: WithdrawalOperationStatus; + confirmTransferUrl?: string; amount: AmountString; defaultExchangeBaseUrl?: string; possibleExchanges: ExchangeListItem[]; } +``` +```typescript +export type WithdrawalOperationStatus = + | "pending" + | "selected" + | "aborted" + | "confirmed"; + ``` ### AcceptBankIntegratedWithdrawalOp @@ -692,6 +753,8 @@ export interface AcceptManualWithdrawalRequest { export interface AcceptManualWithdrawalResult { /** * Payto URIs that can be used to fund the withdrawal. + * + * @deprecated in favor of withdrawalAccountsList */ exchangePaytoUris: string[]; /** @@ -927,6 +990,124 @@ export interface StartRefundQueryRequest { ``` +### ListGlobalCurrencyAuditorsOp +```typescript +export type ListGlobalCurrencyAuditorsOp = { + op: WalletApiOperation.ListGlobalCurrencyAuditors; + request: EmptyObject; + response: ListGlobalCurrencyAuditorsResponse; +}; +// ListGlobalCurrencyAuditors = "listGlobalCurrencyAuditors" + +``` +```typescript +export interface ListGlobalCurrencyAuditorsResponse { + auditors: { + currency: string; + auditorBaseUrl: string; + auditorPub: string; + }[]; +} + +``` + +### ListGlobalCurrencyExchangesOp +```typescript +export type ListGlobalCurrencyExchangesOp = { + op: WalletApiOperation.ListGlobalCurrencyExchanges; + request: EmptyObject; + response: ListGlobalCurrencyExchangesResponse; +}; +// ListGlobalCurrencyExchanges = "listGlobalCurrencyExchanges" + +``` +```typescript +export interface ListGlobalCurrencyExchangesResponse { + exchanges: { + currency: string; + exchangeBaseUrl: string; + exchangeMasterPub: string; + }[]; +} + +``` + +### AddGlobalCurrencyExchangeOp +```typescript +export type AddGlobalCurrencyExchangeOp = { + op: WalletApiOperation.AddGlobalCurrencyExchange; + request: AddGlobalCurrencyExchangeRequest; + response: EmptyObject; +}; +// AddGlobalCurrencyExchange = "addGlobalCurrencyExchange" + +``` +```typescript +export interface AddGlobalCurrencyExchangeRequest { + currency: string; + exchangeBaseUrl: string; + exchangeMasterPub: string; +} + +``` + +### AddGlobalCurrencyAuditorOp +```typescript +export type AddGlobalCurrencyAuditorOp = { + op: WalletApiOperation.AddGlobalCurrencyAuditor; + request: AddGlobalCurrencyAuditorRequest; + response: EmptyObject; +}; +// AddGlobalCurrencyAuditor = "addGlobalCurrencyAuditor" + +``` +```typescript +export interface AddGlobalCurrencyAuditorRequest { + currency: string; + auditorBaseUrl: string; + auditorPub: string; +} + +``` + +### RemoveGlobalCurrencyExchangeOp +```typescript +export type RemoveGlobalCurrencyExchangeOp = { + op: WalletApiOperation.RemoveGlobalCurrencyExchange; + request: RemoveGlobalCurrencyExchangeRequest; + response: EmptyObject; +}; +// RemoveGlobalCurrencyExchange = "removeGlobalCurrencyExchange" + +``` +```typescript +export interface RemoveGlobalCurrencyExchangeRequest { + currency: string; + exchangeBaseUrl: string; + exchangeMasterPub: string; +} + +``` + +### RemoveGlobalCurrencyAuditorOp +```typescript +export type RemoveGlobalCurrencyAuditorOp = { + op: WalletApiOperation.RemoveGlobalCurrencyAuditor; + request: RemoveGlobalCurrencyAuditorRequest; + response: EmptyObject; +}; +// RemoveGlobalCurrencyAuditor = "removeGlobalCurrencyAuditor" + +``` +```typescript +export interface RemoveGlobalCurrencyAuditorRequest { + currency: string; + auditorBaseUrl: string; + auditorPub: string; +} + +``` + ### PrepareTipOp ```typescript /** @@ -1070,6 +1251,45 @@ export interface ShortExchangeListItem { ``` +### PrepareWithdrawExchangeOp +```typescript +/** + * Prepare for withdrawing via a taler://withdraw-exchange URI. + */ +export type PrepareWithdrawExchangeOp = { + op: WalletApiOperation.PrepareWithdrawExchange; + request: PrepareWithdrawExchangeRequest; + response: PrepareWithdrawExchangeResponse; +}; +// PrepareWithdrawExchange = "prepareWithdrawExchange" + +``` +```typescript +export interface PrepareWithdrawExchangeRequest { + /** + * A taler://withdraw-exchange URI. + */ + talerUri: string; +} + +``` +```typescript +export interface PrepareWithdrawExchangeResponse { + /** + * Base URL of the exchange that already existed + * or was ephemerally added as an exchange entry to + * the wallet. + */ + exchangeBaseUrl: string; + /** + * Amount from the taler://withdraw-exchange URI. + * Only present if specified in the URI. + */ + amount?: AmountString; +} + +``` + ### AddExchangeOp ```typescript /** @@ -1100,6 +1320,7 @@ export type UpdateExchangeEntryOp = { ```typescript export interface UpdateExchangeEntryRequest { exchangeBaseUrl: string; + force?: boolean; } ``` @@ -1264,6 +1485,7 @@ export type GetExchangeTosOp = { export interface GetExchangeTosRequest { exchangeBaseUrl: string; acceptedFormat?: string[]; + acceptLanguage?: string; } ``` @@ -1286,6 +1508,16 @@ export interface GetExchangeTosResult { * Accepted content type */ contentType: string; + /** + * Language of the returned content. + * + * If missing, language is unknown. + */ + contentLanguage: string | undefined; + /** + * Available languages as advertised by the exchange. + */ + tosAvailableLanguages: string[]; tosStatus: ExchangeTosStatus; } @@ -1350,31 +1582,69 @@ export interface FeeDescription { ``` -### ListCurrenciesOp +### GetExchangeEntryByUrlOp ```typescript /** - * List currencies known to the wallet. + * Get the current terms of a service of an exchange. */ -export type ListCurrenciesOp = { - op: WalletApiOperation.ListCurrencies; - request: EmptyObject; - response: WalletCurrencyInfo; +export type GetExchangeEntryByUrlOp = { + op: WalletApiOperation.GetExchangeEntryByUrl; + request: GetExchangeEntryByUrlRequest; + response: GetExchangeEntryByUrlResponse; }; -// ListCurrencies = "listCurrencies" +// GetExchangeEntryByUrl = "getExchangeEntryByUrl" ``` ```typescript -export interface WalletCurrencyInfo { - trustedAuditors: { - currency: string; - auditorPub: string; - auditorBaseUrl: string; - }[]; - trustedExchanges: { - currency: string; - exchangeMasterPub: string; - exchangeBaseUrl: string; - }[]; +export interface GetExchangeEntryByUrlRequest { + exchangeBaseUrl: string; +} + +``` + +### GetExchangeResourcesOp +```typescript +/** + * Get resources associated with an exchange. + */ +export type GetExchangeResourcesOp = { + op: WalletApiOperation.GetExchangeResources; + request: GetExchangeResourcesRequest; + response: GetExchangeResourcesResponse; +}; +// GetExchangeResources = "getExchangeResources" + +``` +```typescript +export interface GetExchangeResourcesRequest { + exchangeBaseUrl: string; +} + +``` +```typescript +export interface GetExchangeResourcesResponse { + hasResources: boolean; +} + +``` + +### DeleteExchangeOp +```typescript +/** + * Get resources associated with an exchange. + */ +export type DeleteExchangeOp = { + op: WalletApiOperation.GetExchangeResources; + request: DeleteExchangeRequest; + response: EmptyObject; +}; +// GetExchangeResources = "getExchangeResources" + +``` +```typescript +export interface DeleteExchangeRequest { + exchangeBaseUrl: string; + purge?: boolean; } ``` @@ -1400,18 +1670,6 @@ export interface GetCurrencySpecificationResponse { currencySpecification: CurrencySpecification; } -``` -```typescript -export interface CurrencySpecification { - name: string; - num_fractional_input_digits: Integer; - num_fractional_normal_digits: Integer; - num_fractional_trailing_zero_digits: Integer; - alt_unit_names: { - [log10: string]: string; - }; -} - ``` ### GenerateDepositGroupTxIdOp @@ -1908,6 +2166,17 @@ export interface CheckPeerPushDebitRequest { export interface CheckPeerPushDebitResponse { amountRaw: AmountString; amountEffective: AmountString; + exchangeBaseUrl: string; + /** + * Maximum expiration date, based on how close the coins + * used for the payment are to expiry. + * + * The value is based on when the wallet would typically + * automatically refresh the coins on its own, leaving enough + * time to get a refund for the push payment and refresh the + * coin. + */ + maxExpirationDate: TalerProtocolTimestamp; } ``` @@ -1965,14 +2234,18 @@ export interface PreparePeerPushCreditRequest { ```typescript export interface PreparePeerPushCreditResponse { contractTerms: PeerContractTerms; + amountRaw: AmountString; + amountEffective: AmountString; + transactionId: string; + exchangeBaseUrl: string; + /** + * @deprecated use transaction ID instead. + */ + peerPushCreditId: string; /** * @deprecated */ amount: AmountString; - amountRaw: AmountString; - amountEffective: AmountString; - peerPushCreditId: string; - transactionId: string; } ``` @@ -2172,8 +2445,8 @@ export type ExportDbOp = { ```typescript export type ImportDbOp = { op: WalletApiOperation.ImportDb; - request: any; - response: any; + request: ImportDbRequest; + response: EmptyObject; }; // ImportDb = "importDb" @@ -3020,14 +3293,26 @@ export interface ForceRefreshRequest { ## Common Declarations ```typescript export interface WalletCoreVersion { + implementationSemver: string; + implementationGitHash: string; /** - * @deprecated + * Wallet-core protocol version supported by this implementation + * of the API ("server" version). */ - hash: string | undefined; version: string; exchange: string; merchant: string; + bankIntegrationApiRange: string; + bankConversionApiRange: string; + corebankApiRange: string; + /** + * @deprecated as bank was split into multiple APIs with separate versioning + */ bank: string; + /** + * @deprecated + */ + hash: string | undefined; /** * @deprecated will be removed */ @@ -3228,6 +3513,7 @@ export declare enum TransactionMinorState { CheckRefund = "check-refund", CreatePurse = "create-purse", DeletePurse = "delete-purse", + RefreshExpired = "refresh-expired", Ready = "ready", Merge = "merge", Repurchase = "repurchase", @@ -3320,18 +3606,50 @@ export interface WithdrawalExchangeAccountDetails { * reserve public key. */ paytoUri: string; + /** + * Status that indicates whether the account can be used + * by the user to send funds for a withdrawal. + * + * ok: account should be shown to the user + * error: account should not be shown to the user, UIs might render the error (in conversionError), + * especially in dev mode. + */ + status: "ok" | "error"; /** * Transfer amount. Might be in a different currency than the requested * amount for withdrawal. * * Redundant with the amount in paytoUri, just included to avoid parsing. + * + * Only included if this account does a currency conversion. + */ + transferAmount?: AmountString; + /** + * Currency specification for the external currency. + * + * Only included if this account requires a currency conversion. */ - transferAmount: AmountString; + currencySpecification?: CurrencySpecification; /** * Further restrictions for sending money to the * exchange. */ creditRestrictions?: AccountRestriction[]; + /** + * Error that happened when attempting to request the conversion rate. + */ + conversionError?: TalerErrorDetail; +} +``` +```typescript +export interface CurrencySpecification { + name: string; + num_fractional_input_digits: Integer; + num_fractional_normal_digits: Integer; + num_fractional_trailing_zero_digits: Integer; + alt_unit_names: { + [log10: string]: string; + }; } ``` ```typescript @@ -3376,6 +3694,7 @@ interface WithdrawalDetailsForTalerBankIntegrationApi { * Is the reserve ready for withdrawal? */ reserveIsReady: boolean; + exchangeCreditAccountDetails?: WithdrawalExchangeAccountDetails[]; } ``` ```typescript @@ -3569,6 +3888,7 @@ export declare enum RefreshReason { AbortPay = "abort-pay", AbortDeposit = "abort-deposit", AbortPeerPushDebit = "abort-peer-push-debit", + AbortPeerPullDebit = "abort-peer-pull-debit", Recoup = "recoup", BackupRestored = "backup-restored", Scheduled = "scheduled", @@ -3632,8 +3952,10 @@ export interface TransactionPeerPullCredit extends TransactionCommon { amountEffective: AmountString; /** * URI to send to the other party. + * + * Only available in the right state. */ - talerUri: string; + talerUri: string | undefined; } ``` ```typescript @@ -3743,6 +4065,9 @@ export interface AbortTransactionRequest { } ``` ```typescript +/** + * Info about an exchange entry in the wallet. + */ export interface ExchangeListItem { exchangeBaseUrl: string; currency: string | undefined; @@ -3751,6 +4076,7 @@ export interface ExchangeListItem { exchangeEntryStatus: ExchangeEntryStatus; exchangeUpdateStatus: ExchangeUpdateStatus; ageRestrictionOptions: number[]; + scopeInfo: ScopeInfo | undefined; /** * Information about the last error that occurred when trying * to update the exchange info. @@ -3775,12 +4101,11 @@ export declare enum ExchangeEntryStatus { ```typescript export declare enum ExchangeUpdateStatus { Initial = "initial", - InitialUpdate = "initial(update)", + InitialUpdate = "initial-update", Suspended = "suspended", - Failed = "failed", - OutdatedUpdate = "outdated(update)", + UnavailableUpdate = "unavailable-update", Ready = "ready", - ReadyUpdate = "ready(update)", + ReadyUpdate = "ready-update", } ``` ```typescript @@ -4062,8 +4387,11 @@ export interface ForcedCoinSel { ```typescript export interface AddExchangeRequest { exchangeBaseUrl: string; - masterPub?: string; + /** + * @deprecated use a separate API call to start a forced exchange update instead + */ forceUpdate?: boolean; + masterPub?: string; } ``` ```typescript -- cgit v1.2.3 From 44190713d5d1e4e2a1e9a80dd3282b481fba76d4 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Wed, 31 Jan 2024 11:17:38 +0100 Subject: address #8175 --- libeufin/create_orders.png | Bin 131092 -> 0 bytes libeufin/enter_instance_details.png | Bin 63262 -> 0 bytes libeufin/instance_iban_config.png | Bin 59170 -> 0 bytes libeufin/merchant_first_login.png | Bin 201140 -> 0 bytes libeufin/no_default_account_yet.png | Bin 54464 -> 0 bytes libeufin/payment_links.png | Bin 227921 -> 0 bytes libeufin/regional-manual.rst | 91 -------------------------- screenshots/create_orders.png | Bin 0 -> 131092 bytes screenshots/enter_instance_details.png | Bin 0 -> 63262 bytes screenshots/instance_iban_config.png | Bin 0 -> 59170 bytes screenshots/merchant_first_login.png | Bin 0 -> 201140 bytes screenshots/no_default_account_yet.png | Bin 0 -> 54464 bytes screenshots/payment_links.png | Bin 0 -> 227921 bytes taler-merchant-manual.rst | 116 +++++++++++++++++++++++++++++++-- 14 files changed, 109 insertions(+), 98 deletions(-) delete mode 100644 libeufin/create_orders.png delete mode 100644 libeufin/enter_instance_details.png delete mode 100644 libeufin/instance_iban_config.png delete mode 100644 libeufin/merchant_first_login.png delete mode 100644 libeufin/no_default_account_yet.png delete mode 100644 libeufin/payment_links.png create mode 100644 screenshots/create_orders.png create mode 100644 screenshots/enter_instance_details.png create mode 100644 screenshots/instance_iban_config.png create mode 100644 screenshots/merchant_first_login.png create mode 100644 screenshots/no_default_account_yet.png create mode 100644 screenshots/payment_links.png diff --git a/libeufin/create_orders.png b/libeufin/create_orders.png deleted file mode 100644 index 74814c72..00000000 Binary files a/libeufin/create_orders.png and /dev/null differ diff --git a/libeufin/enter_instance_details.png b/libeufin/enter_instance_details.png deleted file mode 100644 index f2177091..00000000 Binary files a/libeufin/enter_instance_details.png and /dev/null differ diff --git a/libeufin/instance_iban_config.png b/libeufin/instance_iban_config.png deleted file mode 100644 index 03fa8f36..00000000 Binary files a/libeufin/instance_iban_config.png and /dev/null differ diff --git a/libeufin/merchant_first_login.png b/libeufin/merchant_first_login.png deleted file mode 100644 index 0baa0801..00000000 Binary files a/libeufin/merchant_first_login.png and /dev/null differ diff --git a/libeufin/no_default_account_yet.png b/libeufin/no_default_account_yet.png deleted file mode 100644 index c97c231d..00000000 Binary files a/libeufin/no_default_account_yet.png and /dev/null differ diff --git a/libeufin/payment_links.png b/libeufin/payment_links.png deleted file mode 100644 index 0c58b286..00000000 Binary files a/libeufin/payment_links.png and /dev/null differ diff --git a/libeufin/regional-manual.rst b/libeufin/regional-manual.rst index 97b39a7d..441f6599 100644 --- a/libeufin/regional-manual.rst +++ b/libeufin/regional-manual.rst @@ -218,97 +218,6 @@ Refers to ``nexus-manual.conf`` for more details. -Configuring the merchant -======================== - -In order to setup a shop, you need a merchant backend to run. The guided setup -installs and sets one backend up, but the user is required to complete the shop -configuration via the Web browser. - -One fundamental piece of information are the banking details, to allow merchant -receive payments from the exchange. If you don't have a bank account at the regional -bank, contact the administrator and get one. After being able to login to the new -bank account, you can see your IBAN by clicking on the ``Welcome, $USERNAME`` message -in the profile page. The IBAN is shown under the ``Internal IBAN`` box. - -Next, point your browser to ``$proto://backend.$domain_name/``. You should -be welcomed by the following merchant backoffice page: - -.. image:: merchant_first_login.png - -Such page offers to create a merchant profile: fill any required field (including -your access token) and click to ``confirm``. It should now be possible to associate -the banking details to the profile just created: click to ``Bank account`` at the -left of the page. The following page should be shown: - -.. image:: no_default_account_yet.png - -Click on the blue "+" sign on the top right of the page, and expect the following -page to appear: - -.. image:: enter_instance_details.png - -This tutorial is focused on IBAN, so choose ``iban`` as the account type, and -expect the following page to appear: - -.. image:: instance_iban_config.png - -After providing the details and confirming, the shop is ready to generate orders -and accept payments. - -Make an order -+++++++++++++ - -Click on ``Orders`` at the top left corner of the merchant backoffice page; the -following page should appear - -.. image:: create_orders.png - -After having filled the required fields, the interface should show the following -page with the related links to check the status of the order and let wallets pay -for it. Take note of the link beside ``Payment URI`` (we'll call it ``$payUri``). - -.. image:: payment_links.png - -In order to test the setup, it should be now possible to use the command line wallet -to withdraw Taler coins and spend them to buy the order we just created. - -.. _withdraw-simulation: - -Pay for the order -+++++++++++++++++ - -This section explains how to pay for the order in a scenario where the fiat bank -is simulated. The simulation takes place by crafting ad-hoc XML files as if the -bank would have issued them. Such XML files carry information about incoming payments -to the regional currency master bank account. Finally, the XML files are passed -to LibEuFin nexus via a convenient CLI method. The responsible script for such -simulation is ``withdraw.sh``. - -Run ``./withdraw.sh`` without any arguments. Assuming that you ran the command -as the ``test-user``, after the execution, 5 units of the regional currency should -be found in the CLI wallet owned by ``test-user``. - - -Check it with: - -.. code-block:: console - - $ taler-wallet-cli balance - -If so, call the wallet in the following way to finally pay for the order just created: - -.. code-block:: console - - $ taler-wallet-cli handle-uri $payUri - -.. note:: - - Reset the state before going to production, as it impacts the way nexus - asks records to the bank. In particular, delete: any database and the - files ``config/user.conf`` and ``config/internal.conf``, and finally run - ``./main.sh`` again. - Exchange-wallet integration =========================== diff --git a/screenshots/create_orders.png b/screenshots/create_orders.png new file mode 100644 index 00000000..74814c72 Binary files /dev/null and b/screenshots/create_orders.png differ diff --git a/screenshots/enter_instance_details.png b/screenshots/enter_instance_details.png new file mode 100644 index 00000000..f2177091 Binary files /dev/null and b/screenshots/enter_instance_details.png differ diff --git a/screenshots/instance_iban_config.png b/screenshots/instance_iban_config.png new file mode 100644 index 00000000..03fa8f36 Binary files /dev/null and b/screenshots/instance_iban_config.png differ diff --git a/screenshots/merchant_first_login.png b/screenshots/merchant_first_login.png new file mode 100644 index 00000000..0baa0801 Binary files /dev/null and b/screenshots/merchant_first_login.png differ diff --git a/screenshots/no_default_account_yet.png b/screenshots/no_default_account_yet.png new file mode 100644 index 00000000..c97c231d Binary files /dev/null and b/screenshots/no_default_account_yet.png differ diff --git a/screenshots/payment_links.png b/screenshots/payment_links.png new file mode 100644 index 00000000..0c58b286 Binary files /dev/null and b/screenshots/payment_links.png differ diff --git a/taler-merchant-manual.rst b/taler-merchant-manual.rst index d2b5a675..2d674014 100644 --- a/taler-merchant-manual.rst +++ b/taler-merchant-manual.rst @@ -648,7 +648,7 @@ The following is an example for a complete backend configuration: DATABASE = postgres [merchantdb-postgres] - CONFIG = postgres:///donations + CONFIG = postgres:///taler-merchant [merchant-exchange-kudos] EXCHANGE_BASE_URL = https://exchange.demo.taler.net/ @@ -681,6 +681,8 @@ merchant backend as ``$USER`` using $ taler-merchant-httpd & $ taler-merchant-webhook & $ taler-merchant-wirewatch & + $ taler-merchant-depositcheck & + $ taler-merchant-exchange & You only need to run ``taler-merchant-webhook`` if one of the instances is configured to trigger web hooks. Similarly, ``taler-merchant-wirewatch`` is @@ -698,8 +700,8 @@ how to start and stop daemons. When using the Debian/Ubuntu packages, the systemd configuration will already exist. You only need to enable and start the service - using ``systemctl enable taler-merchant-httpd`` and - ``systemctl start taler-merchant-httpd``. Additionally, you should + using ``systemctl enable taler-merchant.target`` and + ``systemctl start taler-merchant.target``. Additionally, you should review the ``/etc/apache2/sites-available/taler-merchant.conf`` or ``/etc/nginx/sites-available/taler-merchant`` (these files contain additional instructions to follow), symlink it to @@ -761,8 +763,40 @@ times, once for each instance. :ref:`reverse proxy `. -Setup without the Web interface -------------------------------- + +Instance setup with the SPA +--------------------------- + +In order to setup a shop, you need a merchant backend to run. The guided +setup installs and sets one backend up, but the user is required to complete +the shop configuration via the Web browser. + +One fundamental piece of information are the banking details, to allow merchant +receive payments from the exchange. If you don't have a bank account at the regional +bank, contact the administrator and get one. After being able to login to the new +bank account, you can see your IBAN by clicking on the ``Welcome, $USERNAME`` message +in the profile page. The IBAN is shown under the ``Internal IBAN`` box. + +Next, point your browser to ``$proto://backend.$domain_name/``. You should +be welcomed by the following merchant backoffice page: + +.. image:: screenshots/merchant_first_login.png + +Such page offers to create a merchant profile: fill any required field (including +your access token) and click to ``confirm``. It should now be possible to associate +the banking details to the profile just created: click to ``Bank account`` at the +left of the page. The following page should be shown: + +.. image:: screenshots/no_default_account_yet.png + +Click on the blue "+" sign on the top right of the page, and expect the following +page to appear: + +.. image:: enter_instance_details.png + + +Instance setup without the Web interface +---------------------------------------- Instances can be created by POSTing a request to ``/management/instances`` without using the Web interface. This could be useful if you want to create @@ -806,8 +840,8 @@ or purge (deleting all associated data) instances exist as well and are document in the :ref:`Merchant Backend API documentation `. -Accounts --------- +Instance account setup +====================== Before you can use an instance productively, you need to configure one or more bank accounts. These bank accounts will be provided to the Taler exchange @@ -826,6 +860,18 @@ The simplest way to configure an account is to use the Web interface which has specific forms for different wire methods. Specifying the revenue gateway with username and password is optional and discussed below. +This tutorial is focused on IBAN, so choose ``iban`` as the account type, and +expect the following page to appear: + +.. image:: screenshots/instance_iban_config.png + +After providing the details and confirming, the shop is ready to generate orders +and accept payments. + + + + + Detecting Settlement: Manually Adding Transfers ----------------------------------------------- @@ -858,6 +904,62 @@ API endpoint. The taler-bank used by regional currency setups also provides a revenue API endpoint at ``$BANK_URL/accounts/$ACCOUNT_NAME/taler-revenue/``. +Make an order +============= + +Click on ``Orders`` at the top left corner of the merchant backoffice page; the +following page should appear + +.. image:: screenshots/create_orders.png + +After having filled the required fields, the interface should show the following +page with the related links to check the status of the order and let wallets pay +for it. Take note of the link beside ``Payment URI`` (we'll call it ``$payUri``). + +.. image:: screenshots/payment_links.png + +In order to test the setup, it should be now possible to use the command line wallet +to withdraw Taler coins and spend them to buy the order we just created. + + +.. _withdraw-simulation: + +Pay for the order +================= + +This section explains how to pay for the order in a scenario where the fiat bank +is simulated. The simulation takes place by crafting ad-hoc XML files as if the +bank would have issued them. Such XML files carry information about incoming payments +to the regional currency master bank account. Finally, the XML files are passed +to LibEuFin nexus via a convenient CLI method. The responsible script for such +simulation is ``withdraw.sh``. + +Run ``./withdraw.sh`` without any arguments. Assuming that you ran the command +as the ``test-user``, after the execution, 5 units of the regional currency should +be found in the CLI wallet owned by ``test-user``. + + +Check it with: + +.. code-block:: console + + $ taler-wallet-cli balance + +If so, call the wallet in the following way to finally pay for the order just created: + +.. code-block:: console + + $ taler-wallet-cli handle-uri $TALER_PAY_URI + +.. note:: + + Reset the state before going to production, as it impacts the way nexus + asks records to the bank. In particular, delete: any database and the + files ``config/user.conf`` and ``config/internal.conf``, and finally run + ``./main.sh`` again. + + + .. _Secure-setup: Secure setup -- cgit v1.2.3 From 61a7c4af65f06d9f97a3247c4f0244c7a5b952dd Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Wed, 31 Jan 2024 14:39:24 +0100 Subject: expand terminology section --- taler-merchant-manual.rst | 73 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 73 insertions(+) diff --git a/taler-merchant-manual.rst b/taler-merchant-manual.rst index 2d674014..072f4ad7 100644 --- a/taler-merchant-manual.rst +++ b/taler-merchant-manual.rst @@ -260,6 +260,61 @@ After the *legal expiration* (by default: a decade), contract information is deleted when running the garbage collector using ``taler-merchant-dbinit``. +.. _template: + +Templates +--------- + +.. index:: Template + +Usually, a merchant must use an authenticated endpoint to create an order and +then share the link to the order with a wallet. Templates are a mechanism that +allows wallets to create their own orders directly, using a public endpoint. +The template fixes some properties of the contracts created from it, while +other details may be left for the customer to provide. Templates are useful +in cases where the point-of-sale of a merchant is offline (and thus cannot +setup an order), or even in cases where a simple static QR code is desired to +accept payments or donations. + +When generating a template, the "summary" text of the contract and the +"amount" to be paid by the customer can be fixed or left for the customer to +specify. If the customer is expected to provide either or both of these +values, the template link (or QR code) can specify a default value. For +example, a cafeteria with a fixed price lunch may use a "lunch" template with +both values fixed to the lunch price and the "lunch" product, a bakery might +fix the summary to "baked goods" but allow the customer to enter the amount +based on the total price of the items being bought, and a charity may allow +donating an arbitrary amount and summary message while also suggesting default +values. + +If an offline merchant wants to confirm that a customer did actually pay the +agreed amount using an order derived from a template, they can associate an +OTP device with the template. + + +.. _otp-device: + +OTP Devices +----------- + +.. index:: OTP +.. index:: TOTP + +A One-Time-Password (OTP) generator is a device or application that generates +a 4 to 8 digit code typically used for authentication. The widely used TOTP +standard is described in `RFC 6238 `_. +For GNU Taler merchant backends, OTP devices are used as a way to assure a +merchant without network connectivity that a customer made a digital +payment. The idea is described in depth in our `SUERF Policy Brief +`_. +To use this method, a merchant must configure the OTP device's shared secret +in the merchant backend, and then associate the OTP device with a +:ref:`template`. Once the customer has paid, they are given a list of OTP +codes which must be shown to the merchant who can check that at least one of +the codes matches their OTP device, proving that the customer made the +payment. + + Transfers --------- @@ -275,6 +330,9 @@ backend with wire *transfer* data that specifies the *wire transfer subject* and the amount that was received. Given this information, the backend can detect and report any irregularities that might arise. + +.. _rewards: + Rewards ------- @@ -296,6 +354,8 @@ the reward. if they see compliance issues). In this case, the reward feature will not be available. +.. _merchant-reserves: + Reserves -------- @@ -315,6 +375,19 @@ While exchange APIs exists to (1) explicitly *open* a reserve to prevent it from being automatically closed and to (2) explicitly *close* a reserve at any time, the current merchant backend does not make use of these APIs. +Webhooks +-------- + +.. index:: webhook + +A webhook is a pre-defined HTTP request that the GNU Taler merchant backend +will make upon certain events, such as an order being paid or refunded. When +the configured event happens, the merchant backend will make an HTTP request +to the endpoint configured in the webhook configuration, possibly sending +selected data about the event to the respective Web service. Webhooks can be +used to trigger additional business logic outside of the GNU Taler merchant +backend. + Installation ============ -- cgit v1.2.3 From 60b071096b1b26da6b2aa5810ae906a27467bcce Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Wed, 31 Jan 2024 21:16:08 +0100 Subject: major updates to taler-merchant-manual --- design-documents/039-taler-browser-integration.rst | 10 +- libeufin/bank-manual.rst | 21 ++ libeufin/index.rst | 20 ++ libeufin/nexus-manual.rst | 21 ++ libeufin/regional-manual.rst | 35 ++- taler-merchant-manual.rst | 245 ++++++++++----------- taler-merchant-pos-terminal.rst | 6 +- taler-wallet.rst | 42 ++++ 8 files changed, 257 insertions(+), 143 deletions(-) diff --git a/design-documents/039-taler-browser-integration.rst b/design-documents/039-taler-browser-integration.rst index b7cd346c..980f3f25 100644 --- a/design-documents/039-taler-browser-integration.rst +++ b/design-documents/039-taler-browser-integration.rst @@ -112,7 +112,7 @@ To enable additional communication features between a website and the GNU Taler include the following meta tag: .. code:: - + where ``$features`` is a comma-separated list of features. @@ -129,8 +129,8 @@ Caveats and Comments ^^^^^^^^^^^^^^^^^^^^ * Anchor tag hijacking does not work in all use-cases, for example when a navigation -to a ``taler://`` URI is initiated programmatically or by pasting -the URI in the browser's address bar. + to a ``taler://`` URI is initiated programmatically or by pasting + the URI in the browser's address bar. * The ``window.taler`` API injection may break some websites (https://github.com/brave/browser-laptop/issues/13711). @@ -148,8 +148,8 @@ the URI in the browser's address bar. * The execution of the websites onclick handler if no Taler Wallet webextension is installed * Triggering the webextension wallet to handle the ``taler://`` URI. -* Future ``window.taler`` injection should be based on user preferences on - sites where the user has explicitly accepted to disclose that is owner of a +* Future ``window.taler`` injection should be based on user preferences on + sites where the user has explicitly accepted to disclose that is owner of a Taler wallet. Other Alternatives diff --git a/libeufin/bank-manual.rst b/libeufin/bank-manual.rst index af977492..a61c7429 100644 --- a/libeufin/bank-manual.rst +++ b/libeufin/bank-manual.rst @@ -1,5 +1,26 @@ +.. + This file is part of GNU TALER. + Copyright (C) 2014-2023 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 + + @author Florian Dold + @author Marcello Stanisci + @author Christian Grothoff + .. target audience: operator, developer +.. _libeufin-bank: + Bank Setup Manual ################# diff --git a/libeufin/index.rst b/libeufin/index.rst index 042388dc..5e4ca054 100644 --- a/libeufin/index.rst +++ b/libeufin/index.rst @@ -1,3 +1,23 @@ +.. + This file is part of GNU TALER. + Copyright (C) 2014-2023 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 + + @author Florian Dold + @author Marcello Stanisci + @author Christian Grothoff + + LibEuFin ######## diff --git a/libeufin/nexus-manual.rst b/libeufin/nexus-manual.rst index 0fab068b..c4ed2cbc 100644 --- a/libeufin/nexus-manual.rst +++ b/libeufin/nexus-manual.rst @@ -1,5 +1,26 @@ +.. + This file is part of GNU TALER. + Copyright (C) 2014-2023 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 + + @author Florian Dold + @author Marcello Stanisci + @author Christian Grothoff + .. target audience: operator, developer +.. _libeufin-nexus: + Nexus Manual ############ diff --git a/libeufin/regional-manual.rst b/libeufin/regional-manual.rst index 441f6599..ca355a49 100644 --- a/libeufin/regional-manual.rst +++ b/libeufin/regional-manual.rst @@ -1,3 +1,23 @@ +.. + This file is part of GNU TALER. + Copyright (C) 2014-2023 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 + + @author Florian Dold + @author Marcello Stanisci + @author Christian Grothoff + + .. target audience: operator Regional Currency Setup Manual @@ -116,9 +136,10 @@ desired setup, in particular: IP address of the system on which you are running the installation (before you execute the installer)). -The information you entered as well as the generated bank admin password will be stored in a file called ``config/user.conf``. -Should you run the script in the future (for example, to upgrade the installation), -you will not be asked these questions a second time. +The information you entered as well as the generated bank admin password will +be stored in a file called ``config/user.conf``. Should you run the script in +the future (for example, to upgrade the installation), you will not be asked +these questions a second time. After answering all of the questions, the actual installation will start. The scripts will download and configure various packages, which may take some time. @@ -167,14 +188,14 @@ Enable regional currency conversion =================================== Prerequisites -------------- ++++++++++++++ This step assumes that you already have a working regional currency bank and have successfully connected to a backing fiat bank account. Follow the instructions from :ref:`EBICS setup `. Configuration -------------- ++++++++++++++ Then you have to enable conversion and at least one TAN channel for cashout in the configuration file. @@ -204,13 +225,13 @@ Then the following command would start the server with conversion API enabled : libeufin-bank serve -c $config_file Web-based Configuration ------------------------ ++++++++++++++++++++++++ Now you should be able to setup conversion rates and ``admin`` debt limit though the Web interface of the bank as the ``admin`` user. Conversion ON! --------------- +++++++++++++++ The last step is to run Nexus to import incoming bank transactions (cash in) and to trigger outgoing bank transactions (cash out). diff --git a/taler-merchant-manual.rst b/taler-merchant-manual.rst index 072f4ad7..dcf518e7 100644 --- a/taler-merchant-manual.rst +++ b/taler-merchant-manual.rst @@ -396,6 +396,28 @@ This chapter describes how to install the GNU Taler merchant backend. .. _Generic-instructions: +Installing the GNU Taler binary packages on Debian +-------------------------------------------------- + +.. include:: frags/installing-debian.rst + +.. include:: frags/apt-install-taler-merchant.rst + + +Installing the GNU Taler binary packages on Trisquel +---------------------------------------------------- + +.. include:: frags/installing-trisquel.rst + + +Installing the GNU Taler binary packages on Ubuntu +-------------------------------------------------- + +.. include:: frags/installing-ubuntu.rst + +.. include:: frags/apt-install-taler-merchant.rst + + Installing from source ---------------------- @@ -433,30 +455,9 @@ libraries! .. include:: frags/install-before-check.rst -Installing the GNU Taler binary packages on Debian --------------------------------------------------- - -.. include:: frags/installing-debian.rst - -.. include:: frags/apt-install-taler-merchant.rst - - -Installing the GNU Taler binary packages on Trisquel ----------------------------------------------------- - -.. include:: frags/installing-trisquel.rst - -Installing the GNU Taler binary packages on Ubuntu --------------------------------------------------- - -.. include:: frags/installing-ubuntu.rst - -.. include:: frags/apt-install-taler-merchant.rst - - -How to configure the merchant’s backend -======================================= +How to configure the merchant backend +===================================== .. index:: taler.conf @@ -747,7 +748,7 @@ Launching the backend .. index:: taler-merchant-httpd Assuming you have configured everything correctly, you can launch the -merchant backend as ``$USER`` using +merchant backend as ``$USER`` using (to provide a trivial example): .. code-block:: console @@ -757,12 +758,7 @@ merchant backend as ``$USER`` using $ taler-merchant-depositcheck & $ taler-merchant-exchange & -You only need to run ``taler-merchant-webhook`` if one of the instances is -configured to trigger web hooks. Similarly, ``taler-merchant-wirewatch`` is -only required if instances have accounts configured with automatic import of -wire transfers via a bank wire gateway. - -To ensure these processes runs always in the background and also after +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 operating system to launch the process. You should also periodically re-start these services to prevent them from exhausing the memory utilization of the @@ -782,7 +778,6 @@ how to start and stop daemons. should be able to visit the merchant backend at the respective HTTP(S) endpoint. - If everything worked as expected, the command .. code-block:: console @@ -794,7 +789,7 @@ 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 set an access token to be provided in an ``Authorize: 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. + * Use the ``--auth=$TOKEN`` command-line option to **taler-merchant-httpd** to set an access token to be provided in an ``Authorize: 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! @@ -809,15 +804,14 @@ and use TLS for improved network privacy, see :ref:`Secure setup ` Instance setup ============== -First of all, we recommend the use of the single-page administration -application (SPA) that is served by default at the base URL of the merchant -backend. You can use it to perform all steps described in this section (and -more!), using a simple Web interface instead of the ``wget`` commands given -below. +We recommend the use of the single-page administration application (SPA) that +is served by default at the base URL of the merchant backend. You can use it +to perform all steps described in this section (and more!), using a simple Web +interface. Alternatively, you can also use the ``wget`` commands given below. -Regardless of which tool you use, the first step for using the backend +Regardless of which approach you use, the first step for using the backend involves the creation of a ``default`` instance. The ``default`` instance can -also create / delete / configure other instances, similar to the ``root`` +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). @@ -836,36 +830,29 @@ times, once for each instance. :ref:`reverse proxy `. - Instance setup with the SPA --------------------------- -In order to setup a shop, you need a merchant backend to run. The guided -setup installs and sets one backend up, but the user is required to complete -the shop configuration via the Web browser. - -One fundamental piece of information are the banking details, to allow merchant -receive payments from the exchange. If you don't have a bank account at the regional -bank, contact the administrator and get one. After being able to login to the new -bank account, you can see your IBAN by clicking on the ``Welcome, $USERNAME`` message -in the profile page. The IBAN is shown under the ``Internal IBAN`` box. +In order to setup an instance, you need the merchant backend to already be +running, and you must either have the credentials for the "default" instance, +or no instance must be configured at all yet. -Next, point your browser to ``$proto://backend.$domain_name/``. You should -be welcomed by the following merchant backoffice page: +To start, point your browser to ``$PROTO://backend.$DOMAIN_NAME/``, replacing +"$PROTO" with "https" or (rarely) "http" and "$DOMAIN_NAME" with your +organizations DNS domain or subdomain. -.. image:: screenshots/merchant_first_login.png +.. note:: -Such page offers to create a merchant profile: fill any required field (including -your access token) and click to ``confirm``. It should now be possible to associate -the banking details to the profile just created: click to ``Bank account`` at the -left of the page. The following page should be shown: + The label "backend" here is also just a suggestion, your administrator + can in principle choose any name. -.. image:: screenshots/no_default_account_yet.png +You should be welcomed by the following merchant backoffice page: -Click on the blue "+" sign on the top right of the page, and expect the following -page to appear: +.. image:: screenshots/merchant_first_login.png -.. image:: enter_instance_details.png +After supplying the required fields, primarily the name of your organization +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 setup without the Web interface @@ -912,6 +899,7 @@ Endpoints to modify (reconfigure), permanently disable (while keeping the data) or purge (deleting all associated data) instances exist as well and are documented in the :ref:`Merchant Backend API documentation `. +.. _instance-account-setup: Instance account setup ====================== @@ -922,29 +910,48 @@ operator to tell it where to wire the income from your sales. Every bank account has an associated *wire method* which determines how an exchange can transfer the funds. The most commonly supported wire method is *iban*, which implies that bank accounts are identified by IBAN numbers and wire transfers -are to be executed between IBAN accounts. +are to be executed between IBAN accounts. For regional currency setups, the +wire method could also be *x-taler-bank*. + +.. note:: + + When using a regional currency, you need to first create a bank account at + the regional bank. You may need to contact the respective administrator who + can set one up. After being able to login to the new bank account, you can + see your bank account number by clicking on the ``Welcome, $USERNAME`` + message in the profile page. Next to the bank account number, you can find + a convenient button to copy the number to the clipboard. Not every exchange will support every *wire method*, and if you do not add a bank account with a wire method that is supported by a particular exchange, then you will not be able to receive payments via that exchange even if you configured the merchant backend to trust that exchange. -The simplest way to configure an account is to use the Web interface which -has specific forms for different wire methods. Specifying the revenue gateway -with username and password is optional and discussed below. +The simplest way to configure an account is to use the Web interface which has +specific forms for different wire methods. First, select ``Bank account`` at +the left of the page. The following page should be shown: + +.. image:: screenshots/no_default_account_yet.png + +Click on the blue "+" sign on the top right of the page to add a new +bank account. The following page should appear: -This tutorial is focused on IBAN, so choose ``iban`` as the account type, and -expect the following page to appear: +.. image:: screenshots/enter_instance_details.png + +First, you should select the wire method, after which the dialog will show you +additional fields specific to the wire method. For example, if youchoose +``iban`` as the account type, the following page should appear: .. image:: screenshots/instance_iban_config.png +Specifying the revenue gateway with username and password is optional and +discussed in section :ref:`automatic-settlement-data-import` below. + After providing the details and confirming, the shop is ready to generate orders and accept payments. - - Detecting Settlement: Manually Adding Transfers ----------------------------------------------- @@ -962,75 +969,54 @@ information, the merchant backend will inquire with the exchange which individual payments were aggregated, check that the total amount is correct, and will then flag the respective contracts as wired. +You can manually enter wire transfers under ``Transfers``. However, this is +tedious, and so if your banking setup supports it, we highly recommend +using the automatic settlement data import. + +.. _automatic-settlement-data-import: + Automatic Settlement Data Import -------------------------------- -To automatically import settlement data, you can provide the merchant backend -with the address and access credentials of a Taler revenue API for each bank -account of an instance. The revenue API endpoint will allow the merchant -backend to observe all incoming wire transfers into your bank account and -automatically import them into the list of wire transfers. +To automatically import settlement data, you need to provide the merchant +backend with the address and access credentials of a +:ref:`taler-bank-merchant-http-api` for each bank account of an instance. The +revenue API endpoint will allow the merchant backend to obtain a list of all +incoming wire transfers into your bank account and automatically import them +into the list of confirmed wire transfers. Note that setting up a revenue API endpoint will usually require you to first -ask your bank for EBICS access and to setup libeufin to provide the revenue -API endpoint. The taler-bank used by regional currency setups also provides -a revenue API endpoint at ``$BANK_URL/accounts/$ACCOUNT_NAME/taler-revenue/``. +ask your bank for EBICS access and to set up :ref:`libeufin-nexus` to provide +the revenue API endpoint. The :ref:`libeufin-bank` used by regional currency +setups also provides a revenue API endpoint at +``$BANK_URL/accounts/$ACCOUNT_NAME/taler-revenue/``. Thus, when using a +regional currency setup, simply use the ``$BANK_URL`` of your bank and specify +your bank login name and password in the :ref:`instance-account-setup` dialog. -Make an order -============= +Manually creating an order using the SPA +======================================== Click on ``Orders`` at the top left corner of the merchant backoffice page; the following page should appear .. image:: screenshots/create_orders.png -After having filled the required fields, the interface should show the following -page with the related links to check the status of the order and let wallets pay -for it. Take note of the link beside ``Payment URI`` (we'll call it ``$payUri``). +After having filled the required fields, the interface should show the +following page with the related links to check the status of the order and let +wallets pay for it. .. image:: screenshots/payment_links.png In order to test the setup, it should be now possible to use the command line wallet -to withdraw Taler coins and spend them to buy the order we just created. - - -.. _withdraw-simulation: - -Pay for the order -================= - -This section explains how to pay for the order in a scenario where the fiat bank -is simulated. The simulation takes place by crafting ad-hoc XML files as if the -bank would have issued them. Such XML files carry information about incoming payments -to the regional currency master bank account. Finally, the XML files are passed -to LibEuFin nexus via a convenient CLI method. The responsible script for such -simulation is ``withdraw.sh``. - -Run ``./withdraw.sh`` without any arguments. Assuming that you ran the command -as the ``test-user``, after the execution, 5 units of the regional currency should -be found in the CLI wallet owned by ``test-user``. - - -Check it with: - -.. code-block:: console - - $ taler-wallet-cli balance - -If so, call the wallet in the following way to finally pay for the order just created: - -.. code-block:: console - - $ taler-wallet-cli handle-uri $TALER_PAY_URI - -.. note:: - - Reset the state before going to production, as it impacts the way nexus - asks records to the bank. In particular, delete: any database and the - files ``config/user.conf`` and ``config/internal.conf``, and finally run - ``./main.sh`` again. +to withdraw Taler coins and spend them to pay for the order we just created. +In practice, you will rarely if ever setup orders manually like this. Instead, +a `GNU Taler e-commerce front-end +`_ or the +:ref:`taler-merchant-pos-app` will do this on-demand. Here, you will only need +to provide the respective front-ends with the URL of your instance +(e.g. ``https://backend.$DOMAIN/instances/$NAME``) and your access token. .. _Secure-setup: @@ -1041,11 +1027,12 @@ Secure setup .. index:: security .. index:: TLS -The Taler backend does not include even the most basic forms of access control -or transport layer security. Thus, production setups **must** deploy the -Taler backend behind an HTTP(S) server that acts as a *reverse proxy*, -performs TLS termination and authentication and then forwards requests to the -backend. +The Taler backend is deliberately simple in terms of support for access +control or transport layer security (TLS). Thus, production setups **must** +deploy the Taler backend behind an HTTP(S) server that acts as a *reverse +proxy*, performs TLS termination and authentication and then forwards requests +to the backend. + Using UNIX domain sockets ------------------------- @@ -1305,6 +1292,7 @@ runtime by the setup logic provided by ``taler-unified-setup.sh``. See :ref:`Taler Exchange Manual ` for how to use ``taler-unified-setup.sh`` to setup the system and in particular on how to specify the bank to be used. + Running taler-merchant-benchmark ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -1341,8 +1329,10 @@ second gives the chance to leave some payments unaggregated, and also to use merchant instances other than the default (which is, actually, the one used by default by the tool). -Note: the ability of driving the aggregation policy is useful for testing -the back-office facility. +.. note:: + + The ability to drive the aggregation policy is useful for testing + the back-office facility. Any subcommand is also equipped with the canonical ``--help`` option, so feel free to issue the following command in order to explore all the @@ -1369,9 +1359,6 @@ option: - - - Temporarily Abandoned Features ============================== diff --git a/taler-merchant-pos-terminal.rst b/taler-merchant-pos-terminal.rst index b5833369..0cca1d52 100644 --- a/taler-merchant-pos-terminal.rst +++ b/taler-merchant-pos-terminal.rst @@ -15,8 +15,10 @@ @author Torsten Grote -GNU Taler Merchant POS Manual -############################# +.. _taler-merchant-pos-app: + +GNU Taler Merchant POS App +########################## The GNU Taler merchant POS (point of sale) terminal allows sellers to diff --git a/taler-wallet.rst b/taler-wallet.rst index 04a77e7d..3ea1dbea 100644 --- a/taler-wallet.rst +++ b/taler-wallet.rst @@ -207,6 +207,48 @@ is functional: # The "deposit group id" can be found in the output of the transactions list. $ taler-wallet-cli deposit track $DEPOSIT_GROUP_ID +.. _withdraw-simulation: + + +Paying for an order +=================== + +.. note:: + + This section is in dire need for some editing... + +This section explains how to pay for an order in a scenario where the fiat bank +is simulated. The simulation takes place by crafting ad-hoc XML files as if the +bank would have issued them. Such XML files carry information about incoming payments +to the regional currency master bank account. Finally, the XML files are passed +to LibEuFin nexus via a convenient CLI method. The responsible script for such +simulation is ``withdraw.sh``. + +Run ``./withdraw.sh`` without any arguments. Assuming that you ran the command +as the ``test-user``, after the execution, 5 units of the regional currency should +be found in the CLI wallet owned by ``test-user``. + + +Check it with: + +.. code-block:: console + + $ taler-wallet-cli balance + +If so, call the wallet in the following way to finally pay for the order just created: + +.. code-block:: console + + $ taler-wallet-cli handle-uri "$TALER_PAY_URI" + +.. note:: + + Reset the state before going to production, as it impacts the way nexus + asks records to the bank. In particular, delete: any database and the + files ``config/user.conf`` and ``config/internal.conf``, and finally run + ``./main.sh`` again. + + -- cgit v1.2.3 From 794201a4f098e778cb9dd48ac6e3bc5d17844d0d Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Thu, 1 Feb 2024 23:20:42 +0100 Subject: allow strings to be used in TOTP protocol specs; bump protocol to v7 --- core/api-merchant.rst | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/core/api-merchant.rst b/core/api-merchant.rst index c6e4535b..3bce5414 100644 --- a/core/api-merchant.rst +++ b/core/api-merchant.rst @@ -3145,10 +3145,11 @@ to validate that a customer made a payment. otp_key: string; // Algorithm for computing the POS confirmation. - // 0: No algorithm (no pos confirmation will be generated) - // 1: Without amounts (typical OTP device) - // 2: With amounts (special-purpose OTP device) - otp_algorithm: Integer; + // "NONE" or 0: No algorithm (no pos confirmation will be generated) + // "TOTP_WITHOUT_PRICE" or 1: Without amounts (typical OTP device) + // "TOTP_WITH_PRICE" or 2: With amounts (special-purpose OTP device) + // The "String" variants are supported @since protocol v7. + otp_algorithm: Integer | String; // Counter for counter-based OTP devices. otp_ctr?: Integer; -- cgit v1.2.3 From b05de7c2269594fa60e9ffe20b2303581d90d52d Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Fri, 2 Feb 2024 13:13:07 +0100 Subject: work on nexus-manual --- frags/ebics-setup.rst | 52 --------------- libeufin/nexus-manual.rst | 149 ++++++++++++++++++++++++++++++++----------- libeufin/regional-manual.rst | 21 ++---- 3 files changed, 117 insertions(+), 105 deletions(-) delete mode 100644 frags/ebics-setup.rst diff --git a/frags/ebics-setup.rst b/frags/ebics-setup.rst deleted file mode 100644 index 8d822e8e..00000000 --- a/frags/ebics-setup.rst +++ /dev/null @@ -1,52 +0,0 @@ -When you sign up for an EBICS-enabled bank account, the bank will provide you -with various credentials. Those must be provided in the -``/etc/libeufin/libeufin-nexus.conf`` configuration file together with the -name of the *fiat* currency. - -The following snippet shows the mandatory configuration values: - -.. _core-config: - -.. code-block:: console - - [nexus-ebics] - CURRENCY = CHF - - # Bank - HOST_BASE_URL = http://bank.example.com/ - BANK_DIALECT = postfinance - - # EBICS IDs - HOST_ID = mybank - USER_ID = myuser - PARTNER_ID = myorg - - # Account information - IBAN = myiban - BIC = mybic - NAME = myname - -.. note:: - Refer to the manpage ``libeufin-nexus.conf(5)`` - for the full array of configuration values. - -.. note:: - If you want to use existing client keys, copy the JSON file to the configured path ``CLIENT_PRIVATE_KEYS_FILE`` (``/var/lib/libeufin-nexus/client-ebics-keys.json`` by default) before running the commands. - -Assuming that the configuration file exists at ``$config_file``, the following command would start the EBICS setup process. - -.. code-block:: console - - libeufin-nexus ebics-setup -c $config_file - -If the previous command failed when running EBICS INI with an error code ``EBICS_INVALID_USER_STATE``, you need to confirm your keys to your bank to activate your account. - -To that purpose, the previous run should have left a PDF document that you can print, sign and send to the bank. Look for the message that looks like ``PDF file with keys hex encoding created at: /tmp/libeufin-nexus-keys-$timestamp.pdf``. - -Once the bank has received and approved this printed documents, run the same command again to download and accept the bank keys. - -.. code-block:: console - - libeufin-nexus ebics-setup -c $config_file - -The setup is considered finished once the bank keys are accepted. \ No newline at end of file diff --git a/libeufin/nexus-manual.rst b/libeufin/nexus-manual.rst index c4ed2cbc..9ca783e8 100644 --- a/libeufin/nexus-manual.rst +++ b/libeufin/nexus-manual.rst @@ -1,6 +1,6 @@ .. This file is part of GNU TALER. - Copyright (C) 2014-2023 Taler Systems SA + Copyright (C) 2014-2024 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 @@ -26,13 +26,18 @@ Nexus Manual .. contents:: Table of Contents -LibEuFin Nexus is an EBICS facilitator. It offers a command line -interface to setup EBICS access, download banking records, and submit payments. -Future versions will offer a Web API to allow Taler Exchanges to talk to their +LibEuFin Nexus is an EBICS facilitator. It offers a command line interface to +setup EBICS access, download banking records, and submit payments. Today, the +LibEuFin implementation supports EBICS 2.5 and 3.0 and has been tested with +the Postfinance (CHF). Please note that banks tend to have their own dialects +of finance messages and thus other retail banks may or may not work. Contact +us if you need support for another bank or core banking protocol. + +Future versions will offer a Web API to allow Taler exchanges to talk to their banks. In this manual, we explain how to setup an EBICS subscriber. We assume that -the bank had already granted EBICS access to the subscriber. +the bank has already granted EBICS access to the subscriber. Installing Nexus ================ @@ -66,26 +71,105 @@ be found in the $PATH. Setting up the EBICS subscriber =============================== -.. include:: ../frags/ebics-setup.rst +When you sign up for an EBICS-enabled bank account, the bank will provide you +with various credentials. Those must be provided in the +``/etc/libeufin/libeufin-nexus.conf`` configuration file together with the +name of the *fiat* currency. -Sending payments -================ +The following snippet shows the mandatory configuration values: + +.. _core-config: + +.. code-block:: ini + + [nexus-ebics] + CURRENCY = CHF + + # Bank + HOST_BASE_URL = http://bank.example.com/ + BANK_DIALECT = postfinance + + # EBICS IDs + HOST_ID = mybank + USER_ID = myuser + PARTNER_ID = myorg + + # Account information + IBAN = myiban + BIC = mybic + NAME = myname + +.. note:: + Refer to the manpage ``libeufin-nexus.conf(5)`` + for the full array of configuration values. + +.. note:: + If you want to use existing client keys, copy the JSON file to the configured path ``CLIENT_PRIVATE_KEYS_FILE`` (``/var/lib/libeufin-nexus/client-ebics-keys.json`` by default) before running the following commands. + +Assuming that the configuration file exists at ``$CONFIG_FILE``, the following +command should start the EBICS setup process: + +.. code-block:: console + + $ libeufin-nexus ebics-setup -c "$CONFIG_FILE" + +If the previous command failed when running EBICS INI with an error code of +``EBICS_INVALID_USER_STATE``, you need to confirm your keys to your bank to +activate your account. + +To that end, the previous run should have left a PDF document that you can +print, sign and send to the bank. Look for the message that looks like ``PDF +file with keys created at '/tmp/libeufin-nexus-keys-$TIMESTAMP.pdf'``. + +Once the bank has received and processed this document, run the same +command again to download and verify the bank's keys: -Sending payments must follow a successful `EBICS subscriber setup `_, -where the bank obtained the subscriber keys, and the subscriber accepted the -bank keys. The responsible subcommand for sending payments is ``ebics-submit``, -and its configuration is a **superset** of core-config_. On top of that, it -expects the database connection string, and *optionally* a frequency to check -for submittable payments in the database. +.. code-block:: console + + $ libeufin-nexus ebics-setup -c "$CONFIG_FILE" + +The EBICS setup is finished once the bank keys have been accepted. -The connection string is specified as + +Database setup +============== + +The configuration file must include a connection string that +tells Nexus how it should connect to the database. The default +is: .. code-block:: ini [nexus-postgres] - config = postgres:///nexus +You must make sure that this database exists and is accessible to the user +running Nexus before continuing. Then, the Nexus database schema must be +created (or updated) to the current Nexus version using the following command: + +.. code-block:: console + + $ libeufin-nexus-dbinit -c "$CONFIG_FILE" + +where ``$CONFIG_FILE`` is again the path to a configuration that contains at +least the above ``[nexus-postgres]`` section. + + +Sending payments +================ + +Sending payments must follow a successful `EBICS subscriber setup +`_, where the bank obtained the subscriber keys, and the +subscriber accepted the bank keys. Furthermore, the database has to +be set up. Right now, some other process must queue payments to be +submitted to the database, so this section only discusses how such +queued payments will be executed. + +The responsible subcommand for sending payments is ``ebics-submit``, and its +configuration is a **superset** of core-config_. On top of that, it expects +the database connection string and *optionally* a frequency at which it will +check for submittable payments in the database. + The frequency **may** be specified as .. code-block:: ini @@ -95,40 +179,31 @@ The frequency **may** be specified as The supported time units are ``s`` (seconds), ``m`` (minutes), ``h`` (hours). -Before delving into the following sections, the database schema must be -created, therefore run the following command: - -.. code-block:: console - - $ libeufin-nexus dbinit -c $config_file - -Where ``$config_file`` is the path to a configuration path that contains at -least the ``[nexus-postgres]`` section. For testing ----------- The ``ebics-submit`` subcommand is **not** suitable to send arbitrary -payments, but rather to submit initiated payments that may be found -in the database. +payments, but rather to submit initiated payments that are already queued for +submission in the Nexus database. -Such initiated payments may be refunds of incoming payments with a subject -that would be invalid for a Taler withdrawal, or from a Taler exchange in -the attempt to pay a merchant. +Such queued payments may originate from bounces of incoming payments with a +subject that would be invalid for a Taler withdrawal, or from a Taler exchange +that needs to send a payment to a merchant. -For testing purposes, however, it is possible to artificially initiate -a payment into the database with the ``contrib/payment_initiation_debug.sh`` -script, found in the libeufin repository. The script pays always one Swiss -Franc to an IBAN and subject pair of choice. +For testing purposes it is possible to manually initiate a payment using the +``contrib/payment_initiation_debug.sh`` script from the libeufin repository. +The script currently always pays one Swiss Franc to the given IBAN and +wire transfer subject given as arguments. The following invocation pays 1 CHF to the CH987654321 with an "Hello, Nexus!" -subject. +subject: .. code-block:: console - $ ./payment_initiation_debug.sh $config_file CH987654321 "Hello, Nexus!" + $ ./payment_initiation_debug.sh "$CONFIG_FILE" CH987654321 "Hello, Nexus!" -``$config_file`` is the path to Nexus' configuration file and it does not need +``$CONFIG_FILE`` is the path to Nexus' configuration file and it does not need the FREQUENCY value. If the previous command worked, now the database should contain a new row in the ``initiated_outgoing_transactions`` table, with an ``unsubmitted`` submission state. diff --git a/libeufin/regional-manual.rst b/libeufin/regional-manual.rst index ca355a49..6d940849 100644 --- a/libeufin/regional-manual.rst +++ b/libeufin/regional-manual.rst @@ -161,22 +161,11 @@ Nexus to communicate with the fiat bank account that backs the regional currency Prerequisites +++++++++++++ -You must have a bank account at a bank dealing in fiat currency that offers an -online banking protocol supported by LibEuFin Nexus. As legacy transactions -in that bank account would likely confuse the system, it is highly advised to -use a fresh bank account, with an empty transaction history. - -Today, the LibEuFin implementation supports EBICS 2.5 and 3.0 and has been -tested with the Postfinance (CHF). Please note that banks tend to have their -own dialects of finance messages and thus other retail banks may or may not work. -Contact us if you need support for another bank or core banking protocol. - -.. _regional-ebics-setup: - -EBICS setup -+++++++++++ - -.. include:: ../frags/ebics-setup.rst +Set up an EBICS subscriber as described in :ref:`ebics-setup` using a bank +account at a bank dealing in fiat currency that offers an online banking +protocol supported by LibEuFin Nexus. As legacy transactions in that bank +account would likely confuse the system, it is advisable to use a fresh bank +account with an empty transaction history. .. note:: -- cgit v1.2.3 From be856edf71386e3c89ca4490a3c9c663efeb78df Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Fri, 2 Feb 2024 19:44:50 +0100 Subject: fix build issues --- core/api-merchant.rst | 5 +++-- libeufin/nexus-manual.rst | 5 +++-- libeufin/regional-manual.rst | 2 +- 3 files changed, 7 insertions(+), 5 deletions(-) diff --git a/core/api-merchant.rst b/core/api-merchant.rst index 3bce5414..b2de8854 100644 --- a/core/api-merchant.rst +++ b/core/api-merchant.rst @@ -2692,6 +2692,8 @@ once we got a reply from the exchange. The transfer cannot be deleted anymore. +.. _api-rewards: + ----------------------- Backend: Giving rewards ----------------------- @@ -2716,7 +2718,6 @@ reserve. The backend will return a reserve public key which must be used as the wire transfer subject when wiring the reward campaign funds to the exchange. -.. _rewards: .. http:post:: [/instances/$INSTANCE]/private/reserves Create a reserve for rewards. @@ -3149,7 +3150,7 @@ to validate that a customer made a payment. // "TOTP_WITHOUT_PRICE" or 1: Without amounts (typical OTP device) // "TOTP_WITH_PRICE" or 2: With amounts (special-purpose OTP device) // The "String" variants are supported @since protocol v7. - otp_algorithm: Integer | String; + otp_algorithm: Integer | string; // Counter for counter-based OTP devices. otp_ctr?: Integer; diff --git a/libeufin/nexus-manual.rst b/libeufin/nexus-manual.rst index 9ca783e8..80a61b93 100644 --- a/libeufin/nexus-manual.rst +++ b/libeufin/nexus-manual.rst @@ -24,8 +24,6 @@ Nexus Manual ############ -.. contents:: Table of Contents - LibEuFin Nexus is an EBICS facilitator. It offers a command line interface to setup EBICS access, download banking records, and submit payments. Today, the LibEuFin implementation supports EBICS 2.5 and 3.0 and has been tested with @@ -39,6 +37,9 @@ banks. In this manual, we explain how to setup an EBICS subscriber. We assume that the bank has already granted EBICS access to the subscriber. +.. contents:: Table of Contents + + Installing Nexus ================ diff --git a/libeufin/regional-manual.rst b/libeufin/regional-manual.rst index 6d940849..5ad8b10b 100644 --- a/libeufin/regional-manual.rst +++ b/libeufin/regional-manual.rst @@ -181,7 +181,7 @@ Prerequisites This step assumes that you already have a working regional currency bank and have successfully connected to a backing fiat bank account. -Follow the instructions from :ref:`EBICS setup `. +Follow the instructions from :ref:`EBICS setup `. Configuration +++++++++++++ -- cgit v1.2.3 From 050d17fa427db532ba2a43580fc1649c1b511acb Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Fri, 2 Feb 2024 19:58:39 +0100 Subject: more nexus-manual reviewing --- libeufin/nexus-manual.rst | 76 +++++++++++++++++++++-------------------------- 1 file changed, 34 insertions(+), 42 deletions(-) diff --git a/libeufin/nexus-manual.rst b/libeufin/nexus-manual.rst index 80a61b93..a3009787 100644 --- a/libeufin/nexus-manual.rst +++ b/libeufin/nexus-manual.rst @@ -176,7 +176,7 @@ The frequency **may** be specified as .. code-block:: ini [nexus-submit] - frequency = 5m + FREQUENCY = 5m The supported time units are ``s`` (seconds), ``m`` (minutes), ``h`` (hours). @@ -215,7 +215,7 @@ send it to the bank. .. code-block:: console - $ libeufin-nexus ebics-submit -c $config_file --transient + $ libeufin-nexus ebics-submit -c "$CONFIG_FILE" --transient The ``--transient`` flag instructs the software to perform only one pass on the database, submit what is submittable, and return. @@ -231,84 +231,76 @@ The ``ebics-submit`` subcommand can run in fixed frequency, or transient mode. The fixed frequency mode causes the command to check the database every time the frequency period expires. To activate this mode, and -- for example -- set a frequency of five minutes, set the configuration value ``FREQUENCY`` to ``5m``. Assuming that -``$config_fixed_frequency`` is set as described above, the following invocation would +``FREQUENCY`` is set as described above, the following invocation would make ``ebics-submit`` check the database every five minutes, and submit any initiated payment according to their submission state. .. code-block:: console - $ libeufin-nexus ebics-submit -c $config_fixed_frequency - + $ libeufin-nexus ebics-submit -c "$CONFIG_FILE" Transient mode causes ``ebics-submit`` to check the database only once, submit any initiated payment according to their submission state, and return. .. code-block:: console - $ libeufin-nexus ebics-submit -c $config + $ libeufin-nexus ebics-submit -c "$CONFIG_FILE" + + -Downloading records -=================== +Downloading payment records +=========================== -Downloading records must follow a successful `EBICS subscriber setup `_, -where the bank obtained the subscriber keys, and the subscriber accepted the bank keys. +Downloading payment records requires that the `EBICS subscriber setup +`_, where the bank obtained the subscriber keys and the +subscriber accepted the bank keys has been completed. -The configuration file must contain all the ``[ebics-setup]`` sections, plus the following -values to set the database connection and a log directory where any downloaded record would -be stored. +The configuration file must contain all the ``[ebics-setup]`` sections, plus +the following values to set the database connection and a log directory where +any downloaded record would be stored. .. code-block:: ini [nexus-postgres] config = postgres:///nexus -Assuming that ``$config_file`` contains any required option, the following command -would download any unseen notifications (as camt.054 files). - -.. code-block:: console - - $ libeufin-nexus ebics-fetch -c $config_file --transient - -The ``--transient`` flag makes the command to download only once and return. If the -bank returned any records, look in ``$LIBEUFIN_DATA_HOME/camt/YYYY-MM-DD`` to find them. -YYYY-MM-DD is the date when the download took place. - To activate periodic downloads, add the following setting to the ``nexus-fetch`` -configuration section in ``$config_file``: +configuration section in ``$CONFIG_FILE``: .. code-block:: ini [nexus-fetch] - frequency = 5m + FREQUENCY = 5m -The following invocation would then download records every five minutes, asking the bank -to only return documents that are timestamped *from* (inclusive) the last incoming transaction. +Assuming that ``$CONFIG_FILE`` contains all required options, the following command +would download any unseen notifications (as ``camt.054`` files): .. code-block:: console - $ libeufin-nexus ebics-fetch -c $config_file + $ libeufin-nexus ebics-fetch -c "$CONFIG_FILE" --transient + +The ``--transient`` flag makes the command to download only once and return. If the +bank returned any records, look in ``$LIBEUFIN_DATA_HOME/camt/YYYY-MM-DD`` to find them. +YYYY-MM-DD is the date when the download took place. Without the flag, Nexus will +download the transaction records at the frequency specified in the configuration. + Testing ------- If the bank account history has transactions that are useful for testing, it is -possible to redownload them via the ``--pinned-start`` argument. Note: if the Nexus -database contains already the bank account history, you might need to **reset** it, -in order to have the redownloaded transactions ingested. +possible to re-download them via the ``--pinned-start`` argument. -.. note:: - - Double-check the configuration: resetting the wrong database might cause DATA LOSS! - -For example, say that three back on the 2023-06-01 an handful of incoming transactions -got booked at the bank account watched by Nexus. After such day, the following command -would redownload them (and ingest them, if the database doesn't have them): +The following command redownloads transactions *from* the pinned start until +the present: .. code-block:: console - $ libeufin-nexus ebics-fetch -c $config_file --pinned-start 2023-06-01 - + $ libeufin-nexus ebics-fetch -c "$CONFIG_FILE" --pinned-start 2023-06-01 .. note:: - The command redownloads transactions *from* the pinned start until the present. + If the Nexus database already contains the bank account history, you might need + to **reset** the database in order to have the re-downloaded transactions be + properly ingested. Be careful when resetting the database: resetting the wrong + database might cause DATA LOSS! -- cgit v1.2.3 From 17d82259309cd065501a981406082ea573981929 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Fri, 2 Feb 2024 20:08:08 +0100 Subject: fix local tocs --- core/api-auditor.rst | 1 + core/api-corebank.rst | 1 + core/api-donau.rst | 1 + core/api-exchange.rst | 1 + core/api-merchant.rst | 2 +- libeufin/bank-manual.rst | 6 ++++-- libeufin/nexus-manual.rst | 1 + taler-developer-manual.rst | 3 ++- 8 files changed, 12 insertions(+), 4 deletions(-) diff --git a/core/api-auditor.rst b/core/api-auditor.rst index 9c2416a9..e837617c 100644 --- a/core/api-auditor.rst +++ b/core/api-auditor.rst @@ -25,6 +25,7 @@ The `glossary `_ defines all specific terms used in this section. .. contents:: Table of Contents + :local: .. _authentication: diff --git a/core/api-corebank.rst b/core/api-corebank.rst index d1cca6f2..481ff3e2 100644 --- a/core/api-corebank.rst +++ b/core/api-corebank.rst @@ -23,6 +23,7 @@ Taler Core Bank API ==================== .. contents:: Table of Contents + :local: Introduction ------------ diff --git a/core/api-donau.rst b/core/api-donau.rst index 4f3ce390..9ef69c92 100644 --- a/core/api-donau.rst +++ b/core/api-donau.rst @@ -26,6 +26,7 @@ The `glossary `_ defines all specific terms used in this section. .. contents:: Table of Contents + :local: .. _donau-overview: diff --git a/core/api-exchange.rst b/core/api-exchange.rst index 713d70f9..09fbcb8e 100644 --- a/core/api-exchange.rst +++ b/core/api-exchange.rst @@ -25,6 +25,7 @@ The `glossary `_ defines all specific terms used in this section. .. contents:: Table of Contents + :local: .. include:: tos.rst diff --git a/core/api-merchant.rst b/core/api-merchant.rst index b2de8854..d4f54fa4 100644 --- a/core/api-merchant.rst +++ b/core/api-merchant.rst @@ -25,7 +25,7 @@ Merchant Backend RESTful API ============================ .. contents:: Table of Contents - + :local: ----------------------- Base URLs and Instances diff --git a/libeufin/bank-manual.rst b/libeufin/bank-manual.rst index a61c7429..ad51ac9b 100644 --- a/libeufin/bank-manual.rst +++ b/libeufin/bank-manual.rst @@ -24,14 +24,16 @@ Bank Setup Manual ################# -.. contents:: Table of Contents - LibEuFin Bank implements a simple core banking system with account and REST APIs, including REST APIs for a Web interface and REST APIs to interact with GNU Taler components. In this manual, we explain how to setup a bank. +.. contents:: Table of Contents + :local: + + Installing LibEuFin Bank ======================== diff --git a/libeufin/nexus-manual.rst b/libeufin/nexus-manual.rst index a3009787..abacac9a 100644 --- a/libeufin/nexus-manual.rst +++ b/libeufin/nexus-manual.rst @@ -38,6 +38,7 @@ In this manual, we explain how to setup an EBICS subscriber. We assume that the bank has already granted EBICS access to the subscriber. .. contents:: Table of Contents + :local: Installing Nexus diff --git a/taler-developer-manual.rst b/taler-developer-manual.rst index ee7d93c3..184c6592 100644 --- a/taler-developer-manual.rst +++ b/taler-developer-manual.rst @@ -28,6 +28,7 @@ Developer's Manual .. contents:: Table of Contents :depth: 2 + :local: Project Overview @@ -477,7 +478,7 @@ All Taler components must be tagged with git before they are deployed on the SS = serial .. include:: checklist-demo-upgrade.rst - + Environments and Builders on taler.net ====================================== -- cgit v1.2.3 From 9cbd128256fd78d94082cec1fda8500a9142b6ff Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Fri, 2 Feb 2024 20:45:43 +0100 Subject: first revision of libeufin-bank manual --- frags/apt-install-libeufin-bank.rst | 6 ++ frags/apt-install-libeufin-nexus.rst | 6 ++ libeufin/bank-manual.rst | 128 +++++++++++++++++++++-------------- libeufin/nexus-manual.rst | 17 +++++ 4 files changed, 105 insertions(+), 52 deletions(-) create mode 100644 frags/apt-install-libeufin-bank.rst create mode 100644 frags/apt-install-libeufin-nexus.rst diff --git a/frags/apt-install-libeufin-bank.rst b/frags/apt-install-libeufin-bank.rst new file mode 100644 index 00000000..97b1bd71 --- /dev/null +++ b/frags/apt-install-libeufin-bank.rst @@ -0,0 +1,6 @@ + +To install libeufin-nexus, you can now simply run: + +.. code-block:: console + + # apt install libeufin-bank diff --git a/frags/apt-install-libeufin-nexus.rst b/frags/apt-install-libeufin-nexus.rst new file mode 100644 index 00000000..25ff8070 --- /dev/null +++ b/frags/apt-install-libeufin-nexus.rst @@ -0,0 +1,6 @@ + +To install libeufin-nexus, you can now simply run: + +.. code-block:: console + + # apt install libeufin-nexus diff --git a/libeufin/bank-manual.rst b/libeufin/bank-manual.rst index ad51ac9b..e9b5425f 100644 --- a/libeufin/bank-manual.rst +++ b/libeufin/bank-manual.rst @@ -1,6 +1,6 @@ .. This file is part of GNU TALER. - Copyright (C) 2014-2023 Taler Systems SA + Copyright (C) 2014-2024 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 @@ -39,6 +39,22 @@ Installing LibEuFin Bank The following section was tested on an *OpenJDK 17* environment. +Installing the libeufin-bank binary packages on Debian +------------------------------------------------------ + +.. include:: ../frags/installing-debian.rst + +.. include:: ../frags/apt-install-libeufin-bank.rst + + +Installing the libeufin-bank binary packages on Ubuntu +------------------------------------------------------ + +.. include:: ../frags/installing-ubuntu.rst + +.. include:: ../frags/apt-install-libeufin-bank.rst + + Building from source -------------------- @@ -61,8 +77,9 @@ Navigate into the *libeufin* local repository, and from top-level run: If the previous steps succeeded, the ``libeufin-bank`` command should be found in the $PATH. -Setting up the LibEuFin Bank -============================ + +Minimal Configuration for LibEuFin Bank +======================================= The following snippet shows the mandatory configuration values: @@ -82,67 +99,77 @@ The following snippet shows the mandatory configuration values: Refer to the manpage ``libeufin-man.conf(5)`` for the full array of configuration values. -Assuming that the configuration file exists at ``$config_file``, the following -command would define the database schema and create an admin account. -.. code-block:: console +Configuring multi-factor authentication +--------------------------------------- - $ libeufin-bank dbinit -c $config_file +libeufin-bank uses helper scripts to send challenge codes to addresses for +multi-factor authentication. By default, those helper scripts are +``libeufin-tan-email.sh`` to send e-mails and ``libeufin-tan-sms.sh`` to send +SMS. It is possible to replace these scripts with use custom scripts to send +the e-mail or SMS TAN. -If you wish to authenticate as admin, you must change the account password with the following command. +Such alternative scripts must accept the phone number / e-mail address as the +``$1`` parameter and the message content to be transmitted in their standard +input. They should return 0 to indicate successful transmission of the +challenge, and non-zero on failure. -.. code-block:: console +To change the scripts used for multi-factor authentication, change the following +options in the configuration file: - $ libeufin-bank passwd -c $config_file admin $PASSWORD +.. code-block:: ini -Then you can start the HTTP server. + [libeufin-bank] + TAN_SMS = custom-tan-sms.sh + TAN_EMAIL = custom-tan-email.sh -.. code-block:: console +.. note:: - $ libeufin-bank serve -c $config_file + The default ``libeufin-tan-sms.sh`` script is based on the `Telesign + `_ provider. It requires an additional local + resource file or environment variables with your Telesign credentials to + exist. -Using custom e-mail / SMS TAN scripts -------------------------------------- +Launching libeufin-bank +======================= -The guided setup installs the TAN scripts found in ``libeufin/contrib/``: -``libeufin-tan-email.sh`` and ``libeufin-tan-sms.sh``, but should you want to -use custom scripts to send the e-mail or SMS TAN, set the configuration like -follows: +Assuming that the configuration file exists at ``$CONFIG_FILE``, the following +command initializes (or upgrades) the database schema: -.. note:: +.. code-block:: console - The default SMS TAN script is based on the `Telesign `_ provider. + $ libeufin-bank-dbinit -c "$CONFIG_FILE" -.. code-block:: ini +Once this is done, you can start the libeufin-bank HTTP server: - [libeufin-bank] +.. code-block:: console - TAN_SMS = custom-tan-sms.sh - TAN_EMAIL = custom-tan-email.sh + $ libeufin-bank serve -c "$CONFIG_FILE" -The scripts TAN_SMS/EMAIL must accept the phone number / e-mail address as the -``$1`` parameter and the message content to be transmitted in their standard -input. -Using the Bank Web Interface +Using the bank Web interface ============================ -Before you can use the Web interface, you must set -a password for the "admin" account. You can do this -using: +To be able to use the Web interface, you must set a password for the "admin" +account. You can set (or reset) the account password to ``$PASSWORD`` using +the following command: .. code-block:: console - $ libeufin-bank passwd -c $config_file admin "$PASSWORD" + $ libeufin-bank passwd -c "$CONFIG_FILE admin "$PASSWORD" + +You can also use the same command to reset the passwords of other accounts by +replacing "admin" with the respective login. + -Setting up Accounts +Setting up accounts ------------------- -Using the above "$PASSWORD", log into the Web interface as "admin". Then -search for the button "Create account" near the list of all existing bank -accounts in the Web interface of libeufin-bank. +Using the above "$PASSWORD", log into the Web interface as "admin". To setup +regular accounts, search for the button "Create account" near the list of all +existing bank accounts in the Web interface of libeufin-bank. You will be asked to specify: @@ -170,27 +197,24 @@ XXX Cashout channel Is this account public? Public accounts can be viewed without access control, their balance and transaction history becomes public. -After submitting the form, a randomly created password -for the new account will be shown in a notification. -The administrator can also change passwords for any -account in the system using the "change password" link -in the account list. To change other details about an -account, select the "Username" in the account list. +After submitting the form, a randomly created password for the new account +will be shown in a notification. The administrator can also change passwords +for any account in the system using the "change password" link in the account +list. To change other details about an account, select the "Username" in the +account list. -Account Introspection +Account introspection --------------------- -Users can see (and possibly change) the settings of -their bank account and also their IBAN by clicking -on the "Welcome, $USERNAME" text after logging into -their bank account using their username and password. +Users can see (and possibly change) the settings of their bank account and +also their IBAN by clicking on the "Welcome, $USERNAME" text after logging +into their bank account using their username and password. -The IBAN field has a convenient "copy to clipboard" -button next to it. +The IBAN field has a convenient "copy to clipboard" button next to it. -Making Transfers between Accounts +Making transfers between accounts --------------------------------- First, you need to know the IBAN of the account to credit, and log in as the @@ -202,7 +226,7 @@ be wired. After pressing "Send", you may have to pass a 2-FA check. Integration with the Taler Exchange =================================== -Exchange Configuration +Exchange configuration ---------------------- TODO. diff --git a/libeufin/nexus-manual.rst b/libeufin/nexus-manual.rst index abacac9a..bff74ef8 100644 --- a/libeufin/nexus-manual.rst +++ b/libeufin/nexus-manual.rst @@ -46,6 +46,23 @@ Installing Nexus The following section was tested on an *OpenJDK 17* environment. + +Installing the libeufin-nexus binary packages on Debian +------------------------------------------------------- + +.. include:: ../frags/installing-debian.rst + +.. include:: ../frags/apt-install-libeufin-nexus.rst + + +Installing the libeufin-nexus binary packages on Ubuntu +------------------------------------------------------- + +.. include:: ../frags/installing-ubuntu.rst + +.. include:: ../frags/apt-install-libeufin-nexus.rst + + Building from source -------------------- -- cgit v1.2.3 From 669ae334e74a7a5894f8acbd07471e239fe3f624 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Fri, 2 Feb 2024 20:51:13 +0100 Subject: make toc local --- libeufin/regional-manual.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/libeufin/regional-manual.rst b/libeufin/regional-manual.rst index 5ad8b10b..bccec641 100644 --- a/libeufin/regional-manual.rst +++ b/libeufin/regional-manual.rst @@ -27,6 +27,7 @@ In this manual, we explain how we model a regional currency and how to set up one using GNU Taler and LibEuFin technology. .. contents:: Table of Contents + :local: How to create/destroy regional currency -- cgit v1.2.3 From 5a1add07e8475496e986162c8888d6ae9732bba2 Mon Sep 17 00:00:00 2001 From: Antoine A <> Date: Fri, 2 Feb 2024 21:25:02 +0100 Subject: update libeufin-bank documentation --- core/api-corebank.rst | 9 +++++---- manpages/libeufin-bank.conf.5.rst | 9 +++++++++ 2 files changed, 14 insertions(+), 4 deletions(-) diff --git a/core/api-corebank.rst b/core/api-corebank.rst index 481ff3e2..1fb8fb43 100644 --- a/core/api-corebank.rst +++ b/core/api-corebank.rst @@ -157,7 +157,7 @@ Account Management // Addresses where to send the TAN for protected operations. contact_data?: ChallengeContactData; - // 'payto' URI of a fiat bank account with a 'receiver-name' parameter. + // IBAN 'payto' URI of a fiat bank account with a 'receiver-name' parameter. // If 'receiver-name' is missing, ``name`` will be used instead. // Payments will be sent to this bank account // when the user wants to convert the regional currency @@ -165,7 +165,8 @@ Account Management cashout_payto_uri?: string; // Internal payto URI of this bank account. - // Used mostly for testing. + // Used mostly for testing, this field is ignored if the bank payment + // method is not IBAN. payto_uri?: string; // If present, set the max debit allowed for this user @@ -253,7 +254,7 @@ Account Management // Addresses where to send the TAN for protected operations. contact_data?: ChallengeContactData; - // 'payto' URI of a fiat bank account with a 'receiver-name' parameter. + // IBAN 'payto' URI of a fiat bank account with a 'receiver-name' parameter. // If 'receiver-name' is missing, ``name`` will be used instead. // Payments will be sent to this bank account // when the user wants to convert the regional currency @@ -488,7 +489,7 @@ Account Management // as well. contact_data?: ChallengeContactData; - // 'payto' URI pointing the bank account + // IBAN 'payto' URI pointing the bank account // where to send cashouts. This field is optional // because not all the accounts are required to participate // in the merchants' circuit. One example is the exchange: diff --git a/manpages/libeufin-bank.conf.5.rst b/manpages/libeufin-bank.conf.5.rst index 0b27319f..30e8d9ab 100644 --- a/manpages/libeufin-bank.conf.5.rst +++ b/manpages/libeufin-bank.conf.5.rst @@ -35,6 +35,15 @@ The following options are from the “[libeufin-bank]” section. CURRENCY Internal currency of the libeufin-bank, e.g. “EUR” for Euro. +PAYMENT_METHOD + Supported payment method, this can either be ``iban`` or ``x-taler-bank`` + +IBAN_PAYTO_BIC + Bank BIC used in generated iban payto URI + +X_TALER_BANK_PAYTO_HOSTNAME + Bank hostname used in generated x-taler-bank payto URI + DEFAULT_DEBT_LIMIT Default debt limit for newly created accounts. Defaults to CURRENCY:0 if not specified. -- cgit v1.2.3 From c0e5be74b8cfbc6978c6b1fa1c7f6c6128fcde3b Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Sat, 3 Feb 2024 21:10:43 +0100 Subject: fix contract terms link --- design-documents/024-age-restriction.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/design-documents/024-age-restriction.rst b/design-documents/024-age-restriction.rst index 280a4f39..ee478ee1 100644 --- a/design-documents/024-age-restriction.rst +++ b/design-documents/024-age-restriction.rst @@ -600,9 +600,9 @@ The object ``ContractTerms`` is extended by an optional field ``minimum_age`` that can be any integer greater than 0. In reality this value will not be smaller than, say, 8, and not larger than, say, 21. -.. ts:def:: ContractTerms +.. ts:def:: DD24ContractTerms - interface ContractTerms { + interface DD24ContractTerms { ... // If the order requires a minimum age greater than 0, this field is set -- cgit v1.2.3 From ca5d9a67e91655c3c5c2f1ca2e04bd2161fc4337 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Sat, 3 Feb 2024 22:47:49 +0100 Subject: work on libeufin manual(s) --- images/Makefile | 5 +- images/regional-arch.dot | 36 +++++ libeufin/bank-manual.rst | 29 +++- libeufin/nexus-manual.rst | 2 + libeufin/regional-manual.rst | 320 +++++++++++++++---------------------------- taler-exchange-manual.rst | 12 +- 6 files changed, 186 insertions(+), 218 deletions(-) create mode 100644 images/regional-arch.dot diff --git a/images/Makefile b/images/Makefile index 56f9fbac..3a7fdab9 100644 --- a/images/Makefile +++ b/images/Makefile @@ -1,7 +1,9 @@ -diagrams: arch-api.png coin.png deposit.png reserve.png transaction-common-states.png transaction-withdrawal-states.png transaction-payment-states.png transaction-refund-states.png transaction-refresh-states.png transaction-reward-states.png transaction-deposit-states.png transaction-push-debit-states.png transaction-push-credit-states.png transaction-pull-credit-states.png transaction-pull-debit-states.png challenger.png +diagrams: regional-arch.png arch-api.png coin.png deposit.png reserve.png transaction-common-states.png transaction-withdrawal-states.png transaction-payment-states.png transaction-refund-states.png transaction-refresh-states.png transaction-reward-states.png transaction-deposit-states.png transaction-push-debit-states.png transaction-push-credit-states.png transaction-pull-credit-states.png transaction-pull-debit-states.png challenger.png arch-api.png: arch-api.dot dot -Tpng arch-api.dot > arch-api.png +regional-arch.png: regional-arch.dot + dot -Tpng regional-arch.dot > regional-arch.png challenger.png: challenger.dot dot -Tpng challenger.dot > challenger.png transaction-common-states.png: transaction-common-states.dot @@ -32,4 +34,3 @@ deposit.png: deposit.dot dot -Tpng deposit.dot > deposit.png reserve.png: reserve.dot dot -Tpng reserve.dot > reserve.png - diff --git a/images/regional-arch.dot b/images/regional-arch.dot new file mode 100644 index 00000000..8a61ed5e --- /dev/null +++ b/images/regional-arch.dot @@ -0,0 +1,36 @@ +digraph G { + subgraph cluster_2 { + ubank; + nexus; + rank="same"; ebank; mbank; + label="Fiat currency"; + }; + subgraph cluster_1 { + user; + exchange; + shop; + rbank; + label="Regional currency"; + }; + subgraph cluster_2b { + } + user[label="Customer (Wallet)"]; + shop[label="Merchant (Backend)"]; + exchange[label="Exchange"]; + ubank[label="Customer Fiat Bank"]; + ebank[label="Exchange Fiat Bank"]; + mbank[label="Merchant Fiat Bank"]; + rbank[label="Regional Currency Bank"]; + user->ubank [label="1. Initiate withdraw"]; + ubank->ebank [label="2. Wire transfer"]; + ebank->nexus [label="3. EBICS (CAMT)"]; + nexus->rbank [label="4. Conversion (Cash-in)"]; + rbank->exchange [label="5. Wirewatch"]; + exchange->user [label="6. Withdraw E-Cash"]; + user->shop [label="7. Spend E-Cash"]; + shop->exchange [label="8. Deposit E-Cash"]; + exchange->rbank [label="9. Credit Shop"]; + rbank->nexus [xlabel="10. Conversion (Cash-out)"]; + nexus->ebank [label="11. EBICS (PAIN)"]; + ebank->mbank [label="12. Wire-transfer"]; +} diff --git a/libeufin/bank-manual.rst b/libeufin/bank-manual.rst index e9b5425f..f8f2dd28 100644 --- a/libeufin/bank-manual.rst +++ b/libeufin/bank-manual.rst @@ -24,7 +24,7 @@ Bank Setup Manual ################# -LibEuFin Bank implements a simple core banking system with +libeufin-bank implements a simple core banking system with account and REST APIs, including REST APIs for a Web interface and REST APIs to interact with GNU Taler components. @@ -99,6 +99,7 @@ The following snippet shows the mandatory configuration values: Refer to the manpage ``libeufin-man.conf(5)`` for the full array of configuration values. +.. _libeufin-mfa: Configuring multi-factor authentication --------------------------------------- @@ -226,12 +227,30 @@ be wired. After pressing "Send", you may have to pass a 2-FA check. Integration with the Taler Exchange =================================== -Exchange configuration ----------------------- +.. note:: + + This step is fully automated if you use the :ref:`guided automated setup `. + +You must have an exchange account with username ``exchange`` for conversion to work. +Assuming that the configuration file exists at ``$CONFIG_FILE``, the following +command would create one: + +.. code-block:: console + + $ libeufin-bank create-account '{"username":"exchange","password":"$EXCHANGE_PASSWORD","name":"Cashout Exchange","is_taler_exchange":true}' -c "$CONFIG_FILE" + +.. note:: + + You can also set up the exchange account as "admin" using the Web interface of libeufin-bank. + +Having done so, take note of two key pieces of information, namely the ``$EXCHANGE_PASSWORD`` and the "payto://"-URI of the exchange bank account. This information must then be used to configure the exchange as described in +:ref:`exchange bank account configuration `. When using the libeufin-bank in the context +of a regional currency with conversion, you must +additionally specify a "conversion-url" when setting +up the exchange account. See the section on :ref:`conversion setup ` in the regional currency setup chapter for details. -TODO. Withdrawing e-cash to a Taler wallet ------------------------------------- +==================================== TODO. diff --git a/libeufin/nexus-manual.rst b/libeufin/nexus-manual.rst index bff74ef8..b8f2458d 100644 --- a/libeufin/nexus-manual.rst +++ b/libeufin/nexus-manual.rst @@ -173,6 +173,7 @@ created (or updated) to the current Nexus version using the following command: where ``$CONFIG_FILE`` is again the path to a configuration that contains at least the above ``[nexus-postgres]`` section. +.. _sending-payments: Sending payments ================ @@ -265,6 +266,7 @@ initiated payment according to their submission state, and return. $ libeufin-nexus ebics-submit -c "$CONFIG_FILE" +.. _receive-transaction-data: Downloading payment records =========================== diff --git a/libeufin/regional-manual.rst b/libeufin/regional-manual.rst index bccec641..f145b69c 100644 --- a/libeufin/regional-manual.rst +++ b/libeufin/regional-manual.rst @@ -1,6 +1,6 @@ .. This file is part of GNU TALER. - Copyright (C) 2014-2023 Taler Systems SA + Copyright (C) 2014-2024 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 @@ -23,23 +23,47 @@ Regional Currency Setup Manual ############################## -In this manual, we explain how we model a regional currency and -how to set up one using GNU Taler and LibEuFin technology. +In this manual, we explain how to set up a regional currency with or without +currency conversion from and to fiat currency. Most of this manual is about +setting up the currency conversion logic with a fiat bank that offers an EBICS +interface. + +If you want to run a regional currency without any conversion from or to a +fiat currency, all you need to do is set up the :ref:`libeufin-bank +` and integrate it with a Taler exchange. As a result, several +sections in this manual related to currency conversion can be +skipped. However, you may still find the :ref:`guided setup +` helpful. .. contents:: Table of Contents :local: -How to create/destroy regional currency -======================================= +Architecture +============ + +There are several key components needed to operate a regional currency based +on GNU Taler and LibEuFin technology: + +- LibEuFin Nexus: is responsible to drive the master (fiat) bank account both to learn + about incoming payments and to send fiat cash-out payments +- LibEuFin Bank: offers basic banking operations, e.g. wire transfers, Taler withdrawals, + account management, cash-out's +- Taler exchange: server side of Taler operations. +- Taler wallet: client side of Taler operations. +- Taler merchant backend: abstracts Taler details to the shops. + +.. image:: ../images/regional-arch.png -In this model, the regional currency is backed by the fiat currency and users are -offered two operations: *cash-in* to create regional currency starting from the fiat, -and *cash-out* to destroy regional currency and obtain fiat currency back. +In this model, the regional currency is backed by the fiat currency and users +are offered two operations: *cash-in* to create regional currency starting +from fiat money, and *cash-out* to convert regional currency into fiat +currency. -The example below assumes that one single unit of regional currency is always backed +The design assumes that one single unit of regional currency is always backed by one single unit of fiat currency. + Cash-in +++++++ @@ -49,8 +73,12 @@ fiat payment of N units, it triggers the creation of N units of regional currenc Such trigger causes the *admin bank account* at the regional bank to wire the N units of regional currency to the Taler exchange (regional) bank account. At this point, the Taler exchange is ready to issue the regional coins to the Taler wallet that proves -to own them. Note: *valid* fiat payments are those with a Taler-relevant subject that -should be generated by a Taler wallet. +to own them. + +.. note:: + + *Valid* fiat payments are those with a Taler-relevant subject that should be generated by a Taler wallet. + Cash-out ++++++++ @@ -60,23 +88,19 @@ a regional payment of N units to the *admin bank account*. This latter triggers a fiat payment of N units to the fiat bank account owned by the user who initiated the cash-out. -How are GNU Taler & LibEuFin used to create the regional currency? -================================================================== -Following are the main components to operate a regional currency based -on GNU Taler and LibEuFin technology. -- LibEuFin Nexus: is responsible to drive the master (fiat) bank account both to learn - about incoming payments and to send fiat cash-out payments -- LibEuFin Bank: offers basic banking operations, e.g. wire transfers, Taler withdrawals, - account management, cash-out's -- Taler exchange: server side of Taler operations. -- Taler wallet: client side of Taler operations. -- Taler merchant backend: abstracts Taler details to the shops. +.. _automated-regional-currency-setup: +Guided Automated Setup +====================== -Guided basic setup -================== +You can either manually follow the steps to :ref:`setup libeufin-nexus +` and :ref:`setup libeufin-bank ` or use the +script described in this section which largely automates the process. If you +choose to use the manual setup, you should skip the final step that actually +starts the Nexus commands to initate payments and download transaction data +until most of the setup steps below have been completed! Prerequisites +++++++++++++ @@ -92,7 +116,7 @@ automatic deployment scripts provided in the ``deployment.git`` Git repository in the ``regional-currency/`` folder. -Obtaining the scripts +Obtaining the Scripts +++++++++++++++++++++ First, download the deployment scripts via Git: @@ -101,8 +125,8 @@ First, download the deployment scripts via Git: $ git clone git://git.taler.net/deployment -Guided Configuration -++++++++++++++++++++ +Running the Guided Configuration +++++++++++++++++++++++++++++++++ This approach sets up a regional currency with cash-in/-out rates of 1:1. @@ -116,8 +140,7 @@ The script will start by asking you fundamental questions about the desired setup, in particular: * The name of the regional currency. It must have 3 to 11 letters. - Currently only 'NETZBON' is supported. - * The ISO code of the fiat currency. Currently only 'CHF' is supported. + * The ISO code of the fiat currency. Use 'CHF' or 'EUR'. * The name of the regional currency bank. It will be shown to business users when they interact with the system. * Whether to use TLS or not. You should answer ``y`` in most cases. @@ -135,7 +158,7 @@ desired setup, in particular: But, these subdomain names, must have been added beforehand to your DNS domain control panel, and they must be pointing to the IP address of the system on which you are running the - installation (before you execute the installer)). + installation (before you execute the installer). The information you entered as well as the generated bank admin password will be stored in a file called ``config/user.conf``. Should you run the script in @@ -148,46 +171,32 @@ Grab a coffee. .. note:: - At this point, the setup is NOT connected to any fiat bank account! + At this point, the setup is NOT connected to any fiat bank account! The next + steps must always be done manually! -Connecting to a Fiat Bank -========================= -Some regional currencies are backed by assets in a fiat currency and allow users -to convert fiat currency into the regional currency (``cash in``) and to convert -regional currency into fiat currency (``cash out``). Restrictions, exchange rates -and fees may apply to these conversions. This section explains how to setup LibEuFin -Nexus to communicate with the fiat bank account that backs the regional currency. +Connecting to a Fiat Bank: the EBICS setup +========================================== -Prerequisites -+++++++++++++ - -Set up an EBICS subscriber as described in :ref:`ebics-setup` using a bank -account at a bank dealing in fiat currency that offers an online banking -protocol supported by LibEuFin Nexus. As legacy transactions in that bank -account would likely confuse the system, it is advisable to use a fresh bank -account with an empty transaction history. - -.. note:: - - For debug setups where the cash-ins are simulated :ref:`this way `, - this step can be entirely skipped. +Some regional currencies are backed by assets in a fiat currency and allow +users to convert fiat currency into the regional currency (``cash in``) and to +convert regional currency into fiat currency (``cash out``). Restrictions, +exchange rates and fees may apply to these conversions. This section explains +how to setup LibEuFin Nexus to communicate with the fiat bank account that +backs the regional currency. +First, you must set up an EBICS subscriber as described in :ref:`EBICS setup +` using a bank account at a bank dealing in fiat currency that +offers an online banking protocol supported by LibEuFin Nexus. As legacy +transactions in that bank account would likely confuse the system, it is +advisable to use a fresh bank account with an empty transaction history. -Enable regional currency conversion -=================================== - -Prerequisites -+++++++++++++ - -This step assumes that you already have a working regional currency bank -and have successfully connected to a backing fiat bank account. -Follow the instructions from :ref:`EBICS setup `. -Configuration -+++++++++++++ +Enabling Currency Conversion +============================ -Then you have to enable conversion and at least one TAN channel for cashout in the configuration file. +Next, you have to enable conversion and should ensure that at least one TAN +channel for :ref:`multi-factor authentication ` is configured: .. code-block:: ini @@ -199,20 +208,13 @@ Then you have to enable conversion and at least one TAN channel for cashout in t # And/Or TAN_EMAIL = libeufin-tan-email.sh +Make sure to (re)start the libeufin-bank after changing +these configuration options: -You must have an exchange account with username ``exchange`` for conversion to work. -Assuming that the configuration file exists at ``$config_file``, the following -command would create one: - -.. code-block:: console - - libeufin-bank create-account '{"username":"exchange","password":"password","name":"Cashout Exchange","is_taler_exchange":true}' -c $config_file - -Then the following command would start the server with conversion API enabled : + .. code-block:: console -.. code-block:: console + # systemctl restart libeufin-bank - libeufin-bank serve -c $config_file Web-based Configuration +++++++++++++++++++++++ @@ -220,30 +222,22 @@ Web-based Configuration Now you should be able to setup conversion rates and ``admin`` debt limit though the Web interface of the bank as the ``admin`` user. -Conversion ON! -++++++++++++++ - -The last step is to run Nexus to import incoming bank -transactions (cash in) and to trigger outgoing bank transactions (cash out). -Refers to ``nexus-manual.conf`` for more details. - +.. _regional-conversion-setup: +Configuring the Exchange for Conversion ++++++++++++++++++++++++++++++++++++++++ -Exchange-wallet integration -=========================== +This section explains how to enable currency conversion at the exchange, +which is critical for wallets to know how to wire fiat currency to an +exchange to obtain regional currency. -Although not strictly needed to start withdrawing regional money, this -section explain how to enable the tight integration between Taler exchange -and wallet, to let wallets learn about the possibility of withdrawing -regional funds via a particular exchange. - -First, you need to use the ``taler-exchange-offline`` tool to inform the -exchange about the fiat bank account that can be used for cash in operations -and also specify the URL for currency conversion. Additionally, you may also -configure restrictions on the bank accounts that may originate the funds, for -example to prevent international wire transfers that may expose you to -additional compliance risks. +You will need to use the ``taler-exchange-offline`` tool to inform the +exchange about the **fiat** bank account that can be used for cash in +operations and also specify the URL for currency conversion. Additionally, +you may also configure restrictions on the bank accounts that may originate +the funds, for example to prevent international wire transfers that may expose +you to additional compliance risks. Given the ``$IBAN`` of the fiat currency bank account and ``$NAME`` as the (URL-encoded) name of the exchange-account owner, the following @@ -262,7 +256,26 @@ Here, the ``$CONVERSION_URL`` must be set to the base URL of the conversion endpoint of the bank, which should be ``https://bank.$DOMAIN/conversion-info/`` in our setup. -Wallet setup +.. note:: + + The above command adds a **second** bank account to the exchange. + You (or the guided setup script) should have already enabled the + regional currency bank account (without any "conversion-url"). + + +System ON! +========== + +The last step is to enable libeufin-nexus to :ref:`import incoming bank +transactions ` (cash in) and to :ref:`trigger +outgoing bank transactions ` (cash out). + +.. code-block:: console + + # systemd enable --now libeufin-nexus-ebics-fetch + # systemd enable --now libeufin-nexus-ebics-submit + +Wallet Setup ============ This section describes the interaction between the Taler graphical wallet (Android, @@ -286,119 +299,14 @@ exchange to perform such deposit. So once the exchange has credited the regiona currency account to your account and assuming the cash out rules are satisfied, you should then be able to start a cash out operation. -.. - FIXME: uncomment once tested. - - Enable regional currency conversion - =================================== - - Prerequisites - +++++++++++++ - - This step assumes that you already have a working regional currency bank - and have successfully connected to a backing fiat bank account. - - Additionally, for each account that is allowed to convert regional currency - into fiat, you must configure the (fiat) bank account number of the fiat - currency with the respective account profile. Only the bank ``admin`` is - allowed to set fiat bank account numbers. - - Furthermore, to achieve a reasonable security level, you must enable two - factor authentication for "cash out" transactions. This requires you to - configure an e-mail address or phone number for every account that supports - "cash out" transactions --- and to setup your system for sending e-mails or - SMS. This manual does not cover setting up e-mail. For SMS delivery, you will - need to obtain credentials from an SMS provider and provide a script to send - messages via such a provider. - - Configuration - +++++++++++++ - - You have to enable conversion and at least one TAN channel for cashout in the - ``/etc/libeufin/libeufin-bank.conf`` configuration file: - - .. code-block:: console - - [libeufin-bank] - ALLOW_CONVERSION = yes - FIAT_CURRENCY = EUR - - TAN_SMS = libeufin-tan-sms.sh - # And/Or - TAN_EMAIL = libeufin-tan-email.sh - - Afterwards, restart the bank: - - .. code-block:: console - - # systemctl restart libeufin-bank - - - The scripts TAN_SMS/EMAIL must accept the phone number / e-mail address - as the ``$1`` parameter and the content in their standard input. The LibEuFin - repository offers them in ``contrib/``: adjust to your setup! - - .. note:: - - the TAN_SMS script relies on a Telesign account. For this reason, - it needs a telesign-secret file found in the PATH, that defines the - environment variables API_KEY and CUSTOMER_ID - Web-based Configuration - +++++++++++++++++++++++ - - Now you should be able to setup conversion rates and ``admin`` debt limit though the Web - interface of the bank as the ``admin`` user. - - - Conversion ON! - ++++++++++++++ - - The last step is to enable the Nexus services to import incoming bank - transactions (cash in) and to trigger outgoing bank transactions (cash out): - - .. code-block:: console - - # systemd enable --now libeufin-nexus-ebics-fetch - # systemd enable --now libeufin-nexus-ebics-submit - - Going live! - =========== - - Exchange setup - ++++++++++++++ - - First, you need to use the ``taler-exchange-offline`` tool to inform the - exchange about the fiat bank account that can be used for cash in operations - and also specify the URL for currency conversion. Additionally, you may also - configure restrictions on the bank accounts that may originate the funds, for - example to prevent international wire transfers that may expose you to - additional compliance risks. - - Given the ``$IBAN`` of the fiat currency bank account and ``$NAME`` as - the (URL-encoded) name of the exchange-account owner, the following - ``taler-exchange-offline`` invocation can be used to inform wallets about - the possibility of currency conversion (cash in) when wallets download - ``/keys`` with bank account data from the exchange: - - .. code-block:: console - - # taler-exchange-offline \ - enable-account \ - payto://iban/$IBAN?receiver-name=$NAME \ - conversion-url "$CONVERSION_URL" \ - upload - - Here, the ``$CONVERSION_URL`` must be set to the base URL of the conversion - endpoint of the bank, which should be ``https://bank.$DOMAIN/conversion-info/`` - in our setup. - -Podman deployment -================= +Alternative Podman-based Deployment +=================================== The Podman-based deployment installs, configures, and launches any Taler and -LibEuFin service with the aim of serving a regional currency. +LibEuFin service required to operate a regional currency. Please clone ``git://git.taler.net/deployment`` and checkout the ``regio`` -branch. Navigate to the ``sandcastle-ng`` directory and read the README file: -it should guide you through all the steps to running the regional currency. +branch. Navigate to the ``sandcastle-ng`` directory and read the README file. +It should guide you through all the necessary steps to deploy a regional +currency. diff --git a/taler-exchange-manual.rst b/taler-exchange-manual.rst index 742b0c8e..ec209f76 100644 --- a/taler-exchange-manual.rst +++ b/taler-exchange-manual.rst @@ -1811,6 +1811,8 @@ periodically, as it signs the various online signing keys of the exchange which periodically expire. +.. _exchange-account-signing: + Account signing --------------- @@ -2013,7 +2015,7 @@ AML Forms --------- AML forms are defined by the DD 54 dynamic forms. -The shipped implementation with of the exchange is installed in +The shipped implementation with of the exchange is installed in .. code-block:: shell-session @@ -2026,11 +2028,11 @@ every entry in the list the next properties are expected to be present: ``label``: used in the UI as the name of the form ``id``: identification name, this will be saved in the exchange database -along with the values to correctly render the form again. +along with the values to correctly render the form again. It should simple, short and without any character outside numbers, letters and underscore. -``version``: when editing a form, instead of just replacing fields +``version``: when editing a form, instead of just replacing fields it will be better to create a new form with the same id and new version. That way old forms in the database will used old definition of the form. It should be a number. @@ -2040,12 +2042,12 @@ See DD 54 dynamic forms. .. attention:: - do not remove a form the list if it has been used. Otherwise you + do not remove a form the list if it has been used. Otherwise you won't be able to see the information save in the exchange database. To add a new one you can simply copy and paste one element, and edit it. -It is much easier to download ``@gnu-taler/aml-backoffice-ui`` source +It is much easier to download ``@gnu-taler/aml-backoffice-ui`` source from ``https://git.taler.net/wallet-core.git/``, compile and copy the file from the ``dist/prod``. -- cgit v1.2.3 From 7247f9665a35c6d0241169059723869b0807d94f Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Sun, 4 Feb 2024 10:44:47 +0100 Subject: fix section 7.6 --- core/api-bank-wire.rst | 2 + taler-exchange-manual.rst | 404 ++++------------------------------------------ 2 files changed, 37 insertions(+), 369 deletions(-) diff --git a/core/api-bank-wire.rst b/core/api-bank-wire.rst index eb7920f9..7c028388 100644 --- a/core/api-bank-wire.rst +++ b/core/api-bank-wire.rst @@ -13,6 +13,8 @@ You should have received a copy of the GNU Affero General Public License along with TALER; see the file COPYING. If not, see +.. _taler-wire-gateway-http-api: + =========================== Taler Wire Gateway HTTP API =========================== diff --git a/taler-exchange-manual.rst b/taler-exchange-manual.rst index ec209f76..79455fec 100644 --- a/taler-exchange-manual.rst +++ b/taler-exchange-manual.rst @@ -1,7 +1,7 @@ .. This file is part of GNU TALER. - Copyright (C) 2014-2023 Taler Systems SA + Copyright (C) 2014-2024 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 @@ -822,369 +822,32 @@ configuration of the online machine: Wire Gateway Setup ================== -The Taler Wire Gateway is an API that connects the Taler exchange to -the underlying core banking system. +The :ref:`Taler Wire Gateway ` is an API that +connects the Taler exchange to the underlying core banking system. There are +several implementations of wire gateways: -LibEuFin is an implementation of the Wire Gateway API for the EBICS protocol. -This section will walk through (1) installing and configuring LibEuFin and -(2) connecting the Taler Exchange to LibEuFin. + * `Project deploymerization `_ implements a wire gateway on top of Bitcoin or Ethereum + * The :ref:`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 ` is an implementation of the Wire Gateway API for the EBICS protocol. Add to list above once nexus implements the TWG directly! -Installation and Basic Configuration ------------------------------------- +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: -First, install the ``libeufin`` package. This can be done on the ``exchange-online`` -machine or a different one. + * The username and password to access the exchange's account in the system. + * The ``payto://`` URI of that account (see `RFC 8905 `_). -.. code-block:: shell-session - - [root@exchange-online]# apt-get install -y libeufin - -The main component of LibEuFin is called the Nexus. It implements a Web -service that provides a JSON abstraction layer to access bank accounts. - -The HTTP port and database connection string can be edited in the configuration: - -.. code-block:: ini - :caption: /etc/libeufin/nexus.env - - LIBEUFIN_NEXUS_PORT=5017 - LIBEUFIN_NEXUS_DB_CONNECTION=jdbc:sqlite:/var/lib/libeufin/nexus/nexus-db.sqlite3 - -After configuring the database, you can start the service. -The database is initialized automatically. - - -.. code-block:: shell-session - - [root@exchange-online]# systemctl enable libeufin-nexus - [root@exchange-online]# systemctl start libeufin-nexus - -You can now create a superuser account. The command to -create the superuser needs direct database access, thus -the configuration file is sourced first, and the relevant -environment variable is exported. - -.. code-block:: console - - [root@exchange-online]# source /etc/libeufin/nexus.env - [root@exchange-online]# export LIBEUFIN_NEXUS_DB_CONNECTION - [root@exchange-online]# NEXUS_ADMIN_PW=$(tr -dc A-Za-z0-9 ` -becomes offered by the Nexus. The purpose is to let a Taler exchange rely on -Nexus to manage its bank account. - -The base URL of the facade that can be used by the Taler exchange -as the Taler Wire Gateway base URL can be seen by listing the facades: - -.. code-block:: console - - [root@exchange-online]# libeufin-cli facades list - -Managing Permissions and Users -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -This guide has so far assumed that a superuser is accessing the LibEuFin Nexus. -However, it is advisable that the Nexus is accessed with users that only have a -minimal set of permissions. - -The Nexus currently only has support for giving non-superusers access to Taler -wire gateway facades. - -To create a new user, use the ``users`` subcommand of the CLI: - -.. code-block:: console - - [root@exchange-online]# libeufin-cli users list - # [ ... shows available users ... ] - - [root@exchange-online]# libeufin-cli users create $USERNAME - # [ ... will prompt for password ... ] - -Permissions are managed with the ``permissions`` subcommand. -The following commands grant permissions to view the transaction history -and create payment initiations with a Taler wire gateway facade: - - -.. code-block:: console - - [root@exchange-online]# libeufin-cli permissions grant \ - user $USERNAME \ - facade $FACADENAME \ - facade.talerwiregateway.history - - [root@exchange-online]# libeufin-cli permissions grant \ - user $USERNAME \ - facade $FACADENAME \ - facade.talerwiregateway.transfer - -.. - FIXME: The two commands above output an empty JSON object - when successful. Possibly, we should suppress that (just like - the other commands do). - -The list of all granted permissions can be reviewed: - -.. code-block:: console - - [root@exchange-online]# libeufin-cli permissions list - - -.. _Bank-account: +.. _exchange-bank-account-configuration: Exchange Bank Account Configuration ----------------------------------- An exchange must be configured with the right settings to access its bank -account via a Taler Wire Gateway. An exchange can be configured to use -multiple bank accounts by using multiple Wire Gateways. Typically only one -Wire Gateway is used. +account via a :ref:`Taler wire gateway `. An +exchange can be configured to use multiple bank accounts by using multiple +wire gateways. Typically only one wire gateway is used. To configure a bank account in Taler, we need to furnish two pieces of information: @@ -1195,8 +858,8 @@ information: an IBAN or ``payto://x-taler-bank/localhost:8080/2`` for the 2nd bank account a the Taler bank demonstrator running at ``localhost`` on port 8080. - The first part of the URI following ``payto://`` (“iban” or - “x-taler-bank”) is called the wire method. + The first part of the URI following ``payto://`` (``iban`` or + ``x-taler-bank``) is called the wire method. - The ``taler-exchange-wirewatch`` and ``taler-exchange-transfer`` tools needs to be provided resources for authentication @@ -1205,20 +868,22 @@ information: for HTTP basic authentication. -A Taler Wire Gateway is configured in a configuration section that follows the -pattern ``exchange-account-$id``, where ``$id`` is an internal identifier for -the bank account accessed by the exchange. The basic information for an +Each Taler wire gateway is configured in a configuration section that follows +the pattern ``exchange-account-$id``, where ``$id`` is an internal identifier +for the bank account accessed by the exchange. The basic information for an account should be put in ``/etc/taler/conf.d/exchange-business.conf``. The secret credentials to access the Taler Wire Gateway API should be put into a corresponding ``exchange-accountcredentials-$id`` section in ``/etc/taler/secrets/exchange-accountcredentials.conf``. The latter file -should already be only readable for the ``taler-exchange-wire`` user. Other -exchange processes should not have access to this information. +should be only readable for the ``taler-exchange-wire`` user. Only the +``taler-exchange-wirewatch`` and ``taler-exchange-transfer`` services should +run as the ``taler-exchange-wire`` user. Other exchange processes do not need +to have access to the account credentials. You can configure multiple accounts for an exchange by creating sections -starting with “exchange-account-” for the section name. You can ENABLE for -each account whether it should be used, and for what (incoming or outgoing -wire transfers): +starting with ``exchange-account-`` for the section name. You must specify +``ENABLE_``-settings for each account whether it should be used, and for what +(incoming or outgoing wire transfers): .. code-block:: ini :caption: /etc/taler/conf.d/exchange-business.conf @@ -1253,15 +918,15 @@ wire transfers): # LibEuFin expects basic auth. WIRE_GATEWAY_AUTH_METHOD = basic - # Username and password set in LibEuFin. + # Username and password to access the Taler wire gateway. USERNAME = ... PASSWORD = ... - # Base URL of the wire gateway set up with LibEuFin. + # Base URL of the Taler wire gateway. WIRE_GATEWAY_URL = ... -Such a Wire Gateway configuration can be tested with the following commands: +Such a wire gateway configuration can be tested with the following commands: .. code-block:: shell-session @@ -1270,7 +935,8 @@ Such a Wire Gateway configuration can be tested with the following commands: [root@exchange-online]# taler-exchange-wire-gateway-client \ --section exchange-accountcredentials-1 --credit-history - +On success, you will see some of your account's transaction history (or an +empty history), while on failure you should see an error message. .. _LegalSetup: @@ -1821,7 +1487,7 @@ The ``enable-account`` step is important to must be used to sign the correct address to wire funds to. Note that for each bank account, additional options **must** be set in the configuration file to tell the exchange how to access the bank account. The offline tool *only* configures the externally -visible portions of the setup. The chapter on `Bank account <_Bank-account>`_ configuration has further details. +visible portions of the setup. The chapter on `bank account configuration <_exchange-bank-account-configuration>`_ has further details. taler-exchange-offline accepts additional options to configure the use of the account. For example, additional options can be used to add currency -- cgit v1.2.3 From 93327c7583bd4d16ee66a2ef2a471e1a7f7d92ea Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Sun, 4 Feb 2024 10:52:25 +0100 Subject: explain DEFAULT_EXCHANGE --- libeufin/bank-manual.rst | 24 +++++++++++++++++++++++- 1 file changed, 23 insertions(+), 1 deletion(-) diff --git a/libeufin/bank-manual.rst b/libeufin/bank-manual.rst index f8f2dd28..c557aa60 100644 --- a/libeufin/bank-manual.rst +++ b/libeufin/bank-manual.rst @@ -253,4 +253,26 @@ up the exchange account. See the section on :ref:`conversion setup `. + +Users can withdraw digital cash from their bank account starting from their +online banking as implemented by the libeufin-bank. However, in this scenario, +the Taler wallet may not already know about an exchange that works with the +respective currency. Thus, the protocol includes the possibility of the bank +*recommending* an exchange service to the wallet, thus providing a sane +default for the wallet to suggest to the user. To do so, the base URL of the +exchange API must be specified in the libeufin-bank configuration: + +.. code-block:: ini + + [libeufin-bank] + DEFAULT_EXCHANGE=${PROTO}://exchange.${DOMAIN_NAME} + +After changing this value, the libeufin-bank service needs to be restarted +to make the change effective. + +.. note:: + + The user may change the default exchange from within the wallet, assuming they know of an alternative exchanges for the currency. -- cgit v1.2.3 From 481b96e0feac9daeb81325acf4b6b8ab13cccceb Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Sun, 4 Feb 2024 10:55:41 +0100 Subject: start on 8174 --- libeufin/regional-manual.rst | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) diff --git a/libeufin/regional-manual.rst b/libeufin/regional-manual.rst index f145b69c..0a13f997 100644 --- a/libeufin/regional-manual.rst +++ b/libeufin/regional-manual.rst @@ -275,8 +275,12 @@ outgoing bank transactions ` (cash out). # systemd enable --now libeufin-nexus-ebics-fetch # systemd enable --now libeufin-nexus-ebics-submit + +Using the Regional Currency +=========================== + Wallet Setup -============ +------------ This section describes the interaction between the Taler graphical wallet (Android, iOS, WebExtensions) and the regional currency system. @@ -286,6 +290,10 @@ be done by scanning a QR code with a ``taler://withdraw-exchange/exchange.$DOMAI URL or by manually entering the URL into the respective ``Add exchange`` dialogue. + +Cash-In +------- + After starting the withdraw process and specifying the desired amount, the wallet should show you the details of the fiat wire transfer that must be made for the cash in to be completed. Once the money has arrived at the fiat bank account, Nexus will @@ -293,6 +301,8 @@ obtain the transaction data and the regional currency bank will create the corresponding amount in regional currency, crediting the GNU Taler exchange account. In turn, the exchange will issue the respective amount to your wallet. +.. FIXME: bad english below + For testing, you should be able to *deposit* regional currency directly into your LibEuFin Bank account from the Taler wallet. Note: the wallet relies on the exchange to perform such deposit. So once the exchange has credited the regional @@ -300,6 +310,12 @@ currency account to your account and assuming the cash out rules are satisfied, should then be able to start a cash out operation. +Cash-Out +-------- + +.. FIXME: #8174 + + Alternative Podman-based Deployment =================================== -- cgit v1.2.3 From eb0bc54fe15afd548ab1617be37616ac826b9c7a Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Sun, 4 Feb 2024 11:36:20 +0100 Subject: document cash-out (#8174) --- libeufin/regional-manual.rst | 56 ++++++++++++++++++++++++++++++++++---------- 1 file changed, 44 insertions(+), 12 deletions(-) diff --git a/libeufin/regional-manual.rst b/libeufin/regional-manual.rst index 0a13f997..3a00a011 100644 --- a/libeufin/regional-manual.rst +++ b/libeufin/regional-manual.rst @@ -294,26 +294,58 @@ dialogue. Cash-In ------- -After starting the withdraw process and specifying the desired amount, the wallet -should show you the details of the fiat wire transfer that must be made for the cash -in to be completed. Once the money has arrived at the fiat bank account, Nexus will +Next, start the withdraw process in the Taler wallet for the respective +currency and specify the desired amount. The wallet will then show you the +details of the fiat wire transfer that must be made for the cash-in to be +completed. Once the money has arrived at the fiat bank account, Nexus will obtain the transaction data and the regional currency bank will create the -corresponding amount in regional currency, crediting the GNU Taler exchange account. -In turn, the exchange will issue the respective amount to your wallet. +corresponding amount in regional currency, crediting the GNU Taler exchange +account. In turn, the exchange will issue the respective amount to your +wallet. + +.. note:: + + Cash-in operations may be subject to conversion rates, conversion fees and + minimum amounts to be transferred. -.. FIXME: bad english below -For testing, you should be able to *deposit* regional currency directly -into your LibEuFin Bank account from the Taler wallet. Note: the wallet relies on the -exchange to perform such deposit. So once the exchange has credited the regional -currency account to your account and assuming the cash out rules are satisfied, you -should then be able to start a cash out operation. +Making payments +--------------- + +For testing, you should be able to *deposit* regional currency directly into +your regional currency libeufin-bank account directly from the Taler wallet. +For this, you primarily need to know your bank account details (which should +be accessible by clicking on your name in the bank Web site after logging in). + +.. note:: + + There may be a short delay between the wallet making the deposit and + the exchange crediting your bank account. This is because the wallet + uses a small wire transfer delay by default when initiating a deposit + into a bank account. + +For production, it is more common for a shop to configure a :ref:`Taler +merchant backend ` or at least use an +instance within such a setup. To configure an instance, you primarily need +again the bank account details to :ref:`setup instance bank accounts +`. Cash-Out -------- -.. FIXME: #8174 +Regional currency accounts that have a positive balance could be eligible for +cash-out. Cash-out operations may again be restricted by the regional +currency operator and will *only* be made to the respective pre-configured +fiat currency bank account. To cash-out, simply log into your regional +currency account, select cash-out, specify the desired amount and pass the +second-factor authorization challenge by entering the TAN you receive at the +registered e-mail address or mobile phone number. + +.. note:: + + Cash-out operations may be subject to conversion rates, conversion fees and + minimum amounts to be transferred. Alternative Podman-based Deployment -- cgit v1.2.3 From cc1c2bf4ea1639f643483119278aea867596a30b Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Sun, 4 Feb 2024 11:41:22 +0100 Subject: fix #8311 --- libeufin/nexus-manual.rst | 20 +++++++++++++++----- 1 file changed, 15 insertions(+), 5 deletions(-) diff --git a/libeufin/nexus-manual.rst b/libeufin/nexus-manual.rst index b8f2458d..e52ff605 100644 --- a/libeufin/nexus-manual.rst +++ b/libeufin/nexus-manual.rst @@ -297,12 +297,22 @@ would download any unseen notifications (as ``camt.054`` files): .. code-block:: console - $ libeufin-nexus ebics-fetch -c "$CONFIG_FILE" --transient + $ libeufin-nexus ebics-fetch -c "$CONFIG_FILE" --transient --debug-ebics + +The ``ebics-fetch`` subcommand will always cause libeufin-nexus to download +the transaction data, parse the CAMT files and import the statements into its +local database. + +The ``--transient`` flag makes the command download and import transaction +data only once and return immediately afterwards. Without the flag, Nexus +will download the transaction records at the frequency specified in the +configuration. + +The ``--debug-ebcis`` flag will cause the CAMT files to be stored in +``$LIBEUFIN_DATA_HOME/camt/$YYYY-MM-DD`` where ``$YYYY-MM-DD`` represents the +date when the download took place. This is mostly useful for debugging. + -The ``--transient`` flag makes the command to download only once and return. If the -bank returned any records, look in ``$LIBEUFIN_DATA_HOME/camt/YYYY-MM-DD`` to find them. -YYYY-MM-DD is the date when the download took place. Without the flag, Nexus will -download the transaction records at the frequency specified in the configuration. Testing -- cgit v1.2.3 From 4be65231eb262bbf1b192edd4beb722d0cac2d56 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Sun, 4 Feb 2024 11:43:24 +0100 Subject: add missing file --- frags/ebics-setup.rst | 0 1 file changed, 0 insertions(+), 0 deletions(-) create mode 100644 frags/ebics-setup.rst diff --git a/frags/ebics-setup.rst b/frags/ebics-setup.rst new file mode 100644 index 00000000..e69de29b -- cgit v1.2.3 From 7e1e2dc83f2ac63ada709f35c23a9bcbb13c6db9 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Mon, 5 Feb 2024 01:17:42 +0100 Subject: deprecate rewards, bump to protocol v8 --- core/api-merchant.rst | 24 ++++++++++++++++++++++-- 1 file changed, 22 insertions(+), 2 deletions(-) diff --git a/core/api-merchant.rst b/core/api-merchant.rst index d4f54fa4..1cf6ccb9 100644 --- a/core/api-merchant.rst +++ b/core/api-merchant.rst @@ -1,6 +1,6 @@ .. This file is part of GNU TALER. - Copyright (C) 2014-2023 Taler Systems SA + Copyright (C) 2014-2024 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 @@ -121,7 +121,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 **6**. + This specification corresponds to ``current`` protocol being version **8**. **Response:** @@ -2698,6 +2698,10 @@ once we got a reply from the exchange. Backend: Giving rewards ----------------------- +.. note:: + + This API is deprecated as of protocol v8. + Rewards are a way for websites to give small amounts of e-cash to visitors (for example as a financial reward for providing information or viewing advertisements). Rewards are non-contractual: neither merchant nor consumer @@ -2708,6 +2712,10 @@ reward. Create reserve -------------- +.. note:: + + This API is deprecated as of protocol v8. + Reserves are basically funds a merchant has provided to an exchange for a rewards campaign. Each reserve has a limited lifetime (say 2--4 weeks). Any funds not used to reward customers will automatically be wired back from the @@ -2909,6 +2917,10 @@ Query funds remaining Authorizing rewards ------------------- +.. note:: + + This API is deprecated as of protocol v8. + .. http:post:: [/instances/$INSTANCE]/private/reserves/$RESERVE_PUB/authorize-reward Authorize creation of a reward from the given reserve. @@ -2983,6 +2995,10 @@ Authorizing rewards Deleting reserves ----------------- +.. note:: + + This API is deprecated as of protocol v8. + .. http:delete:: [/instances/$INSTANCE]/private/reserves/$RESERVE_PUB Delete information about a reserve. Fails if the reserve still has @@ -3008,6 +3024,10 @@ Deleting reserves Checking reward status ---------------------- +.. note:: + + This API is deprecated as of protocol v8. + .. http:get:: [/instances/$INSTANCE]/private/rewards/$REWARD_ID Obtain information about a particular reward. -- cgit v1.2.3 From 79ad50987d5cd670793cf0e75e5cb062770d246c Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Mon, 5 Feb 2024 01:32:26 +0100 Subject: -remove obsolete command --- conf.py | 7 -- manpages/taler-merchant-setup-reserve.1.rst | 119 ---------------------------- 2 files changed, 126 deletions(-) delete mode 100644 manpages/taler-merchant-setup-reserve.1.rst diff --git a/conf.py b/conf.py index 1aae2c40..9e16a795 100644 --- a/conf.py +++ b/conf.py @@ -637,13 +637,6 @@ man_pages = [ "GNU Taler contributors", 1, ), - ( - "manpages/taler-merchant-setup-reserve.1", - "taler-merchant-setup-reserve", - "setup reserve for rewards at a Taler merchant backend", - "GNU Taler contributors", - 1, - ), ( "manpages/taler-exchange-wire-gateway-client.1", "taler-exchange-wire-gateway-client", diff --git a/manpages/taler-merchant-setup-reserve.1.rst b/manpages/taler-merchant-setup-reserve.1.rst deleted file mode 100644 index 73fa2a0c..00000000 --- a/manpages/taler-merchant-setup-reserve.1.rst +++ /dev/null @@ -1,119 +0,0 @@ -taler-merchant-setup-reserve(1) -############################### - - -.. only:: html - - Name - ==== - - **taler-merchant-setup-reserve** - setup reserve for rewards - - -Synopsis -======== - -**taler-merchant-setup-reserve** -[**-A** *USERNAME:PASSWORD* | **--auth=**\ \ *USERNAME:PASSWORD*] -[**-a** *VALUE* | **--amount=**\ \ *VALUE*] -[**-C** *CERTFILE* | **--cert=**\ \ *CERTFILE*] -[**-c** *FILENAME* | **--config=**\ \ *FILENAME*] -[**-e** *URL* | **--exchange-url=**\ \ *URL*] -[**-h** | **--help**] -[**-k** *KEYFILE* | **--key=**\ \ *KEYFILE*] -[**-L** *LOGLEVEL* | **--loglevel=**\ ‌\ *LOGLEVEL*] -[**-l** *FILENAME* | **--logfile=**\ ‌\ *FILENAME*] -[**-m** *URL* | **--merchant-url=**\ \ *URL*] -[**-p** *KEYFILEPASSPHRASE* | **--pass=**\ \ *KEYFILEPASSPHRASE*] -[**-t** *CERTTYPE* | **--type=**\ \ *CERTTYPE*] -[**-w** *METHOD* | **--wire-method=**\ \ *METHOD*] -[**-v** | **--version**] - - -Description -=========== - -**taler-merchant-setup-reserve** is a command-line tool to setup a reserve -(creating the private reserve key) and obtaining the wire transfer information -from the exchange needed to fill the reserve. - - -Options -======= - -**-A** *USERNAME:PASSWORD* \| **--auth=**\ \ *USERNAME:PASSWORD* - Use ``USERNAME`` and ``PASSWORD`` for HTTP client authentication. - The ":" must be present as a separator. - Note that this form of authentication has nothing to do with the TLS client - certificate authentication supported with the ``-C``, ``-k`` and ``-p`` options. - The ``PASSWORD`` given to this option is given to the server! - -**-a** *VALUE* \| **--amount=**\ \ *VALUE* - Mandatory. - Amount to be transferred to the reserve. - -**-C** *CERTFILE* \| **--cert=**\ \ *CERTFILE* - The specified ``CERTFILE`` contains a TLS client certificate to be used to - authenticate the client. See also ``-t``. - -**-c** *FILENAME* \| **--config=**\ \ *FILENAME* - Use the configuration and other resources for the merchant to - operate from ``FILENAME``. - -**-e** *URL* \| **--exchange-url=**\ \ *URL* - Mandatory. - Use ``URL`` for the exchange base URL. - This is the exchange where the reserve will be created. - The currency used in the amount specification must be offered by this exchange. - -**-h** \| **--help** - Print short help on options. - -**-k** *KEYFILE* \| **--key=**\ \ *KEYFILE* - The specified ``KEYFILE`` contains a TLS client private key to be used to - authenticate the client. See also ``-p`` and ``-C``. - -**-L** *LOGLEVEL* \| **--loglevel=**\ ‌\ *LOGLEVEL* - Specifies the log level to use. Accepted values are: ``DEBUG``, ``INFO``, - ``WARNING``, ``ERROR``. - -**-l** *FILENAME* \| **--logfile=**\ ‌\ *FILENAME* - Send logging output to *FILENAME*. - -**-m** *URL* \| **--merchant-url=**\ \ *URL* - Mandatory. - Use ``URL`` as the merchant base URL. - Should include the path to the instance if the reserve is to be - created for a non-default instance. - -**-p** *KEYFILEPASSPHRASE* \| **--pass=**\ \ *KEYFILEPASSPHRASE* - The specified ``KEYFILEPASSPHRASE`` is to be used to decrypt the KEYFILE. - See also ``-k``. Not to be confused with ``-A``. - The ``KEYFILEPASSPHRASE`` given here is only used locally to decrypt the KEYFILE. - -**-t** *CERTTYPE* \| **--type=**\ \ *CERTTYPE* - The specified CERTFILE contains a TLS client certificate of ``CERTTYPE``. - Default is ``PEM``. See also ``-C``. - -**-w** *METHOD* \| **--wire-method=**\ \ *METHOD* - Mandatory. - Which wire method should be used. - Needed to select the wire transfer method of the exchange. - The method must be supported by the exchange. - Typical values would be ``iban`` or ``x-taler-bank``. - -**-v** \| **--version** - Print version information. - - -See Also -======== - -taler-merchant-dbinit(1), taler.conf(5) - - -Bugs -==== - -Report bugs by using https://bugs.taler.net/ or by sending electronic -mail to . -- cgit v1.2.3 From d7d95ad5efa18a3da0dbbb1e8ac7c8b5dca72e59 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Mon, 5 Feb 2024 11:51:00 +0100 Subject: add 'implementation' field to /config responses, for now not mandatory --- core/api-auditor.rst | 5 +++++ core/api-bank-conversion-info.rst | 26 +++++++++++++++----------- core/api-bank-integration.rst | 10 +++++++--- core/api-bank-revenue.rst | 4 ++++ core/api-bank-wire.rst | 4 ++++ core/api-exchange.rst | 5 +++++ core/api-merchant.rst | 4 ++++ core/api-sync.rst | 5 +++++ 8 files changed, 49 insertions(+), 14 deletions(-) diff --git a/core/api-auditor.rst b/core/api-auditor.rst index e837617c..7aae2df5 100644 --- a/core/api-auditor.rst +++ b/core/api-auditor.rst @@ -56,6 +56,7 @@ know-your-customer (KYC) registration before issuing contracts. .. http:get:: /config Get the protocol version and some meta data about the auditor. + This specification corresponds to ``current`` protocol being version **0**. **Response:** @@ -75,6 +76,10 @@ know-your-customer (KYC) registration before issuing contracts. // protocol is versioned independently of the exchange's protocol. version: string; + // URN of the implementation (needed to interpret 'revision' in version). + // @since v0, may become mandatory in the future. + implementation?: string; + // Return which currency this auditor is auditing for. currency: string; diff --git a/core/api-bank-conversion-info.rst b/core/api-bank-conversion-info.rst index 834cac46..322e9403 100644 --- a/core/api-bank-conversion-info.rst +++ b/core/api-bank-conversion-info.rst @@ -48,10 +48,14 @@ is used by wallets for withdrawals that involve a currency conversion. // https://www.gnu.org/software/libtool/manual/html_node/Versioning.html#Versioning // The format is "current:revision:age". version: string; - + // Name of the API. name: "taler-conversion-info"; + // URN of the implementation (needed to interpret 'revision' in version). + // @since v4, may become mandatory in the future. + implementation?: string; + // Currency used by this bank. regional_currency: string; @@ -65,9 +69,9 @@ is used by wallets for withdrawals that involve a currency conversion. fiat_currency_specification: CurrencySpecification; // Additional information on conversion rates. - // Those informations should never be used to perform conversions, + // Those informations should never be used to perform conversions, // use /cashin-rate or /cashout-rate instead. - // Conversion rates can change at any time. Clients must deal with + // Conversion rates can change at any time. Clients must deal with // any resulting errors and call /cashin-rate or /cashout-rate again // to use the new rates. conversion_rate: ConversionRate; @@ -91,7 +95,7 @@ is used by wallets for withdrawals that involve a currency conversion. deducted from their fiat bank account. or - + :query amount_credit: this is the amount that the user will receive in their regional bank account. @@ -100,7 +104,7 @@ is used by wallets for withdrawals that involve a currency conversion. :http:statuscode:`200 OK`: Response is a `CashinConversionResponse`. :http:statuscode:`400 Bad request`: - * ``TALER_EC_GENERIC_PARAMETER_MISSING`` : none of the parameters have been provided. + * ``TALER_EC_GENERIC_PARAMETER_MISSING`` : none of the parameters have been provided. * ``TALER_EC_GENERIC_PARAMETER_MALFORMED`` : both of the parameters have been provided or one of them is not a valid Taler amount. * ``TALER_EC_GENERIC_CURRENCY_MISMATCH`` : the parameter is in the wrong currency. :http:statuscode:`409 Conflict`: @@ -137,7 +141,7 @@ is used by wallets for withdrawals that involve a currency conversion. deducted from their regional bank account. or - + :query amount_credit: this is the amount that the user will receive in their fiat bank account. @@ -146,7 +150,7 @@ is used by wallets for withdrawals that involve a currency conversion. :http:statuscode:`200 OK`: Response is a `CashoutConversionResponse`. :http:statuscode:`400 Bad request`: - * ``TALER_EC_GENERIC_PARAMETER_MISSING`` : none of the parameters have been provided. + * ``TALER_EC_GENERIC_PARAMETER_MISSING`` : none of the parameters have been provided. * ``TALER_EC_GENERIC_PARAMETER_MALFORMED`` : both of the parameters have been provided or one of them is not a valid Taler amount. * ``TALER_EC_GENERIC_CURRENCY_MISMATCH`` : the parameter is in the wrong currency. :http:statuscode:`409 Conflict`: @@ -169,17 +173,17 @@ is used by wallets for withdrawals that involve a currency conversion. .. http:post:: /conversion-rate - This endpoint allows the administrator to update + This endpoint allows the administrator to update the exchange rate between the regional currency and the fiat currency of the banking system. **Request:** .. ts:def:: ConversionRate - + interface ConversionRate { // Exchange rate to buy regional currency from fiat - cashin_ratio: DecimalNumber; + cashin_ratio: DecimalNumber; // Regional amount fee to subtract after applying the cashin ratio. cashin_fee: Amount; @@ -194,7 +198,7 @@ is used by wallets for withdrawals that involve a currency conversion. cashin_rounding_mode: "zero" | "up" | "nearest"; // Exchange rate to sell regional currency for fiat - cashout_ratio: DecimalNumber; + cashout_ratio: DecimalNumber; // Fiat amount fee to subtract after applying the cashout ratio. cashout_fee: Amount; diff --git a/core/api-bank-integration.rst b/core/api-bank-integration.rst index 598ad82f..748d98da 100644 --- a/core/api-bank-integration.rst +++ b/core/api-bank-integration.rst @@ -50,6 +50,10 @@ to tightly integrate with GNU Taler. // The format is "current:revision:age". version: string; + // URN of the implementation (needed to interpret 'revision' in version). + // @since v2, may become mandatory in the future. + implementation?: string; + // Currency used by this bank. currency: string; @@ -169,7 +173,7 @@ for the withdrawal operation (the ``WITHDRAWAL_ID``) to interact with the withdr :http:statuscode:`404 Not found`: The bank does not know about a withdrawal operation with the specified ``WITHDRAWAL_ID``. :http:statuscode:`409 Conflict`: - * ``TALER_EC_BANK_WITHDRAWAL_OPERATION_RESERVE_SELECTION_CONFLICT`` : + * ``TALER_EC_BANK_WITHDRAWAL_OPERATION_RESERVE_SELECTION_CONFLICT`` : The wallet selected a different exchange or reserve public key under the same withdrawal ID. * ``TALER_EC_BANK_DUPLICATE_RESERVE_PUB_SUBJECT`` : the reserve public key is already used. * ``TALER_EC_BANK_UNKNOWN_ACCOUNT`` : the selected exchange account was not found. @@ -208,9 +212,9 @@ for the withdrawal operation (the ``WITHDRAWAL_ID``) to interact with the withdr **Response:** - :http:statuscode:`204 No content`: + :http:statuscode:`204 No content`: The withdrawal operation has been aborted. :http:statuscode:`404 Not found`: The withdrawal operation was not found. - :http:statuscode:`409 Conflict`: + :http:statuscode:`409 Conflict`: The withdrawal operation has been confirmed previously and can't be aborted. diff --git a/core/api-bank-revenue.rst b/core/api-bank-revenue.rst index 0ccc7123..a647fb35 100644 --- a/core/api-bank-revenue.rst +++ b/core/api-bank-revenue.rst @@ -48,6 +48,10 @@ used by the merchant (or other parties) to query for incoming transactions to th // Currency used by this gateway. currency: string; + + // URN of the implementation (needed to interpret 'revision' in version). + // @since v0, may become mandatory in the future. + implementation?: string; } diff --git a/core/api-bank-wire.rst b/core/api-bank-wire.rst index 7c028388..a76f5195 100644 --- a/core/api-bank-wire.rst +++ b/core/api-bank-wire.rst @@ -52,6 +52,10 @@ LibEuFin (work in progress). // Currency used by this gateway. currency: string; + + // URN of the implementation (needed to interpret 'revision' in version). + // @since v0, may become mandatory in the future. + implementation?: string; } -------------- diff --git a/core/api-exchange.rst b/core/api-exchange.rst index 09fbcb8e..c257cf4e 100644 --- a/core/api-exchange.rst +++ b/core/api-exchange.rst @@ -62,6 +62,7 @@ possibly by using HTTPS. as well as the list of possible KYC requirements. This endpoint is largely for the SPA for AML officers. Merchants should use ``/keys`` which also contains the protocol version and currency. + This specification corresponds to ``current`` protocol being version **18**. **Response:** @@ -79,6 +80,10 @@ possibly by using HTTPS. // Name of the protocol. name: "taler-exchange"; + // URN of the implementation (needed to interpret 'revision' in version). + // @since v18, may become mandatory in the future. + implementation?: string; + // Currency supported by this exchange, given // as a currency code ("USD" or "EUR"). currency: string; diff --git a/core/api-merchant.rst b/core/api-merchant.rst index 1cf6ccb9..2ecb492e 100644 --- a/core/api-merchant.rst +++ b/core/api-merchant.rst @@ -139,6 +139,10 @@ such as the implemented version of the protocol and the currency used. // Name of the protocol. name: "taler-merchant"; + // URN of the implementation (needed to interpret 'revision' in version). + // @since v8, may become mandatory in the future. + implementation?: string; + // Default (!) currency supported by this backend. // This is the currency that the backend should // suggest by default to the user when entering diff --git a/core/api-sync.rst b/core/api-sync.rst index 69f59696..51d2b674 100644 --- a/core/api-sync.rst +++ b/core/api-sync.rst @@ -114,6 +114,7 @@ Receiving Configuration .. http:get:: /config Obtain the key configuration settings of the storage service. + This specification corresponds to ``current`` protocol being version **2**. **Response:** @@ -139,6 +140,10 @@ Receiving Configuration // The format is "current:revision:age". version: string; + // URN of the implementation (needed to interpret 'revision' in version). + // @since v2, may become mandatory in the future. + implementation?: string; + } .. _sync: -- cgit v1.2.3 From b3d250485a0fd894783b17b2f04c2318ebf4aa1b Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Mon, 5 Feb 2024 11:52:53 +0100 Subject: return 'implementation' field in /config responses --- core/api-challenger.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/core/api-challenger.rst b/core/api-challenger.rst index 00035c52..45fc5df8 100644 --- a/core/api-challenger.rst +++ b/core/api-challenger.rst @@ -98,6 +98,7 @@ Receiving Configuration .. http:get:: /config Obtain the key configuration settings of the storage service. + This specification corresponds to ``current`` protocol being version **0**. **Response:** @@ -114,6 +115,10 @@ Receiving Configuration // The format is "current:revision:age". version: string; + // URN of the implementation (needed to interpret 'revision' in version). + // @since v0, may become mandatory in the future. + implementation?: string; + } .. _challenger-setup: -- cgit v1.2.3 From b711253326cd192c34a75d19e6180f291863556b Mon Sep 17 00:00:00 2001 From: Antoine A <> Date: Mon, 5 Feb 2024 19:07:32 +0100 Subject: Update libeufin doc --- core/api-corebank.rst | 6 +++++- libeufin/nexus-manual.rst | 32 +++++++++++++++----------------- manpages/libeufin-bank.conf.5.rst | 4 ++-- manpages/libeufin-nexus.1.rst | 20 ++++++++++++++++++++ 4 files changed, 42 insertions(+), 20 deletions(-) diff --git a/core/api-corebank.rst b/core/api-corebank.rst index 1fb8fb43..a4cbe09a 100644 --- a/core/api-corebank.rst +++ b/core/api-corebank.rst @@ -1,7 +1,7 @@ .. This file is part of GNU TALER. - Copyright (C) 2014-2023 Taler Systems SA + Copyright (C) 2014-2024 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 @@ -114,6 +114,10 @@ Config // TAN channels supported by the server supported_tan_channels: TanChannel[]; + + // Wire transfer type supported by the bank. + // Default to 'iban' is missing + wire_type?: string; } diff --git a/libeufin/nexus-manual.rst b/libeufin/nexus-manual.rst index e52ff605..4f75ea72 100644 --- a/libeufin/nexus-manual.rst +++ b/libeufin/nexus-manual.rst @@ -271,26 +271,24 @@ initiated payment according to their submission state, and return. Downloading payment records =========================== -Downloading payment records requires that the `EBICS subscriber setup -`_, where the bank obtained the subscriber keys and the -subscriber accepted the bank keys has been completed. - -The configuration file must contain all the ``[ebics-setup]`` sections, plus -the following values to set the database connection and a log directory where -any downloaded record would be stored. - -.. code-block:: ini +Downloading payments must follow a successful `EBICS subscriber setup +`_, where the bank obtained the subscriber keys, and the +subscriber accepted the bank keys. Furthermore, the database has to +be set up. - [nexus-postgres] - config = postgres:///nexus +The responsible subcommand for sending payments is ``ebics-fetch``, and its +configuration is a **superset** of core-config_. On top of that, it expects +the database connection string and *optionally* a frequency at which it will +downloads any unseen notifications and ingest them in the database. -To activate periodic downloads, add the following setting to the ``nexus-fetch`` -configuration section in ``$CONFIG_FILE``: +The frequency **may** be specified as .. code-block:: ini - [nexus-fetch] - FREQUENCY = 5m + [nexus-fetch] + FREQUENCY = 5m + +The supported time units are ``s`` (seconds), ``m`` (minutes), ``h`` (hours). Assuming that ``$CONFIG_FILE`` contains all required options, the following command would download any unseen notifications (as ``camt.054`` files): @@ -315,8 +313,8 @@ date when the download took place. This is mostly useful for debugging. -Testing -------- +For Testing +----------- If the bank account history has transactions that are useful for testing, it is possible to re-download them via the ``--pinned-start`` argument. diff --git a/manpages/libeufin-bank.conf.5.rst b/manpages/libeufin-bank.conf.5.rst index 30e8d9ab..6830c405 100644 --- a/manpages/libeufin-bank.conf.5.rst +++ b/manpages/libeufin-bank.conf.5.rst @@ -35,8 +35,8 @@ The following options are from the “[libeufin-bank]” section. CURRENCY Internal currency of the libeufin-bank, e.g. “EUR” for Euro. -PAYMENT_METHOD - Supported payment method, this can either be ``iban`` or ``x-taler-bank`` +WIRE_TYPE + Supported payment target type, this can either be ``iban`` or ``x-taler-bank`` IBAN_PAYTO_BIC Bank BIC used in generated iban payto URI diff --git a/manpages/libeufin-nexus.1.rst b/manpages/libeufin-nexus.1.rst index 70a137b3..d4922a99 100644 --- a/manpages/libeufin-nexus.1.rst +++ b/manpages/libeufin-nexus.1.rst @@ -115,6 +115,26 @@ This subcommand downloads banking records via EBICS and stores them into the dat **--pinned-start** Only supported in --transient mode, this option lets specify the earliest timestamp of the downloaded documents. The latest timestamp is always the current time. +initiate-payment +---------------- + +This subcommand initiates an outgoing payment. The pending payment is stored in the database and will be performed the next time ``ebics-submit`` run. + +It takes one argument, the creditor IBAN payto URI, which must contain a 'receiver-name' and may contain an 'amount' and a 'message' if they have not been defined using CLI options. + +**-h** \| **--help** + Print short help on options. +**-c** \| **--config** *FILENAME* + Specifies the configuration file. +**-L** \| **--log** *LOGLEVEL* + Configure logging to use LOGLEVEL. +**--amount** *AMOUNT* + The amount to transfer, payto 'amount' parameter takes the precedence +**--subject** *TEXT* + The payment subject, payto 'message' parameter takes the precedence +**--request-uid** *TEXT* + The payment request UID, will be randomly generated if missing. + .. include:: ../frags/libeufin-config-cli.rst SEE ALSO -- cgit v1.2.3 From b4a9c9812e3c1e40d383742298f9f92efa447e74 Mon Sep 17 00:00:00 2001 From: Antoine A <> Date: Mon, 5 Feb 2024 19:07:32 +0100 Subject: Update libeufin doc --- libeufin/nexus-manual.rst | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/libeufin/nexus-manual.rst b/libeufin/nexus-manual.rst index 4f75ea72..9a1199aa 100644 --- a/libeufin/nexus-manual.rst +++ b/libeufin/nexus-manual.rst @@ -212,16 +212,13 @@ subject that would be invalid for a Taler withdrawal, or from a Taler exchange that needs to send a payment to a merchant. For testing purposes it is possible to manually initiate a payment using the -``contrib/payment_initiation_debug.sh`` script from the libeufin repository. -The script currently always pays one Swiss Franc to the given IBAN and -wire transfer subject given as arguments. - +``initiate-payment``subcommand. The following invocation pays 1 CHF to the CH987654321 with an "Hello, Nexus!" subject: .. code-block:: console - $ ./payment_initiation_debug.sh "$CONFIG_FILE" CH987654321 "Hello, Nexus!" + $ libeufin-nexus initiate-payment -c "$CONFIG_FILE" --subject "Hello, Nexus!" "payto://iban/CH987654321?receiver-name=Name&amount=CHF:1" ``$CONFIG_FILE`` is the path to Nexus' configuration file and it does not need the FREQUENCY value. If the previous command worked, now the database should -- cgit v1.2.3 From dd09a8d0b3dec2a99b6e26af48fb309b41e40c39 Mon Sep 17 00:00:00 2001 From: Antoine A <> Date: Mon, 5 Feb 2024 19:20:27 +0100 Subject: Update corebank API --- core/api-corebank.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/core/api-corebank.rst b/core/api-corebank.rst index a4cbe09a..7a503f46 100644 --- a/core/api-corebank.rst +++ b/core/api-corebank.rst @@ -117,6 +117,7 @@ Config // Wire transfer type supported by the bank. // Default to 'iban' is missing + // @since v4, may become mandatory in the future. wire_type?: string; } -- cgit v1.2.3 From 7e6ab6e7dd3f863d811d70a91c16f43602e09c50 Mon Sep 17 00:00:00 2001 From: Antoine A <> Date: Tue, 6 Feb 2024 16:25:50 +0100 Subject: Update libeufin doc --- libeufin/bank-manual.rst | 14 +++++++------- manpages/libeufin-bank.conf.5.rst | 7 +++++-- manpages/libeufin-nexus.conf.5.rst | 12 +++++++++++- 3 files changed, 23 insertions(+), 10 deletions(-) diff --git a/libeufin/bank-manual.rst b/libeufin/bank-manual.rst index c557aa60..83f25f6a 100644 --- a/libeufin/bank-manual.rst +++ b/libeufin/bank-manual.rst @@ -87,13 +87,13 @@ The following snippet shows the mandatory configuration values: [libeufin-bank] CURRENCY = KUDOS - - # Server - SERVE = tcp - PORT = 8080 - - [libeufin-bankdb-postgres] - CONFIG = postgresql:///libeufinbank + + # Supported payment target type + WIRE_TYPE = iban or x-taler-bank + # If WIRE_TYPE = iban + IBAN_PAYTO_BIC = SANDBOXX + # If WIRE_TYPE = x-taler-bank + X_TALER_BANK_PAYTO_HOSTNAME = https://bank.taler.net .. note:: Refer to the manpage ``libeufin-man.conf(5)`` diff --git a/manpages/libeufin-bank.conf.5.rst b/manpages/libeufin-bank.conf.5.rst index 6830c405..a33d6f49 100644 --- a/manpages/libeufin-bank.conf.5.rst +++ b/manpages/libeufin-bank.conf.5.rst @@ -39,10 +39,10 @@ WIRE_TYPE Supported payment target type, this can either be ``iban`` or ``x-taler-bank`` IBAN_PAYTO_BIC - Bank BIC used in generated iban payto URI + Bank BIC used in generated iban payto URI. Required if WIRE_TYPE = iban X_TALER_BANK_PAYTO_HOSTNAME - Bank hostname used in generated x-taler-bank payto URI + Bank hostname used in generated x-taler-bank payto URI. Required if WIRE_TYPE = x-taler-bank DEFAULT_DEBT_LIMIT Default debt limit for newly created accounts. Defaults to CURRENCY:0 if not specified. @@ -95,6 +95,9 @@ following value. CONFIG PostgreSQL connection string. +SQL_DIR + Where are the SQL files to setup our tables? + SEE ALSO ======== diff --git a/manpages/libeufin-nexus.conf.5.rst b/manpages/libeufin-nexus.conf.5.rst index 1ebe8b67..8b281f7f 100644 --- a/manpages/libeufin-nexus.conf.5.rst +++ b/manpages/libeufin-nexus.conf.5.rst @@ -130,7 +130,6 @@ PARTNER_ID EBICS specific: partner ID of the EBICS subscriber. This value must be assigned by the bank after having activated a new EBICS subscriber. - BANK_PUBLIC_KEYS_FILE Filesystem location where Nexus should store the bank public keys. @@ -165,6 +164,17 @@ FREQUENCY Duration value to instruct the ``ebics-fetch`` subcommand how often it should download from the bank. +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? + SEE ALSO ======== -- cgit v1.2.3 From 7444aabbcc51fc6069be52dd64f6022658ed6898 Mon Sep 17 00:00:00 2001 From: Antoine A <> Date: Tue, 6 Feb 2024 18:21:11 +0100 Subject: Update libeufin doc --- libeufin/nexus-manual.rst | 28 ++++++++++++++-------------- manpages/libeufin-nexus.1.rst | 2 +- 2 files changed, 15 insertions(+), 15 deletions(-) diff --git a/libeufin/nexus-manual.rst b/libeufin/nexus-manual.rst index 9a1199aa..9b71249d 100644 --- a/libeufin/nexus-manual.rst +++ b/libeufin/nexus-manual.rst @@ -236,8 +236,9 @@ send it to the bank. The ``--transient`` flag instructs the software to perform only one pass on the database, submit what is submittable, and return. -Alternatively, the ``--debug`` flag makes ebics-submit accept data from STDIN, -and submit it to the bank. +The ``--debug-ebics $SAVEDIR`` flag will cause the files to be stored in +``$SAVEDIR/$YYYY-MM-DD/submit`` where ``$YYYY-MM-DD`` represents the +date when the upload took place. This is mostly useful for debugging. For production -------------- @@ -276,7 +277,7 @@ be set up. The responsible subcommand for sending payments is ``ebics-fetch``, and its configuration is a **superset** of core-config_. On top of that, it expects the database connection string and *optionally* a frequency at which it will -downloads any unseen notifications and ingest them in the database. +downloads any new EBICS files and ingest them in the database. The frequency **may** be specified as @@ -287,24 +288,23 @@ The frequency **may** be specified as The supported time units are ``s`` (seconds), ``m`` (minutes), ``h`` (hours). -Assuming that ``$CONFIG_FILE`` contains all required options, the following command -would download any unseen notifications (as ``camt.054`` files): +Assuming that ``$CONFIG_FILE`` contains all required options, the following +command would download any unseen EBICS files: .. code-block:: console - $ libeufin-nexus ebics-fetch -c "$CONFIG_FILE" --transient --debug-ebics + $ libeufin-nexus ebics-fetch -c "$CONFIG_FILE" --transient The ``ebics-fetch`` subcommand will always cause libeufin-nexus to download -the transaction data, parse the CAMT files and import the statements into its -local database. +then parse EBICS files and ingest their content statements into its local +database. -The ``--transient`` flag makes the command download and import transaction -data only once and return immediately afterwards. Without the flag, Nexus -will download the transaction records at the frequency specified in the -configuration. +The ``--transient`` flag makes the command download and import EBICS files only +once and return immediately afterwards. Without the flag, Nexus +will download at the frequency specified in the configuration. -The ``--debug-ebcis`` flag will cause the CAMT files to be stored in -``$LIBEUFIN_DATA_HOME/camt/$YYYY-MM-DD`` where ``$YYYY-MM-DD`` represents the +The ``--debug-ebics $SAVEDIR`` flag will cause the files to be stored in +``$SAVEDIR/$YYYY-MM-DD/fetch`` where ``$YYYY-MM-DD`` represents the date when the download took place. This is mostly useful for debugging. diff --git a/manpages/libeufin-nexus.1.rst b/manpages/libeufin-nexus.1.rst index d4922a99..7a8abd00 100644 --- a/manpages/libeufin-nexus.1.rst +++ b/manpages/libeufin-nexus.1.rst @@ -99,7 +99,7 @@ Its options are as follows: ebics-fetch ----------- -This subcommand downloads banking records via EBICS and stores them into the database. Along the download, ebics-fetch would bounce incoming payments that do not have a valid Taler subject, or as well those with an already existing valid subject. Valid incoming payments are then stored in the database so that they can trigger Taler withdrawals. Along this process, ebics-submit would as well reconcile initiated outgoing payments with any outgoing transactions that shows up in the downloaded records. +This subcommand downloads and parse EBICS files and ingest them into the database. Along the download, ebics-fetch would bounce incoming payments that do not have a valid Taler subject, or as well those with an already existing valid subject. Valid incoming payments are then stored in the database so that they can trigger Taler withdrawals. Along this process, ebics-submit would as well reconcile initiated outgoing payments with any outgoing transactions that shows up in the downloaded records. **-h** \| **--help** Print short help on options. -- cgit v1.2.3 From 9aeb3617a2ea3b649c79432718aa884ba29fd4d9 Mon Sep 17 00:00:00 2001 From: Sebastian Date: Tue, 6 Feb 2024 18:30:15 -0300 Subject: clarify some requirements for merchant and wallet integration --- design-documents/035-regional-currencies.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/design-documents/035-regional-currencies.rst b/design-documents/035-regional-currencies.rst index 8be7ea49..3d62dcc3 100644 --- a/design-documents/035-regional-currencies.rst +++ b/design-documents/035-regional-currencies.rst @@ -30,6 +30,11 @@ Requirements * Regional currencies should be easy to use as well * It must be easy to integrate regional/official currencies with the existing Taler auditor/exchange structure +* Wallet users should be able to see disagregated balance between global currencies + and regional currencies supported by different exchanges even if the currency + name is equal. +* Merchants should be able to accept regional and global currencies based on the + supported exchange list. Proposed Solution ================= -- cgit v1.2.3 From ed58cbe6c34993272d40bf10d401042ab09fdc4b Mon Sep 17 00:00:00 2001 From: Antoine A <> Date: Wed, 7 Feb 2024 14:51:25 +0100 Subject: Update libeufin doc --- libeufin/nexus-manual.rst | 6 ++++++ manpages/libeufin-nexus.1.rst | 8 +++++++- 2 files changed, 13 insertions(+), 1 deletion(-) diff --git a/libeufin/nexus-manual.rst b/libeufin/nexus-manual.rst index 9b71249d..68613854 100644 --- a/libeufin/nexus-manual.rst +++ b/libeufin/nexus-manual.rst @@ -299,6 +299,12 @@ The ``ebics-fetch`` subcommand will always cause libeufin-nexus to download then parse EBICS files and ingest their content statements into its local database. +The files type can be given as an argument to select what will be fetched. If no argument is given, all supported files are fetched. The following files are supported: + +* ``acknowledgement``: EBICS acknowledgement, retrieves the status of EBICS orders. +* ``status``: Payment status, retrieves status of pending debits. +* ``notification``: Debit & credit notifications, retrieves the history of confirmed debits and credits. + The ``--transient`` flag makes the command download and import EBICS files only once and return immediately afterwards. Without the flag, Nexus will download at the frequency specified in the configuration. diff --git a/manpages/libeufin-nexus.1.rst b/manpages/libeufin-nexus.1.rst index 7a8abd00..a0ed99ff 100644 --- a/manpages/libeufin-nexus.1.rst +++ b/manpages/libeufin-nexus.1.rst @@ -99,7 +99,13 @@ Its options are as follows: ebics-fetch ----------- -This subcommand downloads and parse EBICS files and ingest them into the database. Along the download, ebics-fetch would bounce incoming payments that do not have a valid Taler subject, or as well those with an already existing valid subject. Valid incoming payments are then stored in the database so that they can trigger Taler withdrawals. Along this process, ebics-submit would as well reconcile initiated outgoing payments with any outgoing transactions that shows up in the downloaded records. +This subcommand downloads and parse EBICS files and ingest them into the database. Along the download, ebics-fetch would bounce incoming payments that do not have a valid Taler subject, or as well those with an already existing valid subject. Valid incoming payments are then stored in the database so that they can trigger Taler withdrawals. Along this process, ebics-submit would as well reconcile initiated outgoing payments with any outgoing transactions that show up in the downloaded records. + +The files type can be given as an argument to select what will be fetched. If no argument is given, all supported files are fetched. The following files are supported: + +* ``acknowledgement``: EBICS acknowledgement, retrieves the status of EBICS orders. +* ``status``: Payment status, retrieves status of pending debits. +* ``notification``: Debit & credit notifications, retrieves the history of confirmed debits and credits. **-h** \| **--help** Print short help on options. -- cgit v1.2.3 From e7abc4f2119c778a79983d49887a9426de6f0d25 Mon Sep 17 00:00:00 2001 From: Florian Dold Date: Thu, 8 Feb 2024 15:42:05 +0100 Subject: draft intro to bank integration --- core/index-bank-apis.rst | 1 + core/intro-bank-apis.rst | 105 +++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 106 insertions(+) create mode 100644 core/intro-bank-apis.rst diff --git a/core/index-bank-apis.rst b/core/index-bank-apis.rst index ad3bae1c..f108df32 100644 --- a/core/index-bank-apis.rst +++ b/core/index-bank-apis.rst @@ -27,6 +27,7 @@ Bank RESTful APIs .. toctree:: :maxdepth: 1 + intro-bank-apis api-corebank api-bank-wire api-bank-revenue diff --git a/core/intro-bank-apis.rst b/core/intro-bank-apis.rst new file mode 100644 index 00000000..df14a688 --- /dev/null +++ b/core/intro-bank-apis.rst @@ -0,0 +1,105 @@ +################################################ +Introduction to Taler (Core-)Banking Integration +################################################ + +This chapter provides an overview of the different ways that a bank or core +banking system can provide integration with GNU Taler. + + +Settlement Account Access +######################### + +To make a GNU Taler deployment possible, the exchange service needs API access +to a settlement bank account. The settlement account is used to fund digital +cash withdrawals into users' Taler wallets, as well as to pay out merchants +that deposited digital cash with the exchange. + +The following two operations need to be supported by the settlement account: + +1. Querying transactions on the settlement account. +2. Initiating payments (simple credit transfer). + +Note that there is only **one** settlement account needed per Taler deployment. +There is no per-user settlement account. Thus, creating or managing bank +accounts is not a requirement. + +A core banking system could directly provide the HTTP/REST APIs +consumed by the Taler exchange (:doc:`api-bank-integration`). Otherwise, an adapter (typically part +of the libeufin component) needs to be written. + + +Improved Withdrawal Process +########################### + +In principle, any typical account-based (core-)banking system can be used as +the underlying account-based financial layer for GNU Taler. + +However, without extra support from the bank, the user experience for Taler +withdrawals is not ideal. + +Withdrawals without any extra support from the core banking system require the +user to make a transaction to a particular bank account (i.e. the exchange's +settlement account) with a rather long cryptographic identifier in the subject. +This identifier is generated by the user's wallet when initiating a withdrawal +from the wallet application. If the user misspells the identifier, the payment +will be sent back automatically by the exchange. + +However, the wallet has no information about whether bank the transfer was +already made by the user or if it was even made correctly. This makes it hard +to show accurate information to the user about the status of withdrawing +digital cash into their Taler wallet. + + +Withdrawal Bank-Integration API +=============================== + +A core banking system can provide better support for GNU Taler withdrawals by +allowing users to initiate *Taler withdrawal operations* from their bank +account (e.g. in their banking app or online banking). A Taler withdrawal +operation has a unique identifier (chosen/generated by the core banking +system), called the WOPID (Withdrawal Operation Identifier). + +The core banking system can provide a (public) API to access withdrawal +operations (:doc:`api-bank-integration`). + +The wallet learns the WOPID and API address via a ``taler://withdraw/...`` +QR-Code or link. + +The wallet generates the cryptographic identifiers required for the withdrawal, +allows the user to choose an exchange (the bank may suggest a default one!), +and then submits this information (chose exchange, reserve public key) for the +respective WOPID to the bank-integration API. + +The user can then confirm (or abort!) the withdrawal on their bank account. + +In the Taler wallet app, the user can now always see the accurate status of +their withdrawal operation (e.g. bank transfer done, aborted, confirmation/2FA +pending). + + +Payto-URI Integration +===================== + +When initiating a withdrawal from the Taler wallet, the wallet can generate a +payto:// link or QR code with the payment information necessary to make a +credit transfer to the exchange's settlement account. + +Banking apps may provide integration here simply by handling payto:// URIs. + +Integration based on payto:// URIs prevents mistakes in typing the +cryptographic identifier and bank account number during withdrawals. However, +it still does not allow the wallet do accurately show the status of a +withdrawal to the user. + + +Future: Intent-Based Integration on Android +=========================================== + +(This type of integration is currently not specified, but planned for the future.) + +On the Android platform, applications can communicate via Intents. That would +allow the Taler wallet to open a credit transfer dialog in a supported banking +app to fund a withdrawal. The banking app can send the status of the credit +transfer (confirmed/aborted by the user) back to the wallet, which can then +show more accurate status information about the withdrawal to the user. + -- cgit v1.2.3 From bafaa3e4f58e5f64a7ccc4bdd6f4315e247955fd Mon Sep 17 00:00:00 2001 From: Florian Dold Date: Thu, 8 Feb 2024 15:55:28 +0100 Subject: -clarifications --- core/intro-bank-apis.rst | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/core/intro-bank-apis.rst b/core/intro-bank-apis.rst index df14a688..2077a893 100644 --- a/core/intro-bank-apis.rst +++ b/core/intro-bank-apis.rst @@ -67,11 +67,15 @@ QR-Code or link. The wallet generates the cryptographic identifiers required for the withdrawal, allows the user to choose an exchange (the bank may suggest a default one!), -and then submits this information (chose exchange, reserve public key) for the +and then submits this information (chosen exchange, reserve public key) for the respective WOPID to the bank-integration API. -The user can then confirm (or abort!) the withdrawal on their bank account. +The user can then confirm the withdrawal by completing the 2FA of +their bank account for the operation. (Alternatively, the user can abort the operation +in their banking client / 2FA app.) +The wallet can continuously query the status of the withdrawal operation (via +the API address and WOPID). In the Taler wallet app, the user can now always see the accurate status of their withdrawal operation (e.g. bank transfer done, aborted, confirmation/2FA pending). -- cgit v1.2.3 From cefce8c998893ad8b2e53a1a9f5b01bbec8fdc7d Mon Sep 17 00:00:00 2001 From: Florian Dold Date: Thu, 8 Feb 2024 16:10:13 +0100 Subject: -clarifications --- core/intro-bank-apis.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/core/intro-bank-apis.rst b/core/intro-bank-apis.rst index 2077a893..ad97a36f 100644 --- a/core/intro-bank-apis.rst +++ b/core/intro-bank-apis.rst @@ -74,6 +74,11 @@ The user can then confirm the withdrawal by completing the 2FA of their bank account for the operation. (Alternatively, the user can abort the operation in their banking client / 2FA app.) +Upon completion of the 2FA / confirmation step, the core banking system +initiates a credit transfer for the withdrawal operations (with the chosen +exchange as the creditor and the cryptographic identifier / reserve pub in the +subject). Afterwards, the withdrawal operation is marked as done. + The wallet can continuously query the status of the withdrawal operation (via the API address and WOPID). In the Taler wallet app, the user can now always see the accurate status of -- cgit v1.2.3 From b864feead778b0f6a4c23af4f1f970b50efcadfc Mon Sep 17 00:00:00 2001 From: Mikolai Gütschow Date: Thu, 8 Feb 2024 16:41:24 +0100 Subject: api-{common,exchange,merchant}: fix some API types --- core/api-common.rst | 21 ++++++++++++++++++++- core/api-exchange.rst | 7 ++----- core/api-merchant.rst | 2 +- 3 files changed, 23 insertions(+), 7 deletions(-) diff --git a/core/api-common.rst b/core/api-common.rst index a6bb9abe..863d3099 100644 --- a/core/api-common.rst +++ b/core/api-common.rst @@ -543,7 +543,7 @@ Blinded coin // coin's `public EdDSA key `. interface RSACoinEnvelope { cipher: "RSA" | "RSA+age_restricted"; - rsa_blinded_planchet: string; // Crockford `Base32` encoded + rsa_blinded_planchet: BlindedRsaSignature; } .. ts:def:: CSCoinEnvelope @@ -567,6 +567,25 @@ Blinded coin type DenominationBlindingKeyP = string; +. _unblinded-coin: + +Unblinded coin +^^^^^^^^^^^^^^ + +.. ts:def:: UnblindedSignature + + // The type of a coin's unblinded signature depends on the cipher that was used + // for signing with a denomination key. + // Note that for now, only RSA is supported. + type UnblindedSignature = RsaUnblindedSignature; + +.. ts:def:: RsaUnblindedSignature + + interface RsaUnblindedSignature { + cipher: "RSA"; + rsa_signature: RsaSignature; + } + .. _signature: diff --git a/core/api-exchange.rst b/core/api-exchange.rst index c257cf4e..404e9706 100644 --- a/core/api-exchange.rst +++ b/core/api-exchange.rst @@ -3398,7 +3398,7 @@ the API during normal operation. // Melt commitment. Hash over the various coins to be withdrawn. // See also ``TALER_refresh_get_commitment()``. - rc: TALER_RefreshCommitmentP; + rc: HashCode; // Master seed for the Clause-schnorr R-value // creation. Must match the /csr-melt request. @@ -3545,10 +3545,7 @@ the API during normal operation. .. ts:def:: RevealResponse - interface RevealResponse { - // List of the exchange's blinded RSA signatures on the new coins. - ev_sigs : Array<{ ev_sig: BlindedDenominationSignature }>; - } + type RevealResponse = BatchWithdrawResponse; .. ts:def:: RevealConflictResponse diff --git a/core/api-merchant.rst b/core/api-merchant.rst index 2ecb492e..3582e628 100644 --- a/core/api-merchant.rst +++ b/core/api-merchant.rst @@ -368,7 +368,7 @@ Making the payment coin_pub: EddsaPublicKey; // Signature made by the denomination public key. - ub_sig: RsaSignature; + ub_sig: UnblindedSignature; // The hash of the denomination public key associated with this coin. h_denom: HashCode; -- cgit v1.2.3 From cdcbf16507936e91b5649957ecaaf27032c501f6 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Mon, 5 Feb 2024 22:22:29 +0100 Subject: document 308 redirect for deprecated /instances/default/* URLs --- core/api-merchant.rst | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/core/api-merchant.rst b/core/api-merchant.rst index 3582e628..652c7303 100644 --- a/core/api-merchant.rst +++ b/core/api-merchant.rst @@ -36,11 +36,13 @@ This is useful when multiple businesses want to share the same payment infrastructure. Merchant backends have one special ``default`` instance. This ``default`` -instance is used when no explicit instance is specified. Despite its name, -this instance must be created after the installation. In case *no* default -instance is found - or its credentials got lost -, the administrator can use -the default instance's rights by resorting on the ``--auth`` command line option, -or by restarting the service by providing an environment variable called +instance is used when no explicit instance is specified. Note that using +``/instances/default/$ANYTHING`` is deprecated and will result in a permanent +redirect (HTTP status 308) to ``$ANYTHING``. a Despite its name, this instance +must be created after the installation. In case *no* default instance is +found - or its credentials got lost -, the administrator can use the default +instance's rights by resorting on the ``--auth`` command line option, or by +restarting the service by providing an environment variable called ``TALER_MERCHANT_TOKEN``. Each instance (default and others) has a base URL. The resources under @@ -74,10 +76,10 @@ Examples: https://merchant-backend.example.com/instances/myinst/orders/ABCD A private endpoint (explicit "default" instance): - https://merchant-backend.example.com/instances/default/private/orders + https://merchant-backend.example.com/private/orders A public endpoint (explicit "default" instance): - https://merchant-backend.example.com/instances/default/orders + https://merchant-backend.example.com/orders Endpoints to manage other instances (ONLY for implicit "default" instance): https://merchant-backend.example.com/management/instances -- cgit v1.2.3 From cea05d8bd8e7c39a7e909463d4dd840d4dd3d2e3 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Thu, 8 Feb 2024 16:32:54 +0100 Subject: document auditor API changes --- core/api-auditor.rst | 7 ++++++- manpages/taler.conf.5.rst | 4 +++- 2 files changed, 9 insertions(+), 2 deletions(-) diff --git a/core/api-auditor.rst b/core/api-auditor.rst index 7aae2df5..dcb39864 100644 --- a/core/api-auditor.rst +++ b/core/api-auditor.rst @@ -56,7 +56,7 @@ know-your-customer (KYC) registration before issuing contracts. .. http:get:: /config Get the protocol version and some meta data about the auditor. - This specification corresponds to ``current`` protocol being version **0**. + This specification corresponds to ``current`` protocol being version **1**. **Response:** @@ -85,6 +85,10 @@ know-your-customer (KYC) registration before issuing contracts. // EdDSA master public key of the auditor. auditor_public_key: EddsaPublicKey; + + // EdDSA master public key of the exchange. + // Added in protocol v1. + exchange_master_public_key: EddsaPublicKey; } .. note:: @@ -231,6 +235,7 @@ paid out first. // Master public key of the exchange corresponding to ``master_sig``. // Identifies the exchange this is about. + // @deprecated since v1 (now ignored, global per auditor) master_pub: EddsaPublicKey; // When does the validity of the exchange_pub end? diff --git a/manpages/taler.conf.5.rst b/manpages/taler.conf.5.rst index 09b993e0..191c7e59 100644 --- a/manpages/taler.conf.5.rst +++ b/manpages/taler.conf.5.rst @@ -151,7 +151,9 @@ BIND_TO MASTER_PUBLIC_KEY Crockford Base32-encoded master public key, public version of the - exchange's long-time offline signing key. + exchange's long-time offline signing key. This configuration option + is also used by the **auditor** to determine the public key of the + exchange which it is auditing. AML_THRESHOLD Largest amount in this currency that can be transferred per month without -- cgit v1.2.3 From ab72f7349e965768ade45b5edd68c31d1cf8298a Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Thu, 8 Feb 2024 16:36:46 +0100 Subject: /wire endpoint died a long time ago, fix spec to match implementations, thanks to Mikolai for pointing it out --- core/api-exchange.rst | 187 ++++++++++++++++++++------------------------------ 1 file changed, 76 insertions(+), 111 deletions(-) diff --git a/core/api-exchange.rst b/core/api-exchange.rst index 404e9706..0e79ae6b 100644 --- a/core/api-exchange.rst +++ b/core/api-exchange.rst @@ -255,6 +255,79 @@ possibly by using HTTPS. } + The specification for the account object is: + + .. ts:def:: WireAccount + + interface WireAccount { + // ``payto://`` URI identifying the account and wire method + payto_uri: string; + + // URI to convert amounts from or to the currency used by + // this wire account of the exchange. Missing if no + // conversion is applicable. + conversion_url?: string; + + // Restrictions that apply to bank accounts that would send + // funds to the exchange (crediting this exchange bank account). + // Optional, empty array for unrestricted. + credit_restrictions: AccountRestriction[]; + + // Restrictions that apply to bank accounts that would receive + // funds from the exchange (debiting this exchange bank account). + // Optional, empty array for unrestricted. + debit_restrictions: AccountRestriction[]; + + // Signature using the exchange's offline key over + // a `TALER_MasterWireDetailsPS` + // with purpose ``TALER_SIGNATURE_MASTER_WIRE_DETAILS``. + master_sig: EddsaSignature; + } + + .. ts:def:: AccountRestriction + + type AccountRestriction = + | RegexAccountRestriction + | DenyAllAccountRestriction + + .. ts:def:: DenyAllAccountRestriction + + // Account restriction that disables this type of + // account for the indicated operation categorically. + interface DenyAllAccountRestriction { + + type: "deny"; + } + + .. ts:def:: RegexAccountRestriction + + // Accounts interacting with this type of account + // restriction must have a payto://-URI matching + // the given regex. + interface RegexAccountRestriction { + + type: "regex"; + + // Regular expression that the payto://-URI of the + // partner account must follow. The regular expression + // should follow posix-egrep, but without support for character + // classes, GNU extensions, back-references or intervals. See + // 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. Applications + // may support regexes with additional features, but exchanges + // must not use such regexes. + payto_regex: string; + + // Hint for a human to understand the restriction + // (that is hopefully easier to comprehend than the regex itself). + human_hint: string; + + // Map from IETF BCP 47 language tags to localized + // human hints. + human_hint_i18n?: { [lang_tag: string]: string }; + + } + .. ts:def:: GlobalFees interface GlobalFees { @@ -542,114 +615,6 @@ possibly by using HTTPS. Both the individual denominations *and* the denomination list is signed, allowing customers to prove that they received an inconsistent list. -.. _wire-req: - -.. http:get:: /wire - - Returns a list of payment methods supported by the exchange. The idea is - that wallets may use this information to instruct users on how to perform - wire transfers to top up their wallets. - - **Response:** - - :http:statuscode:`200 OK`: - The exchange responds with a `WireResponse` object. This request should virtually always be successful. - - **Details:** - - .. ts:def:: WireResponse - - interface WireResponse { - - // Master public key of the exchange, must match the key returned in ``/keys``. - master_public_key: EddsaPublicKey; - - // Array of wire accounts operated by the exchange for - // incoming wire transfers. - accounts: WireAccount[]; - - // Object mapping names of wire methods (i.e. "iban" or "x-taler-bank") - // to wire fees. - fees: { method : AggregateTransferFee[] }; - - // List of exchanges that this exchange is partnering - // with to enable wallet-to-wallet transfers. - wads: ExchangePartner[]; - } - - The specification for the account object is: - - .. ts:def:: WireAccount - - interface WireAccount { - // ``payto://`` URI identifying the account and wire method - payto_uri: string; - - // URI to convert amounts from or to the currency used by - // this wire account of the exchange. Missing if no - // conversion is applicable. - conversion_url?: string; - - // Restrictions that apply to bank accounts that would send - // funds to the exchange (crediting this exchange bank account). - // Optional, empty array for unrestricted. - credit_restrictions: AccountRestriction[]; - - // Restrictions that apply to bank accounts that would receive - // funds from the exchange (debiting this exchange bank account). - // Optional, empty array for unrestricted. - debit_restrictions: AccountRestriction[]; - - // Signature using the exchange's offline key over - // a `TALER_MasterWireDetailsPS` - // with purpose ``TALER_SIGNATURE_MASTER_WIRE_DETAILS``. - master_sig: EddsaSignature; - } - - .. ts:def:: AccountRestriction - - type AccountRestriction = - | RegexAccountRestriction - | DenyAllAccountRestriction - - .. ts:def:: DenyAllAccountRestriction - - // Account restriction that disables this type of - // account for the indicated operation categorically. - interface DenyAllAccountRestriction { - - type: "deny"; - } - - .. ts:def:: RegexAccountRestriction - - // Accounts interacting with this type of account - // restriction must have a payto://-URI matching - // the given regex. - interface RegexAccountRestriction { - - type: "regex"; - - // Regular expression that the payto://-URI of the - // partner account must follow. The regular expression - // should follow posix-egrep, but without support for character - // classes, GNU extensions, back-references or intervals. See - // 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. Applications - // may support regexes with additional features, but exchanges - // must not use such regexes. - payto_regex: string; - - // Hint for a human to understand the restriction - // (that is hopefully easier to comprehend than the regex itself). - human_hint: string; - - // Map from IETF BCP 47 language tags to localized - // human hints. - human_hint_i18n?: { [lang_tag: string]: string }; - - } - Aggregate wire transfer fees representing the fees the exchange charges per wire transfer to a merchant must be specified as an array in all wire transfer response objects under ``fees``. The @@ -664,9 +629,6 @@ possibly by using HTTPS. // Per transfer closing fee. closing_fee: Amount; - // Per exchange-to-exchange transfer (wad) fee. - wad_fee: Amount; - // What date (inclusive) does this fee go into effect? // The different fees must cover the full time period in which // any of the denomination keys are valid without overlap. @@ -691,6 +653,9 @@ possibly by using HTTPS. // Public master key of the partner exchange. partner_master_pub: EddsaPublicKey; + // Per exchange-to-exchange transfer (wad) fee. + wad_fee: Amount; + // Exchange-to-exchange wad (wire) transfer frequency. wad_frequency: RelativeTime; -- cgit v1.2.3 From 8daac5d9293a6bb7ad80bd646cca211079234e38 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Thu, 8 Feb 2024 16:42:28 +0100 Subject: remove rewards, fix links --- core/api-auditor.rst | 14 +++--- core/api-common.rst | 2 +- taler-merchant-manual.rst | 3 +- taler-user-guide.rst | 109 ---------------------------------------------- 4 files changed, 10 insertions(+), 118 deletions(-) diff --git a/core/api-auditor.rst b/core/api-auditor.rst index dcb39864..61e448b8 100644 --- a/core/api-auditor.rst +++ b/core/api-auditor.rst @@ -351,14 +351,14 @@ This API is used to obtain a list of all the balances that are stored by the aud **Details:** - .. ts:def:: Balances + .. ts:def:: BalanceList interface BalanceList { // Total amount reported - auditor_total_reported_balance: taler_amount; + auditor_total_reported_balance: Amount; // Amount potentially missing - auditor_missing_balance: taler_amount; + auditor_missing_balance: Amount; //... } @@ -402,16 +402,16 @@ This API is used by the auditor to obtain a list of pending denominations interface PendingDenomination { // Balance of denomination. - denom_balance: taler_amount; + denom_balance: Amount; // Amount that was lost due to failures by the exchange. - denom_loss: taler_amount; + denom_loss: Amount; // Amount at risk of loss due to recoup operations. - denom_risk: taler_amount; + denom_risk: Amount; // Amount actually lost due to recoup operations after a revocation. - recoup_loss: taler_amount; + recoup_loss: Amount; } .. note:: diff --git a/core/api-common.rst b/core/api-common.rst index 863d3099..5dc0c791 100644 --- a/core/api-common.rst +++ b/core/api-common.rst @@ -1043,7 +1043,7 @@ within the }; -.. _TALER_DepositRequestPS: +.. _taler_depositrequestps: .. sourcecode:: c diff --git a/taler-merchant-manual.rst b/taler-merchant-manual.rst index dcf518e7..04aadb5d 100644 --- a/taler-merchant-manual.rst +++ b/taler-merchant-manual.rst @@ -152,11 +152,12 @@ main Taler configuration (especially the accepted *currency* and *exchanges*). 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: Instance Bank Accounts ---------------------- -.. index:: instance-bank-account +.. index:: Bank account To receive payments, an instance must have configured one or more bank *accounts*. When configuring the bank account of an instance, one should diff --git a/taler-user-guide.rst b/taler-user-guide.rst index a88faae3..8b7a5ed1 100644 --- a/taler-user-guide.rst +++ b/taler-user-guide.rst @@ -322,112 +322,3 @@ Mustach templating engine: * reason: the reason entered by the merchant staff for granting the refund; be careful, you probably want to inform your staff if a webhook may expose this information to the consumer - - -.. _Rewarding-visitors: - -Rewarding visitors -================== - -.. index:: rewards - -Taler can also be used to reward digital cash to Web site visitors. For -example, you may be running an online survey, and you want to reward those -people that have dutifully completed the survey. If they have installed a -Taler wallet, you can provide them with a reward for their deeds. This section -describes how to setup the Taler merchant backend for rewarding. - -There are three basic steps that must happen to reward a visitor. - -.. _Fund-the-reserve: - -Fund the reserve ----------------- - -.. index:: reserve - -First, the reserve must be setup in the merchant backend. A reserve -is always tied to a particular instance. To create a reserve with -10 KUDOS at instance ``default`` using the demo exchange, use: - -.. code-block:: console - - $ taler-merchant-setup-reserve \ - -a KUDOS:10 \ - -e https://exchange.demo.taler.net/ \ - -m http://localhost:8888/instances/default - -The above command assumes that the merchant runs on localhost on -port 8888. -For more information, including how to transmit authentication information -to the backend, see :doc:`manpages/taler-merchant-setup-reserve.1`. - -The command will output a ``payto://`` URI which specifies where to -wire the funds and which wire transfer subject to use. - - .. note:: - - FIXME: add full example output. - -In our example, the output for the wire transfer subject is: - -.. code-block:: none - - QPE24X8PBX3BZ6E7GQ5VAVHV32FWTTCADR0TRQ183MSSJD2CHNEG - -You now need to make a wire transfer to the exchange’s bank account -using the given wire transfer subject. - -Make your wire transfer and (optionally) check at -“https://exchange/reserves/QPE24X...” whether your transfer has arrived at the -exchange. - -Once the funds have arrived, you can start to use the reserve for -rewarding. - -Note that an exchange will typically close a reserve after four weeks, wiring -all remaining funds back to the sender’s account. Thus, you should plan to -wire funds corresponding to a campaign of about two weeks to the exchange -initially. If your campaign runs longer, you should setup another reserve -every other week to ensure one is always ready. - -.. _Authorize-a-reward: - -Authorize a reward ------------------- - -When your frontend has reached the point where a client is supposed to receive -a reward, it needs to first authorize the reward. For this, the frontend must use -a POST to ``/private/reserves/$RESERVE_PUB/authorize-reward``. To authorize a -reward, the frontend has to provide the following information in the body of the -POST request: - -- The amount of the reward - -- The justification (only used internally for the back-office) - -- The URL where the wallet should navigate next after the reward was - processed - -- The reward-pickup URL (see next section) - -In response to this request, the backend will return a reward token, an -expiration time and the exchange URL. The expiration time will indicate -how long the reward is valid (when the reserve expires). The reward token is -an opaque string that contains all the information needed by the wallet -to process the reward. The frontend must send this reward token to the browser -in a special “402 Payment Required” response inside the ``Taler`` -header. - -The frontend should handle errors returned by the backend, such as -misconfigured instances or a lack of remaining funds for rewarding. - -.. _Picking-up-of-the-reward: - -Picking up of the reward ------------------------- - -The wallet will POST a JSON object to the shop’s -``/rewards/$REWARD_ID/pickup`` handler. -The frontend must then forward this request to the backend. The response -generated by the backend can then be forwarded directly to the wallet. -- cgit v1.2.3 From 7d63c95d0f779a2ade14896af9d4b304e038f826 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Thu, 8 Feb 2024 16:51:24 +0100 Subject: remove reward-related APIs and design considerations --- checklist-demo-upgrade.rst | 10 - core/api-exchange.rst | 17 +- core/api-merchant.rst | 541 +-------------------- design-documents/014-merchant-backoffice-ui.rst | 8 - .../020-backoffice-rewards-management.rst | 2 +- design-documents/023-taler-kyc.rst | 2 +- design-documents/031-invoicing.rst | 15 +- .../037-wallet-transactions-lifecycle.rst | 58 --- .../041-wallet-balance-amount-definitions.rst | 14 - design-documents/053-wallet-ui.rst | 57 +-- images/Makefile | 4 +- images/transaction-reward-states.dot | 11 - manpages/taler-wallet-cli.1.rst | 2 - manpages/taler.conf.5.rst | 7 - orphaned/taler-nfc-guide.rst | 4 +- taler-developer-manual.rst | 3 +- taler-exchange-manual.rst | 2 +- taler-merchant-api-tutorial.rst | 67 --- taler-merchant-manual.rst | 44 -- taler-wallet.rst | 1 - 20 files changed, 40 insertions(+), 829 deletions(-) delete mode 100644 images/transaction-reward-states.dot diff --git a/checklist-demo-upgrade.rst b/checklist-demo-upgrade.rst index c45c1847..d8724030 100644 --- a/checklist-demo-upgrade.rst +++ b/checklist-demo-upgrade.rst @@ -136,7 +136,6 @@ Merchant SPA - |democheck| edit template to add TOTP device, set price to fixed, summary to be entered - |democheck| scan template QR code, edit summary and pay - |democheck| check displayed TOTP code matches TOTP app -- |democheck| create reserve for rewards - |democheck| do manual wire transfer in bank to establish reserve funding - |democheck| check that partially refunded order is marked as awaiting wire transfer - |democheck| check bank wired funds to merchant (if needed, wait) @@ -148,14 +147,6 @@ Merchant SPA - |democheck| check that orders are marked as completed -Survey/Rewards -^^^^^^^^^^^^^^ - -- |democheck| Visit https://survey.demo.taler.net/ and receive a reward. -- |democheck| Verify that the survey stats page (https://survey.demo.taler.net/survey-stats) is working, - and that the survey reserve has sufficient funds. - - P2P payments ^^^^^^^^^^^^ @@ -180,4 +171,3 @@ Shutdown - |democheck| enter bank account (if possible) - |democheck| wallet balance goes to zero - |democheck| specified bank account receives remaining balance - diff --git a/core/api-exchange.rst b/core/api-exchange.rst index 0e79ae6b..f7d63d0e 100644 --- a/core/api-exchange.rst +++ b/core/api-exchange.rst @@ -198,7 +198,8 @@ possibly by using HTTPS. // Set to true if this exchange allows the use // of reserves for rewards. - rewards_allowed: boolean; + // @deprecated in protocol v18. + rewards_allowed: false; // EdDSA master public key of the exchange, used to sign entries // in ``denoms`` and ``signkeys``. @@ -5071,12 +5072,12 @@ Reserve control --------------- This section describes the reserve control API which can be used to (1) -prevent a reserve from expiring (which is useful if the reserve is used for -rewards), to (2) pay an annual fee to allow a number of purses to be created -for the respective reserve without paying a purse fee each time, to (3) obtain -KYC information associated with a reserve to prove 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. +prevent a reserve from expiring, to (2) pay an annual fee to allow a number of +purses to be created for the respective reserve without paying a purse fee +each time, to (3) obtain KYC information associated with a reserve to prove +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:: @@ -5084,7 +5085,7 @@ naturally expire and possibly (5) wire the funds to a designated account. .. http:post:: /reserves/$RESERVE_PUB/open - Request keeping a reserve open for rewards or invoicing. + Request keeping a reserve open for invoicing. **Request:** diff --git a/core/api-merchant.rst b/core/api-merchant.rst index 652c7303..46392118 100644 --- a/core/api-merchant.rst +++ b/core/api-merchant.rst @@ -199,8 +199,7 @@ This section describes (public) endpoints that wallets must be able to interact with directly (without HTTP-based authentication). These endpoints are used to process payments (claiming an order, paying for the order, checking payment/refund status and aborting payments), -process refunds (checking refund status, obtaining the refund), -and to pick up rewards. +and to process refunds (checking refund status, obtaining the refund). Claiming an order @@ -837,111 +836,6 @@ the contract. Refunds must be approved by the merchant's business logic. } -Picking up rewards ------------------- - -Rewards are a way for wallets to obtain e-cash from -a website. - -.. http:get:: [/instances/$INSTANCE]/rewards/$REWARD_ID - - Handle request from wallet to provide details about a reward. - - This endpoint typically also supports requests with the "Accept" header - requesting "text/html". In this case, an HTML response suitable for - triggering the interaction with the wallet is returned. If the backend - installation does not include the required HTML templates, a 406 status - code is returned. - - **Response:** - - :http:statuscode:`200 OK`: - A reward is being returned. The backend responds with a `RewardInformation`. - :http:statuscode:`404 Not found`: - The reward identifier is unknown. - :http:statuscode:`406 Not acceptable`: - The merchant backend could not load the template required to generate a reply in the desired format. (Likely HTML templates were not properly installed.) - :http:statuscode:`410 Gone`: - A reward has been fully claimed. The JSON reply still contains the `RewardInformation`. - - .. ts:def:: RewardInformation - - interface RewardInformation { - - // Exchange from which the reward will be withdrawn. Needed by the - // wallet to determine denominations, fees, etc. - exchange_url: string; - - // URL where to go after obtaining the reward. - next_url: string; - - // (Remaining) amount of the reward (including fees). - reward_amount: Amount; - - // Timestamp indicating when the reward is set to expire (may be in the past). - // Note that rewards that have expired MAY also result in a 404 response. - expiration: Timestamp; - } - - -.. http:post:: [/instances/$INSTANCE]/rewards/$REWARD_ID/pickup - - Handle request from wallet to pick up a reward. - - **Request:** - - The request body is a `RewardPickupRequest` object. - - **Response:** - - :http:statuscode:`200 OK`: - A reward is being returned. The backend responds with a `RewardResponse`. - :http:statuscode:`401 Unauthorized`: - The reward amount requested exceeds the reward. - :http:statuscode:`404 Not found`: - The reward identifier is unknown. - :http:statuscode:`409 Conflict`: - Some of the denomination key hashes of the request do not match those currently available from the exchange (hence there is a conflict between what the wallet requests and what the merchant believes the exchange can provide). - :http:statuscode:`410 Gone`: - The reward has expired. - - .. ts:def:: RewardPickupRequest - - interface RewardPickupRequest { - - // List of planchets the wallet wants to use for the reward. - planchets: PlanchetDetail[]; - } - - .. ts:def:: PlanchetDetail - - interface PlanchetDetail { - // Hash of the denomination's public key (hashed to reduce - // bandwidth consumption). - denom_pub_hash: HashCode; - - // Coin's blinded public key. - coin_ev: CoinEnvelope; - } - - .. ts:def:: RewardResponse - - interface RewardResponse { - - // Blind RSA signatures over the planchets. - // The order of the signatures matches the planchets list. - blind_sigs: BlindSignature[]; - } - - .. ts:def:: BlindSignature - - interface BlindSignature { - - // The (blind) RSA signature. Still needs to be unblinded. - blind_sig: BlindedRsaSignature; - } - - ------------------- Instance management ------------------- @@ -2698,439 +2592,6 @@ once we got a reply from the exchange. The transfer cannot be deleted anymore. -.. _api-rewards: - ------------------------ -Backend: Giving rewards ------------------------ - -.. note:: - - This API is deprecated as of protocol v8. - -Rewards are a way for websites to give small amounts of e-cash to visitors (for -example as a financial reward for providing information or viewing -advertisements). Rewards are non-contractual: neither merchant nor consumer -have any contractual information about the other party as a result of the -reward. - - -Create reserve --------------- - -.. note:: - - This API is deprecated as of protocol v8. - -Reserves are basically funds a merchant has provided to an exchange for a -rewards campaign. Each reserve has a limited lifetime (say 2--4 weeks). Any -funds not used to reward customers will automatically be wired back from the -exchange to the originating account. - -Before handing out rewards, a merchant must tell the backend to set up a -reserve. The backend will return a reserve public key which must be used as -the wire transfer subject when wiring the reward campaign funds to the -exchange. - -.. http:post:: [/instances/$INSTANCE]/private/reserves - - Create a reserve for rewards. - - This request is **not** idempotent. However, while repeating - it will create another reserve, that is generally pretty harmless - (assuming only one of the reserves is filled with a wire transfer). - Clients may want to eventually delete the unused reserves to - avoid clutter. - - **Request:** - - The request body is a `ReserveCreateRequest` object. - - **Response:** - - :http:statuscode:`200 OK`: - The backend is waiting for the reserve to be established. The merchant - must now perform the wire transfer indicated in the `ReserveCreateConfirmation`. - :http:statuscode:`408 Request timeout`: - The exchange did not respond on time. - :http:statuscode:`409 Conflict`: - The exchange does not support the requested wire method or does not allow rewards. - :http:statuscode:`502 Bad gateway`: - We could not obtain ``/wire`` details from the specified exchange base URL. - :http:statuscode:`504 Gateway timeout`: - The merchant's interaction with the exchange took too long. - The client might want to try again later. - - .. ts:def:: ReserveCreateRequest - - interface ReserveCreateRequest { - // Amount that the merchant promises to put into the reserve. - initial_balance: Amount; - - // Exchange the merchant intends to use for rewards. - exchange_url: string; - - // Desired wire method, for example "iban" or "x-taler-bank". - wire_method: string; - } - - .. ts:def:: ReserveCreateConfirmation - - interface ReserveCreateConfirmation { - // Public key identifying the reserve. - reserve_pub: EddsaPublicKey; - - // Wire accounts of the exchange where to transfer the funds. - accounts: WireAccount[]; - } - -.. http:get:: [/instances/$INSTANCE]/private/reserves - - Obtain list of reserves that have been created for rewards. - - **Request:** - - :query after: *Optional*. Only return reserves created after the given timestamp in milliseconds. - :query active: *Optional*. Only return active/inactive reserves depending on the boolean given. - :query failures: *Optional*. Only return reserves where we disagree with the exchange about the initial balance. - - **Response:** - - :http:statuscode:`200 OK`: - Returns a list of known reward reserves. - The body is a `RewardReserveStatus`. - - .. ts:def:: RewardReserveStatus - - interface RewardReserveStatus { - // Array of all known reserves (possibly empty!). - reserves: ReserveStatusEntry[]; - } - - .. ts:def:: ReserveStatusEntry - - interface ReserveStatusEntry { - // Public key of the reserve. - reserve_pub: EddsaPublicKey; - - // Timestamp when it was established. - creation_time: Timestamp; - - // Timestamp when it expires. - expiration_time: Timestamp; - - // Initial amount as per reserve creation call. - merchant_initial_amount: Amount; - - // Initial amount as per exchange, 0 if exchange did - // not confirm reserve creation yet. - exchange_initial_amount: Amount; - - // Amount picked up so far. - pickup_amount: Amount; - - // Amount approved for rewards that exceeds the pickup_amount. - committed_amount: Amount; - - // Is this reserve active (false if it was deleted but not purged)? - active: boolean; - } - - -Query funds remaining ---------------------- - -.. http:get:: [/instances/$INSTANCE]/private/reserves/$RESERVE_PUB - - Obtain information about a specific reserve that have been created for rewards. - - **Request:** - - :query rewards: *Optional*. If set to "yes", returns also information about all of the rewards created. - - **Response:** - - :http:statuscode:`200 OK`: - Returns the `ReserveDetail`. - :http:statuscode:`404 Not found`: - The reward reserve is not known. - :http:statuscode:`502 Bad gateway`: - We are having trouble with the request because of a problem with the exchange. - Likely returned with an "exchange_code" in addition to a "code" and - an "exchange_http_status" in addition to our own HTTP status. Also usually - includes the full exchange reply to our request under "exchange_reply". - This is only returned if there was actual trouble with the exchange, not - if the exchange merely did not respond yet or if it responded that the - reserve was not yet filled. - :http:statuscode:`504 Gateway timeout`: - The merchant's interaction with the exchange took too long. - The client might want to try again later. - - .. ts:def:: ReserveDetail - - interface ReserveDetail { - // Timestamp when it was established. - creation_time: Timestamp; - - // Timestamp when it expires. - expiration_time: Timestamp; - - // Initial amount as per reserve creation call. - merchant_initial_amount: Amount; - - // Initial amount as per exchange, 0 if exchange did - // not confirm reserve creation yet. - exchange_initial_amount: Amount; - - // Amount picked up so far. - pickup_amount: Amount; - - // Amount approved for rewards that exceeds the pickup_amount. - committed_amount: Amount; - - // Array of all rewards created by this reserves (possibly empty!). - // Only present if asked for explicitly. - rewards?: RewardStatusEntry[]; - - // Is this reserve active (false if it was deleted but not purged)? - active: boolean; - - // Array of wire accounts of the exchange that could - // be used to fill the reserve, can be NULL - // if the reserve is inactive or was already filled - accounts?: WireAccount[]; - - // URL of the exchange hosting the reserve, - // NULL if the reserve is inactive - exchange_url: string; - } - - .. ts:def:: RewardStatusEntry - - interface RewardStatusEntry { - - // Unique identifier for the reward. - reward_id: HashCode; - - // Total amount of the reward that can be withdrawn. - total_amount: Amount; - - // Human-readable reason for why the reward was granted. - reason: string; - } - - -Authorizing rewards -------------------- - -.. note:: - - This API is deprecated as of protocol v8. - -.. http:post:: [/instances/$INSTANCE]/private/reserves/$RESERVE_PUB/authorize-reward - - Authorize creation of a reward from the given reserve. - - **Request:** - - The request body is a `RewardCreateRequest` object. - - **Response:** - - :http:statuscode:`200 OK`: - A reward has been created. The backend responds with a `RewardCreateConfirmation`. - :http:statuscode:`404 Not found`: - The instance or the reserve is unknown to the backend. - :http:statuscode:`412 Precondition failed`: - The reward amount requested exceeds the available reserve balance for rewards. - - .. ts:def:: RewardCreateRequest - - interface RewardCreateRequest { - // Amount that the customer should be rewarded. - amount: Amount; - - // Justification for giving the reward. - justification: string; - - // URL that the user should be directed to after receiving the reward, - // will be included in the reward_token. - next_url: string; - } - - .. ts:def:: RewardCreateConfirmation - - interface RewardCreateConfirmation { - // Unique reward identifier for the reward that was created. - reward_id: HashCode; - - // taler://reward URI for the reward. - taler_reward_uri: string; - - // URL that will directly trigger processing - // the reward when the browser is redirected to it. - reward_status_url: string; - - // When does the reward expire? - reward_expiration: Timestamp; - } - - -.. http:post:: [/instances/$INSTANCE]/private/rewards - - Authorize creation of a reward, with - automatic selection of a working reserve of the instance by the - backend. Intentionally otherwise identical to the ``/authorize-reward`` - endpoint given above. - - **Request:** - - The request body is a `RewardCreateRequest` object. - - **Response:** - - :http:statuscode:`200 OK`: - A reward has been created. The backend responds with a `RewardCreateConfirmation`. - :http:statuscode:`404 Not found`: - The instance is unknown to the backend. - :http:statuscode:`412 Precondition failed`: - The reward amount requested exceeds the available reserve balance for rewards - in all of the reserves of the instance. - - -Deleting reserves ------------------ - -.. note:: - - This API is deprecated as of protocol v8. - -.. http:delete:: [/instances/$INSTANCE]/private/reserves/$RESERVE_PUB - - Delete information about a reserve. Fails if the reserve still has - committed to rewards that were not yet picked up and that have not yet - expired. - - **Request:** - - :query purge: *Optional*. If set to YES, the reserve and all information - about rewards it issued will be fully deleted. - Otherwise only the private key would be deleted. - - **Response:** - - :http:statuscode:`204 No content`: - The backend has successfully deleted the reserve. - :http:statuscode:`404 Not found`: - The backend does not know the instance or the reserve. - :http:statuscode:`409 Conflict`: - The backend refuses to delete the reserve (committed rewards awaiting pickup). - - -Checking reward status ----------------------- - -.. note:: - - This API is deprecated as of protocol v8. - -.. http:get:: [/instances/$INSTANCE]/private/rewards/$REWARD_ID - - Obtain information about a particular reward. - - **Request:** - - :query pickups: *Optional*. If set to "yes", returns also information about all of the pickups. - :query min_amount: *Optional*. Minimum pick-up amount the client is interested in. - :query timeout_ms=NUMBER: *Optional.* If specified, the merchant backend will - wait up to ``timeout_ms`` milliseconds for rewards of at least min_pick_up to be - picked up. A client must never rely on this behavior, as the - merchant backend may return a response immediately. - - **Response:** - - :http:statuscode:`200 OK`: - The reward is known. The backend responds with a `RewardDetails` message. - :http:statuscode:`404 Not found`: - The reward is unknown to the backend. - - .. ts:def:: RewardDetails - - interface RewardDetails { - // Amount that we authorized for this reward. - total_authorized: Amount; - - // Amount that was picked up by the user already. - total_picked_up: Amount; - - // Human-readable reason given when authorizing the reward. - reason: string; - - // Timestamp indicating when the reward is set to expire (may be in the past). - expiration: Timestamp; - - // Reserve public key from which the reward is funded. - reserve_pub: EddsaPublicKey; - - // Array showing the pickup operations of the wallet (possibly empty!). - // Only present if asked for explicitly. - pickups?: PickupDetail[]; - } - - .. ts:def:: PickupDetail - - interface PickupDetail { - // Unique identifier for the pickup operation. - pickup_id: HashCode; - - // Number of planchets involved. - num_planchets: Integer; - - // Total amount requested for this pickup_id. - requested_amount: Amount; - } - - -.. http:get:: [/instances/$INSTANCE]/private/rewards - - Return the list of all rewards. - - **Request:** - - :query include_expired: *Optional*. If set to "yes", the result includes expired rewards also. Otherwise, only active rewards are returned. - - :query limit: *Optional*. At most return the given number of results. Negative for descending in database row id, positive for ascending in database row id. - - :query offset: *Optional*. Starting ``row_id`` for an iteration. - - **Response:** - - :http:statuscode:`200 OK`: - The backend has successfully found the list of rewards. The backend responds - with a `RewardsResponse`. - - .. ts:def:: RewardsResponse - - interface RewardsResponse { - - // List of rewards that are present in the backend. - rewards: Reward[]; - } - - .. ts:def:: Reward - - interface Reward { - - // ID of the reward in the backend database. - row_id: number; - - // Unique identifier for the reward. - reward_id: HashCode; - - // (Remaining) amount of the reward (including fees). - reward_amount: Amount; - } - ----------- OTP Devices ----------- diff --git a/design-documents/014-merchant-backoffice-ui.rst b/design-documents/014-merchant-backoffice-ui.rst index eaf435a4..1f744a15 100644 --- a/design-documents/014-merchant-backoffice-ui.rst +++ b/design-documents/014-merchant-backoffice-ui.rst @@ -139,11 +139,3 @@ Story #4: Manage inventory - change product description / price / etc. - delete products from inventory - - -Story #5: Manage rewards ------------------------- - -- set up reward reserve - -- check reward reserve status diff --git a/design-documents/020-backoffice-rewards-management.rst b/design-documents/020-backoffice-rewards-management.rst index 1eef39b1..8345a3b9 100644 --- a/design-documents/020-backoffice-rewards-management.rst +++ b/design-documents/020-backoffice-rewards-management.rst @@ -1,4 +1,4 @@ -DD 20: Backoffice Rewards Management +XX 20: Backoffice Rewards Management #################################### Summary diff --git a/design-documents/023-taler-kyc.rst b/design-documents/023-taler-kyc.rst index 4d8f2cbc..d34241d7 100644 --- a/design-documents/023-taler-kyc.rst +++ b/design-documents/023-taler-kyc.rst @@ -40,7 +40,7 @@ Taler needs to run KYC checks in the following circumstances: * key: IBAN (encoded as payto:// URI) -* Reserve is "opened" for invoicing or rewards. +* Reserve is "opened" for invoicing. * key: reserve (=KYC account) long term public key per wallet (encoded as payto:// URI) diff --git a/design-documents/031-invoicing.rst b/design-documents/031-invoicing.rst index cfe776ed..0fcc88fd 100644 --- a/design-documents/031-invoicing.rst +++ b/design-documents/031-invoicing.rst @@ -4,9 +4,7 @@ DD 31: Invoicing Summary ======= -This document proposes new endpoints to support invoicing, -that incidentally also address the long-standing rewards -reserve expiration problem. +This document proposes new endpoints to support invoicing. Motivation @@ -36,10 +34,7 @@ Requirements * Reasonable UX and overall design impact. * Wallets may want to pay for the reserve with coins - (reserve fresh, not created via bank transfer), while - rewarding merchants likely want to pay from the reserve - balance itself. So both styles of payment should be - supported. + (reserve fresh, not created via bank transfer). Unclear in the current proposal are: @@ -62,12 +57,10 @@ charge the ``account_fee``, bump the number of open purses threshold in the ``reserves`` table and stop auto-closing of the reserve. This will ensure that the users can withdraw the reserve balance into their wallet even after a longer time period. This helps if the invoice is paid after a significant -delay, and also addresses the unwanted reward reserve closure -problem. Introduce a way to force an immediate closure of a reserve, allowing +delay. Introduce a way to force an immediate closure of a reserve, allowing P2P reserve from invoices to be send to a bank account (this allows a wallet to be used for convenient invoicing and not strictly require the wallet to -receive the funds) and also allowing the user to recover funds from a reward -reserve after rewards are no longer issued. +receive the funds). The solution needs three new tables for: diff --git a/design-documents/037-wallet-transactions-lifecycle.rst b/design-documents/037-wallet-transactions-lifecycle.rst index 9d749595..7a8cfacd 100644 --- a/design-documents/037-wallet-transactions-lifecycle.rst +++ b/design-documents/037-wallet-transactions-lifecycle.rst @@ -525,64 +525,6 @@ the same as if the double-spending transaction had been deleted by the user. .. image:: ../images/transaction-refresh-states.png - -Transaction Type: Reward ------------------------- - -* ``pending(user)`` - - We have downloaded the metadata for the reward. This is the initial state for a - reward transaction. The user needs to accept/refuse the reward. - - * ``[reward-expired] => expired`` - * ``[action:accept] => pending(pickup)`` - -* ``pending(pickup)`` - - We are picking up the reward. - - * ``[failure] => failed``: any type of failure, including expiration. - * ``[processed-kyc-required] => pending(kyc-required)`` - * ``[success] => done`` - * ``[action:suspend] => suspended(pickup)`` - -* ``suspended(pickup)`` - - The user suspended the operation while the reward was being picked up. - - * ``[reward-expired] => failed`` - * ``[action:resume] => pending(pickup)`` - -* ``pending(kyc)`` - - The user needs to perform a KYC check to continue. This usually should only - happen if the wallet balance exceeds some threshold. - - * ``[poll-success] => pending(pickup)`` - * ``[action:suspend] => suspended(kyc)`` - -* ``suspended(kyc)`` - - The user suspended the KYC operation. Note that we do not time out here if - the reward expires, as the wallet balance threshold KYC likely applies even - without the reward. - - * ``[action:resume] => pending(kyc)`` - -* ``done`` - - The reward operation completed. - - * ``[action:delete] => deleted`` - -* ``deleted`` - - All memory of the reward operation is lost, but of course the resulting fresh - coins are preserved. - -.. image:: ../images/transaction-reward-states.png - - Transaction Type: Deposit ------------------------- diff --git a/design-documents/041-wallet-balance-amount-definitions.rst b/design-documents/041-wallet-balance-amount-definitions.rst index 1c89d634..9943d482 100644 --- a/design-documents/041-wallet-balance-amount-definitions.rst +++ b/design-documents/041-wallet-balance-amount-definitions.rst @@ -245,20 +245,6 @@ REFUND Is there a way that the merchant can initiate a refund of purchase + refund_fee so the wallet will get the same effective_amount? -REWARD - raw amount is the amount that the merchant send as reward - - ``instructed_amount`` = reward.amount - - ``raw_amount`` = instructed_amount + withdrawal_fee - - ``effective_amount`` = instructed_amount - - .. note:: - We should not show fee for rewards in the wallet since the merchant is the one choosing - the exchange and we can assume that those rewards are paid by the merchant. - So the wallet only care about the effective. - Coin selection algorithm ------------------------ diff --git a/design-documents/053-wallet-ui.rst b/design-documents/053-wallet-ui.rst index 5891eb37..5b5ba22d 100644 --- a/design-documents/053-wallet-ui.rst +++ b/design-documents/053-wallet-ui.rst @@ -4,7 +4,7 @@ DD 53: Wallet UI Design Summary ======= -This document proposes designs wallet UI. It defines what Android, iOS and +This document proposes designs wallet UI. It defines what Android, iOS and WebExtension should follow in order to have a coherent UI between platforms. Motivation @@ -12,8 +12,8 @@ Motivation We want user to be able to help each others independent of the implementation they are using. -We want user to be able to capitalize the effort of learning how to use one -wallet and be able to use a different one without the need to learn +We want user to be able to capitalize the effort of learning how to use one +wallet and be able to use a different one without the need to learn anything new. Currently development of different platform specific implementation are independent and every developer needs to choose the layout, texts and buttons and navigation. @@ -25,7 +25,7 @@ Every screen MUST be defined in a document with the following information: * **Identifiable UI screens**: every UI should have an unique identifier that will be use for development discussion and bug reports. There should be an option - in the application to enable an active rendering of the id. + in the application to enable an active rendering of the id. * **Description**: the reason to be of the screen, should help to define what will be included into, what is going to left for other screens and when and from @@ -41,24 +41,24 @@ properties is defined in the spec the implementation must implement it. The spec should be minimal to achieve the objective in the description. * **Info**: Spec of information that the user should have access. The type of info - could be a field (id and value) or a banner (information and instructions). - The spec will help to reuse the text for i18n across apps and defined + could be a field (id and value) or a banner (information and instructions). + The spec will help to reuse the text for i18n across apps and defined * **Inputs**: Spec of information need to provide in current screen. The type of input, range of values and validation should be defined if necessary. -* **Actions**: Spec of buttons and interactable elements that will have a significant +* **Actions**: Spec of buttons and interactable elements that will have a significant change in the current state. It should also mention navigation when applicable. - + * **Layout**: Spec position of elements when needed. The spec should be "soft" in a sense - that elements should be easy to find following directions like "close to X" or + that elements should be easy to find following directions like "close to X" or "at the start/end of the screen". -Screen should be defined using the most relaxed definition that are good enough to +Screen should be defined using the most relaxed definition that are good enough to be clear for the user. Platform will use this definition and adapt to the differences on the platform taking advantange of platform API and screen sizes. -When a screen have multiple uses for the same purpose, a substate section should be +When a screen have multiple uses for the same purpose, a substate section should be included with the difference with the main definition. Part of the screens that are reused shoud also be defined in this document as screen. @@ -84,11 +84,11 @@ fee, restrictions and ETA should be clear for the user. * exchange to be used showing the URL * table of details of the operation: use the ``operation-table-details`` screen * starting currency: if the exchange has the currency conversion service enabled user should be able to the details based on the wire transfer currency - * taler URI: show copy button or QR to complete the operation with another device + * taler URI: show copy button or QR to complete the operation with another device ``Inputs``: * age restriction: allow the selection of the restriction in the age group possible by the exchange - * service provider: allow the selection of different exchange + * service provider: allow the selection of different exchange ``Actions``: * confirm operation: on success will be redirected to the ``transaction-details`` screen where the detail of the current transaction will be displayed @@ -111,10 +111,10 @@ fee, restrictions and ETA should be clear for the user. * order summary * table of details of the operation: use the ``operation-table-details`` screen * receipt: order id - * payment deadline: absolute time before the claimed order expires - * taler URI: show copy button or QR to complete the operation with another device + * payment deadline: absolute time before the claimed order expires + * taler URI: show copy button or QR to complete the operation with another device * cant pay desc: if the user has enough balance but unable to use it - * payment status: if the + * payment status: if the ``Actions``: * confirm operation: if the payment is possible, on success will be redirected to the ``transaction-details`` screen where the detail of the current transaction will be displayed @@ -156,7 +156,7 @@ fee, restrictions and ETA should be clear for the user. ``Inputs``: * subject: short description of the transaction * expiration: absolute time/date after which the invoice is not valid anymore - * service provider: allow the selection of different exchange + * service provider: allow the selection of different exchange ``Actions``: * confirm operation: on success will be redirected to the ``transaction-details`` screen where the detail of the current transaction will be displayed @@ -225,24 +225,6 @@ fee, restrictions and ETA should be clear for the user. * review and confirm ToS: if the current selected exchange has a version of ToS that the user didn't yet accepted, use the ``accept-tos`` screen * cancel: user will be redirected to ``balance`` -cta-reward ------------ - -``Description``: this screen is used for the confirmation of the acceptance of -a reward from a merchant. -the success of this operation will be an will decrease the balance in the wallet. -fee, restrictions and ETA should be clear for the user. - -``Info``: - * amount: effective amount to receive - * exchange: from where this money comes from - * merchant: offering the reward - -``Actions``: - * confirm operation: on success will be redirected to the ``transaction-details`` screen where the detail of the current transaction will be displayed - * review and confirm ToS: if the current selected exchange has a version of ToS that the user didn't yet accepted, use the ``accept-tos`` screen - * cancel: user will be redirected to ``balance`` - operation-table-details ----------------------- @@ -252,12 +234,12 @@ the initial amount and the final amount with all the items related to the operat ``labels``: initial amount of the operation, and final amount are always shown. Fee should be shown as an extra row in the table if it is non-zero. -Converted amount should be shown as an extra row if initial amount currency is not the same +Converted amount should be shown as an extra row if initial amount currency is not the same as the final amount currency. Initial amount label by operation: - * payment -> Price + * payment -> Price * deposit -> Send * peer-pull-credit -> Invoice * peer-pull-debit -> Invoice @@ -286,4 +268,3 @@ user already accepted ToS) Q / A ===== - diff --git a/images/Makefile b/images/Makefile index 3a7fdab9..ad7a695d 100644 --- a/images/Makefile +++ b/images/Makefile @@ -1,4 +1,4 @@ -diagrams: regional-arch.png arch-api.png coin.png deposit.png reserve.png transaction-common-states.png transaction-withdrawal-states.png transaction-payment-states.png transaction-refund-states.png transaction-refresh-states.png transaction-reward-states.png transaction-deposit-states.png transaction-push-debit-states.png transaction-push-credit-states.png transaction-pull-credit-states.png transaction-pull-debit-states.png challenger.png +diagrams: regional-arch.png arch-api.png coin.png deposit.png reserve.png transaction-common-states.png transaction-withdrawal-states.png transaction-payment-states.png transaction-refund-states.png transaction-refresh-states.png transaction-deposit-states.png transaction-push-debit-states.png transaction-push-credit-states.png transaction-pull-credit-states.png transaction-pull-debit-states.png challenger.png arch-api.png: arch-api.dot dot -Tpng arch-api.dot > arch-api.png @@ -16,8 +16,6 @@ transaction-refund-states.png: transaction-refund-states.dot dot -Tpng transaction-refund-states.dot > transaction-refund-states.png transaction-refresh-states.png: transaction-refresh-states.dot dot -Tpng transaction-refresh-states.dot > transaction-refresh-states.png -transaction-reward-states.png: transaction-reward-states.dot - dot -Tpng transaction-reward-states.dot > transaction-reward-states.png transaction-deposit-states.png: transaction-deposit-states.dot dot -Tpng transaction-deposit-states.dot > transaction-deposit-states.png transaction-push-debit-states.png: transaction-push-debit-states.dot diff --git a/images/transaction-reward-states.dot b/images/transaction-reward-states.dot deleted file mode 100644 index 476c8c74..00000000 --- a/images/transaction-reward-states.dot +++ /dev/null @@ -1,11 +0,0 @@ -digraph G { - initial[label="", shape="circle"]; - dialog_user[label="dialog(user)"]; - pending_pickup[label="pickup"]; - done[label="done", shape="box"]; - - initial -> dialog_user; - - dialog_user -> pending_pickup [color=blue, label="OK"]; - pending_pickup -> done [color=green]; -} diff --git a/manpages/taler-wallet-cli.1.rst b/manpages/taler-wallet-cli.1.rst index 2d35bb87..dad790f5 100644 --- a/manpages/taler-wallet-cli.1.rst +++ b/manpages/taler-wallet-cli.1.rst @@ -46,8 +46,6 @@ for testing. **withdraw-uri** URI -**reward-uri** URI - **refund-uri** URI **pay-uri** [**-y** | **--yes**] URI diff --git a/manpages/taler.conf.5.rst b/manpages/taler.conf.5.rst index 191c7e59..115dee8a 100644 --- a/manpages/taler.conf.5.rst +++ b/manpages/taler.conf.5.rst @@ -162,13 +162,6 @@ AML_THRESHOLD KYC_AML_TRIGGER Program to run on KYC attribute data to decide whether we should immediately flag an account for AML review. Program must return 0 if a manual AML review is not needed, and non-zero to trigger an AML review. The KYC attribute data of the new user will be passed on standard-input. -ENABLE_REWARDS - This option can be used to announce that an exchange does not allow - the use of the reserves for rewards. The default is YES which means - that rewards are allowed. The option merely announces that - rewards is enabled or disabled, and protocol-compliant merchant - backends will then enable or disable the feature accordingly. - STEFAN_ABS Absolte amount to add as an offset in the STEFAN fee approximation curve (see DD47). Defaults to CURRENCY:0 if not specified. diff --git a/orphaned/taler-nfc-guide.rst b/orphaned/taler-nfc-guide.rst index aa961d31..d025d347 100644 --- a/orphaned/taler-nfc-guide.rst +++ b/orphaned/taler-nfc-guide.rst @@ -231,8 +231,8 @@ to dereference the ``taler://pay`` URI from the example above: # success response with no data m<-w 9000 -(Note that this process works analogously for communication between a bank/ATM -terminal or "reward provider".) +(Note that this process works analogously for communication with a bank/ATM +terminal.) Request tunneling diff --git a/taler-developer-manual.rst b/taler-developer-manual.rst index 184c6592..ce0e600f 100644 --- a/taler-developer-manual.rst +++ b/taler-developer-manual.rst @@ -93,8 +93,7 @@ overview: sending invoices or payments to other wallets. * taler-merchant-demos: various demonstration services operated at - 'demo.taler.net', including a simple shop, donation page and a - survey with reward functionality. + 'demo.taler.net', including a simple shop and a donation page. There are other important repositories without code, including: diff --git a/taler-exchange-manual.rst b/taler-exchange-manual.rst index 79455fec..64c2a7d9 100644 --- a/taler-exchange-manual.rst +++ b/taler-exchange-manual.rst @@ -967,7 +967,7 @@ Taler permits an exchange to require KYC data under the following circumstances: * 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 - * Reserve is "opened" for invoicing or rewards (**planned feature**) + * Reserve is "opened" for invoicing (**planned feature**) Any of the above requests can trigger the KYC process, which can be illustrated as follows: diff --git a/taler-merchant-api-tutorial.rst b/taler-merchant-api-tutorial.rst index 739cf07f..87fee9ca 100644 --- a/taler-merchant-api-tutorial.rst +++ b/taler-merchant-api-tutorial.rst @@ -63,10 +63,6 @@ If you want to look at some simple, running examples, check out these: that accepts donations for software projects and gives donation receipts. -- The - `survey `__ - that gives users who answer a question a small reward. - - The `WooCommerce plugin `__ which is a comprehensive integration into a Web shop including the refund business process. @@ -413,69 +409,6 @@ considered to identify a resource you can pay for and thus do not have to be unique. -.. _Giving-Customers-Rewards: -.. index:: rewards - -Giving Customers Rewards -======================== - -GNU Taler allows Web sites to grant digital cash directly to a visitor. The -idea is that some sites may want incentivize actions such as filling out a -survey or trying a new feature. It is important to note that receiving rewards is -not enforceable for the visitor, as there is no contract. It is simply a -voluntary gesture of appreciation of the site to its visitor. However, once a -reward has been granted, the visitor obtains full control over the funds provided -by the site. - -The merchant backend of the site must be properly configured for rewards, and -sufficient funds must be made available for rewards. See the :ref:`Taler User -Guide ` for details. - -To check if rewards are configured properly and if there are sufficient -funds available for granting rewards, query the ``/private/reserves`` endpoint: - -.. code-block:: python - - >>> import requests - >>> requests.get("https://backend.demo.taler.net/private/reserves", - ... headers={"Authorization": "Bearer secret-token:sandbox"}) - - -Check that a reserve exists where the ``merchant_initial_amount`` is below the -``committed_amount`` and that the reserve is ``active``. - -.. _authorize-reward: - -To authorize a reward, ``POST`` to ``/private/rewards``. The following fields -are recognized in the JSON request object: - -- ``amount``: Amount that should be given to the visitor as a reward. - -- ``justification``: Description of why the reward was granted. Human-readable - text not exposed to the customer, but used by the Back Office. - -- ``next_url``: The URL that the user’s browser should be redirected to by - the wallet, once the reward has been processed. - -The response from the backend contains a ``taler_reward_url``. The -customer’s browser must be redirected to this URL for the wallet to pick -up the reward. - -.. _pick-up-reward: - -This code snipped illustrates giving a reward: - -.. code-block:: python - - >>> import requests - >>> reward_req = dict(amount="KUDOS:0.5", - ... justification="User filled out survey", - ... next_url="https://merchant.com/thanks.html") - >>> requests.post("https://backend.demo.taler.net/private/rewards", json=reward_req, - ... headers={"Authorization": "Bearer secret-token:sandbox"}) - - - .. _Advanced-topics: Advanced topics diff --git a/taler-merchant-manual.rst b/taler-merchant-manual.rst index 04aadb5d..9ed7ea3e 100644 --- a/taler-merchant-manual.rst +++ b/taler-merchant-manual.rst @@ -332,50 +332,6 @@ and the amount that was received. Given this information, the backend can detect and report any irregularities that might arise. -.. _rewards: - -Rewards -------- - -.. index:: reward -.. index:: pick up - -Taler does not only allow a Website to be paid, but also to make voluntary, -non-contractual payments to visitors, called *rewards*. Such rewards could be -granted as a reward for filling in surveys or watching advertizements. For -rewards, there is no contract, rewards are always voluntary actions by the Web -site that do not arise from a contractual obligation. Before a Web site -can create rewards, it must establish a reserve. Once a reserve has been -established, the merchant can *grant* rewards, allowing wallets to *pick up* -the reward. - -.. note:: - - Rewards are an optional feature, and exchanges may disable rewards (usually - if they see compliance issues). In this case, the reward feature will - not be available. - -.. _merchant-reserves: - - -Reserves --------- - -.. index:: reserve -.. index:: close - -A *reserve* is a pool of electronic cash at an exchange under the control of -a private key. Merchants withdraw coins from a reserve when granting -rewards. A reserve is established by first generating the required key material -in the merchant backend, and then wiring the desired amount of funds to the -exchange. - -An exchange will automatically *close* a reserve after a fixed period of time -(typically about a month), wiring any remaining funds back to the merchant. -While exchange APIs exists to (1) explicitly *open* a reserve to prevent it -from being automatically closed and to (2) explicitly *close* a reserve at any -time, the current merchant backend does not make use of these APIs. - Webhooks -------- diff --git a/taler-wallet.rst b/taler-wallet.rst index 3ea1dbea..62dca80d 100644 --- a/taler-wallet.rst +++ b/taler-wallet.rst @@ -431,7 +431,6 @@ Things we still need tests for: Or when the merchant is not reachable? Or the bank? This can be tested by temporarily killing those services. * How does the wallet deal with processing the same ``taler://(pay|withdraw)`` URI twice? -* Test rewards (accepting/refusing a reward) * Test refunds * Test for :ref:`session-based payments ` * Test case for auto-refunds -- cgit v1.2.3 From added705853e4e4097d146f67881c064d24f76b6 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Thu, 8 Feb 2024 17:00:22 +0100 Subject: fix stefan_lin type --- core/api-common.rst | 8 ++++++++ core/api-exchange.rst | 7 +++---- 2 files changed, 11 insertions(+), 4 deletions(-) diff --git a/core/api-common.rst b/core/api-common.rst index 5dc0c791..bdf3ad81 100644 --- a/core/api-common.rst +++ b/core/api-common.rst @@ -352,6 +352,14 @@ Integers // JavaScript numbers restricted to integers. type Integer = number; +Floats +^^^^^^ + +.. ts:def:: Float + + // JavaScript numbers. + type Float = number; + Ages ^^^^ diff --git a/core/api-exchange.rst b/core/api-exchange.rst index f7d63d0e..b4f2c3cb 100644 --- a/core/api-exchange.rst +++ b/core/api-exchange.rst @@ -174,10 +174,9 @@ possibly by using HTTPS. // Linear cost factor for the STEFAN curve used // to (over) approximate fees payable by amount. // - // Note that the total to be paid is first to be - // divided by the smallest denomination to obtain - // the value to be multiplied with. - stefan_lin: Amount; + // Note that this is a scalar, as it is multiplied + // with the actual amount. + stefan_lin: Float; // Type of the asset. "fiat", "crypto", "regional" // or "stock". Wallets should adjust their UI/UX -- cgit v1.2.3 From 87265fdf985cc48172ede01b8083414dbb75f94b Mon Sep 17 00:00:00 2001 From: Florian Dold Date: Fri, 9 Feb 2024 11:36:30 +0100 Subject: improve bank integration docs based on feedback from Antoine and Christian --- core/intro-bank-apis.rst | 44 ++++++++++++++++++++++++++++++++------------ 1 file changed, 32 insertions(+), 12 deletions(-) diff --git a/core/intro-bank-apis.rst b/core/intro-bank-apis.rst index ad97a36f..f4307138 100644 --- a/core/intro-bank-apis.rst +++ b/core/intro-bank-apis.rst @@ -34,8 +34,10 @@ Improved Withdrawal Process In principle, any typical account-based (core-)banking system can be used as the underlying account-based financial layer for GNU Taler. -However, without extra support from the bank, the user experience for Taler -withdrawals is not ideal. +However, without extra support from the bank, withdrawals can be difficult for +unexperienced users. Thus to make sure that a Taler deployment can achieve +mass adoption from non-technical users, extra integration by the bank / core +banking system should be provided. Withdrawals without any extra support from the core banking system require the user to make a transaction to a particular bank account (i.e. the exchange's @@ -44,10 +46,10 @@ This identifier is generated by the user's wallet when initiating a withdrawal from the wallet application. If the user misspells the identifier, the payment will be sent back automatically by the exchange. -However, the wallet has no information about whether bank the transfer was -already made by the user or if it was even made correctly. This makes it hard -to show accurate information to the user about the status of withdrawing -digital cash into their Taler wallet. +However, until the wire transfer is successfully completed, the wallet has no +information about whether the transfer was already made by the user or if it +was even made correctly. This makes it hard to show accurate information to +the user about the status of withdrawing digital cash into their Taler wallet. Withdrawal Bank-Integration API @@ -90,7 +92,8 @@ Payto-URI Integration ===================== When initiating a withdrawal from the Taler wallet, the wallet can generate a -payto:// link or QR code with the payment information necessary to make a +payto:// link or QR code (see `RFC 8905 `_) +with the payment information necessary to make a credit transfer to the exchange's settlement account. Banking apps may provide integration here simply by handling payto:// URIs. @@ -106,9 +109,26 @@ Future: Intent-Based Integration on Android (This type of integration is currently not specified, but planned for the future.) -On the Android platform, applications can communicate via Intents. That would -allow the Taler wallet to open a credit transfer dialog in a supported banking -app to fund a withdrawal. The banking app can send the status of the credit -transfer (confirmed/aborted by the user) back to the wallet, which can then -show more accurate status information about the withdrawal to the user. +On the Android platform, applications can communicate via +`Intents `_. +That would allow the Taler wallet to open a credit transfer dialog in a +supported banking app to fund a withdrawal. The banking app can send the +status of the credit transfer (confirmed/aborted by the user) back to the +wallet, which can then show more accurate status information about the +withdrawal to the user. + + +Integration for Merchants +######################### + +The Taler merchant backend has the option to connect to what +we call the :doc:`Bank Revenue API `. + +A core banking system may provide this API to merchants that have a business +account at the that bank. The API provides read-only access to incoming +transactions on the merchant bank account. +It allows merchants to easily and automatically reconcile incoming bank +transfers from the Taler exchange's settlement account with the respective +Taler payments. Usually multiple Taler payments are aggregated into one larger +payment in the underlying banking layer. -- cgit v1.2.3 From e5f80467bf6e74eb11447ac5e1c41ef25c67a064 Mon Sep 17 00:00:00 2001 From: Sebastian Date: Fri, 9 Feb 2024 10:01:58 -0300 Subject: fixing #8354 --- core/api-merchant.rst | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/core/api-merchant.rst b/core/api-merchant.rst index 46392118..24773c47 100644 --- a/core/api-merchant.rst +++ b/core/api-merchant.rst @@ -2669,8 +2669,12 @@ to validate that a customer made a payment. // Human-readable description for the device. otp_device_description: string; - // A base64-encoded key - otp_key: string; + // A key encoded with RFC 3548 Base32. + // IMPORTANT: This is not using the typical + // Taler base32-crockford encoding. + // Instead it uses the RFC 3548 encoding to + // be compatible with the TOTP standard. + otp_key?: string; // Algorithm for computing the POS confirmation. otp_algorithm: Integer; -- cgit v1.2.3 From 0a83900769669fbfe28f64587d14580a1ea94655 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Sat, 10 Feb 2024 11:37:34 +0100 Subject: document protocol change for #8353 --- core/api-merchant.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/core/api-merchant.rst b/core/api-merchant.rst index 24773c47..14206c8a 100644 --- a/core/api-merchant.rst +++ b/core/api-merchant.rst @@ -123,7 +123,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 **8**. + This specification corresponds to ``current`` protocol being version **9**. **Response:** @@ -2129,6 +2129,7 @@ Inspecting orders :query session_id: *Optional*. Session ID that the payment must be bound to. If not specified, the payment is not session-bound. :query transfer: *Deprecated in protocol V6*. *Optional*. If set to "YES", try to obtain the wire transfer status for this order from the exchange. Otherwise, the wire transfer status MAY be returned if it is available. :query timeout_ms: *Optional*. Timeout in milliseconds to wait for a payment if the answer would otherwise be negative (long polling). + :query allow_refunded_for_repurchase: *Optional*. Since protocol v9 refunded orders are only returned under "already_paid_order_id" if this flag is set explicitly to "YES". **Response:** -- cgit v1.2.3 From d948729fc0356418a8c1773d33870cb1ad2ae5b7 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Sat, 10 Feb 2024 13:04:12 +0100 Subject: allow filter also in public endpoint --- core/api-merchant.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/core/api-merchant.rst b/core/api-merchant.rst index 14206c8a..7cd0f0dd 100644 --- a/core/api-merchant.rst +++ b/core/api-merchant.rst @@ -412,6 +412,7 @@ Querying payment status merchant backend may return a response immediately. :query await_refund_obtained=BOOLEAN: *Optional*. If set to "yes", poll for the order's pending refunds to be picked up. ``timeout_ms`` specifies how long we will wait for the refund. :query refund=AMOUNT: *Optional*. Indicates that we are polling for a refund above the given AMOUNT. ``timeout_ms`` will specify how long we will wait for the refund. + :query allow_refunded_for_repurchase: *Optional*. Since protocol v9 refunded orders are only returned under "already_paid_order_id" if this flag is set explicitly to "YES". **Response:** -- cgit v1.2.3 From 05984ea52daa06b7575da19164dd26b2789f93a0 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Sat, 10 Feb 2024 17:04:48 +0100 Subject: misc fixes --- libeufin/nexus-manual.rst | 2 +- libeufin/regional-manual.rst | 10 +++++----- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/libeufin/nexus-manual.rst b/libeufin/nexus-manual.rst index 68613854..a5ef0e8e 100644 --- a/libeufin/nexus-manual.rst +++ b/libeufin/nexus-manual.rst @@ -212,7 +212,7 @@ subject that would be invalid for a Taler withdrawal, or from a Taler exchange that needs to send a payment to a merchant. For testing purposes it is possible to manually initiate a payment using the -``initiate-payment``subcommand. +``initiate-payment`` subcommand. The following invocation pays 1 CHF to the CH987654321 with an "Hello, Nexus!" subject: diff --git a/libeufin/regional-manual.rst b/libeufin/regional-manual.rst index 3a00a011..d17cf7c8 100644 --- a/libeufin/regional-manual.rst +++ b/libeufin/regional-manual.rst @@ -280,7 +280,7 @@ Using the Regional Currency =========================== Wallet Setup ------------- +++++++++++++ This section describes the interaction between the Taler graphical wallet (Android, iOS, WebExtensions) and the regional currency system. @@ -292,7 +292,7 @@ dialogue. Cash-In -------- ++++++++ Next, start the withdraw process in the Taler wallet for the respective currency and specify the desired amount. The wallet will then show you the @@ -310,7 +310,7 @@ wallet. Making payments ---------------- ++++++++++++++++ For testing, you should be able to *deposit* regional currency directly into your regional currency libeufin-bank account directly from the Taler wallet. @@ -332,7 +332,7 @@ again the bank account details to :ref:`setup instance bank accounts Cash-Out --------- +++++++++ Regional currency accounts that have a positive balance could be eligible for cash-out. Cash-out operations may again be restricted by the regional @@ -342,7 +342,7 @@ currency account, select cash-out, specify the desired amount and pass the second-factor authorization challenge by entering the TAN you receive at the registered e-mail address or mobile phone number. -.. note:: +note:: Cash-out operations may be subject to conversion rates, conversion fees and minimum amounts to be transferred. -- cgit v1.2.3 From 63885d038ccf5e94e267e4000411c8afeeaaead4 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Sat, 10 Feb 2024 23:01:11 +0100 Subject: -fix typo --- manpages/libeufin-sandbox.1.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/manpages/libeufin-sandbox.1.rst b/manpages/libeufin-sandbox.1.rst index e073500e..6f0948d0 100644 --- a/manpages/libeufin-sandbox.1.rst +++ b/manpages/libeufin-sandbox.1.rst @@ -70,16 +70,16 @@ config This command takes argument ``NAME`` and creates a demobank with that name. -Option ``--currency CUR`` (default: ``EUR``) specifes another currency. +Option ``--currency CUR`` (default: ``EUR``) specifies another currency. Option ``--captcha-url $URL`` specifies where the wallet user is going -to be redirected to confirm the withdrawal operation. This $URL should +to be redirected to confirm the withdrawal operation. This $URL should point to the bank frontend. More precisely to the UI that let the user finish a withdrawal operation that needs to be confirmed. Example of -this value may be "https://bank.domain/#/operation/{wopid}" where +this value may be "https://bank.domain/#/operation/{wopid}" where "https://bank.domain" returns the demobank SPA and the demobank view under the route "/operation/{wopid}" will show the status of the operation id {wopid}. Note that "{wopid}" is literally in the --captcha-url config and replaced at -runtime by the sandbox server. +runtime by the sandbox server. Option ``--bank-debt-limit N`` (default: 1000000) specifies that the bank debt limit should be N (units of currency). Similarly, option ``--users-debt-limit N`` (default: 1000) specifies -- cgit v1.2.3 From 3b47bac9e30cd44e49394b523ec53578e88db45f Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Sat, 10 Feb 2024 23:02:34 +0100 Subject: fix more typos --- manpages/taler.conf.5.rst | 2 +- taler-exchange-manual.rst | 4 ++-- taler-merchant-manual.rst | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/manpages/taler.conf.5.rst b/manpages/taler.conf.5.rst index 115dee8a..84606774 100644 --- a/manpages/taler.conf.5.rst +++ b/manpages/taler.conf.5.rst @@ -163,7 +163,7 @@ KYC_AML_TRIGGER Program to run on KYC attribute data to decide whether we should immediately flag an account for AML review. Program must return 0 if a manual AML review is not needed, and non-zero to trigger an AML review. The KYC attribute data of the new user will be passed on standard-input. STEFAN_ABS - Absolte amount to add as an offset in the STEFAN fee approximation + Absolute amount to add as an offset in the STEFAN fee approximation curve (see DD47). Defaults to CURRENCY:0 if not specified. STEFAN_LOG diff --git a/taler-exchange-manual.rst b/taler-exchange-manual.rst index 64c2a7d9..9cdd51d1 100644 --- a/taler-exchange-manual.rst +++ b/taler-exchange-manual.rst @@ -1382,7 +1382,7 @@ started using a simple command: At this point, the exchange service is not yet fully operational. -To check whether the exchange is running correctly under the advertized +To check whether the exchange is running correctly under the advertised base URL, run: .. code-block:: shell-session @@ -1673,7 +1673,7 @@ makes the decision given the KYC attributes: The given program will be given the KYC attributes in JSON format on standard input, and must return 0 to continue without AML and non-zero to flag the -account for manual review. To disable this triger, simply leave the option to +account for manual review. To disable this trigger, simply leave the option to its default value of '[/usr/bin/]true'. To flag all new users for manual review, simply set the program to '[/usr/bin/]false'. diff --git a/taler-merchant-manual.rst b/taler-merchant-manual.rst index 9ed7ea3e..97a422d0 100644 --- a/taler-merchant-manual.rst +++ b/taler-merchant-manual.rst @@ -567,7 +567,7 @@ For the ``postgres`` backend, you need to specify: [merchantdb-postgres] CONFIG = "postgres:///taler-merchant" -This option specifies a PostgreSQL access path, typicallly using the format +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, ``taler-merchant`` on the local machine). Suppose ``$USER`` is the name of the user who will run the backend process -- cgit v1.2.3 From 1230914677e2cf3a680179236c3e5c8b1c2b00db Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Sat, 10 Feb 2024 23:09:47 +0100 Subject: -typo --- frags/libeufin-config-cli.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/frags/libeufin-config-cli.rst b/frags/libeufin-config-cli.rst index 3974aea8..5475324e 100644 --- a/frags/libeufin-config-cli.rst +++ b/frags/libeufin-config-cli.rst @@ -20,7 +20,7 @@ It takes two arguments, the section name and the option name **-c** \| **--config** *FILENAME* Specifies the configuration file. **-L** \| **--log** *LOGLEVEL* - Configure logging to use LOGLEVEL. + Configure logging to use LOGLEVEL. **-f** \| **--filename** Interpret value as path with dollar-expansion. @@ -34,18 +34,18 @@ This command dump the configuration. **-c** \| **--config** *FILENAME* Specifies the configuration file. **-L** \| **--log** *LOGLEVEL* - Configure logging to use LOGLEVEL. + Configure logging to use LOGLEVEL. config pathsub -------------- This command substitute variables in a path. -It takes one argument, a path expresion. +It takes one argument, a path expression. **-h** \| **--help** Print short help on options. **-c** \| **--config** *FILENAME* Specifies the configuration file. **-L** \| **--log** *LOGLEVEL* - Configure logging to use LOGLEVEL. \ No newline at end of file + Configure logging to use LOGLEVEL. -- cgit v1.2.3 From 40cbc8c2e78d4203845d5589df6b241861bfbcee Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Sun, 11 Feb 2024 14:44:18 +0100 Subject: clarify documentation for #8056 --- core/api-exchange.rst | 71 ++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 50 insertions(+), 21 deletions(-) diff --git a/core/api-exchange.rst b/core/api-exchange.rst index b4f2c3cb..429170ce 100644 --- a/core/api-exchange.rst +++ b/core/api-exchange.rst @@ -1,6 +1,6 @@ .. This file is part of GNU TALER. - Copyright (C) 2014-2023 Taler Systems SA + Copyright (C) 2014-2024 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 @@ -4832,9 +4832,18 @@ wallet-to-wallet payments. Only another exchange should access this endpoint. KYC status updates ------------------ +This section describes endpoints used to set up, complete and +inquire about KYC operations performed by an exchange for +regulatory compliance. + .. http:post:: /kyc-wallet Setup KYC identification for a wallet. Returns the KYC UUID. + This endpoint is used by compliant Taler wallets when they + are about to hit the balance threshold and thus need to have + the customer provide their personal details to the exchange. + The wallet is identified by its long-lived reserve public key + (which is used for P2P payments, not for withdrawals). **Request:** @@ -4891,15 +4900,18 @@ KYC status updates .. http:get:: /kyc-check/$REQUIREMENT_ROW/$H_PAYTO/$USERTYPE - Check or update KYC status of a particular payment target. - Returns the current KYC status of the account and, if - negative, returns the URL where the KYC process can be - initiated. The ``$REQUIREMENT_ROW`` must have been - returned previously from an exchange API endpoint that - determined that KYC was needed. The ``$H_PATYO`` must be - the hash of the payto:// URI of the payment target. - The ``$USERTYPE`` states whether the entity to perform - the KYC is an "individual" or "business". + Checks the KYC status of a particular payment target and possibly begins the + KYC process. This endpoint is used by wallets or merchants that have been + told about a KYC requirement and now want to check if the KYC requirement + has been fulfilled. Long-polling may be used to instantly observe a change + in the KYC requirement status. + + Returns the current KYC status of the requirement process and, if negative, + returns the URL where the KYC process can be initiated. The + ``$REQUIREMENT_ROW`` must have been returned previously from an exchange API + endpoint that determined that KYC was needed. The ``$H_PATYO`` must be the + hash of the "payto://" URI of the payment target. The ``$USERTYPE`` states + whether the entity to perform the KYC is an "individual" or a "business". **Request:** @@ -4918,12 +4930,13 @@ KYC status updates The response will be an `AccountKycStatus` object. :http:statuscode:`202 Accepted`: The user should be redirected to the provided location to perform - the required KYC checks to open the account. Afterwards, the - ``/kyc-check/`` request should be repeated. + the required KYC checks to satisfy the legal requirements. Afterwards, the + ``/kyc-check/`` request should be repeated to check whether the + user has completed the process. The response will be an `AccountKycRedirect` object. :http:statuscode:`204 No content`: The exchange is not configured to perform KYC and thus - generally all accounts are simply considered legitimate. + the legal requirements are already satisfied. :http:statuscode:`402 Payment Required`: The client must pay the KYC fee for the KYC process. **This is currently not implemented, see #7365.** @@ -4933,6 +4946,10 @@ KYC status updates The payment target is unknown. :http:statuscode:`451 Unavailable for Legal Reasons`: The transaction cannot be completed due to AML rules. + Thus, the operation is currently not stuck on KYC, but + on exchange staff performing their AML review. The user + should be told to wait and/or contact the exchange operator + if the situation persists. The response will be a `AccountAmlBlocked` object. **Details:** @@ -5003,10 +5020,18 @@ KYC status updates .. http:get:: /kyc-proof/$PROVIDER_SECTION?state=$H_PAYTO - Update KYC status of a particular payment target. Provides + Endpoint accessed from the user's browser at the *end* of a + KYC process, possibly providing the exchange with additional + credentials to obtain the results of the KYC process. + Specifically, the URL arguments should provide information to the exchange that allows it to verify that the user has completed the KYC process. The details depend on - the logic, which is selected by the $PROVIDER_SECTION. + the logic, which is selected by the "$PROVIDER_SECTION". + + While this is a GET (and thus safe, and idempotent), the operation + may actually trigger significant changes in the exchange's state. + In particular, it may update the KYC status of a particular + payment target. **Request:** @@ -5025,6 +5050,10 @@ KYC status updates **Response:** + Given that the response is returned to a user using a browser and **not** to + a Taler wallet, the response format is in human-readable HTML and not in + machine-readable JSON. + :http:statuscode:`302 Found`: The KYC operation succeeded and the payment target is now authorized to transact. @@ -5047,11 +5076,11 @@ KYC status updates .. http:get:: /kyc-webhook/$LOGIC/* .. http:post:: /kyc-webhook/$LOGIC/* - Update KYC status of a particular payment target. Provides - information to the KYC logic of the exchange that allows - it to verify that the user has completed the KYC process. - May be a GET or a POST request, depending on $LOGIC or - $PROVIDER_SECTION. + All of the above endpoints can be used to update KYC status of a particular + payment target. They provide information to the KYC logic of the exchange + that allows it to verify that the user has completed the KYC process. May + be a GET or a POST request, depending on the specific "$LOGIC" and/or the + "$PROVIDER_SECTION". **Request:** @@ -5061,7 +5090,7 @@ KYC status updates **Response:** :http:statuscode:`204 No content`: - The webhook succeeded. + The operation succeeded. :http:statuscode:`404 Not found`: The specified logic is unknown. -- cgit v1.2.3 From a2dba11f1da7ee18eb2da19533e92a700fa755fc Mon Sep 17 00:00:00 2001 From: Antoine A <> Date: Mon, 12 Feb 2024 11:03:48 +0100 Subject: Improve regional currency manual --- libeufin/regional-manual.rst | 3 ++- manpages/libeufin-nexus.conf.5.rst | 2 +- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/libeufin/regional-manual.rst b/libeufin/regional-manual.rst index d17cf7c8..d7187117 100644 --- a/libeufin/regional-manual.rst +++ b/libeufin/regional-manual.rst @@ -134,7 +134,8 @@ Navigate into the *regional-currency/* directory, and as **root** run: .. code-block:: console - # ./main.sh + $ cd deployment/regional-currency/ + $ sudo ./main.sh The script will start by asking you fundamental questions about the desired setup, in particular: diff --git a/manpages/libeufin-nexus.conf.5.rst b/manpages/libeufin-nexus.conf.5.rst index 8b281f7f..e70ff7b3 100644 --- a/manpages/libeufin-nexus.conf.5.rst +++ b/manpages/libeufin-nexus.conf.5.rst @@ -111,7 +111,7 @@ the ``libeufin-nexus ebics-setup`` command. CURRENCY Name of the currency, e.g. “EUR” for Euro. -HOST_BASE_URL = http://bank.example.com/ +HOST_BASE_URL URL of the EBICS server BANK_DIALECT -- cgit v1.2.3 From 808abd6ee3c8dc5053e69a7ba8df4b4d3cf29a6a Mon Sep 17 00:00:00 2001 From: Antoine A <> Date: Mon, 12 Feb 2024 18:03:50 +0100 Subject: Improve regional currency manual --- libeufin/bank-manual.rst | 2 +- libeufin/nexus-manual.rst | 20 ++++++++-------- libeufin/regional-manual.rst | 54 ++++++++++++++++++++++---------------------- 3 files changed, 37 insertions(+), 39 deletions(-) diff --git a/libeufin/bank-manual.rst b/libeufin/bank-manual.rst index 83f25f6a..25b793ea 100644 --- a/libeufin/bank-manual.rst +++ b/libeufin/bank-manual.rst @@ -255,7 +255,7 @@ Withdrawing e-cash to a Taler wallet .. note:: - This step is fully automated if you use the :ref:`guided automated setup `. + This step is fully automated if you use the :ref:`guided automated setup `. Users can withdraw digital cash from their bank account starting from their online banking as implemented by the libeufin-bank. However, in this scenario, diff --git a/libeufin/nexus-manual.rst b/libeufin/nexus-manual.rst index a5ef0e8e..c51b8838 100644 --- a/libeufin/nexus-manual.rst +++ b/libeufin/nexus-manual.rst @@ -105,25 +105,25 @@ The following snippet shows the mandatory configuration values: CURRENCY = CHF # Bank - HOST_BASE_URL = http://bank.example.com/ + HOST_BASE_URL = https://ebics.postfinance.ch/ebics/ebics.aspx BANK_DIALECT = postfinance # EBICS IDs - HOST_ID = mybank - USER_ID = myuser - PARTNER_ID = myorg + HOST_ID = PFEBICS + USER_ID = PFC00563 + PARTNER_ID = PFC00563 # Account information - IBAN = myiban - BIC = mybic - NAME = myname + IBAN = CH7789144474425692816 + BIC = POFICHBEXXX + NAME = John Smith S.A. .. note:: Refer to the manpage ``libeufin-nexus.conf(5)`` for the full array of configuration values. .. note:: - If you want to use existing client keys, copy the JSON file to the configured path ``CLIENT_PRIVATE_KEYS_FILE`` (``/var/lib/libeufin-nexus/client-ebics-keys.json`` by default) before running the following commands. + If you want to use existing client keys, copy the JSON file to the configured path ``CLIENT_PRIVATE_KEYS_FILE`` (``/var/lib/libeufin-nexus/client-ebics-keys.json`` with the default config) before running the following commands. Assuming that the configuration file exists at ``$CONFIG_FILE``, the following command should start the EBICS setup process: @@ -314,8 +314,6 @@ The ``--debug-ebics $SAVEDIR`` flag will cause the files to be stored in date when the download took place. This is mostly useful for debugging. - - For Testing ----------- @@ -327,7 +325,7 @@ the present: .. code-block:: console - $ libeufin-nexus ebics-fetch -c "$CONFIG_FILE" --pinned-start 2023-06-01 + $ libeufin-nexus ebics-fetch -c "$CONFIG_FILE" --pinned-start 2023-11-01 .. note:: diff --git a/libeufin/regional-manual.rst b/libeufin/regional-manual.rst index d7187117..1a28fa6e 100644 --- a/libeufin/regional-manual.rst +++ b/libeufin/regional-manual.rst @@ -130,36 +130,36 @@ Running the Guided Configuration This approach sets up a regional currency with cash-in/-out rates of 1:1. -Navigate into the *regional-currency/* directory, and as **root** run: +Navigate into the *regional-currency/* directory and run *main.sh* as **root**: .. code-block:: console $ cd deployment/regional-currency/ - $ sudo ./main.sh + # ./main.sh The script will start by asking you fundamental questions about the desired setup, in particular: - * The name of the regional currency. It must have 3 to 11 letters. - * The ISO code of the fiat currency. Use 'CHF' or 'EUR'. - * The name of the regional currency bank. It will be shown to business - users when they interact with the system. - * Whether to use TLS or not. You should answer ``y`` in most cases. - * Whether to run taler-exchange-offline. Unless you need a high-security - setup and expect to run an offline key management process, say ``y``. - If you say ``n``, you will need to run ``taler-exchange-offline setup`` - on your offline system and provide the master public key. Furthermore, - you should then study the exchange manual on offline key management to - finish the exchange setup process later. - * The admin password for the bank. Be absolutely sure to enter a very, - very long and high-entropy password, preferably use the autogenerated one. - * The DNS domain name of your setup (i.e: domain.tld). The installer will - create by itself all the needed subdomains for your domain name, - as (``bank.$DOMAIN``, ``exchange.$DOMAIN`` and ``backend.$DOMAIN``). - But, these subdomain names, must have been added beforehand to your - DNS domain control panel, and they must be pointing to the - IP address of the system on which you are running the - installation (before you execute the installer). +* The name of the regional currency. It must have 3 to 11 letters. +* The ISO code of the fiat currency. Use 'CHF' or 'EUR'. +* The name of the regional currency bank. It will be shown to business + users when they interact with the system. +* Whether to use TLS or not. You should answer ``y`` in most cases. +* Whether to run taler-exchange-offline. Unless you need a high-security + setup and expect to run an offline key management process, say ``y``. + If you say ``n``, you will need to run ``taler-exchange-offline setup`` + on your offline system and provide the master public key. Furthermore, + you should then study the exchange manual on offline key management to + finish the exchange setup process later. +* The admin password for the bank. Be absolutely sure to enter a very, + very long and high-entropy password, preferably use the autogenerated one. +* The DNS domain name of your setup (i.e: domain.tld). The installer will + create by itself all the needed subdomains for your domain name, + as (``bank.$DOMAIN``, ``exchange.$DOMAIN`` and ``backend.$DOMAIN``). + But, these subdomain names, must have been added beforehand to your + DNS domain control panel, and they must be pointing to the + IP address of the system on which you are running the + installation (before you execute the installer). The information you entered as well as the generated bank admin password will be stored in a file called ``config/user.conf``. Should you run the script in @@ -212,9 +212,9 @@ channel for :ref:`multi-factor authentication ` is configured: Make sure to (re)start the libeufin-bank after changing these configuration options: - .. code-block:: console +.. code-block:: console - # systemctl restart libeufin-bank + # systemctl restart libeufin-bank Web-based Configuration @@ -343,10 +343,10 @@ currency account, select cash-out, specify the desired amount and pass the second-factor authorization challenge by entering the TAN you receive at the registered e-mail address or mobile phone number. -note:: +.. note:: - Cash-out operations may be subject to conversion rates, conversion fees and - minimum amounts to be transferred. + Cash-out operations may be subject to conversion rates, conversion fees and + minimum amounts to be transferred. Alternative Podman-based Deployment -- cgit v1.2.3 From da24ce8a77e8aac371ad05837a14319328b2fc98 Mon Sep 17 00:00:00 2001 From: Florian Dold Date: Mon, 12 Feb 2024 22:20:00 +0100 Subject: bank integration API: document previous behavior of confirm_transfer_url --- core/api-bank-integration.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/core/api-bank-integration.rst b/core/api-bank-integration.rst index 748d98da..4131a28a 100644 --- a/core/api-bank-integration.rst +++ b/core/api-bank-integration.rst @@ -119,6 +119,7 @@ for the withdrawal operation (the ``WITHDRAWAL_ID``) to interact with the withdr // URL that the user needs to navigate to in order to // complete some final confirmation (e.g. 2FA). + // Only applicable when ``status`` is ``selected`` or ``pending``. // It may contain withdrawal operation id confirm_transfer_url?: string; @@ -194,7 +195,7 @@ for the withdrawal operation (the ``WITHDRAWAL_ID``) to interact with the withdr // URL that the user needs to navigate to in order to // complete some final confirmation (e.g. 2FA). // - // Only applicable when ``status`` is ``selected``. + // Only applicable when ``status`` is ``selected`` or ``pending``. // It may contain withdrawal operation id confirm_transfer_url?: string; -- cgit v1.2.3 From e69d507a90b51984a92550b38140a8258b92936d Mon Sep 17 00:00:00 2001 From: Sebastian Date: Tue, 13 Feb 2024 12:12:21 -0300 Subject: update wallet core docs --- wallet/wallet-core.md | 146 ++++++++++++++++---------------------------------- 1 file changed, 46 insertions(+), 100 deletions(-) diff --git a/wallet/wallet-core.md b/wallet/wallet-core.md index 449dfbbb..977e100d 100644 --- a/wallet/wallet-core.md +++ b/wallet/wallet-core.md @@ -46,9 +46,6 @@ This file is auto-generated from [wallet-core](https://git.taler.net/wallet-core * [AddGlobalCurrencyAuditorOp](#addglobalcurrencyauditorop) * [RemoveGlobalCurrencyExchangeOp](#removeglobalcurrencyexchangeop) * [RemoveGlobalCurrencyAuditorOp](#removeglobalcurrencyauditorop) -### Rewards -* [PrepareTipOp](#preparetipop) -* [AcceptTipOp](#accepttipop) ### Exchange Management * [ListExchangesOp](#listexchangesop) * [ListExchangesForScopedCurrencyOp](#listexchangesforscopedcurrencyop) @@ -389,8 +386,16 @@ export type GetTransactionsOp = { export interface TransactionsRequest { /** * return only transactions in the given currency + * + * it will be removed in next release + * + * @deprecated use scopeInfo */ currency?: string; + /** + * return only transactions in the given scopeInfo + */ + scopeInfo?: ScopeInfo; /** * if present, results will be limited to transactions related to the given search string */ @@ -422,6 +427,18 @@ export type ListAssociatedRefreshesOp = { }; // ListAssociatedRefreshes = "listAssociatedRefreshes" +``` +```typescript +export interface ListAssociatedRefreshesRequest { + transactionId: string; +} + +``` +```typescript +export interface ListAssociatedRefreshesResponse { + transactionIds: string[]; +} + ``` ### TestingGetSampleTransactionsOp @@ -917,7 +934,7 @@ export interface ConfirmPayRequest { * @deprecated use transactionId instead */ proposalId?: string; - transactionId?: string; + transactionId?: TransactionIdStr; sessionId?: string; forcedCoinSel?: ForcedCoinSel; } @@ -968,6 +985,9 @@ export interface PrepareRefundRequest { ``` ```typescript export interface StartRefundQueryForUriResponse { + /** + * Transaction id of the *payment* where the refund query was started. + */ transactionId: TransactionIdStr; } @@ -1108,96 +1128,6 @@ export interface RemoveGlobalCurrencyAuditorRequest { ``` -### PrepareTipOp -```typescript -/** - * Query and store information about a reward. - */ -export type PrepareTipOp = { - op: WalletApiOperation.PrepareReward; - request: PrepareRewardRequest; - response: PrepareRewardResult; -}; -// PrepareReward = "prepareReward" - -``` -```typescript -export interface PrepareRewardRequest { - talerRewardUri: string; -} - -``` -```typescript -export interface PrepareTipResult { - /** - * Unique ID for the tip assigned by the wallet. - * Typically different from the merchant-generated tip ID. - * - * @deprecated use transactionId instead - */ - walletRewardId: string; - /** - * Tip transaction ID. - */ - transactionId: string; - /** - * Has the tip already been accepted? - */ - accepted: boolean; - /** - * Amount that the merchant gave. - */ - rewardAmountRaw: AmountString; - /** - * Amount that arrived at the wallet. - * Might be lower than the raw amount due to fees. - */ - rewardAmountEffective: AmountString; - /** - * Base URL of the merchant backend giving then tip. - */ - merchantBaseUrl: string; - /** - * Base URL of the exchange that is used to withdraw the tip. - * Determined by the merchant, the wallet/user has no choice here. - */ - exchangeBaseUrl: string; - /** - * Time when the tip will expire. After it expired, it can't be picked - * up anymore. - */ - expirationTimestamp: TalerProtocolTimestamp; -} - -``` - -### AcceptTipOp -```typescript -/** - * Accept a reward. - */ -export type AcceptTipOp = { - op: WalletApiOperation.AcceptReward; - request: AcceptRewardRequest; - response: AcceptTipResponse; -}; -// AcceptReward = "acceptReward" - -``` -```typescript -export interface AcceptRewardRequest { - walletRewardId: string; -} - -``` -```typescript -export interface AcceptTipResponse { - transactionId: TransactionIdStr; - next_url?: string; -} - -``` - ### ListExchangesOp ```typescript /** @@ -1720,7 +1650,7 @@ export interface CreateDepositGroupRequest { * that occur while the operation has been created but * before the creation request has returned. */ - transactionId?: string; + transactionId?: TransactionIdStr; depositPaytoUri: string; amount: AmountString; } @@ -2236,7 +2166,7 @@ export interface PreparePeerPushCreditResponse { contractTerms: PeerContractTerms; amountRaw: AmountString; amountEffective: AmountString; - transactionId: string; + transactionId: TransactionIdStr; exchangeBaseUrl: string; /** * @deprecated use transaction ID instead. @@ -2373,7 +2303,7 @@ export interface PreparePeerPullDebitResponse { amountRaw: AmountString; amountEffective: AmountString; peerPullDebitId: string; - transactionId: string; + transactionId: TransactionIdStr; } ``` @@ -2399,7 +2329,7 @@ export interface ConfirmPeerPullDebitRequest { * @deprecated use transactionId instead */ peerPullDebitId?: string; - transactionId?: string; + transactionId?: TransactionIdStr; } ``` @@ -2450,6 +2380,12 @@ export type ImportDbOp = { }; // ImportDb = "importDb" +``` +```typescript +export interface ImportDbRequest { + dump: any; +} + ``` ### ClearDbOp @@ -3241,7 +3177,7 @@ export type TestingWaitTransactionStateOp = { ``` ```typescript export interface TestingWaitTransactionRequest { - transactionId: string; + transactionId: TransactionIdStr; txState: TransactionState; } @@ -3374,7 +3310,8 @@ export type Transaction = | TransactionPeerPullDebit | TransactionPeerPushCredit | TransactionPeerPushDebit - | TransactionInternalWithdrawal; + | TransactionInternalWithdrawal + | TransactionRecoup; ``` ```typescript /** @@ -3444,6 +3381,7 @@ export declare enum TransactionType { PeerPushCredit = "peer-push-credit", PeerPullDebit = "peer-pull-debit", PeerPullCredit = "peer-pull-credit", + Recoup = "recoup", } ``` ```typescript @@ -4060,6 +3998,14 @@ export interface TransactionInternalWithdrawal extends TransactionCommon { } ``` ```typescript +/** + * The exchange revoked a key and the wallet recoups funds. + */ +export interface TransactionRecoup extends TransactionCommon { + type: TransactionType.Recoup; +} +``` +```typescript export interface AbortTransactionRequest { transactionId: TransactionIdStr; } -- cgit v1.2.3 From 289bbd7a3be772e64ccc1fcc141f255c543c9e9e Mon Sep 17 00:00:00 2001 From: Antoine A <> Date: Wed, 14 Feb 2024 22:17:52 +0100 Subject: Improve regional currency manual --- libeufin/nexus-manual.rst | 3 ++ libeufin/regional-manual.rst | 101 +++++++++++++++++++++---------------------- 2 files changed, 52 insertions(+), 52 deletions(-) diff --git a/libeufin/nexus-manual.rst b/libeufin/nexus-manual.rst index c51b8838..022d90a8 100644 --- a/libeufin/nexus-manual.rst +++ b/libeufin/nexus-manual.rst @@ -95,6 +95,9 @@ with various credentials. Those must be provided in the ``/etc/libeufin/libeufin-nexus.conf`` configuration file together with the name of the *fiat* currency. +.. note:: + As legacy transactions in that bank account would likely confuse the system, it is advisable to use a fresh bank account with an empty transaction history. + The following snippet shows the mandatory configuration values: .. _core-config: diff --git a/libeufin/regional-manual.rst b/libeufin/regional-manual.rst index 1a28fa6e..beec5d0c 100644 --- a/libeufin/regional-manual.rst +++ b/libeufin/regional-manual.rst @@ -23,21 +23,16 @@ Regional Currency Setup Manual ############################## -In this manual, we explain how to set up a regional currency with or without -currency conversion from and to fiat currency. Most of this manual is about -setting up the currency conversion logic with a fiat bank that offers an EBICS -interface. - -If you want to run a regional currency without any conversion from or to a -fiat currency, all you need to do is set up the :ref:`libeufin-bank -` and integrate it with a Taler exchange. As a result, several -sections in this manual related to currency conversion can be -skipped. However, you may still find the :ref:`guided setup -` helpful. +This manual explains how to set up a regional currency that may be backed by a fiat currency. Most of the manual is concerned with setting up the currency conversion logic with a fiat bank that offers an EBICS interface. + +To understand how the regional currency works and how it is backed by a fiat currency, you can read about its :ref:`architecture`. + +If you want to setup a regional currency backed by a fiat currency, you can use the :ref:`guided automated setup`, which largely automates the process. You can also follow the :ref:`manual setup` if you want a customized one. .. contents:: Table of Contents :local: +.. _regional-currency-setup-architecture: Architecture ============ @@ -89,18 +84,12 @@ a fiat payment of N units to the fiat bank account owned by the user who initiat cash-out. - .. _automated-regional-currency-setup: Guided Automated Setup ====================== -You can either manually follow the steps to :ref:`setup libeufin-nexus -` and :ref:`setup libeufin-bank ` or use the -script described in this section which largely automates the process. If you -choose to use the manual setup, you should skip the final step that actually -starts the Nexus commands to initate payments and download transaction data -until most of the setup steps below have been completed! +This section describes how to setup a regional currency backed by a fiat currency using a script that largely automates the process. You can also follow the :ref:`manual setup` if you want a customized one. Prerequisites +++++++++++++ @@ -111,11 +100,6 @@ Furthermore, you should run the process on a system with one or more globally reachable IP address(es) *and* with various DNS names already pointing to these IPs. -To further simplify the process, we suggest to use (or at least study) the -automatic deployment scripts provided in the ``deployment.git`` Git repository -in the ``regional-currency/`` folder. - - Obtaining the Scripts +++++++++++++++++++++ @@ -123,13 +107,12 @@ First, download the deployment scripts via Git: .. code-block:: console + # apt update && apt install git $ git clone git://git.taler.net/deployment Running the Guided Configuration ++++++++++++++++++++++++++++++++ -This approach sets up a regional currency with cash-in/-out rates of 1:1. - Navigate into the *regional-currency/* directory and run *main.sh* as **root**: .. code-block:: console @@ -144,6 +127,13 @@ desired setup, in particular: * The ISO code of the fiat currency. Use 'CHF' or 'EUR'. * The name of the regional currency bank. It will be shown to business users when they interact with the system. +* The DNS domain name of your setup (i.e: domain.tld). The installer will + create by itself all the needed subdomains for your domain name, + as (``bank.$DOMAIN``, ``exchange.$DOMAIN`` and ``backend.$DOMAIN``). + But, these subdomain names, must have been added beforehand to your + DNS domain control panel, and they must be pointing to the + IP address of the system on which you are running the + installation (before you execute the installer). * Whether to use TLS or not. You should answer ``y`` in most cases. * Whether to run taler-exchange-offline. Unless you need a high-security setup and expect to run an offline key management process, say ``y``. @@ -153,13 +143,6 @@ desired setup, in particular: finish the exchange setup process later. * The admin password for the bank. Be absolutely sure to enter a very, very long and high-entropy password, preferably use the autogenerated one. -* The DNS domain name of your setup (i.e: domain.tld). The installer will - create by itself all the needed subdomains for your domain name, - as (``bank.$DOMAIN``, ``exchange.$DOMAIN`` and ``backend.$DOMAIN``). - But, these subdomain names, must have been added beforehand to your - DNS domain control panel, and they must be pointing to the - IP address of the system on which you are running the - installation (before you execute the installer). The information you entered as well as the generated bank admin password will be stored in a file called ``config/user.conf``. Should you run the script in @@ -175,26 +158,44 @@ Grab a coffee. At this point, the setup is NOT connected to any fiat bank account! The next steps must always be done manually! +Web-based Configuration ++++++++++++++++++++++++ + +This script sets up a regional currency with conversion rates of 1:1. You can change conversion rates and ``admin`` debt limit through the Web interface of the bank as the ``admin`` user. Connecting to a Fiat Bank: the EBICS setup -========================================== +++++++++++++++++++++++++++++++++++++++++++ -Some regional currencies are backed by assets in a fiat currency and allow -users to convert fiat currency into the regional currency (``cash in``) and to -convert regional currency into fiat currency (``cash out``). Restrictions, -exchange rates and fees may apply to these conversions. This section explains -how to setup LibEuFin Nexus to communicate with the fiat bank account that -backs the regional currency. +To complete the conversion setup, you have to set up an EBICS subscriber as described in :ref:`EBICS setup ` using a bank account at a bank dealing in fiat currency that offers an online banking protocol supported by LibEuFin Nexus. -First, you must set up an EBICS subscriber as described in :ref:`EBICS setup -` using a bank account at a bank dealing in fiat currency that -offers an online banking protocol supported by LibEuFin Nexus. As legacy -transactions in that bank account would likely confuse the system, it is -advisable to use a fresh bank account with an empty transaction history. +System ON! +++++++++++ +The last step is to enable libeufin-nexus to :ref:`import incoming bank +transactions ` (cash in) and to :ref:`trigger +outgoing bank transactions ` (cash out). + +.. code-block:: console + + # systemd enable --now libeufin-nexus-ebics-fetch + # systemd enable --now libeufin-nexus-ebics-submit + +.. _manual-regional-currency-setup: + +Manual Setup +============ + +This section describes how to setup a regional currency manually. + +You first need to setup the :ref:`libeufin-bank` and integrate it with a Taler exchange. + +If you don't want your regional currency to be backed by a fiat currency, you can stop here. Enabling Currency Conversion -============================ +++++++++++++++++++++++++++++ + +You need to setup the :ref:`libeufin-nexus` using a bank account at a bank dealing in fiat currency that +offers an online banking protocol supported by LibEuFin Nexus. Next, you have to enable conversion and should ensure that at least one TAN channel for :ref:`multi-factor authentication ` is configured: @@ -220,9 +221,7 @@ these configuration options: Web-based Configuration +++++++++++++++++++++++ -Now you should be able to setup conversion rates and ``admin`` debt limit though the Web -interface of the bank as the ``admin`` user. - +Now you have to setup conversion rates and ``admin`` debt limit through the Web interface of the bank as the ``admin`` user. .. _regional-conversion-setup: @@ -237,7 +236,7 @@ You will need to use the ``taler-exchange-offline`` tool to inform the exchange about the **fiat** bank account that can be used for cash in operations and also specify the URL for currency conversion. Additionally, you may also configure restrictions on the bank accounts that may originate -the funds, for example to prevent international wire transfers that may expose +the funds, for example, to prevent international wire transfers that may expose you to additional compliance risks. Given the ``$IBAN`` of the fiat currency bank account and ``$NAME`` as @@ -263,9 +262,8 @@ in our setup. You (or the guided setup script) should have already enabled the regional currency bank account (without any "conversion-url"). - System ON! -========== +++++++++++ The last step is to enable libeufin-nexus to :ref:`import incoming bank transactions ` (cash in) and to :ref:`trigger @@ -276,7 +274,6 @@ outgoing bank transactions ` (cash out). # systemd enable --now libeufin-nexus-ebics-fetch # systemd enable --now libeufin-nexus-ebics-submit - Using the Regional Currency =========================== -- cgit v1.2.3 From bcb0468f55def20361cdca493eef54fc9004f4f9 Mon Sep 17 00:00:00 2001 From: Antoine A <> Date: Thu, 15 Feb 2024 15:06:50 +0100 Subject: Improve regional currency manual --- libeufin/bank-manual.rst | 34 ++++++++++++++++++---------------- libeufin/nexus-manual.rst | 3 +++ libeufin/regional-manual.rst | 9 +++++++-- 3 files changed, 28 insertions(+), 18 deletions(-) diff --git a/libeufin/bank-manual.rst b/libeufin/bank-manual.rst index 25b793ea..4dd74210 100644 --- a/libeufin/bank-manual.rst +++ b/libeufin/bank-manual.rst @@ -104,16 +104,25 @@ The following snippet shows the mandatory configuration values: Configuring multi-factor authentication --------------------------------------- -libeufin-bank uses helper scripts to send challenge codes to addresses for -multi-factor authentication. By default, those helper scripts are -``libeufin-tan-email.sh`` to send e-mails and ``libeufin-tan-sms.sh`` to send -SMS. It is possible to replace these scripts with use custom scripts to send -the e-mail or SMS TAN. +libeufin-bank supports two factor authentification. libeufin-bank uses helper scripts to send challenge codes to addresses for multi-factor authentication. By default, those helper scripts are ``libeufin-tan-email.sh`` to send e-mails and ``libeufin-tan-sms.sh`` to send SMS. To enable two factor authentication you need to configure at least one TAN channel: -Such alternative scripts must accept the phone number / e-mail address as the -``$1`` parameter and the message content to be transmitted in their standard -input. They should return 0 to indicate successful transmission of the -challenge, and non-zero on failure. +.. code-block:: ini + + [libeufin-bank] + TAN_SMS = libeufin-tan-sms.sh + # And/Or + TAN_EMAIL = libeufin-tan-email.sh + +.. note:: + + The default ``libeufin-tan-sms.sh`` script is based on the `Telesign `_ provider. It requires an additional ``telesign-secrets`` script in the PATH that sets the ``CUSTOMER_ID`` and the ``API_KEY`` for the Telesign API. + +.. note:: + + The default ``libeufin-tan-email.sh`` script is based on the ``mail`` linux command. It requires a working local mail transfer agent. + +It is possible to replace these scripts with use custom scripts to send +the e-mail or SMS TAN. Such alternative scripts must accept the phone number / e-mail address as the ``$1`` parameter and the message content to be transmitted in their standard input. They should return 0 to indicate successful transmission of the challenge, and non-zero on failure. To change the scripts used for multi-factor authentication, change the following options in the configuration file: @@ -124,13 +133,6 @@ options in the configuration file: TAN_SMS = custom-tan-sms.sh TAN_EMAIL = custom-tan-email.sh -.. note:: - - The default ``libeufin-tan-sms.sh`` script is based on the `Telesign - `_ provider. It requires an additional local - resource file or environment variables with your Telesign credentials to - exist. - Launching libeufin-bank ======================= diff --git a/libeufin/nexus-manual.rst b/libeufin/nexus-manual.rst index 022d90a8..7ac59467 100644 --- a/libeufin/nexus-manual.rst +++ b/libeufin/nexus-manual.rst @@ -125,6 +125,9 @@ The following snippet shows the mandatory configuration values: Refer to the manpage ``libeufin-nexus.conf(5)`` for the full array of configuration values. +.. warning:: + This combination of HOST_ID, USER_ID and PARTNER_ID must never be used by another instance of libeufin-nexus or by other EBICS clients, otherwise data will be lost. + .. note:: If you want to use existing client keys, copy the JSON file to the configured path ``CLIENT_PRIVATE_KEYS_FILE`` (``/var/lib/libeufin-nexus/client-ebics-keys.json`` with the default config) before running the following commands. diff --git a/libeufin/regional-manual.rst b/libeufin/regional-manual.rst index beec5d0c..d2571b24 100644 --- a/libeufin/regional-manual.rst +++ b/libeufin/regional-manual.rst @@ -158,10 +158,15 @@ Grab a coffee. At this point, the setup is NOT connected to any fiat bank account! The next steps must always be done manually! +Multi-factor authentification ++++++++++++++++++++++++++++++ + +By default, multi-factor authentication via SMS and email is enabled. You have to manually configure both channels as described in :ref:`multi-factor authentication `. + Web-based Configuration +++++++++++++++++++++++ -This script sets up a regional currency with conversion rates of 1:1. You can change conversion rates and ``admin`` debt limit through the Web interface of the bank as the ``admin`` user. +By default, the regional currency conversion rates are 1:1. You can change the conversion rates and the ``admin`` debt limit via the bank's web interface as the ``admin`` user. Connecting to a Fiat Bank: the EBICS setup ++++++++++++++++++++++++++++++++++++++++++ @@ -221,7 +226,7 @@ these configuration options: Web-based Configuration +++++++++++++++++++++++ -Now you have to setup conversion rates and ``admin`` debt limit through the Web interface of the bank as the ``admin`` user. +Now you have to set the conversion rates and the ``admin`` debt limit via the bank's web interface as the ``admin`` user. .. _regional-conversion-setup: -- cgit v1.2.3 From 55524cdf91753b7b3ab964873a534c1c2e699ded Mon Sep 17 00:00:00 2001 From: Javier Sepulveda Date: Fri, 16 Feb 2024 12:32:28 +0100 Subject: Additional information (subdomains + subsequent executions) --- libeufin/regional-manual.rst | 52 ++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 48 insertions(+), 4 deletions(-) diff --git a/libeufin/regional-manual.rst b/libeufin/regional-manual.rst index d2571b24..d974bb05 100644 --- a/libeufin/regional-manual.rst +++ b/libeufin/regional-manual.rst @@ -100,6 +100,30 @@ Furthermore, you should run the process on a system with one or more globally reachable IP address(es) *and* with various DNS names already pointing to these IPs. +Preparing the required subdomain names +++++++++++++++++++++++++++++++++++++ + +The GNU Taler program needs to have three subdomains pointing to your server IP address, in order to let NGINX to accommodate each component. +These are "bank", "exchange" and "backend", this said, you need to have a registered top level domain name, +where you can create type (A) entries, as subdomains pointing to your own server public IP address. +A very good advice when creating these subdomains, and if your domain panel lets you specify the TTL (time to live) figure, is +to specify a very low value (such as 300), so in case of future changes, its value (the IP address), will be propagated quickly. + +Once you have added the three required subdomains in your domain control panel, you have to make sure as well, these subdomains have +propogated over the Internet correctly, and they are currently publicly available. + +You can check this from your terminal very easyly with the "dig" command, as this: + +.. code-block:: console + +dig -t txt bank.domainname.ltd +dig -t txt exchange.domainname.ltd +dig -t txt backend.domainname.ltd + +You can also use `this tool `_ for the same purpose, and to check the propagation status. + +Now you are ready to go with the next step. + Obtaining the Scripts +++++++++++++++++++++ @@ -130,9 +154,9 @@ desired setup, in particular: * The DNS domain name of your setup (i.e: domain.tld). The installer will create by itself all the needed subdomains for your domain name, as (``bank.$DOMAIN``, ``exchange.$DOMAIN`` and ``backend.$DOMAIN``). - But, these subdomain names, must have been added beforehand to your + But, these subdomain names as explained before, must have been added beforehand to your DNS domain control panel, and they must be pointing to the - IP address of the system on which you are running the + IP address of the server on which you are running the installation (before you execute the installer). * Whether to use TLS or not. You should answer ``y`` in most cases. * Whether to run taler-exchange-offline. Unless you need a high-security @@ -145,8 +169,8 @@ desired setup, in particular: very long and high-entropy password, preferably use the autogenerated one. The information you entered as well as the generated bank admin password will -be stored in a file called ``config/user.conf``. Should you run the script in -the future (for example, to upgrade the installation), you will not be asked +be stored in a file called ``config/user.conf``. If you run the script in +the future again (for example, to upgrade the installation), you will not be asked these questions a second time. After answering all of the questions, the actual installation will start. The @@ -158,6 +182,26 @@ Grab a coffee. At this point, the setup is NOT connected to any fiat bank account! The next steps must always be done manually! +Running the script again from scratch ++++++++++++++++++++++++++++++++++++++ + +If for some reason your installation doesn't work because you have answered erroneously +some of the interactive questions, or you just want to reset the current installation and to re-deploy +the script again for having its latest changes, you will have to proceed as follows: + +In brief you need to wipe completely the "content" of the file config/user.conf, this doesn't mean +to remove the file itself, but only its content. Eventhough you can do this manually by editing the file manually +with you preferred text editor, you can also do this in one single command. + +.. code-block:: console + +cat /dev/null > config/user.conf + +.. note:: + +In future versions of the program when executed for the second time, the program itself will +show an option to offer to wipe the content of this user.conf file, automatically. + Multi-factor authentification +++++++++++++++++++++++++++++ -- cgit v1.2.3 From 257ec471e15d8af1e6a3cb8e386c9dd328a5cf53 Mon Sep 17 00:00:00 2001 From: Javier Sepulveda Date: Fri, 16 Feb 2024 12:53:27 +0100 Subject: Fix rst typo spaces for code and notes, sections --- libeufin/regional-manual.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/libeufin/regional-manual.rst b/libeufin/regional-manual.rst index d974bb05..4b19fd3f 100644 --- a/libeufin/regional-manual.rst +++ b/libeufin/regional-manual.rst @@ -116,9 +116,9 @@ You can check this from your terminal very easyly with the "dig" command, as thi .. code-block:: console -dig -t txt bank.domainname.ltd -dig -t txt exchange.domainname.ltd -dig -t txt backend.domainname.ltd + $ dig -t txt bank.domainname.ltd + $ dig -t txt exchange.domainname.ltd + $ dig -t txt backend.domainname.ltd You can also use `this tool `_ for the same purpose, and to check the propagation status. @@ -179,8 +179,8 @@ Grab a coffee. .. note:: - At this point, the setup is NOT connected to any fiat bank account! The next - steps must always be done manually! + At this point, the setup is NOT connected to any fiat bank account! The next + steps must always be done manually! Running the script again from scratch +++++++++++++++++++++++++++++++++++++ @@ -195,12 +195,12 @@ with you preferred text editor, you can also do this in one single command. .. code-block:: console -cat /dev/null > config/user.conf + $ cat /dev/null > config/user.conf .. note:: -In future versions of the program when executed for the second time, the program itself will -show an option to offer to wipe the content of this user.conf file, automatically. + In future versions of the program when executed for the second time, the program itself will + show an option to offer to wipe the content of this user.conf file, automatically. Multi-factor authentification +++++++++++++++++++++++++++++ -- cgit v1.2.3 From ef4e6b0f9b38ba7b986939f1776c2f36f9d22655 Mon Sep 17 00:00:00 2001 From: Javier Sepulveda Date: Fri, 16 Feb 2024 12:57:54 +0100 Subject: Fix minor text typos --- libeufin/regional-manual.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/libeufin/regional-manual.rst b/libeufin/regional-manual.rst index 4b19fd3f..b47adee9 100644 --- a/libeufin/regional-manual.rst +++ b/libeufin/regional-manual.rst @@ -112,7 +112,7 @@ to specify a very low value (such as 300), so in case of future changes, its val Once you have added the three required subdomains in your domain control panel, you have to make sure as well, these subdomains have propogated over the Internet correctly, and they are currently publicly available. -You can check this from your terminal very easyly with the "dig" command, as this: +You can check this from your terminal very easily with the "dig" command, as this: .. code-block:: console @@ -200,7 +200,7 @@ with you preferred text editor, you can also do this in one single command. .. note:: In future versions of the program when executed for the second time, the program itself will - show an option to offer to wipe the content of this user.conf file, automatically. + show an option to offer wiping the content of this config/user.conf file, automatically. Multi-factor authentification +++++++++++++++++++++++++++++ -- cgit v1.2.3 From 93766130afa3586d1d47b4e68e3e857b7423d98e Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Sat, 17 Feb 2024 17:58:51 +0100 Subject: spec debug mode --- manpages/taler.conf.5.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/manpages/taler.conf.5.rst b/manpages/taler.conf.5.rst index 84606774..3748b673 100644 --- a/manpages/taler.conf.5.rst +++ b/manpages/taler.conf.5.rst @@ -293,6 +293,12 @@ KYC_OAUTH2_POST_URL KYC_OAUTH2_CONVERTER_HELPER Helper to convert JSON with KYC data returned by the OAuth2.0 info endpoint into GNU Taler internal format. Specific to the OAuth 2.0 provider. +KYC_OAUTH2_DEBUG_MODE + Set to YES to allow error responses to include potentially + sensitive private information (such as full responses + from the OAuth 2.0 server) that might aid in debugging + problems. Should be set to "NO" in production. + EXCHANGE KYC KYCAID OPTIONS ^^^^^^^^^^^^^^^^^^^^^^^^^^^ -- cgit v1.2.3 From af8b4c12951039315e0b6c3a0d20c5d400612d00 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Sat, 17 Feb 2024 18:27:01 +0100 Subject: document challenger forms --- taler-challenger-manual.rst | 152 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 152 insertions(+) diff --git a/taler-challenger-manual.rst b/taler-challenger-manual.rst index e4a59ee6..c45dcb1d 100644 --- a/taler-challenger-manual.rst +++ b/taler-challenger-manual.rst @@ -519,3 +519,155 @@ The Challenger database can be re-initialized using: However, running this command will result in all data in the database being lost. + + +.. _ChallengerCustomization: + +Template Customization +====================== + +The Challenger service comes with various HTML templates that are shown to +guide users through the process. Challenger uses `Mustach +`__ as the templating engine. This section +describes the various templates. In general, the templates must be installed +to the ``share/challenger/templates/`` directory. The file names must be of +the form ``$NAME.$LANG.must`` where ``$NAME`` is the name of the template and +``$LANG`` is the 2-letter language code of the template. English templates +must exist and will be used as a fallback. If the browser (user-agent) has +provided language preferences in the HTTP header and the respective language +exists, the correct language will be automatically served. + +The following subsections give details about each of the templates. The +subsection title is the ``$NAME`` of the respective template. + +enter-$ADDRESS_TYPE-form +------------------------ + +These templates are used to ask the user to enter the address that challenger +is expected to validate. Here, ``$ADDRESS_TYPE`` will be replaced by the +``ADDRESS_TYPE`` configuration option in the ``[challenger]`` section of the +configuration file. Typical values include ``address`` (for physical mailing +addresses), ``phone`` (for mobile phone numbers) and ``email`` (for email +addresses). For testing, ``file`` (where the TAN code is written into a local +file) is also supported. + +The template is instantiated using the following information: + + * fix_address: boolean; indicates if the given address cannot be changed + anymore, the form should be read-only if set to true. + + * nonce: String; unique value identifying the challenge, should be shown + to the user so that they can recognize it when they receive the TAN code + + * last_address: Object; form values from the previous submission if available, + details depend on the ``ADDRESS_TYPE``, should be used to pre-populate the form + + * changes_left: Integer; number of times the address can still be changed, + may or may not be shown to the user + +enter-tan-form +-------------- + +This page should generate the HTML form for the user to enter the TAN code +that they received at the respective address. + +The template is instantiated using the following information: + + * nonce: String; unique value identifying the challenge, should be shown + to the user so that they can match it to the TAN code they received + + * attempts_left: Integer; how many more attempts are allowed, might be + shown to the user, highlighting might be appropriate for low values + such as 1 or 2 (the form will never be used if the value is zero) + + * address: Object; the address that is being validated, might be shown + or not + + * transmitted: boolean; true if we just retransmitted the challenge, + false if we sent a challenge recently and thus refused to transmit it + again this time; might make a useful hint to the user + + * next_tx_time: String; timestamp explaining when we would re-transmit + the challenge the next time (at the earliest) if requested by the user + + +invalid-pin +----------- + +The user has provided an invalid TAN code (HTTP 403 Forbidden). + +The 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 + + * hint: String; human-readable Taler error code, should be shown for the + user to understand the error + + * addresses_left: Integer; how many times is the user still allowed to + change the address; if 0, the user should not be shown a link to jump + to the address entry form + + * pin_transmissions_left: Integer; how many times might the PIN still + be retransmitted + + * auth_attempts_left: Integer; how many times might the user still try + entering the PIN code + +If both *pin_transmissions_left* and *auth_attempts_left* are zero, the link +to re-enter the PIN should be hidden and the user should only be allowed to +specify a different address. The form will never be generated if all three +values are zero. (Thus there is always at least one valid choice when the form +is shown.) + + +validation-unknown +------------------ + +The user has tried to access a validation process that is not known to the +backend (HTTP 404 Not Found). + +The 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 + + * hint: String; human-readable Taler error code, should be shown for the + user to understand the error + + * detail: String; optional, extended human-readable text provided to elaborate + on the error, should be shown to provide additional context + + +invalid-request +--------------- + +The request of the client is invalid (HTTP 400 Bad Request). + +The 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 + + * hint: String; human-readable Taler error code, should be shown for the + user to understand the error + + * detail: String; optional, extended human-readable text provided to elaborate + on the error, should be shown to provide additional context + + +internal-error +-------------- + +The service experienced an internal error (HTTP 500 Internal Server Error). + +The 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 + + * hint: String; human-readable Taler error code, should be shown for the + user to understand the error + + * detail: String; optional, extended human-readable text provided to elaborate + on the error, should be shown to provide additional context -- cgit v1.2.3 From b061229e5610b01faf1ccd48b9a0aa1d596f85ba Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Sat, 17 Feb 2024 19:11:51 +0100 Subject: document KYC templates: --- libeufin/regional-manual.rst | 30 ++-- taler-exchange-manual.rst | 317 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 332 insertions(+), 15 deletions(-) diff --git a/libeufin/regional-manual.rst b/libeufin/regional-manual.rst index b47adee9..e3389a2d 100644 --- a/libeufin/regional-manual.rst +++ b/libeufin/regional-manual.rst @@ -101,28 +101,28 @@ reachable IP address(es) *and* with various DNS names already pointing to these IPs. Preparing the required subdomain names -++++++++++++++++++++++++++++++++++++ +++++++++++++++++++++++++++++++++++++++ -The GNU Taler program needs to have three subdomains pointing to your server IP address, in order to let NGINX to accommodate each component. -These are "bank", "exchange" and "backend", this said, you need to have a registered top level domain name, -where you can create type (A) entries, as subdomains pointing to your own server public IP address. +The GNU Taler program needs to have three subdomains pointing to your server IP address, in order to let NGINX to accommodate each component. +These are "bank", "exchange" and "backend", this said, you need to have a registered top level domain name, +where you can create type (A) entries, as subdomains pointing to your own server public IP address. A very good advice when creating these subdomains, and if your domain panel lets you specify the TTL (time to live) figure, is -to specify a very low value (such as 300), so in case of future changes, its value (the IP address), will be propagated quickly. +to specify a very low value (such as 300), so in case of future changes, its value (the IP address), will be propagated quickly. Once you have added the three required subdomains in your domain control panel, you have to make sure as well, these subdomains have -propogated over the Internet correctly, and they are currently publicly available. +propogated over the Internet correctly, and they are currently publicly available. You can check this from your terminal very easily with the "dig" command, as this: .. code-block:: console - $ dig -t txt bank.domainname.ltd + $ dig -t txt bank.domainname.ltd $ dig -t txt exchange.domainname.ltd $ dig -t txt backend.domainname.ltd -You can also use `this tool `_ for the same purpose, and to check the propagation status. +You can also use `this tool `_ for the same purpose, and to check the propagation status. -Now you are ready to go with the next step. +Now you are ready to go with the next step. Obtaining the Scripts +++++++++++++++++++++ @@ -185,13 +185,13 @@ Grab a coffee. Running the script again from scratch +++++++++++++++++++++++++++++++++++++ -If for some reason your installation doesn't work because you have answered erroneously +If for some reason your installation doesn't work because you have answered erroneously some of the interactive questions, or you just want to reset the current installation and to re-deploy -the script again for having its latest changes, you will have to proceed as follows: +the script again for having its latest changes, you will have to proceed as follows: In brief you need to wipe completely the "content" of the file config/user.conf, this doesn't mean to remove the file itself, but only its content. Eventhough you can do this manually by editing the file manually -with you preferred text editor, you can also do this in one single command. +with you preferred text editor, you can also do this in one single command. .. code-block:: console @@ -199,8 +199,8 @@ with you preferred text editor, you can also do this in one single command. .. note:: - In future versions of the program when executed for the second time, the program itself will - show an option to offer wiping the content of this config/user.conf file, automatically. + In future versions of the program when executed for the second time, the program itself will + show an option to offer wiping the content of this config/user.conf file, automatically. Multi-factor authentification +++++++++++++++++++++++++++++ @@ -236,7 +236,7 @@ Manual Setup This section describes how to setup a regional currency manually. -You first need to setup the :ref:`libeufin-bank` and integrate it with a Taler exchange. +You first need to setup the :ref:`libeufin-bank` and integrate it with a Taler exchange. If you don't want your regional currency to be backed by a fiat currency, you can stop here. diff --git a/taler-exchange-manual.rst b/taler-exchange-manual.rst index 9cdd51d1..088f71d2 100644 --- a/taler-exchange-manual.rst +++ b/taler-exchange-manual.rst @@ -1936,6 +1936,323 @@ grant the permissions to the other exchange processes again. +.. _ExchangeTemplateCustomization: + +Template Customization +====================== + +The Exchange comes with various HTML templates that are shown to +guide users through the KYC process. The Exchange uses `Mustach +`__ as the templating engine. This section +describes the various templates. In general, the templates must be installed +to the ``share/taler/exchange/templates/`` directory. The file names must be of +the form ``$NAME.$LANG.must`` where ``$NAME`` is the name of the template and +``$LANG`` is the 2-letter language code of the template. English templates +must exist and will be used as a fallback. If the browser (user-agent) has +provided language preferences in the HTTP header and the respective language +exists, the correct language will be automatically served. + +The following subsections give details about each of the templates. Most +subsection title are the ``$NAME`` of the respective template. + + +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) + +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 + + * 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 + + +kycaid-invalid-request +---------------------- + +The KYCaid plugin does not support requests to the +``/kyc-proof/`` endpoint (HTTP 400 bad request). + +This templates is instantiated using the following information: + + * 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 + + * error: String; error code 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 + + + +oauth2-authentication-failure +----------------------------- + +The OAuth2 server said that the request was not +properly authenticated (HTTP 403 Forbidden). + + +This templates is instantiated using the following information: + + * 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 + + +oauth2-authorization-failure +---------------------------- + +The OAuth2 server refused to return the KYC data +because the authorization code provided was +invalid (HTTP 403 Forbidden). + +This templates is instantiated using the following information: + + * 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 + + * error: String; error code from the server + + * error_message: String; error message from the server + + +oauth2-authorization-failure-malformed +-------------------------------------- + +The server refused the authorization, but then provided +a malformed response (HTTP 502 Bad Gateway). + +This templates is instantiated using the following information: + + * 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 + + * debug: Bool; 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 use if "debug" is true + + +oauth2-bad-request +------------------ + +The client made an invalid request (HTTP 400 Bad Request). + +This templates is instantiated using the following information: + + * 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 + + * message: String; additional error message elaborating on what was bad about the request + + +oauth2-conversion-failure +------------------------- + +Converting the KYC data into the exchange's internal +format failed (HTTP 502 Bad Gateway). + +This templates is instantiated using the following information: + + * 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 + + * debug: Bool; 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 + + * attributes: Object; attributes returned by the conversion command, often NULL (after all, conversion failed) + + * message: error message elaborating on the conversion failure + + +oauth2-provider-failure +----------------------- + +We did not get an acceptable response from the OAuth2 +provider (HTTP 502 Bad Gateway). + +This templates is instantiated using the following information: + + * 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 + + * message: String; could be NULL; text elaborating on the details of the failure + + +persona-exchange-unauthorized +----------------------------- + +The Persona server refused our request (HTTP 403 Forbidden from Persona, returned as a HTTP 502 Bad Gateway). + +This templates is instantiated using the following information: + + * 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 + + * data: Object; data returned from Persona service, optional + + * persona_http_status: Integer; HTTP status code returned by Persona + + +persona-load-failure +-------------------- + +The Persona server refused our request (HTTP 429 Too Many Requests from Persona, returned as a HTTP 503 Service Unavailable). + +This templates is instantiated using the following information: + + * 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 + + * data: Object; data returned from Persona service, optional + + * persona_http_status: Integer; HTTP status code returned by Persona + + +persona-exchange-unpaid +----------------------- + +The Persona server refused our request (HTTP 402 Payment REquired from Persona, returned as a HTTP 503 Service Unavailable). + +This templates is instantiated using the following information: + + * 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 + + * data: Object; data returned from Persona service, optional + + * persona_http_status: Integer; HTTP status code returned by Persona + + + +persona-logic-failure +--------------------- + +The Persona server refused our request (HTTP 400, 403, 409, 422 from Persona, returned as a HTTP 502 Bad Gateway). + +This templates is instantiated using the following information: + + * 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 + + * data: Object; data returned from Persona service, optional + + * persona_http_status: Integer; HTTP status code returned by Persona + + +persona-invalid-response +------------------------ + +The Persona server refused our request in an +unexpected way; returned as a HTTP 502 Bad Gateway. + +This templates is instantiated using the following information: + + * 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 + + * debug: Bool; 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 use if "debug" is true + + +persona-network-timeout +----------------------- + +The Persona server refused our request (HTTP 408 from Persona, returned as a HTTP 504 Gateway Timeout). + +This templates is instantiated using the following information: + + * 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 + + * data: Object; data returned from Persona service, optional + + * persona_http_status: Integer; HTTP status code returned by Persona + + +persona-kyc-failed +------------------ + +The Persona server indicated a problem with the KYC process, saying it was not completed. + +This templates is instantiated using the following information: + + * 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``. + + * persona_http_status: Integer; HTTP status code returned by Persona + +persona-provider-failure +------------------------ + +The Persona server refused our request (HTTP 500 from Persona, returned as a HTTP 502 Bad Gateway). + +This templates is instantiated using the following information: + + * 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 + + * data: Object; data returned from Persona service, optional + + * persona_http_status: Integer; HTTP status code returned by Persona + + .. _ExchangeBenchmarking: Benchmarking -- cgit v1.2.3 From 3ec3cb94f02af7f44ef87a980965a1f1ea3b8496 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Sat, 17 Feb 2024 19:32:46 +0100 Subject: document merchant MUST templates --- taler-exchange-manual.rst | 32 +++++++++---------- taler-merchant-manual.rst | 78 ++++++++++++++++++++++++++++++++++++++++++++--- 2 files changed, 89 insertions(+), 21 deletions(-) diff --git a/taler-exchange-manual.rst b/taler-exchange-manual.rst index 088f71d2..ecb88807 100644 --- a/taler-exchange-manual.rst +++ b/taler-exchange-manual.rst @@ -1953,7 +1953,7 @@ provided language preferences in the HTTP header and the respective language exists, the correct language will be automatically served. The following subsections give details about each of the templates. Most -subsection title are the ``$NAME`` of the respective template. +subsection titles are the ``$NAME`` of the respective template. Generic Errors Templates @@ -1985,7 +1985,7 @@ kycaid-invalid-request The KYCaid plugin does not support requests to the ``/kyc-proof/`` endpoint (HTTP 400 bad request). -This templates is instantiated using the following information: +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 @@ -2008,7 +2008,7 @@ The OAuth2 server said that the request was not properly authenticated (HTTP 403 Forbidden). -This templates is instantiated using the following information: +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 @@ -2024,7 +2024,7 @@ The OAuth2 server refused to return the KYC data because the authorization code provided was invalid (HTTP 403 Forbidden). -This templates is instantiated using the following information: +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 @@ -2043,7 +2043,7 @@ oauth2-authorization-failure-malformed The server refused the authorization, but then provided a malformed response (HTTP 502 Bad Gateway). -This templates is instantiated using the following information: +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 @@ -2061,7 +2061,7 @@ oauth2-bad-request The client made an invalid request (HTTP 400 Bad Request). -This templates is instantiated using the following information: +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 @@ -2078,7 +2078,7 @@ oauth2-conversion-failure Converting the KYC data into the exchange's internal format failed (HTTP 502 Bad Gateway). -This templates is instantiated using the following information: +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 @@ -2101,7 +2101,7 @@ oauth2-provider-failure We did not get an acceptable response from the OAuth2 provider (HTTP 502 Bad Gateway). -This templates is instantiated using the following information: +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 @@ -2117,7 +2117,7 @@ persona-exchange-unauthorized The Persona server refused our request (HTTP 403 Forbidden from Persona, returned as a HTTP 502 Bad Gateway). -This templates is instantiated using the following information: +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 @@ -2135,7 +2135,7 @@ persona-load-failure The Persona server refused our request (HTTP 429 Too Many Requests from Persona, returned as a HTTP 503 Service Unavailable). -This templates is instantiated using the following information: +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 @@ -2153,7 +2153,7 @@ persona-exchange-unpaid The Persona server refused our request (HTTP 402 Payment REquired from Persona, returned as a HTTP 503 Service Unavailable). -This templates is instantiated using the following information: +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 @@ -2172,7 +2172,7 @@ persona-logic-failure The Persona server refused our request (HTTP 400, 403, 409, 422 from Persona, returned as a HTTP 502 Bad Gateway). -This templates is instantiated using the following information: +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 @@ -2191,7 +2191,7 @@ persona-invalid-response The Persona server refused our request in an unexpected way; returned as a HTTP 502 Bad Gateway. -This templates is instantiated using the following information: +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 @@ -2209,7 +2209,7 @@ persona-network-timeout The Persona server refused our request (HTTP 408 from Persona, returned as a HTTP 504 Gateway Timeout). -This templates is instantiated using the following information: +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 @@ -2227,7 +2227,7 @@ persona-kyc-failed The Persona server indicated a problem with the KYC process, saying it was not completed. -This templates is instantiated using the following information: +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 @@ -2240,7 +2240,7 @@ persona-provider-failure The Persona server refused our request (HTTP 500 from Persona, returned as a HTTP 502 Bad Gateway). -This templates is instantiated using the following information: +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 diff --git a/taler-merchant-manual.rst b/taler-merchant-manual.rst index 97a422d0..d1520d02 100644 --- a/taler-merchant-manual.rst +++ b/taler-merchant-manual.rst @@ -1114,15 +1114,83 @@ Legal conditions for using the service .. include:: frags/legal.rst +.. _MerchantTemplateCustomization: -Mustach HTML Templates +Template Customization ---------------------- -The installation process will install various HTML templates to be served -to trigger the wallet interaction. You may change those templates to your -own design. The templating language used is Mustach, and the templates -are in the ``share/taler/merchant/templates/`` directory. +The installation process will install various HTML templates to be served to +trigger the wallet interaction. You may change those templates to your own +design. The templating language used is `Mustach +`__, and the templates are in the +``share/taler/merchant/templates/`` directory. +The file names must be of the form ``$NAME.$LANG.must`` where ``$NAME`` is the +name of the template and ``$LANG`` is the 2-letter language code of the +template. English templates must exist and will be used as a fallback. If the +browser (user-agent) has provided language preferences in the HTTP header and +the respective language exists, the correct language will be automatically +served. + +The following subsections give details about each of the templates. The +subsection titles are the ``$NAME`` of the respective template. + +request_payment +^^^^^^^^^^^^^^^ + +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_qrcode_svg: Image; an SVG image of the QR code with the + ``taler_pay_uri``. + + * 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 + + +offer_refund +^^^^^^^^^^^^ + +Page shown to offer a customer a refund. + +This template is instantiated using the following information: + + * taler_refund_uri: String; the ``taler://pay/`` URI that must be given + to the wallet to initiate the payment + + * taler_refund_qrcode_svg: Image; an SVG image of the QR code with the + ``taler_pay_uri``. + + * refund_amount: Amount; how much did the merchant refund + + * refund_taken: Amount; how much did the customer already take back in refunds + + * order_summary: String; a text summarizing the order + + + +show_order_details +^^^^^^^^^^^^^^^^^^ + +Page shown to the user when they go back to the payment page but +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 + + * contract_terms: Object; the full contract terms (shoud probably + not be shown in full!) + + * refund_amount: Amount; how much did the merchant refund + + * refund_taken: Amount; how much did the customer already take back in refunds Static files ------------ -- cgit v1.2.3 From 96a2725d3899324773337afd7d73d99465c7b0e2 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Sun, 18 Feb 2024 11:26:26 +0100 Subject: return more details --- taler-challenger-manual.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/taler-challenger-manual.rst b/taler-challenger-manual.rst index c45dcb1d..3b89615e 100644 --- a/taler-challenger-manual.rst +++ b/taler-challenger-manual.rst @@ -614,6 +614,10 @@ The template is instantiated using the following information: * auth_attempts_left: Integer; how many times might the user still try entering the PIN code + * exhausted: Bool; if true, the PIN was not even evaluated as the user previously exhausted the number of attempts + + * no_challenge: Bool; if true, the PIN was not even evaluated as no challenge was ever issued (the user must have skipped the step of providing their address first!) + If both *pin_transmissions_left* and *auth_attempts_left* are zero, the link to re-enter the PIN should be hidden and the user should only be allowed to specify a different address. The form will never be generated if all three -- cgit v1.2.3 From 2254c8b5afc8ef781205dd7be0b1b6e44049b449 Mon Sep 17 00:00:00 2001 From: Antoine A <> Date: Mon, 19 Feb 2024 17:38:15 +0100 Subject: Improve 2FA documentation --- libeufin/bank-manual.rst | 45 +++++++++++++++++++++++++++++++-------- libeufin/regional-manual.rst | 8 +++---- manpages/libeufin-bank.conf.5.rst | 12 +++++++++++ 3 files changed, 52 insertions(+), 13 deletions(-) diff --git a/libeufin/bank-manual.rst b/libeufin/bank-manual.rst index 4dd74210..228cbef1 100644 --- a/libeufin/bank-manual.rst +++ b/libeufin/bank-manual.rst @@ -104,25 +104,51 @@ The following snippet shows the mandatory configuration values: Configuring multi-factor authentication --------------------------------------- -libeufin-bank supports two factor authentification. libeufin-bank uses helper scripts to send challenge codes to addresses for multi-factor authentication. By default, those helper scripts are ``libeufin-tan-email.sh`` to send e-mails and ``libeufin-tan-sms.sh`` to send SMS. To enable two factor authentication you need to configure at least one TAN channel: +libeufin-bank supports two-factor authentication. libeufin-bank uses helper scripts to send challenge codes to addresses for multi-factor authentication. We provide two default helper scripts: ``libeufin-tan-email.sh`` to send e-mails and ``libeufin-tan-sms.sh`` to send SMS. To enable two-factor authentication you need to configure at least one TAN channel. + +SMS TAN channel ++++++++++++++++ + +The default ``libeufin-tan-sms.sh`` script is based on the `Telesign `_ provider. It requires an additional ``AUTH_TOKEN`` environment variable for the `Telesign API `_. + +To test your setup run: + +.. code-block:: console + + $ 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: .. code-block:: ini [libeufin-bank] TAN_SMS = libeufin-tan-sms.sh - # And/Or - TAN_EMAIL = libeufin-tan-email.sh + TAN_SMS_ENV = "AUTH_TOKEN=$TELESIGN_TOKEN" -.. note:: +Mail TAN channel +++++++++++++++++ - The default ``libeufin-tan-sms.sh`` script is based on the `Telesign `_ provider. It requires an additional ``telesign-secrets`` script in the PATH that sets the ``CUSTOMER_ID`` and the ``API_KEY`` for the Telesign API. +The default ``libeufin-tan-email.sh`` script is based on the ``mail`` Linux command. It requires a working local mail transfer agent. -.. note:: +To test your setup run: - The default ``libeufin-tan-email.sh`` script is based on the ``mail`` linux command. It requires a working local mail transfer agent. +.. code-block:: console + + $ echo "Test 1234" | libeufin-tan-email.sh $EMAIL + +If you received an email containing "Test 1234" you can enable this channel in the config: + +.. code-block:: ini + + [libeufin-bank] + TAN_EMAIL = libeufin-tan-email.sh + +Custom TAN channel scripts +++++++++++++++++++++++++++ It is possible to replace these scripts with use custom scripts to send -the e-mail or SMS TAN. Such alternative scripts must accept the phone number / e-mail address as the ``$1`` parameter and the message content to be transmitted in their standard input. They should return 0 to indicate successful transmission of the challenge, and non-zero on failure. +the e-mail or SMS TAN. Such alternative scripts must accept the phone number / e-mail address as the ``$1`` parameter and the message content to be transmitted in their standard input. They should return 0 to indicate successful transmission of the challenge and non-zero on failure. To change the scripts used for multi-factor authentication, change the following options in the configuration file: @@ -131,8 +157,9 @@ options in the configuration file: [libeufin-bank] TAN_SMS = custom-tan-sms.sh + TAN_SMS_ENV = TAN_EMAIL = custom-tan-email.sh - + TAN_EMAIL_ENV = Launching libeufin-bank ======================= diff --git a/libeufin/regional-manual.rst b/libeufin/regional-manual.rst index e3389a2d..469be164 100644 --- a/libeufin/regional-manual.rst +++ b/libeufin/regional-manual.rst @@ -110,7 +110,7 @@ A very good advice when creating these subdomains, and if your domain panel lets to specify a very low value (such as 300), so in case of future changes, its value (the IP address), will be propagated quickly. Once you have added the three required subdomains in your domain control panel, you have to make sure as well, these subdomains have -propogated over the Internet correctly, and they are currently publicly available. +propagated over the Internet correctly, and they are currently publicly available. You can check this from your terminal very easily with the "dig" command, as this: @@ -190,7 +190,7 @@ some of the interactive questions, or you just want to reset the current install the script again for having its latest changes, you will have to proceed as follows: In brief you need to wipe completely the "content" of the file config/user.conf, this doesn't mean -to remove the file itself, but only its content. Eventhough you can do this manually by editing the file manually +to remove the file itself, but only its content. Even though you can do this manually by editing the file manually with you preferred text editor, you can also do this in one single command. .. code-block:: console @@ -202,8 +202,8 @@ with you preferred text editor, you can also do this in one single command. In future versions of the program when executed for the second time, the program itself will show an option to offer wiping the content of this config/user.conf file, automatically. -Multi-factor authentification -+++++++++++++++++++++++++++++ +Multi-factor authentication ++++++++++++++++++++++++++++ By default, multi-factor authentication via SMS and email is enabled. You have to manually configure both channels as described in :ref:`multi-factor authentication `. diff --git a/manpages/libeufin-bank.conf.5.rst b/manpages/libeufin-bank.conf.5.rst index a33d6f49..35103760 100644 --- a/manpages/libeufin-bank.conf.5.rst +++ b/manpages/libeufin-bank.conf.5.rst @@ -71,6 +71,14 @@ TAN_EMAIL Path to TAN challenge transmission script via email. If not specified, this TAN channel will not be supported. Only used if ``ALLOW_CONVERSION`` is ``YES``. +TAN_SMS_ENV + Environment variables for the sms TAN script. + Only used if ``TAN_SMS`` is set. + +TAN_EMAIL_ENV + Environment variables for the email TAN script. + Only used if ``TAN_EMAIL`` is set. + SERVE This can either be ``tcp`` or ``unix``. @@ -78,6 +86,10 @@ PORT Port on which the HTTP server listens, e.g. 9967. Only used if ``SERVE`` is ``tcp``. +BIND_TO + Which IP address should we bind to? E.g. ``127.0.0.1`` or ``::1``for loopback. Can also be given as a hostname. + Only used if ``SERVE`` is ``tcp``. + UNIXPATH Which unix domain path should we bind to? Only used if ``SERVE`` is ``unix``. -- cgit v1.2.3 From 90905b612195040e1a5118ca3c0f6b94c7647ed7 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Mon, 19 Feb 2024 22:11:03 +0100 Subject: remove dead links --- index.rst | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/index.rst b/index.rst index f562b2e8..d30542cb 100644 --- a/index.rst +++ b/index.rst @@ -41,12 +41,8 @@ The system will be based on free software and open protocols. In this document, we describe the REST-based APIs between the various components, internal architecture of key components, and how to get them -installed. In addition to this documentation, we have source-level -documentation which you can find converted to HTML at these pages: +installed. -* `Exchange `_ -* `Merchant `_ -* `Wallet-core `_ Documentation Overview ---------------------- -- cgit v1.2.3 From 738347d169e4f5fe2a57d21b439efb82b0971821 Mon Sep 17 00:00:00 2001 From: Florian Dold Date: Tue, 20 Feb 2024 15:05:56 +0100 Subject: systemctl, not systemd --- libeufin/regional-manual.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/libeufin/regional-manual.rst b/libeufin/regional-manual.rst index 469be164..adac6414 100644 --- a/libeufin/regional-manual.rst +++ b/libeufin/regional-manual.rst @@ -226,8 +226,8 @@ outgoing bank transactions ` (cash out). .. code-block:: console - # systemd enable --now libeufin-nexus-ebics-fetch - # systemd enable --now libeufin-nexus-ebics-submit + # systemctl enable --now libeufin-nexus-ebics-fetch + # systemctl enable --now libeufin-nexus-ebics-submit .. _manual-regional-currency-setup: @@ -320,8 +320,8 @@ outgoing bank transactions ` (cash out). .. code-block:: console - # systemd enable --now libeufin-nexus-ebics-fetch - # systemd enable --now libeufin-nexus-ebics-submit + # systemctl enable --now libeufin-nexus-ebics-fetch + # systemctl enable --now libeufin-nexus-ebics-submit Using the Regional Currency =========================== -- cgit v1.2.3 From 32b087689c7205875e3edf2e806b1eb6e6ccd8da Mon Sep 17 00:00:00 2001 From: Antoine A <> Date: Tue, 20 Feb 2024 15:54:28 +0100 Subject: Split regional manual in two --- frags/nexus-ebics-setup.rst | 65 ++++++ frags/regional-manual-architecture.rst | 48 ++++ frags/regional-manual-use.rst | 70 ++++++ libeufin/bank-manual.rst | 4 +- libeufin/index.rst | 3 +- libeufin/nexus-manual.rst | 66 +----- libeufin/regional-automated-manual.rst | 177 ++++++++++++++ libeufin/regional-custom-manual.rst | 123 ++++++++++ libeufin/regional-manual.rst | 407 --------------------------------- 9 files changed, 488 insertions(+), 475 deletions(-) create mode 100644 frags/nexus-ebics-setup.rst create mode 100644 frags/regional-manual-architecture.rst create mode 100644 frags/regional-manual-use.rst create mode 100644 libeufin/regional-automated-manual.rst create mode 100644 libeufin/regional-custom-manual.rst delete mode 100644 libeufin/regional-manual.rst diff --git a/frags/nexus-ebics-setup.rst b/frags/nexus-ebics-setup.rst new file mode 100644 index 00000000..21904322 --- /dev/null +++ b/frags/nexus-ebics-setup.rst @@ -0,0 +1,65 @@ + +When you sign up for an EBICS-enabled bank account, the bank will provide you +with various credentials. Those must be provided in the +``/etc/libeufin/libeufin-nexus.conf`` configuration file together with the +name of the *fiat* currency. + +.. note:: + As legacy transactions in that bank account would likely confuse the system, it is advisable to use a fresh bank account with an empty transaction history. + +The following snippet shows the mandatory configuration values: + +.. _core-config: + +.. code-block:: ini + + [nexus-ebics] + CURRENCY = CHF + + # Bank + HOST_BASE_URL = https://ebics.postfinance.ch/ebics/ebics.aspx + BANK_DIALECT = postfinance + + # EBICS IDs + HOST_ID = PFEBICS + USER_ID = PFC00563 + PARTNER_ID = PFC00563 + + # Account information + IBAN = CH7789144474425692816 + BIC = POFICHBEXXX + NAME = John Smith S.A. + +.. note:: + Refer to the manpage ``libeufin-nexus.conf(5)`` + for the full array of configuration values. + +.. warning:: + This combination of HOST_ID, USER_ID and PARTNER_ID must never be used by another instance of libeufin-nexus or by other EBICS clients, otherwise data will be lost. + +.. note:: + If you want to use existing client keys, copy the JSON file to the configured path ``CLIENT_PRIVATE_KEYS_FILE`` (``/var/lib/libeufin-nexus/client-ebics-keys.json`` with the default config) before running the following commands. + +Assuming that the configuration file exists at ``$CONFIG_FILE``, the following +command should start the EBICS setup process: + +.. code-block:: console + + $ libeufin-nexus ebics-setup -c "$CONFIG_FILE" + +If the previous command failed when running EBICS INI with an error code of +``EBICS_INVALID_USER_STATE``, you need to confirm your keys to your bank to +activate your account. + +To that end, the previous run should have left a PDF document that you can +print, sign and send to the bank. Look for the message that looks like ``PDF +file with keys created at '/tmp/libeufin-nexus-keys-$TIMESTAMP.pdf'``. + +Once the bank has received and processed this document, run the same +command again to download and verify the bank's keys: + +.. code-block:: console + + $ libeufin-nexus ebics-setup -c "$CONFIG_FILE" + +The EBICS setup is finished once the bank keys have been accepted. \ No newline at end of file diff --git a/frags/regional-manual-architecture.rst b/frags/regional-manual-architecture.rst new file mode 100644 index 00000000..cfb8aacd --- /dev/null +++ b/frags/regional-manual-architecture.rst @@ -0,0 +1,48 @@ +Architecture +============ + +There are several key components needed to operate a regional currency based +on GNU Taler and LibEuFin technology: + +- LibEuFin Nexus: is responsible to drive the master (fiat) bank account both to learn + about incoming payments and to send fiat cash-out payments +- LibEuFin Bank: offers basic banking operations, e.g. wire transfers, Taler withdrawals, + account management, cash-out's +- Taler exchange: server side of Taler operations. +- Taler wallet: client side of Taler operations. +- Taler merchant backend: abstracts Taler details to the shops. + +.. image:: ../images/regional-arch.png + +In this model, the regional currency is backed by the fiat currency and users +are offered two operations: *cash-in* to create regional currency starting +from fiat money, and *cash-out* to convert regional currency into fiat +currency. + +The design assumes that one single unit of regional currency is always backed +by one single unit of fiat currency. + + +Cash-in ++++++++ + +One fundamental entity to create the regional currency is the *master bank account*. +The master bank account is hosted at one fiat bank and whenever it receives a *valid* +fiat payment of N units, it triggers the creation of N units of regional currency. +Such trigger causes the *admin bank account* at the regional bank to wire the N units of +regional currency to the Taler exchange (regional) bank account. At this point, the +Taler exchange is ready to issue the regional coins to the Taler wallet that proves +to own them. + +.. note:: + + *Valid* fiat payments are those with a Taler-relevant subject that should be generated by a Taler wallet. + + +Cash-out +++++++++ + +Once a regional bank user confirms a cash-out operation of N units, the system sends +a regional payment of N units to the *admin bank account*. This latter triggers then +a fiat payment of N units to the fiat bank account owned by the user who initiated the +cash-out. \ No newline at end of file diff --git a/frags/regional-manual-use.rst b/frags/regional-manual-use.rst new file mode 100644 index 00000000..40106356 --- /dev/null +++ b/frags/regional-manual-use.rst @@ -0,0 +1,70 @@ +Using the Regional Currency +=========================== + +Wallet Setup +++++++++++++ + +This section describes the interaction between the Taler graphical wallet (Android, +iOS, WebExtensions) and the regional currency system. + +You need to add your regional currency exchange to the wallet. This can +be done by scanning a QR code with a ``taler://withdraw-exchange/exchange.$DOMAIN`` +URL or by manually entering the URL into the respective ``Add exchange`` +dialogue. + + +Cash-In ++++++++ + +Next, start the withdraw process in the Taler wallet for the respective +currency and specify the desired amount. The wallet will then show you the +details of the fiat wire transfer that must be made for the cash-in to be +completed. Once the money has arrived at the fiat bank account, Nexus will +obtain the transaction data and the regional currency bank will create the +corresponding amount in regional currency, crediting the GNU Taler exchange +account. In turn, the exchange will issue the respective amount to your +wallet. + +.. note:: + + Cash-in operations may be subject to conversion rates, conversion fees and + minimum amounts to be transferred. + + +Making payments ++++++++++++++++ + +For testing, you should be able to *deposit* regional currency directly into +your regional currency libeufin-bank account directly from the Taler wallet. +For this, you primarily need to know your bank account details (which should +be accessible by clicking on your name in the bank Web site after logging in). + +.. note:: + + There may be a short delay between the wallet making the deposit and + the exchange crediting your bank account. This is because the wallet + uses a small wire transfer delay by default when initiating a deposit + into a bank account. + +For production, it is more common for a shop to configure a :ref:`Taler +merchant backend ` or at least use an +instance within such a setup. To configure an instance, you primarily need +again the bank account details to :ref:`setup instance bank accounts +`. + + +Cash-Out +++++++++ + +Regional currency accounts that have a positive balance could be eligible for +cash-out. Cash-out operations may again be restricted by the regional +currency operator and will *only* be made to the respective pre-configured +fiat currency bank account. To cash-out, simply log into your regional +currency account, select cash-out, specify the desired amount and pass the +second-factor authorization challenge by entering the TAN you receive at the +registered e-mail address or mobile phone number. + +.. note:: + + Cash-out operations may be subject to conversion rates, conversion fees and + minimum amounts to be transferred. diff --git a/libeufin/bank-manual.rst b/libeufin/bank-manual.rst index 228cbef1..4b00635a 100644 --- a/libeufin/bank-manual.rst +++ b/libeufin/bank-manual.rst @@ -258,7 +258,7 @@ Integration with the Taler Exchange .. note:: - This step is fully automated if you use the :ref:`guided automated setup `. + This step is fully automated if you use the :doc:`automated setup manual`. You must have an exchange account with username ``exchange`` for conversion to work. Assuming that the configuration file exists at ``$CONFIG_FILE``, the following @@ -284,7 +284,7 @@ Withdrawing e-cash to a Taler wallet .. note:: - This step is fully automated if you use the :ref:`guided automated setup `. + This step is fully automated if you use the :doc:`automated setup manual`. Users can withdraw digital cash from their bank account starting from their online banking as implemented by the libeufin-bank. However, in this scenario, diff --git a/libeufin/index.rst b/libeufin/index.rst index 5e4ca054..c77255b0 100644 --- a/libeufin/index.rst +++ b/libeufin/index.rst @@ -29,5 +29,6 @@ LibEuFin is a project providing free software tooling for European FinTech. nexus-manual bank-manual - regional-manual + regional-automated-manual + regional-custom-manual setup-ebics-at-postfinance diff --git a/libeufin/nexus-manual.rst b/libeufin/nexus-manual.rst index 7ac59467..de2f4bae 100644 --- a/libeufin/nexus-manual.rst +++ b/libeufin/nexus-manual.rst @@ -90,71 +90,7 @@ be found in the $PATH. Setting up the EBICS subscriber =============================== -When you sign up for an EBICS-enabled bank account, the bank will provide you -with various credentials. Those must be provided in the -``/etc/libeufin/libeufin-nexus.conf`` configuration file together with the -name of the *fiat* currency. - -.. note:: - As legacy transactions in that bank account would likely confuse the system, it is advisable to use a fresh bank account with an empty transaction history. - -The following snippet shows the mandatory configuration values: - -.. _core-config: - -.. code-block:: ini - - [nexus-ebics] - CURRENCY = CHF - - # Bank - HOST_BASE_URL = https://ebics.postfinance.ch/ebics/ebics.aspx - BANK_DIALECT = postfinance - - # EBICS IDs - HOST_ID = PFEBICS - USER_ID = PFC00563 - PARTNER_ID = PFC00563 - - # Account information - IBAN = CH7789144474425692816 - BIC = POFICHBEXXX - NAME = John Smith S.A. - -.. note:: - Refer to the manpage ``libeufin-nexus.conf(5)`` - for the full array of configuration values. - -.. warning:: - This combination of HOST_ID, USER_ID and PARTNER_ID must never be used by another instance of libeufin-nexus or by other EBICS clients, otherwise data will be lost. - -.. note:: - If you want to use existing client keys, copy the JSON file to the configured path ``CLIENT_PRIVATE_KEYS_FILE`` (``/var/lib/libeufin-nexus/client-ebics-keys.json`` with the default config) before running the following commands. - -Assuming that the configuration file exists at ``$CONFIG_FILE``, the following -command should start the EBICS setup process: - -.. code-block:: console - - $ libeufin-nexus ebics-setup -c "$CONFIG_FILE" - -If the previous command failed when running EBICS INI with an error code of -``EBICS_INVALID_USER_STATE``, you need to confirm your keys to your bank to -activate your account. - -To that end, the previous run should have left a PDF document that you can -print, sign and send to the bank. Look for the message that looks like ``PDF -file with keys created at '/tmp/libeufin-nexus-keys-$TIMESTAMP.pdf'``. - -Once the bank has received and processed this document, run the same -command again to download and verify the bank's keys: - -.. code-block:: console - - $ libeufin-nexus ebics-setup -c "$CONFIG_FILE" - -The EBICS setup is finished once the bank keys have been accepted. - +.. include:: ../frags/nexus-ebics-setup.rst Database setup ============== diff --git a/libeufin/regional-automated-manual.rst b/libeufin/regional-automated-manual.rst new file mode 100644 index 00000000..aea5ca88 --- /dev/null +++ b/libeufin/regional-automated-manual.rst @@ -0,0 +1,177 @@ +.. + This file is part of GNU TALER. + Copyright (C) 2014-2024 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 + + @author Florian Dold + @author Marcello Stanisci + @author Christian Grothoff + + +.. target audience: operator + +Regional Currency Automated Setup Manual +######################################## + +This manual describes how to setup a regional currency backed by a fiat currency using a script that largely automates the process. If you want to do a custom setup you can follow the :doc:`custom setup manual`. + + +.. contents:: Table of Contents + :local: + +.. include:: ../frags/regional-manual-architecture.rst + +Guided Automated Setup +====================== + +Prerequisites ++++++++++++++ + +For this manual, we assume that the system is deployed on a contemporary +Debian GNU/Linux or Ubuntu LTS system using the binary packages provided. +Furthermore, you should run the process on a system with one or more globally +reachable IP address(es) *and* with various DNS names already pointing to +these IPs. + +Preparing the required subdomain names +++++++++++++++++++++++++++++++++++++++ + +The GNU Taler program needs to have three subdomains pointing to your server IP address, in order to let NGINX to accommodate each component. +These are "bank", "exchange" and "backend", this said, you need to have a registered top level domain name, +where you can create type (A) entries, as subdomains pointing to your own server public IP address. +A very good advice when creating these subdomains, and if your domain panel lets you specify the TTL (time to live) figure, is +to specify a very low value (such as 300), so in case of future changes, its value (the IP address), will be propagated quickly. + +Once you have added the three required subdomains in your domain control panel, you have to make sure as well, these subdomains have +propagated over the Internet correctly, and they are currently publicly available. + +You can check this from your terminal very easily with the "ping" command, as this: + +.. code-block:: console + + $ ping -c1 bank.domainname.ltd + $ ping -c1 exchange.domainname.ltd + $ ping -c1 backend.domainname.ltd + +You can also use `this tool `_ for the same purpose, and to check the propagation status. + +Now you are ready to go with the next step. + +Obtaining the Scripts ++++++++++++++++++++++ + +First, download the deployment scripts via Git: + +.. code-block:: console + + # apt update && apt install git + $ git clone git://git.taler.net/deployment + +Running the Guided Configuration +++++++++++++++++++++++++++++++++ + +Navigate into the *regional-currency/* directory and run *main.sh* as **root**: + +.. code-block:: console + + $ cd deployment/regional-currency/ + # ./main.sh + +The script will start by asking you fundamental questions about the +desired setup, in particular: + +* The name of the regional currency. It must have 3 to 11 letters. +* The ISO code of the fiat currency. Use 'CHF' or 'EUR'. +* The name of the regional currency bank. It will be shown to business + users when they interact with the system. +* The DNS domain name of your setup (i.e: domain.tld). The installer will + create by itself all the needed subdomains for your domain name, + as (``bank.$DOMAIN``, ``exchange.$DOMAIN`` and ``backend.$DOMAIN``). + But, these subdomain names as explained before, must have been added beforehand to your + DNS domain control panel, and they must be pointing to the + IP address of the server on which you are running the + installation (before you execute the installer). +* Whether to use TLS or not. You should answer ``y`` in most cases. +* Whether to run taler-exchange-offline. Unless you need a high-security + setup and expect to run an offline key management process, say ``y``. + If you say ``n``, you will need to run ``taler-exchange-offline setup`` + on your offline system and provide the master public key. Furthermore, + you should then study the exchange manual on offline key management to + finish the exchange setup process later. +* The admin password for the bank. Be absolutely sure to enter a very, + very long and high-entropy password, preferably use the autogenerated one. + +The information you entered as well as the generated bank admin password will +be stored in a file called ``config/user.conf``. If you run the script in +the future again (for example, to upgrade the installation), you will not be asked +these questions a second time. + +After answering all of the questions, the actual installation will start. The +scripts will download and configure various packages, which may take some time. +Grab a coffee. + +.. note:: + + At this point, the setup is NOT connected to any fiat bank account! The next + steps must always be done manually! + +Running the script again from scratch ++++++++++++++++++++++++++++++++++++++ + +If for some reason your installation doesn't work because you have answered erroneously +some of the interactive questions, or you just want to reset the current installation and to re-deploy +the script again for having its latest changes, you will have to proceed as follows: + +In brief you need to wipe completely the "content" of the file config/user.conf, this doesn't mean +to remove the file itself, but only its content. Even though you can do this manually by editing the file manually +with you preferred text editor, you can also do this in one single command. + +.. code-block:: console + + $ cat /dev/null > config/user.conf + +.. note:: + + In future versions of the program when executed for the second time, the program itself will + show an option to offer wiping the content of this config/user.conf file, automatically. + +Multi-factor authentication ++++++++++++++++++++++++++++ + +By default, multi-factor authentication via SMS and email is enabled. You have to manually configure both channels as described in :ref:`multi-factor authentication `. + +Web-based Configuration ++++++++++++++++++++++++ + +By default, the regional currency conversion rates are 1:1. You can change the conversion rates and the ``admin`` debt limit via the bank's web interface as the ``admin`` user. + +Connecting to a Fiat Bank: the EBICS setup +++++++++++++++++++++++++++++++++++++++++++ + +To complete the conversion setup, you have to set up an EBICS subscriber using a bank account at a bank dealing in fiat currency that offers an online banking protocol supported by LibEuFin Nexus. + +.. include:: ../frags/nexus-ebics-setup.rst + +System ON! +++++++++++ + +The last step is to enable libeufin-nexus to :ref:`import incoming bank +transactions ` (cash in) and to :ref:`trigger +outgoing bank transactions ` (cash out). + +.. code-block:: console + + # systemctl enable --now libeufin-nexus-ebics-fetch + # systemctl enable --now libeufin-nexus-ebics-submit + +.. include:: ../frags/regional-manual-use.rst \ No newline at end of file diff --git a/libeufin/regional-custom-manual.rst b/libeufin/regional-custom-manual.rst new file mode 100644 index 00000000..5674420e --- /dev/null +++ b/libeufin/regional-custom-manual.rst @@ -0,0 +1,123 @@ +.. + This file is part of GNU TALER. + Copyright (C) 2014-2024 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 + + @author Florian Dold + @author Marcello Stanisci + @author Christian Grothoff + + +.. target audience: operator + +Regional Currency Custom Setup Manual +##################################### + +This manual describes how to setup a regional currency manually. If you want a guided setup you can follow the :doc:`automated setup manual`. + +.. contents:: Table of Contents + :local: + +.. include:: ../frags/regional-manual-architecture.rst + +Custom Manual Setup +=================== + +You first need to setup the :ref:`libeufin-bank` and integrate it with a Taler exchange. + +If you don't want your regional currency to be backed by a fiat currency, you can stop here. + +Enabling Currency Conversion +++++++++++++++++++++++++++++ + +You need to setup the :ref:`libeufin-nexus` using a bank account at a bank dealing in fiat currency that +offers an online banking protocol supported by LibEuFin Nexus. + +Next, you have to enable conversion and should ensure that at least one TAN +channel for :ref:`multi-factor authentication ` is configured: + +.. code-block:: ini + + [libeufin-bank] + ALLOW_CONVERSION = YES + FIAT_CURRENCY = EUR + + TAN_SMS = libeufin-tan-sms.sh + # And/Or + TAN_EMAIL = libeufin-tan-email.sh + +Make sure to (re)start the libeufin-bank after changing +these configuration options: + +.. code-block:: console + + # systemctl restart libeufin-bank + + +Web-based Configuration ++++++++++++++++++++++++ + +Now you have to set the conversion rates and the ``admin`` debt limit via the bank's web interface as the ``admin`` user. + +.. _regional-conversion-setup: + +Configuring the Exchange for Conversion ++++++++++++++++++++++++++++++++++++++++ + +This section explains how to enable currency conversion at the exchange, +which is critical for wallets to know how to wire fiat currency to an +exchange to obtain regional currency. + +You will need to use the ``taler-exchange-offline`` tool to inform the +exchange about the **fiat** bank account that can be used for cash in +operations and also specify the URL for currency conversion. Additionally, +you may also configure restrictions on the bank accounts that may originate +the funds, for example, to prevent international wire transfers that may expose +you to additional compliance risks. + +Given the ``$IBAN`` of the fiat currency bank account and ``$NAME`` as +the (URL-encoded) name of the exchange-account owner, the following +``taler-exchange-offline`` invocation can be used to notify wallets about +the possibility of currency conversion (cash in): + +.. code-block:: console + + # taler-exchange-offline \ + enable-account \ + payto://iban/$IBAN?receiver-name=$NAME \ + conversion-url "$CONVERSION_URL" \ + upload + +Here, the ``$CONVERSION_URL`` must be set to the base URL of the conversion +endpoint of the bank, which should be ``https://bank.$DOMAIN/conversion-info/`` +in our setup. + +.. note:: + + The above command adds a **second** bank account to the exchange. + You (or the guided setup script) should have already enabled the + regional currency bank account (without any "conversion-url"). + +System ON! +++++++++++ + +The last step is to enable libeufin-nexus to :ref:`import incoming bank +transactions ` (cash in) and to :ref:`trigger +outgoing bank transactions ` (cash out). + +.. code-block:: console + + # systemctl enable --now libeufin-nexus-ebics-fetch + # systemctl enable --now libeufin-nexus-ebics-submit + +.. include:: ../frags/regional-manual-use.rst \ No newline at end of file diff --git a/libeufin/regional-manual.rst b/libeufin/regional-manual.rst deleted file mode 100644 index adac6414..00000000 --- a/libeufin/regional-manual.rst +++ /dev/null @@ -1,407 +0,0 @@ -.. - This file is part of GNU TALER. - Copyright (C) 2014-2024 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 - - @author Florian Dold - @author Marcello Stanisci - @author Christian Grothoff - - -.. target audience: operator - -Regional Currency Setup Manual -############################## - -This manual explains how to set up a regional currency that may be backed by a fiat currency. Most of the manual is concerned with setting up the currency conversion logic with a fiat bank that offers an EBICS interface. - -To understand how the regional currency works and how it is backed by a fiat currency, you can read about its :ref:`architecture`. - -If you want to setup a regional currency backed by a fiat currency, you can use the :ref:`guided automated setup`, which largely automates the process. You can also follow the :ref:`manual setup` if you want a customized one. - -.. contents:: Table of Contents - :local: - -.. _regional-currency-setup-architecture: - -Architecture -============ - -There are several key components needed to operate a regional currency based -on GNU Taler and LibEuFin technology: - -- LibEuFin Nexus: is responsible to drive the master (fiat) bank account both to learn - about incoming payments and to send fiat cash-out payments -- LibEuFin Bank: offers basic banking operations, e.g. wire transfers, Taler withdrawals, - account management, cash-out's -- Taler exchange: server side of Taler operations. -- Taler wallet: client side of Taler operations. -- Taler merchant backend: abstracts Taler details to the shops. - -.. image:: ../images/regional-arch.png - -In this model, the regional currency is backed by the fiat currency and users -are offered two operations: *cash-in* to create regional currency starting -from fiat money, and *cash-out* to convert regional currency into fiat -currency. - -The design assumes that one single unit of regional currency is always backed -by one single unit of fiat currency. - - -Cash-in -+++++++ - -One fundamental entity to create the regional currency is the *master bank account*. -The master bank account is hosted at one fiat bank and whenever it receives a *valid* -fiat payment of N units, it triggers the creation of N units of regional currency. -Such trigger causes the *admin bank account* at the regional bank to wire the N units of -regional currency to the Taler exchange (regional) bank account. At this point, the -Taler exchange is ready to issue the regional coins to the Taler wallet that proves -to own them. - -.. note:: - - *Valid* fiat payments are those with a Taler-relevant subject that should be generated by a Taler wallet. - - -Cash-out -++++++++ - -Once a regional bank user confirms a cash-out operation of N units, the system sends -a regional payment of N units to the *admin bank account*. This latter triggers then -a fiat payment of N units to the fiat bank account owned by the user who initiated the -cash-out. - - -.. _automated-regional-currency-setup: - -Guided Automated Setup -====================== - -This section describes how to setup a regional currency backed by a fiat currency using a script that largely automates the process. You can also follow the :ref:`manual setup` if you want a customized one. - -Prerequisites -+++++++++++++ - -For this manual, we assume that the system is deployed on a contemporary -Debian GNU/Linux or Ubuntu LTS system using the binary packages provided. -Furthermore, you should run the process on a system with one or more globally -reachable IP address(es) *and* with various DNS names already pointing to -these IPs. - -Preparing the required subdomain names -++++++++++++++++++++++++++++++++++++++ - -The GNU Taler program needs to have three subdomains pointing to your server IP address, in order to let NGINX to accommodate each component. -These are "bank", "exchange" and "backend", this said, you need to have a registered top level domain name, -where you can create type (A) entries, as subdomains pointing to your own server public IP address. -A very good advice when creating these subdomains, and if your domain panel lets you specify the TTL (time to live) figure, is -to specify a very low value (such as 300), so in case of future changes, its value (the IP address), will be propagated quickly. - -Once you have added the three required subdomains in your domain control panel, you have to make sure as well, these subdomains have -propagated over the Internet correctly, and they are currently publicly available. - -You can check this from your terminal very easily with the "dig" command, as this: - -.. code-block:: console - - $ dig -t txt bank.domainname.ltd - $ dig -t txt exchange.domainname.ltd - $ dig -t txt backend.domainname.ltd - -You can also use `this tool `_ for the same purpose, and to check the propagation status. - -Now you are ready to go with the next step. - -Obtaining the Scripts -+++++++++++++++++++++ - -First, download the deployment scripts via Git: - -.. code-block:: console - - # apt update && apt install git - $ git clone git://git.taler.net/deployment - -Running the Guided Configuration -++++++++++++++++++++++++++++++++ - -Navigate into the *regional-currency/* directory and run *main.sh* as **root**: - -.. code-block:: console - - $ cd deployment/regional-currency/ - # ./main.sh - -The script will start by asking you fundamental questions about the -desired setup, in particular: - -* The name of the regional currency. It must have 3 to 11 letters. -* The ISO code of the fiat currency. Use 'CHF' or 'EUR'. -* The name of the regional currency bank. It will be shown to business - users when they interact with the system. -* The DNS domain name of your setup (i.e: domain.tld). The installer will - create by itself all the needed subdomains for your domain name, - as (``bank.$DOMAIN``, ``exchange.$DOMAIN`` and ``backend.$DOMAIN``). - But, these subdomain names as explained before, must have been added beforehand to your - DNS domain control panel, and they must be pointing to the - IP address of the server on which you are running the - installation (before you execute the installer). -* Whether to use TLS or not. You should answer ``y`` in most cases. -* Whether to run taler-exchange-offline. Unless you need a high-security - setup and expect to run an offline key management process, say ``y``. - If you say ``n``, you will need to run ``taler-exchange-offline setup`` - on your offline system and provide the master public key. Furthermore, - you should then study the exchange manual on offline key management to - finish the exchange setup process later. -* The admin password for the bank. Be absolutely sure to enter a very, - very long and high-entropy password, preferably use the autogenerated one. - -The information you entered as well as the generated bank admin password will -be stored in a file called ``config/user.conf``. If you run the script in -the future again (for example, to upgrade the installation), you will not be asked -these questions a second time. - -After answering all of the questions, the actual installation will start. The -scripts will download and configure various packages, which may take some time. -Grab a coffee. - -.. note:: - - At this point, the setup is NOT connected to any fiat bank account! The next - steps must always be done manually! - -Running the script again from scratch -+++++++++++++++++++++++++++++++++++++ - -If for some reason your installation doesn't work because you have answered erroneously -some of the interactive questions, or you just want to reset the current installation and to re-deploy -the script again for having its latest changes, you will have to proceed as follows: - -In brief you need to wipe completely the "content" of the file config/user.conf, this doesn't mean -to remove the file itself, but only its content. Even though you can do this manually by editing the file manually -with you preferred text editor, you can also do this in one single command. - -.. code-block:: console - - $ cat /dev/null > config/user.conf - -.. note:: - - In future versions of the program when executed for the second time, the program itself will - show an option to offer wiping the content of this config/user.conf file, automatically. - -Multi-factor authentication -+++++++++++++++++++++++++++ - -By default, multi-factor authentication via SMS and email is enabled. You have to manually configure both channels as described in :ref:`multi-factor authentication `. - -Web-based Configuration -+++++++++++++++++++++++ - -By default, the regional currency conversion rates are 1:1. You can change the conversion rates and the ``admin`` debt limit via the bank's web interface as the ``admin`` user. - -Connecting to a Fiat Bank: the EBICS setup -++++++++++++++++++++++++++++++++++++++++++ - -To complete the conversion setup, you have to set up an EBICS subscriber as described in :ref:`EBICS setup ` using a bank account at a bank dealing in fiat currency that offers an online banking protocol supported by LibEuFin Nexus. - -System ON! -++++++++++ - -The last step is to enable libeufin-nexus to :ref:`import incoming bank -transactions ` (cash in) and to :ref:`trigger -outgoing bank transactions ` (cash out). - -.. code-block:: console - - # systemctl enable --now libeufin-nexus-ebics-fetch - # systemctl enable --now libeufin-nexus-ebics-submit - -.. _manual-regional-currency-setup: - -Manual Setup -============ - -This section describes how to setup a regional currency manually. - -You first need to setup the :ref:`libeufin-bank` and integrate it with a Taler exchange. - -If you don't want your regional currency to be backed by a fiat currency, you can stop here. - -Enabling Currency Conversion -++++++++++++++++++++++++++++ - -You need to setup the :ref:`libeufin-nexus` using a bank account at a bank dealing in fiat currency that -offers an online banking protocol supported by LibEuFin Nexus. - -Next, you have to enable conversion and should ensure that at least one TAN -channel for :ref:`multi-factor authentication ` is configured: - -.. code-block:: ini - - [libeufin-bank] - ALLOW_CONVERSION = YES - FIAT_CURRENCY = EUR - - TAN_SMS = libeufin-tan-sms.sh - # And/Or - TAN_EMAIL = libeufin-tan-email.sh - -Make sure to (re)start the libeufin-bank after changing -these configuration options: - -.. code-block:: console - - # systemctl restart libeufin-bank - - -Web-based Configuration -+++++++++++++++++++++++ - -Now you have to set the conversion rates and the ``admin`` debt limit via the bank's web interface as the ``admin`` user. - -.. _regional-conversion-setup: - -Configuring the Exchange for Conversion -+++++++++++++++++++++++++++++++++++++++ - -This section explains how to enable currency conversion at the exchange, -which is critical for wallets to know how to wire fiat currency to an -exchange to obtain regional currency. - -You will need to use the ``taler-exchange-offline`` tool to inform the -exchange about the **fiat** bank account that can be used for cash in -operations and also specify the URL for currency conversion. Additionally, -you may also configure restrictions on the bank accounts that may originate -the funds, for example, to prevent international wire transfers that may expose -you to additional compliance risks. - -Given the ``$IBAN`` of the fiat currency bank account and ``$NAME`` as -the (URL-encoded) name of the exchange-account owner, the following -``taler-exchange-offline`` invocation can be used to notify wallets about -the possibility of currency conversion (cash in): - -.. code-block:: console - - # taler-exchange-offline \ - enable-account \ - payto://iban/$IBAN?receiver-name=$NAME \ - conversion-url "$CONVERSION_URL" \ - upload - -Here, the ``$CONVERSION_URL`` must be set to the base URL of the conversion -endpoint of the bank, which should be ``https://bank.$DOMAIN/conversion-info/`` -in our setup. - -.. note:: - - The above command adds a **second** bank account to the exchange. - You (or the guided setup script) should have already enabled the - regional currency bank account (without any "conversion-url"). - -System ON! -++++++++++ - -The last step is to enable libeufin-nexus to :ref:`import incoming bank -transactions ` (cash in) and to :ref:`trigger -outgoing bank transactions ` (cash out). - -.. code-block:: console - - # systemctl enable --now libeufin-nexus-ebics-fetch - # systemctl enable --now libeufin-nexus-ebics-submit - -Using the Regional Currency -=========================== - -Wallet Setup -++++++++++++ - -This section describes the interaction between the Taler graphical wallet (Android, -iOS, WebExtensions) and the regional currency system. - -You need to add your regional currency exchange to the wallet. This can -be done by scanning a QR code with a ``taler://withdraw-exchange/exchange.$DOMAIN`` -URL or by manually entering the URL into the respective ``Add exchange`` -dialogue. - - -Cash-In -+++++++ - -Next, start the withdraw process in the Taler wallet for the respective -currency and specify the desired amount. The wallet will then show you the -details of the fiat wire transfer that must be made for the cash-in to be -completed. Once the money has arrived at the fiat bank account, Nexus will -obtain the transaction data and the regional currency bank will create the -corresponding amount in regional currency, crediting the GNU Taler exchange -account. In turn, the exchange will issue the respective amount to your -wallet. - -.. note:: - - Cash-in operations may be subject to conversion rates, conversion fees and - minimum amounts to be transferred. - - -Making payments -+++++++++++++++ - -For testing, you should be able to *deposit* regional currency directly into -your regional currency libeufin-bank account directly from the Taler wallet. -For this, you primarily need to know your bank account details (which should -be accessible by clicking on your name in the bank Web site after logging in). - -.. note:: - - There may be a short delay between the wallet making the deposit and - the exchange crediting your bank account. This is because the wallet - uses a small wire transfer delay by default when initiating a deposit - into a bank account. - -For production, it is more common for a shop to configure a :ref:`Taler -merchant backend ` or at least use an -instance within such a setup. To configure an instance, you primarily need -again the bank account details to :ref:`setup instance bank accounts -`. - - -Cash-Out -++++++++ - -Regional currency accounts that have a positive balance could be eligible for -cash-out. Cash-out operations may again be restricted by the regional -currency operator and will *only* be made to the respective pre-configured -fiat currency bank account. To cash-out, simply log into your regional -currency account, select cash-out, specify the desired amount and pass the -second-factor authorization challenge by entering the TAN you receive at the -registered e-mail address or mobile phone number. - -.. note:: - - Cash-out operations may be subject to conversion rates, conversion fees and - minimum amounts to be transferred. - - -Alternative Podman-based Deployment -=================================== - -The Podman-based deployment installs, configures, and launches any Taler and -LibEuFin service required to operate a regional currency. - -Please clone ``git://git.taler.net/deployment`` and checkout the ``regio`` -branch. Navigate to the ``sandcastle-ng`` directory and read the README file. -It should guide you through all the necessary steps to deploy a regional -currency. -- cgit v1.2.3 From 7ca42dbe1228aa29fb1ad49fad8bf921e091b4a9 Mon Sep 17 00:00:00 2001 From: Antoine A <> Date: Tue, 20 Feb 2024 19:23:10 +0100 Subject: Improve regional currency manual --- frags/nexus-ebics-setup.rst | 24 ++++++++++++++++++++---- libeufin/regional-automated-manual.rst | 8 ++++---- 2 files changed, 24 insertions(+), 8 deletions(-) diff --git a/frags/nexus-ebics-setup.rst b/frags/nexus-ebics-setup.rst index 21904322..19292151 100644 --- a/frags/nexus-ebics-setup.rst +++ b/frags/nexus-ebics-setup.rst @@ -37,8 +37,19 @@ The following snippet shows the mandatory configuration values: .. warning:: This combination of HOST_ID, USER_ID and PARTNER_ID must never be used by another instance of libeufin-nexus or by other EBICS clients, otherwise data will be lost. -.. note:: - If you want to use existing client keys, copy the JSON file to the configured path ``CLIENT_PRIVATE_KEYS_FILE`` (``/var/lib/libeufin-nexus/client-ebics-keys.json`` with the default config) before running the following commands. +Reuse existing client keys +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If you have client keys from a previous EBICS setup you can copy the JSON file to the configured path ``CLIENT_PRIVATE_KEYS_FILE`` (``/var/lib/libeufin-nexus/client-ebics-keys.json`` with the default config). + +Make sure this file is acessible to the user running ``libeufin-nexus``, for the default services you should run: + +.. code-block:: console + + $ chown libeufin-nexus:libeufin-nexus /var/lib/libeufin-nexus/client-ebics-keys.json + +Create new client keys +^^^^^^^^^^^^^^^^^^^^^^ Assuming that the configuration file exists at ``$CONFIG_FILE``, the following command should start the EBICS setup process: @@ -55,8 +66,13 @@ To that end, the previous run should have left a PDF document that you can print, sign and send to the bank. Look for the message that looks like ``PDF file with keys created at '/tmp/libeufin-nexus-keys-$TIMESTAMP.pdf'``. -Once the bank has received and processed this document, run the same -command again to download and verify the bank's keys: +Once the bank has received and processed this document you can continue. + +Get bank keys +^^^^^^^^^^^^^ + +Assuming that the configuration file exists at ``$CONFIG_FILE``, the following +command will finish the EBICS setup process: .. code-block:: console diff --git a/libeufin/regional-automated-manual.rst b/libeufin/regional-automated-manual.rst index aea5ca88..6dacaf0b 100644 --- a/libeufin/regional-automated-manual.rst +++ b/libeufin/regional-automated-manual.rst @@ -87,8 +87,7 @@ Navigate into the *regional-currency/* directory and run *main.sh* as **root**: $ cd deployment/regional-currency/ # ./main.sh -The script will start by asking you fundamental questions about the -desired setup, in particular: +The script will start by installing required packages and then asking you fundamental questions about the desired setup, in particular : * The name of the regional currency. It must have 3 to 11 letters. * The ISO code of the fiat currency. Use 'CHF' or 'EUR'. @@ -102,12 +101,13 @@ desired setup, in particular: IP address of the server on which you are running the installation (before you execute the installer). * Whether to use TLS or not. You should answer ``y`` in most cases. -* Whether to run taler-exchange-offline. Unless you need a high-security +* Whether to store Taler Exchange keys on this server or externally on another server. Unless you need a high-security setup and expect to run an offline key management process, say ``y``. If you say ``n``, you will need to run ``taler-exchange-offline setup`` on your offline system and provide the master public key. Furthermore, you should then study the exchange manual on offline key management to finish the exchange setup process later. +* Whether to setup sms two-factor authentication using Telesign. You should answer ``y`` in most cases. * The admin password for the bank. Be absolutely sure to enter a very, very long and high-entropy password, preferably use the autogenerated one. @@ -148,7 +148,7 @@ with you preferred text editor, you can also do this in one single command. Multi-factor authentication +++++++++++++++++++++++++++ -By default, multi-factor authentication via SMS and email is enabled. You have to manually configure both channels as described in :ref:`multi-factor authentication `. +The script allows you to configure multi-factor authentication via SMS using Telesign as a provider. You can also configure multi-factor authentication via email or use providers other than Telesign for SMS. You will need to configure these channels manually as described in :ref:`multi-factor authentication `. Web-based Configuration +++++++++++++++++++++++ -- cgit v1.2.3 From 755bea81a9f5e2735527d06b3ff75f8288c729f4 Mon Sep 17 00:00:00 2001 From: Javier Sepulveda Date: Wed, 21 Feb 2024 09:48:28 +0100 Subject: Test walkthrough for the Bank backend administator area --- frags/regional-manual-use.rst | 39 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) diff --git a/frags/regional-manual-use.rst b/frags/regional-manual-use.rst index 40106356..09532a58 100644 --- a/frags/regional-manual-use.rst +++ b/frags/regional-manual-use.rst @@ -1,6 +1,45 @@ Using the Regional Currency =========================== +The very first step you should check afte the installation process has been +completed successfully, is to make sure all three URLs (bank,backend and exchange), +are available (this measn to see a Website, and not any NGINX error). + + +Bank backend walkthrough ++++++++++++++++++++++++++ + +* As stated abouth, please visit before "https://bank.yourdomain.ltd", +to make sure it is available. + +* Now login with the username "admin" and the password you have choosen +during the installation process, or use the one which might + have been generated automatically (and shown on your terminal +screen), during the installation process. + Once inside the Bank Administrator area, please create the "very +first" customer account. + +* Transfer some funds from the "admin" bank account to the new customer +account. + +* Now logout from the "admin" account, and login again using the recently "customer" account you have created, and make +sure the funds you have transfered from admin, have arrived correctly. + +* Now, please choose the option "Send Money to a Taler Wallet", and try +to send for example 100 units of your regional currency to the + wallet installed on your browser or mobile phone. + +* Now try to spend some of these funds from your wallet, and try to buy +something somewhere, with the same digital currency you + have choosen, during your installation process, let's say Netzbon. + +* Lastly, you can also try to transfer funds to another "bank account", +for that you will need to know the recipient's username or the bank account ID. + +If you have successfully accomplished all the previous steps, for the bank administrator +backend and your installed Wallet, you can move now to test other components such +as the Merchant backend (https://backend.yourdomain.ltd). + Wallet Setup ++++++++++++ -- cgit v1.2.3 From 10050f06594eafa5f4f3acbaf753e67e07f14e76 Mon Sep 17 00:00:00 2001 From: Javier Sepulveda Date: Wed, 21 Feb 2024 11:42:31 +0100 Subject: Fix rst bullets --- frags/regional-manual-use.rst | 27 ++++++++++----------------- 1 file changed, 10 insertions(+), 17 deletions(-) diff --git a/frags/regional-manual-use.rst b/frags/regional-manual-use.rst index 09532a58..32fcb762 100644 --- a/frags/regional-manual-use.rst +++ b/frags/regional-manual-use.rst @@ -9,31 +9,24 @@ are available (this measn to see a Website, and not any NGINX error). Bank backend walkthrough +++++++++++++++++++++++++ -* As stated abouth, please visit before "https://bank.yourdomain.ltd", -to make sure it is available. +- As stated above, please visit before "https://bank.yourdomain.ltd", to make sure it is available. -* Now login with the username "admin" and the password you have choosen -during the installation process, or use the one which might - have been generated automatically (and shown on your terminal -screen), during the installation process. - Once inside the Bank Administrator area, please create the "very -first" customer account. +- Now login with the username "admin" and the password you have choosen during the installation process, or use the one which might + have been generated automatically (and shown on your terminal screen), during the installation process. + Once inside the Bank Administrator area, please create the "very first" customer account. -* Transfer some funds from the "admin" bank account to the new customer -account. +- Transfer some funds from the "admin" bank account to this new customer account. -* Now logout from the "admin" account, and login again using the recently "customer" account you have created, and make +- Now logout from the "admin" account, and login again using the recently "customer" account you have created, and make sure the funds you have transfered from admin, have arrived correctly. -* Now, please choose the option "Send Money to a Taler Wallet", and try -to send for example 100 units of your regional currency to the +- Now, please choose the option "Send Money to a Taler Wallet", and try to send for example 100 units of your regional currency to the wallet installed on your browser or mobile phone. -* Now try to spend some of these funds from your wallet, and try to buy -something somewhere, with the same digital currency you - have choosen, during your installation process, let's say Netzbon. +- Now try to spend some of these funds from your wallet, and try to buy something somewhere, with the same digital +currency you have choosen, during your installation process, let's say Netzbon. -* Lastly, you can also try to transfer funds to another "bank account", +- Lastly, you can also try to transfer funds to another "bank account", for that you will need to know the recipient's username or the bank account ID. If you have successfully accomplished all the previous steps, for the bank administrator -- cgit v1.2.3 From b6c366c4e201bd54021b42750e0d36c27d83103e Mon Sep 17 00:00:00 2001 From: Javier Sepulveda Date: Wed, 21 Feb 2024 13:31:40 +0100 Subject: Fix intros --- frags/regional-manual-use.rst | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/frags/regional-manual-use.rst b/frags/regional-manual-use.rst index 32fcb762..9eaf2f7e 100644 --- a/frags/regional-manual-use.rst +++ b/frags/regional-manual-use.rst @@ -17,17 +17,14 @@ Bank backend walkthrough - Transfer some funds from the "admin" bank account to this new customer account. -- Now logout from the "admin" account, and login again using the recently "customer" account you have created, and make -sure the funds you have transfered from admin, have arrived correctly. +- Now logout from the "admin" account, and login again using the recently "customer" account you have created, and make sure the funds you have transfered from admin, have arrived correctly. - Now, please choose the option "Send Money to a Taler Wallet", and try to send for example 100 units of your regional currency to the wallet installed on your browser or mobile phone. -- Now try to spend some of these funds from your wallet, and try to buy something somewhere, with the same digital -currency you have choosen, during your installation process, let's say Netzbon. +- Now try to spend some of these funds from your wallet, and try to buy something somewhere, with the same digital currency you have choosen, during your installation process, let's say Netzbon. -- Lastly, you can also try to transfer funds to another "bank account", -for that you will need to know the recipient's username or the bank account ID. +- Lastly, you can also try to transfer funds to another "bank account",for that you will need to know the recipient's username or the bank account ID. If you have successfully accomplished all the previous steps, for the bank administrator backend and your installed Wallet, you can move now to test other components such -- cgit v1.2.3 From 62536c6c29e9754de5988b76883ddb04c5c529d8 Mon Sep 17 00:00:00 2001 From: Florian Dold Date: Wed, 21 Feb 2024 14:21:58 +0100 Subject: DD55 very early draft --- design-documents/055-wallet-problem-report.rst | 82 ++++++++++++++++++++++++++ design-documents/index.rst | 1 + 2 files changed, 83 insertions(+) create mode 100644 design-documents/055-wallet-problem-report.rst diff --git a/design-documents/055-wallet-problem-report.rst b/design-documents/055-wallet-problem-report.rst new file mode 100644 index 00000000..18909f40 --- /dev/null +++ b/design-documents/055-wallet-problem-report.rst @@ -0,0 +1,82 @@ +DD 55: Wallet Problem Reports +############################# + +.. note:: + + **Status**: Early work in progress / DD number reservation. + +Summary +======= + +This design document specifies global error reports generated/managed by wallet-core +and rendered by the wallet UIs. + +Motivation +========== + +Sometimes the wallet encounters issues that go beyond the scope of single transaction. + +Requirements +============ + +* problem reports must have a clear lifecycle +* problem reports must have some type of identification that allows to + easily find out if a new problem report needs to be created when an + error happens or whether an existing one has been created + +Proposed Solution +================= + +Report identification +--------------------- + +The report identifier serves multiple purposes: + +1. Usage as a reference in wallet-core APIs +2. De-duplication. The report ID should allow easy identification of an already existing report for a particular problem. + +New wallet-core requests +------------------------ + +* ``listProblemReports`` +* ``acknowledgeProblemReport``: Mark a problem report as read. +* ``deleteProblemReport``: Delete the problem report. + +New wallet-core notification type +--------------------------------- + +* ``problem-report`` to notify clients about status changes or an error report + (including creation!) + + +Types of reports +---------------- + +* money lost due to the exchange stopping to offer a denomination +* money locked behind a (long) pending refresh +* money lost due to a permanently failing refresh + + +Definition of Done +================== + +TBD. + +Alternatives +============ + +TBD. + +Drawbacks +========= + +TBD. + +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? + diff --git a/design-documents/index.rst b/design-documents/index.rst index 91bfce4c..454564d0 100644 --- a/design-documents/index.rst +++ b/design-documents/index.rst @@ -66,4 +66,5 @@ Design documents that start with "XX" are considered deprecated. 052-libeufin-bank-2fa.rst 053-wallet-ui.rst 054-dynamic-form.rst + 055-wallet-problem-report.rst 999-template -- cgit v1.2.3 From 28644d13f72199cb215297c60f6266ac46502c20 Mon Sep 17 00:00:00 2001 From: Antoine A <> Date: Wed, 21 Feb 2024 14:52:54 +0100 Subject: Improve regional currency manual --- libeufin/regional-automated-manual.rst | 9 ++++----- libeufin/regional-custom-manual.rst | 3 +-- 2 files changed, 5 insertions(+), 7 deletions(-) diff --git a/libeufin/regional-automated-manual.rst b/libeufin/regional-automated-manual.rst index 6dacaf0b..8c0f80c3 100644 --- a/libeufin/regional-automated-manual.rst +++ b/libeufin/regional-automated-manual.rst @@ -138,12 +138,12 @@ with you preferred text editor, you can also do this in one single command. .. code-block:: console - $ cat /dev/null > config/user.conf + # rm config/user.conf .. note:: - In future versions of the program when executed for the second time, the program itself will - show an option to offer wiping the content of this config/user.conf file, automatically. + In future versions of the program when executed for the second time, the program itself will + show an option to offer wiping the content of this config/user.conf file, automatically. Multi-factor authentication +++++++++++++++++++++++++++ @@ -171,7 +171,6 @@ outgoing bank transactions ` (cash out). .. code-block:: console - # systemctl enable --now libeufin-nexus-ebics-fetch - # systemctl enable --now libeufin-nexus-ebics-submit + # systemctl enable --now libeufin-nexus.target .. include:: ../frags/regional-manual-use.rst \ No newline at end of file diff --git a/libeufin/regional-custom-manual.rst b/libeufin/regional-custom-manual.rst index 5674420e..a3c1aecd 100644 --- a/libeufin/regional-custom-manual.rst +++ b/libeufin/regional-custom-manual.rst @@ -117,7 +117,6 @@ outgoing bank transactions ` (cash out). .. code-block:: console - # systemctl enable --now libeufin-nexus-ebics-fetch - # systemctl enable --now libeufin-nexus-ebics-submit + # systemctl enable --now libeufin-nexus.target .. include:: ../frags/regional-manual-use.rst \ No newline at end of file -- cgit v1.2.3 From 0cb17605ccf92e8235a2ccb2ebbdb04782349d0f Mon Sep 17 00:00:00 2001 From: Florian Dold Date: Wed, 21 Feb 2024 16:50:30 +0100 Subject: typo --- frags/regional-manual-use.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/frags/regional-manual-use.rst b/frags/regional-manual-use.rst index 9eaf2f7e..bab59f26 100644 --- a/frags/regional-manual-use.rst +++ b/frags/regional-manual-use.rst @@ -3,7 +3,7 @@ Using the Regional Currency The very first step you should check afte the installation process has been completed successfully, is to make sure all three URLs (bank,backend and exchange), -are available (this measn to see a Website, and not any NGINX error). +are available (this means to see a Website, and not any NGINX error). Bank backend walkthrough -- cgit v1.2.3 From 13511a7e31d8ce44608a1e7c6a6176e7ffe87712 Mon Sep 17 00:00:00 2001 From: Antoine A <> Date: Wed, 21 Feb 2024 16:59:39 +0100 Subject: Improve regional currency manual --- frags/nexus-ebics-setup.rst | 2 +- libeufin/regional-automated-manual.rst | 55 ++++++++++++++++++++++++++++------ 2 files changed, 47 insertions(+), 10 deletions(-) diff --git a/frags/nexus-ebics-setup.rst b/frags/nexus-ebics-setup.rst index 19292151..91494f52 100644 --- a/frags/nexus-ebics-setup.rst +++ b/frags/nexus-ebics-setup.rst @@ -59,7 +59,7 @@ command should start the EBICS setup process: $ libeufin-nexus ebics-setup -c "$CONFIG_FILE" If the previous command failed when running EBICS INI with an error code of -``EBICS_INVALID_USER_STATE``, you need to confirm your keys to your bank to +``EBICS_INVALID_USER_OR_USER_STATE``, you need to confirm your keys to your bank to activate your account. To that end, the previous run should have left a PDF document that you can diff --git a/libeufin/regional-automated-manual.rst b/libeufin/regional-automated-manual.rst index 8c0f80c3..1dc3e2f2 100644 --- a/libeufin/regional-automated-manual.rst +++ b/libeufin/regional-automated-manual.rst @@ -89,26 +89,26 @@ Navigate into the *regional-currency/* directory and run *main.sh* as **root**: The script will start by installing required packages and then asking you fundamental questions about the desired setup, in particular : -* The name of the regional currency. It must have 3 to 11 letters. -* The ISO code of the fiat currency. Use 'CHF' or 'EUR'. -* The name of the regional currency bank. It will be shown to business +#. The name of the regional currency. It must have 3 to 11 letters. +#. The ISO code of the fiat currency. Use 'CHF' or 'EUR'. +#. The name of the regional currency bank. It will be shown to business users when they interact with the system. -* The DNS domain name of your setup (i.e: domain.tld). The installer will +#. The DNS domain name of your setup (i.e: domain.tld). The installer will create by itself all the needed subdomains for your domain name, as (``bank.$DOMAIN``, ``exchange.$DOMAIN`` and ``backend.$DOMAIN``). But, these subdomain names as explained before, must have been added beforehand to your DNS domain control panel, and they must be pointing to the IP address of the server on which you are running the installation (before you execute the installer). -* Whether to use TLS or not. You should answer ``y`` in most cases. -* Whether to store Taler Exchange keys on this server or externally on another server. Unless you need a high-security +#. Whether to use TLS or not. You should answer ``y`` in most cases. +#. Whether to store Taler Exchange keys on this server or externally on another server. Unless you need a high-security setup and expect to run an offline key management process, say ``y``. If you say ``n``, you will need to run ``taler-exchange-offline setup`` on your offline system and provide the master public key. Furthermore, you should then study the exchange manual on offline key management to finish the exchange setup process later. -* Whether to setup sms two-factor authentication using Telesign. You should answer ``y`` in most cases. -* The admin password for the bank. Be absolutely sure to enter a very, +#. Whether to setup sms two-factor authentication using Telesign. You should answer ``y`` in most cases. +#. The admin password for the bank. Be absolutely sure to enter a very, very long and high-entropy password, preferably use the autogenerated one. The information you entered as well as the generated bank admin password will @@ -158,10 +158,47 @@ By default, the regional currency conversion rates are 1:1. You can change the c Connecting to a Fiat Bank: the EBICS setup ++++++++++++++++++++++++++++++++++++++++++ -To complete the conversion setup, you have to set up an EBICS subscriber using a bank account at a bank dealing in fiat currency that offers an online banking protocol supported by LibEuFin Nexus. +To complete the conversion setup, you have to set up an EBICS subscriber using a fiat bank account at a bank dealing in fiat currency that offers an online banking protocol supported by LibEuFin Nexus. .. include:: ../frags/nexus-ebics-setup.rst +Configuring the Exchange for Conversion ++++++++++++++++++++++++++++++++++++++++ + +This section explains how to enable currency conversion at the exchange, +which is critical for wallets to know how to wire fiat currency to an +exchange to obtain regional currency. + +You will need to use the ``taler-exchange-offline`` tool to inform the +exchange about the **fiat** bank account that can be used for cash in +operations and also specify the URL for currency conversion. Additionally, +you may also configure restrictions on the bank accounts that may originate +the funds, for example, to prevent international wire transfers that may expose +you to additional compliance risks. + +Given the ``$IBAN`` of the fiat currency bank account and ``$NAME`` as +the (URL-encoded) name of the exchange-account owner, the following +``taler-exchange-offline`` invocation can be used to notify wallets about +the possibility of currency conversion (cash in): + +.. code-block:: console + + # taler-exchange-offline \ + enable-account \ + payto://iban/$IBAN?receiver-name=$NAME \ + conversion-url "$CONVERSION_URL" \ + upload + +Here, the ``$CONVERSION_URL`` must be set to the base URL of the conversion +endpoint of the bank, which should be ``https://bank.$DOMAIN/conversion-info/`` +in our setup. + +.. note:: + + The above command adds a **second** bank account to the exchange. + You (or the guided setup script) should have already enabled the + regional currency bank account (without any "conversion-url"). + System ON! ++++++++++ -- cgit v1.2.3 From 50f0bae2192034bc7546b88278bc36673e399dca Mon Sep 17 00:00:00 2001 From: Antoine A <> Date: Wed, 21 Feb 2024 17:04:17 +0100 Subject: Improve regional currency manual --- libeufin/regional-automated-manual.rst | 21 ++++----------------- 1 file changed, 4 insertions(+), 17 deletions(-) diff --git a/libeufin/regional-automated-manual.rst b/libeufin/regional-automated-manual.rst index 1dc3e2f2..9b1338df 100644 --- a/libeufin/regional-automated-manual.rst +++ b/libeufin/regional-automated-manual.rst @@ -91,25 +91,12 @@ The script will start by installing required packages and then asking you fundam #. The name of the regional currency. It must have 3 to 11 letters. #. The ISO code of the fiat currency. Use 'CHF' or 'EUR'. -#. The name of the regional currency bank. It will be shown to business - users when they interact with the system. -#. The DNS domain name of your setup (i.e: domain.tld). The installer will - create by itself all the needed subdomains for your domain name, - as (``bank.$DOMAIN``, ``exchange.$DOMAIN`` and ``backend.$DOMAIN``). - But, these subdomain names as explained before, must have been added beforehand to your - DNS domain control panel, and they must be pointing to the - IP address of the server on which you are running the - installation (before you execute the installer). +#. The name of the regional currency bank. It will be shown to business users when they interact with the system. +#. The DNS domain name of your setup (i.e: domain.tld). The installer will create by itself all the needed subdomains for your domain name, as (``bank.$DOMAIN``, ``exchange.$DOMAIN`` and ``backend.$DOMAIN``). But, these subdomain names as explained before, must have been added beforehand to your DNS domain control panel, and they must be pointing to the IP address of the server on which you are running the installation (before you execute the installer). #. Whether to use TLS or not. You should answer ``y`` in most cases. -#. Whether to store Taler Exchange keys on this server or externally on another server. Unless you need a high-security - setup and expect to run an offline key management process, say ``y``. - If you say ``n``, you will need to run ``taler-exchange-offline setup`` - on your offline system and provide the master public key. Furthermore, - you should then study the exchange manual on offline key management to - finish the exchange setup process later. +#. Whether to store Taler Exchange keys on this server or externally on another server. Unless you need a high-security setup and expect to run an offline key management process, say ``y``. If you say ``n``, you will need to run ``taler-exchange-offline setup`` on your offline system and provide the master public key. Furthermore, you should then study the exchange manual on offline key management to finish the exchange setup process later. #. Whether to setup sms two-factor authentication using Telesign. You should answer ``y`` in most cases. -#. The admin password for the bank. Be absolutely sure to enter a very, - very long and high-entropy password, preferably use the autogenerated one. +#. The admin password for the bank. Be absolutely sure to enter a very, very long and high-entropy password, preferably use the autogenerated one. The information you entered as well as the generated bank admin password will be stored in a file called ``config/user.conf``. If you run the script in -- cgit v1.2.3 From af968a65a14f87b9126ee1619e10ba054ba090f5 Mon Sep 17 00:00:00 2001 From: Antoine A <> Date: Wed, 21 Feb 2024 17:22:10 +0100 Subject: Improve regional currency manual --- frags/nexus-ebics-setup.rst | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/frags/nexus-ebics-setup.rst b/frags/nexus-ebics-setup.rst index 91494f52..564978b8 100644 --- a/frags/nexus-ebics-setup.rst +++ b/frags/nexus-ebics-setup.rst @@ -42,7 +42,7 @@ Reuse existing client keys If you have client keys from a previous EBICS setup you can copy the JSON file to the configured path ``CLIENT_PRIVATE_KEYS_FILE`` (``/var/lib/libeufin-nexus/client-ebics-keys.json`` with the default config). -Make sure this file is acessible to the user running ``libeufin-nexus``, for the default services you should run: +Make sure this file is accessible to the user running ``libeufin-nexus``, for the default services you should run: .. code-block:: console @@ -78,4 +78,10 @@ command will finish the EBICS setup process: $ libeufin-nexus ebics-setup -c "$CONFIG_FILE" -The EBICS setup is finished once the bank keys have been accepted. \ No newline at end of file +The EBICS setup is finished once the bank keys have been accepted. + +Make sure this bank keys are accessible to the user running ``libeufin-nexus``, for the default services you should run: + +.. code-block:: console + + $ chown libeufin-nexus:libeufin-nexus /var/lib/libeufin-nexus/bank-ebics-keys.json -- cgit v1.2.3 From 158ddc760c813082b850e876003dba2f2644a503 Mon Sep 17 00:00:00 2001 From: Florian Dold Date: Wed, 21 Feb 2024 19:30:06 +0100 Subject: DD55 --- design-documents/055-wallet-problem-report.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/design-documents/055-wallet-problem-report.rst b/design-documents/055-wallet-problem-report.rst index 18909f40..0b478416 100644 --- a/design-documents/055-wallet-problem-report.rst +++ b/design-documents/055-wallet-problem-report.rst @@ -55,6 +55,7 @@ Types of reports * money lost due to the exchange stopping to offer a denomination * money locked behind a (long) pending refresh * money lost due to a permanently failing refresh +* exchange changed its master public key Definition of Done -- cgit v1.2.3 From d6a97e7a95b77e3e058ebbda25dce559c38d4de8 Mon Sep 17 00:00:00 2001 From: Florian Dold Date: Thu, 22 Feb 2024 13:34:50 +0100 Subject: dd55 --- design-documents/055-wallet-problem-report.rst | 1 + design-documents/index.rst | 1 + 2 files changed, 2 insertions(+) diff --git a/design-documents/055-wallet-problem-report.rst b/design-documents/055-wallet-problem-report.rst index 0b478416..a7ae783c 100644 --- a/design-documents/055-wallet-problem-report.rst +++ b/design-documents/055-wallet-problem-report.rst @@ -56,6 +56,7 @@ Types of reports * money locked behind a (long) pending refresh * money lost due to a permanently failing refresh * exchange changed its master public key +* a denomination changed its info (expiration, fees) Definition of Done diff --git a/design-documents/index.rst b/design-documents/index.rst index 454564d0..03448acb 100644 --- a/design-documents/index.rst +++ b/design-documents/index.rst @@ -67,4 +67,5 @@ Design documents that start with "XX" are considered deprecated. 053-wallet-ui.rst 054-dynamic-form.rst 055-wallet-problem-report.rst + 056-wallet-activity-diagnostics.rst 999-template -- cgit v1.2.3 From 9bbc32c0484be670f4a32cc3e9e4a0faae994851 Mon Sep 17 00:00:00 2001 From: Antoine A <> Date: Thu, 22 Feb 2024 16:26:34 +0100 Subject: Improve 2FA documentation --- core/api-corebank.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/core/api-corebank.rst b/core/api-corebank.rst index 7a503f46..68f47fc7 100644 --- a/core/api-corebank.rst +++ b/core/api-corebank.rst @@ -1006,7 +1006,7 @@ Cashouts .. http:post:: /accounts/$USERNAME/challenge/$CHALLENGE_ID/confirm - Solves the ``CHALLENGE_ID`` challenge and performs the protected operation. + Solves the ``CHALLENGE_ID`` challenge and allows performing the protected operation. When the challenge is confirmed, you can call the protected endpoint again with ``CHALLENGE_ID`` in the ``X-Challenge-Id`` HTTP header and an empty request body. -- cgit v1.2.3 From 6978fed0ddf1bfa2d658a3b17a309b34e6357944 Mon Sep 17 00:00:00 2001 From: Antoine A <> Date: Thu, 22 Feb 2024 17:49:26 +0100 Subject: Improve regional currency manual --- frags/regional-manual-use.rst | 2 +- libeufin/regional-automated-manual.rst | 88 +++++++++++++++++++++++++++++----- 2 files changed, 76 insertions(+), 14 deletions(-) diff --git a/frags/regional-manual-use.rst b/frags/regional-manual-use.rst index bab59f26..f33d9010 100644 --- a/frags/regional-manual-use.rst +++ b/frags/regional-manual-use.rst @@ -37,7 +37,7 @@ This section describes the interaction between the Taler graphical wallet (Andro iOS, WebExtensions) and the regional currency system. You need to add your regional currency exchange to the wallet. This can -be done by scanning a QR code with a ``taler://withdraw-exchange/exchange.$DOMAIN`` +be done by scanning a QR code with a ``taler://withdraw-exchange/exchange.$DOMAIN/$MASTER_PUB`` URL or by manually entering the URL into the respective ``Add exchange`` dialogue. diff --git a/libeufin/regional-automated-manual.rst b/libeufin/regional-automated-manual.rst index 9b1338df..29e24681 100644 --- a/libeufin/regional-automated-manual.rst +++ b/libeufin/regional-automated-manual.rst @@ -147,7 +147,79 @@ Connecting to a Fiat Bank: the EBICS setup To complete the conversion setup, you have to set up an EBICS subscriber using a fiat bank account at a bank dealing in fiat currency that offers an online banking protocol supported by LibEuFin Nexus. -.. include:: ../frags/nexus-ebics-setup.rst +When you sign up for an EBICS-enabled bank account, the bank will provide you +with various credentials. Those must be provided in the +``/etc/libeufin/libeufin-nexus.conf`` configuration file. + +.. note:: + As legacy transactions in that bank account would likely confuse the system, it is advisable to use a fresh bank account with an empty transaction history. + +The following snippet shows the mandatory configuration values: + +.. _core-config: + +.. code-block:: ini + + [nexus-ebics] + # Bank + HOST_BASE_URL = https://ebics.postfinance.ch/ebics/ebics.aspx + BANK_DIALECT = postfinance + + # EBICS IDs + HOST_ID = PFEBICS + USER_ID = PFC00563 + PARTNER_ID = PFC00563 + + # Account information + IBAN = CH7789144474425692816 + BIC = POFICHBEXXX + NAME = John Smith S.A. + +.. warning:: + This combination of HOST_ID, USER_ID and PARTNER_ID must never be used by another instance of libeufin-nexus or by other EBICS clients, otherwise data will be lost. + +Reuse existing client keys +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If you have client keys from a previous EBICS setup you can copy the JSON file to ``/var/lib/libeufin-nexus/client-ebics-keys.json``. + +Make sure this file is accessible to the user running ``libeufin-nexus``, for the default services you should run: + +.. code-block:: console + + $ chown libeufin-nexus:libeufin-nexus /var/lib/libeufin-nexus/client-ebics-keys.json + +Create new client keys +^^^^^^^^^^^^^^^^^^^^^^ + +Run the following command to start the EBICS setup process: + +.. code-block:: console + + $ sudo -u libeufin-nexus libeufin-nexus ebics-setup + +If the previous command failed when running EBICS INI with an error code of +``EBICS_INVALID_USER_OR_USER_STATE``, you need to confirm your keys to your bank to +activate your account. + +To that end, the previous run should have left a PDF document that you can +print, sign and send to the bank. Look for the message that looks like ``PDF +file with keys created at '/tmp/libeufin-nexus-keys-$TIMESTAMP.pdf'``. + +Once the bank has received and processed this document you can continue. + +Get bank keys +^^^^^^^^^^^^^ + +Assuming that the configuration file exists at ``$CONFIG_FILE``, the following +command will finish the EBICS setup process: + +.. code-block:: console + + $ sudo -u libeufin-nexus libeufin-nexus ebics-setup + +The EBICS setup is finished once the bank keys have been accepted. + Configuring the Exchange for Conversion +++++++++++++++++++++++++++++++++++++++ @@ -170,22 +242,12 @@ the possibility of currency conversion (cash in): .. code-block:: console - # taler-exchange-offline \ + $ sudo -u taler-exchange-offline taler-exchange-offline \ enable-account \ payto://iban/$IBAN?receiver-name=$NAME \ - conversion-url "$CONVERSION_URL" \ + conversion-url "${PROTO}://bank.$DOMAIN/conversion-info/" \ upload -Here, the ``$CONVERSION_URL`` must be set to the base URL of the conversion -endpoint of the bank, which should be ``https://bank.$DOMAIN/conversion-info/`` -in our setup. - -.. note:: - - The above command adds a **second** bank account to the exchange. - You (or the guided setup script) should have already enabled the - regional currency bank account (without any "conversion-url"). - System ON! ++++++++++ -- cgit v1.2.3 From 3f329383f0743ff9256b70e4a1e807010a0db73a Mon Sep 17 00:00:00 2001 From: Antoine A <> Date: Thu, 22 Feb 2024 17:54:33 +0100 Subject: Improve regional currency manual --- libeufin/regional-automated-manual.rst | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/libeufin/regional-automated-manual.rst b/libeufin/regional-automated-manual.rst index 29e24681..b16c11f8 100644 --- a/libeufin/regional-automated-manual.rst +++ b/libeufin/regional-automated-manual.rst @@ -183,7 +183,7 @@ Reuse existing client keys If you have client keys from a previous EBICS setup you can copy the JSON file to ``/var/lib/libeufin-nexus/client-ebics-keys.json``. -Make sure this file is accessible to the user running ``libeufin-nexus``, for the default services you should run: +Make sure this file is accessible to the user running ``libeufin-nexus``, you should run: .. code-block:: console @@ -211,8 +211,7 @@ Once the bank has received and processed this document you can continue. Get bank keys ^^^^^^^^^^^^^ -Assuming that the configuration file exists at ``$CONFIG_FILE``, the following -command will finish the EBICS setup process: +Run the following command to finish the EBICS setup process: .. code-block:: console -- cgit v1.2.3 From 53970e2ee81ce97055ee0fd63430547efc39ac6a Mon Sep 17 00:00:00 2001 From: Marc Stibane Date: Sun, 25 Feb 2024 10:30:19 +0100 Subject: Screenshot of iOS Taler Wallet: empty wallet (#10) --- .../ios-wallet/VIEW_EMPTY_WALLET_10.png | Bin 0 -> 165173 bytes 1 file changed, 0 insertions(+), 0 deletions(-) create mode 100644 design-documents/wallet-screenshots/ios-wallet/VIEW_EMPTY_WALLET_10.png diff --git a/design-documents/wallet-screenshots/ios-wallet/VIEW_EMPTY_WALLET_10.png b/design-documents/wallet-screenshots/ios-wallet/VIEW_EMPTY_WALLET_10.png new file mode 100644 index 00000000..4f1a19ec Binary files /dev/null and b/design-documents/wallet-screenshots/ios-wallet/VIEW_EMPTY_WALLET_10.png differ -- cgit v1.2.3 From 9b7566cab59cfdadf9894c7c154a4c9237c7c92e Mon Sep 17 00:00:00 2001 From: Marc Stibane Date: Sun, 25 Feb 2024 12:16:46 +0100 Subject: Screenshots for iOS cta-withdraw --- .../ios-wallet/VIEW_EMPTY_WALLET_10.png | Bin 165173 -> 0 bytes .../ios-wallet/cta-withdraw-bank-confirm.png | Bin 0 -> 357675 bytes .../ios-wallet/cta-withdraw-bank-confirmed.png | Bin 0 -> 357108 bytes .../ios-wallet/cta-withdraw-bank-register.png | Bin 0 -> 338618 bytes .../ios-wallet/cta-withdraw-bank-send-money.png | Bin 0 -> 464966 bytes .../ios-wallet/cta-withdraw-bank-withdraw.png | Bin 0 -> 505046 bytes .../cta-withdraw-sheet130-withdraw-confirm.png | Bin 0 -> 202047 bytes .../ios-wallet/cta-withdraw-sheet130-withdraw.png | Bin 0 -> 246405 bytes .../ios-wallet/cta-withdraw-sheet131-tos.png | Bin 0 -> 317496 bytes .../cta-withdraw-sheet133-withdraw-confirm-bank.png | Bin 0 -> 230382 bytes .../ios-wallet/cta-withdraw-view10-empty-wallet.png | Bin 0 -> 169741 bytes .../ios-wallet/cta-withdraw-view22-balances.png | Bin 0 -> 239045 bytes 12 files changed, 0 insertions(+), 0 deletions(-) delete mode 100644 design-documents/wallet-screenshots/ios-wallet/VIEW_EMPTY_WALLET_10.png create mode 100644 design-documents/wallet-screenshots/ios-wallet/cta-withdraw-bank-confirm.png create mode 100644 design-documents/wallet-screenshots/ios-wallet/cta-withdraw-bank-confirmed.png create mode 100644 design-documents/wallet-screenshots/ios-wallet/cta-withdraw-bank-register.png create mode 100644 design-documents/wallet-screenshots/ios-wallet/cta-withdraw-bank-send-money.png create mode 100644 design-documents/wallet-screenshots/ios-wallet/cta-withdraw-bank-withdraw.png create mode 100644 design-documents/wallet-screenshots/ios-wallet/cta-withdraw-sheet130-withdraw-confirm.png create mode 100644 design-documents/wallet-screenshots/ios-wallet/cta-withdraw-sheet130-withdraw.png create mode 100644 design-documents/wallet-screenshots/ios-wallet/cta-withdraw-sheet131-tos.png create mode 100644 design-documents/wallet-screenshots/ios-wallet/cta-withdraw-sheet133-withdraw-confirm-bank.png create mode 100644 design-documents/wallet-screenshots/ios-wallet/cta-withdraw-view10-empty-wallet.png create mode 100644 design-documents/wallet-screenshots/ios-wallet/cta-withdraw-view22-balances.png diff --git a/design-documents/wallet-screenshots/ios-wallet/VIEW_EMPTY_WALLET_10.png b/design-documents/wallet-screenshots/ios-wallet/VIEW_EMPTY_WALLET_10.png deleted file mode 100644 index 4f1a19ec..00000000 Binary files a/design-documents/wallet-screenshots/ios-wallet/VIEW_EMPTY_WALLET_10.png and /dev/null differ diff --git a/design-documents/wallet-screenshots/ios-wallet/cta-withdraw-bank-confirm.png b/design-documents/wallet-screenshots/ios-wallet/cta-withdraw-bank-confirm.png new file mode 100644 index 00000000..4441777a Binary files /dev/null and b/design-documents/wallet-screenshots/ios-wallet/cta-withdraw-bank-confirm.png differ diff --git a/design-documents/wallet-screenshots/ios-wallet/cta-withdraw-bank-confirmed.png b/design-documents/wallet-screenshots/ios-wallet/cta-withdraw-bank-confirmed.png new file mode 100644 index 00000000..c356eb13 Binary files /dev/null and b/design-documents/wallet-screenshots/ios-wallet/cta-withdraw-bank-confirmed.png differ diff --git a/design-documents/wallet-screenshots/ios-wallet/cta-withdraw-bank-register.png b/design-documents/wallet-screenshots/ios-wallet/cta-withdraw-bank-register.png new file mode 100644 index 00000000..e7b7c1f9 Binary files /dev/null and b/design-documents/wallet-screenshots/ios-wallet/cta-withdraw-bank-register.png differ diff --git a/design-documents/wallet-screenshots/ios-wallet/cta-withdraw-bank-send-money.png b/design-documents/wallet-screenshots/ios-wallet/cta-withdraw-bank-send-money.png new file mode 100644 index 00000000..788ae7ab Binary files /dev/null and b/design-documents/wallet-screenshots/ios-wallet/cta-withdraw-bank-send-money.png differ diff --git a/design-documents/wallet-screenshots/ios-wallet/cta-withdraw-bank-withdraw.png b/design-documents/wallet-screenshots/ios-wallet/cta-withdraw-bank-withdraw.png new file mode 100644 index 00000000..74e1efff Binary files /dev/null and b/design-documents/wallet-screenshots/ios-wallet/cta-withdraw-bank-withdraw.png differ diff --git a/design-documents/wallet-screenshots/ios-wallet/cta-withdraw-sheet130-withdraw-confirm.png b/design-documents/wallet-screenshots/ios-wallet/cta-withdraw-sheet130-withdraw-confirm.png new file mode 100644 index 00000000..22c57d66 Binary files /dev/null and b/design-documents/wallet-screenshots/ios-wallet/cta-withdraw-sheet130-withdraw-confirm.png differ diff --git a/design-documents/wallet-screenshots/ios-wallet/cta-withdraw-sheet130-withdraw.png b/design-documents/wallet-screenshots/ios-wallet/cta-withdraw-sheet130-withdraw.png new file mode 100644 index 00000000..4f893fd4 Binary files /dev/null and b/design-documents/wallet-screenshots/ios-wallet/cta-withdraw-sheet130-withdraw.png differ diff --git a/design-documents/wallet-screenshots/ios-wallet/cta-withdraw-sheet131-tos.png b/design-documents/wallet-screenshots/ios-wallet/cta-withdraw-sheet131-tos.png new file mode 100644 index 00000000..1aafc03e Binary files /dev/null and b/design-documents/wallet-screenshots/ios-wallet/cta-withdraw-sheet131-tos.png differ diff --git a/design-documents/wallet-screenshots/ios-wallet/cta-withdraw-sheet133-withdraw-confirm-bank.png b/design-documents/wallet-screenshots/ios-wallet/cta-withdraw-sheet133-withdraw-confirm-bank.png new file mode 100644 index 00000000..94ad63b1 Binary files /dev/null and b/design-documents/wallet-screenshots/ios-wallet/cta-withdraw-sheet133-withdraw-confirm-bank.png differ diff --git a/design-documents/wallet-screenshots/ios-wallet/cta-withdraw-view10-empty-wallet.png b/design-documents/wallet-screenshots/ios-wallet/cta-withdraw-view10-empty-wallet.png new file mode 100644 index 00000000..a6737b9f Binary files /dev/null and b/design-documents/wallet-screenshots/ios-wallet/cta-withdraw-view10-empty-wallet.png differ diff --git a/design-documents/wallet-screenshots/ios-wallet/cta-withdraw-view22-balances.png b/design-documents/wallet-screenshots/ios-wallet/cta-withdraw-view22-balances.png new file mode 100644 index 00000000..bd83cb8f Binary files /dev/null and b/design-documents/wallet-screenshots/ios-wallet/cta-withdraw-view22-balances.png differ -- cgit v1.2.3 From b4b7cc5cb0d5a609e63711100520f577ba3bee57 Mon Sep 17 00:00:00 2001 From: Marc Stibane Date: Sun, 25 Feb 2024 12:18:11 +0100 Subject: Screenshots for iOS cta-withdraw, with CHF instead of KUDOS --- .../CHF/cta-withdraw-sheet130-withdraw-confirm.png | Bin 0 -> 193455 bytes .../ios-wallet/CHF/cta-withdraw-sheet130-withdraw.png | Bin 0 -> 237544 bytes .../cta-withdraw-sheet133-withdraw-confirm-bank.png | Bin 0 -> 231969 bytes .../ios-wallet/CHF/cta-withdraw-view22-balances.png | Bin 0 -> 234937 bytes 4 files changed, 0 insertions(+), 0 deletions(-) create mode 100644 design-documents/wallet-screenshots/ios-wallet/CHF/cta-withdraw-sheet130-withdraw-confirm.png create mode 100644 design-documents/wallet-screenshots/ios-wallet/CHF/cta-withdraw-sheet130-withdraw.png create mode 100644 design-documents/wallet-screenshots/ios-wallet/CHF/cta-withdraw-sheet133-withdraw-confirm-bank.png create mode 100644 design-documents/wallet-screenshots/ios-wallet/CHF/cta-withdraw-view22-balances.png diff --git a/design-documents/wallet-screenshots/ios-wallet/CHF/cta-withdraw-sheet130-withdraw-confirm.png b/design-documents/wallet-screenshots/ios-wallet/CHF/cta-withdraw-sheet130-withdraw-confirm.png new file mode 100644 index 00000000..11dd9db0 Binary files /dev/null and b/design-documents/wallet-screenshots/ios-wallet/CHF/cta-withdraw-sheet130-withdraw-confirm.png differ diff --git a/design-documents/wallet-screenshots/ios-wallet/CHF/cta-withdraw-sheet130-withdraw.png b/design-documents/wallet-screenshots/ios-wallet/CHF/cta-withdraw-sheet130-withdraw.png new file mode 100644 index 00000000..d46f0e5c Binary files /dev/null and b/design-documents/wallet-screenshots/ios-wallet/CHF/cta-withdraw-sheet130-withdraw.png differ diff --git a/design-documents/wallet-screenshots/ios-wallet/CHF/cta-withdraw-sheet133-withdraw-confirm-bank.png b/design-documents/wallet-screenshots/ios-wallet/CHF/cta-withdraw-sheet133-withdraw-confirm-bank.png new file mode 100644 index 00000000..5d7dd8cd Binary files /dev/null and b/design-documents/wallet-screenshots/ios-wallet/CHF/cta-withdraw-sheet133-withdraw-confirm-bank.png differ diff --git a/design-documents/wallet-screenshots/ios-wallet/CHF/cta-withdraw-view22-balances.png b/design-documents/wallet-screenshots/ios-wallet/CHF/cta-withdraw-view22-balances.png new file mode 100644 index 00000000..473621e8 Binary files /dev/null and b/design-documents/wallet-screenshots/ios-wallet/CHF/cta-withdraw-view22-balances.png differ -- cgit v1.2.3 From 530c17e2085125758c89795533a60d153c66e144 Mon Sep 17 00:00:00 2001 From: Marc Stibane Date: Sun, 25 Feb 2024 15:17:13 +0100 Subject: Move screenshots into withdraw-bankIntegrated --- .../CHF/cta-withdraw-sheet130-withdraw-confirm.png | Bin 193455 -> 0 bytes .../ios-wallet/CHF/cta-withdraw-sheet130-withdraw.png | Bin 237544 -> 0 bytes .../cta-withdraw-sheet133-withdraw-confirm-bank.png | Bin 231969 -> 0 bytes .../ios-wallet/CHF/cta-withdraw-view22-balances.png | Bin 234937 -> 0 bytes .../ios-wallet/cta-withdraw-bank-confirm.png | Bin 357675 -> 0 bytes .../ios-wallet/cta-withdraw-bank-confirmed.png | Bin 357108 -> 0 bytes .../ios-wallet/cta-withdraw-bank-register.png | Bin 338618 -> 0 bytes .../ios-wallet/cta-withdraw-bank-send-money.png | Bin 464966 -> 0 bytes .../ios-wallet/cta-withdraw-bank-withdraw.png | Bin 505046 -> 0 bytes .../cta-withdraw-sheet130-withdraw-confirm.png | Bin 202047 -> 0 bytes .../ios-wallet/cta-withdraw-sheet130-withdraw.png | Bin 246405 -> 0 bytes .../ios-wallet/cta-withdraw-sheet131-tos.png | Bin 317496 -> 0 bytes .../cta-withdraw-sheet133-withdraw-confirm-bank.png | Bin 230382 -> 0 bytes .../ios-wallet/cta-withdraw-view10-empty-wallet.png | Bin 169741 -> 0 bytes .../ios-wallet/cta-withdraw-view22-balances.png | Bin 239045 -> 0 bytes .../CHF/cta-withdraw-sheet130-withdraw-confirm.png | Bin 0 -> 193455 bytes .../CHF/cta-withdraw-sheet130-withdraw.png | Bin 0 -> 237544 bytes .../cta-withdraw-sheet133-withdraw-confirm-bank.png | Bin 0 -> 231969 bytes .../CHF/cta-withdraw-view22-balances.png | Bin 0 -> 234937 bytes .../cta-withdraw-bank-confirm.png | Bin 0 -> 357675 bytes .../cta-withdraw-bank-confirmed.png | Bin 0 -> 357108 bytes .../cta-withdraw-bank-register.png | Bin 0 -> 338618 bytes .../cta-withdraw-bank-send-money.png | Bin 0 -> 464966 bytes .../cta-withdraw-bank-withdraw.png | Bin 0 -> 505046 bytes .../cta-withdraw-sheet130-withdraw-confirm.png | Bin 0 -> 202047 bytes .../cta-withdraw-sheet130-withdraw.png | Bin 0 -> 246405 bytes .../cta-withdraw-sheet131-tos.png | Bin 0 -> 317496 bytes .../cta-withdraw-sheet133-withdraw-confirm-bank.png | Bin 0 -> 230382 bytes .../cta-withdraw-view10-empty-wallet.png | Bin 0 -> 169741 bytes .../cta-withdraw-view22-balances.png | Bin 0 -> 239045 bytes 30 files changed, 0 insertions(+), 0 deletions(-) delete mode 100644 design-documents/wallet-screenshots/ios-wallet/CHF/cta-withdraw-sheet130-withdraw-confirm.png delete mode 100644 design-documents/wallet-screenshots/ios-wallet/CHF/cta-withdraw-sheet130-withdraw.png delete mode 100644 design-documents/wallet-screenshots/ios-wallet/CHF/cta-withdraw-sheet133-withdraw-confirm-bank.png delete mode 100644 design-documents/wallet-screenshots/ios-wallet/CHF/cta-withdraw-view22-balances.png delete mode 100644 design-documents/wallet-screenshots/ios-wallet/cta-withdraw-bank-confirm.png delete mode 100644 design-documents/wallet-screenshots/ios-wallet/cta-withdraw-bank-confirmed.png delete mode 100644 design-documents/wallet-screenshots/ios-wallet/cta-withdraw-bank-register.png delete mode 100644 design-documents/wallet-screenshots/ios-wallet/cta-withdraw-bank-send-money.png delete mode 100644 design-documents/wallet-screenshots/ios-wallet/cta-withdraw-bank-withdraw.png delete mode 100644 design-documents/wallet-screenshots/ios-wallet/cta-withdraw-sheet130-withdraw-confirm.png delete mode 100644 design-documents/wallet-screenshots/ios-wallet/cta-withdraw-sheet130-withdraw.png delete mode 100644 design-documents/wallet-screenshots/ios-wallet/cta-withdraw-sheet131-tos.png delete mode 100644 design-documents/wallet-screenshots/ios-wallet/cta-withdraw-sheet133-withdraw-confirm-bank.png delete mode 100644 design-documents/wallet-screenshots/ios-wallet/cta-withdraw-view10-empty-wallet.png delete mode 100644 design-documents/wallet-screenshots/ios-wallet/cta-withdraw-view22-balances.png create mode 100644 design-documents/wallet-screenshots/ios-wallet/withdraw-bankIntegrated/CHF/cta-withdraw-sheet130-withdraw-confirm.png create mode 100644 design-documents/wallet-screenshots/ios-wallet/withdraw-bankIntegrated/CHF/cta-withdraw-sheet130-withdraw.png create mode 100644 design-documents/wallet-screenshots/ios-wallet/withdraw-bankIntegrated/CHF/cta-withdraw-sheet133-withdraw-confirm-bank.png create mode 100644 design-documents/wallet-screenshots/ios-wallet/withdraw-bankIntegrated/CHF/cta-withdraw-view22-balances.png create mode 100644 design-documents/wallet-screenshots/ios-wallet/withdraw-bankIntegrated/cta-withdraw-bank-confirm.png create mode 100644 design-documents/wallet-screenshots/ios-wallet/withdraw-bankIntegrated/cta-withdraw-bank-confirmed.png create mode 100644 design-documents/wallet-screenshots/ios-wallet/withdraw-bankIntegrated/cta-withdraw-bank-register.png create mode 100644 design-documents/wallet-screenshots/ios-wallet/withdraw-bankIntegrated/cta-withdraw-bank-send-money.png create mode 100644 design-documents/wallet-screenshots/ios-wallet/withdraw-bankIntegrated/cta-withdraw-bank-withdraw.png create mode 100644 design-documents/wallet-screenshots/ios-wallet/withdraw-bankIntegrated/cta-withdraw-sheet130-withdraw-confirm.png create mode 100644 design-documents/wallet-screenshots/ios-wallet/withdraw-bankIntegrated/cta-withdraw-sheet130-withdraw.png create mode 100644 design-documents/wallet-screenshots/ios-wallet/withdraw-bankIntegrated/cta-withdraw-sheet131-tos.png create mode 100644 design-documents/wallet-screenshots/ios-wallet/withdraw-bankIntegrated/cta-withdraw-sheet133-withdraw-confirm-bank.png create mode 100644 design-documents/wallet-screenshots/ios-wallet/withdraw-bankIntegrated/cta-withdraw-view10-empty-wallet.png create mode 100644 design-documents/wallet-screenshots/ios-wallet/withdraw-bankIntegrated/cta-withdraw-view22-balances.png diff --git a/design-documents/wallet-screenshots/ios-wallet/CHF/cta-withdraw-sheet130-withdraw-confirm.png b/design-documents/wallet-screenshots/ios-wallet/CHF/cta-withdraw-sheet130-withdraw-confirm.png deleted file mode 100644 index 11dd9db0..00000000 Binary files a/design-documents/wallet-screenshots/ios-wallet/CHF/cta-withdraw-sheet130-withdraw-confirm.png and /dev/null differ diff --git a/design-documents/wallet-screenshots/ios-wallet/CHF/cta-withdraw-sheet130-withdraw.png b/design-documents/wallet-screenshots/ios-wallet/CHF/cta-withdraw-sheet130-withdraw.png deleted file mode 100644 index d46f0e5c..00000000 Binary files a/design-documents/wallet-screenshots/ios-wallet/CHF/cta-withdraw-sheet130-withdraw.png and /dev/null differ diff --git a/design-documents/wallet-screenshots/ios-wallet/CHF/cta-withdraw-sheet133-withdraw-confirm-bank.png b/design-documents/wallet-screenshots/ios-wallet/CHF/cta-withdraw-sheet133-withdraw-confirm-bank.png deleted file mode 100644 index 5d7dd8cd..00000000 Binary files a/design-documents/wallet-screenshots/ios-wallet/CHF/cta-withdraw-sheet133-withdraw-confirm-bank.png and /dev/null differ diff --git a/design-documents/wallet-screenshots/ios-wallet/CHF/cta-withdraw-view22-balances.png b/design-documents/wallet-screenshots/ios-wallet/CHF/cta-withdraw-view22-balances.png deleted file mode 100644 index 473621e8..00000000 Binary files a/design-documents/wallet-screenshots/ios-wallet/CHF/cta-withdraw-view22-balances.png and /dev/null differ diff --git a/design-documents/wallet-screenshots/ios-wallet/cta-withdraw-bank-confirm.png b/design-documents/wallet-screenshots/ios-wallet/cta-withdraw-bank-confirm.png deleted file mode 100644 index 4441777a..00000000 Binary files a/design-documents/wallet-screenshots/ios-wallet/cta-withdraw-bank-confirm.png and /dev/null differ diff --git a/design-documents/wallet-screenshots/ios-wallet/cta-withdraw-bank-confirmed.png b/design-documents/wallet-screenshots/ios-wallet/cta-withdraw-bank-confirmed.png deleted file mode 100644 index c356eb13..00000000 Binary files a/design-documents/wallet-screenshots/ios-wallet/cta-withdraw-bank-confirmed.png and /dev/null differ diff --git a/design-documents/wallet-screenshots/ios-wallet/cta-withdraw-bank-register.png b/design-documents/wallet-screenshots/ios-wallet/cta-withdraw-bank-register.png deleted file mode 100644 index e7b7c1f9..00000000 Binary files a/design-documents/wallet-screenshots/ios-wallet/cta-withdraw-bank-register.png and /dev/null differ diff --git a/design-documents/wallet-screenshots/ios-wallet/cta-withdraw-bank-send-money.png b/design-documents/wallet-screenshots/ios-wallet/cta-withdraw-bank-send-money.png deleted file mode 100644 index 788ae7ab..00000000 Binary files a/design-documents/wallet-screenshots/ios-wallet/cta-withdraw-bank-send-money.png and /dev/null differ diff --git a/design-documents/wallet-screenshots/ios-wallet/cta-withdraw-bank-withdraw.png b/design-documents/wallet-screenshots/ios-wallet/cta-withdraw-bank-withdraw.png deleted file mode 100644 index 74e1efff..00000000 Binary files a/design-documents/wallet-screenshots/ios-wallet/cta-withdraw-bank-withdraw.png and /dev/null differ diff --git a/design-documents/wallet-screenshots/ios-wallet/cta-withdraw-sheet130-withdraw-confirm.png b/design-documents/wallet-screenshots/ios-wallet/cta-withdraw-sheet130-withdraw-confirm.png deleted file mode 100644 index 22c57d66..00000000 Binary files a/design-documents/wallet-screenshots/ios-wallet/cta-withdraw-sheet130-withdraw-confirm.png and /dev/null differ diff --git a/design-documents/wallet-screenshots/ios-wallet/cta-withdraw-sheet130-withdraw.png b/design-documents/wallet-screenshots/ios-wallet/cta-withdraw-sheet130-withdraw.png deleted file mode 100644 index 4f893fd4..00000000 Binary files a/design-documents/wallet-screenshots/ios-wallet/cta-withdraw-sheet130-withdraw.png and /dev/null differ diff --git a/design-documents/wallet-screenshots/ios-wallet/cta-withdraw-sheet131-tos.png b/design-documents/wallet-screenshots/ios-wallet/cta-withdraw-sheet131-tos.png deleted file mode 100644 index 1aafc03e..00000000 Binary files a/design-documents/wallet-screenshots/ios-wallet/cta-withdraw-sheet131-tos.png and /dev/null differ diff --git a/design-documents/wallet-screenshots/ios-wallet/cta-withdraw-sheet133-withdraw-confirm-bank.png b/design-documents/wallet-screenshots/ios-wallet/cta-withdraw-sheet133-withdraw-confirm-bank.png deleted file mode 100644 index 94ad63b1..00000000 Binary files a/design-documents/wallet-screenshots/ios-wallet/cta-withdraw-sheet133-withdraw-confirm-bank.png and /dev/null differ diff --git a/design-documents/wallet-screenshots/ios-wallet/cta-withdraw-view10-empty-wallet.png b/design-documents/wallet-screenshots/ios-wallet/cta-withdraw-view10-empty-wallet.png deleted file mode 100644 index a6737b9f..00000000 Binary files a/design-documents/wallet-screenshots/ios-wallet/cta-withdraw-view10-empty-wallet.png and /dev/null differ diff --git a/design-documents/wallet-screenshots/ios-wallet/cta-withdraw-view22-balances.png b/design-documents/wallet-screenshots/ios-wallet/cta-withdraw-view22-balances.png deleted file mode 100644 index bd83cb8f..00000000 Binary files a/design-documents/wallet-screenshots/ios-wallet/cta-withdraw-view22-balances.png and /dev/null differ diff --git a/design-documents/wallet-screenshots/ios-wallet/withdraw-bankIntegrated/CHF/cta-withdraw-sheet130-withdraw-confirm.png b/design-documents/wallet-screenshots/ios-wallet/withdraw-bankIntegrated/CHF/cta-withdraw-sheet130-withdraw-confirm.png new file mode 100644 index 00000000..11dd9db0 Binary files /dev/null and b/design-documents/wallet-screenshots/ios-wallet/withdraw-bankIntegrated/CHF/cta-withdraw-sheet130-withdraw-confirm.png differ diff --git a/design-documents/wallet-screenshots/ios-wallet/withdraw-bankIntegrated/CHF/cta-withdraw-sheet130-withdraw.png b/design-documents/wallet-screenshots/ios-wallet/withdraw-bankIntegrated/CHF/cta-withdraw-sheet130-withdraw.png new file mode 100644 index 00000000..d46f0e5c Binary files /dev/null and b/design-documents/wallet-screenshots/ios-wallet/withdraw-bankIntegrated/CHF/cta-withdraw-sheet130-withdraw.png differ diff --git a/design-documents/wallet-screenshots/ios-wallet/withdraw-bankIntegrated/CHF/cta-withdraw-sheet133-withdraw-confirm-bank.png b/design-documents/wallet-screenshots/ios-wallet/withdraw-bankIntegrated/CHF/cta-withdraw-sheet133-withdraw-confirm-bank.png new file mode 100644 index 00000000..5d7dd8cd Binary files /dev/null and b/design-documents/wallet-screenshots/ios-wallet/withdraw-bankIntegrated/CHF/cta-withdraw-sheet133-withdraw-confirm-bank.png differ diff --git a/design-documents/wallet-screenshots/ios-wallet/withdraw-bankIntegrated/CHF/cta-withdraw-view22-balances.png b/design-documents/wallet-screenshots/ios-wallet/withdraw-bankIntegrated/CHF/cta-withdraw-view22-balances.png new file mode 100644 index 00000000..473621e8 Binary files /dev/null and b/design-documents/wallet-screenshots/ios-wallet/withdraw-bankIntegrated/CHF/cta-withdraw-view22-balances.png differ diff --git a/design-documents/wallet-screenshots/ios-wallet/withdraw-bankIntegrated/cta-withdraw-bank-confirm.png b/design-documents/wallet-screenshots/ios-wallet/withdraw-bankIntegrated/cta-withdraw-bank-confirm.png new file mode 100644 index 00000000..4441777a Binary files /dev/null and b/design-documents/wallet-screenshots/ios-wallet/withdraw-bankIntegrated/cta-withdraw-bank-confirm.png differ diff --git a/design-documents/wallet-screenshots/ios-wallet/withdraw-bankIntegrated/cta-withdraw-bank-confirmed.png b/design-documents/wallet-screenshots/ios-wallet/withdraw-bankIntegrated/cta-withdraw-bank-confirmed.png new file mode 100644 index 00000000..c356eb13 Binary files /dev/null and b/design-documents/wallet-screenshots/ios-wallet/withdraw-bankIntegrated/cta-withdraw-bank-confirmed.png differ diff --git a/design-documents/wallet-screenshots/ios-wallet/withdraw-bankIntegrated/cta-withdraw-bank-register.png b/design-documents/wallet-screenshots/ios-wallet/withdraw-bankIntegrated/cta-withdraw-bank-register.png new file mode 100644 index 00000000..e7b7c1f9 Binary files /dev/null and b/design-documents/wallet-screenshots/ios-wallet/withdraw-bankIntegrated/cta-withdraw-bank-register.png differ diff --git a/design-documents/wallet-screenshots/ios-wallet/withdraw-bankIntegrated/cta-withdraw-bank-send-money.png b/design-documents/wallet-screenshots/ios-wallet/withdraw-bankIntegrated/cta-withdraw-bank-send-money.png new file mode 100644 index 00000000..788ae7ab Binary files /dev/null and b/design-documents/wallet-screenshots/ios-wallet/withdraw-bankIntegrated/cta-withdraw-bank-send-money.png differ diff --git a/design-documents/wallet-screenshots/ios-wallet/withdraw-bankIntegrated/cta-withdraw-bank-withdraw.png b/design-documents/wallet-screenshots/ios-wallet/withdraw-bankIntegrated/cta-withdraw-bank-withdraw.png new file mode 100644 index 00000000..74e1efff Binary files /dev/null and b/design-documents/wallet-screenshots/ios-wallet/withdraw-bankIntegrated/cta-withdraw-bank-withdraw.png differ diff --git a/design-documents/wallet-screenshots/ios-wallet/withdraw-bankIntegrated/cta-withdraw-sheet130-withdraw-confirm.png b/design-documents/wallet-screenshots/ios-wallet/withdraw-bankIntegrated/cta-withdraw-sheet130-withdraw-confirm.png new file mode 100644 index 00000000..22c57d66 Binary files /dev/null and b/design-documents/wallet-screenshots/ios-wallet/withdraw-bankIntegrated/cta-withdraw-sheet130-withdraw-confirm.png differ diff --git a/design-documents/wallet-screenshots/ios-wallet/withdraw-bankIntegrated/cta-withdraw-sheet130-withdraw.png b/design-documents/wallet-screenshots/ios-wallet/withdraw-bankIntegrated/cta-withdraw-sheet130-withdraw.png new file mode 100644 index 00000000..4f893fd4 Binary files /dev/null and b/design-documents/wallet-screenshots/ios-wallet/withdraw-bankIntegrated/cta-withdraw-sheet130-withdraw.png differ diff --git a/design-documents/wallet-screenshots/ios-wallet/withdraw-bankIntegrated/cta-withdraw-sheet131-tos.png b/design-documents/wallet-screenshots/ios-wallet/withdraw-bankIntegrated/cta-withdraw-sheet131-tos.png new file mode 100644 index 00000000..1aafc03e Binary files /dev/null and b/design-documents/wallet-screenshots/ios-wallet/withdraw-bankIntegrated/cta-withdraw-sheet131-tos.png differ diff --git a/design-documents/wallet-screenshots/ios-wallet/withdraw-bankIntegrated/cta-withdraw-sheet133-withdraw-confirm-bank.png b/design-documents/wallet-screenshots/ios-wallet/withdraw-bankIntegrated/cta-withdraw-sheet133-withdraw-confirm-bank.png new file mode 100644 index 00000000..94ad63b1 Binary files /dev/null and b/design-documents/wallet-screenshots/ios-wallet/withdraw-bankIntegrated/cta-withdraw-sheet133-withdraw-confirm-bank.png differ diff --git a/design-documents/wallet-screenshots/ios-wallet/withdraw-bankIntegrated/cta-withdraw-view10-empty-wallet.png b/design-documents/wallet-screenshots/ios-wallet/withdraw-bankIntegrated/cta-withdraw-view10-empty-wallet.png new file mode 100644 index 00000000..a6737b9f Binary files /dev/null and b/design-documents/wallet-screenshots/ios-wallet/withdraw-bankIntegrated/cta-withdraw-view10-empty-wallet.png differ diff --git a/design-documents/wallet-screenshots/ios-wallet/withdraw-bankIntegrated/cta-withdraw-view22-balances.png b/design-documents/wallet-screenshots/ios-wallet/withdraw-bankIntegrated/cta-withdraw-view22-balances.png new file mode 100644 index 00000000..bd83cb8f Binary files /dev/null and b/design-documents/wallet-screenshots/ios-wallet/withdraw-bankIntegrated/cta-withdraw-view22-balances.png differ -- cgit v1.2.3 From 0b6e0a4e3f7331d0e026f7722a6572f4cce3aa90 Mon Sep 17 00:00:00 2001 From: Marc Stibane Date: Sun, 25 Feb 2024 15:19:07 +0100 Subject: Screenshots for iOS withdraw-exchange, with NETZBON and CHF --- .../cta-withdrawExchange-sheet-amount.png | Bin 0 -> 173529 bytes .../cta-withdrawExchange-sheet-wireTransfer-CHF-1.png | Bin 0 -> 292949 bytes .../cta-withdrawExchange-sheet-wireTransfer-CHF-2.png | Bin 0 -> 407510 bytes .../cta-withdrawExchange-sheet-wireTransfer-CHF-3.png | Bin 0 -> 331196 bytes .../cta-withdrawExchange-sheet135-amount.png | Bin 0 -> 215793 bytes .../cta-withdrawExchange-sheet135-amount2.png | Bin 0 -> 214738 bytes .../cta-withdrawExchange-sheet135-tos.png | Bin 0 -> 116707 bytes .../cta-withdrawExchange-sheet135-wireTransfer-CHF.png | Bin 0 -> 304402 bytes ...cta-withdrawExchange-sheet135-wireTransfer-CHF2.png | Bin 0 -> 420238 bytes ...cta-withdrawExchange-sheet135-wireTransfer-NETZ.png | Bin 0 -> 309949 bytes ...ta-withdrawExchange-sheet135-wireTransfer-NETZ2.png | Bin 0 -> 413992 bytes .../cta-withdrawExchange-sheet135-withdraw-tos.png | Bin 0 -> 170387 bytes 12 files changed, 0 insertions(+), 0 deletions(-) create mode 100644 design-documents/wallet-screenshots/ios-wallet/withdraw-exchange/cta-withdrawExchange-sheet-amount.png create mode 100644 design-documents/wallet-screenshots/ios-wallet/withdraw-exchange/cta-withdrawExchange-sheet-wireTransfer-CHF-1.png create mode 100644 design-documents/wallet-screenshots/ios-wallet/withdraw-exchange/cta-withdrawExchange-sheet-wireTransfer-CHF-2.png create mode 100644 design-documents/wallet-screenshots/ios-wallet/withdraw-exchange/cta-withdrawExchange-sheet-wireTransfer-CHF-3.png create mode 100644 design-documents/wallet-screenshots/ios-wallet/withdraw-exchange/cta-withdrawExchange-sheet135-amount.png create mode 100644 design-documents/wallet-screenshots/ios-wallet/withdraw-exchange/cta-withdrawExchange-sheet135-amount2.png create mode 100644 design-documents/wallet-screenshots/ios-wallet/withdraw-exchange/cta-withdrawExchange-sheet135-tos.png create mode 100644 design-documents/wallet-screenshots/ios-wallet/withdraw-exchange/cta-withdrawExchange-sheet135-wireTransfer-CHF.png create mode 100644 design-documents/wallet-screenshots/ios-wallet/withdraw-exchange/cta-withdrawExchange-sheet135-wireTransfer-CHF2.png create mode 100644 design-documents/wallet-screenshots/ios-wallet/withdraw-exchange/cta-withdrawExchange-sheet135-wireTransfer-NETZ.png create mode 100644 design-documents/wallet-screenshots/ios-wallet/withdraw-exchange/cta-withdrawExchange-sheet135-wireTransfer-NETZ2.png create mode 100644 design-documents/wallet-screenshots/ios-wallet/withdraw-exchange/cta-withdrawExchange-sheet135-withdraw-tos.png diff --git a/design-documents/wallet-screenshots/ios-wallet/withdraw-exchange/cta-withdrawExchange-sheet-amount.png b/design-documents/wallet-screenshots/ios-wallet/withdraw-exchange/cta-withdrawExchange-sheet-amount.png new file mode 100644 index 00000000..9a51cb78 Binary files /dev/null and b/design-documents/wallet-screenshots/ios-wallet/withdraw-exchange/cta-withdrawExchange-sheet-amount.png differ diff --git a/design-documents/wallet-screenshots/ios-wallet/withdraw-exchange/cta-withdrawExchange-sheet-wireTransfer-CHF-1.png b/design-documents/wallet-screenshots/ios-wallet/withdraw-exchange/cta-withdrawExchange-sheet-wireTransfer-CHF-1.png new file mode 100644 index 00000000..1d9fdbfd Binary files /dev/null and b/design-documents/wallet-screenshots/ios-wallet/withdraw-exchange/cta-withdrawExchange-sheet-wireTransfer-CHF-1.png differ diff --git a/design-documents/wallet-screenshots/ios-wallet/withdraw-exchange/cta-withdrawExchange-sheet-wireTransfer-CHF-2.png b/design-documents/wallet-screenshots/ios-wallet/withdraw-exchange/cta-withdrawExchange-sheet-wireTransfer-CHF-2.png new file mode 100644 index 00000000..3ea5b9ca Binary files /dev/null and b/design-documents/wallet-screenshots/ios-wallet/withdraw-exchange/cta-withdrawExchange-sheet-wireTransfer-CHF-2.png differ diff --git a/design-documents/wallet-screenshots/ios-wallet/withdraw-exchange/cta-withdrawExchange-sheet-wireTransfer-CHF-3.png b/design-documents/wallet-screenshots/ios-wallet/withdraw-exchange/cta-withdrawExchange-sheet-wireTransfer-CHF-3.png new file mode 100644 index 00000000..c15f9a5e Binary files /dev/null and b/design-documents/wallet-screenshots/ios-wallet/withdraw-exchange/cta-withdrawExchange-sheet-wireTransfer-CHF-3.png differ diff --git a/design-documents/wallet-screenshots/ios-wallet/withdraw-exchange/cta-withdrawExchange-sheet135-amount.png b/design-documents/wallet-screenshots/ios-wallet/withdraw-exchange/cta-withdrawExchange-sheet135-amount.png new file mode 100644 index 00000000..4db97e7c Binary files /dev/null and b/design-documents/wallet-screenshots/ios-wallet/withdraw-exchange/cta-withdrawExchange-sheet135-amount.png differ diff --git a/design-documents/wallet-screenshots/ios-wallet/withdraw-exchange/cta-withdrawExchange-sheet135-amount2.png b/design-documents/wallet-screenshots/ios-wallet/withdraw-exchange/cta-withdrawExchange-sheet135-amount2.png new file mode 100644 index 00000000..8c0d7f2a Binary files /dev/null and b/design-documents/wallet-screenshots/ios-wallet/withdraw-exchange/cta-withdrawExchange-sheet135-amount2.png differ diff --git a/design-documents/wallet-screenshots/ios-wallet/withdraw-exchange/cta-withdrawExchange-sheet135-tos.png b/design-documents/wallet-screenshots/ios-wallet/withdraw-exchange/cta-withdrawExchange-sheet135-tos.png new file mode 100644 index 00000000..b71d7dcf Binary files /dev/null and b/design-documents/wallet-screenshots/ios-wallet/withdraw-exchange/cta-withdrawExchange-sheet135-tos.png differ diff --git a/design-documents/wallet-screenshots/ios-wallet/withdraw-exchange/cta-withdrawExchange-sheet135-wireTransfer-CHF.png b/design-documents/wallet-screenshots/ios-wallet/withdraw-exchange/cta-withdrawExchange-sheet135-wireTransfer-CHF.png new file mode 100644 index 00000000..8a467161 Binary files /dev/null and b/design-documents/wallet-screenshots/ios-wallet/withdraw-exchange/cta-withdrawExchange-sheet135-wireTransfer-CHF.png differ diff --git a/design-documents/wallet-screenshots/ios-wallet/withdraw-exchange/cta-withdrawExchange-sheet135-wireTransfer-CHF2.png b/design-documents/wallet-screenshots/ios-wallet/withdraw-exchange/cta-withdrawExchange-sheet135-wireTransfer-CHF2.png new file mode 100644 index 00000000..24bb4881 Binary files /dev/null and b/design-documents/wallet-screenshots/ios-wallet/withdraw-exchange/cta-withdrawExchange-sheet135-wireTransfer-CHF2.png differ diff --git a/design-documents/wallet-screenshots/ios-wallet/withdraw-exchange/cta-withdrawExchange-sheet135-wireTransfer-NETZ.png b/design-documents/wallet-screenshots/ios-wallet/withdraw-exchange/cta-withdrawExchange-sheet135-wireTransfer-NETZ.png new file mode 100644 index 00000000..7423411a Binary files /dev/null and b/design-documents/wallet-screenshots/ios-wallet/withdraw-exchange/cta-withdrawExchange-sheet135-wireTransfer-NETZ.png differ diff --git a/design-documents/wallet-screenshots/ios-wallet/withdraw-exchange/cta-withdrawExchange-sheet135-wireTransfer-NETZ2.png b/design-documents/wallet-screenshots/ios-wallet/withdraw-exchange/cta-withdrawExchange-sheet135-wireTransfer-NETZ2.png new file mode 100644 index 00000000..80843838 Binary files /dev/null and b/design-documents/wallet-screenshots/ios-wallet/withdraw-exchange/cta-withdrawExchange-sheet135-wireTransfer-NETZ2.png differ diff --git a/design-documents/wallet-screenshots/ios-wallet/withdraw-exchange/cta-withdrawExchange-sheet135-withdraw-tos.png b/design-documents/wallet-screenshots/ios-wallet/withdraw-exchange/cta-withdrawExchange-sheet135-withdraw-tos.png new file mode 100644 index 00000000..21056f08 Binary files /dev/null and b/design-documents/wallet-screenshots/ios-wallet/withdraw-exchange/cta-withdrawExchange-sheet135-withdraw-tos.png differ -- cgit v1.2.3 From 4af379f314b87b77261044cad2b38f94aae713c8 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Sun, 25 Feb 2024 16:30:52 +0100 Subject: add screenshots --- design-documents/053-wallet-ui.rst | 77 ++++++++++++++++++++++- screenshots/cta-payment-firefox-0.png | Bin 0 -> 43899 bytes screenshots/cta-payment-firefox-latest.png | 1 + screenshots/cta-payment-paid-firefox-0.png | Bin 0 -> 36529 bytes screenshots/cta-payment-paid-firefox-latest.png | 1 + screenshots/cta-url-entry-firefox-0.png | Bin 0 -> 37619 bytes screenshots/cta-url-entry-firefox-latest.png | 1 + screenshots/cta-wire-transfer-firefox-0.png | Bin 0 -> 75735 bytes screenshots/cta-wire-transfer-firefox-latest.png | 1 + screenshots/cta-withdraw-done-firefox-0.png | Bin 0 -> 30061 bytes screenshots/cta-withdraw-done-firefox-latest.png | 1 + screenshots/cta-withdraw-firefox-0.png | Bin 0 -> 35550 bytes screenshots/cta-withdraw-firefox-latest.png | 1 + 13 files changed, 81 insertions(+), 2 deletions(-) create mode 100644 screenshots/cta-payment-firefox-0.png create mode 120000 screenshots/cta-payment-firefox-latest.png create mode 100644 screenshots/cta-payment-paid-firefox-0.png create mode 120000 screenshots/cta-payment-paid-firefox-latest.png create mode 100644 screenshots/cta-url-entry-firefox-0.png create mode 120000 screenshots/cta-url-entry-firefox-latest.png create mode 100644 screenshots/cta-wire-transfer-firefox-0.png create mode 120000 screenshots/cta-wire-transfer-firefox-latest.png create mode 100644 screenshots/cta-withdraw-done-firefox-0.png create mode 120000 screenshots/cta-withdraw-done-firefox-latest.png create mode 100644 screenshots/cta-withdraw-firefox-0.png create mode 120000 screenshots/cta-withdraw-firefox-latest.png diff --git a/design-documents/053-wallet-ui.rst b/design-documents/053-wallet-ui.rst index 5b5ba22d..5c3ccb9e 100644 --- a/design-documents/053-wallet-ui.rst +++ b/design-documents/053-wallet-ui.rst @@ -70,7 +70,7 @@ Common definition: Proposed Solutions ================== -List of dall screens with the defined properties +List of all screens with the defined properties. cta-withdraw ------------ @@ -98,8 +98,62 @@ fee, restrictions and ETA should be clear for the user. .. attention:: User should be able to play with the amount, not possible in the current design +cta-wire-transfer +----------------- + +``Description``: this screen is used to show the user the information for +the wire transfer to complete a manual withdrawal operation. + +``Info``: + * wire transfer subject to be used (first, most important) + * target bank account to transfer funds to (e.g. IBAN) + * total amount to transfer in the wire transfer currency + * button to copy ``payto://`` URI with the information to clipboard + +``Actions``: + * abort: aborts the withdrawal operation + * menu: go back to the main balances list (operation continues in background) + * automatic: screen changes to "cta-withdraw-done" upon completion + +cta-withdraw-done +----------------- + +``Description``: this screen is used to show the user the information for +a completed withdraw operation (bank-integrated or manual) + +``Info``: + * amount wired (hidden if no fees) + * fees paid (hidden if no fees) + * total amount withdrawn into wallet (effective balance change) + * exchange base URL + * date + +``Actions``: + * delete: deletes information about the withdrawal operation + + +cta-url-entry +------------- + +``Description``: this screen allows the user to scan a QR code, scan an NFC +tag, or enter a taler://-URL. Its implementation may differ significantly +between platforms. For example, scanning NFC tags may be fully automated, +scanning QR codes may involve some system applications, and maybe the dialog +only allows the URL entry *or* the camera but not both at the same time, +depending on implementation specifics. + +``Info``: + * camera with current image to enable user to focus on QR code + * current URL, with information if it is not well-formed for GNU Taler + * possibly status information on NFC reader (if available) + +``Actions``: + * open: if entered manually, open URL as-entered (otherwise open is automatic) + * back: return to previous view + + cta-payment ------------- +----------- ``Description``: this screen is used for the confirmation of a payment to a merchant. the success of this operation will be an decrease of the balance in the wallet @@ -121,6 +175,25 @@ fee, restrictions and ETA should be clear for the user. * get more cash: if there is not enough balance, it will be redirected to ``cta-witddraw`` * cancel: user will be redirected to ``balance`` + +cta-payment-paid +---------------- + +``Description``: this screen is used to show information with details +about a historic payment. + +``Info``: + * merchant offering the order showing the URL + * order summary + * table of details of the operation: use the ``operation-table-details`` screen + * receipt: order id + * payment status: if the order was refunded + +``Actions``: + * delete: delete information about the transaction + * back: user will be redirected to ``balance`` + + cta-deposit ------------ diff --git a/screenshots/cta-payment-firefox-0.png b/screenshots/cta-payment-firefox-0.png new file mode 100644 index 00000000..c9d01380 Binary files /dev/null and b/screenshots/cta-payment-firefox-0.png differ diff --git a/screenshots/cta-payment-firefox-latest.png b/screenshots/cta-payment-firefox-latest.png new file mode 120000 index 00000000..26b0f16e --- /dev/null +++ b/screenshots/cta-payment-firefox-latest.png @@ -0,0 +1 @@ +cta-payment-firefox-0.png \ No newline at end of file diff --git a/screenshots/cta-payment-paid-firefox-0.png b/screenshots/cta-payment-paid-firefox-0.png new file mode 100644 index 00000000..f67e2af3 Binary files /dev/null and b/screenshots/cta-payment-paid-firefox-0.png differ diff --git a/screenshots/cta-payment-paid-firefox-latest.png b/screenshots/cta-payment-paid-firefox-latest.png new file mode 120000 index 00000000..22dd4530 --- /dev/null +++ b/screenshots/cta-payment-paid-firefox-latest.png @@ -0,0 +1 @@ +cta-payment-paid-firefox-0.png \ No newline at end of file diff --git a/screenshots/cta-url-entry-firefox-0.png b/screenshots/cta-url-entry-firefox-0.png new file mode 100644 index 00000000..ba98a8e4 Binary files /dev/null and b/screenshots/cta-url-entry-firefox-0.png differ diff --git a/screenshots/cta-url-entry-firefox-latest.png b/screenshots/cta-url-entry-firefox-latest.png new file mode 120000 index 00000000..f24b6cb8 --- /dev/null +++ b/screenshots/cta-url-entry-firefox-latest.png @@ -0,0 +1 @@ +cta-url-entry-firefox-0.png \ No newline at end of file diff --git a/screenshots/cta-wire-transfer-firefox-0.png b/screenshots/cta-wire-transfer-firefox-0.png new file mode 100644 index 00000000..7301cedc Binary files /dev/null and b/screenshots/cta-wire-transfer-firefox-0.png differ diff --git a/screenshots/cta-wire-transfer-firefox-latest.png b/screenshots/cta-wire-transfer-firefox-latest.png new file mode 120000 index 00000000..202edda1 --- /dev/null +++ b/screenshots/cta-wire-transfer-firefox-latest.png @@ -0,0 +1 @@ +cta-wire-transfer-firefox-0.png \ No newline at end of file diff --git a/screenshots/cta-withdraw-done-firefox-0.png b/screenshots/cta-withdraw-done-firefox-0.png new file mode 100644 index 00000000..3a3fc2f6 Binary files /dev/null and b/screenshots/cta-withdraw-done-firefox-0.png differ diff --git a/screenshots/cta-withdraw-done-firefox-latest.png b/screenshots/cta-withdraw-done-firefox-latest.png new file mode 120000 index 00000000..f707ff77 --- /dev/null +++ b/screenshots/cta-withdraw-done-firefox-latest.png @@ -0,0 +1 @@ +cta-withdraw-done-firefox-0.png \ No newline at end of file diff --git a/screenshots/cta-withdraw-firefox-0.png b/screenshots/cta-withdraw-firefox-0.png new file mode 100644 index 00000000..e75fb875 Binary files /dev/null and b/screenshots/cta-withdraw-firefox-0.png differ diff --git a/screenshots/cta-withdraw-firefox-latest.png b/screenshots/cta-withdraw-firefox-latest.png new file mode 120000 index 00000000..4ed704c3 --- /dev/null +++ b/screenshots/cta-withdraw-firefox-latest.png @@ -0,0 +1 @@ +cta-withdraw-firefox-0.png \ No newline at end of file -- cgit v1.2.3 From febcda22bd04089cf486238195f45e26ea1288d9 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Sun, 25 Feb 2024 16:42:24 +0100 Subject: tos --- screenshots/cta-accept-tos-firefox-0.png | Bin 0 -> 105184 bytes screenshots/cta-accept-tos-firefox-latest.png | 1 + 2 files changed, 1 insertion(+) create mode 100644 screenshots/cta-accept-tos-firefox-0.png create mode 120000 screenshots/cta-accept-tos-firefox-latest.png diff --git a/screenshots/cta-accept-tos-firefox-0.png b/screenshots/cta-accept-tos-firefox-0.png new file mode 100644 index 00000000..6809d775 Binary files /dev/null and b/screenshots/cta-accept-tos-firefox-0.png differ diff --git a/screenshots/cta-accept-tos-firefox-latest.png b/screenshots/cta-accept-tos-firefox-latest.png new file mode 120000 index 00000000..f1b6f069 --- /dev/null +++ b/screenshots/cta-accept-tos-firefox-latest.png @@ -0,0 +1 @@ +cta-accept-tos-firefox-0.png \ No newline at end of file -- cgit v1.2.3 From 7454c419dba44ce25165ca372856f4d37e7c06df Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Sun, 25 Feb 2024 17:01:16 +0100 Subject: add image links to DD53 --- design-documents/053-wallet-ui.rst | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/design-documents/053-wallet-ui.rst b/design-documents/053-wallet-ui.rst index 5c3ccb9e..c36d4759 100644 --- a/design-documents/053-wallet-ui.rst +++ b/design-documents/053-wallet-ui.rst @@ -115,6 +115,8 @@ the wire transfer to complete a manual withdrawal operation. * menu: go back to the main balances list (operation continues in background) * automatic: screen changes to "cta-withdraw-done" upon completion +.. image:: ../screenshots/cta-wire-transfer-firefox-latest.png + cta-withdraw-done ----------------- @@ -131,6 +133,8 @@ a completed withdraw operation (bank-integrated or manual) ``Actions``: * delete: deletes information about the withdrawal operation +.. image:: ../screenshots/cta-withdraw-done-firefox-latest.png + cta-url-entry ------------- @@ -151,6 +155,8 @@ depending on implementation specifics. * open: if entered manually, open URL as-entered (otherwise open is automatic) * back: return to previous view +.. image:: ../screenshots/cta-url-entry-firefox-latest.png + cta-payment ----------- @@ -175,6 +181,7 @@ fee, restrictions and ETA should be clear for the user. * get more cash: if there is not enough balance, it will be redirected to ``cta-witddraw`` * cancel: user will be redirected to ``balance`` +.. image:: ../screenshots/cta-payment-firefox-latest.png cta-payment-paid ---------------- @@ -193,6 +200,7 @@ about a historic payment. * delete: delete information about the transaction * back: user will be redirected to ``balance`` +.. image:: ../screenshots/cta-payment-paid-firefox-latest.png cta-deposit ------------ @@ -213,6 +221,7 @@ fee, restrictions and ETA should be clear for the user. .. attention:: User should be able to play with the amount, not possible in the current design + cta-peer-pull-initiate ---------------------- @@ -339,5 +348,8 @@ user already accepted ToS) * accept tos: will mark this version as accepted in wallet core and redirect the user to the screen from where it was invoked * save/print tos: will save the ToS outside of the wallet +.. image:: ../screenshots/cta-accept-tos-firefox-latest.png + + Q / A ===== -- cgit v1.2.3 From 383931f2abff7e3f6260d697bd79739e64bb1428 Mon Sep 17 00:00:00 2001 From: Javier Sepulveda Date: Mon, 26 Feb 2024 11:23:17 +0100 Subject: Advise about default enabled firewall programs such as UFW --- libeufin/regional-automated-manual.rst | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/libeufin/regional-automated-manual.rst b/libeufin/regional-automated-manual.rst index b16c11f8..ad821a1e 100644 --- a/libeufin/regional-automated-manual.rst +++ b/libeufin/regional-automated-manual.rst @@ -65,6 +65,9 @@ You can check this from your terminal very easily with the "ping" command, as th You can also use `this tool `_ for the same purpose, and to check the propagation status. +.. warning:: + Take into account some hosting providers providing virtualized servers (VPS or VDS), can enable by default the firewall program "UFW", blocking by default the port number 443. So you have to either disable this firewall program, or open to this 443 port number to allow https. + Now you are ready to go with the next step. Obtaining the Scripts @@ -258,4 +261,4 @@ outgoing bank transactions ` (cash out). # systemctl enable --now libeufin-nexus.target -.. include:: ../frags/regional-manual-use.rst \ No newline at end of file +.. include:: ../frags/regional-manual-use.rst -- cgit v1.2.3 From 2e03711ac40e37daf7365b7eaff5be8283ab1313 Mon Sep 17 00:00:00 2001 From: Antoine A <> Date: Mon, 26 Feb 2024 15:59:31 +0100 Subject: Update corebank API --- core/api-corebank.rst | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/core/api-corebank.rst b/core/api-corebank.rst index 68f47fc7..fa137a22 100644 --- a/core/api-corebank.rst +++ b/core/api-corebank.rst @@ -382,6 +382,10 @@ Account Management // Is this a taler exchange account? is_taler_exchange: boolean; + + // Opaque unique ID used for pagination. + // @since v4, will become mandatory in the future. + row_id?: Integer; } .. http:get:: /accounts @@ -451,6 +455,10 @@ Account Management // Is this a taler exchange account? is_taler_exchange: boolean; + + // Opaque unique ID used for pagination. + // @since v4, will become mandatory in the future. + row_id?: Integer; } .. _bank-account-info: -- cgit v1.2.3 From 6b67d45815fc08da537331ec58b20cbe6abe7318 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Mon, 26 Feb 2024 21:35:47 +0100 Subject: fix #8260 --- core/api-merchant.rst | 29 +++++++++++++++++++++-------- 1 file changed, 21 insertions(+), 8 deletions(-) diff --git a/core/api-merchant.rst b/core/api-merchant.rst index 7cd0f0dd..d3044505 100644 --- a/core/api-merchant.rst +++ b/core/api-merchant.rst @@ -1983,14 +1983,14 @@ Creating orders // Short summary of the order. summary: string; - // See documentation of fulfillment_url in ContractTerms. + // See documentation of fulfillment_url in `ContractTerms`. // Either fulfillment_url or fulfillment_message must be specified. // When creating an order, the fulfillment URL can // contain ``${ORDER_ID}`` which will be substituted with the // order ID of the newly created order. fulfillment_url?: string; - // See documentation of fulfillment_message in ContractTerms. + // See documentation of fulfillment_message in `ContractTerms`. // Either fulfillment_url or fulfillment_message must be specified. fulfillment_message?: string; } @@ -3256,13 +3256,26 @@ The contract terms must have the following structure: public_reorder_url?: string; // URL that will show that the order was successful after - // it has been paid for. Optional. When POSTing to the - // merchant, the placeholder "${ORDER_ID}" will be - // replaced with the actual order ID (useful if the + // it has been paid for. Optional, but either ``fulfillment_url`` + // or ``fulfillment_message`` must be specified in every + // contract terms. + // + // If a non-unique fulfillment URL is used, a customer can only + // buy the order once and will be redirected to a previous purchase + // when trying to buy an order with the same fulfillment URL a second + // time. This is useful for digital goods that a customer only needs + // to buy once but should be able to repeatedly download. + // + // For orders where the customer is expected to be able to make + // repeated purchases (for equivalent goods), the fulfillment URL + // should be made unique for every order. The easiest way to do + // this is to include a unique order ID in the fulfillment URL. + // + // When POSTing to the merchant, the placeholder text "${ORDER_ID}" + // is be replaced with the actual order ID (useful if the // order ID is generated server-side and needs to be - // in the URL). - // Note that this placeholder can only be used once. - // Either fulfillment_url or fulfillment_message must be specified. + // in the URL). Note that this placeholder can only be used once. + // Front-ends may use other means to generate a unique fulfillment URL. fulfillment_url?: string; // Message shown to the customer after paying for the order. -- cgit v1.2.3 From 4ebc8a8d83d06ff623484c85de9cb9a91b540e2b Mon Sep 17 00:00:00 2001 From: Antoine A <> Date: Wed, 28 Feb 2024 10:54:20 +0100 Subject: Improve 2FA documentation --- libeufin/bank-manual.rst | 2 +- libeufin/regional-automated-manual.rst | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/libeufin/bank-manual.rst b/libeufin/bank-manual.rst index 4b00635a..ab793b2b 100644 --- a/libeufin/bank-manual.rst +++ b/libeufin/bank-manual.rst @@ -109,7 +109,7 @@ 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 `_ provider. It requires an additional ``AUTH_TOKEN`` environment variable for the `Telesign API `_. +The default ``libeufin-tan-sms.sh`` script is based on the `Telesign `_ SMS provider. It requires an additional ``AUTH_TOKEN`` environment variable for `Telesign Basic authentication `_. To test your setup run: diff --git a/libeufin/regional-automated-manual.rst b/libeufin/regional-automated-manual.rst index ad821a1e..596fb12e 100644 --- a/libeufin/regional-automated-manual.rst +++ b/libeufin/regional-automated-manual.rst @@ -98,8 +98,8 @@ The script will start by installing required packages and then asking you fundam #. The DNS domain name of your setup (i.e: domain.tld). The installer will create by itself all the needed subdomains for your domain name, as (``bank.$DOMAIN``, ``exchange.$DOMAIN`` and ``backend.$DOMAIN``). But, these subdomain names as explained before, must have been added beforehand to your DNS domain control panel, and they must be pointing to the IP address of the server on which you are running the installation (before you execute the installer). #. Whether to use TLS or not. You should answer ``y`` in most cases. #. Whether to store Taler Exchange keys on this server or externally on another server. Unless you need a high-security setup and expect to run an offline key management process, say ``y``. If you say ``n``, you will need to run ``taler-exchange-offline setup`` on your offline system and provide the master public key. Furthermore, you should then study the exchange manual on offline key management to finish the exchange setup process later. -#. Whether to setup sms two-factor authentication using Telesign. You should answer ``y`` in most cases. -#. The admin password for the bank. Be absolutely sure to enter a very, very long and high-entropy password, preferably use the autogenerated one. +#. Whether to setup SMS two-factor authentication using `Telesign `_, multi-factor authentication is strongly recommended, especially when regional currency can be converted to fiat currency. This requires `a Customer ID and an API Key `_. You should answer ``y`` in most cases. +#. The admin password for the bank. Be absolutely sure to enter a very, very long and high-entropy password, preferably using the autogenerated one. The information you entered as well as the generated bank admin password will be stored in a file called ``config/user.conf``. If you run the script in -- cgit v1.2.3 From 1368ea38aecc9e1982be0c4a9344f5542770f15f Mon Sep 17 00:00:00 2001 From: Florian Dold Date: Wed, 28 Feb 2024 11:22:05 +0100 Subject: first shot at qa checklist --- checklist-demo-upgrade.rst | 173 ---------------------------------- checklist-release.rst | 141 --------------------------- checklists/checklist-demo-upgrade.rst | 173 ++++++++++++++++++++++++++++++++++ checklists/checklist-release.rst | 141 +++++++++++++++++++++++++++ checklists/qa-0.9.4.rst | 161 +++++++++++++++++++++++++++++++ taler-developer-manual.rst | 6 +- 6 files changed, 478 insertions(+), 317 deletions(-) delete mode 100644 checklist-demo-upgrade.rst delete mode 100644 checklist-release.rst create mode 100644 checklists/checklist-demo-upgrade.rst create mode 100644 checklists/checklist-release.rst create mode 100644 checklists/qa-0.9.4.rst diff --git a/checklist-demo-upgrade.rst b/checklist-demo-upgrade.rst deleted file mode 100644 index d8724030..00000000 --- a/checklist-demo-upgrade.rst +++ /dev/null @@ -1,173 +0,0 @@ -GNU Taler Demo Upgrade Checklist --------------------------------- - -.. |democheck| raw:: html - - - - -Domains -^^^^^^^ - -The checklist uses the ``demo.taler.net`` domains. However, -the same sandcastle demo can also be hosted at other domains. -The same instructions should apply. - -Post-upgrade checks -^^^^^^^^^^^^^^^^^^^ - -- |democheck| Run the headless wallet to check that services are actually working: - - .. code-block:: console - - taler-wallet-cli api 'runIntegrationTestV2' '{"exchangeBaseUrl":"https://exchange.demo.taler.net", "corebankApiBaseUrl": "https://bank.demo.taler.net", "merchantBaseUrl": "https://backend.demo.taler.net", "merchantAuthToken":"secret-token:sandbox"}' - - -Wallets -^^^^^^^ - -We consider the following published wallets to be "production wallets": - -* Browser: Firefox Add-On Store -* Browser: Chrome Web Store -* Android: Google Play -* Android: F-Droid -* iOS: Apple Store / Testflight - -Basics -^^^^^^ - -- |democheck| Visit https://demo.taler.net/ to see if the landing page is displayed correctly -- |democheck| landing language switcher -- |democheck| Visit the wallet installation page, install the wallet -- |democheck| see if the wallet presence indicator is updated correctly (in browsers). -- |democheck| Visit https://bank.demo.taler.net/, register a new user -- |democheck| bank language switcher -- |democheck| bank logout -- |democheck| bank login -- |democheck| bank-integrated withdraw process, abort in bank -- |democheck| transaction history: delete pending withdraw -- |democheck| do bank-integrated withdraw process (5 KUDOS) -- |democheck| do wallet-initiated withdraw process (5 KUDOS) -- |democheck| withdraw process of large amount (20 KUDOS) runs into KYC check -- |democheck| fail KYC check (if possible for the given setup) -- |democheck| pass KYC check (tests that 2nd attempt is possible) -- |democheck| withdraw process of very large amount (50 KUDOS) runs into AML check -- |democheck| visit exchange SPA, create AML officer key -- |democheck| register AML officer key with offline tool (if possible) -- |democheck| allow withdraw process blocked on AML to proceed (if possible) - - -Exchange AML SPA -^^^^^^^^^^^^^^^^ - -- |democheck| enter non-trivial form, change status to frozen -- |democheck| check account status in history is now frozen and shows in that category -- |democheck| enter another form, change status to normal, increase AML threshold -- |democheck| view forms in history, view previously submitted form -- |democheck| check account status in history is now normal and shows in that category -- |democheck| log out -- |democheck| check log in succeeds with correct password -- |democheck| check log in fails from different browser with same password - - -Blog demo -^^^^^^^^^ - -- |democheck| Visit https://shop.demo.taler.net/ -- |democheck| blog page article list renders -- |democheck| payment for blog article -- |democheck| Verify that the balance in the wallet was updated correctly. -- |democheck| Go back to https://shop.demo.taler.net/ and click on the same article - link. Verify that the article is shown and **no** repeated payment is - requested. -- |democheck| Open the fulfillment page from the previous step in an anonymous browsing session - (without the wallet installed) and verify that it requests a payment again. -- |democheck| Delete cookies on https://shop.demo.taler.net/ and click on the same article again. - Verify that the wallet detects that the article has already purchased and successfully - redirects to the article without spending more money. -- |democheck| payment for other blog article -- |democheck| refund of 2nd blog article (button at the end) -- |democheck| wallet transaction history rendering -- |democheck| delete refund history entry; check original purchase entry was also deleted -- |democheck| payment for other blog article -- |democheck| refund of 3rd blog article (button at the end) -- |democheck| wallet transaction history rendering -- |democheck| delete 3rd block purchase history entry; check refund entry was also deleted - - -Donation demo -^^^^^^^^^^^^^ - -- |democheck| Reset wallet -- |democheck| Withdraw age-restricted coins (< 14) -- |democheck| Try to make a donation on https://donations.demo.taler.net/, fail due to age-restriction -- |democheck| Withdraw age-restricted coins (>= 14) -- |democheck| Make a donation on https://donations.demo.taler.net/ -- |democheck| Make another donation with the same parameters and verify - that the payment is requested again, instead of showing the previous - fulfillment page. - - -Merchant SPA -^^^^^^^^^^^^ - -- |democheck| test SPA loads -- |democheck| try to login with wrong password -- |democheck| try to login with correct password -- |democheck| create instance, check default is set to cover (STEFAN) fees -- |democheck| modify instance -- |democheck| add bank account -- |democheck| edit bank account -- |democheck| remove bank account -- |democheck| check order creation fails without bank account -- |democheck| add bank account again -- |democheck| add product with 1 in stock and preview image -- |democheck| add "advanced" order with inventory product and a 2 minute wire delay -- |democheck| claim order, check available stock goes down in inventory -- |democheck| create 2nd order, check this fails due to missing inventory -- |democheck| pay for 1st order with wallet -- |democheck| check transaction history for preview image -- |democheck| trigger partial refund -- |democheck| accept refund with wallet -- |democheck| create template with fixed summary, default editable price -- |democheck| scan template QR code, edit price and pay -- |democheck| add TOTP device (using some TOTP app to share secret with) -- |democheck| edit template to add TOTP device, set price to fixed, summary to be entered -- |democheck| scan template QR code, edit summary and pay -- |democheck| check displayed TOTP code matches TOTP app -- |democheck| do manual wire transfer in bank to establish reserve funding -- |democheck| check that partially refunded order is marked as awaiting wire transfer -- |democheck| check bank wired funds to merchant (if needed, wait) -- |democheck| add bank wire transfer manually to backend -- |democheck| change settings for merchant to not pay for (STEFAN) fees -- |democheck| create and pay for another order with 1 minute wire transfer delay -- |democheck| edit bank account details, adding revenue facade with credentials -- |democheck| wait and check if wire transfer is automatically imported -- |democheck| check that orders are marked as completed - - -P2P payments -^^^^^^^^^^^^ - -- |democheck| generating push payment (to self is OK) -- |democheck| accepting push payment (from self is OK) -- |democheck| generating pull payment (to self is OK) -- |democheck| accepting pull payment (from self is OK) -- |democheck| sending money back from wallet to bank account -- |democheck| wallet transaction history rendering -- |democheck| delete history entry - - -Shutdown -^^^^^^^^ - -- |democheck| create two full wallets, fill one only via (a large) P2P transfer -- |democheck| revoke highest-value denomination -- |democheck| spend money in a wallet such that the balance falls below highest denomination value -- |democheck| revoke all remaining denominations -- |democheck| fail to spend any more money -- |democheck| if wallet was filled via p2p payments, wallet asks for target deposit account (exchange going out of business) -- |democheck| enter bank account (if possible) -- |democheck| wallet balance goes to zero -- |democheck| specified bank account receives remaining balance diff --git a/checklist-release.rst b/checklist-release.rst deleted file mode 100644 index a51c165d..00000000 --- a/checklist-release.rst +++ /dev/null @@ -1,141 +0,0 @@ -GNU Taler Release Checklist ---------------------------- - -.. |releasecheck| raw:: html - - - -For exchange: - -- |releasecheck| no compiler warnings at "-Wall" with gcc -- |releasecheck| no compiler warnings at "-Wall" with clang -- |releasecheck| ensure Coverity static analysis passes -- |releasecheck| make check. -- |releasecheck| make dist, make check on result of 'make dist'. -- |releasecheck| Change version number in configure.ac. -- |releasecheck| update man pages / info page documentation (prebuilt branch) -- |releasecheck| make dist for release -- |releasecheck| verify dist builds from source -- |releasecheck| upgrade 'demo.taler.net' -- |releasecheck| run :doc:`demo upgrade checklist ` -- |releasecheck| tag repo. -- |releasecheck| use 'deployment.git/packaging/\*-docker/' to build Debian and Ubuntu packages -- |releasecheck| upload packages to 'deb.taler.net' (note: only Florian/Christian can sign) -- |releasecheck| change 'demo.taler.net' deployment to use new tag. -- |releasecheck| Upload triplet to ftp-upload.gnu.org/incoming/ftp or /incoming/alpha - -For merchant (C backend): - -- |releasecheck| no compiler warnings at "-Wall" with gcc -- |releasecheck| no compiler warnings at "-Wall" with clang -- |releasecheck| ensure Coverity static analysis passes -- |releasecheck| make check. -- |releasecheck| make dist, make check on result of 'make dist'. -- |releasecheck| update SPA (prebuilt branch) -- |releasecheck| Change version number in configure.ac. -- |releasecheck| make dist for release. -- |releasecheck| verify dist builds from source -- |releasecheck| upgrade 'demo.taler.net' -- |releasecheck| run :doc:`demo upgrade checklist ` -- |releasecheck| tag repo. -- |releasecheck| use 'deployment.git/packaging/\*-docker/' to build Debian and Ubuntu packages -- |releasecheck| upload packages to 'deb.taler.net' (note: only Florian/Christian can sign) -- |releasecheck| change 'demo.taler.net' deployment to use new tag. -- |releasecheck| Upload triplet to ftp-upload.gnu.org/incoming/ftp or /incoming/alpha - -For sync: - -- |releasecheck| no compiler warnings at "-Wall" with gcc -- |releasecheck| no compiler warnings at "-Wall" with clang -- |releasecheck| ensure Coverity static analysis passes -- |releasecheck| make check. -- |releasecheck| make dist, make check on result of 'make dist'. -- |releasecheck| Change version number in configure.ac. -- |releasecheck| make dist for release -- |releasecheck| verify dist builds from source -- |releasecheck| upgrade 'demo.taler.net' -- |releasecheck| run :doc:`demo upgrade checklist ` -- |releasecheck| tag repo. -- |releasecheck| use 'deployment.git/packaging/\*-docker/' to build Debian and Ubuntu packages -- |releasecheck| upload packages to 'deb.taler.net' (note: only Florian/Christian can sign) -- |releasecheck| change 'demo.taler.net' deployment to use new tag. -- |releasecheck| Upload triplet to ftp-upload.gnu.org/incoming/ftp or /incoming/alpha - -For taler-mdb: - -- |releasecheck| no compiler warnings at "-Wall" with gcc -- |releasecheck| ensure Coverity static analysis passes -- |releasecheck| Change version number in configure.ac. -- |releasecheck| make dist for release. -- |releasecheck| tag repo. -- |releasecheck| use 'deployment.git/packaging/\*-docker/' to build Debian and Ubuntu packages -- |releasecheck| upload packages to 'deb.taler.net' (note: only Florian/Christian can sign) -- |releasecheck| Upload triplet to ftp-upload.gnu.org/incoming/ftp or /incoming/alpha - -For taler-twister: - -- |releasecheck| no compiler warnings at "-Wall" with gcc -- |releasecheck| no compiler warnings at "-Wall" with clang -- |releasecheck| ensure Coverity static analysis passes -- |releasecheck| make check. -- |releasecheck| make dist, make check on result of 'make dist'. -- |releasecheck| Change version number in configure.ac. -- |releasecheck| make dist for release. -- |releasecheck| verify dist builds from source -- |releasecheck| upgrade 'demo.taler.net' -- |releasecheck| run :doc:`demo upgrade checklist ` -- |releasecheck| tag repo. -- |releasecheck| Upload triplet to ftp-upload.gnu.org/incoming/ftp or /incoming/alpha - -For libeufin: - -- |releasecheck| update SPA of bank -- |releasecheck| build libeufin -- |releasecheck| upgrade 'demo.taler.net' -- |releasecheck| run :doc:`demo upgrade checklist ` -- |releasecheck| make dist for release. -- |releasecheck| verify dist builds from source -- |releasecheck| tag repo. -- |releasecheck| use 'deployment.git/packaging/\*-docker/' to build Debian and Ubuntu packages -- |releasecheck| upload packages to 'deb.taler.net' (note: only Florian/Christian can sign) -- |releasecheck| change 'demo.taler.net' deployment to use new tag. -- |releasecheck| Upload triplet to ftp-upload.gnu.org/incoming/ftp or /incoming/alpha - -For Python merchant frontend: - -- |releasecheck| upgrade 'demo.taler.net' -- |releasecheck| run :doc:`demo upgrade checklist ` -- |releasecheck| change 'demo.taler.net' deployment to use new tag. - -Wallet-core: - -- |releasecheck| build wallet -- |releasecheck| run integration test -- |releasecheck| make dist for release. -- |releasecheck| verify dist builds from source -- |releasecheck| tag repo. -- |releasecheck| use 'deployment.git/packaging/\*-docker/' to build Debian and Ubuntu packages -- |releasecheck| upload packages to 'deb.taler.net' (note: only Florian/Christian can sign) -- |releasecheck| change 'demo.taler.net' deployment to use new tag. -- |releasecheck| Upload triplet to ftp-upload.gnu.org/incoming/ftp or /incoming/alpha - -Android-Wallet: - -- |releasecheck| build wallet -- |releasecheck| run :doc:`demo upgrade checklist ` -- |releasecheck| tag repo. -- |releasecheck| upload new wallet release to app store - -Webextension-Wallet: - -- |releasecheck| build wallet -- |releasecheck| run :doc:`demo upgrade checklist ` -- |releasecheck| tag repo. -- |releasecheck| upload new wallet release to app store - -Release announcement: - -- |releasecheck| Update bug tracker (mark release, resolved -> closed) -- |releasecheck| Send announcement to taler@gnu.org -- |releasecheck| Send announcement to info-gnu@gnu.org (major releases only) -- |releasecheck| Send announcement to coordinator@translationproject.org diff --git a/checklists/checklist-demo-upgrade.rst b/checklists/checklist-demo-upgrade.rst new file mode 100644 index 00000000..d8724030 --- /dev/null +++ b/checklists/checklist-demo-upgrade.rst @@ -0,0 +1,173 @@ +GNU Taler Demo Upgrade Checklist +-------------------------------- + +.. |democheck| raw:: html + + + + +Domains +^^^^^^^ + +The checklist uses the ``demo.taler.net`` domains. However, +the same sandcastle demo can also be hosted at other domains. +The same instructions should apply. + +Post-upgrade checks +^^^^^^^^^^^^^^^^^^^ + +- |democheck| Run the headless wallet to check that services are actually working: + + .. code-block:: console + + taler-wallet-cli api 'runIntegrationTestV2' '{"exchangeBaseUrl":"https://exchange.demo.taler.net", "corebankApiBaseUrl": "https://bank.demo.taler.net", "merchantBaseUrl": "https://backend.demo.taler.net", "merchantAuthToken":"secret-token:sandbox"}' + + +Wallets +^^^^^^^ + +We consider the following published wallets to be "production wallets": + +* Browser: Firefox Add-On Store +* Browser: Chrome Web Store +* Android: Google Play +* Android: F-Droid +* iOS: Apple Store / Testflight + +Basics +^^^^^^ + +- |democheck| Visit https://demo.taler.net/ to see if the landing page is displayed correctly +- |democheck| landing language switcher +- |democheck| Visit the wallet installation page, install the wallet +- |democheck| see if the wallet presence indicator is updated correctly (in browsers). +- |democheck| Visit https://bank.demo.taler.net/, register a new user +- |democheck| bank language switcher +- |democheck| bank logout +- |democheck| bank login +- |democheck| bank-integrated withdraw process, abort in bank +- |democheck| transaction history: delete pending withdraw +- |democheck| do bank-integrated withdraw process (5 KUDOS) +- |democheck| do wallet-initiated withdraw process (5 KUDOS) +- |democheck| withdraw process of large amount (20 KUDOS) runs into KYC check +- |democheck| fail KYC check (if possible for the given setup) +- |democheck| pass KYC check (tests that 2nd attempt is possible) +- |democheck| withdraw process of very large amount (50 KUDOS) runs into AML check +- |democheck| visit exchange SPA, create AML officer key +- |democheck| register AML officer key with offline tool (if possible) +- |democheck| allow withdraw process blocked on AML to proceed (if possible) + + +Exchange AML SPA +^^^^^^^^^^^^^^^^ + +- |democheck| enter non-trivial form, change status to frozen +- |democheck| check account status in history is now frozen and shows in that category +- |democheck| enter another form, change status to normal, increase AML threshold +- |democheck| view forms in history, view previously submitted form +- |democheck| check account status in history is now normal and shows in that category +- |democheck| log out +- |democheck| check log in succeeds with correct password +- |democheck| check log in fails from different browser with same password + + +Blog demo +^^^^^^^^^ + +- |democheck| Visit https://shop.demo.taler.net/ +- |democheck| blog page article list renders +- |democheck| payment for blog article +- |democheck| Verify that the balance in the wallet was updated correctly. +- |democheck| Go back to https://shop.demo.taler.net/ and click on the same article + link. Verify that the article is shown and **no** repeated payment is + requested. +- |democheck| Open the fulfillment page from the previous step in an anonymous browsing session + (without the wallet installed) and verify that it requests a payment again. +- |democheck| Delete cookies on https://shop.demo.taler.net/ and click on the same article again. + Verify that the wallet detects that the article has already purchased and successfully + redirects to the article without spending more money. +- |democheck| payment for other blog article +- |democheck| refund of 2nd blog article (button at the end) +- |democheck| wallet transaction history rendering +- |democheck| delete refund history entry; check original purchase entry was also deleted +- |democheck| payment for other blog article +- |democheck| refund of 3rd blog article (button at the end) +- |democheck| wallet transaction history rendering +- |democheck| delete 3rd block purchase history entry; check refund entry was also deleted + + +Donation demo +^^^^^^^^^^^^^ + +- |democheck| Reset wallet +- |democheck| Withdraw age-restricted coins (< 14) +- |democheck| Try to make a donation on https://donations.demo.taler.net/, fail due to age-restriction +- |democheck| Withdraw age-restricted coins (>= 14) +- |democheck| Make a donation on https://donations.demo.taler.net/ +- |democheck| Make another donation with the same parameters and verify + that the payment is requested again, instead of showing the previous + fulfillment page. + + +Merchant SPA +^^^^^^^^^^^^ + +- |democheck| test SPA loads +- |democheck| try to login with wrong password +- |democheck| try to login with correct password +- |democheck| create instance, check default is set to cover (STEFAN) fees +- |democheck| modify instance +- |democheck| add bank account +- |democheck| edit bank account +- |democheck| remove bank account +- |democheck| check order creation fails without bank account +- |democheck| add bank account again +- |democheck| add product with 1 in stock and preview image +- |democheck| add "advanced" order with inventory product and a 2 minute wire delay +- |democheck| claim order, check available stock goes down in inventory +- |democheck| create 2nd order, check this fails due to missing inventory +- |democheck| pay for 1st order with wallet +- |democheck| check transaction history for preview image +- |democheck| trigger partial refund +- |democheck| accept refund with wallet +- |democheck| create template with fixed summary, default editable price +- |democheck| scan template QR code, edit price and pay +- |democheck| add TOTP device (using some TOTP app to share secret with) +- |democheck| edit template to add TOTP device, set price to fixed, summary to be entered +- |democheck| scan template QR code, edit summary and pay +- |democheck| check displayed TOTP code matches TOTP app +- |democheck| do manual wire transfer in bank to establish reserve funding +- |democheck| check that partially refunded order is marked as awaiting wire transfer +- |democheck| check bank wired funds to merchant (if needed, wait) +- |democheck| add bank wire transfer manually to backend +- |democheck| change settings for merchant to not pay for (STEFAN) fees +- |democheck| create and pay for another order with 1 minute wire transfer delay +- |democheck| edit bank account details, adding revenue facade with credentials +- |democheck| wait and check if wire transfer is automatically imported +- |democheck| check that orders are marked as completed + + +P2P payments +^^^^^^^^^^^^ + +- |democheck| generating push payment (to self is OK) +- |democheck| accepting push payment (from self is OK) +- |democheck| generating pull payment (to self is OK) +- |democheck| accepting pull payment (from self is OK) +- |democheck| sending money back from wallet to bank account +- |democheck| wallet transaction history rendering +- |democheck| delete history entry + + +Shutdown +^^^^^^^^ + +- |democheck| create two full wallets, fill one only via (a large) P2P transfer +- |democheck| revoke highest-value denomination +- |democheck| spend money in a wallet such that the balance falls below highest denomination value +- |democheck| revoke all remaining denominations +- |democheck| fail to spend any more money +- |democheck| if wallet was filled via p2p payments, wallet asks for target deposit account (exchange going out of business) +- |democheck| enter bank account (if possible) +- |democheck| wallet balance goes to zero +- |democheck| specified bank account receives remaining balance diff --git a/checklists/checklist-release.rst b/checklists/checklist-release.rst new file mode 100644 index 00000000..a51c165d --- /dev/null +++ b/checklists/checklist-release.rst @@ -0,0 +1,141 @@ +GNU Taler Release Checklist +--------------------------- + +.. |releasecheck| raw:: html + + + +For exchange: + +- |releasecheck| no compiler warnings at "-Wall" with gcc +- |releasecheck| no compiler warnings at "-Wall" with clang +- |releasecheck| ensure Coverity static analysis passes +- |releasecheck| make check. +- |releasecheck| make dist, make check on result of 'make dist'. +- |releasecheck| Change version number in configure.ac. +- |releasecheck| update man pages / info page documentation (prebuilt branch) +- |releasecheck| make dist for release +- |releasecheck| verify dist builds from source +- |releasecheck| upgrade 'demo.taler.net' +- |releasecheck| run :doc:`demo upgrade checklist ` +- |releasecheck| tag repo. +- |releasecheck| use 'deployment.git/packaging/\*-docker/' to build Debian and Ubuntu packages +- |releasecheck| upload packages to 'deb.taler.net' (note: only Florian/Christian can sign) +- |releasecheck| change 'demo.taler.net' deployment to use new tag. +- |releasecheck| Upload triplet to ftp-upload.gnu.org/incoming/ftp or /incoming/alpha + +For merchant (C backend): + +- |releasecheck| no compiler warnings at "-Wall" with gcc +- |releasecheck| no compiler warnings at "-Wall" with clang +- |releasecheck| ensure Coverity static analysis passes +- |releasecheck| make check. +- |releasecheck| make dist, make check on result of 'make dist'. +- |releasecheck| update SPA (prebuilt branch) +- |releasecheck| Change version number in configure.ac. +- |releasecheck| make dist for release. +- |releasecheck| verify dist builds from source +- |releasecheck| upgrade 'demo.taler.net' +- |releasecheck| run :doc:`demo upgrade checklist ` +- |releasecheck| tag repo. +- |releasecheck| use 'deployment.git/packaging/\*-docker/' to build Debian and Ubuntu packages +- |releasecheck| upload packages to 'deb.taler.net' (note: only Florian/Christian can sign) +- |releasecheck| change 'demo.taler.net' deployment to use new tag. +- |releasecheck| Upload triplet to ftp-upload.gnu.org/incoming/ftp or /incoming/alpha + +For sync: + +- |releasecheck| no compiler warnings at "-Wall" with gcc +- |releasecheck| no compiler warnings at "-Wall" with clang +- |releasecheck| ensure Coverity static analysis passes +- |releasecheck| make check. +- |releasecheck| make dist, make check on result of 'make dist'. +- |releasecheck| Change version number in configure.ac. +- |releasecheck| make dist for release +- |releasecheck| verify dist builds from source +- |releasecheck| upgrade 'demo.taler.net' +- |releasecheck| run :doc:`demo upgrade checklist ` +- |releasecheck| tag repo. +- |releasecheck| use 'deployment.git/packaging/\*-docker/' to build Debian and Ubuntu packages +- |releasecheck| upload packages to 'deb.taler.net' (note: only Florian/Christian can sign) +- |releasecheck| change 'demo.taler.net' deployment to use new tag. +- |releasecheck| Upload triplet to ftp-upload.gnu.org/incoming/ftp or /incoming/alpha + +For taler-mdb: + +- |releasecheck| no compiler warnings at "-Wall" with gcc +- |releasecheck| ensure Coverity static analysis passes +- |releasecheck| Change version number in configure.ac. +- |releasecheck| make dist for release. +- |releasecheck| tag repo. +- |releasecheck| use 'deployment.git/packaging/\*-docker/' to build Debian and Ubuntu packages +- |releasecheck| upload packages to 'deb.taler.net' (note: only Florian/Christian can sign) +- |releasecheck| Upload triplet to ftp-upload.gnu.org/incoming/ftp or /incoming/alpha + +For taler-twister: + +- |releasecheck| no compiler warnings at "-Wall" with gcc +- |releasecheck| no compiler warnings at "-Wall" with clang +- |releasecheck| ensure Coverity static analysis passes +- |releasecheck| make check. +- |releasecheck| make dist, make check on result of 'make dist'. +- |releasecheck| Change version number in configure.ac. +- |releasecheck| make dist for release. +- |releasecheck| verify dist builds from source +- |releasecheck| upgrade 'demo.taler.net' +- |releasecheck| run :doc:`demo upgrade checklist ` +- |releasecheck| tag repo. +- |releasecheck| Upload triplet to ftp-upload.gnu.org/incoming/ftp or /incoming/alpha + +For libeufin: + +- |releasecheck| update SPA of bank +- |releasecheck| build libeufin +- |releasecheck| upgrade 'demo.taler.net' +- |releasecheck| run :doc:`demo upgrade checklist ` +- |releasecheck| make dist for release. +- |releasecheck| verify dist builds from source +- |releasecheck| tag repo. +- |releasecheck| use 'deployment.git/packaging/\*-docker/' to build Debian and Ubuntu packages +- |releasecheck| upload packages to 'deb.taler.net' (note: only Florian/Christian can sign) +- |releasecheck| change 'demo.taler.net' deployment to use new tag. +- |releasecheck| Upload triplet to ftp-upload.gnu.org/incoming/ftp or /incoming/alpha + +For Python merchant frontend: + +- |releasecheck| upgrade 'demo.taler.net' +- |releasecheck| run :doc:`demo upgrade checklist ` +- |releasecheck| change 'demo.taler.net' deployment to use new tag. + +Wallet-core: + +- |releasecheck| build wallet +- |releasecheck| run integration test +- |releasecheck| make dist for release. +- |releasecheck| verify dist builds from source +- |releasecheck| tag repo. +- |releasecheck| use 'deployment.git/packaging/\*-docker/' to build Debian and Ubuntu packages +- |releasecheck| upload packages to 'deb.taler.net' (note: only Florian/Christian can sign) +- |releasecheck| change 'demo.taler.net' deployment to use new tag. +- |releasecheck| Upload triplet to ftp-upload.gnu.org/incoming/ftp or /incoming/alpha + +Android-Wallet: + +- |releasecheck| build wallet +- |releasecheck| run :doc:`demo upgrade checklist ` +- |releasecheck| tag repo. +- |releasecheck| upload new wallet release to app store + +Webextension-Wallet: + +- |releasecheck| build wallet +- |releasecheck| run :doc:`demo upgrade checklist ` +- |releasecheck| tag repo. +- |releasecheck| upload new wallet release to app store + +Release announcement: + +- |releasecheck| Update bug tracker (mark release, resolved -> closed) +- |releasecheck| Send announcement to taler@gnu.org +- |releasecheck| Send announcement to info-gnu@gnu.org (major releases only) +- |releasecheck| Send announcement to coordinator@translationproject.org diff --git a/checklists/qa-0.9.4.rst b/checklists/qa-0.9.4.rst new file mode 100644 index 00000000..bb525b0c --- /dev/null +++ b/checklists/qa-0.9.4.rst @@ -0,0 +1,161 @@ +=================== +Taler 0.9.4 QA Plan +=================== + +Wallet Platforms +================ + +Platforms listed here are the officially supported platforms for this release. + +* Overview / Installation Page + + * https://taler.net/en/wallet.html + +* Android + + * Google Play: https://play.google.com/store/apps/details?id=net.taler.wallet + * F-Droid: TBD + * APK Download: TBD + +* Browser + + * Chrome: https://chromewebstore.google.com/detail/gnu-taler-wallet/millncjiddlpgdmkklmhfadpacifaonc + * Firefox: https://addons.mozilla.org/en-US/firefox/addon/taler-wallet/ + +* iOS + + +Wallet Flows +============ + +* Bank-Integrated withdrawal + + * webext: "Continue with Mobile Wallet" flow + +* Manual withdrawal + + * ``taler://withdraw-exchange`` flow + + * Currency conversion withdrawal + +* Peer Push Payments ("Send Money") + +* Peer Pull Payments ("Invoice") + +* Deposits + + * Check that deposit arrived + +* Payment + + * on blog merchant + * on survey + * directly initiated via merchant SPA + * webext: "Pay with Mobile Wallet" flow + +* Pay Templates + + * Payment TOTP codes + +* Exchange Management + + * Reloading Exchange Keys + * Deleting an Exchange + + +Running Deployments +=================== + +These deployments are maintained by us and should work for the release. + +* Sandcastle-based: + + * demo.taler.net + + * test.taler.net + +* Regio-Based: + + * regio-taler.fdold.eu + + + +Regio Deployment +================ + +* Deployment Automation (deployment.git/regional-currency) + + * Test with Debian bookworm + + * Test with Ubuntu (FIXME: Which versions?) + + * Check logs for errors + + * Test with telesign + + * Set up EBICS integration + +* Deployment Functionality + + * All flows of the wallet should work + + * All flows of libeufin with regional currency shold work + + * End-To-End conversion withdrawal and deposit with real money + + * Check logs + +libeufin-bank +============= + +* Admin functionality + + * Login + + * Credential change + + * Conversion settings + + * Bank account creation + + * Test transfers + +* Normal account functionality + + * Transfers + + * Transfer to the exchange should bounce + + * Withdrawals + + * (conversion-only): Test cash-in + + * (conversion-only): Test cash-out + + * 2FA for withdrawals, cash-out + +Merchant Backend SPA +==================== + +* Instance creation + +* Bank Account Setup + +* Order Creation + +* Templates + +* TOTP Device Management + + * Also test together with Templates + + +Android Merchant PoS +==================== + +* Test against demo.taler.net + +Android Cashier App +=================== + +* Test against demo.taler.net diff --git a/taler-developer-manual.rst b/taler-developer-manual.rst index ce0e600f..2e12f48a 100644 --- a/taler-developer-manual.rst +++ b/taler-developer-manual.rst @@ -434,7 +434,7 @@ exported by ``~/.bashrc``. Upgrading the ``demo`` environment should be done with care, and ideally be coordinated on the mailing list before. It is our goal for ``demo`` to always run a "working version" that is compatible with various published wallets. -Please use the :doc:`demo upgrade checklist ` to make +Please use the :doc:`demo upgrade checklist ` to make sure everything is working. Nginx is already configured to reach the services as exported by Docker Compose. @@ -476,7 +476,7 @@ All Taler components must be tagged with git before they are deployed on the DD = day SS = serial -.. include:: checklist-demo-upgrade.rst +.. include:: checklists/checklist-demo-upgrade.rst Environments and Builders on taler.net @@ -649,7 +649,7 @@ outside of this versioning. All tables of a GNU Taler component should live in Releases ======== -.. include:: checklist-release.rst +.. include:: checklists/checklist-release.rst Release Process --------------- -- cgit v1.2.3 From 563d87c3acbb2ceacb7a707ce5ff93500bf7e73c Mon Sep 17 00:00:00 2001 From: Florian Dold Date: Wed, 28 Feb 2024 15:04:38 +0100 Subject: checklist --- checklists/qa-0.9.4.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/checklists/qa-0.9.4.rst b/checklists/qa-0.9.4.rst index bb525b0c..ec0504e6 100644 --- a/checklists/qa-0.9.4.rst +++ b/checklists/qa-0.9.4.rst @@ -149,6 +149,11 @@ Merchant Backend SPA * Also test together with Templates +* Setup up Taler Bank Revenue API + +* Check that money from order arrive at the bank + with the right subject. + Android Merchant PoS ==================== -- cgit v1.2.3 From b5c9c6a9649d4c1fb83f4c3c731116d3fc5fcd8f Mon Sep 17 00:00:00 2001 From: Florian Dold Date: Wed, 28 Feb 2024 15:15:51 +0100 Subject: checklist --- checklists/qa-0.9.4.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/checklists/qa-0.9.4.rst b/checklists/qa-0.9.4.rst index ec0504e6..6ac094f3 100644 --- a/checklists/qa-0.9.4.rst +++ b/checklists/qa-0.9.4.rst @@ -95,6 +95,8 @@ Regio Deployment * Set up EBICS integration + * Check that ToS is configured + * Deployment Functionality * All flows of the wallet should work -- cgit v1.2.3 From cd092fed0a6c67edd6e612d3e80067c2b617196e Mon Sep 17 00:00:00 2001 From: Antoine A <> Date: Wed, 28 Feb 2024 17:26:12 +0100 Subject: Improve regional currency manual --- libeufin/regional-automated-manual.rst | 47 +++++++++++++++------------------- libeufin/regional-custom-manual.rst | 8 +++--- 2 files changed, 23 insertions(+), 32 deletions(-) diff --git a/libeufin/regional-automated-manual.rst b/libeufin/regional-automated-manual.rst index 596fb12e..aa579373 100644 --- a/libeufin/regional-automated-manual.rst +++ b/libeufin/regional-automated-manual.rst @@ -93,9 +93,15 @@ Navigate into the *regional-currency/* directory and run *main.sh* as **root**: The script will start by installing required packages and then asking you fundamental questions about the desired setup, in particular : #. The name of the regional currency. It must have 3 to 11 letters. -#. The ISO code of the fiat currency. Use 'CHF' or 'EUR'. +#. Whether to setup your regional currency to be backed by a fiat currency. You will need bank account at a bank dealing in fiat currency that offers an online banking protocol supported by LibEuFin Nexus. If you say `y` you will have to also provide the following information: + + #. The ISO code of the fiat currency. Use 'CHF' or 'EUR'. + #. The IBAN of the fiat bank account. + #. The BIC of the fiat bank account. + #. The legal name of the fiat bank account. + #. The name of the regional currency bank. It will be shown to business users when they interact with the system. -#. The DNS domain name of your setup (i.e: domain.tld). The installer will create by itself all the needed subdomains for your domain name, as (``bank.$DOMAIN``, ``exchange.$DOMAIN`` and ``backend.$DOMAIN``). But, these subdomain names as explained before, must have been added beforehand to your DNS domain control panel, and they must be pointing to the IP address of the server on which you are running the installation (before you execute the installer). +#. The DNS domain name of your setup (i.e: domain.tld). The installer will create by itself all the needed subdomains for your domain name, as (``bank.$DOMAIN_NAME``, ``exchange.$DOMAIN_NAME`` and ``backend.$DOMAIN_NAME``). But, these subdomain names as explained before, must have been added beforehand to your DNS domain control panel, and they must be pointing to the IP address of the server on which you are running the installation (before you execute the installer). #. Whether to use TLS or not. You should answer ``y`` in most cases. #. Whether to store Taler Exchange keys on this server or externally on another server. Unless you need a high-security setup and expect to run an offline key management process, say ``y``. If you say ``n``, you will need to run ``taler-exchange-offline setup`` on your offline system and provide the master public key. Furthermore, you should then study the exchange manual on offline key management to finish the exchange setup process later. #. Whether to setup SMS two-factor authentication using `Telesign `_, multi-factor authentication is strongly recommended, especially when regional currency can be converted to fiat currency. This requires `a Customer ID and an API Key `_. You should answer ``y`` in most cases. @@ -122,9 +128,9 @@ If for some reason your installation doesn't work because you have answered erro some of the interactive questions, or you just want to reset the current installation and to re-deploy the script again for having its latest changes, you will have to proceed as follows: -In brief you need to wipe completely the "content" of the file config/user.conf, this doesn't mean +In brief, you need to wipe completely the "content" of the file config/user.conf, this doesn't mean to remove the file itself, but only its content. Even though you can do this manually by editing the file manually -with you preferred text editor, you can also do this in one single command. +with your preferred text editor, you can also do this in one single command. .. code-block:: console @@ -140,6 +146,8 @@ Multi-factor authentication The script allows you to configure multi-factor authentication via SMS using Telesign as a provider. You can also configure multi-factor authentication via email or use providers other than Telesign for SMS. You will need to configure these channels manually as described in :ref:`multi-factor authentication `. +If you choose not to back your regional currency with a fiat currency, you can stop here. + Web-based Configuration +++++++++++++++++++++++ @@ -148,7 +156,7 @@ By default, the regional currency conversion rates are 1:1. You can change the c Connecting to a Fiat Bank: the EBICS setup ++++++++++++++++++++++++++++++++++++++++++ -To complete the conversion setup, you have to set up an EBICS subscriber using a fiat bank account at a bank dealing in fiat currency that offers an online banking protocol supported by LibEuFin Nexus. +To complete the conversion setup, you have to set up an EBICS subscriber using the fiat bank account you specified during the automated setup. When you sign up for an EBICS-enabled bank account, the bank will provide you with various credentials. Those must be provided in the @@ -173,11 +181,6 @@ The following snippet shows the mandatory configuration values: USER_ID = PFC00563 PARTNER_ID = PFC00563 - # Account information - IBAN = CH7789144474425692816 - BIC = POFICHBEXXX - NAME = John Smith S.A. - .. warning:: This combination of HOST_ID, USER_ID and PARTNER_ID must never be used by another instance of libeufin-nexus or by other EBICS clients, otherwise data will be lost. @@ -226,30 +229,20 @@ The EBICS setup is finished once the bank keys have been accepted. Configuring the Exchange for Conversion +++++++++++++++++++++++++++++++++++++++ -This section explains how to enable currency conversion at the exchange, -which is critical for wallets to know how to wire fiat currency to an -exchange to obtain regional currency. - -You will need to use the ``taler-exchange-offline`` tool to inform the -exchange about the **fiat** bank account that can be used for cash in -operations and also specify the URL for currency conversion. Additionally, -you may also configure restrictions on the bank accounts that may originate -the funds, for example, to prevent international wire transfers that may expose -you to additional compliance risks. - -Given the ``$IBAN`` of the fiat currency bank account and ``$NAME`` as -the (URL-encoded) name of the exchange-account owner, the following -``taler-exchange-offline`` invocation can be used to notify wallets about -the possibility of currency conversion (cash in): +By default, the exchange is setup to perform conversion without any restrictions. You may configure restrictions on the bank accounts that may originate the funds, for example, to prevent international wire transfers that may expose you to additional compliance risks: .. code-block:: console $ sudo -u taler-exchange-offline taler-exchange-offline \ enable-account \ - payto://iban/$IBAN?receiver-name=$NAME \ - conversion-url "${PROTO}://bank.$DOMAIN/conversion-info/" \ + "${CONVERSION_PAYTO}" \ + conversion-url "${PROTO}://bank.$DOMAIN_NAME/conversion-info/" \ + # restrictions ... upload +.. note:: + Refer to the manpage ``taler-exchange-offline`` for a full array or possible restrictions. + System ON! ++++++++++ diff --git a/libeufin/regional-custom-manual.rst b/libeufin/regional-custom-manual.rst index a3c1aecd..815c821d 100644 --- a/libeufin/regional-custom-manual.rst +++ b/libeufin/regional-custom-manual.rst @@ -44,7 +44,9 @@ You need to setup the :ref:`libeufin-nexus` using a bank account offers an online banking protocol supported by LibEuFin Nexus. Next, you have to enable conversion and should ensure that at least one TAN -channel for :ref:`multi-factor authentication ` is configured: +channel for :ref:`multi-factor authentication ` is configured. + +The following snippet shows how to enable conversion in ``libeufin-bank`` configuration: .. code-block:: ini @@ -52,10 +54,6 @@ channel for :ref:`multi-factor authentication ` is configured: ALLOW_CONVERSION = YES FIAT_CURRENCY = EUR - TAN_SMS = libeufin-tan-sms.sh - # And/Or - TAN_EMAIL = libeufin-tan-email.sh - Make sure to (re)start the libeufin-bank after changing these configuration options: -- cgit v1.2.3 From a5ccd3f53a4f3d08fc5cbed975a8799449903a59 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Thu, 29 Feb 2024 10:29:55 +0100 Subject: clean up intro text --- index.rst | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/index.rst b/index.rst index d30542cb..e97fe2b9 100644 --- a/index.rst +++ b/index.rst @@ -37,11 +37,12 @@ practice a fraudulent Exchange might go bankrupt instead of paying the Merchants and thus the Exchange will need to be audited regularly like any other banking institution. -The system will be based on free software and open protocols. +The system is based on free software and open protocols. + +In this documentation, we describe the REST-based APIs between the various +components, how to use the system, the internal architecture of key +components, and how to get them installed and configured. -In this document, we describe the REST-based APIs between the various -components, internal architecture of key components, and how to get them -installed. Documentation Overview -- cgit v1.2.3 From ed161edaee17ba6760fce787601db18b635fa16b Mon Sep 17 00:00:00 2001 From: Antoine A <> Date: Thu, 29 Feb 2024 13:42:33 +0100 Subject: Improve regional currency manual --- libeufin/regional-automated-manual.rst | 12 ++++++------ libeufin/regional-custom-manual.rst | 1 + 2 files changed, 7 insertions(+), 6 deletions(-) diff --git a/libeufin/regional-automated-manual.rst b/libeufin/regional-automated-manual.rst index aa579373..937831f9 100644 --- a/libeufin/regional-automated-manual.rst +++ b/libeufin/regional-automated-manual.rst @@ -23,7 +23,7 @@ Regional Currency Automated Setup Manual ######################################## -This manual describes how to setup a regional currency backed by a fiat currency using a script that largely automates the process. If you want to do a custom setup you can follow the :doc:`custom setup manual`. +This manual describes how to setup a regional currency using a script that largely automates the process. If you want to do a custom setup you can follow the :doc:`custom setup manual`. .. contents:: Table of Contents @@ -38,7 +38,7 @@ Prerequisites +++++++++++++ For this manual, we assume that the system is deployed on a contemporary -Debian GNU/Linux or Ubuntu LTS system using the binary packages provided. +Debian GNU/Linux Bookworm or Ubuntu Mantic system using the binary packages provided. Furthermore, you should run the process on a system with one or more globally reachable IP address(es) *and* with various DNS names already pointing to these IPs. @@ -66,7 +66,7 @@ You can check this from your terminal very easily with the "ping" command, as th You can also use `this tool `_ for the same purpose, and to check the propagation status. .. warning:: - Take into account some hosting providers providing virtualized servers (VPS or VDS), can enable by default the firewall program "UFW", blocking by default the port number 443. So you have to either disable this firewall program, or open to this 443 port number to allow https. + Take into account some hosting providers providing virtualized servers (VPS or VDS) can enable by default the firewall program "UFW", blocking by default the port number 443. So you have to either disable this firewall program, or open to this 443 port number to allow https. Now you are ready to go with the next step. @@ -90,10 +90,10 @@ Navigate into the *regional-currency/* directory and run *main.sh* as **root**: $ cd deployment/regional-currency/ # ./main.sh -The script will start by installing required packages and then asking you fundamental questions about the desired setup, in particular : +The script will start by installing the required packages and then asking you fundamental questions about the desired setup, in particular: #. The name of the regional currency. It must have 3 to 11 letters. -#. Whether to setup your regional currency to be backed by a fiat currency. You will need bank account at a bank dealing in fiat currency that offers an online banking protocol supported by LibEuFin Nexus. If you say `y` you will have to also provide the following information: +#. Whether to setup the regional currency to be backed by a fiat currency. You'll need a bank account at a fiat currency bank offering an online banking protocol supported by LibEuFin Nexus. If you answer ``y``, you will also need to provide the following information: #. The ISO code of the fiat currency. Use 'CHF' or 'EUR'. #. The IBAN of the fiat bank account. @@ -103,7 +103,6 @@ The script will start by installing required packages and then asking you fundam #. The name of the regional currency bank. It will be shown to business users when they interact with the system. #. The DNS domain name of your setup (i.e: domain.tld). The installer will create by itself all the needed subdomains for your domain name, as (``bank.$DOMAIN_NAME``, ``exchange.$DOMAIN_NAME`` and ``backend.$DOMAIN_NAME``). But, these subdomain names as explained before, must have been added beforehand to your DNS domain control panel, and they must be pointing to the IP address of the server on which you are running the installation (before you execute the installer). #. Whether to use TLS or not. You should answer ``y`` in most cases. -#. Whether to store Taler Exchange keys on this server or externally on another server. Unless you need a high-security setup and expect to run an offline key management process, say ``y``. If you say ``n``, you will need to run ``taler-exchange-offline setup`` on your offline system and provide the master public key. Furthermore, you should then study the exchange manual on offline key management to finish the exchange setup process later. #. Whether to setup SMS two-factor authentication using `Telesign `_, multi-factor authentication is strongly recommended, especially when regional currency can be converted to fiat currency. This requires `a Customer ID and an API Key `_. You should answer ``y`` in most cases. #. The admin password for the bank. Be absolutely sure to enter a very, very long and high-entropy password, preferably using the autogenerated one. @@ -233,6 +232,7 @@ By default, the exchange is setup to perform conversion without any restrictions .. code-block:: console + $ . config/user.conf $ sudo -u taler-exchange-offline taler-exchange-offline \ enable-account \ "${CONVERSION_PAYTO}" \ diff --git a/libeufin/regional-custom-manual.rst b/libeufin/regional-custom-manual.rst index 815c821d..842b943b 100644 --- a/libeufin/regional-custom-manual.rst +++ b/libeufin/regional-custom-manual.rst @@ -94,6 +94,7 @@ the possibility of currency conversion (cash in): enable-account \ payto://iban/$IBAN?receiver-name=$NAME \ conversion-url "$CONVERSION_URL" \ + # restrictions ... upload Here, the ``$CONVERSION_URL`` must be set to the base URL of the conversion -- cgit v1.2.3 From 6cbacdfbc28a73f2f4321b482f6e91a8efd7cc21 Mon Sep 17 00:00:00 2001 From: Florian Dold Date: Thu, 29 Feb 2024 23:38:57 +0100 Subject: checklist --- checklists/qa-0.9.4.rst | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/checklists/qa-0.9.4.rst b/checklists/qa-0.9.4.rst index 6ac094f3..72dcdab8 100644 --- a/checklists/qa-0.9.4.rst +++ b/checklists/qa-0.9.4.rst @@ -166,3 +166,24 @@ Android Cashier App =================== * Test against demo.taler.net + + +Debian Repository +================= + +* Debian + + * repo at https://deb.taler.net/apt/debian/ + * supported codename(s): bookworm + + +* Ubuntu: + + * repo at https://deb.taler.net/apt/ubuntu/ + * supported codename(s): mantic + +GNU Release +=========== + +* Release Announcement +* FTP Upload -- cgit v1.2.3 From 26dc3631e6b81ab2eb6cac11c144eb71d31194ee Mon Sep 17 00:00:00 2001 From: Florian Dold Date: Thu, 29 Feb 2024 23:42:44 +0100 Subject: checklist --- checklists/qa-0.9.4.rst | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/checklists/qa-0.9.4.rst b/checklists/qa-0.9.4.rst index 72dcdab8..5f22e5a1 100644 --- a/checklists/qa-0.9.4.rst +++ b/checklists/qa-0.9.4.rst @@ -79,7 +79,6 @@ These deployments are maintained by us and should work for the release. * regio-taler.fdold.eu - Regio Deployment ================ @@ -107,6 +106,7 @@ Regio Deployment * Check logs + libeufin-bank ============= @@ -136,6 +136,7 @@ libeufin-bank * 2FA for withdrawals, cash-out + Merchant Backend SPA ==================== @@ -162,12 +163,21 @@ Android Merchant PoS * Test against demo.taler.net + Android Cashier App =================== * Test against demo.taler.net + +CI +== + +* https://buildbot.taler.net/#/waterfall +* CI should pass + + Debian Repository ================= -- cgit v1.2.3 From 6611af24895160a72aa2fdd69f54cd2cbff8f2bb Mon Sep 17 00:00:00 2001 From: Florian Dold Date: Fri, 1 Mar 2024 00:49:55 +0100 Subject: dd55 --- design-documents/055-wallet-problem-report.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/design-documents/055-wallet-problem-report.rst b/design-documents/055-wallet-problem-report.rst index a7ae783c..84c6159a 100644 --- a/design-documents/055-wallet-problem-report.rst +++ b/design-documents/055-wallet-problem-report.rst @@ -55,6 +55,7 @@ Types of reports * money lost due to the exchange stopping to offer a denomination * money locked behind a (long) pending refresh * money lost due to a permanently failing refresh +* money lost due to expired denominations (auto-refresh wasn't done fast enough) * exchange changed its master public key * a denomination changed its info (expiration, fees) -- cgit v1.2.3 From 85d1f0a0def91ee0fafccdde7fdf9c514b1a486b Mon Sep 17 00:00:00 2001 From: Antoine A <> Date: Fri, 1 Mar 2024 10:30:17 +0100 Subject: Improve regional currency manual --- libeufin/regional-automated-manual.rst | 34 +++++++++++++++++++++++++++++++++- libeufin/regional-custom-manual.rst | 31 +++++++++++++++++++++++++++++++ 2 files changed, 64 insertions(+), 1 deletion(-) diff --git a/libeufin/regional-automated-manual.rst b/libeufin/regional-automated-manual.rst index 937831f9..4fe492ab 100644 --- a/libeufin/regional-automated-manual.rst +++ b/libeufin/regional-automated-manual.rst @@ -105,6 +105,8 @@ The script will start by installing the required packages and then asking you fu #. Whether to use TLS or not. You should answer ``y`` in most cases. #. Whether to setup SMS two-factor authentication using `Telesign `_, multi-factor authentication is strongly recommended, especially when regional currency can be converted to fiat currency. This requires `a Customer ID and an API Key `_. You should answer ``y`` in most cases. #. The admin password for the bank. Be absolutely sure to enter a very, very long and high-entropy password, preferably using the autogenerated one. +#. Whether to generate terms of service (ToS) for the exchange from default templates. +#. Whether to generate a privacy policy for the exchange from default templates. The information you entered as well as the generated bank admin password will be stored in a file called ``config/user.conf``. If you run the script in @@ -241,7 +243,7 @@ By default, the exchange is setup to perform conversion without any restrictions upload .. note:: - Refer to the manpage ``taler-exchange-offline`` for a full array or possible restrictions. + Refer to the manpage ``taler-exchange-offline`` for a full array of possible restrictions. System ON! ++++++++++ @@ -254,4 +256,34 @@ outgoing bank transactions ` (cash out). # systemctl enable --now libeufin-nexus.target +Configuring exchange terms +++++++++++++++++++++++++++ + +You can use your own terms of service and privacy policy. You can use the default templates in ``/usr/share/taler/terms`` as a guide. +Assuming you have custom terms of service and privacy policy ``rst`` teamplte files at ``TOS_PATH`` and ``PRIVACY_PATH``, the following commands generate the terms files: + +.. code-block:: console + + # taler-terms-generator -i "$TOS_PATH" + # taler-terms-generator -i "$PRIVACY_PATH" + +You now have to specify the terms file names in the exchange config: + +.. code-block:: console + + # TERMS_ETAG="$(basename "$TOS_PATH" .rst)" + # PRIVACY_ETAG="$(basename "$PRIVACY_PATH" .rst)" + +.. code-block:: ini + + [exchange] + TERMS_ETAG=${TERMS_ETAG} + PRIVACY_ETAG=${PRIVACY_ETAG} + +Make sure to restart taler-exchange after changing these configuration options: + +.. code-block:: console + + # systemctl restart taler-exchange.target + .. include:: ../frags/regional-manual-use.rst diff --git a/libeufin/regional-custom-manual.rst b/libeufin/regional-custom-manual.rst index 842b943b..a6060586 100644 --- a/libeufin/regional-custom-manual.rst +++ b/libeufin/regional-custom-manual.rst @@ -118,4 +118,35 @@ outgoing bank transactions ` (cash out). # systemctl enable --now libeufin-nexus.target + +Configuring exchange terms +++++++++++++++++++++++++++ + +You can use your own terms of service and privacy policy. You can use the default templates in ``/usr/share/taler/terms`` as a guide. +Assuming you have custom terms of service and privacy policy ``rst`` teamplte files at ``TOS_PATH`` and ``PRIVACY_PATH``, the following commands generate the terms files: + +.. code-block:: console + + # taler-terms-generator -i "$TOS_PATH" + # taler-terms-generator -i "$PRIVACY_PATH" + +You now have to specify the terms file names in the exchange config: + +.. code-block:: console + + # TERMS_ETAG="$(basename "$TOS_PATH" .rst)" + # PRIVACY_ETAG="$(basename "$PRIVACY_PATH" .rst)" + +.. code-block:: ini + + [exchange] + TERMS_ETAG=${TERMS_ETAG} + PRIVACY_ETAG=${PRIVACY_ETAG} + +Make sure to restart taler-exchange after changing these configuration options: + +.. code-block:: console + + # systemctl restart taler-exchange.target + .. include:: ../frags/regional-manual-use.rst \ No newline at end of file -- cgit v1.2.3 From caf4feb4f1dbf9d9903f41c53ff6a11781c3957e Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Sat, 2 Mar 2024 19:33:15 +0100 Subject: -fix build ERROR --- frags/nexus-ebics-setup.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/frags/nexus-ebics-setup.rst b/frags/nexus-ebics-setup.rst index 564978b8..76f51bfe 100644 --- a/frags/nexus-ebics-setup.rst +++ b/frags/nexus-ebics-setup.rst @@ -38,7 +38,7 @@ The following snippet shows the mandatory configuration values: This combination of HOST_ID, USER_ID and PARTNER_ID must never be used by another instance of libeufin-nexus or by other EBICS clients, otherwise data will be lost. Reuse existing client keys -^^^^^^^^^^^^^^^^^^^^^^^^^^ +-------------------------- If you have client keys from a previous EBICS setup you can copy the JSON file to the configured path ``CLIENT_PRIVATE_KEYS_FILE`` (``/var/lib/libeufin-nexus/client-ebics-keys.json`` with the default config). @@ -49,7 +49,7 @@ Make sure this file is accessible to the user running ``libeufin-nexus``, for th $ chown libeufin-nexus:libeufin-nexus /var/lib/libeufin-nexus/client-ebics-keys.json Create new client keys -^^^^^^^^^^^^^^^^^^^^^^ +---------------------- Assuming that the configuration file exists at ``$CONFIG_FILE``, the following command should start the EBICS setup process: @@ -69,7 +69,7 @@ file with keys created at '/tmp/libeufin-nexus-keys-$TIMESTAMP.pdf'``. Once the bank has received and processed this document you can continue. Get bank keys -^^^^^^^^^^^^^ +------------- Assuming that the configuration file exists at ``$CONFIG_FILE``, the following command will finish the EBICS setup process: -- cgit v1.2.3 From ea4612e9671d4955145a9ca486d2434e5b2e38bd Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Sat, 2 Mar 2024 21:15:06 +0100 Subject: -minor edits --- taler-user-guide.rst | 32 ++++++++++++++++---------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/taler-user-guide.rst b/taler-user-guide.rst index 8b7a5ed1..b29f7902 100644 --- a/taler-user-guide.rst +++ b/taler-user-guide.rst @@ -38,8 +38,8 @@ an account at the bank. Some operations also require access to the merchant backend. -Withdrawing -=========== +Withdrawing from bank accounts +============================== Withdrawing is the step where money is moved from a bank account into a GNU Taler wallet. There are two main ways to do this. @@ -70,7 +70,8 @@ Wallet initiated withdrawal In this case, you will start the withdraw process from the GNU Taler wallet. Under "Settings", you will find a list of exchanges. If the list is empty or does not contain the desired exchange, you may have to first add the exchange -by providing the respective URL. +by providing the respective URL. The payment service provider operating the +exchange service should have such a QR code on their Web site. Next to the exchange, there is a drop-down menu with an option to "withdraw". (If you already have money in your wallet, you will also find the same button @@ -86,16 +87,16 @@ as instructed by the wallet. Once the money has arrived at the exchange, the wallet will automatically withdraw the funds. -Depositing -========== +Depositing into bank accounts +============================= If you have money in your wallet, you can use the "deposit" button to deposit the funds into a bank account. The wallet will ask you to specify the amount and the target bank account. -Sending cash -============ +Sending digital cash +==================== Once you have digital cash, you can send it to another GNU Taler wallet. Simply specify the amount and a human-readable reason for the @@ -109,19 +110,19 @@ clicking the QR code scan button). Afterwards, review the reason text and accept the funds to complete the transaction. -Invoicing -========= +Receiving digital cash +====================== -To receive funds from another user, you can send an invoice to another GNU +To receive funds from another user, you can send a payment request to another GNU Taler wallet. Simply specify the amount and a human-readable reason for the -invoice. The wallet will then show a QR code (and give the option to export -the invoice as a taler://-URL). Send the image of the QR code to the payer +payment request. The wallet will then show a QR code (and give the option to export +the payment request as a taler://-URL). Send the image of the QR code to the payer wallet (or send the taler://-URL to the target wallet). The target wallet should scan the QR code (or enter the text of the taler://-URL into the URL import dialog which is available by holding or clicking the QR code scan button). Afterwards, review the reason for -the invoice and decide whether or not to pay the invoice. Selecting +the payment request and decide whether or not to pay it. Selecting "pay" will complete the transaction. Depending on the configuration of the exchange, the receiving wallet may have @@ -270,9 +271,8 @@ template does not specify a fixed amount, the payer will be prompted to enter the amount to be paid (and possibly given the opportunity to specify or alter the summary). Selecting "pay" will complete the transaction. If payment confirmations are configured by the merchant backend, the wallet will then -display a confirmation code that can be shown to the merchant as a proof of -payment. - +display a TOTP confirmation code that can be shown to the merchant as a proof +of payment. -- cgit v1.2.3 From a9270360b6f0d0597a20fe3f9d1afc190b1a51a7 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Sat, 2 Mar 2024 21:29:07 +0100 Subject: structural improvments, de-duplication --- taler-auditor-manual.rst | 4 ++-- taler-challenger-manual.rst | 4 ++-- taler-exchange-manual.rst | 9 ++++++-- taler-merchant-api-tutorial.rst | 11 +++++++--- taler-merchant-manual.rst | 19 ++++++---------- taler-merchant-pos-terminal.rst | 41 ++++++----------------------------- taler-user-guide.rst | 48 +++++++++++++++++++++++------------------ taler-wallet.rst | 20 +++++++++++++++-- 8 files changed, 77 insertions(+), 79 deletions(-) diff --git a/taler-auditor-manual.rst b/taler-auditor-manual.rst index 9f9bf1f7..bb8e7741 100644 --- a/taler-auditor-manual.rst +++ b/taler-auditor-manual.rst @@ -17,8 +17,8 @@ @author Christian Grothoff -GNU Taler Auditor Operator Manual -################################# +Auditor Operator Manual +####################### Introduction ============ diff --git a/taler-challenger-manual.rst b/taler-challenger-manual.rst index 3b89615e..3e4871cb 100644 --- a/taler-challenger-manual.rst +++ b/taler-challenger-manual.rst @@ -17,8 +17,8 @@ @author Christian Grothoff @author Florian Dold -GNU Taler Challenger Operator Manual -#################################### +Challenger Operator Manual +########################## Introduction ============ diff --git a/taler-exchange-manual.rst b/taler-exchange-manual.rst index ecb88807..e3d5e745 100644 --- a/taler-exchange-manual.rst +++ b/taler-exchange-manual.rst @@ -17,8 +17,8 @@ @author Christian Grothoff @author Florian Dold -GNU Taler Exchange Operator Manual -################################## +Exchange Operator Manual +######################## Introduction ============ @@ -35,6 +35,11 @@ About this manual This manual targets system administrators who want to install and operate a GNU Taler exchange. +.. contents:: Table of Contents + :maxdepth: 1 + :glob: + + Organizational prerequisites ---------------------------- diff --git a/taler-merchant-api-tutorial.rst b/taler-merchant-api-tutorial.rst index 87fee9ca..2bb95457 100644 --- a/taler-merchant-api-tutorial.rst +++ b/taler-merchant-api-tutorial.rst @@ -19,8 +19,8 @@ .. _merchant-api-tutorial: -GNU Taler Merchant API Tutorial -############################### +Merchant API Tutorial +##################### Introduction ============ @@ -68,8 +68,13 @@ If you want to look at some simple, running examples, check out these: process. +.. contents:: Table of Contents + :maxdepth: 1 + :glob: + + Architecture overview ---------------------- +===================== The Taler software stack for a merchant consists of the following main components: diff --git a/taler-merchant-manual.rst b/taler-merchant-manual.rst index d1520d02..6e130f88 100644 --- a/taler-merchant-manual.rst +++ b/taler-merchant-manual.rst @@ -18,8 +18,8 @@ .. _taler-merchant-backend-operator-manual: -GNU Taler Merchant Backend Operator Manual -########################################## +Merchant Backend Operator Manual +################################ Introduction ============ @@ -42,21 +42,14 @@ We expect some moderate familiarity with the compilation and installation of Free Software packages. An understanding of cryptography is not required. -This first chapter of the manual will give a brief overview of the -overall Taler architecture, describing the environment in which the -Taler backend operates. The second chapter then explains how to install -the software, including key dependencies. The third chapter will explain -how to configure the backend, including in particular the configuration -of the bank account details of the merchant. - -The last chapter gives some additional information about advanced topics -which will be useful for system administrators but are not necessary for -operating a basic backend. +.. contents:: Table of Contents + :maxdepth: 1 + :glob: .. _Architecture-overview: Architecture overview ---------------------- +===================== .. index:: crypto-currency .. index:: KUDOS diff --git a/taler-merchant-pos-terminal.rst b/taler-merchant-pos-terminal.rst index 0cca1d52..1627cef8 100644 --- a/taler-merchant-pos-terminal.rst +++ b/taler-merchant-pos-terminal.rst @@ -17,15 +17,20 @@ .. _taler-merchant-pos-app: -GNU Taler Merchant POS App +Merchant Point of Sale App ########################## -The GNU Taler merchant POS (point of sale) terminal allows sellers to +The GNU Taler merchant point of sale (POS) App allows sellers to * process customers' orders by adding or removing products * calculate the amount owed by the customer * let the customer make a Taler payment via QR code or NFC +.. contents:: Table of Contents + :maxdepth: 1 + :glob: + + Android App =========== @@ -66,38 +71,6 @@ Clicking this opens a menu with these items: * Settings: Allows you to change the app configuration settings (URL and username/password) and to forget the password (for locking the app). -Testing nightly builds ----------------------- - -Every change to the app's source code triggers an automatic build -that gets published in a F-Droid repository. -If you don't have it already, download the `F-Droid app `_ -and then click the following link (on your phone) to add the nightly repository. - - `GNU Taler Nightly F-Droid Repository `_ - -.. note:: - Nightly apps can be installed alongside official releases - and thus are meant **only for testing purposes**. - Use at your own risk! - -While not recommended, APKs can also be -`downloaded directly `__. - -Building from source --------------------- - -Import in and build with Android Studio or run on the command line: - -.. code-block:: console - - $ git clone https://git.taler.net/merchant-terminal-android.git - $ cd merchant-terminal-android - $ ./gradlew assembleRelease - -If you do not have the proprietary Android SDK installed, -see the :doc:`taler-developer-manual` -for :ref:`build instructions using free SDK rebuilds `. APIs and Data Formats ===================== diff --git a/taler-user-guide.rst b/taler-user-guide.rst index b29f7902..fbc3b1c6 100644 --- a/taler-user-guide.rst +++ b/taler-user-guide.rst @@ -16,8 +16,8 @@ @author Christian Grothoff -GNU Taler User Guide -#################### +User Guide +########## Introduction ============ @@ -38,6 +38,12 @@ an account at the bank. Some operations also require access to the merchant backend. +.. contents:: Table of Contents + :maxdepth: 1 + :glob: + + + Withdrawing from bank accounts ============================== @@ -179,18 +185,18 @@ A simple way for merchants to accept GNU Taler payments is the use of the point-of-sale app. The app can be installed on an Android phone or tablet and is configured via a simple JSON file on a Web site: - * In the app settings you need to specify the URL of the Web site where - the app can download the categories, products and prices from which - orders are to be compiled. You can optionally specify a username and - password to authenticate to the Web server. +* In the app settings you need to specify the URL of the Web site where + the app can download the categories, products and prices from which + orders are to be compiled. You can optionally specify a username and + password to authenticate to the Web server. - * The syntax of the JSON file is described in the point-of-sale app - manual. However, you may simply want to download the sample JSON - file from our documentation and use it as a starting point. +* The syntax of the JSON file is described in the point-of-sale app + manual. However, you may simply want to download the sample JSON + file from our documentation and use it as a starting point. - * A key option is the merchant backend with the authorization key - which must be included in this JSON configuration. You may point - the point-of-sale app to any instance of a merchant backend. +* A key option is the merchant backend with the authorization key + which must be included in this JSON configuration. You may point + the point-of-sale app to any instance of a merchant backend. Once configured, the point-of-sale app allows the user to select a product category and then to quickly add products from that category to an order. You @@ -305,8 +311,8 @@ Pay events For "pay" events, the backend will provide the following information to the Mustach templating engine: - * :ref:`contract_terms `: the contract terms of the paid order - * order_id: the ID of the order that received the refund +* :ref:`contract_terms `: the contract terms of the paid order +* order_id: the ID of the order that received the refund Refund events @@ -315,10 +321,10 @@ Refund events For "refund" events, the backend will provide the following information to the Mustach templating engine: - * timestamp: time of the refund (in nanoseconds since 1970) - * order_id: the ID of the order that received the refund - * :ref:`contract_terms `: the full JSON of the contract terms of the refunded order - * refund_amout: the amount that was being refunded - * reason: the reason entered by the merchant staff for granting the refund; - be careful, you probably want to inform your staff if a webhook may expose - this information to the consumer +* timestamp: time of the refund (in nanoseconds since 1970) +* order_id: the ID of the order that received the refund +* :ref:`contract_terms `: the full JSON of the contract terms of the refunded order +* refund_amout: the amount that was being refunded +* reason: the reason entered by the merchant staff for granting the refund; + be careful, you probably want to inform your staff if a webhook may expose + this information to the consumer diff --git a/taler-wallet.rst b/taler-wallet.rst index 62dca80d..5a10adc0 100644 --- a/taler-wallet.rst +++ b/taler-wallet.rst @@ -1,5 +1,21 @@ -GNU Taler Wallet Manual -####################### +.. + This file is part of GNU TALER. + Copyright (C) 2014-2024 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 + + +Wallet Manual +############# The GNU Taler wallet allows customers to withdraw and spend digital cash. -- cgit v1.2.3 From 4e06d8dfa57f33bbcbefa2ee39126135062853a7 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Sat, 2 Mar 2024 21:44:48 +0100 Subject: structural improvments, de-duplication --- taler-exchange-manual.rst | 8 ++++---- taler-merchant-manual.rst | 10 +++++----- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/taler-exchange-manual.rst b/taler-exchange-manual.rst index e3d5e745..dcbdba2c 100644 --- a/taler-exchange-manual.rst +++ b/taler-exchange-manual.rst @@ -20,6 +20,10 @@ Exchange Operator Manual ######################## +.. contents:: Table of Contents + :depth: 2 + + Introduction ============ @@ -35,10 +39,6 @@ About this manual This manual targets system administrators who want to install and operate a GNU Taler exchange. -.. contents:: Table of Contents - :maxdepth: 1 - :glob: - Organizational prerequisites ---------------------------- diff --git a/taler-merchant-manual.rst b/taler-merchant-manual.rst index 6e130f88..9925df0e 100644 --- a/taler-merchant-manual.rst +++ b/taler-merchant-manual.rst @@ -21,6 +21,10 @@ Merchant Backend Operator Manual ################################ +.. contents:: Table of Contents + :depth: 2 + + Introduction ============ @@ -42,14 +46,10 @@ We expect some moderate familiarity with the compilation and installation of Free Software packages. An understanding of cryptography is not required. -.. contents:: Table of Contents - :maxdepth: 1 - :glob: - .. _Architecture-overview: Architecture overview -===================== +--------------------- .. index:: crypto-currency .. index:: KUDOS -- cgit v1.2.3 From 32784beb452442e64821a3de479f48b239a7e246 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Sat, 2 Mar 2024 21:52:46 +0100 Subject: fix structure --- checklists/checklist-release.rst | 16 ++++++++-------- taler-auditor-manual.rst | 4 ++++ taler-developer-manual.rst | 5 +++++ taler-merchant-api-tutorial.rst | 10 ++++------ taler-merchant-pos-terminal.rst | 3 +-- taler-user-guide.rst | 9 +++------ 6 files changed, 25 insertions(+), 22 deletions(-) diff --git a/checklists/checklist-release.rst b/checklists/checklist-release.rst index a51c165d..eaefd0b9 100644 --- a/checklists/checklist-release.rst +++ b/checklists/checklist-release.rst @@ -17,7 +17,7 @@ For exchange: - |releasecheck| make dist for release - |releasecheck| verify dist builds from source - |releasecheck| upgrade 'demo.taler.net' -- |releasecheck| run :doc:`demo upgrade checklist ` +- |releasecheck| run :doc:`demo upgrade checklist ` - |releasecheck| tag repo. - |releasecheck| use 'deployment.git/packaging/\*-docker/' to build Debian and Ubuntu packages - |releasecheck| upload packages to 'deb.taler.net' (note: only Florian/Christian can sign) @@ -36,7 +36,7 @@ For merchant (C backend): - |releasecheck| make dist for release. - |releasecheck| verify dist builds from source - |releasecheck| upgrade 'demo.taler.net' -- |releasecheck| run :doc:`demo upgrade checklist ` +- |releasecheck| run :doc:`demo upgrade checklist ` - |releasecheck| tag repo. - |releasecheck| use 'deployment.git/packaging/\*-docker/' to build Debian and Ubuntu packages - |releasecheck| upload packages to 'deb.taler.net' (note: only Florian/Christian can sign) @@ -54,7 +54,7 @@ For sync: - |releasecheck| make dist for release - |releasecheck| verify dist builds from source - |releasecheck| upgrade 'demo.taler.net' -- |releasecheck| run :doc:`demo upgrade checklist ` +- |releasecheck| run :doc:`demo upgrade checklist ` - |releasecheck| tag repo. - |releasecheck| use 'deployment.git/packaging/\*-docker/' to build Debian and Ubuntu packages - |releasecheck| upload packages to 'deb.taler.net' (note: only Florian/Christian can sign) @@ -83,7 +83,7 @@ For taler-twister: - |releasecheck| make dist for release. - |releasecheck| verify dist builds from source - |releasecheck| upgrade 'demo.taler.net' -- |releasecheck| run :doc:`demo upgrade checklist ` +- |releasecheck| run :doc:`demo upgrade checklist ` - |releasecheck| tag repo. - |releasecheck| Upload triplet to ftp-upload.gnu.org/incoming/ftp or /incoming/alpha @@ -92,7 +92,7 @@ For libeufin: - |releasecheck| update SPA of bank - |releasecheck| build libeufin - |releasecheck| upgrade 'demo.taler.net' -- |releasecheck| run :doc:`demo upgrade checklist ` +- |releasecheck| run :doc:`demo upgrade checklist ` - |releasecheck| make dist for release. - |releasecheck| verify dist builds from source - |releasecheck| tag repo. @@ -104,7 +104,7 @@ For libeufin: For Python merchant frontend: - |releasecheck| upgrade 'demo.taler.net' -- |releasecheck| run :doc:`demo upgrade checklist ` +- |releasecheck| run :doc:`demo upgrade checklist ` - |releasecheck| change 'demo.taler.net' deployment to use new tag. Wallet-core: @@ -122,14 +122,14 @@ Wallet-core: Android-Wallet: - |releasecheck| build wallet -- |releasecheck| run :doc:`demo upgrade checklist ` +- |releasecheck| run :doc:`demo upgrade checklist ` - |releasecheck| tag repo. - |releasecheck| upload new wallet release to app store Webextension-Wallet: - |releasecheck| build wallet -- |releasecheck| run :doc:`demo upgrade checklist ` +- |releasecheck| run :doc:`demo upgrade checklist ` - |releasecheck| tag repo. - |releasecheck| upload new wallet release to app store diff --git a/taler-auditor-manual.rst b/taler-auditor-manual.rst index bb8e7741..cbc2aeff 100644 --- a/taler-auditor-manual.rst +++ b/taler-auditor-manual.rst @@ -20,6 +20,10 @@ Auditor Operator Manual ####################### +.. contents:: Table of Contents + :depth: 1 + + Introduction ============ diff --git a/taler-developer-manual.rst b/taler-developer-manual.rst index 2e12f48a..1aa5cc8d 100644 --- a/taler-developer-manual.rst +++ b/taler-developer-manual.rst @@ -645,6 +645,11 @@ Developers and operators MUST NOT make changes to database schema outside of this versioning. All tables of a GNU Taler component should live in their own schema. +QA Plans +======== + +.. include:: checklists/qa-0.9.4.rst + Releases ======== diff --git a/taler-merchant-api-tutorial.rst b/taler-merchant-api-tutorial.rst index 2bb95457..02062464 100644 --- a/taler-merchant-api-tutorial.rst +++ b/taler-merchant-api-tutorial.rst @@ -22,6 +22,9 @@ Merchant API Tutorial ##################### +.. contents:: Table of Contents + :depth: 2 + Introduction ============ @@ -68,13 +71,8 @@ If you want to look at some simple, running examples, check out these: process. -.. contents:: Table of Contents - :maxdepth: 1 - :glob: - - Architecture overview -===================== +--------------------- The Taler software stack for a merchant consists of the following main components: diff --git a/taler-merchant-pos-terminal.rst b/taler-merchant-pos-terminal.rst index 1627cef8..3077b63f 100644 --- a/taler-merchant-pos-terminal.rst +++ b/taler-merchant-pos-terminal.rst @@ -27,8 +27,7 @@ The GNU Taler merchant point of sale (POS) App allows sellers to * let the customer make a Taler payment via QR code or NFC .. contents:: Table of Contents - :maxdepth: 1 - :glob: + :depth: 1 Android App diff --git a/taler-user-guide.rst b/taler-user-guide.rst index fbc3b1c6..a74eae22 100644 --- a/taler-user-guide.rst +++ b/taler-user-guide.rst @@ -19,6 +19,9 @@ User Guide ########## +.. contents:: Table of Contents + :depth: 1 + Introduction ============ @@ -38,12 +41,6 @@ an account at the bank. Some operations also require access to the merchant backend. -.. contents:: Table of Contents - :maxdepth: 1 - :glob: - - - Withdrawing from bank accounts ============================== -- cgit v1.2.3 From fde91a6d7c780ff2310567b7a3abcf97282fbbb1 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Sat, 2 Mar 2024 22:05:35 +0100 Subject: misc fixes --- core/api-challenger.rst | 1 + core/api-common.rst | 2 ++ core/api-mailbox.rst | 3 +++ core/api-sync.rst | 1 + core/api-taldir.rst | 2 ++ core/index.rst | 2 +- design-documents/046-mumimo-contracts.rst | 15 +++++---------- index.rst | 2 +- taler-auditor-manual.rst | 1 + taler-challenger-manual.rst | 5 +++++ taler-exchange-manual.rst | 3 ++- taler-merchant-api-tutorial.rst | 1 + taler-merchant-manual.rst | 3 ++- taler-merchant-pos-terminal.rst | 1 + taler-user-guide.rst | 1 + taler-wallet.rst | 4 ++++ 16 files changed, 33 insertions(+), 14 deletions(-) diff --git a/core/api-challenger.rst b/core/api-challenger.rst index 45fc5df8..914d8d01 100644 --- a/core/api-challenger.rst +++ b/core/api-challenger.rst @@ -88,6 +88,7 @@ Using the ``/info`` endpoint the client can then finally obtain the (now) verified address of the user. .. contents:: Table of Contents + :local: .. include:: tos.rst diff --git a/core/api-common.rst b/core/api-common.rst index bdf3ad81..51f2ab9f 100644 --- a/core/api-common.rst +++ b/core/api-common.rst @@ -24,6 +24,8 @@ Conventions for Taler RESTful APIs ================================== +.. contents:: Table of Contents + :local: ------------------------- HTTP Request and Response diff --git a/core/api-mailbox.rst b/core/api-mailbox.rst index 33db482d..34d27ded 100644 --- a/core/api-mailbox.rst +++ b/core/api-mailbox.rst @@ -29,6 +29,9 @@ for all details not specified in the individual requests. The `glossary `_ defines all specific terms used in this section. +.. contents:: Table of Contents + :local: + .. include:: tos.rst ------------------------- diff --git a/core/api-sync.rst b/core/api-sync.rst index 51d2b674..c2c86c23 100644 --- a/core/api-sync.rst +++ b/core/api-sync.rst @@ -103,6 +103,7 @@ user's location profiles by linking client IP addresses and client keys. .. contents:: Table of Contents + :local: .. include:: tos.rst diff --git a/core/api-taldir.rst b/core/api-taldir.rst index 1639e36d..4da9bb02 100644 --- a/core/api-taldir.rst +++ b/core/api-taldir.rst @@ -34,6 +34,8 @@ for all details not specified in the individual requests. The `glossary `_ defines all specific terms used in this section. +.. contents:: Table of Contents + :local: .. include:: tos.rst diff --git a/core/index.rst b/core/index.rst index d6a20244..8a764c10 100644 --- a/core/index.rst +++ b/core/index.rst @@ -32,7 +32,7 @@ protocols using JSON. .. toctree:: - :maxdepth: 2 + :maxdepth: 1 api-overview api-common diff --git a/design-documents/046-mumimo-contracts.rst b/design-documents/046-mumimo-contracts.rst index 5bc3d25a..fcb7f2b1 100644 --- a/design-documents/046-mumimo-contracts.rst +++ b/design-documents/046-mumimo-contracts.rst @@ -472,10 +472,7 @@ consumes an available discount token, that contract should be moved up in the list. Which specific alternative contract was chosen by the user is indicated in the -subcontract index field of the :ref:`TALER_DepositRequestPS`. - -FIXME-DOLD: Should we also sign over this in the -:ref:`TALER_DepositConfirmationPS`? +subcontract index field of the :ref:`TALER_DepositRequestPS `. Output Commitments @@ -483,8 +480,9 @@ Output Commitments When a contract has outputs, the wallet must send an array of blinded tokens, coins or tax receipts together with the payment request. The order in the -array must match the order in the outputs field of the contract. For currency outputs, one array element must include all of the required planchets for a batch withdrawal, -but of course not the reserve signature. +array must match the order in the outputs field of the contract. For currency +outputs, one array element must include all of the required planchets for a +batch withdrawal, but of course not the reserve signature. .. note:: @@ -492,10 +490,7 @@ but of course not the reserve signature. batch-withdraw API to only use a single reserve signature. This array of blinded values is hashed to create the output commitment hash -(``h_outputs``) in the :ref:`TALER_DepositRequestPS`. - -FIXME-DOLD: Should we also sign over this in the -:ref:`TALER_DepositConfirmationPS`? +(``h_outputs``) in the :ref:`TALER_DepositRequestPS `. diff --git a/index.rst b/index.rst index e97fe2b9..bd3b30d6 100644 --- a/index.rst +++ b/index.rst @@ -50,7 +50,7 @@ Documentation Overview .. toctree:: :numbered: - :maxdepth: 2 + :maxdepth: 1 core/index taler-user-guide diff --git a/taler-auditor-manual.rst b/taler-auditor-manual.rst index cbc2aeff..94e86a8d 100644 --- a/taler-auditor-manual.rst +++ b/taler-auditor-manual.rst @@ -22,6 +22,7 @@ Auditor Operator Manual .. contents:: Table of Contents :depth: 1 + :local: Introduction diff --git a/taler-challenger-manual.rst b/taler-challenger-manual.rst index 3e4871cb..a7a7169f 100644 --- a/taler-challenger-manual.rst +++ b/taler-challenger-manual.rst @@ -20,6 +20,11 @@ Challenger Operator Manual ########################## +.. contents:: Table of Contents + :depth: 2 + :local: + + Introduction ============ diff --git a/taler-exchange-manual.rst b/taler-exchange-manual.rst index dcbdba2c..57db7095 100644 --- a/taler-exchange-manual.rst +++ b/taler-exchange-manual.rst @@ -21,7 +21,8 @@ Exchange Operator Manual ######################## .. contents:: Table of Contents - :depth: 2 + :depth: 1 + :local: Introduction diff --git a/taler-merchant-api-tutorial.rst b/taler-merchant-api-tutorial.rst index 02062464..15e21e21 100644 --- a/taler-merchant-api-tutorial.rst +++ b/taler-merchant-api-tutorial.rst @@ -24,6 +24,7 @@ Merchant API Tutorial .. contents:: Table of Contents :depth: 2 + :local: Introduction ============ diff --git a/taler-merchant-manual.rst b/taler-merchant-manual.rst index 9925df0e..48605a55 100644 --- a/taler-merchant-manual.rst +++ b/taler-merchant-manual.rst @@ -22,7 +22,8 @@ Merchant Backend Operator Manual ################################ .. contents:: Table of Contents - :depth: 2 + :depth: 1 + :local: Introduction diff --git a/taler-merchant-pos-terminal.rst b/taler-merchant-pos-terminal.rst index 3077b63f..efc487cb 100644 --- a/taler-merchant-pos-terminal.rst +++ b/taler-merchant-pos-terminal.rst @@ -28,6 +28,7 @@ The GNU Taler merchant point of sale (POS) App allows sellers to .. contents:: Table of Contents :depth: 1 + :local: Android App diff --git a/taler-user-guide.rst b/taler-user-guide.rst index a74eae22..127218fb 100644 --- a/taler-user-guide.rst +++ b/taler-user-guide.rst @@ -21,6 +21,7 @@ User Guide .. contents:: Table of Contents :depth: 1 + :local: Introduction ============ diff --git a/taler-wallet.rst b/taler-wallet.rst index 5a10adc0..1d1a3991 100644 --- a/taler-wallet.rst +++ b/taler-wallet.rst @@ -19,6 +19,10 @@ Wallet Manual The GNU Taler wallet allows customers to withdraw and spend digital cash. +.. contents:: Table of Contents + :depth: 1 + :local: + WebExtension Wallet =================== -- cgit v1.2.3 From 1646c07abee282ce28e8bb4395dafb301beaf2db Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Sat, 2 Mar 2024 22:30:29 +0100 Subject: review QA plan --- checklists/qa-0.9.4.rst | 152 +++++++++++++++++++++++++++++------------------- 1 file changed, 91 insertions(+), 61 deletions(-) diff --git a/checklists/qa-0.9.4.rst b/checklists/qa-0.9.4.rst index 5f22e5a1..98680c8d 100644 --- a/checklists/qa-0.9.4.rst +++ b/checklists/qa-0.9.4.rst @@ -14,7 +14,7 @@ Platforms listed here are the officially supported platforms for this release. * Android * Google Play: https://play.google.com/store/apps/details?id=net.taler.wallet - * F-Droid: TBD + * F-Droid: https://f-droid.org/en/packages/net.taler.wallet.fdroid/ * APK Download: TBD * Browser @@ -25,10 +25,26 @@ Platforms listed here are the officially supported platforms for this release. * iOS +Running Deployments +=================== + +These deployments are maintained by us and should work for the release: + +* Sandcastle-based: + + * demo.taler.net + + * test.taler.net + +* Regio-based: + + * regio-taler.fdold.eu + + Wallet Flows ============ -* Bank-Integrated withdrawal +* Bank-integrated withdrawal * webext: "Continue with Mobile Wallet" flow @@ -38,124 +54,138 @@ Wallet Flows * Currency conversion withdrawal -* Peer Push Payments ("Send Money") +* Peer push payments ("Send Money") -* Peer Pull Payments ("Invoice") +* Peer pull payments ("Receive Money") -* Deposits +* Deposit into bank account * Check that deposit arrived -* Payment +* Payment at merchant * on blog merchant * on survey * directly initiated via merchant SPA * webext: "Pay with Mobile Wallet" flow -* Pay Templates +* Pay templates * Payment TOTP codes -* Exchange Management +* Exchange management - * Reloading Exchange Keys - * Deleting an Exchange + * Reloading exchange keys + * Deleting an exchange -Running Deployments +libeufin-bank Flows =================== -These deployments are maintained by us and should work for the release. +* Admin functionality -* Sandcastle-based: + * Login - * demo.taler.net + * Credential change - * test.taler.net + * Conversion settings -* Regio-Based: + * Bank account creation - * regio-taler.fdold.eu + * Test transfers +* Normal account functionality -Regio Deployment -================ + * Transfers -* Deployment Automation (deployment.git/regional-currency) + * Transfer to the exchange should bounce - * Test with Debian bookworm + * Withdrawals - * Test with Ubuntu (FIXME: Which versions?) + * (conversion-only): Test cash-in - * Check logs for errors + * (conversion-only): Test cash-out - * Test with telesign + * Lower cash-out limit enforced - * Set up EBICS integration + * 2FA for withdrawals, cash-out - * Check that ToS is configured -* Deployment Functionality +Merchant Backend SPA Flows +========================== - * All flows of the wallet should work +* Instance creation - * All flows of libeufin with regional currency shold work +* Simple bank account setup - * End-To-End conversion withdrawal and deposit with real money +* Order creation - * Check logs + * Pay order (with short wire transfer deadline) + * Check that money from order arrive at the bank with the right subject -libeufin-bank -============= +* Extended bank account setup -* Admin functionality + * Add Taler Bank Revenue API - * Login + * Check bank transfer list (for wire transfer of previously paid+wired order) - * Credential change + * Check order payment status goes to "final" automatically - * Conversion settings +* TOTP Device Management - * Bank account creation + * Add device - * Test transfers + * Edit device (set new secret, export new secret as QR code) -* Normal account functionality + * Delete device - * Transfers +* Templates - * Transfer to the exchange should bounce + * Add template - * Withdrawals + * Edit template - * (conversion-only): Test cash-in + * Add TOTP device to template - * (conversion-only): Test cash-out + * Edit TOTP device associated with template - * 2FA for withdrawals, cash-out + * Pay template + * Check TOTP code matches -Merchant Backend SPA -==================== + * Remove TOTP device from template -* Instance creation + * Delete template -* Bank Account Setup -* Order Creation -* Templates +Regio Deployment +================ -* TOTP Device Management +* Deployment Automation (deployment.git/regional-currency) + + * Test with Debian bookworm + + * Test with Ubuntu mantic + + * Check logs for errors + + * Test with telesign (SMS) - * Also test together with Templates + * Set up EBICS integration + + * Check that ToS is configured + +* Deployment Functionality -* Setup up Taler Bank Revenue API + * All flows of the wallet should work (see ``Wallet Flows`` above) -* Check that money from order arrive at the bank - with the right subject. + * All flows of libeufin-bank should work (see ``libeufin-bank Flows`` above) + + * Merchant backend should work (see ``Merchant Backend SPA Flows`` above) + + * Check logs Android Merchant PoS @@ -170,7 +200,6 @@ Android Cashier App * Test against demo.taler.net - CI == @@ -187,13 +216,14 @@ Debian Repository * supported codename(s): bookworm -* Ubuntu: +* Ubuntu: * repo at https://deb.taler.net/apt/ubuntu/ * supported codename(s): mantic + GNU Release =========== -* Release Announcement -* FTP Upload +* Release announcement +* FTP upload -- cgit v1.2.3 From b517fcdf4808d18e3ecaf16946de9fe17cf35485 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Sat, 2 Mar 2024 22:48:23 +0100 Subject: spec merchant api v10, see #8357 --- core/api-merchant.rst | 60 +++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 49 insertions(+), 11 deletions(-) diff --git a/core/api-merchant.rst b/core/api-merchant.rst index d3044505..24a9a29e 100644 --- a/core/api-merchant.rst +++ b/core/api-merchant.rst @@ -123,7 +123,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 **9**. + This specification corresponds to ``current`` protocol being version **10**. **Response:** @@ -142,7 +142,7 @@ such as the implemented version of the protocol and the currency used. name: "taler-merchant"; // URN of the implementation (needed to interpret 'revision' in version). - // @since v8, may become mandatory in the future. + // @since **v8**, may become mandatory in the future. implementation?: string; // Default (!) currency supported by this backend. @@ -166,7 +166,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 protocol **v6**. exchanges: ExchangeConfigInfo[]; } @@ -412,7 +412,7 @@ Querying payment status merchant backend may return a response immediately. :query await_refund_obtained=BOOLEAN: *Optional*. If set to "yes", poll for the order's pending refunds to be picked up. ``timeout_ms`` specifies how long we will wait for the refund. :query refund=AMOUNT: *Optional*. Indicates that we are polling for a refund above the given AMOUNT. ``timeout_ms`` will specify how long we will wait for the refund. - :query allow_refunded_for_repurchase: *Optional*. Since protocol v9 refunded orders are only returned under "already_paid_order_id" if this flag is set explicitly to "YES". + :query allow_refunded_for_repurchase: *Optional*. Since protocol **v9** refunded orders are only returned under "already_paid_order_id" if this flag is set explicitly to "YES". **Response:** @@ -1937,7 +1937,7 @@ Creating orders // The session for which the payment is made (or replayed). // Only set for session-based payments. - // Since protocol v6. + // Since protocol **v6**. session_id?: string; // Specifies that some products are to be included in the @@ -2070,8 +2070,8 @@ Inspecting orders :query date_s: *Optional.* Non-negative date in seconds after the UNIX Epoc, see ``delta`` for its interpretation. If not specified, we default to the oldest or most recent entry, depending on ``delta``. :query start: *Optional*. Row number threshold, see ``delta`` for its interpretation. Defaults to ``INT64_MAX``, namely the biggest row id possible in the database. :query timeout_ms: *Optional*. Timeout in milliseconds to wait for additional orders if the answer would otherwise be negative (long polling). Only useful if delta is positive. Note that the merchant MAY still return a response that contains fewer than ``delta`` orders. - :query session_id: *Optional*. Since protocol v6. Filters by session ID. - :query fulfillment_url: *Optional*. Since protocol v6. Filters by fulfillment URL. + :query session_id: *Optional*. Since protocol **v6**. Filters by session ID. + :query fulfillment_url: *Optional*. Since protocol **v6**. Filters by fulfillment URL. **Response:** @@ -2128,9 +2128,9 @@ Inspecting orders **Request:** :query session_id: *Optional*. Session ID that the payment must be bound to. If not specified, the payment is not session-bound. - :query transfer: *Deprecated in protocol V6*. *Optional*. If set to "YES", try to obtain the wire transfer status for this order from the exchange. Otherwise, the wire transfer status MAY be returned if it is available. + :query transfer: Deprecated in protocol **V6**. *Optional*. If set to "YES", try to obtain the wire transfer status for this order from the exchange. Otherwise, the wire transfer status MAY be returned if it is available. :query timeout_ms: *Optional*. Timeout in milliseconds to wait for a payment if the answer would otherwise be negative (long polling). - :query allow_refunded_for_repurchase: *Optional*. Since protocol v9 refunded orders are only returned under "already_paid_order_id" if this flag is set explicitly to "YES". + :query allow_refunded_for_repurchase: *Optional*. Since protocol **v9** refunded orders are only returned under "already_paid_order_id" if this flag is set explicitly to "YES". **Response:** @@ -2193,7 +2193,7 @@ Inspecting orders // Reports about trouble obtaining wire transfer details, // empty array if no trouble were encountered. - // @deprecated in protocol v6 + // @deprecated in protocol **v6**. wire_reports: TransactionWireReport[]; // The refund details for this order. One entry per @@ -2638,7 +2638,7 @@ to validate that a customer made a payment. // "NONE" or 0: No algorithm (no pos confirmation will be generated) // "TOTP_WITHOUT_PRICE" or 1: Without amounts (typical OTP device) // "TOTP_WITH_PRICE" or 2: With amounts (special-purpose OTP device) - // The "String" variants are supported @since protocol v7. + // The "String" variants are supported @since protocol **v7**. otp_algorithm: Integer | string; // Counter for counter-based OTP devices. @@ -2720,6 +2720,17 @@ to validate that a customer made a payment. This is used to obtain detailed information about a specific OTP device. + The client can provide additional inputs in the query to allow the backend + to compute and return a sample OTP code. Note that it is not an error if + the client provides query arguments that are not being used *or* that are + insufficient for the server to compute the ``otp_code``: If the client + provides inadequate query parameters, the ``otp_code`` is simply omitted + from the response. + + **Query:** + + :query faketime=TIMESTAMP: *Optional*. Timestamp in seconds to use when calculating the current OTP code of the device. Since protocol **v10**. + :query price=AMOUNT: *Optional*. Price to use when calculating the current OTP code of the device. Since protocol **v10**. **Response:** @@ -2737,11 +2748,38 @@ to validate that a customer made a payment. device_description: string; // Algorithm for computing the POS confirmation. + // + // Currently, the following numbers are defined: + // 0: None + // 1: TOTP without price + // 2: TOTP with price otp_algorithm: Integer; // Counter for counter-based OTP devices. otp_ctr?: Integer; + // Current OTP code of the device. + // + // If the ``otp_algorithm`` is time-based, the code is + // returned for the current time, or for the ``faketime`` + // if a TIMESTAMP query argument was provided by the client. + // + // When using OTP with counters, the counter is **NOT** + // increased merely because this endpoint created + // an OTP code (this is a GET request, after all!). + // + // If the ``otp_algorithm`` requires an amount, the + // ``amount`` argument must be specified in the + // query, otherwise the ``otp_code`` is not + // generated. + // + // This field is *optional* in the response, as it is + // only provided if we could compute it based on the + // ``otp_algorithm`` and matching client query arguments. + // + // Available since protocol **v10**. + otp_code?: Integer; + } .. http:delete:: [/instances/$INSTANCE]/private/otp-devices/$DEVICE_ID -- cgit v1.2.3 From c54c4c15ebb35282c4107f81a002ee97c428caea Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Sat, 2 Mar 2024 22:49:42 +0100 Subject: spec merchant api v10, see #8357 --- core/api-merchant.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/core/api-merchant.rst b/core/api-merchant.rst index 24a9a29e..ca0cd351 100644 --- a/core/api-merchant.rst +++ b/core/api-merchant.rst @@ -2758,6 +2758,12 @@ to validate that a customer made a payment. // Counter for counter-based OTP devices. otp_ctr?: Integer; + // Current time for time-based OTP devices. + // Will match the ``faketime`` argument of the + // query if one was present, otherwise the current + // time at the backend. + otp_timestamp?: Integer; + // Current OTP code of the device. // // If the ``otp_algorithm`` is time-based, the code is -- cgit v1.2.3 From 5cebfc318511380fdb40aa63f112886045e4828a Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Sun, 3 Mar 2024 11:37:24 +0100 Subject: improve v10 spec --- core/api-merchant.rst | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/core/api-merchant.rst b/core/api-merchant.rst index ca0cd351..00e4a7f6 100644 --- a/core/api-merchant.rst +++ b/core/api-merchant.rst @@ -2762,9 +2762,14 @@ to validate that a customer made a payment. // Will match the ``faketime`` argument of the // query if one was present, otherwise the current // time at the backend. - otp_timestamp?: Integer; + // + // Available since protocol **v10**. + otp_timestamp: Integer; - // Current OTP code of the device. + // Current OTP confirmation string of the device. + // Matches exactly the string that would be returned + // as part of a payment confirmation for the given + // amount and time (so may contain multiple OTP codes). // // If the ``otp_algorithm`` is time-based, the code is // returned for the current time, or for the ``faketime`` @@ -2784,7 +2789,7 @@ to validate that a customer made a payment. // ``otp_algorithm`` and matching client query arguments. // // Available since protocol **v10**. - otp_code?: Integer; + otp_code?: String; } -- cgit v1.2.3 From 3aa55f2b2bcd6aa28b2a85da2a9fe75c02b6d20b Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Tue, 5 Mar 2024 10:15:43 +0100 Subject: elaborate on account restrictions --- libeufin/regional-custom-manual.rst | 20 ++++++++++++++++---- 1 file changed, 16 insertions(+), 4 deletions(-) diff --git a/libeufin/regional-custom-manual.rst b/libeufin/regional-custom-manual.rst index a6060586..8477c18d 100644 --- a/libeufin/regional-custom-manual.rst +++ b/libeufin/regional-custom-manual.rst @@ -94,12 +94,24 @@ the possibility of currency conversion (cash in): enable-account \ payto://iban/$IBAN?receiver-name=$NAME \ conversion-url "$CONVERSION_URL" \ - # restrictions ... + debit-restriction \ + deny \ + credit-restriction \ + regex \ + 'payto://iban/.*/CH.*?receiver-name=.*' \ + 'Swiss only' \ + '{ "de" : "nur Schweiz", \ + "fr" : "Suisse uniquement" }' upload Here, the ``$CONVERSION_URL`` must be set to the base URL of the conversion -endpoint of the bank, which should be ``https://bank.$DOMAIN/conversion-info/`` -in our setup. +endpoint of the bank, which should be +``https://bank.$DOMAIN/conversion-info/`` in our setup. Note that you can +leave out the "credit-restriction" if you want to allow international inbound +wire transfers. The "debit-restriction" is largely mandatory as in this setup +the taler-exchange-transfer is only configured to deal with the regional +currency bank. Crediting fiat bank accounts must thus be done via the +cash-out functionality of the regional currency bank account. .. note:: @@ -149,4 +161,4 @@ Make sure to restart taler-exchange after changing these configuration options: # systemctl restart taler-exchange.target -.. include:: ../frags/regional-manual-use.rst \ No newline at end of file +.. include:: ../frags/regional-manual-use.rst -- cgit v1.2.3 From a57cdcc3e645276f1df4c232de82ad00a9c4cf4e Mon Sep 17 00:00:00 2001 From: Florian Dold Date: Tue, 5 Mar 2024 11:24:58 +0100 Subject: delete DD --- design-documents/index.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/design-documents/index.rst b/design-documents/index.rst index 03448acb..454564d0 100644 --- a/design-documents/index.rst +++ b/design-documents/index.rst @@ -67,5 +67,4 @@ Design documents that start with "XX" are considered deprecated. 053-wallet-ui.rst 054-dynamic-form.rst 055-wallet-problem-report.rst - 056-wallet-activity-diagnostics.rst 999-template -- cgit v1.2.3 From 087521ae8fab8f1bb4b847e09cb961afb9572ddb Mon Sep 17 00:00:00 2001 From: Javier Sepulveda Date: Tue, 5 Mar 2024 13:51:33 +0100 Subject: Draft information text for current server monitoring tools --- taler-monitoring-infrastructure.rst | 197 ++++++++++++++++++++++++++++++++++++ 1 file changed, 197 insertions(+) create mode 100644 taler-monitoring-infrastructure.rst diff --git a/taler-monitoring-infrastructure.rst b/taler-monitoring-infrastructure.rst new file mode 100644 index 00000000..3b809fb3 --- /dev/null +++ b/taler-monitoring-infrastructure.rst @@ -0,0 +1,197 @@ +.. + This file is part of GNU TALER. + + Copyright (C) 2014-2023 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 + + @author Javier Sepulveda +.. _taler-merchant-monitoring: + +GNU Taler monitoring +#################### + +.. image:: images/taler-monitoring-infrastructure.png + +In order to check the availability of our server infrastructure, we use the Grafana and Uptime KUMA monitoring programs. + +On the one hand Grafana let us to see *graphically* the server consumption resources, and even alert us of some specific situations. +On the other hand with a more basic tool such as Uptime KUMA (which does mostly ping and https checks), +we get the very first status information, as the very first countermeasure. + +Grafana +======= + +- Our grafana instance can be reached at https://grafana.taler.net + +User accounts: +-------------- + +We have only two main user accounts: + +- One "admin" account for server administrators. +- One general "read-only" account, for the rest of the team. + +How to install Grafana +---------------------- + +Please refer to the Grafana official website for installation instructions for your specific operating system. For the +specific case of the GNU/Linux distribution Debian 12 (bookworm), you can use the next set of instructions. + +.. code-block:: console + + # apt-get install -y apt-transport-https + # apt-get install -y software-properties-common wget + # wget -q -O /usr/share/keyrings/grafana.key https://apt.grafana.com/gpg.key + # echo "deb [signed-by=/usr/share/keyrings/grafana.key] https://apt.grafana.com stable main" | tee -a /etc/apt/sources.list.d/grafana.list + # apt update + # apt-get install grafana + # systemctl daemon-reload + # systemctl enable --now grafana-server + +.. note:: + + If you want to deploy grafana automatically, and if you have access to the --private git repository "migration-exercise-stable.git", + please clone it, and execute from Grafana subfolder the grafana.sh file. This script will install for you Grafana and will leave it up and running on port 3000 of your server. + +Grafana Dashboards +------------------ + +As we understand creating tailored Grafana dashboards, is very time consuming thing to do, and in the top of that +you really have to to be very proficient to do that, we use the available and pre-built `Grafana dashboards `_, which eventually we can also tweak a little, to fit our needs. + +Node Exporter +++++++++++++++ + +- More information can be found on the `Node Exporter `_ website. +- Dashboard ID: 1860 + +.. note:: + + If you want to deploy Postgres Exporter automatically and have access to the --private git repository "migration-exercise-stable.git", please clone it, + and execute from the subfolder taler.net/grafana/node-exporter.sh, this script will install for you Node Exporter and will leave it running on port 9100. + This script also will create, start, and enable on reboot a new service. + +Postgres Exporter ++++++++++++++++++ + +- More information can be found on the `PostgreSQL exporter `_ website. +- Dashboard ID: 12485 + +.. image:: images/grafana-postgres-exporter.png + +.. note:: + + If you want to deploy Postgres Exporter automatically and have access to the --private git repository "migration-exercise-stable.git", please clone it, + and execute from the subfolder taler.net/grafana/postgres-exporter.sh, this script will install for you Grafana and will leave it running on port 9187. + +Uptime Kuma from Grafana +++++++++++++++++++++++++ + +This is an easy to way to integrate all monitored websites from Uptime Kuma, into Grafana. Thus, +from the same place (Grafana), you can check also the status of the website and the expiration date of the +certificates. + +- More information can be found on the `Uptime Kuma for Grafana `_ website. +- Dashboard ID: 18278 + +.. image:: images/uptime-kuma-from-grafana.png + +Grafana Data Sources +--------------------- +As a data source connector we use Prometheus. + +Prometheus +++++++++++ +More information can be found in the `Grafana and Prometheus `_ website. + +.. note:: + + If you want to deploy Prometheus automatically and have access to the --private git repository "migration-exercise-stable.git", please clone it, + and execute from the subfolder taler.net/grafana/prometheus.sh, this script will install for you Grafana and will leave it running on port 9090. + +Managing logs +------------- + +In order to manage logs, we use Loki + Promtail (Debian packages), which are very easy to integrate with Grafana and Prometheus. + +.. code-block:: console + + # Install + # apt-get install loki promtail + # Start services + # systemctl start loki promtail + # Enable services on reboot + # systemctl enable loki + # systemctl enable promtail + +Loki and Promtail services in Grafana +---------------------------------------------- + +1) Make sure you have prometheus running on port 9090 +2) Make sure you have loki running on port 3100 + +.. code-block:: console + + systemctl status prometheus loki + + +.. note:: + + We still don't have Loki and Promtail installed in production (taler.net), and neither + configured to track certain log files. + +Grafana Alerting +---------------- + +#. In order to use the Grafana alerting system rules, you need first to configure working SMTP service of your server. +#. Once you have done the necessary changes on the Grafana configuration file, you have to either restart or reload the "grafana-server" service with the systemctl command as usual. +#. Then go to the Grafana admin panel Alerting -> Contact points, and within the email address you are using for this purpose, check if SMTP is indeed working by pressing the "test" button. +#. If that works, you will receive an email in your mailbox with the Grafana logo confirming that the server can satisfactorily send email messages. + + +Uptime Kuma +=========== + +- URL: http://139.162.254.179:3001/dashboard +- Users: One single administration account with full privileges. +- Installation: With Docker + +.. image:: images/kuma.png + +.. note:: + + 1) In order to guarantee the KUMA is doing its work, it needs to be install 100% externally from the servers you want to monitor. (Server Kuma 1) + 2) Also, it is important to monitor the KUMA server itself, so you don't endup without a monitoring system. (Server Kuma 2) + +In our case, we do both. We have the two Uptime KUMA servers completely outside our server infrastructure, so one monitors the other, and +the latter one, monitors our own Taler servers. + +Kuma monitor types +------------------- + +Kuma counts with quite a few monitor types, such as https, TCP port or ping. In our case, we use mainly https requests, +and pings, to make sure as a first check that our servers are responsive. + +Another handy feature that Kuma has, is the "Certificate Expiry Notification feature, which we also use, and eventually warn us about a certificate +expiration dates. + +So in brief in our KUMA main server, we use these 3 monitor types (ping,https,certificate expiration) for each website that we monitor. + +Exceptionally for additional notifications, and specifically due of the importance of the Taler Operations server, +we use in addition SMS notifications (clicksend provider). This way in case of KUMA detecting the Taler Operations unavailability, +a SMS message will be sent to at the very least two persons from the deployment and operations department. + +How to edit notifications: + +.. image:: images/uptime-kuma-edit.png + -- cgit v1.2.3 From 2a889111cf080943bd4cac544e1247b4a4f4d429 Mon Sep 17 00:00:00 2001 From: Antoine A <> Date: Tue, 5 Mar 2024 17:47:55 +0100 Subject: update corebank API --- core/api-corebank.rst | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/core/api-corebank.rst b/core/api-corebank.rst index fa137a22..c3f835ad 100644 --- a/core/api-corebank.rst +++ b/core/api-corebank.rst @@ -83,6 +83,11 @@ Config // The format is "current:revision:age". version: string; + // Bank display name to be used in user interfaces. + // For consistency use "Taler Bank" if missing. + // @since v4, will become mandatory in the next version. + bank_name?: string; + // If 'true' the server provides local currency conversion support // If 'false' some parts of the API are not supported and return 501 allow_conversion: boolean; @@ -117,7 +122,7 @@ Config // Wire transfer type supported by the bank. // Default to 'iban' is missing - // @since v4, may become mandatory in the future. + // @since v4, will become mandatory in the next version. wire_type?: string; } @@ -384,7 +389,7 @@ Account Management is_taler_exchange: boolean; // Opaque unique ID used for pagination. - // @since v4, will become mandatory in the future. + // @since v4, will become mandatory in the next version. row_id?: Integer; } @@ -457,7 +462,7 @@ Account Management is_taler_exchange: boolean; // Opaque unique ID used for pagination. - // @since v4, will become mandatory in the future. + // @since v4, will become mandatory in the next version. row_id?: Integer; } -- cgit v1.2.3 From 6f4f2ca7ef5cea652417ba56bc0eb61ec9c792f5 Mon Sep 17 00:00:00 2001 From: Antoine A <> Date: Tue, 5 Mar 2024 17:58:57 +0100 Subject: update corebank API --- core/api-corebank.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/core/api-corebank.rst b/core/api-corebank.rst index c3f835ad..e1cb4fb6 100644 --- a/core/api-corebank.rst +++ b/core/api-corebank.rst @@ -507,8 +507,8 @@ Account Management // as well. contact_data?: ChallengeContactData; - // IBAN 'payto' URI pointing the bank account - // where to send cashouts. This field is optional + // IBAN 'payto' URI with a 'receiver-name' parameter of a fiat bank + // account where to send cashouts. This field is optional // because not all the accounts are required to participate // in the merchants' circuit. One example is the exchange: // that never cashouts. Registering these accounts can -- cgit v1.2.3 From 5fe272750cf8986c9cab004d508da13b623112e2 Mon Sep 17 00:00:00 2001 From: Florian Dold Date: Tue, 5 Mar 2024 21:49:32 +0100 Subject: dd55 --- design-documents/055-wallet-problem-report.rst | 33 ++++++++++++++++++++++++-- 1 file changed, 31 insertions(+), 2 deletions(-) diff --git a/design-documents/055-wallet-problem-report.rst b/design-documents/055-wallet-problem-report.rst index 84c6159a..2fd7a221 100644 --- a/design-documents/055-wallet-problem-report.rst +++ b/design-documents/055-wallet-problem-report.rst @@ -5,6 +5,11 @@ DD 55: Wallet Problem Reports **Status**: Early work in progress / DD number reservation. +.. warning:: + + We concluded that we don't need the problem reports feature right now, + as all cases we care about are already covered by something else. + Summary ======= @@ -52,13 +57,35 @@ New wallet-core notification type Types of reports ---------------- +(Currently we don't have any good examples where this is actually needed.) + +Examples of what should NOT be a report +--------------------------------------- + * money lost due to the exchange stopping to offer a denomination + + * => Should be a transactions item + * money locked behind a (long) pending refresh + + * => Should be a pending transaction + * money lost due to a permanently failing refresh + + * => pending or final transaction item + * money lost due to expired denominations (auto-refresh wasn't done fast enough) -* exchange changed its master public key + + * => transaction item + * a denomination changed its info (expiration, fees) + * => exchange entry state + +* Important information about the exchange changed (master pub, accounts, keys) + + => exchange entry state + Definition of Done ================== @@ -68,7 +95,9 @@ TBD. Alternatives ============ -TBD. +* Report problems with an API specific to each resource (exchange entry, transaction, ...) +* Have an *alerts* API that returns alerts to the client that the client can show to to the user, + but that a user can't interact with. Drawbacks ========= -- cgit v1.2.3 From 9d329e9f27894c62e390c4eea37533e9679911df Mon Sep 17 00:00:00 2001 From: Christian Blättler Date: Tue, 5 Mar 2024 22:12:10 +0100 Subject: dd46: remove old TODO --- design-documents/046-mumimo-contracts.rst | 2 -- 1 file changed, 2 deletions(-) diff --git a/design-documents/046-mumimo-contracts.rst b/design-documents/046-mumimo-contracts.rst index fcb7f2b1..b76d1539 100644 --- a/design-documents/046-mumimo-contracts.rst +++ b/design-documents/046-mumimo-contracts.rst @@ -62,8 +62,6 @@ We want Taler to support various interesting use-cases: acquired (i.e., not brought from home or stolen from a stack of dirty items) and incentivizes return after use. -TODO: add more use-cases here! - Proposed Solution ================= -- cgit v1.2.3 From a018517be52b08a20cfeed20f8416cd33f4974e5 Mon Sep 17 00:00:00 2001 From: Christian Blättler Date: Tue, 5 Mar 2024 22:13:17 +0100 Subject: dd46: syntax fixes --- design-documents/046-mumimo-contracts.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/design-documents/046-mumimo-contracts.rst b/design-documents/046-mumimo-contracts.rst index b76d1539..9c693b01 100644 --- a/design-documents/046-mumimo-contracts.rst +++ b/design-documents/046-mumimo-contracts.rst @@ -210,7 +210,7 @@ The contract terms v1 will have the following structure: // Maximum wire fee accepted by the merchant (customer share to be // divided by the ``wire_fee_amortization`` factor, and further reduced // if deposit fees are below ``max_fee``). Default if missing is zero. - max_wire_fee: Amount; + max_wire_fee?: Amount; // Over how many customer transactions does the merchant expect to // amortize wire fees on average? If the exchange's wire fee is @@ -220,7 +220,7 @@ The contract terms v1 will have the following structure: // between the ``max_fee`` and the sum of the actual deposit fees. // Optional, default value if missing is 1. 0 and negative values are // invalid and also interpreted as 1. - wire_fee_amortization: number; + wire_fee_amortization?: number; // Exchanges that the merchant accepts for this currency. exchanges: Exchange[]; @@ -269,15 +269,15 @@ The contract terms v1 will have the following structure: // Map from authority labels to meta data abou the // respective token authority. - token_types: { [authority_label: TokenAuthority }; + token_types: { [authority_label: string]: TokenAuthority }; } .. ts:def:: ContractInput type ContractInput = - | ContractInputRation - | ContractInputToken; + ContractInputRation | + ContractInputToken; .. ts:def:: ContractInputRation @@ -450,8 +450,8 @@ The contract terms v1 will have the following structure: .. ts:def:: TokenSignerPublicKey type TokenSignerPublicKey = - | DenomGroupRsa - | DenomGroupCs; + DenomGroupRsa | + DenomGroupCs; TODO: may want to do a deep copy and rename DenomGroup* to TokenSignerPublicKey* here. -- cgit v1.2.3 From 9b0678d5fb4b7ffafae92539797858a84680c656 Mon Sep 17 00:00:00 2001 From: Christian Blättler Date: Tue, 5 Mar 2024 22:13:54 +0100 Subject: dd46: shared type TokenClass for input and output tokens --- design-documents/046-mumimo-contracts.rst | 54 +++++++++++++++++-------------- 1 file changed, 29 insertions(+), 25 deletions(-) diff --git a/design-documents/046-mumimo-contracts.rst b/design-documents/046-mumimo-contracts.rst index 9c693b01..5f1d1d98 100644 --- a/design-documents/046-mumimo-contracts.rst +++ b/design-documents/046-mumimo-contracts.rst @@ -188,7 +188,7 @@ The contract terms v1 will have the following structure: extra?: any; // Fee limits and wire account details by currency. - limits: { [currency:string] : CurrencyLimit }; + limits: { [currency: string]: CurrencyLimit }; } .. ts:def:: CurrencyLimit @@ -303,9 +303,9 @@ The contract terms v1 will have the following structure: type: "token"; - // Hash over the public key used to sign the - // type of subscription token required. - h_issuer: HashCode; + // Label of the token authority in the + // 'token_types' map on the top-level. + authority_label: string; // Number of tokens of this type required. // Defaults to one if the field is not provided. @@ -316,17 +316,17 @@ The contract terms v1 will have the following structure: .. ts:def:: ContractOutput type ContractOutput = - | ContractOutputCurrency - | ContractOutputTaxReceipt - | ContractOutputToken; + ContractOutputCoin | + ContractOutputTaxReceipt | + ContractOutputToken; -.. ts:def:: ContractOutputCurrency +.. ts:def:: ContractOutputCoin - interface ContractOutputCurrency { + interface ContractOutputCoin { - type: "currency"; + type: "coins"; - // Amount of currency that will be yielded. + // Amount of coins that will be yielded. // This excludes any applicable withdraw fees. brutto_yield: Amount; @@ -358,24 +358,21 @@ The contract terms v1 will have the following structure: // 'token_types' map on the top-level. authority_label: string; - // Must a wallet understand this token type to - // process contracts that consume or yield it? - critical: boolean; + // Number of tokens to be yelded. + // Defaults to one if the field is not provided. + number?: Integer; - // Information about the class of token that will - // be yielded. - details: OutputTokenClass; } -.. ts:def:: OutputTokenClass +.. ts:def:: TokenClass - type OutputTokenClass = - | OutputTokenClassSubscription - | OutputTokenClassDiscount + type TokenClass = + TokenClassSubscription + | TokenClassDiscount -.. ts:def:: OutputTokenClassSubscription +.. ts:def:: TokenClassSubscription - interface OutputTokenClassSubscription { + interface TokenClassSubscription { class: "subscription"; @@ -394,9 +391,9 @@ The contract terms v1 will have the following structure: }; -.. ts:def:: OutputTokenClassDiscount +.. ts:def:: TokenClassDiscount - interface OutputTokenClassDiscount { + interface TokenClassDiscount { class: "discount"; @@ -431,6 +428,13 @@ The contract terms v1 will have the following structure: // When will tokens signed by this key expire? token_expiration: Timestamp; + // Class-specific information of the token + details: TokenClass; + + // Must a wallet understand this token type to + // process contracts that consume or yield it? + critical: boolean; + // Number of tokens issued according to ASS authority // FIXME: this is still rather speculative in the design... ass?: Integer; -- cgit v1.2.3 From 05edb08e886c55dd9200a42e52e1bcb7007d13f4 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Tue, 5 Mar 2024 22:47:11 +0100 Subject: document new ADDRESS_RESTRICTIONS regex option --- manpages/challenger.conf.5.rst | 2 ++ taler-challenger-manual.rst | 3 ++- 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/manpages/challenger.conf.5.rst b/manpages/challenger.conf.5.rst index a46b8461..66c46e80 100644 --- a/manpages/challenger.conf.5.rst +++ b/manpages/challenger.conf.5.rst @@ -71,6 +71,8 @@ AUTH_COMMAND ADDRESS_TYPE Type of the address that is being collected, returned as part of the ``address_type`` in the ``/info`` endpoint. Examples include ``email`` or ``phone``. +ADDRESS_RESTRICTIONS + JSON object with a map of keys (names of the fields of the address to be entered by the user) to objects with a "regex" (string) containing an extended Posix regular expression for allowed address field values, and a "hint"/"hint_i18n" giving a human-readable explanation to display if the value entered by the user does not match the regex. Keys that are not mapped to such an object have no restriction on the value provided by the user. Examples would be '{"email":{"hint":"valid e-mail address required","regex":"^[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+\.[a-zA-Z0-9-.]+$"}' or '{"zip":{"hint":"numeric zip code required","regex":"^[0-9]+$"}'. SEE ALSO diff --git a/taler-challenger-manual.rst b/taler-challenger-manual.rst index a7a7169f..39b06710 100644 --- a/taler-challenger-manual.rst +++ b/taler-challenger-manual.rst @@ -1,7 +1,7 @@ .. This file is part of GNU TALER. - Copyright (C) 2023 Taler Systems SA + Copyright (C) 2023, 2024 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 @@ -558,6 +558,7 @@ file) is also supported. The template is instantiated using the following information: + * restrictions: Object; map of keys (names of the fields of the address to be entered by the user) to objects with a "regex" (string) containing an extended Posix regular expression for allowed address field values, and a "hint"/"hint_i18n" giving a human-readable explanation to display if the value entered by the user does not match the regex. Keys that are not mapped to such an object have no restriction on the value provided by the user. See "ADDRESS_RESTRICTIONS" in the challenger configuration. * fix_address: boolean; indicates if the given address cannot be changed anymore, the form should be read-only if set to true. -- cgit v1.2.3 From 126747a0d078626a221ccf96447b1f0e1988b50c Mon Sep 17 00:00:00 2001 From: Sebastian Date: Wed, 6 Mar 2024 14:56:01 -0300 Subject: screens from wallet webex --- .../webex-wallet/1-wallet-installed.png | Bin 0 -> 57887 bytes .../webex-wallet/add-exchange/1-balance.png | Bin 0 -> 30910 bytes .../add-exchange/10-testkudos-in-the-list.png | Bin 0 -> 32709 bytes .../add-exchange/11-select-test-kudos.png | Bin 0 -> 49363 bytes .../webex-wallet/add-exchange/2-click-get-cash.png | Bin 0 -> 36330 bytes .../add-exchange/3-click-add-exchange.png | Bin 0 -> 42139 bytes .../webex-wallet/add-exchange/4-input-URL.png | Bin 0 -> 56001 bytes .../webex-wallet/add-exchange/5-click-next.png | Bin 0 -> 37919 bytes .../webex-wallet/add-exchange/6-review-tos.png | Bin 0 -> 72501 bytes .../webex-wallet/add-exchange/7-accept-tos.png | Bin 0 -> 37051 bytes .../webex-wallet/add-exchange/8-confirm.png | Bin 0 -> 30910 bytes .../webex-wallet/add-exchange/9-click-get-cash.png | Bin 0 -> 36330 bytes .../webex-wallet/deposit/1-balance.png | Bin 0 -> 35087 bytes .../webex-wallet/deposit/10-balance.png | Bin 0 -> 47824 bytes .../webex-wallet/deposit/2-click-send.png | Bin 0 -> 47464 bytes .../webex-wallet/deposit/3-click-deposit.png | Bin 0 -> 35569 bytes .../webex-wallet/deposit/4-click-add-account.png | Bin 0 -> 54335 bytes .../webex-wallet/deposit/5-complete-form.png | Bin 0 -> 60639 bytes .../webex-wallet/deposit/6-click-add.png | Bin 0 -> 59490 bytes .../webex-wallet/deposit/7-confirm-deposit.png | Bin 0 -> 60419 bytes .../webex-wallet/deposit/8-show-transaction.png | Bin 0 -> 65622 bytes .../deposit/9-after-deposit-confirmed.png | Bin 0 -> 76645 bytes .../wallet-screenshots/webex-wallet/dev-tools.png | Bin 0 -> 95380 bytes .../webex-wallet/invoice/1-balance.png | Bin 0 -> 36026 bytes .../webex-wallet/invoice/10-confirm-transfer.png | Bin 0 -> 55732 bytes .../webex-wallet/invoice/11-show-history.png | Bin 0 -> 49646 bytes .../webex-wallet/invoice/2-click-add.png | Bin 0 -> 48365 bytes .../webex-wallet/invoice/3-input-six.png | Bin 0 -> 48827 bytes .../webex-wallet/invoice/4-click-invoice.png | Bin 0 -> 62019 bytes .../webex-wallet/invoice/5-complete-form.png | Bin 0 -> 64943 bytes .../webex-wallet/invoice/6-create-invoice.png | Bin 0 -> 73127 bytes .../webex-wallet/invoice/7-copy-qr-open-qr-page.png | Bin 0 -> 48070 bytes .../webex-wallet/invoice/8-paste-URI.png | Bin 0 -> 63650 bytes .../webex-wallet/invoice/9-click-open.png | Bin 0 -> 52823 bytes .../webex-wallet/payment/1-load-shop.png | Bin 0 -> 2449960 bytes .../webex-wallet/payment/10-click-article-URL.png | Bin 0 -> 76691 bytes .../webex-wallet/payment/2-click-first-article.png | Bin 0 -> 83759 bytes .../webex-wallet/payment/3-confirm-payment.png | Bin 0 -> 442385 bytes .../webex-wallet/payment/4-click-refund.png | Bin 0 -> 101347 bytes .../webex-wallet/payment/5-click-request-refund.png | Bin 0 -> 41768 bytes .../webex-wallet/payment/6-accept-refund.png | Bin 0 -> 85837 bytes .../webex-wallet/payment/7-click-refund-detail.png | Bin 0 -> 69279 bytes .../webex-wallet/payment/8-show-history.png | Bin 0 -> 81889 bytes .../webex-wallet/payment/9-click-receipt.png | Bin 0 -> 85837 bytes .../wallet-screenshots/webex-wallet/scan-qr-code.png | Bin 0 -> 36358 bytes .../webex-wallet/settings-developer-mode.png | Bin 0 -> 170233 bytes .../webex-wallet/settings-normal-mode.png | Bin 0 -> 47851 bytes .../webex-wallet/transfer/1-initial-balance.png | Bin 0 -> 36311 bytes .../webex-wallet/transfer/10-open-URI.png | Bin 0 -> 51973 bytes .../webex-wallet/transfer/11-accept-transfer.png | Bin 0 -> 49787 bytes .../webex-wallet/transfer/12-show-history.png | Bin 0 -> 47985 bytes .../webex-wallet/transfer/2-click-send.png | Bin 0 -> 47235 bytes .../webex-wallet/transfer/3-amount-five.png | Bin 0 -> 47547 bytes .../webex-wallet/transfer/4-send-wallet.png | Bin 0 -> 56300 bytes .../webex-wallet/transfer/5-complete-form.png | Bin 0 -> 58617 bytes .../webex-wallet/transfer/6-confirm-transfer.png | Bin 0 -> 77092 bytes .../webex-wallet/transfer/7-show-history.png | Bin 0 -> 55329 bytes .../webex-wallet/transfer/8-scan-qr.png | Bin 0 -> 48384 bytes .../webex-wallet/transfer/9-paste-URI.png | Bin 0 -> 64510 bytes .../withdrawal/10-transaction-completed.png | Bin 0 -> 44344 bytes .../withdrawal/11-history-after-withdraw.png | Bin 0 -> 35260 bytes .../webex-wallet/withdrawal/2-empty-wallet.png | Bin 0 -> 29113 bytes .../webex-wallet/withdrawal/3-get-digital-cash.png | Bin 0 -> 36120 bytes .../webex-wallet/withdrawal/4-select-kudos.png | Bin 0 -> 47910 bytes .../webex-wallet/withdrawal/5-set-amount-five.png | Bin 0 -> 48389 bytes .../webex-wallet/withdrawal/6-withdraw-from-bank.png | Bin 0 -> 52203 bytes .../webex-wallet/withdrawal/7-review-tos.png | Bin 0 -> 69841 bytes .../webex-wallet/withdrawal/8-accept-tos.png | Bin 0 -> 50475 bytes .../webex-wallet/withdrawal/9-confirm-withdraw.png | Bin 0 -> 148862 bytes 69 files changed, 0 insertions(+), 0 deletions(-) create mode 100644 design-documents/wallet-screenshots/webex-wallet/1-wallet-installed.png create mode 100644 design-documents/wallet-screenshots/webex-wallet/add-exchange/1-balance.png create mode 100644 design-documents/wallet-screenshots/webex-wallet/add-exchange/10-testkudos-in-the-list.png create mode 100644 design-documents/wallet-screenshots/webex-wallet/add-exchange/11-select-test-kudos.png create mode 100644 design-documents/wallet-screenshots/webex-wallet/add-exchange/2-click-get-cash.png create mode 100644 design-documents/wallet-screenshots/webex-wallet/add-exchange/3-click-add-exchange.png create mode 100644 design-documents/wallet-screenshots/webex-wallet/add-exchange/4-input-URL.png create mode 100644 design-documents/wallet-screenshots/webex-wallet/add-exchange/5-click-next.png create mode 100644 design-documents/wallet-screenshots/webex-wallet/add-exchange/6-review-tos.png create mode 100644 design-documents/wallet-screenshots/webex-wallet/add-exchange/7-accept-tos.png create mode 100644 design-documents/wallet-screenshots/webex-wallet/add-exchange/8-confirm.png create mode 100644 design-documents/wallet-screenshots/webex-wallet/add-exchange/9-click-get-cash.png create mode 100644 design-documents/wallet-screenshots/webex-wallet/deposit/1-balance.png create mode 100644 design-documents/wallet-screenshots/webex-wallet/deposit/10-balance.png create mode 100644 design-documents/wallet-screenshots/webex-wallet/deposit/2-click-send.png create mode 100644 design-documents/wallet-screenshots/webex-wallet/deposit/3-click-deposit.png create mode 100644 design-documents/wallet-screenshots/webex-wallet/deposit/4-click-add-account.png create mode 100644 design-documents/wallet-screenshots/webex-wallet/deposit/5-complete-form.png create mode 100644 design-documents/wallet-screenshots/webex-wallet/deposit/6-click-add.png create mode 100644 design-documents/wallet-screenshots/webex-wallet/deposit/7-confirm-deposit.png create mode 100644 design-documents/wallet-screenshots/webex-wallet/deposit/8-show-transaction.png create mode 100644 design-documents/wallet-screenshots/webex-wallet/deposit/9-after-deposit-confirmed.png create mode 100644 design-documents/wallet-screenshots/webex-wallet/dev-tools.png create mode 100644 design-documents/wallet-screenshots/webex-wallet/invoice/1-balance.png create mode 100644 design-documents/wallet-screenshots/webex-wallet/invoice/10-confirm-transfer.png create mode 100644 design-documents/wallet-screenshots/webex-wallet/invoice/11-show-history.png create mode 100644 design-documents/wallet-screenshots/webex-wallet/invoice/2-click-add.png create mode 100644 design-documents/wallet-screenshots/webex-wallet/invoice/3-input-six.png create mode 100644 design-documents/wallet-screenshots/webex-wallet/invoice/4-click-invoice.png create mode 100644 design-documents/wallet-screenshots/webex-wallet/invoice/5-complete-form.png create mode 100644 design-documents/wallet-screenshots/webex-wallet/invoice/6-create-invoice.png create mode 100644 design-documents/wallet-screenshots/webex-wallet/invoice/7-copy-qr-open-qr-page.png create mode 100644 design-documents/wallet-screenshots/webex-wallet/invoice/8-paste-URI.png create mode 100644 design-documents/wallet-screenshots/webex-wallet/invoice/9-click-open.png create mode 100644 design-documents/wallet-screenshots/webex-wallet/payment/1-load-shop.png create mode 100644 design-documents/wallet-screenshots/webex-wallet/payment/10-click-article-URL.png create mode 100644 design-documents/wallet-screenshots/webex-wallet/payment/2-click-first-article.png create mode 100644 design-documents/wallet-screenshots/webex-wallet/payment/3-confirm-payment.png create mode 100644 design-documents/wallet-screenshots/webex-wallet/payment/4-click-refund.png create mode 100644 design-documents/wallet-screenshots/webex-wallet/payment/5-click-request-refund.png create mode 100644 design-documents/wallet-screenshots/webex-wallet/payment/6-accept-refund.png create mode 100644 design-documents/wallet-screenshots/webex-wallet/payment/7-click-refund-detail.png create mode 100644 design-documents/wallet-screenshots/webex-wallet/payment/8-show-history.png create mode 100644 design-documents/wallet-screenshots/webex-wallet/payment/9-click-receipt.png create mode 100644 design-documents/wallet-screenshots/webex-wallet/scan-qr-code.png create mode 100644 design-documents/wallet-screenshots/webex-wallet/settings-developer-mode.png create mode 100644 design-documents/wallet-screenshots/webex-wallet/settings-normal-mode.png create mode 100644 design-documents/wallet-screenshots/webex-wallet/transfer/1-initial-balance.png create mode 100644 design-documents/wallet-screenshots/webex-wallet/transfer/10-open-URI.png create mode 100644 design-documents/wallet-screenshots/webex-wallet/transfer/11-accept-transfer.png create mode 100644 design-documents/wallet-screenshots/webex-wallet/transfer/12-show-history.png create mode 100644 design-documents/wallet-screenshots/webex-wallet/transfer/2-click-send.png create mode 100644 design-documents/wallet-screenshots/webex-wallet/transfer/3-amount-five.png create mode 100644 design-documents/wallet-screenshots/webex-wallet/transfer/4-send-wallet.png create mode 100644 design-documents/wallet-screenshots/webex-wallet/transfer/5-complete-form.png create mode 100644 design-documents/wallet-screenshots/webex-wallet/transfer/6-confirm-transfer.png create mode 100644 design-documents/wallet-screenshots/webex-wallet/transfer/7-show-history.png create mode 100644 design-documents/wallet-screenshots/webex-wallet/transfer/8-scan-qr.png create mode 100644 design-documents/wallet-screenshots/webex-wallet/transfer/9-paste-URI.png create mode 100644 design-documents/wallet-screenshots/webex-wallet/withdrawal/10-transaction-completed.png create mode 100644 design-documents/wallet-screenshots/webex-wallet/withdrawal/11-history-after-withdraw.png create mode 100644 design-documents/wallet-screenshots/webex-wallet/withdrawal/2-empty-wallet.png create mode 100644 design-documents/wallet-screenshots/webex-wallet/withdrawal/3-get-digital-cash.png create mode 100644 design-documents/wallet-screenshots/webex-wallet/withdrawal/4-select-kudos.png create mode 100644 design-documents/wallet-screenshots/webex-wallet/withdrawal/5-set-amount-five.png create mode 100644 design-documents/wallet-screenshots/webex-wallet/withdrawal/6-withdraw-from-bank.png create mode 100644 design-documents/wallet-screenshots/webex-wallet/withdrawal/7-review-tos.png create mode 100644 design-documents/wallet-screenshots/webex-wallet/withdrawal/8-accept-tos.png create mode 100644 design-documents/wallet-screenshots/webex-wallet/withdrawal/9-confirm-withdraw.png diff --git a/design-documents/wallet-screenshots/webex-wallet/1-wallet-installed.png b/design-documents/wallet-screenshots/webex-wallet/1-wallet-installed.png new file mode 100644 index 00000000..6036a6c9 Binary files /dev/null and b/design-documents/wallet-screenshots/webex-wallet/1-wallet-installed.png differ diff --git a/design-documents/wallet-screenshots/webex-wallet/add-exchange/1-balance.png b/design-documents/wallet-screenshots/webex-wallet/add-exchange/1-balance.png new file mode 100644 index 00000000..1041e2ee Binary files /dev/null and b/design-documents/wallet-screenshots/webex-wallet/add-exchange/1-balance.png differ diff --git a/design-documents/wallet-screenshots/webex-wallet/add-exchange/10-testkudos-in-the-list.png b/design-documents/wallet-screenshots/webex-wallet/add-exchange/10-testkudos-in-the-list.png new file mode 100644 index 00000000..12a53026 Binary files /dev/null and b/design-documents/wallet-screenshots/webex-wallet/add-exchange/10-testkudos-in-the-list.png differ diff --git a/design-documents/wallet-screenshots/webex-wallet/add-exchange/11-select-test-kudos.png b/design-documents/wallet-screenshots/webex-wallet/add-exchange/11-select-test-kudos.png new file mode 100644 index 00000000..43e18c89 Binary files /dev/null and b/design-documents/wallet-screenshots/webex-wallet/add-exchange/11-select-test-kudos.png differ diff --git a/design-documents/wallet-screenshots/webex-wallet/add-exchange/2-click-get-cash.png b/design-documents/wallet-screenshots/webex-wallet/add-exchange/2-click-get-cash.png new file mode 100644 index 00000000..d7d247f0 Binary files /dev/null and b/design-documents/wallet-screenshots/webex-wallet/add-exchange/2-click-get-cash.png differ diff --git a/design-documents/wallet-screenshots/webex-wallet/add-exchange/3-click-add-exchange.png b/design-documents/wallet-screenshots/webex-wallet/add-exchange/3-click-add-exchange.png new file mode 100644 index 00000000..7a1a48e9 Binary files /dev/null and b/design-documents/wallet-screenshots/webex-wallet/add-exchange/3-click-add-exchange.png differ diff --git a/design-documents/wallet-screenshots/webex-wallet/add-exchange/4-input-URL.png b/design-documents/wallet-screenshots/webex-wallet/add-exchange/4-input-URL.png new file mode 100644 index 00000000..efdf852a Binary files /dev/null and b/design-documents/wallet-screenshots/webex-wallet/add-exchange/4-input-URL.png differ diff --git a/design-documents/wallet-screenshots/webex-wallet/add-exchange/5-click-next.png b/design-documents/wallet-screenshots/webex-wallet/add-exchange/5-click-next.png new file mode 100644 index 00000000..9a2782f2 Binary files /dev/null and b/design-documents/wallet-screenshots/webex-wallet/add-exchange/5-click-next.png differ diff --git a/design-documents/wallet-screenshots/webex-wallet/add-exchange/6-review-tos.png b/design-documents/wallet-screenshots/webex-wallet/add-exchange/6-review-tos.png new file mode 100644 index 00000000..44a85d6f Binary files /dev/null and b/design-documents/wallet-screenshots/webex-wallet/add-exchange/6-review-tos.png differ diff --git a/design-documents/wallet-screenshots/webex-wallet/add-exchange/7-accept-tos.png b/design-documents/wallet-screenshots/webex-wallet/add-exchange/7-accept-tos.png new file mode 100644 index 00000000..c73c5256 Binary files /dev/null and b/design-documents/wallet-screenshots/webex-wallet/add-exchange/7-accept-tos.png differ diff --git a/design-documents/wallet-screenshots/webex-wallet/add-exchange/8-confirm.png b/design-documents/wallet-screenshots/webex-wallet/add-exchange/8-confirm.png new file mode 100644 index 00000000..1041e2ee Binary files /dev/null and b/design-documents/wallet-screenshots/webex-wallet/add-exchange/8-confirm.png differ diff --git a/design-documents/wallet-screenshots/webex-wallet/add-exchange/9-click-get-cash.png b/design-documents/wallet-screenshots/webex-wallet/add-exchange/9-click-get-cash.png new file mode 100644 index 00000000..d7d247f0 Binary files /dev/null and b/design-documents/wallet-screenshots/webex-wallet/add-exchange/9-click-get-cash.png differ diff --git a/design-documents/wallet-screenshots/webex-wallet/deposit/1-balance.png b/design-documents/wallet-screenshots/webex-wallet/deposit/1-balance.png new file mode 100644 index 00000000..7c571c48 Binary files /dev/null and b/design-documents/wallet-screenshots/webex-wallet/deposit/1-balance.png differ diff --git a/design-documents/wallet-screenshots/webex-wallet/deposit/10-balance.png b/design-documents/wallet-screenshots/webex-wallet/deposit/10-balance.png new file mode 100644 index 00000000..4e3a787b Binary files /dev/null and b/design-documents/wallet-screenshots/webex-wallet/deposit/10-balance.png differ diff --git a/design-documents/wallet-screenshots/webex-wallet/deposit/2-click-send.png b/design-documents/wallet-screenshots/webex-wallet/deposit/2-click-send.png new file mode 100644 index 00000000..2cdb5fe0 Binary files /dev/null and b/design-documents/wallet-screenshots/webex-wallet/deposit/2-click-send.png differ diff --git a/design-documents/wallet-screenshots/webex-wallet/deposit/3-click-deposit.png b/design-documents/wallet-screenshots/webex-wallet/deposit/3-click-deposit.png new file mode 100644 index 00000000..afc4a431 Binary files /dev/null and b/design-documents/wallet-screenshots/webex-wallet/deposit/3-click-deposit.png differ diff --git a/design-documents/wallet-screenshots/webex-wallet/deposit/4-click-add-account.png b/design-documents/wallet-screenshots/webex-wallet/deposit/4-click-add-account.png new file mode 100644 index 00000000..c91bc8d9 Binary files /dev/null and b/design-documents/wallet-screenshots/webex-wallet/deposit/4-click-add-account.png differ diff --git a/design-documents/wallet-screenshots/webex-wallet/deposit/5-complete-form.png b/design-documents/wallet-screenshots/webex-wallet/deposit/5-complete-form.png new file mode 100644 index 00000000..77514161 Binary files /dev/null and b/design-documents/wallet-screenshots/webex-wallet/deposit/5-complete-form.png differ diff --git a/design-documents/wallet-screenshots/webex-wallet/deposit/6-click-add.png b/design-documents/wallet-screenshots/webex-wallet/deposit/6-click-add.png new file mode 100644 index 00000000..e78538c7 Binary files /dev/null and b/design-documents/wallet-screenshots/webex-wallet/deposit/6-click-add.png differ diff --git a/design-documents/wallet-screenshots/webex-wallet/deposit/7-confirm-deposit.png b/design-documents/wallet-screenshots/webex-wallet/deposit/7-confirm-deposit.png new file mode 100644 index 00000000..bf2c61bc Binary files /dev/null and b/design-documents/wallet-screenshots/webex-wallet/deposit/7-confirm-deposit.png differ diff --git a/design-documents/wallet-screenshots/webex-wallet/deposit/8-show-transaction.png b/design-documents/wallet-screenshots/webex-wallet/deposit/8-show-transaction.png new file mode 100644 index 00000000..381ae09e Binary files /dev/null and b/design-documents/wallet-screenshots/webex-wallet/deposit/8-show-transaction.png differ diff --git a/design-documents/wallet-screenshots/webex-wallet/deposit/9-after-deposit-confirmed.png b/design-documents/wallet-screenshots/webex-wallet/deposit/9-after-deposit-confirmed.png new file mode 100644 index 00000000..74c2026d Binary files /dev/null and b/design-documents/wallet-screenshots/webex-wallet/deposit/9-after-deposit-confirmed.png differ diff --git a/design-documents/wallet-screenshots/webex-wallet/dev-tools.png b/design-documents/wallet-screenshots/webex-wallet/dev-tools.png new file mode 100644 index 00000000..a817d055 Binary files /dev/null and b/design-documents/wallet-screenshots/webex-wallet/dev-tools.png differ diff --git a/design-documents/wallet-screenshots/webex-wallet/invoice/1-balance.png b/design-documents/wallet-screenshots/webex-wallet/invoice/1-balance.png new file mode 100644 index 00000000..a6692c4f Binary files /dev/null and b/design-documents/wallet-screenshots/webex-wallet/invoice/1-balance.png differ diff --git a/design-documents/wallet-screenshots/webex-wallet/invoice/10-confirm-transfer.png b/design-documents/wallet-screenshots/webex-wallet/invoice/10-confirm-transfer.png new file mode 100644 index 00000000..2611c9f3 Binary files /dev/null and b/design-documents/wallet-screenshots/webex-wallet/invoice/10-confirm-transfer.png differ diff --git a/design-documents/wallet-screenshots/webex-wallet/invoice/11-show-history.png b/design-documents/wallet-screenshots/webex-wallet/invoice/11-show-history.png new file mode 100644 index 00000000..52907939 Binary files /dev/null and b/design-documents/wallet-screenshots/webex-wallet/invoice/11-show-history.png differ diff --git a/design-documents/wallet-screenshots/webex-wallet/invoice/2-click-add.png b/design-documents/wallet-screenshots/webex-wallet/invoice/2-click-add.png new file mode 100644 index 00000000..7834436d Binary files /dev/null and b/design-documents/wallet-screenshots/webex-wallet/invoice/2-click-add.png differ diff --git a/design-documents/wallet-screenshots/webex-wallet/invoice/3-input-six.png b/design-documents/wallet-screenshots/webex-wallet/invoice/3-input-six.png new file mode 100644 index 00000000..0f910210 Binary files /dev/null and b/design-documents/wallet-screenshots/webex-wallet/invoice/3-input-six.png differ diff --git a/design-documents/wallet-screenshots/webex-wallet/invoice/4-click-invoice.png b/design-documents/wallet-screenshots/webex-wallet/invoice/4-click-invoice.png new file mode 100644 index 00000000..0d7c1b31 Binary files /dev/null and b/design-documents/wallet-screenshots/webex-wallet/invoice/4-click-invoice.png differ diff --git a/design-documents/wallet-screenshots/webex-wallet/invoice/5-complete-form.png b/design-documents/wallet-screenshots/webex-wallet/invoice/5-complete-form.png new file mode 100644 index 00000000..625afb3c Binary files /dev/null and b/design-documents/wallet-screenshots/webex-wallet/invoice/5-complete-form.png differ diff --git a/design-documents/wallet-screenshots/webex-wallet/invoice/6-create-invoice.png b/design-documents/wallet-screenshots/webex-wallet/invoice/6-create-invoice.png new file mode 100644 index 00000000..def698a8 Binary files /dev/null and b/design-documents/wallet-screenshots/webex-wallet/invoice/6-create-invoice.png differ diff --git a/design-documents/wallet-screenshots/webex-wallet/invoice/7-copy-qr-open-qr-page.png b/design-documents/wallet-screenshots/webex-wallet/invoice/7-copy-qr-open-qr-page.png new file mode 100644 index 00000000..fe221eac Binary files /dev/null and b/design-documents/wallet-screenshots/webex-wallet/invoice/7-copy-qr-open-qr-page.png differ diff --git a/design-documents/wallet-screenshots/webex-wallet/invoice/8-paste-URI.png b/design-documents/wallet-screenshots/webex-wallet/invoice/8-paste-URI.png new file mode 100644 index 00000000..26351cb9 Binary files /dev/null and b/design-documents/wallet-screenshots/webex-wallet/invoice/8-paste-URI.png differ diff --git a/design-documents/wallet-screenshots/webex-wallet/invoice/9-click-open.png b/design-documents/wallet-screenshots/webex-wallet/invoice/9-click-open.png new file mode 100644 index 00000000..90393d3b Binary files /dev/null and b/design-documents/wallet-screenshots/webex-wallet/invoice/9-click-open.png differ diff --git a/design-documents/wallet-screenshots/webex-wallet/payment/1-load-shop.png b/design-documents/wallet-screenshots/webex-wallet/payment/1-load-shop.png new file mode 100644 index 00000000..4aacc47b Binary files /dev/null and b/design-documents/wallet-screenshots/webex-wallet/payment/1-load-shop.png differ diff --git a/design-documents/wallet-screenshots/webex-wallet/payment/10-click-article-URL.png b/design-documents/wallet-screenshots/webex-wallet/payment/10-click-article-URL.png new file mode 100644 index 00000000..74488cb6 Binary files /dev/null and b/design-documents/wallet-screenshots/webex-wallet/payment/10-click-article-URL.png differ diff --git a/design-documents/wallet-screenshots/webex-wallet/payment/2-click-first-article.png b/design-documents/wallet-screenshots/webex-wallet/payment/2-click-first-article.png new file mode 100644 index 00000000..31635b8a Binary files /dev/null and b/design-documents/wallet-screenshots/webex-wallet/payment/2-click-first-article.png differ diff --git a/design-documents/wallet-screenshots/webex-wallet/payment/3-confirm-payment.png b/design-documents/wallet-screenshots/webex-wallet/payment/3-confirm-payment.png new file mode 100644 index 00000000..016f5514 Binary files /dev/null and b/design-documents/wallet-screenshots/webex-wallet/payment/3-confirm-payment.png differ diff --git a/design-documents/wallet-screenshots/webex-wallet/payment/4-click-refund.png b/design-documents/wallet-screenshots/webex-wallet/payment/4-click-refund.png new file mode 100644 index 00000000..4a3ddd39 Binary files /dev/null and b/design-documents/wallet-screenshots/webex-wallet/payment/4-click-refund.png differ diff --git a/design-documents/wallet-screenshots/webex-wallet/payment/5-click-request-refund.png b/design-documents/wallet-screenshots/webex-wallet/payment/5-click-request-refund.png new file mode 100644 index 00000000..9b27cd5b Binary files /dev/null and b/design-documents/wallet-screenshots/webex-wallet/payment/5-click-request-refund.png differ diff --git a/design-documents/wallet-screenshots/webex-wallet/payment/6-accept-refund.png b/design-documents/wallet-screenshots/webex-wallet/payment/6-accept-refund.png new file mode 100644 index 00000000..a4b1c137 Binary files /dev/null and b/design-documents/wallet-screenshots/webex-wallet/payment/6-accept-refund.png differ diff --git a/design-documents/wallet-screenshots/webex-wallet/payment/7-click-refund-detail.png b/design-documents/wallet-screenshots/webex-wallet/payment/7-click-refund-detail.png new file mode 100644 index 00000000..14291836 Binary files /dev/null and b/design-documents/wallet-screenshots/webex-wallet/payment/7-click-refund-detail.png differ diff --git a/design-documents/wallet-screenshots/webex-wallet/payment/8-show-history.png b/design-documents/wallet-screenshots/webex-wallet/payment/8-show-history.png new file mode 100644 index 00000000..2758f7f3 Binary files /dev/null and b/design-documents/wallet-screenshots/webex-wallet/payment/8-show-history.png differ diff --git a/design-documents/wallet-screenshots/webex-wallet/payment/9-click-receipt.png b/design-documents/wallet-screenshots/webex-wallet/payment/9-click-receipt.png new file mode 100644 index 00000000..a4b1c137 Binary files /dev/null and b/design-documents/wallet-screenshots/webex-wallet/payment/9-click-receipt.png differ diff --git a/design-documents/wallet-screenshots/webex-wallet/scan-qr-code.png b/design-documents/wallet-screenshots/webex-wallet/scan-qr-code.png new file mode 100644 index 00000000..ae28e3db Binary files /dev/null and b/design-documents/wallet-screenshots/webex-wallet/scan-qr-code.png differ diff --git a/design-documents/wallet-screenshots/webex-wallet/settings-developer-mode.png b/design-documents/wallet-screenshots/webex-wallet/settings-developer-mode.png new file mode 100644 index 00000000..c93883dc Binary files /dev/null and b/design-documents/wallet-screenshots/webex-wallet/settings-developer-mode.png differ diff --git a/design-documents/wallet-screenshots/webex-wallet/settings-normal-mode.png b/design-documents/wallet-screenshots/webex-wallet/settings-normal-mode.png new file mode 100644 index 00000000..50f70cab Binary files /dev/null and b/design-documents/wallet-screenshots/webex-wallet/settings-normal-mode.png differ diff --git a/design-documents/wallet-screenshots/webex-wallet/transfer/1-initial-balance.png b/design-documents/wallet-screenshots/webex-wallet/transfer/1-initial-balance.png new file mode 100644 index 00000000..20e74cf3 Binary files /dev/null and b/design-documents/wallet-screenshots/webex-wallet/transfer/1-initial-balance.png differ diff --git a/design-documents/wallet-screenshots/webex-wallet/transfer/10-open-URI.png b/design-documents/wallet-screenshots/webex-wallet/transfer/10-open-URI.png new file mode 100644 index 00000000..22f21f89 Binary files /dev/null and b/design-documents/wallet-screenshots/webex-wallet/transfer/10-open-URI.png differ diff --git a/design-documents/wallet-screenshots/webex-wallet/transfer/11-accept-transfer.png b/design-documents/wallet-screenshots/webex-wallet/transfer/11-accept-transfer.png new file mode 100644 index 00000000..9ee2083a Binary files /dev/null and b/design-documents/wallet-screenshots/webex-wallet/transfer/11-accept-transfer.png differ diff --git a/design-documents/wallet-screenshots/webex-wallet/transfer/12-show-history.png b/design-documents/wallet-screenshots/webex-wallet/transfer/12-show-history.png new file mode 100644 index 00000000..d2d12ca8 Binary files /dev/null and b/design-documents/wallet-screenshots/webex-wallet/transfer/12-show-history.png differ diff --git a/design-documents/wallet-screenshots/webex-wallet/transfer/2-click-send.png b/design-documents/wallet-screenshots/webex-wallet/transfer/2-click-send.png new file mode 100644 index 00000000..0e705860 Binary files /dev/null and b/design-documents/wallet-screenshots/webex-wallet/transfer/2-click-send.png differ diff --git a/design-documents/wallet-screenshots/webex-wallet/transfer/3-amount-five.png b/design-documents/wallet-screenshots/webex-wallet/transfer/3-amount-five.png new file mode 100644 index 00000000..ffe4bee7 Binary files /dev/null and b/design-documents/wallet-screenshots/webex-wallet/transfer/3-amount-five.png differ diff --git a/design-documents/wallet-screenshots/webex-wallet/transfer/4-send-wallet.png b/design-documents/wallet-screenshots/webex-wallet/transfer/4-send-wallet.png new file mode 100644 index 00000000..f566b0cb Binary files /dev/null and b/design-documents/wallet-screenshots/webex-wallet/transfer/4-send-wallet.png differ diff --git a/design-documents/wallet-screenshots/webex-wallet/transfer/5-complete-form.png b/design-documents/wallet-screenshots/webex-wallet/transfer/5-complete-form.png new file mode 100644 index 00000000..836755ca Binary files /dev/null and b/design-documents/wallet-screenshots/webex-wallet/transfer/5-complete-form.png differ diff --git a/design-documents/wallet-screenshots/webex-wallet/transfer/6-confirm-transfer.png b/design-documents/wallet-screenshots/webex-wallet/transfer/6-confirm-transfer.png new file mode 100644 index 00000000..55de4bb0 Binary files /dev/null and b/design-documents/wallet-screenshots/webex-wallet/transfer/6-confirm-transfer.png differ diff --git a/design-documents/wallet-screenshots/webex-wallet/transfer/7-show-history.png b/design-documents/wallet-screenshots/webex-wallet/transfer/7-show-history.png new file mode 100644 index 00000000..39de7b66 Binary files /dev/null and b/design-documents/wallet-screenshots/webex-wallet/transfer/7-show-history.png differ diff --git a/design-documents/wallet-screenshots/webex-wallet/transfer/8-scan-qr.png b/design-documents/wallet-screenshots/webex-wallet/transfer/8-scan-qr.png new file mode 100644 index 00000000..cacdce06 Binary files /dev/null and b/design-documents/wallet-screenshots/webex-wallet/transfer/8-scan-qr.png differ diff --git a/design-documents/wallet-screenshots/webex-wallet/transfer/9-paste-URI.png b/design-documents/wallet-screenshots/webex-wallet/transfer/9-paste-URI.png new file mode 100644 index 00000000..32ac0ff4 Binary files /dev/null and b/design-documents/wallet-screenshots/webex-wallet/transfer/9-paste-URI.png differ diff --git a/design-documents/wallet-screenshots/webex-wallet/withdrawal/10-transaction-completed.png b/design-documents/wallet-screenshots/webex-wallet/withdrawal/10-transaction-completed.png new file mode 100644 index 00000000..2a774334 Binary files /dev/null and b/design-documents/wallet-screenshots/webex-wallet/withdrawal/10-transaction-completed.png differ diff --git a/design-documents/wallet-screenshots/webex-wallet/withdrawal/11-history-after-withdraw.png b/design-documents/wallet-screenshots/webex-wallet/withdrawal/11-history-after-withdraw.png new file mode 100644 index 00000000..54b05212 Binary files /dev/null and b/design-documents/wallet-screenshots/webex-wallet/withdrawal/11-history-after-withdraw.png differ diff --git a/design-documents/wallet-screenshots/webex-wallet/withdrawal/2-empty-wallet.png b/design-documents/wallet-screenshots/webex-wallet/withdrawal/2-empty-wallet.png new file mode 100644 index 00000000..79fc787b Binary files /dev/null and b/design-documents/wallet-screenshots/webex-wallet/withdrawal/2-empty-wallet.png differ diff --git a/design-documents/wallet-screenshots/webex-wallet/withdrawal/3-get-digital-cash.png b/design-documents/wallet-screenshots/webex-wallet/withdrawal/3-get-digital-cash.png new file mode 100644 index 00000000..273d5f5f Binary files /dev/null and b/design-documents/wallet-screenshots/webex-wallet/withdrawal/3-get-digital-cash.png differ diff --git a/design-documents/wallet-screenshots/webex-wallet/withdrawal/4-select-kudos.png b/design-documents/wallet-screenshots/webex-wallet/withdrawal/4-select-kudos.png new file mode 100644 index 00000000..741ac32a Binary files /dev/null and b/design-documents/wallet-screenshots/webex-wallet/withdrawal/4-select-kudos.png differ diff --git a/design-documents/wallet-screenshots/webex-wallet/withdrawal/5-set-amount-five.png b/design-documents/wallet-screenshots/webex-wallet/withdrawal/5-set-amount-five.png new file mode 100644 index 00000000..8454928b Binary files /dev/null and b/design-documents/wallet-screenshots/webex-wallet/withdrawal/5-set-amount-five.png differ diff --git a/design-documents/wallet-screenshots/webex-wallet/withdrawal/6-withdraw-from-bank.png b/design-documents/wallet-screenshots/webex-wallet/withdrawal/6-withdraw-from-bank.png new file mode 100644 index 00000000..e0942a0c Binary files /dev/null and b/design-documents/wallet-screenshots/webex-wallet/withdrawal/6-withdraw-from-bank.png differ diff --git a/design-documents/wallet-screenshots/webex-wallet/withdrawal/7-review-tos.png b/design-documents/wallet-screenshots/webex-wallet/withdrawal/7-review-tos.png new file mode 100644 index 00000000..505e06d3 Binary files /dev/null and b/design-documents/wallet-screenshots/webex-wallet/withdrawal/7-review-tos.png differ diff --git a/design-documents/wallet-screenshots/webex-wallet/withdrawal/8-accept-tos.png b/design-documents/wallet-screenshots/webex-wallet/withdrawal/8-accept-tos.png new file mode 100644 index 00000000..61d3c0a4 Binary files /dev/null and b/design-documents/wallet-screenshots/webex-wallet/withdrawal/8-accept-tos.png differ diff --git a/design-documents/wallet-screenshots/webex-wallet/withdrawal/9-confirm-withdraw.png b/design-documents/wallet-screenshots/webex-wallet/withdrawal/9-confirm-withdraw.png new file mode 100644 index 00000000..579803cc Binary files /dev/null and b/design-documents/wallet-screenshots/webex-wallet/withdrawal/9-confirm-withdraw.png differ -- cgit v1.2.3 From 77a8fa7279f149b3cd04cb953b0f7b826c875175 Mon Sep 17 00:00:00 2001 From: Sebastian Date: Wed, 6 Mar 2024 15:29:28 -0300 Subject: store imgs --- .../webex-wallet/1-wallet-installed.png | Bin 57887 -> 0 bytes .../wallet-screenshots/webex-wallet/READE | 22 +++++++++++++++++++++ .../webex-wallet/store-installed.png | Bin 0 -> 32548 bytes .../webex-wallet/store-payment.png | Bin 0 -> 28060 bytes .../webex-wallet/store-withdraw.png | Bin 0 -> 20772 bytes 5 files changed, 22 insertions(+) delete mode 100644 design-documents/wallet-screenshots/webex-wallet/1-wallet-installed.png create mode 100644 design-documents/wallet-screenshots/webex-wallet/READE create mode 100644 design-documents/wallet-screenshots/webex-wallet/store-installed.png create mode 100644 design-documents/wallet-screenshots/webex-wallet/store-payment.png create mode 100644 design-documents/wallet-screenshots/webex-wallet/store-withdraw.png diff --git a/design-documents/wallet-screenshots/webex-wallet/1-wallet-installed.png b/design-documents/wallet-screenshots/webex-wallet/1-wallet-installed.png deleted file mode 100644 index 6036a6c9..00000000 Binary files a/design-documents/wallet-screenshots/webex-wallet/1-wallet-installed.png and /dev/null differ diff --git a/design-documents/wallet-screenshots/webex-wallet/READE b/design-documents/wallet-screenshots/webex-wallet/READE new file mode 100644 index 00000000..597fa22e --- /dev/null +++ b/design-documents/wallet-screenshots/webex-wallet/READE @@ -0,0 +1,22 @@ +Wallet Web Extension screenshots +-------------------------------- + +Screenshoots are organized by common use case using +the happy path to ilustrate the user flow: + + * withdrawal: starts from an empty wallet and performs + a manual withdrawal with demo exchange. + * payment: starts from demo shop and pay for an article. + also showing how a refund looks. + * transfer: performs a p2p push debit and credit. + * invoice: performs a p2p pull credit and debit. + * deposit: starts from a wallet with some balance + and deposit into a bank account new yet + known by the wallet. + * add-exchange: add the test exchange into the wallet. + +In this root folder there are some additionals screen for +settings, dev tools and others. + +Screenshot starting with "store-*" are used in chrome webstore +and firefox addon store. diff --git a/design-documents/wallet-screenshots/webex-wallet/store-installed.png b/design-documents/wallet-screenshots/webex-wallet/store-installed.png new file mode 100644 index 00000000..67c481fc Binary files /dev/null and b/design-documents/wallet-screenshots/webex-wallet/store-installed.png differ diff --git a/design-documents/wallet-screenshots/webex-wallet/store-payment.png b/design-documents/wallet-screenshots/webex-wallet/store-payment.png new file mode 100644 index 00000000..3f776696 Binary files /dev/null and b/design-documents/wallet-screenshots/webex-wallet/store-payment.png differ diff --git a/design-documents/wallet-screenshots/webex-wallet/store-withdraw.png b/design-documents/wallet-screenshots/webex-wallet/store-withdraw.png new file mode 100644 index 00000000..8409a0b9 Binary files /dev/null and b/design-documents/wallet-screenshots/webex-wallet/store-withdraw.png differ -- cgit v1.2.3 From 70d848507ba233fa9e530481cd7816c399db6d19 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Wed, 6 Mar 2024 23:25:57 +0100 Subject: document fix for #8369 --- manpages/taler.conf.5.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/manpages/taler.conf.5.rst b/manpages/taler.conf.5.rst index 3748b673..3074f68b 100644 --- a/manpages/taler.conf.5.rst +++ b/manpages/taler.conf.5.rst @@ -182,6 +182,12 @@ BASE_URL Added to wire transfers to enable tracking by merchants. Used by the KYC logic when interacting with OAuth 2.0. +TOPLEVEL_REDIRECT_URL + Where to redirect visitors that access the top-level + "/" endpoint of the exchange. Should point users to + information about the exchange operator. + Optional setting, defaults to "/terms". + AGGREGATOR_IDLE_SLEEP_INTERVAL For how long should the taler-exchange-aggregator sleep when it is idle before trying to look for more work? Default is 60 seconds. -- cgit v1.2.3 From e39dd668c013a44854d8b9fd62b486a90f6931b9 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Thu, 7 Mar 2024 09:52:56 +0100 Subject: fix bad anchor warning --- manpages/challenger.conf.5.rst | 2 +- taler-developer-manual.rst | 114 +++++++++++++++++------------------------ 2 files changed, 49 insertions(+), 67 deletions(-) diff --git a/manpages/challenger.conf.5.rst b/manpages/challenger.conf.5.rst index 66c46e80..626d11f7 100644 --- a/manpages/challenger.conf.5.rst +++ b/manpages/challenger.conf.5.rst @@ -72,7 +72,7 @@ ADDRESS_TYPE Type of the address that is being collected, returned as part of the ``address_type`` in the ``/info`` endpoint. Examples include ``email`` or ``phone``. ADDRESS_RESTRICTIONS - JSON object with a map of keys (names of the fields of the address to be entered by the user) to objects with a "regex" (string) containing an extended Posix regular expression for allowed address field values, and a "hint"/"hint_i18n" giving a human-readable explanation to display if the value entered by the user does not match the regex. Keys that are not mapped to such an object have no restriction on the value provided by the user. Examples would be '{"email":{"hint":"valid e-mail address required","regex":"^[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+\.[a-zA-Z0-9-.]+$"}' or '{"zip":{"hint":"numeric zip code required","regex":"^[0-9]+$"}'. + JSON object with a map of keys (names of the fields of the address to be entered by the user) to objects with a "regex" (string) containing an extended Posix regular expression for allowed address field values, and a "hint"/"hint_i18n" giving a human-readable explanation to display if the value entered by the user does not match the regex. Keys that are not mapped to such an object have no restriction on the value provided by the user. Examples would be '{"email":{"hint":"valid e-mail address required","regex":"^[a-zA-Z0-9\_.+-]+@[a-zA-Z0-9-]+\.[a-zA-Z0-9-.]+$"}' or '{"zip":{"hint":"numeric zip code required","regex":"^[0-9]+$"}'. SEE ALSO diff --git a/taler-developer-manual.rst b/taler-developer-manual.rst index 1aa5cc8d..3035e55d 100644 --- a/taler-developer-manual.rst +++ b/taler-developer-manual.rst @@ -1524,18 +1524,16 @@ use when talking to end users or even system administrators. trusted third party that verifies that the :term:`exchange` is operating correctly bank - traditional financial service provider who offers wire :term:`transfers ` between accounts + traditional financial service provider who offers + :term:`wire transfers ` between accounts buyer individual in control of a Taler :term:`wallet`, usually using it to - :term:`spend` the :term:`coins` on :term:`contracts` (see also :term:`customer`). + :term:`spend` the :term:`coins ` on :term:`contracts ` (see also :term:`customer`). close - closes - closed - closing operation an :term:`exchange` performs on a :term:`reserve` that has not been - :term:`drained` by :term:`withdraw` operations. When closing a reserve, the + :term:`emptied ` by :term:`withdraw` operations. When closing a reserve, the exchange wires the remaining funds back to the customer, minus a :term:`fee` for closing @@ -1543,10 +1541,8 @@ use when talking to end users or even system administrators. individual that directs the buyer (perhaps the same individual) to make a purchase coin - coins coins are individual token representing a certain amount of value, also known as the :term:`denomination` of the coin - commitment refresh commitment data that the wallet commits to during the :term:`melt` stage of the :term:`refresh` protocol where it @@ -1555,9 +1551,8 @@ use when talking to end users or even system administrators. probabilistically (see: :term:`kappa`) during the :term:`reveal` stage. contract - contracts formal agreement between :term:`merchant` and :term:`customer` specifying the - :term:`contract terms` and signed by the merchant and the :term:`coins` of the + :term:`contract terms` and signed by the merchant and the :term:`coins ` of the customer contract terms @@ -1573,32 +1568,32 @@ use when talking to end users or even system administrators. particular :term:`denomination` deposit - deposits - depositing operation by which a merchant passes coins to an exchange, expecting the exchange to credit his bank account in the future using an :term:`aggregate` :term:`wire transfer` drain - drained - a :term:`reserve` is being drained when a :term:`wallet` is using the - reserve's private key to :term:`withdraw` coins from it. This reduces - the balance of the reserve. Once the balance reaches zero, we say that - the reserve has been (fully) drained. Reserves that are not drained - (which is the normal process) are :term:`closed` by the exchange. + process by which an exchange operator takes the profits + (from :term:`fees `) out of the escrow account and moves them into + their regular business account dirty - dirty coin - a coin is dirty if its public key may be known to an entity other than + a :term:`coin` is dirty if its public key may be known to an entity other than the customer, thereby creating the danger of some entity being able to link multiple transactions of coin's owner if the coin is not refreshed + empty + a :term:`reserve` is being emptied when a :term:`wallet` is using the + reserve's private key to :term:`withdraw` coins from it. This reduces + the balance of the reserve. Once the balance reaches zero, we say that + the reserve has been (fully) emptied. Reserves that are not emptied + (which is the normal process) are :term:`closed ` by the exchange. + exchange Taler's payment service operator. Issues electronic coins during withdrawal and redeems them when they are deposited by merchants expired - expiration Various operations come with time limits. In particular, denomination keys come with strict time limits for the various operations involving the coin issued under the denomination. The most important limit is the @@ -1620,18 +1615,17 @@ use when talking to end users or even system administrators. fee an :term:`exchange` charges various fees for its service. The different fees are specified in the protocol. There are fees per coin for - :term:`withdrawing`, :term:`depositing`, :term:`melting`, and - :term:`refunding`. Furthermore, there are fees per wire transfer - for :term:`closing` a :term:`reserve`: and for - :term:`aggregate` :term:`wire transfers` to the :term:`merchant`. + :term:`withdrawing `, :term:`depositing `, :term:`melting `, and + :term:`refunding `. Furthermore, there are fees per wire transfer + when a :term:`reserve` is :term:`closed ` + and for :term:`aggregate` :term:`wire transfers ` + to the :term:`merchant`. fresh - fresh coin - a coin is fresh if its public key is only known to the customer + a :term:`coin` is fresh if its public key is only known to the customer - json JSON - JavaScript Object Notation + JavaScript Object Notation (JSON) is a serialization format derived from the JavaScript language which is commonly used in the Taler protocol as the payload of HTTP requests and responses. @@ -1641,11 +1635,11 @@ use when talking to end users or even system administrators. The probability of successfully evading the income transparency with the refresh protocol is 1:kappa. - LibEuFin - FIXME: explain + libeufin + Kotlin component that implements a regional currency bank and an + adapter to communicate via EBICS with European core banking systems. link - linking specific step in the :term:`refresh` protocol that an exchange must offer to prevent abuse of the :term:`refresh` mechanism. The link step is not needed in normal operation, it just must be offered. @@ -1655,9 +1649,7 @@ use when talking to end users or even system administrators. message signing keys melt - melted - melting - step of the :term:`refresh` protocol where a :term:`dirty coin` + step of the :term:`refresh` protocol where a :term:`dirty` :term:`coin` is invalidated to be reborn :term:`fresh` in a subsequent :term:`reveal` step. @@ -1683,19 +1675,19 @@ use when talking to end users or even system administrators. recoup Operation by which an exchange returns the value of coins affected - by a :term:`revocation` to their :term:`owner`, either by allowing the owner to + by a :term:`revocation ` to their :term:`owner`, either by allowing the owner to withdraw new coins or wiring funds back to the bank account of the :term:`owner`. planchet precursor data for a :term:`coin`. A planchet includes the coin's internal secrets (coin private key, blinding factor), but lacks the RSA signature - of the :term:`exchange`. When :term:`withdrawing`, a :term:`wallet` + of the :term:`exchange`. When :term:`withdrawing `, a :term:`wallet` creates and persists a planchet before asking the exchange to sign it to get the coin. purchase Refers to the overall process of negotiating a :term:`contract` and then - making a payment with :term:`coins` to a :term:`merchant`. + making a payment with :term:`coins ` to a :term:`merchant`. privacy policy Statement of an operator how they will protect the privacy of users. @@ -1708,13 +1700,11 @@ use when talking to end users or even system administrators. merchant backend. refresh - refreshing - operation by which a :term:`dirty coin` is converted into one or more - :term:`fresh` coins. Involves :term:`melting` the :term:`dirty coin` and - then :term:`revealing` so-called :term:`transfer keys`. + operation by which a :term:`dirty` :term:`coin` is converted into one or more + :term:`fresh` coins. Involves :term:`melting ` the :term:`dirty` coins and + then :term:`revealing ` so-called :term:`transfer keys `. refund - refunding operation by which a merchant steps back from the right to funds that he obtained from a :term:`deposit` operation, giving the right to the funds back to the customer @@ -1726,25 +1716,23 @@ use when talking to end users or even system administrators. reserve accounting mechanism used by the exchange to track customer funds - from incoming :term:`wire transfers`. A reserve is created whenever + from incoming :term:`wire transfers `. A reserve is created whenever a customer wires money to the exchange using a well-formed public key in the subject. The exchange then allows the customer's :term:`wallet` to :term:`withdraw` up to the amount received in :term:`fresh` - :term:`coins` from the reserve, thereby draining the reserve. If a - reserve is not drained, the exchange eventually :term:`closes` it. + :term:`coins ` from the reserve, thereby emptying the reserve. If a + reserve is not emptied, the exchange will eventually :term:`close` it. Other definition: Funds set aside for future use; either the balance of a customer at the exchange ready for withdrawal, or the funds kept in the exchange;s bank account to cover obligations from coins in circulation. reveal - revealing step in the :term:`refresh` protocol where some of the transfer private keys are revealed to prove honest behavior on the part of the wallet. In the reveal step, the exchange returns the signed :term:`fresh` coins. revoke - revocation exceptional operation by which an exchange withdraws a denomination from circulation, either because the signing key was compromised or because the exchange is going out of operation; unspent coins of a revoked @@ -1756,22 +1744,14 @@ use when talking to end users or even system administrators. time. spend - spending operation by which a customer gives a merchant the right to deposit coins in return for merchandise - transfer - transfers - wire transfer - wire transfers - method of sending funds between :term:`bank` accounts - transfer key - transfer keys special cryptographic key used in the :term:`refresh` protocol, some of which are revealed during the :term:`reveal` step. Note that transfer keys have, - despite the name, no relationship to :term:`wire transfers`. They merely - help to transfer the value from a :term:`dirty coin` to a :term:`fresh coin` + despite the name, no relationship to :term:`wire transfers `. They merely + help to transfer the value from a :term:`dirty` coin to a :term:`fresh` coin terms the general terms of service of an operator, possibly including @@ -1804,25 +1784,27 @@ use when talking to end users or even system administrators. Cross-browser API used to implement the GNU Taler wallet browser extension. wire gateway - FIXME: explain + API used by the exchange to talk with some real-time gross settlement system + (core banking system, blockchain) to notice inbound credits wire transfers + (during withdraw) and to trigger outbound debit wire transfers (primarily + for deposits). + + wire transfer + a wire transfer is a method of sending funds between :term:`bank` accounts wire transfer identifier - wtid Subject of a wire transfer from the exchange to a merchant; set by the aggregator to a random nonce which uniquely identifies the transfer. withdraw - withdrawing - withdrawal operation by which a :term:`wallet` can convert funds from a :term:`reserve` to fresh coins zombie - zombie coin - coin where the respective :term:`denomination key` is past its - :term:`deposit` :term:`expiration` time, but which is still (again) valid - for an operation because it was :term:`melted` while it was still + :term:`coin` where the respective :term:`denomination key` is past its + :term:`deposit` :term:`expiration ` time, but which is still (again) valid + for an operation because it was :term:`melted ` while it was still valid, and then later again credited during a :term:`recoup` process -- cgit v1.2.3 From 570cd03a8a39605fe667067cc0b84701e441c680 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Thu, 7 Mar 2024 10:01:29 +0100 Subject: -fix build issues --- core/api-merchant.rst | 2 +- design-documents/054-dynamic-form.rst | 14 +++++++------- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/core/api-merchant.rst b/core/api-merchant.rst index 00e4a7f6..a291d9cf 100644 --- a/core/api-merchant.rst +++ b/core/api-merchant.rst @@ -2789,7 +2789,7 @@ to validate that a customer made a payment. // ``otp_algorithm`` and matching client query arguments. // // Available since protocol **v10**. - otp_code?: String; + otp_code?: string; } diff --git a/design-documents/054-dynamic-form.rst b/design-documents/054-dynamic-form.rst index 6ff84d41..d93b3684 100644 --- a/design-documents/054-dynamic-form.rst +++ b/design-documents/054-dynamic-form.rst @@ -51,7 +51,7 @@ readOnly (flag to disable input), onUpdate (callback on form data update), and computeFormState (function to derive the form state based on current data). -.. code-block:: javascript +.. code-block:: typescript interface FormType { value: Partial; @@ -82,7 +82,7 @@ The field type ``AmountJson`` and ``AbsoluteTime`` are opaque since field is use The form can be instanciated using -.. code-block:: javascript +.. code-block:: typescript import { FormProvider } from "@gnu-taler/web-util/browser"; @@ -90,7 +90,7 @@ The form can be instanciated using Then the field component can access all the properties by the ``useField(name)`` hook, which will return -.. code-block:: javascript +.. code-block:: typescript interface InputFieldHandler { value: Type; @@ -116,10 +116,10 @@ A set of common form field exist in ``@gnu-taler/web-util``: and should be used inside a ``Form`` context. -.. code-block:: javascript +.. code-block:: none function MyFormComponent():VNode { - return + return @@ -132,7 +132,7 @@ Example Consider a form shape represented by the TypeScript type: -.. code-block:: javascript +.. code-block:: typescript type TheFormType = { name: string, @@ -148,7 +148,7 @@ Consider a form shape represented by the TypeScript type: An example instance of this form could be: -.. code-block:: javascript +.. code-block:: typescript const theFormValue: TheFormType = { name: "Sebastian", -- cgit v1.2.3 From a864b45f2454038b7a6055b6b44c53bfc5b2f6f4 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Thu, 7 Mar 2024 10:08:27 +0100 Subject: -fix more build issues --- core/api-bank-revenue.rst | 2 +- design-documents/024-age-restriction.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/core/api-bank-revenue.rst b/core/api-bank-revenue.rst index a647fb35..98b38113 100644 --- a/core/api-bank-revenue.rst +++ b/core/api-bank-revenue.rst @@ -110,7 +110,7 @@ Querying the transaction history **Response:** :http:statuscode:`200 OK`: - JSON object of type `MerchantIncomingHistory`. + JSON object of type `RevenueIncomingHistory`. :http:statuscode:`400 Bad request`: Request malformed. The bank replies with an `ErrorDetail` object. :http:statuscode:`401 Unauthorized`: diff --git a/design-documents/024-age-restriction.rst b/design-documents/024-age-restriction.rst index ee478ee1..0445aa6d 100644 --- a/design-documents/024-age-restriction.rst +++ b/design-documents/024-age-restriction.rst @@ -247,7 +247,7 @@ changed since the given timestamp. // Similar as for ``.denoms``, if the query parameter ``last_issue_date`` // was provided by the client, the exchange will only return the keys that // have changed since the given timestamp. - age_restricted_denoms: Denom[]; + age_restricted_denoms: DenomCommon[]; //... } -- cgit v1.2.3 From d13c3cb6a5a7a2da100c0479a38ffe9d1df5fe2c Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Thu, 7 Mar 2024 10:27:37 +0100 Subject: fix name --- core/api-corebank.rst | 8 +++---- images/kyc-process.pdf | Bin 0 -> 24633 bytes images/kyc-process.png | Bin 0 -> 44435 bytes images/kyc-process.tex | 58 ++++++++++++++++++++++++++++++++++++++++++++++ kyc-process.pdf | Bin 24633 -> 0 bytes kyc-process.png | Bin 44435 -> 0 bytes kyc-process.tex | 58 ---------------------------------------------- taler-exchange-manual.rst | 2 +- 8 files changed, 63 insertions(+), 63 deletions(-) create mode 100644 images/kyc-process.pdf create mode 100644 images/kyc-process.png create mode 100644 images/kyc-process.tex delete mode 100644 kyc-process.pdf delete mode 100644 kyc-process.png delete mode 100644 kyc-process.tex diff --git a/core/api-corebank.rst b/core/api-corebank.rst index e1cb4fb6..851fc3ba 100644 --- a/core/api-corebank.rst +++ b/core/api-corebank.rst @@ -83,7 +83,7 @@ Config // The format is "current:revision:age". version: string; - // Bank display name to be used in user interfaces. + // Bank display name to be used in user interfaces. // For consistency use "Taler Bank" if missing. // @since v4, will become mandatory in the next version. bank_name?: string; @@ -175,7 +175,7 @@ Account Management cashout_payto_uri?: string; // Internal payto URI of this bank account. - // Used mostly for testing, this field is ignored if the bank payment + // Used mostly for testing, this field is ignored if the bank payment // method is not IBAN. payto_uri?: string; @@ -507,7 +507,7 @@ Account Management // as well. contact_data?: ChallengeContactData; - // IBAN 'payto' URI with a 'receiver-name' parameter of a fiat bank + // IBAN 'payto' URI with a 'receiver-name' parameter of a fiat bank // account where to send cashouts. This field is optional // because not all the accounts are required to participate // in the merchants' circuit. One example is the exchange: @@ -831,7 +831,7 @@ Cashouts :http:statuscode:`200 OK`: The cashout request was correctly created. - This returns the `CashoutPending` response. + This returns the `CashoutResponse` response. :http:statuscode:`202 Accepted`: 2FA is required for this operation. This returns the `Challenge` response. :http:statuscode:`404 Not found`: diff --git a/images/kyc-process.pdf b/images/kyc-process.pdf new file mode 100644 index 00000000..8b178c02 Binary files /dev/null and b/images/kyc-process.pdf differ diff --git a/images/kyc-process.png b/images/kyc-process.png new file mode 100644 index 00000000..563418b1 Binary files /dev/null and b/images/kyc-process.png differ diff --git a/images/kyc-process.tex b/images/kyc-process.tex new file mode 100644 index 00000000..c10dd8d9 --- /dev/null +++ b/images/kyc-process.tex @@ -0,0 +1,58 @@ +\documentclass[fleqn]{article} +\usepackage{amsmath} +\usepackage{multimedia} +\usepackage[utf8]{inputenc} +\usepackage{framed,color,ragged2e} +\usepackage[absolute,overlay]{textpos} +\usepackage{xcolor} +\usepackage{relsize} +\usepackage{graphicx} +\usepackage{tikz,eurosym,calc} +\usetikzlibrary{tikzmark} +\usetikzlibrary{shapes,arrows,arrows.meta} +\usetikzlibrary{positioning,fit,patterns} +\usetikzlibrary{calc} +\usepackage{pgf-umlsd} +\usepackage{relsize} + +\pagestyle{empty} +\begin{document} + +\begin{sequencediagram} + \newinst{customer}{Customer} + \newinst[4]{ex}{Exchange} + \newinst[4]{kyc}{KYC Provider} + \postlevel + \mess[0]{customer}{POST: payment request}{ex} + \mess[0]{ex}{POST: initiate KYC}{kyc} + \mess[0]{kyc}{KYC-Start-URL}{ex} + \mess[0]{ex}{KYC-Start-URL}{customer} + \postlevel + \mess[0]{customer}{GET: KYC-Start-URL}{kyc} + \mess[0]{kyc}{KYC Web Form}{customer} + \mess[0]{customer}{POST: KYC data}{kyc} + \mess[0]{kyc}{redirect URL or pending}{customer} + \postlevel + \begin{sdblock}{alternative}{} + \mess[0]{customer}{GET: redirect URL}{ex} + \mess[0]{ex}{Thanks!}{customer} + \end{sdblock} + \prelevel + \prelevel + \prelevel + \prelevel + \prelevel + \begin{sdblock}{alternative}{} + \mess[0]{kyc}{Async validation finished Webhook}{ex} + \mess[0]{ex}{Thanks!}{kyc} + \end{sdblock} + \postlevel + \mess[0]{ex}{GET: KYC status?}{kyc} + \mess[0]{kyc}{KYC data}{ex} + \mess[0]{customer}{POST: payment request}{ex} + \mess[0]{ex}{normal response}{customer} +\end{sequencediagram} + +\end{document} + + diff --git a/kyc-process.pdf b/kyc-process.pdf deleted file mode 100644 index 8b178c02..00000000 Binary files a/kyc-process.pdf and /dev/null differ diff --git a/kyc-process.png b/kyc-process.png deleted file mode 100644 index 563418b1..00000000 Binary files a/kyc-process.png and /dev/null differ diff --git a/kyc-process.tex b/kyc-process.tex deleted file mode 100644 index c10dd8d9..00000000 --- a/kyc-process.tex +++ /dev/null @@ -1,58 +0,0 @@ -\documentclass[fleqn]{article} -\usepackage{amsmath} -\usepackage{multimedia} -\usepackage[utf8]{inputenc} -\usepackage{framed,color,ragged2e} -\usepackage[absolute,overlay]{textpos} -\usepackage{xcolor} -\usepackage{relsize} -\usepackage{graphicx} -\usepackage{tikz,eurosym,calc} -\usetikzlibrary{tikzmark} -\usetikzlibrary{shapes,arrows,arrows.meta} -\usetikzlibrary{positioning,fit,patterns} -\usetikzlibrary{calc} -\usepackage{pgf-umlsd} -\usepackage{relsize} - -\pagestyle{empty} -\begin{document} - -\begin{sequencediagram} - \newinst{customer}{Customer} - \newinst[4]{ex}{Exchange} - \newinst[4]{kyc}{KYC Provider} - \postlevel - \mess[0]{customer}{POST: payment request}{ex} - \mess[0]{ex}{POST: initiate KYC}{kyc} - \mess[0]{kyc}{KYC-Start-URL}{ex} - \mess[0]{ex}{KYC-Start-URL}{customer} - \postlevel - \mess[0]{customer}{GET: KYC-Start-URL}{kyc} - \mess[0]{kyc}{KYC Web Form}{customer} - \mess[0]{customer}{POST: KYC data}{kyc} - \mess[0]{kyc}{redirect URL or pending}{customer} - \postlevel - \begin{sdblock}{alternative}{} - \mess[0]{customer}{GET: redirect URL}{ex} - \mess[0]{ex}{Thanks!}{customer} - \end{sdblock} - \prelevel - \prelevel - \prelevel - \prelevel - \prelevel - \begin{sdblock}{alternative}{} - \mess[0]{kyc}{Async validation finished Webhook}{ex} - \mess[0]{ex}{Thanks!}{kyc} - \end{sdblock} - \postlevel - \mess[0]{ex}{GET: KYC status?}{kyc} - \mess[0]{kyc}{KYC data}{ex} - \mess[0]{customer}{POST: payment request}{ex} - \mess[0]{ex}{normal response}{customer} -\end{sequencediagram} - -\end{document} - - diff --git a/taler-exchange-manual.rst b/taler-exchange-manual.rst index 57db7095..f0c345c7 100644 --- a/taler-exchange-manual.rst +++ b/taler-exchange-manual.rst @@ -978,7 +978,7 @@ Taler permits an exchange to require KYC data under the following circumstances: Any of the above requests can trigger the KYC process, which can be illustrated as follows: -.. image:: kyc-process.png +.. image:: images/kyc-process.png At the end of the KYC process, the wallet re-tries the original request, and assuming KYC was successful, the -- cgit v1.2.3 From 7768e98a8e1d27f8c612757e145d9076dfc9d9ea Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Thu, 7 Mar 2024 11:32:55 +0100 Subject: fix categories --- conf.py | 36 ++++++++++++++++++------------------ 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/conf.py b/conf.py index 9e16a795..d19481ed 100644 --- a/conf.py +++ b/conf.py @@ -765,54 +765,54 @@ texinfo_documents = [ "taler-auditor", "Taler Auditor Manual", "GNU Taler team", - "MENU ENTRY", - "DESCRIPTION", - "CATEGORY", + "GNU Taler Auditor", + "External audit for Taler Exchange operation", + "Networking", ), ( "taler-exchange-manual", "taler-exchange", "Taler Exchange Manual", "GNU Taler team", - "MENU ENTRY", - "DESCRIPTION", - "CATEGORY", + "GNU Taler Exchange", + "Taler payment service provider", + "Networking", ), ( "taler-challenger-manual", "challenger", "Taler Challenger Manual", "GNU Taler team", - "MENU ENTRY", - "DESCRIPTION", - "CATEGORY", + "Challenger", + "OAuth2-based customer address validation service", + "Networking", ), ( "taler-merchant-manual", "taler-merchant", "Taler Merchant Manual", "GNU Taler team", - "MENU ENTRY", - "DESCRIPTION", - "CATEGORY", + "GNU Taler Merchant", + "Backend for merchants accepting Taler payments", + "Networking", ), ( "taler-merchant-api-tutorial", "taler-merchant-api-tutorial", "Taler Merchant API Tutorial", "GNU Taler team", - "MENU ENTRY", - "DESCRIPTION", - "CATEGORY", + "GNU Taler Merchant API", + "Tutorial for using the merchant backend API", + "Networking", ), ( "taler-developer-manual", "taler-developer-manual", "Taler Developer Manual", "GNU Taler team", - "MENU ENTRY", - "DESCRIPTION", - "CATEGORY", + "GNU Taler Development", + "Manual for GNU Taler contributors", + "Networking", ), ] -- cgit v1.2.3 From 814e64550f31e73949fce3b7d8bd38720168ecaf Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Thu, 7 Mar 2024 11:35:49 +0100 Subject: -fix warning --- checklists/qa-0.9.4.rst | 25 ++++++++++++------------- 1 file changed, 12 insertions(+), 13 deletions(-) diff --git a/checklists/qa-0.9.4.rst b/checklists/qa-0.9.4.rst index 98680c8d..77e51081 100644 --- a/checklists/qa-0.9.4.rst +++ b/checklists/qa-0.9.4.rst @@ -1,9 +1,8 @@ -=================== Taler 0.9.4 QA Plan -=================== +------------------- Wallet Platforms -================ +^^^^^^^^^^^^^^^^ Platforms listed here are the officially supported platforms for this release. @@ -26,7 +25,7 @@ Platforms listed here are the officially supported platforms for this release. Running Deployments -=================== +^^^^^^^^^^^^^^^^^^^ These deployments are maintained by us and should work for the release: @@ -42,7 +41,7 @@ These deployments are maintained by us and should work for the release: Wallet Flows -============ +^^^^^^^^^^^^ * Bank-integrated withdrawal @@ -80,7 +79,7 @@ Wallet Flows libeufin-bank Flows -=================== +^^^^^^^^^^^^^^^^^^^ * Admin functionality @@ -112,7 +111,7 @@ libeufin-bank Flows Merchant Backend SPA Flows -========================== +^^^^^^^^^^^^^^^^^^^^^^^^^^ * Instance creation @@ -161,7 +160,7 @@ Merchant Backend SPA Flows Regio Deployment -================ +^^^^^^^^^^^^^^^^ * Deployment Automation (deployment.git/regional-currency) @@ -189,26 +188,26 @@ Regio Deployment Android Merchant PoS -==================== +^^^^^^^^^^^^^^^^^^^^ * Test against demo.taler.net Android Cashier App -=================== +^^^^^^^^^^^^^^^^^^^ * Test against demo.taler.net CI -== +^^ * https://buildbot.taler.net/#/waterfall * CI should pass Debian Repository -================= +^^^^^^^^^^^^^^^^^ * Debian @@ -223,7 +222,7 @@ Debian Repository GNU Release -=========== +^^^^^^^^^^^ * Release announcement * FTP upload -- cgit v1.2.3 From e1e7eb367e6b799cb75d8763f8236cd9974f5814 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Thu, 7 Mar 2024 11:40:43 +0100 Subject: -bump version --- conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/conf.py b/conf.py index d19481ed..280579cd 100644 --- a/conf.py +++ b/conf.py @@ -87,7 +87,7 @@ copyright = "2014-2022 Taler Systems SA (GPLv3+ or GFDL 1.3+)" # The short X.Y version. version = "0.9" # The full version, including alpha/beta/rc tags. -release = "0.9.0" +release = "0.9.4" # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. -- cgit v1.2.3 From eab66ca5d92a30e32f1ad9d6eec8f0e8cd359c68 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Thu, 7 Mar 2024 11:56:49 +0100 Subject: bump year --- conf.py | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/conf.py b/conf.py index 280579cd..db8a4069 100644 --- a/conf.py +++ b/conf.py @@ -78,7 +78,7 @@ master_doc = "index" # General information about the project. project = "GNU Taler" -copyright = "2014-2022 Taler Systems SA (GPLv3+ or GFDL 1.3+)" +copyright = "2014-2024 Taler Systems SA (GPLv3+ or GFDL 1.3+)" # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the @@ -767,7 +767,7 @@ texinfo_documents = [ "GNU Taler team", "GNU Taler Auditor", "External audit for Taler Exchange operation", - "Networking", + "Network applications", ), ( "taler-exchange-manual", @@ -776,16 +776,16 @@ texinfo_documents = [ "GNU Taler team", "GNU Taler Exchange", "Taler payment service provider", - "Networking", + "Network applications", ), ( "taler-challenger-manual", "challenger", "Taler Challenger Manual", "GNU Taler team", - "Challenger", - "OAuth2-based customer address validation service", - "Networking", + "GNU Taler Challenger", + "Customer address validation service", + "Network applications", ), ( "taler-merchant-manual", @@ -794,7 +794,7 @@ texinfo_documents = [ "GNU Taler team", "GNU Taler Merchant", "Backend for merchants accepting Taler payments", - "Networking", + "Network applications", ), ( "taler-merchant-api-tutorial", @@ -803,7 +803,7 @@ texinfo_documents = [ "GNU Taler team", "GNU Taler Merchant API", "Tutorial for using the merchant backend API", - "Networking", + "Network applications", ), ( "taler-developer-manual", @@ -812,7 +812,7 @@ texinfo_documents = [ "GNU Taler team", "GNU Taler Development", "Manual for GNU Taler contributors", - "Networking", + "Network applications", ), ] -- cgit v1.2.3 From 9df45adc3bb4a4e4f38a5e8ba44d6f00058bcdc4 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Thu, 7 Mar 2024 13:03:48 +0100 Subject: -change 406 to 400 --- core/api-merchant.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/core/api-merchant.rst b/core/api-merchant.rst index a291d9cf..d21d8073 100644 --- a/core/api-merchant.rst +++ b/core/api-merchant.rst @@ -288,17 +288,17 @@ Making the payment Either the client request is malformed or some specific processing error happened that may be the fault of the client as detailed in the JSON body of the response. + This includes the case where the payment is insufficient (sum is below + the required total amount, for example because the wallet calculated the + fees wrong). :http:statuscode:`402 Payment required`: There used to be a sufficient payment, but due to refunds the amount effectively paid is no longer sufficient. (If the amount is generally insufficient, we - return "406 Not Acceptable", only if this is because of refunds we return 402.) + return "400 Bad Request", only if this is because of refunds we return 402.) :http:statuscode:`403 Forbidden`: One of the coin signatures was not valid. :http:statuscode:`404 Not found`: The merchant backend could not find the order or the instance and thus cannot process the payment. - :http:statuscode:`406 Not acceptable`: - The payment is insufficient (sum is below the required total amount). - TODO: Should probably change to a different status code in the future as 406 is technically wrong. :http:statuscode:`408 Request timeout`: The backend took too long to process the request. Likely the merchant's connection to the exchange timed out. Try again. -- cgit v1.2.3 From 767c7bfb838bb6667239a4854ed0c51b504fb625 Mon Sep 17 00:00:00 2001 From: Iván Ávalos Date: Thu, 7 Mar 2024 10:49:18 -0600 Subject: DD53: screens from Android wallet --- .gitignore | 2 ++ design-documents/053-wallet-ui.rst | 32 +++++++++++++++++++-- .../android-wallet/accept-tos.png | Bin 0 -> 118553 bytes .../android-wallet/cta-deposit.png | Bin 0 -> 54746 bytes .../android-wallet/cta-payment-paid.png | Bin 0 -> 55338 bytes .../android-wallet/cta-payment.png | Bin 0 -> 59747 bytes .../android-wallet/cta-peer-pull-initiate.png | Bin 0 -> 54340 bytes .../android-wallet/cta-peer-push-initiate.png | Bin 0 -> 50363 bytes .../android-wallet/cta-url-entry-1.png | Bin 0 -> 87037 bytes .../android-wallet/cta-url-entry-2.png | Bin 0 -> 23916 bytes .../android-wallet/cta-wire-transfer-1.png | Bin 0 -> 68795 bytes .../android-wallet/cta-wire-transfer-2.png | Bin 0 -> 60355 bytes .../android-wallet/cta-withdraw-1.png | Bin 0 -> 42897 bytes .../android-wallet/cta-withdraw-2.png | Bin 0 -> 43977 bytes .../android-wallet/cta-withdraw-done.png | Bin 0 -> 44643 bytes 15 files changed, 32 insertions(+), 2 deletions(-) create mode 100644 design-documents/wallet-screenshots/android-wallet/accept-tos.png create mode 100644 design-documents/wallet-screenshots/android-wallet/cta-deposit.png create mode 100644 design-documents/wallet-screenshots/android-wallet/cta-payment-paid.png create mode 100644 design-documents/wallet-screenshots/android-wallet/cta-payment.png create mode 100644 design-documents/wallet-screenshots/android-wallet/cta-peer-pull-initiate.png create mode 100644 design-documents/wallet-screenshots/android-wallet/cta-peer-push-initiate.png create mode 100644 design-documents/wallet-screenshots/android-wallet/cta-url-entry-1.png create mode 100644 design-documents/wallet-screenshots/android-wallet/cta-url-entry-2.png create mode 100644 design-documents/wallet-screenshots/android-wallet/cta-wire-transfer-1.png create mode 100644 design-documents/wallet-screenshots/android-wallet/cta-wire-transfer-2.png create mode 100644 design-documents/wallet-screenshots/android-wallet/cta-withdraw-1.png create mode 100644 design-documents/wallet-screenshots/android-wallet/cta-withdraw-2.png create mode 100644 design-documents/wallet-screenshots/android-wallet/cta-withdraw-done.png diff --git a/.gitignore b/.gitignore index 7dab94e6..b1119077 100644 --- a/.gitignore +++ b/.gitignore @@ -12,3 +12,5 @@ images/deposit.png images/reserve.png *.png texinfo/ + +!/design-documents/wallet-screenshots/**/*.png diff --git a/design-documents/053-wallet-ui.rst b/design-documents/053-wallet-ui.rst index c36d4759..d57dfb53 100644 --- a/design-documents/053-wallet-ui.rst +++ b/design-documents/053-wallet-ui.rst @@ -98,6 +98,9 @@ fee, restrictions and ETA should be clear for the user. .. attention:: User should be able to play with the amount, not possible in the current design +.. image:: ./wallet-screenshots/android-wallet/cta-withdraw-2.png + :width: 30% + cta-wire-transfer ----------------- @@ -116,6 +119,10 @@ the wire transfer to complete a manual withdrawal operation. * automatic: screen changes to "cta-withdraw-done" upon completion .. image:: ../screenshots/cta-wire-transfer-firefox-latest.png +.. image:: ./wallet-screenshots/android-wallet/cta-wire-transfer-1.png + :width: 30% +.. image:: ./wallet-screenshots/android-wallet/cta-wire-transfer-2.png + :width: 30% cta-withdraw-done ----------------- @@ -134,7 +141,9 @@ a completed withdraw operation (bank-integrated or manual) * delete: deletes information about the withdrawal operation .. image:: ../screenshots/cta-withdraw-done-firefox-latest.png - + :width: 60% +.. image:: ./wallet-screenshots/android-wallet/cta-withdraw-done.png + :width: 30% cta-url-entry ------------- @@ -156,6 +165,10 @@ depending on implementation specifics. * back: return to previous view .. image:: ../screenshots/cta-url-entry-firefox-latest.png +.. image:: ./wallet-screenshots/android-wallet/cta-url-entry-1.png + :width: 30% +.. image:: ./wallet-screenshots/android-wallet/cta-url-entry-2.png + :width: 30% cta-payment @@ -182,6 +195,9 @@ fee, restrictions and ETA should be clear for the user. * cancel: user will be redirected to ``balance`` .. image:: ../screenshots/cta-payment-firefox-latest.png + :width: 60% +.. image:: ./wallet-screenshots/android-wallet/cta-payment.png + :width: 30% cta-payment-paid ---------------- @@ -201,6 +217,9 @@ about a historic payment. * back: user will be redirected to ``balance`` .. image:: ../screenshots/cta-payment-paid-firefox-latest.png + :width: 60% +.. image:: ./wallet-screenshots/android-wallet/cta-payment-paid.png + :width: 30% cta-deposit ------------ @@ -221,6 +240,8 @@ fee, restrictions and ETA should be clear for the user. .. attention:: User should be able to play with the amount, not possible in the current design +.. image:: ./wallet-screenshots/android-wallet/cta-deposit.png + :width: 30% cta-peer-pull-initiate ---------------------- @@ -249,6 +270,8 @@ fee, restrictions and ETA should be clear for the user. Is the invoice creation always free of charge or does the exchange have a mechanism to impose a fee to pay on creation? +.. image:: ./wallet-screenshots/android-wallet/cta-peer-pull-initiate.png + :width: 30% cta-peer-pull-confirm --------------------- @@ -289,6 +312,9 @@ fee, restrictions and ETA should be clear for the user. * confirm operation: on success will be redirected to the ``transaction-details`` screen where the detail of the current transaction will be displayed * cancel: user will be redirected to ``balance`` +.. image:: ./wallet-screenshots/android-wallet/cta-peer-push-initiate.png + :width: 30% + cta-peer-push-confirm --------------------- @@ -349,7 +375,9 @@ user already accepted ToS) * save/print tos: will save the ToS outside of the wallet .. image:: ../screenshots/cta-accept-tos-firefox-latest.png - + :width: 45% +.. image:: ./wallet-screenshots/android-wallet/accept-tos.png + :width: 45% Q / A ===== diff --git a/design-documents/wallet-screenshots/android-wallet/accept-tos.png b/design-documents/wallet-screenshots/android-wallet/accept-tos.png new file mode 100644 index 00000000..c9537071 Binary files /dev/null and b/design-documents/wallet-screenshots/android-wallet/accept-tos.png differ diff --git a/design-documents/wallet-screenshots/android-wallet/cta-deposit.png b/design-documents/wallet-screenshots/android-wallet/cta-deposit.png new file mode 100644 index 00000000..74435360 Binary files /dev/null and b/design-documents/wallet-screenshots/android-wallet/cta-deposit.png differ diff --git a/design-documents/wallet-screenshots/android-wallet/cta-payment-paid.png b/design-documents/wallet-screenshots/android-wallet/cta-payment-paid.png new file mode 100644 index 00000000..51a412c7 Binary files /dev/null and b/design-documents/wallet-screenshots/android-wallet/cta-payment-paid.png differ diff --git a/design-documents/wallet-screenshots/android-wallet/cta-payment.png b/design-documents/wallet-screenshots/android-wallet/cta-payment.png new file mode 100644 index 00000000..d518c922 Binary files /dev/null and b/design-documents/wallet-screenshots/android-wallet/cta-payment.png differ diff --git a/design-documents/wallet-screenshots/android-wallet/cta-peer-pull-initiate.png b/design-documents/wallet-screenshots/android-wallet/cta-peer-pull-initiate.png new file mode 100644 index 00000000..9be8abdf Binary files /dev/null and b/design-documents/wallet-screenshots/android-wallet/cta-peer-pull-initiate.png differ diff --git a/design-documents/wallet-screenshots/android-wallet/cta-peer-push-initiate.png b/design-documents/wallet-screenshots/android-wallet/cta-peer-push-initiate.png new file mode 100644 index 00000000..8ee0ef7d Binary files /dev/null and b/design-documents/wallet-screenshots/android-wallet/cta-peer-push-initiate.png differ diff --git a/design-documents/wallet-screenshots/android-wallet/cta-url-entry-1.png b/design-documents/wallet-screenshots/android-wallet/cta-url-entry-1.png new file mode 100644 index 00000000..0705e7f0 Binary files /dev/null and b/design-documents/wallet-screenshots/android-wallet/cta-url-entry-1.png differ diff --git a/design-documents/wallet-screenshots/android-wallet/cta-url-entry-2.png b/design-documents/wallet-screenshots/android-wallet/cta-url-entry-2.png new file mode 100644 index 00000000..18ed9bdf Binary files /dev/null and b/design-documents/wallet-screenshots/android-wallet/cta-url-entry-2.png differ diff --git a/design-documents/wallet-screenshots/android-wallet/cta-wire-transfer-1.png b/design-documents/wallet-screenshots/android-wallet/cta-wire-transfer-1.png new file mode 100644 index 00000000..71e354f6 Binary files /dev/null and b/design-documents/wallet-screenshots/android-wallet/cta-wire-transfer-1.png differ diff --git a/design-documents/wallet-screenshots/android-wallet/cta-wire-transfer-2.png b/design-documents/wallet-screenshots/android-wallet/cta-wire-transfer-2.png new file mode 100644 index 00000000..719b890c Binary files /dev/null and b/design-documents/wallet-screenshots/android-wallet/cta-wire-transfer-2.png differ diff --git a/design-documents/wallet-screenshots/android-wallet/cta-withdraw-1.png b/design-documents/wallet-screenshots/android-wallet/cta-withdraw-1.png new file mode 100644 index 00000000..3da47302 Binary files /dev/null and b/design-documents/wallet-screenshots/android-wallet/cta-withdraw-1.png differ diff --git a/design-documents/wallet-screenshots/android-wallet/cta-withdraw-2.png b/design-documents/wallet-screenshots/android-wallet/cta-withdraw-2.png new file mode 100644 index 00000000..dbe4c7b1 Binary files /dev/null and b/design-documents/wallet-screenshots/android-wallet/cta-withdraw-2.png differ diff --git a/design-documents/wallet-screenshots/android-wallet/cta-withdraw-done.png b/design-documents/wallet-screenshots/android-wallet/cta-withdraw-done.png new file mode 100644 index 00000000..5860f280 Binary files /dev/null and b/design-documents/wallet-screenshots/android-wallet/cta-withdraw-done.png differ -- cgit v1.2.3 From 11a31158a2829d01aa6c57fab6673af32d12d24d Mon Sep 17 00:00:00 2001 From: Iván Ávalos Date: Thu, 7 Mar 2024 14:58:02 -0600 Subject: DD53: improve DD53 structure and add screenshots --- .gitignore | 1 + design-documents/053-wallet-ui.rst | 683 +++++++++++++++------ .../android-wallet/accept-tos.png | Bin 118553 -> 0 bytes .../android-wallet/cta-deposit.png | Bin 54746 -> 0 bytes .../android-wallet/cta-payment-paid.png | Bin 55338 -> 0 bytes .../android-wallet/cta-payment.png | Bin 59747 -> 0 bytes .../android-wallet/cta-peer-pull-initiate.png | Bin 54340 -> 0 bytes .../android-wallet/cta-peer-push-initiate.png | Bin 50363 -> 0 bytes .../android-wallet/cta-url-entry-1.png | Bin 87037 -> 0 bytes .../android-wallet/cta-url-entry-2.png | Bin 23916 -> 0 bytes .../android-wallet/cta-wire-transfer-1.png | Bin 68795 -> 0 bytes .../android-wallet/cta-wire-transfer-2.png | Bin 60355 -> 0 bytes .../android-wallet/cta-withdraw-1.png | Bin 42897 -> 0 bytes .../android-wallet/cta-withdraw-2.png | Bin 43977 -> 0 bytes .../android-wallet/cta-withdraw-done.png | Bin 44643 -> 0 bytes screenshots/balance-list-android-0.png | Bin 0 -> 47885 bytes screenshots/balance-list-android-latest.png | 1 + screenshots/balance-list-firefox-0.png | Bin 0 -> 44775 bytes screenshots/balance-list-firefox-latest.png | 1 + screenshots/cta-accept-tos-android-0.png | Bin 0 -> 118553 bytes screenshots/cta-accept-tos-android-latest.png | 1 + screenshots/cta-deposit-android-0.png | Bin 0 -> 54746 bytes screenshots/cta-deposit-android-latest.png | 1 + screenshots/cta-deposit-firefox-0.png | Bin 0 -> 59490 bytes screenshots/cta-deposit-firefox-latest.png | 1 + screenshots/cta-payment-android-0.png | Bin 0 -> 59747 bytes screenshots/cta-payment-android-latest.png | 1 + screenshots/cta-payment-paid-android-0.png | Bin 0 -> 55338 bytes screenshots/cta-payment-paid-android-latest.png | 1 + screenshots/cta-peer-pull-initiate-android-0.png | Bin 0 -> 54340 bytes .../cta-peer-pull-initiate-android-latest.png | 1 + screenshots/cta-peer-pull-initiate-firefox-0.png | Bin 0 -> 62019 bytes .../cta-peer-pull-initiate-firefox-latest.png | 1 + screenshots/cta-peer-push-initiate-android-0.png | Bin 0 -> 50363 bytes .../cta-peer-push-initiate-android-latest.png | 1 + screenshots/cta-peer-push-initiate-firefox-0.png | Bin 0 -> 56300 bytes .../cta-peer-push-initiate-firefox-latest.png | 1 + screenshots/cta-url-entry-1-android-0.png | Bin 0 -> 87037 bytes screenshots/cta-url-entry-1-android-latest.png | 1 + screenshots/cta-url-entry-2-android-0.png | Bin 0 -> 23916 bytes screenshots/cta-url-entry-2-android-latest.png | 1 + screenshots/cta-wire-transfer-1-android-0.png | Bin 0 -> 68795 bytes screenshots/cta-wire-transfer-1-android-latest.png | 1 + screenshots/cta-wire-transfer-2-android-0.png | Bin 0 -> 60355 bytes screenshots/cta-wire-transfer-2-android-latest.png | 1 + screenshots/cta-withdraw-1-android-0.png | Bin 0 -> 42897 bytes screenshots/cta-withdraw-1-android-latest.png | 1 + screenshots/cta-withdraw-2-android-0.png | Bin 0 -> 43977 bytes screenshots/cta-withdraw-2-android-latest.png | 1 + screenshots/cta-withdraw-done-android-0.png | Bin 0 -> 44643 bytes screenshots/cta-withdraw-done-android-latest.png | 1 + screenshots/cta-withdraw-firefox-1.png | Bin 0 -> 50475 bytes screenshots/cta-withdraw-firefox-latest.png | 2 +- screenshots/transaction-list-android-0.png | Bin 0 -> 83906 bytes screenshots/transaction-list-android-latest.png | 1 + screenshots/transaction-list-firefox-0.png | Bin 0 -> 47985 bytes screenshots/transaction-list-firefox-latest.png | 1 + 57 files changed, 505 insertions(+), 201 deletions(-) delete mode 100644 design-documents/wallet-screenshots/android-wallet/accept-tos.png delete mode 100644 design-documents/wallet-screenshots/android-wallet/cta-deposit.png delete mode 100644 design-documents/wallet-screenshots/android-wallet/cta-payment-paid.png delete mode 100644 design-documents/wallet-screenshots/android-wallet/cta-payment.png delete mode 100644 design-documents/wallet-screenshots/android-wallet/cta-peer-pull-initiate.png delete mode 100644 design-documents/wallet-screenshots/android-wallet/cta-peer-push-initiate.png delete mode 100644 design-documents/wallet-screenshots/android-wallet/cta-url-entry-1.png delete mode 100644 design-documents/wallet-screenshots/android-wallet/cta-url-entry-2.png delete mode 100644 design-documents/wallet-screenshots/android-wallet/cta-wire-transfer-1.png delete mode 100644 design-documents/wallet-screenshots/android-wallet/cta-wire-transfer-2.png delete mode 100644 design-documents/wallet-screenshots/android-wallet/cta-withdraw-1.png delete mode 100644 design-documents/wallet-screenshots/android-wallet/cta-withdraw-2.png delete mode 100644 design-documents/wallet-screenshots/android-wallet/cta-withdraw-done.png create mode 100644 screenshots/balance-list-android-0.png create mode 120000 screenshots/balance-list-android-latest.png create mode 100644 screenshots/balance-list-firefox-0.png create mode 120000 screenshots/balance-list-firefox-latest.png create mode 100644 screenshots/cta-accept-tos-android-0.png create mode 120000 screenshots/cta-accept-tos-android-latest.png create mode 100644 screenshots/cta-deposit-android-0.png create mode 120000 screenshots/cta-deposit-android-latest.png create mode 100644 screenshots/cta-deposit-firefox-0.png create mode 120000 screenshots/cta-deposit-firefox-latest.png create mode 100644 screenshots/cta-payment-android-0.png create mode 120000 screenshots/cta-payment-android-latest.png create mode 100644 screenshots/cta-payment-paid-android-0.png create mode 120000 screenshots/cta-payment-paid-android-latest.png create mode 100644 screenshots/cta-peer-pull-initiate-android-0.png create mode 120000 screenshots/cta-peer-pull-initiate-android-latest.png create mode 100644 screenshots/cta-peer-pull-initiate-firefox-0.png create mode 120000 screenshots/cta-peer-pull-initiate-firefox-latest.png create mode 100644 screenshots/cta-peer-push-initiate-android-0.png create mode 120000 screenshots/cta-peer-push-initiate-android-latest.png create mode 100644 screenshots/cta-peer-push-initiate-firefox-0.png create mode 120000 screenshots/cta-peer-push-initiate-firefox-latest.png create mode 100644 screenshots/cta-url-entry-1-android-0.png create mode 120000 screenshots/cta-url-entry-1-android-latest.png create mode 100644 screenshots/cta-url-entry-2-android-0.png create mode 120000 screenshots/cta-url-entry-2-android-latest.png create mode 100644 screenshots/cta-wire-transfer-1-android-0.png create mode 120000 screenshots/cta-wire-transfer-1-android-latest.png create mode 100644 screenshots/cta-wire-transfer-2-android-0.png create mode 120000 screenshots/cta-wire-transfer-2-android-latest.png create mode 100644 screenshots/cta-withdraw-1-android-0.png create mode 120000 screenshots/cta-withdraw-1-android-latest.png create mode 100644 screenshots/cta-withdraw-2-android-0.png create mode 120000 screenshots/cta-withdraw-2-android-latest.png create mode 100644 screenshots/cta-withdraw-done-android-0.png create mode 120000 screenshots/cta-withdraw-done-android-latest.png create mode 100644 screenshots/cta-withdraw-firefox-1.png create mode 100644 screenshots/transaction-list-android-0.png create mode 120000 screenshots/transaction-list-android-latest.png create mode 100644 screenshots/transaction-list-firefox-0.png create mode 120000 screenshots/transaction-list-firefox-latest.png diff --git a/.gitignore b/.gitignore index b1119077..03767229 100644 --- a/.gitignore +++ b/.gitignore @@ -14,3 +14,4 @@ images/reserve.png texinfo/ !/design-documents/wallet-screenshots/**/*.png +!/screenshots/*.png diff --git a/design-documents/053-wallet-ui.rst b/design-documents/053-wallet-ui.rst index d57dfb53..3a6602e1 100644 --- a/design-documents/053-wallet-ui.rst +++ b/design-documents/053-wallet-ui.rst @@ -40,20 +40,24 @@ Additionaly the document COULD defined the components of the UI. If one of this properties is defined in the spec the implementation must implement it. The specification should be minimal to achieve the objective in the description. -* **Info**: Spec of information that the user should have access. The type of info +* **Info**. Spec of information that the user should have access. The type of info could be a field (id and value) or a banner (information and instructions). The spec will help to reuse the text for i18n across apps and defined -* **Inputs**: Spec of information need to provide in current screen. The type of input, +* **Inputs**. Spec of information need to provide in current screen. The type of input, range of values and validation should be defined if necessary. -* **Actions**: Spec of buttons and interactable elements that will have a significant +* **Actions**. Spec of buttons and interactable elements that will have a significant change in the current state. It should also mention navigation when applicable. -* **Layout**: Spec position of elements when needed. The spec should be "soft" in a sense +* **Layout**. Spec position of elements when needed. The spec should be "soft" in a sense that elements should be easy to find following directions like "close to X" or "at the start/end of the screen". +* **Screenshots**. Should be provided for all wallet implementations and kept + up to date, to ensure that they can be used to aid in UI/UX and QA + discussions. + Screen should be defined using the most relaxed definition that are good enough to be clear for the user. Platform will use this definition and adapt to the differences on the platform taking advantange of platform API and screen sizes. @@ -72,278 +76,543 @@ Proposed Solutions List of all screens with the defined properties. +.. _balance-list-ref: + +balance-list +------------ + +This screen shows a currency-scoped list of the balances stored in the wallet, +and includes information about the total, incoming, and outgoing amounts, as +well as the currency scope information for each item. + +Info +^^^^ + +* List of balances in the wallet, where each item contains: + + * Total amount with currency (see :doc:`051-fractional-digits`). + * Incoming amount (money pending to arrive). + * Outgoing amount (money pending to leave). + * Currency scope information (see :doc:`035-regional-currencies`). + +Actions +^^^^^^^ + +* **View transactions**. Clicking on a balance item should take you to the + transaction list (:ref:`transaction-list-ref`) associated with that balance. + +Screenshots +^^^^^^^^^^^ + ++-----------+----------------------------------------------------------------+ +| Platform | Screenshot | ++===========+================================================================+ +| WebEx | .. image:: ../screenshots/balance-list-firefox-latest.png | ++-----------+----------------------------------------------------------------+ +| Android | .. image:: ../screenshots/balance-list-android-latest.png | +| | :width: 30% | ++-----------+----------------------------------------------------------------+ + + +.. _transaction-list-ref: + +transaction-list +---------------- + +This screen shows a list of all the transactions associated with a given +currency scope. + +Info +^^^^ + +* Total amount and currency (see :doc:`051-fractional-digits`). +* List of transactions associated with the currency scope, with pending + transactions on top, and where each item contains the following: + + * **Title**. It depends on the transaction type. It can be the exchange URL + (e.g. exchange.demo.taler.net), a description of the type of transaction + (e.g. Deposit, Invoice, Payment, etc.), the name of the merchant paid + (e.g. Essay Shop), etc. + * **Summary**. It provides complementary information about the transaction + for the user, such as the status of the transaction (e.g. “Waiting for + confirmation,” “KYC required,” an error message, etc.). (The summary is + provided by wallet-core, along with internationalized versions.) + * **Timestamp**. The moment when the transaction was created. Ideally, it + should be shown with minimal precision, only showing the minutes, hours or + days that have elapsed. + * **Amount**. The positive or negative impact that the transaction has in + the total balance of the currency scope. It should be made clear whether + the amount of the transaction is positive or negative, ideally with a sign + (+/-) and a color (green/red). + * **Pending**. It should be indicated whether the transaction is pending or + finished. This can be done with a small badge and with different colors, + however, it should be always clear and communicate the message + effectively. + +Actions +^^^^^^^ + +* **Send**. The transaction list should include a button that allows the user + to initiate transactions that result in money being sent, such as deposits + and peer push payments. +* **Receive**. The transaction list should also include a button that allows + the user to initiate transactions that result in money being received, such + as withdrawals and peer pull payments. +* **View transaction details**. When clicking on a transaction, the user + should be taken to its corresponding transaction details depending on the + type of the transaction clicked. +* **Select transaction(s)**. The user should be able to select one or more + transactions to perform specific bulk actions, such as deleting. The + interaction that triggers this action might differ across platforms. For + example, in Android this would be achieved by double pressing a transaction + (to activate selection mode) and then clicking other transactions to be + selected. On iOS, this could be achieved using an “Edit” button in the + toolbar that reveals checkboxes that allow the user to select the desired + transactions. +* **Delete transaction(s)**. This could be achieved in bulk via selection + mode, or individually for each transaction via a menu or a button. Either + way, performing a deletion should always show a confirmation menu before + doing the actual deletion. + +Screenshots +^^^^^^^^^^^ + ++-----------+----------------------------------------------------------------+ +| Platform | Screenshot | ++===========+================================================================+ +| WebEx | .. image:: ../screenshots/transaction-list-firefox-latest.png | ++-----------+----------------------------------------------------------------+ +| Android | .. image:: ../screenshots/transaction-list-android-latest.png | +| | :width: 30% | ++-----------+----------------------------------------------------------------+ + + +.. _cta-withdraw-ref: + cta-withdraw ------------ -``Description``: this screen is used for the confirmation of a manual withdrawal, -bank-integrated witdrawals and exchange withdrawals. -the success of this operation will be an increase of the balance in the wallet. -fee, restrictions and ETA should be clear for the user. +This screen is used for the confirmation of a manual withdrawal, +bank-integrated witdrawals and exchange withdrawals. the success of this +operation will be an increase of the balance in the wallet. fee, restrictions +and ETA should be clear for the user. + +Info +^^^^ + +* exchange to be used showing the URL +* table of details of the operation: use the :ref:`operation-table-details-ref` screen +* starting currency: if the exchange has the currency conversion service enabled user should be able to the details based on the wire transfer currency +* taler URI: show copy button or QR to complete the operation with another device -``Info``: - * exchange to be used showing the URL - * table of details of the operation: use the ``operation-table-details`` screen - * starting currency: if the exchange has the currency conversion service enabled user should be able to the details based on the wire transfer currency - * taler URI: show copy button or QR to complete the operation with another device +Inputs +^^^^^^ -``Inputs``: - * age restriction: allow the selection of the restriction in the age group possible by the exchange - * service provider: allow the selection of different exchange +* age restriction: allow the selection of the restriction in the age group possible by the exchange +* service provider: allow the selection of different exchange -``Actions``: - * confirm operation: on success will be redirected to the ``transaction-details`` screen where the detail of the current transaction will be displayed - * review and confirm ToS: if the current selected exchange has a version of ToS that the user didn't yet accepted, use the ``accept-tos`` screen - * cancel: user will be redirected to ``balance`` +Actions +^^^^^^^ + +* **confirm operation**: on success will be redirected to the ``transaction-details`` screen where the detail of the current transaction will be displayed +* **review and confirm ToS**: if the current selected exchange has a version of ToS that the user didn't yet accepted, use the :ref:`accept-tos-ref` screen +* **cancel**: user will be redirected to ``balance`` .. attention:: User should be able to play with the amount, not possible in the current design -.. image:: ./wallet-screenshots/android-wallet/cta-withdraw-2.png - :width: 30% +Screenshots +^^^^^^^^^^^ + ++-----------+----------------------------------------------------------------+ +| Platform | Screenshot | ++===========+================================================================+ +| WebEx | .. image:: ../screenshots/cta-withdraw-firefox-latest.png | ++-----------+----------------------------------------------------------------+ +| Android | .. image:: ../screenshots/cta-withdraw-2-android-latest.png | +| | :width: 30% | ++-----------+----------------------------------------------------------------+ + + +.. _cta-wire-transfer-ref: cta-wire-transfer ----------------- -``Description``: this screen is used to show the user the information for -the wire transfer to complete a manual withdrawal operation. +This screen is used to show the user the information for the wire transfer to +complete a manual withdrawal operation. + +Info +^^^^ -``Info``: - * wire transfer subject to be used (first, most important) - * target bank account to transfer funds to (e.g. IBAN) - * total amount to transfer in the wire transfer currency - * button to copy ``payto://`` URI with the information to clipboard +* wire transfer subject to be used (first, most important) +* target bank account to transfer funds to (e.g. IBAN) +* total amount to transfer in the wire transfer currency +* button to copy ``payto://`` URI with the information to clipboard -``Actions``: - * abort: aborts the withdrawal operation - * menu: go back to the main balances list (operation continues in background) - * automatic: screen changes to "cta-withdraw-done" upon completion +Actions +^^^^^^^ -.. image:: ../screenshots/cta-wire-transfer-firefox-latest.png -.. image:: ./wallet-screenshots/android-wallet/cta-wire-transfer-1.png - :width: 30% -.. image:: ./wallet-screenshots/android-wallet/cta-wire-transfer-2.png - :width: 30% +* **abort**: aborts the withdrawal operation +* **menu**: go back to the main balances list (operation continues in background) +* **automatic**: screen changes to "cta-withdraw-done" upon completion + +Screenshots +^^^^^^^^^^^ + ++-----------+------------------------------------------------------------------+ +| Platform | Screenshot | ++===========+==================================================================+ +| WebEx | .. image:: ../screenshots/cta-wire-transfer-firefox-latest.png | ++-----------+------------------------------------------------------------------+ +| Android | .. image:: ../screenshots/cta-wire-transfer-1-android-latest.png | +| | :width: 30% | +| | .. image:: ../screenshots/cta-wire-transfer-2-android-latest.png | +| | :width: 30% | ++-----------+------------------------------------------------------------------+ + + +.. _cta-withdraw-done-ref: cta-withdraw-done ----------------- -``Description``: this screen is used to show the user the information for -a completed withdraw operation (bank-integrated or manual) +This screen is used to show the user the information for a completed withdraw +operation (bank-integrated or manual) + +Info +^^^^ -``Info``: - * amount wired (hidden if no fees) - * fees paid (hidden if no fees) - * total amount withdrawn into wallet (effective balance change) - * exchange base URL - * date +* amount wired (hidden if no fees) +* fees paid (hidden if no fees) +* total amount withdrawn into wallet (effective balance change) +* exchange base URL +* date -``Actions``: - * delete: deletes information about the withdrawal operation +Actions +^^^^^^^ -.. image:: ../screenshots/cta-withdraw-done-firefox-latest.png - :width: 60% -.. image:: ./wallet-screenshots/android-wallet/cta-withdraw-done.png - :width: 30% +* **delete**: deletes information about the withdrawal operation + +Screenshots +^^^^^^^^^^^ + ++-----------+------------------------------------------------------------------+ +| Platform | Screenshot | ++===========+==================================================================+ +| WebEx | .. image:: ../screenshots/cta-withdraw-done-firefox-latest.png | ++-----------+------------------------------------------------------------------+ +| Android | .. image:: ../screenshots/cta-withdraw-done-android-latest.png | +| | :width: 30% | ++-----------+------------------------------------------------------------------+ + + +.. _cta-url-entry-ref: cta-url-entry ------------- -``Description``: this screen allows the user to scan a QR code, scan an NFC -tag, or enter a taler://-URL. Its implementation may differ significantly -between platforms. For example, scanning NFC tags may be fully automated, -scanning QR codes may involve some system applications, and maybe the dialog -only allows the URL entry *or* the camera but not both at the same time, -depending on implementation specifics. +This screen allows the user to scan a QR code, scan an NFC tag, or enter a +taler://-URL. Its implementation may differ significantly between +platforms. For example, scanning NFC tags may be fully automated, scanning QR +codes may involve some system applications, and maybe the dialog only allows +the URL entry *or* the camera but not both at the same time, depending on +implementation specifics. + +Info +^^^^ -``Info``: - * camera with current image to enable user to focus on QR code - * current URL, with information if it is not well-formed for GNU Taler - * possibly status information on NFC reader (if available) +* camera with current image to enable user to focus on QR code +* current URL, with information if it is not well-formed for GNU Taler +* possibly status information on NFC reader (if available) -``Actions``: - * open: if entered manually, open URL as-entered (otherwise open is automatic) - * back: return to previous view +Actions +^^^^^^^ -.. image:: ../screenshots/cta-url-entry-firefox-latest.png -.. image:: ./wallet-screenshots/android-wallet/cta-url-entry-1.png - :width: 30% -.. image:: ./wallet-screenshots/android-wallet/cta-url-entry-2.png - :width: 30% +* **open**: if entered manually, open URL as-entered (otherwise open is automatic) +* **back**: return to previous view +Screenshots +^^^^^^^^^^^ + ++-----------+------------------------------------------------------------------+ +| Platform | Screenshot | ++===========+==================================================================+ +| WebEx | .. image:: ../screenshots/cta-url-entry-firefox-latest.png | ++-----------+------------------------------------------------------------------+ +| Android | .. image:: ../screenshots/cta-url-entry-1-android-latest.png | +| | :width: 30% | +| | .. image:: ../screenshots/cta-url-entry-2-android-latest.png | +| | :width: 30% | ++-----------+------------------------------------------------------------------+ + + +.. _cta-payment-ref: cta-payment ----------- -``Description``: this screen is used for the confirmation of a payment to a merchant. -the success of this operation will be an decrease of the balance in the wallet -and save a ticket/invoice of the purchase. -fee, restrictions and ETA should be clear for the user. - -``Info``: - * merchant offering the order showing the URL - * order summary - * table of details of the operation: use the ``operation-table-details`` screen - * receipt: order id - * payment deadline: absolute time before the claimed order expires - * taler URI: show copy button or QR to complete the operation with another device - * cant pay desc: if the user has enough balance but unable to use it - * payment status: if the - -``Actions``: - * confirm operation: if the payment is possible, on success will be redirected to the ``transaction-details`` screen where the detail of the current transaction will be displayed - * get more cash: if there is not enough balance, it will be redirected to ``cta-witddraw`` - * cancel: user will be redirected to ``balance`` - -.. image:: ../screenshots/cta-payment-firefox-latest.png - :width: 60% -.. image:: ./wallet-screenshots/android-wallet/cta-payment.png - :width: 30% +This screen is used for the confirmation of a payment to a merchant. the +success of this operation will be an decrease of the balance in the wallet and +save a ticket/invoice of the purchase. fee, restrictions and ETA should be +clear for the user. + +Info +^^^^ + +* merchant offering the order showing the URL +* order summary +* table of details of the operation: use the :ref:`operation-table-details-ref` screen +* receipt: order id +* payment deadline: absolute time before the claimed order expires +* taler URI: show copy button or QR to complete the operation with another device +* cant pay desc: if the user has enough balance but unable to use it +* payment status: if the + +Actions +^^^^^^^ + +* **confirm operation**: if the payment is possible, on success will be redirected to the ``transaction-details`` screen where the detail of the current transaction will be displayed +* **get more cash**: if there is not enough balance, it will be redirected to :ref:`cta-withdraw-ref` +* **cancel**: user will be redirected to ``balance`` + +Screenshots +^^^^^^^^^^^ + ++-----------+------------------------------------------------------------------+ +| Platform | Screenshot | ++===========+==================================================================+ +| WebEx | .. image:: ../screenshots/cta-payment-firefox-latest.png | ++-----------+------------------------------------------------------------------+ +| Android | .. image:: ../screenshots/cta-payment-android-latest.png | +| | :width: 30% | ++-----------+------------------------------------------------------------------+ + + +.. _cta-payment-paid-ref: cta-payment-paid ---------------- -``Description``: this screen is used to show information with details -about a historic payment. +This screen is used to show information with details about a historic payment. + +Info +^^^^ + +* merchant offering the order showing the URL +* order summary +* table of details of the operation: use the :ref:`operation-table-details-ref` screen +* receipt: order id +* payment status: if the order was refunded + +Actions +^^^^^^^ -``Info``: - * merchant offering the order showing the URL - * order summary - * table of details of the operation: use the ``operation-table-details`` screen - * receipt: order id - * payment status: if the order was refunded +* **delete**: delete information about the transaction +* **back**: user will be redirected to ``balance`` -``Actions``: - * delete: delete information about the transaction - * back: user will be redirected to ``balance`` +Screenshots +^^^^^^^^^^^ -.. image:: ../screenshots/cta-payment-paid-firefox-latest.png - :width: 60% -.. image:: ./wallet-screenshots/android-wallet/cta-payment-paid.png - :width: 30% ++-----------+------------------------------------------------------------------+ +| Platform | Screenshot | ++===========+==================================================================+ +| WebEx | .. image:: ../screenshots/cta-payment-paid-firefox-latest.png | ++-----------+------------------------------------------------------------------+ +| Android | .. image:: ../screenshots/cta-payment-paid-android-latest.png | +| | :width: 30% | ++-----------+------------------------------------------------------------------+ + + +.. _cta-deposit-ref: cta-deposit ------------ -``Description``: this screen is used for the confirmation of a deposit. -the success of this operation will be an decrease of the balance in the wallet -and save a deposit ticket for reference. -fee, restrictions and ETA should be clear for the user. +This screen is used for the confirmation of a deposit. the success of this +operation will be an decrease of the balance in the wallet and save a deposit +ticket for reference. fee, restrictions and ETA should be clear for the user. + +Info +^^^^ -``Info``: - * bank account where the money is going to - * table of details of the operation: use the ``operation-table-details`` screen +* bank account where the money is going to +* table of details of the operation: use the :ref:`operation-table-details-ref` screen -``Actions``: - * confirm operation: on success will be redirected to the ``transaction-details`` screen where the detail of the current transaction will be displayed - * cancel: user will be redirected to ``balance`` +Actions +^^^^^^^ + +* **confirm operation**: on success will be redirected to the ``transaction-details`` screen where the detail of the current transaction will be displayed +* **cancel**: user will be redirected to ``balance`` .. attention:: User should be able to play with the amount, not possible in the current design -.. image:: ./wallet-screenshots/android-wallet/cta-deposit.png - :width: 30% +Screenshots +^^^^^^^^^^^ + ++-----------+------------------------------------------------------------------+ +| Platform | Screenshot | ++===========+==================================================================+ +| WebEx | .. image:: ../screenshots/cta-deposit-firefox-latest.png | ++-----------+------------------------------------------------------------------+ +| Android | .. image:: ../screenshots/cta-deposit-android-latest.png | +| | :width: 30% | ++-----------+------------------------------------------------------------------+ + + +.. _cta-peer-pull-initiate-ref: cta-peer-pull-initiate ---------------------- -``Description``: this screen is used for the confirmation of the creation of -a peer pull transaction or invoice to request money from another wallet. -the success of this operation will not change the balance immediately in the wallet -and allow the user to share a taler URI to the payer. -fee, restrictions and ETA should be clear for the user. +This screen is used for the confirmation of the creation of a peer pull +transaction or invoice to request money from another wallet. the success of +this operation will not change the balance immediately in the wallet and allow +the user to share a taler URI to the payer. fee, restrictions and ETA should +be clear for the user. + +Info +^^^^ + +* exchange to be used showing the URL +* table of details of the operation: use the :ref:`operation-table-details-ref` screen -``Info``: - * exchange to be used showing the URL - * table of details of the operation: use the ``operation-table-details`` screen +Inputs +^^^^^^ -``Inputs``: - * subject: short description of the transaction - * expiration: absolute time/date after which the invoice is not valid anymore - * service provider: allow the selection of different exchange +* **subject**: short description of the transaction +* **expiration**: absolute time/date after which the invoice is not valid anymore +* **service provider**: allow the selection of different exchange -``Actions``: - * confirm operation: on success will be redirected to the ``transaction-details`` screen where the detail of the current transaction will be displayed - * review and confirm ToS: if the current selected exchange has a version of ToS that the user didn't yet accepted, use the ``accept-tos`` screen - * cancel: user will be redirected to ``balance`` +Actions +^^^^^^^ + +* **confirm operation**: on success will be redirected to the ``transaction-details`` screen where the detail of the current transaction will be displayed +* **review and confirm ToS**: if the current selected exchange has a version of ToS that the user didn't yet accepted, use the :ref:`accept-tos-ref` screen +* *cancel*: user will be redirected to ``balance`` .. attention:: Is the invoice creation always free of charge or does the exchange have a mechanism to impose a fee to pay on creation? -.. image:: ./wallet-screenshots/android-wallet/cta-peer-pull-initiate.png - :width: 30% +Screenshots +^^^^^^^^^^^ + ++-----------+----------------------------------------------------------------------+ +| Platform | Screenshot | ++===========+======================================================================+ +| WebEx | .. image:: ../screenshots/cta-peer-pull-initiate-firefox-latest.png | ++-----------+----------------------------------------------------------------------+ +| Android | .. image:: ../screenshots/cta-peer-pull-initiate-android-latest.png | +| | :width: 30% | ++-----------+----------------------------------------------------------------------+ + + +.. _cta-peer-pull-confirm-ref: cta-peer-pull-confirm --------------------- -``Description``: this screen is used for the confirmation of the payment of -a peer pull transaction or invoice to send money from another wallet. -the success of this operation will be an will decrease the balance in the wallet. -fee, restrictions and ETA should be clear for the user. +This screen is used for the confirmation of the payment of a peer pull +transaction or invoice to send money from another wallet. the success of this +operation will be an will decrease the balance in the wallet. fee, +restrictions and ETA should be clear for the user. + +Info +^^^^ -``Info``: - * exchange to be used showing the URL - * subject: short description of the transaction - * table of details of the operation: use the ``operation-table-details`` screen - * expiration: absolute time/date after which the invoice is not valid anymore +* exchange to be used showing the URL +* subject: short description of the transaction +* table of details of the operation: use the :ref:`operation-table-details-ref` screen +* expiration: absolute time/date after which the invoice is not valid anymore -``Actions``: - * confirm operation: if the payment is possible, on success will be redirected to the ``transaction-details`` screen where the detail of the current transaction will be displayed - * get more cash: if there is not enough balance, it will be redirected to ``cta-witddraw`` - * cancel: user will be redirected to ``balance`` +Actions +^^^^^^^ + +* **confirm operation**: if the payment is possible, on success will be redirected to the ``transaction-details`` screen where the detail of the current transaction will be displayed +* **get more cash**: if there is not enough balance, it will be redirected to :ref:`cta-withdraw-ref` +* **cancel**: user will be redirected to ``balance`` cta-peer-push-initiate ---------------------- -``Description``: this screen is used for the confirmation of the creation of -a peer push transaction or transfer money to another wallet. -the success of this operation will reduce the balance immediately in the wallet -and allow the user to share a taler URI to the receiver. -fee, restrictions and ETA should be clear for the user. +This screen is used for the confirmation of the creation of a peer push +transaction or transfer money to another wallet. the success of this +operation will reduce the balance immediately in the wallet and allow the user +to share a taler URI to the receiver. fee, restrictions and ETA should be +clear for the user. + +Info +^^^^ + +* table of details of the operation: use the ``operation-table-details`` screen + +Inputs +^^^^^^ + +* **subject**: short description of the transaction +* **expiration**: absolute time/date after which the transfer is not valid anymore -``Info``: - * table of details of the operation: use the ``operation-table-details`` screen +Actions +^^^^^^^ -``Inputs``: - * subject: short description of the transaction - * expiration: absolute time/date after which the transfer is not valid anymore +* **confirm operation**: on success will be redirected to the ``transaction-details`` screen where the detail of the current transaction will be displayed +* **cancel**: user will be redirected to ``balance`` -``Actions``: - * confirm operation: on success will be redirected to the ``transaction-details`` screen where the detail of the current transaction will be displayed - * cancel: user will be redirected to ``balance`` +Screenshots +^^^^^^^^^^^ -.. image:: ./wallet-screenshots/android-wallet/cta-peer-push-initiate.png - :width: 30% ++-----------+----------------------------------------------------------------------+ +| Platform | Screenshot | ++===========+======================================================================+ +| WebEx | .. image:: ../screenshots/cta-peer-push-initiate-firefox-latest.png | ++-----------+----------------------------------------------------------------------+ +| Android | .. image:: ../screenshots/cta-peer-push-initiate-android-latest.png | +| | :width: 30% | ++-----------+----------------------------------------------------------------------+ + + +.. _cta-peer-push-confirm-ref: cta-peer-push-confirm --------------------- -``Description``: this screen is used for the confirmation of the acceptance of -a peer push transaction or transfer money to this wallet. -the success of this operation will be an will decrease the balance in the wallet. -fee, restrictions and ETA should be clear for the user. +This screen is used for the confirmation of the acceptance of a peer push +transaction or transfer money to this wallet. the success of this operation +will be an will decrease the balance in the wallet. fee, restrictions and ETA +should be clear for the user. + +Info +^^^^ -``Info``: - * subject: short description of the payment - * expiration: absolute time/date after which the invoice is not valid anymore - * table of details of the operation: use the ``operation-table-details`` screen +* subject: short description of the payment +* expiration: absolute time/date after which the invoice is not valid anymore +* table of details of the operation: use the ``operation-table-details`` screen -``Actions``: - * confirm operation: on success will be redirected to the ``transaction-details`` screen where the detail of the current transaction will be displayed - * review and confirm ToS: if the current selected exchange has a version of ToS that the user didn't yet accepted, use the ``accept-tos`` screen - * cancel: user will be redirected to ``balance`` +Actions +^^^^^^^ +* **confirm operation**: on success will be redirected to the ``transaction-details`` screen where the detail of the current transaction will be displayed +* **review and confirm ToS**: if the current selected exchange has a version of ToS that the user didn't yet accepted, use the :ref:`accept-tos-ref` screen +* **cancel**: user will be redirected to ``balance`` + +.. _operation-table-details-ref: operation-table-details ----------------------- -``Description``: with the table it should be clear how much the operation will cost, -the initial amount and the final amount with all the items related to the operations (like fee) +With the table it should be clear how much the operation will cost, the +initial amount and the final amount with all the items related to the +operations (like fee) + +Labels +^^^^^^ -``labels``: initial amount of the operation, and final amount are always shown. -Fee should be shown as an extra row in the table if it is non-zero. -Converted amount should be shown as an extra row if initial amount currency is not the same -as the final amount currency. +Initial amount of the operation, and final amount are always shown. Fee should +be shown as an extra row in the table if it is non-zero. Converted amount +should be shown as an extra row if initial amount currency is not the same as +the final amount currency. Initial amount label by operation: @@ -357,27 +626,41 @@ Initial amount label by operation: * refund -> Refund +.. _accept-tos-ref: + accept-tos ---------- -``Description``: this screen can be use everytime that the user is going to interact -with an exchange. since at any moment wallet may find that ToS changed the user needs -to be prevented from continue before reading/accepting new rules. If possible, this -screen should be used inplace of other actions and hidden if not required (for example, -user already accepted ToS) +This screen can be use everytime that the user is going to interact with an +exchange. since at any moment wallet may find that ToS changed the user needs +to be prevented from continue before reading/accepting new rules. If possible, +this screen should be used inplace of other actions and hidden if not required +(for example, user already accepted ToS) + +Inputs +^^^^^^ + +* **format**: allow the selection of a ToS format +* **languange**: allow the selection of a languange different from system lang + +Actions +^^^^^^^ -``Inputs``: - * format: allow the selection of a ToS format - * languange: allow the selection of a languange different from system lang +* **accept tos**: will mark this version as accepted in wallet core and redirect the user to the screen from where it was invoked +* **save/print tos**: will save the ToS outside of the wallet -``Actions``: - * accept tos: will mark this version as accepted in wallet core and redirect the user to the screen from where it was invoked - * save/print tos: will save the ToS outside of the wallet +Screenshots +^^^^^^^^^^^ -.. image:: ../screenshots/cta-accept-tos-firefox-latest.png - :width: 45% -.. image:: ./wallet-screenshots/android-wallet/accept-tos.png - :width: 45% ++-----------+------------------------------------------------------------------+ +| Platform | Screenshot | ++===========+==================================================================+ +| WebEx | .. image:: ../screenshots/cta-accept-tos-firefox-latest.png | +| | :width: 30% | ++-----------+------------------------------------------------------------------+ +| Android | .. image:: ../screenshots/cta-accept-tos-android-latest.png | +| | :width: 30% | ++-----------+------------------------------------------------------------------+ Q / A ===== diff --git a/design-documents/wallet-screenshots/android-wallet/accept-tos.png b/design-documents/wallet-screenshots/android-wallet/accept-tos.png deleted file mode 100644 index c9537071..00000000 Binary files a/design-documents/wallet-screenshots/android-wallet/accept-tos.png and /dev/null differ diff --git a/design-documents/wallet-screenshots/android-wallet/cta-deposit.png b/design-documents/wallet-screenshots/android-wallet/cta-deposit.png deleted file mode 100644 index 74435360..00000000 Binary files a/design-documents/wallet-screenshots/android-wallet/cta-deposit.png and /dev/null differ diff --git a/design-documents/wallet-screenshots/android-wallet/cta-payment-paid.png b/design-documents/wallet-screenshots/android-wallet/cta-payment-paid.png deleted file mode 100644 index 51a412c7..00000000 Binary files a/design-documents/wallet-screenshots/android-wallet/cta-payment-paid.png and /dev/null differ diff --git a/design-documents/wallet-screenshots/android-wallet/cta-payment.png b/design-documents/wallet-screenshots/android-wallet/cta-payment.png deleted file mode 100644 index d518c922..00000000 Binary files a/design-documents/wallet-screenshots/android-wallet/cta-payment.png and /dev/null differ diff --git a/design-documents/wallet-screenshots/android-wallet/cta-peer-pull-initiate.png b/design-documents/wallet-screenshots/android-wallet/cta-peer-pull-initiate.png deleted file mode 100644 index 9be8abdf..00000000 Binary files a/design-documents/wallet-screenshots/android-wallet/cta-peer-pull-initiate.png and /dev/null differ diff --git a/design-documents/wallet-screenshots/android-wallet/cta-peer-push-initiate.png b/design-documents/wallet-screenshots/android-wallet/cta-peer-push-initiate.png deleted file mode 100644 index 8ee0ef7d..00000000 Binary files a/design-documents/wallet-screenshots/android-wallet/cta-peer-push-initiate.png and /dev/null differ diff --git a/design-documents/wallet-screenshots/android-wallet/cta-url-entry-1.png b/design-documents/wallet-screenshots/android-wallet/cta-url-entry-1.png deleted file mode 100644 index 0705e7f0..00000000 Binary files a/design-documents/wallet-screenshots/android-wallet/cta-url-entry-1.png and /dev/null differ diff --git a/design-documents/wallet-screenshots/android-wallet/cta-url-entry-2.png b/design-documents/wallet-screenshots/android-wallet/cta-url-entry-2.png deleted file mode 100644 index 18ed9bdf..00000000 Binary files a/design-documents/wallet-screenshots/android-wallet/cta-url-entry-2.png and /dev/null differ diff --git a/design-documents/wallet-screenshots/android-wallet/cta-wire-transfer-1.png b/design-documents/wallet-screenshots/android-wallet/cta-wire-transfer-1.png deleted file mode 100644 index 71e354f6..00000000 Binary files a/design-documents/wallet-screenshots/android-wallet/cta-wire-transfer-1.png and /dev/null differ diff --git a/design-documents/wallet-screenshots/android-wallet/cta-wire-transfer-2.png b/design-documents/wallet-screenshots/android-wallet/cta-wire-transfer-2.png deleted file mode 100644 index 719b890c..00000000 Binary files a/design-documents/wallet-screenshots/android-wallet/cta-wire-transfer-2.png and /dev/null differ diff --git a/design-documents/wallet-screenshots/android-wallet/cta-withdraw-1.png b/design-documents/wallet-screenshots/android-wallet/cta-withdraw-1.png deleted file mode 100644 index 3da47302..00000000 Binary files a/design-documents/wallet-screenshots/android-wallet/cta-withdraw-1.png and /dev/null differ diff --git a/design-documents/wallet-screenshots/android-wallet/cta-withdraw-2.png b/design-documents/wallet-screenshots/android-wallet/cta-withdraw-2.png deleted file mode 100644 index dbe4c7b1..00000000 Binary files a/design-documents/wallet-screenshots/android-wallet/cta-withdraw-2.png and /dev/null differ diff --git a/design-documents/wallet-screenshots/android-wallet/cta-withdraw-done.png b/design-documents/wallet-screenshots/android-wallet/cta-withdraw-done.png deleted file mode 100644 index 5860f280..00000000 Binary files a/design-documents/wallet-screenshots/android-wallet/cta-withdraw-done.png and /dev/null differ diff --git a/screenshots/balance-list-android-0.png b/screenshots/balance-list-android-0.png new file mode 100644 index 00000000..f87919f8 Binary files /dev/null and b/screenshots/balance-list-android-0.png differ diff --git a/screenshots/balance-list-android-latest.png b/screenshots/balance-list-android-latest.png new file mode 120000 index 00000000..0af04e4b --- /dev/null +++ b/screenshots/balance-list-android-latest.png @@ -0,0 +1 @@ +balance-list-android-0.png \ No newline at end of file diff --git a/screenshots/balance-list-firefox-0.png b/screenshots/balance-list-firefox-0.png new file mode 100644 index 00000000..6a4fcb12 Binary files /dev/null and b/screenshots/balance-list-firefox-0.png differ diff --git a/screenshots/balance-list-firefox-latest.png b/screenshots/balance-list-firefox-latest.png new file mode 120000 index 00000000..390d4b60 --- /dev/null +++ b/screenshots/balance-list-firefox-latest.png @@ -0,0 +1 @@ +balance-list-firefox-0.png \ No newline at end of file diff --git a/screenshots/cta-accept-tos-android-0.png b/screenshots/cta-accept-tos-android-0.png new file mode 100644 index 00000000..c9537071 Binary files /dev/null and b/screenshots/cta-accept-tos-android-0.png differ diff --git a/screenshots/cta-accept-tos-android-latest.png b/screenshots/cta-accept-tos-android-latest.png new file mode 120000 index 00000000..89544b02 --- /dev/null +++ b/screenshots/cta-accept-tos-android-latest.png @@ -0,0 +1 @@ +cta-accept-tos-android-0.png \ No newline at end of file diff --git a/screenshots/cta-deposit-android-0.png b/screenshots/cta-deposit-android-0.png new file mode 100644 index 00000000..74435360 Binary files /dev/null and b/screenshots/cta-deposit-android-0.png differ diff --git a/screenshots/cta-deposit-android-latest.png b/screenshots/cta-deposit-android-latest.png new file mode 120000 index 00000000..53a323c3 --- /dev/null +++ b/screenshots/cta-deposit-android-latest.png @@ -0,0 +1 @@ +cta-deposit-android-0.png \ No newline at end of file diff --git a/screenshots/cta-deposit-firefox-0.png b/screenshots/cta-deposit-firefox-0.png new file mode 100644 index 00000000..e78538c7 Binary files /dev/null and b/screenshots/cta-deposit-firefox-0.png differ diff --git a/screenshots/cta-deposit-firefox-latest.png b/screenshots/cta-deposit-firefox-latest.png new file mode 120000 index 00000000..93e5beca --- /dev/null +++ b/screenshots/cta-deposit-firefox-latest.png @@ -0,0 +1 @@ +cta-deposit-firefox-0.png \ No newline at end of file diff --git a/screenshots/cta-payment-android-0.png b/screenshots/cta-payment-android-0.png new file mode 100644 index 00000000..d518c922 Binary files /dev/null and b/screenshots/cta-payment-android-0.png differ diff --git a/screenshots/cta-payment-android-latest.png b/screenshots/cta-payment-android-latest.png new file mode 120000 index 00000000..b858e45f --- /dev/null +++ b/screenshots/cta-payment-android-latest.png @@ -0,0 +1 @@ +cta-payment-android-0.png \ No newline at end of file diff --git a/screenshots/cta-payment-paid-android-0.png b/screenshots/cta-payment-paid-android-0.png new file mode 100644 index 00000000..51a412c7 Binary files /dev/null and b/screenshots/cta-payment-paid-android-0.png differ diff --git a/screenshots/cta-payment-paid-android-latest.png b/screenshots/cta-payment-paid-android-latest.png new file mode 120000 index 00000000..8aabd17e --- /dev/null +++ b/screenshots/cta-payment-paid-android-latest.png @@ -0,0 +1 @@ +cta-payment-paid-android-0.png \ No newline at end of file diff --git a/screenshots/cta-peer-pull-initiate-android-0.png b/screenshots/cta-peer-pull-initiate-android-0.png new file mode 100644 index 00000000..9be8abdf Binary files /dev/null and b/screenshots/cta-peer-pull-initiate-android-0.png differ diff --git a/screenshots/cta-peer-pull-initiate-android-latest.png b/screenshots/cta-peer-pull-initiate-android-latest.png new file mode 120000 index 00000000..eeb4d8c9 --- /dev/null +++ b/screenshots/cta-peer-pull-initiate-android-latest.png @@ -0,0 +1 @@ +cta-peer-pull-initiate-android-0.png \ No newline at end of file diff --git a/screenshots/cta-peer-pull-initiate-firefox-0.png b/screenshots/cta-peer-pull-initiate-firefox-0.png new file mode 100644 index 00000000..0d7c1b31 Binary files /dev/null and b/screenshots/cta-peer-pull-initiate-firefox-0.png differ diff --git a/screenshots/cta-peer-pull-initiate-firefox-latest.png b/screenshots/cta-peer-pull-initiate-firefox-latest.png new file mode 120000 index 00000000..74339ee9 --- /dev/null +++ b/screenshots/cta-peer-pull-initiate-firefox-latest.png @@ -0,0 +1 @@ +cta-peer-pull-initiate-firefox-0.png \ No newline at end of file diff --git a/screenshots/cta-peer-push-initiate-android-0.png b/screenshots/cta-peer-push-initiate-android-0.png new file mode 100644 index 00000000..8ee0ef7d Binary files /dev/null and b/screenshots/cta-peer-push-initiate-android-0.png differ diff --git a/screenshots/cta-peer-push-initiate-android-latest.png b/screenshots/cta-peer-push-initiate-android-latest.png new file mode 120000 index 00000000..ee8bd57a --- /dev/null +++ b/screenshots/cta-peer-push-initiate-android-latest.png @@ -0,0 +1 @@ +cta-peer-push-initiate-android-0.png \ No newline at end of file diff --git a/screenshots/cta-peer-push-initiate-firefox-0.png b/screenshots/cta-peer-push-initiate-firefox-0.png new file mode 100644 index 00000000..f566b0cb Binary files /dev/null and b/screenshots/cta-peer-push-initiate-firefox-0.png differ diff --git a/screenshots/cta-peer-push-initiate-firefox-latest.png b/screenshots/cta-peer-push-initiate-firefox-latest.png new file mode 120000 index 00000000..98a59294 --- /dev/null +++ b/screenshots/cta-peer-push-initiate-firefox-latest.png @@ -0,0 +1 @@ +cta-peer-push-initiate-firefox-0.png \ No newline at end of file diff --git a/screenshots/cta-url-entry-1-android-0.png b/screenshots/cta-url-entry-1-android-0.png new file mode 100644 index 00000000..0705e7f0 Binary files /dev/null and b/screenshots/cta-url-entry-1-android-0.png differ diff --git a/screenshots/cta-url-entry-1-android-latest.png b/screenshots/cta-url-entry-1-android-latest.png new file mode 120000 index 00000000..3ff5ec48 --- /dev/null +++ b/screenshots/cta-url-entry-1-android-latest.png @@ -0,0 +1 @@ +cta-url-entry-1-android-0.png \ No newline at end of file diff --git a/screenshots/cta-url-entry-2-android-0.png b/screenshots/cta-url-entry-2-android-0.png new file mode 100644 index 00000000..18ed9bdf Binary files /dev/null and b/screenshots/cta-url-entry-2-android-0.png differ diff --git a/screenshots/cta-url-entry-2-android-latest.png b/screenshots/cta-url-entry-2-android-latest.png new file mode 120000 index 00000000..c589b4c9 --- /dev/null +++ b/screenshots/cta-url-entry-2-android-latest.png @@ -0,0 +1 @@ +cta-url-entry-2-android-0.png \ No newline at end of file diff --git a/screenshots/cta-wire-transfer-1-android-0.png b/screenshots/cta-wire-transfer-1-android-0.png new file mode 100644 index 00000000..71e354f6 Binary files /dev/null and b/screenshots/cta-wire-transfer-1-android-0.png differ diff --git a/screenshots/cta-wire-transfer-1-android-latest.png b/screenshots/cta-wire-transfer-1-android-latest.png new file mode 120000 index 00000000..ec0bf1b0 --- /dev/null +++ b/screenshots/cta-wire-transfer-1-android-latest.png @@ -0,0 +1 @@ +cta-wire-transfer-1-android-0.png \ No newline at end of file diff --git a/screenshots/cta-wire-transfer-2-android-0.png b/screenshots/cta-wire-transfer-2-android-0.png new file mode 100644 index 00000000..719b890c Binary files /dev/null and b/screenshots/cta-wire-transfer-2-android-0.png differ diff --git a/screenshots/cta-wire-transfer-2-android-latest.png b/screenshots/cta-wire-transfer-2-android-latest.png new file mode 120000 index 00000000..cb712f15 --- /dev/null +++ b/screenshots/cta-wire-transfer-2-android-latest.png @@ -0,0 +1 @@ +cta-wire-transfer-2-android-0.png \ No newline at end of file diff --git a/screenshots/cta-withdraw-1-android-0.png b/screenshots/cta-withdraw-1-android-0.png new file mode 100644 index 00000000..3da47302 Binary files /dev/null and b/screenshots/cta-withdraw-1-android-0.png differ diff --git a/screenshots/cta-withdraw-1-android-latest.png b/screenshots/cta-withdraw-1-android-latest.png new file mode 120000 index 00000000..a183a53f --- /dev/null +++ b/screenshots/cta-withdraw-1-android-latest.png @@ -0,0 +1 @@ +cta-withdraw-1-android-0.png \ No newline at end of file diff --git a/screenshots/cta-withdraw-2-android-0.png b/screenshots/cta-withdraw-2-android-0.png new file mode 100644 index 00000000..dbe4c7b1 Binary files /dev/null and b/screenshots/cta-withdraw-2-android-0.png differ diff --git a/screenshots/cta-withdraw-2-android-latest.png b/screenshots/cta-withdraw-2-android-latest.png new file mode 120000 index 00000000..6ca7417d --- /dev/null +++ b/screenshots/cta-withdraw-2-android-latest.png @@ -0,0 +1 @@ +cta-withdraw-2-android-0.png \ No newline at end of file diff --git a/screenshots/cta-withdraw-done-android-0.png b/screenshots/cta-withdraw-done-android-0.png new file mode 100644 index 00000000..5860f280 Binary files /dev/null and b/screenshots/cta-withdraw-done-android-0.png differ diff --git a/screenshots/cta-withdraw-done-android-latest.png b/screenshots/cta-withdraw-done-android-latest.png new file mode 120000 index 00000000..7751f9d0 --- /dev/null +++ b/screenshots/cta-withdraw-done-android-latest.png @@ -0,0 +1 @@ +cta-withdraw-done-android-0.png \ No newline at end of file diff --git a/screenshots/cta-withdraw-firefox-1.png b/screenshots/cta-withdraw-firefox-1.png new file mode 100644 index 00000000..61d3c0a4 Binary files /dev/null and b/screenshots/cta-withdraw-firefox-1.png differ diff --git a/screenshots/cta-withdraw-firefox-latest.png b/screenshots/cta-withdraw-firefox-latest.png index 4ed704c3..189b3525 120000 --- a/screenshots/cta-withdraw-firefox-latest.png +++ b/screenshots/cta-withdraw-firefox-latest.png @@ -1 +1 @@ -cta-withdraw-firefox-0.png \ No newline at end of file +cta-withdraw-firefox-1.png \ No newline at end of file diff --git a/screenshots/transaction-list-android-0.png b/screenshots/transaction-list-android-0.png new file mode 100644 index 00000000..e9309a83 Binary files /dev/null and b/screenshots/transaction-list-android-0.png differ diff --git a/screenshots/transaction-list-android-latest.png b/screenshots/transaction-list-android-latest.png new file mode 120000 index 00000000..d6123a74 --- /dev/null +++ b/screenshots/transaction-list-android-latest.png @@ -0,0 +1 @@ +transaction-list-android-0.png \ No newline at end of file diff --git a/screenshots/transaction-list-firefox-0.png b/screenshots/transaction-list-firefox-0.png new file mode 100644 index 00000000..d2d12ca8 Binary files /dev/null and b/screenshots/transaction-list-firefox-0.png differ diff --git a/screenshots/transaction-list-firefox-latest.png b/screenshots/transaction-list-firefox-latest.png new file mode 120000 index 00000000..463f0be8 --- /dev/null +++ b/screenshots/transaction-list-firefox-latest.png @@ -0,0 +1 @@ +transaction-list-firefox-0.png \ No newline at end of file -- cgit v1.2.3 From 0df099d459060e09dd710cda2d144dd7370c2a3f Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Thu, 7 Mar 2024 22:22:01 +0100 Subject: -update regional architecture image --- images/regional-arch.png | Bin 0 -> 126574 bytes 1 file changed, 0 insertions(+), 0 deletions(-) create mode 100644 images/regional-arch.png diff --git a/images/regional-arch.png b/images/regional-arch.png new file mode 100644 index 00000000..952b7e60 Binary files /dev/null and b/images/regional-arch.png differ -- cgit v1.2.3 From 57f68dee4cdb383f575ea6ab06c6ab05ad7dc7ab Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Fri, 8 Mar 2024 10:39:47 +0100 Subject: add -a option for taler-exchange-dbinit --- manpages/taler-exchange-dbinit.1.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/manpages/taler-exchange-dbinit.1.rst b/manpages/taler-exchange-dbinit.1.rst index 0ee83543..cbbc494c 100644 --- a/manpages/taler-exchange-dbinit.1.rst +++ b/manpages/taler-exchange-dbinit.1.rst @@ -13,6 +13,7 @@ Synopsis ======== **taler-exchange-dbinit** +[**-a** | **--inject-auditor**] [**-c** *FILENAME* | **--config=**\ ‌\ *FILENAME*] [**-g** | **--gc**] [**-h** | **--help**] @@ -31,6 +32,9 @@ Taler exchange to operate. Its options are as follows: +**-a** \| **--inject-auditor** + Installs triggers to notify real-time auditors of relevant changes to the database state. + **-c** *FILENAME* \| **--config=**\ ‌\ *FILENAME* Use the configuration and other resources for the exchange to operate from *FILENAME*. -- cgit v1.2.3 From 705921a7f857a9caa77061bbf0f05f0515569b4f Mon Sep 17 00:00:00 2001 From: Florian Dold Date: Fri, 8 Mar 2024 13:44:37 +0100 Subject: regio: be more explicit --- libeufin/regional-automated-manual.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/libeufin/regional-automated-manual.rst b/libeufin/regional-automated-manual.rst index 4fe492ab..b199aa92 100644 --- a/libeufin/regional-automated-manual.rst +++ b/libeufin/regional-automated-manual.rst @@ -234,7 +234,9 @@ By default, the exchange is setup to perform conversion without any restrictions .. code-block:: console - $ . config/user.conf + # Make sure environment variables are available + $ source config/user.conf + $ sudo -u taler-exchange-offline taler-exchange-offline \ enable-account \ "${CONVERSION_PAYTO}" \ -- cgit v1.2.3 From b6c48cab4cce1f8105b0280ab06f82267fee4c1c Mon Sep 17 00:00:00 2001 From: Iván Ávalos Date: Fri, 8 Mar 2024 10:20:14 -0600 Subject: DD53: add iOS screenshots --- design-documents/053-wallet-ui.rst | 44 ++++++++++++++++++++++ screenshots/balance-list-1-ios-0.png | Bin 0 -> 395744 bytes screenshots/balance-list-1-ios-latest.png | 1 + screenshots/balance-list-2-ios-0.png | Bin 0 -> 427641 bytes screenshots/balance-list-2-ios-latest.png | 1 + screenshots/cta-accept-tos-ios-0.png | Bin 0 -> 334259 bytes screenshots/cta-accept-tos-ios-latest.png | 1 + screenshots/cta-deposit-1-ios-0.png | Bin 0 -> 155427 bytes screenshots/cta-deposit-1-ios-latest.png | 1 + screenshots/cta-deposit-2-ios-0.png | Bin 0 -> 174391 bytes screenshots/cta-deposit-2-ios-latest.png | 1 + screenshots/cta-payment-ios-0.png | Bin 0 -> 198398 bytes screenshots/cta-payment-ios-latest.png | 1 + screenshots/cta-payment-paid-1-ios-0.png | Bin 0 -> 197183 bytes screenshots/cta-payment-paid-1-ios-latest.png | 1 + screenshots/cta-payment-paid-2-ios-0.png | Bin 0 -> 294874 bytes screenshots/cta-payment-paid-2-ios-latest.png | 1 + screenshots/cta-peer-pull-initiate-ios-0.png | Bin 0 -> 186311 bytes screenshots/cta-peer-pull-initiate-ios-latest.png | 1 + screenshots/cta-peer-push-initiate-ios-0.png | Bin 0 -> 176120 bytes screenshots/cta-peer-push-initiate-ios-latest.png | 1 + screenshots/cta-wire-transfer-1-ios-0.png | Bin 0 -> 292949 bytes screenshots/cta-wire-transfer-1-ios-latest.png | 1 + screenshots/cta-wire-transfer-2-ios-0.png | Bin 0 -> 407510 bytes screenshots/cta-wire-transfer-2-ios-latest.png | 1 + screenshots/cta-wire-transfer-3-ios-0.png | Bin 0 -> 331196 bytes screenshots/cta-wire-transfer-3-ios-latest.png | 1 + screenshots/cta-withdraw-done-ios-0.png | Bin 0 -> 310883 bytes screenshots/cta-withdraw-done-ios-latest.png | 1 + screenshots/cta-withdraw-ios-0.png | Bin 0 -> 193455 bytes screenshots/cta-withdraw-ios-latest.png | 1 + screenshots/transaction-list-ios-0.png | Bin 0 -> 474321 bytes screenshots/transaction-list-ios-latest.png | 1 + 33 files changed, 60 insertions(+) create mode 100644 screenshots/balance-list-1-ios-0.png create mode 120000 screenshots/balance-list-1-ios-latest.png create mode 100644 screenshots/balance-list-2-ios-0.png create mode 120000 screenshots/balance-list-2-ios-latest.png create mode 100644 screenshots/cta-accept-tos-ios-0.png create mode 120000 screenshots/cta-accept-tos-ios-latest.png create mode 100644 screenshots/cta-deposit-1-ios-0.png create mode 120000 screenshots/cta-deposit-1-ios-latest.png create mode 100644 screenshots/cta-deposit-2-ios-0.png create mode 120000 screenshots/cta-deposit-2-ios-latest.png create mode 100644 screenshots/cta-payment-ios-0.png create mode 120000 screenshots/cta-payment-ios-latest.png create mode 100644 screenshots/cta-payment-paid-1-ios-0.png create mode 120000 screenshots/cta-payment-paid-1-ios-latest.png create mode 100644 screenshots/cta-payment-paid-2-ios-0.png create mode 120000 screenshots/cta-payment-paid-2-ios-latest.png create mode 100644 screenshots/cta-peer-pull-initiate-ios-0.png create mode 120000 screenshots/cta-peer-pull-initiate-ios-latest.png create mode 100644 screenshots/cta-peer-push-initiate-ios-0.png create mode 120000 screenshots/cta-peer-push-initiate-ios-latest.png create mode 100644 screenshots/cta-wire-transfer-1-ios-0.png create mode 120000 screenshots/cta-wire-transfer-1-ios-latest.png create mode 100644 screenshots/cta-wire-transfer-2-ios-0.png create mode 120000 screenshots/cta-wire-transfer-2-ios-latest.png create mode 100644 screenshots/cta-wire-transfer-3-ios-0.png create mode 120000 screenshots/cta-wire-transfer-3-ios-latest.png create mode 100644 screenshots/cta-withdraw-done-ios-0.png create mode 120000 screenshots/cta-withdraw-done-ios-latest.png create mode 100644 screenshots/cta-withdraw-ios-0.png create mode 120000 screenshots/cta-withdraw-ios-latest.png create mode 100644 screenshots/transaction-list-ios-0.png create mode 120000 screenshots/transaction-list-ios-latest.png diff --git a/design-documents/053-wallet-ui.rst b/design-documents/053-wallet-ui.rst index 3a6602e1..99640ceb 100644 --- a/design-documents/053-wallet-ui.rst +++ b/design-documents/053-wallet-ui.rst @@ -112,6 +112,11 @@ Screenshots | Android | .. image:: ../screenshots/balance-list-android-latest.png | | | :width: 30% | +-----------+----------------------------------------------------------------+ +| iOS | .. image:: ../screenshots/balance-list-1-ios-latest.png | +| | :width: 30% | +| | .. image:: ../screenshots/balance-list-2-ios-latest.png | +| | :width: 30% | ++-----------+----------------------------------------------------------------+ .. _transaction-list-ref: @@ -185,6 +190,9 @@ Screenshots | Android | .. image:: ../screenshots/transaction-list-android-latest.png | | | :width: 30% | +-----------+----------------------------------------------------------------+ +| iOS | .. image:: ../screenshots/transaction-list-ios-latest.png | +| | :width: 30% | ++-----------+----------------------------------------------------------------+ .. _cta-withdraw-ref: @@ -232,6 +240,9 @@ Screenshots | Android | .. image:: ../screenshots/cta-withdraw-2-android-latest.png | | | :width: 30% | +-----------+----------------------------------------------------------------+ +| iOS | .. image:: ../screenshots/cta-withdraw-ios-latest.png | +| | :width: 30% | ++-----------+----------------------------------------------------------------+ .. _cta-wire-transfer-ref: @@ -270,6 +281,13 @@ Screenshots | | .. image:: ../screenshots/cta-wire-transfer-2-android-latest.png | | | :width: 30% | +-----------+------------------------------------------------------------------+ +| iOS | .. image:: ../screenshots/cta-wire-transfer-1-ios-latest.png | +| | :width: 30% | +| | .. image:: ../screenshots/cta-wire-transfer-2-ios-latest.png | +| | :width: 30% | +| | .. image:: ../screenshots/cta-wire-transfer-3-ios-latest.png | +| | :width: 30% | ++-----------+------------------------------------------------------------------+ .. _cta-withdraw-done-ref: @@ -305,6 +323,9 @@ Screenshots | Android | .. image:: ../screenshots/cta-withdraw-done-android-latest.png | | | :width: 30% | +-----------+------------------------------------------------------------------+ +| iOS | .. image:: ../screenshots/cta-withdraw-done-ios-latest.png | +| | :width: 30% | ++-----------+------------------------------------------------------------------+ .. _cta-url-entry-ref: @@ -387,6 +408,9 @@ Screenshots | Android | .. image:: ../screenshots/cta-payment-android-latest.png | | | :width: 30% | +-----------+------------------------------------------------------------------+ +| iOS | .. image:: ../screenshots/cta-payment-ios-latest.png | +| | :width: 30% | ++-----------+------------------------------------------------------------------+ .. _cta-payment-paid-ref: @@ -422,6 +446,11 @@ Screenshots | Android | .. image:: ../screenshots/cta-payment-paid-android-latest.png | | | :width: 30% | +-----------+------------------------------------------------------------------+ +| iOS | .. image:: ../screenshots/cta-payment-paid-1-ios-latest.png | +| | :width: 30% | +| | .. image:: ../screenshots/cta-payment-paid-2-ios-latest.png | +| | :width: 30% | ++-----------+------------------------------------------------------------------+ .. _cta-deposit-ref: @@ -459,6 +488,11 @@ Screenshots | Android | .. image:: ../screenshots/cta-deposit-android-latest.png | | | :width: 30% | +-----------+------------------------------------------------------------------+ +| iOS | .. image:: ../screenshots/cta-deposit-1-ios-latest.png | +| | :width: 30% | +| | .. image:: ../screenshots/cta-deposit-2-ios-latest.png | +| | :width: 30% | ++-----------+------------------------------------------------------------------+ .. _cta-peer-pull-initiate-ref: @@ -507,6 +541,9 @@ Screenshots | Android | .. image:: ../screenshots/cta-peer-pull-initiate-android-latest.png | | | :width: 30% | +-----------+----------------------------------------------------------------------+ +| iOS | .. image:: ../screenshots/cta-peer-pull-initiate-ios-latest.png | +| | :width: 30% | ++-----------+----------------------------------------------------------------------+ .. _cta-peer-pull-confirm-ref: @@ -571,6 +608,9 @@ Screenshots | Android | .. image:: ../screenshots/cta-peer-push-initiate-android-latest.png | | | :width: 30% | +-----------+----------------------------------------------------------------------+ +| iOS | .. image:: ../screenshots/cta-peer-push-initiate-ios-latest.png | +| | :width: 30% | ++-----------+----------------------------------------------------------------------+ .. _cta-peer-push-confirm-ref: @@ -661,6 +701,10 @@ Screenshots | Android | .. image:: ../screenshots/cta-accept-tos-android-latest.png | | | :width: 30% | +-----------+------------------------------------------------------------------+ +| iOS | .. image:: ../screenshots/cta-accept-tos-ios-latest.png | +| | :width: 30% | ++-----------+------------------------------------------------------------------+ + Q / A ===== diff --git a/screenshots/balance-list-1-ios-0.png b/screenshots/balance-list-1-ios-0.png new file mode 100644 index 00000000..bead680a Binary files /dev/null and b/screenshots/balance-list-1-ios-0.png differ diff --git a/screenshots/balance-list-1-ios-latest.png b/screenshots/balance-list-1-ios-latest.png new file mode 120000 index 00000000..d876cbcc --- /dev/null +++ b/screenshots/balance-list-1-ios-latest.png @@ -0,0 +1 @@ +balance-list-1-ios-0.png \ No newline at end of file diff --git a/screenshots/balance-list-2-ios-0.png b/screenshots/balance-list-2-ios-0.png new file mode 100644 index 00000000..23efbbd5 Binary files /dev/null and b/screenshots/balance-list-2-ios-0.png differ diff --git a/screenshots/balance-list-2-ios-latest.png b/screenshots/balance-list-2-ios-latest.png new file mode 120000 index 00000000..4b7f977e --- /dev/null +++ b/screenshots/balance-list-2-ios-latest.png @@ -0,0 +1 @@ +balance-list-2-ios-0.png \ No newline at end of file diff --git a/screenshots/cta-accept-tos-ios-0.png b/screenshots/cta-accept-tos-ios-0.png new file mode 100644 index 00000000..7d8d5ff8 Binary files /dev/null and b/screenshots/cta-accept-tos-ios-0.png differ diff --git a/screenshots/cta-accept-tos-ios-latest.png b/screenshots/cta-accept-tos-ios-latest.png new file mode 120000 index 00000000..091a79a1 --- /dev/null +++ b/screenshots/cta-accept-tos-ios-latest.png @@ -0,0 +1 @@ +cta-accept-tos-ios-0.png \ No newline at end of file diff --git a/screenshots/cta-deposit-1-ios-0.png b/screenshots/cta-deposit-1-ios-0.png new file mode 100644 index 00000000..6cf30dde Binary files /dev/null and b/screenshots/cta-deposit-1-ios-0.png differ diff --git a/screenshots/cta-deposit-1-ios-latest.png b/screenshots/cta-deposit-1-ios-latest.png new file mode 120000 index 00000000..a3a21c74 --- /dev/null +++ b/screenshots/cta-deposit-1-ios-latest.png @@ -0,0 +1 @@ +cta-deposit-1-ios-0.png \ No newline at end of file diff --git a/screenshots/cta-deposit-2-ios-0.png b/screenshots/cta-deposit-2-ios-0.png new file mode 100644 index 00000000..49007f6c Binary files /dev/null and b/screenshots/cta-deposit-2-ios-0.png differ diff --git a/screenshots/cta-deposit-2-ios-latest.png b/screenshots/cta-deposit-2-ios-latest.png new file mode 120000 index 00000000..5dd80393 --- /dev/null +++ b/screenshots/cta-deposit-2-ios-latest.png @@ -0,0 +1 @@ +cta-deposit-2-ios-0.png \ No newline at end of file diff --git a/screenshots/cta-payment-ios-0.png b/screenshots/cta-payment-ios-0.png new file mode 100644 index 00000000..ad7cb8f0 Binary files /dev/null and b/screenshots/cta-payment-ios-0.png differ diff --git a/screenshots/cta-payment-ios-latest.png b/screenshots/cta-payment-ios-latest.png new file mode 120000 index 00000000..130b47c8 --- /dev/null +++ b/screenshots/cta-payment-ios-latest.png @@ -0,0 +1 @@ +cta-payment-ios-0.png \ No newline at end of file diff --git a/screenshots/cta-payment-paid-1-ios-0.png b/screenshots/cta-payment-paid-1-ios-0.png new file mode 100644 index 00000000..09364982 Binary files /dev/null and b/screenshots/cta-payment-paid-1-ios-0.png differ diff --git a/screenshots/cta-payment-paid-1-ios-latest.png b/screenshots/cta-payment-paid-1-ios-latest.png new file mode 120000 index 00000000..c721af49 --- /dev/null +++ b/screenshots/cta-payment-paid-1-ios-latest.png @@ -0,0 +1 @@ +cta-payment-paid-1-ios-0.png \ No newline at end of file diff --git a/screenshots/cta-payment-paid-2-ios-0.png b/screenshots/cta-payment-paid-2-ios-0.png new file mode 100644 index 00000000..b340000f Binary files /dev/null and b/screenshots/cta-payment-paid-2-ios-0.png differ diff --git a/screenshots/cta-payment-paid-2-ios-latest.png b/screenshots/cta-payment-paid-2-ios-latest.png new file mode 120000 index 00000000..7b13031e --- /dev/null +++ b/screenshots/cta-payment-paid-2-ios-latest.png @@ -0,0 +1 @@ +cta-payment-paid-2-ios-0.png \ No newline at end of file diff --git a/screenshots/cta-peer-pull-initiate-ios-0.png b/screenshots/cta-peer-pull-initiate-ios-0.png new file mode 100644 index 00000000..421cae8c Binary files /dev/null and b/screenshots/cta-peer-pull-initiate-ios-0.png differ diff --git a/screenshots/cta-peer-pull-initiate-ios-latest.png b/screenshots/cta-peer-pull-initiate-ios-latest.png new file mode 120000 index 00000000..e083752f --- /dev/null +++ b/screenshots/cta-peer-pull-initiate-ios-latest.png @@ -0,0 +1 @@ +cta-peer-pull-initiate-ios-0.png \ No newline at end of file diff --git a/screenshots/cta-peer-push-initiate-ios-0.png b/screenshots/cta-peer-push-initiate-ios-0.png new file mode 100644 index 00000000..a574c880 Binary files /dev/null and b/screenshots/cta-peer-push-initiate-ios-0.png differ diff --git a/screenshots/cta-peer-push-initiate-ios-latest.png b/screenshots/cta-peer-push-initiate-ios-latest.png new file mode 120000 index 00000000..f42c0924 --- /dev/null +++ b/screenshots/cta-peer-push-initiate-ios-latest.png @@ -0,0 +1 @@ +cta-peer-push-initiate-ios-0.png \ No newline at end of file diff --git a/screenshots/cta-wire-transfer-1-ios-0.png b/screenshots/cta-wire-transfer-1-ios-0.png new file mode 100644 index 00000000..1d9fdbfd Binary files /dev/null and b/screenshots/cta-wire-transfer-1-ios-0.png differ diff --git a/screenshots/cta-wire-transfer-1-ios-latest.png b/screenshots/cta-wire-transfer-1-ios-latest.png new file mode 120000 index 00000000..49cacb7f --- /dev/null +++ b/screenshots/cta-wire-transfer-1-ios-latest.png @@ -0,0 +1 @@ +cta-wire-transfer-1-ios-0.png \ No newline at end of file diff --git a/screenshots/cta-wire-transfer-2-ios-0.png b/screenshots/cta-wire-transfer-2-ios-0.png new file mode 100644 index 00000000..3ea5b9ca Binary files /dev/null and b/screenshots/cta-wire-transfer-2-ios-0.png differ diff --git a/screenshots/cta-wire-transfer-2-ios-latest.png b/screenshots/cta-wire-transfer-2-ios-latest.png new file mode 120000 index 00000000..6879480a --- /dev/null +++ b/screenshots/cta-wire-transfer-2-ios-latest.png @@ -0,0 +1 @@ +cta-wire-transfer-2-ios-0.png \ No newline at end of file diff --git a/screenshots/cta-wire-transfer-3-ios-0.png b/screenshots/cta-wire-transfer-3-ios-0.png new file mode 100644 index 00000000..c15f9a5e Binary files /dev/null and b/screenshots/cta-wire-transfer-3-ios-0.png differ diff --git a/screenshots/cta-wire-transfer-3-ios-latest.png b/screenshots/cta-wire-transfer-3-ios-latest.png new file mode 120000 index 00000000..daba13f8 --- /dev/null +++ b/screenshots/cta-wire-transfer-3-ios-latest.png @@ -0,0 +1 @@ +cta-wire-transfer-3-ios-0.png \ No newline at end of file diff --git a/screenshots/cta-withdraw-done-ios-0.png b/screenshots/cta-withdraw-done-ios-0.png new file mode 100644 index 00000000..93561c5d Binary files /dev/null and b/screenshots/cta-withdraw-done-ios-0.png differ diff --git a/screenshots/cta-withdraw-done-ios-latest.png b/screenshots/cta-withdraw-done-ios-latest.png new file mode 120000 index 00000000..26f90634 --- /dev/null +++ b/screenshots/cta-withdraw-done-ios-latest.png @@ -0,0 +1 @@ +cta-withdraw-done-ios-0.png \ No newline at end of file diff --git a/screenshots/cta-withdraw-ios-0.png b/screenshots/cta-withdraw-ios-0.png new file mode 100644 index 00000000..11dd9db0 Binary files /dev/null and b/screenshots/cta-withdraw-ios-0.png differ diff --git a/screenshots/cta-withdraw-ios-latest.png b/screenshots/cta-withdraw-ios-latest.png new file mode 120000 index 00000000..9c7d604b --- /dev/null +++ b/screenshots/cta-withdraw-ios-latest.png @@ -0,0 +1 @@ +cta-withdraw-ios-0.png \ No newline at end of file diff --git a/screenshots/transaction-list-ios-0.png b/screenshots/transaction-list-ios-0.png new file mode 100644 index 00000000..6180c2c5 Binary files /dev/null and b/screenshots/transaction-list-ios-0.png differ diff --git a/screenshots/transaction-list-ios-latest.png b/screenshots/transaction-list-ios-latest.png new file mode 120000 index 00000000..e0d8b772 --- /dev/null +++ b/screenshots/transaction-list-ios-latest.png @@ -0,0 +1 @@ +transaction-list-ios-0.png \ No newline at end of file -- cgit v1.2.3 From c0dcafaaef7dc0fbdf1b263e0c3d8fa3935131f5 Mon Sep 17 00:00:00 2001 From: Florian Dold Date: Fri, 8 Mar 2024 20:14:00 +0100 Subject: add v0.10.x qa checklist --- checklists/qa-0.10.rst | 233 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 233 insertions(+) create mode 100644 checklists/qa-0.10.rst diff --git a/checklists/qa-0.10.rst b/checklists/qa-0.10.rst new file mode 100644 index 00000000..262f44f5 --- /dev/null +++ b/checklists/qa-0.10.rst @@ -0,0 +1,233 @@ +Taler 0.9.4 QA Plan +------------------- + +Wallet Platforms +^^^^^^^^^^^^^^^^ + +Platforms listed here are the officially supported platforms for this release. + +* Overview / Installation Page + + * https://taler.net/en/wallet.html + +* Android + + * Google Play: https://play.google.com/store/apps/details?id=net.taler.wallet + * F-Droid: https://f-droid.org/en/packages/net.taler.wallet.fdroid/ + * APK Download: TBD + +* Browser + + * Chrome: https://chromewebstore.google.com/detail/gnu-taler-wallet/millncjiddlpgdmkklmhfadpacifaonc + * Firefox: https://addons.mozilla.org/en-US/firefox/addon/taler-wallet/ + +* iOS + + +Running Deployments +^^^^^^^^^^^^^^^^^^^ + +These deployments are maintained by us and should work for the release: + +* Sandcastle-based: + + * demo.taler.net + + * test.taler.net + +* Regio-based: + + * regio-taler.fdold.eu + + +Wallet Flows +^^^^^^^^^^^^ + +* Bank-integrated withdrawal + + * webext: "Continue with Mobile Wallet" flow + +* Manual withdrawal + + * ``taler://withdraw-exchange`` flow + + * Currency conversion withdrawal + +* Peer push payments ("Send Money") + +* Peer pull payments ("Receive Money") + +* Deposit into bank account + + * Check that deposit arrived + +* Payment at merchant + + * on blog merchant + * on survey + * directly initiated via merchant SPA + * webext: "Pay with Mobile Wallet" flow + +* Pay templates + + * Payment TOTP codes + +* Exchange management + + * Reloading exchange keys + * Deleting an exchange + +* Offline handling + + * Check error messages for other flows when internet connectivity + is bad or device is completely offline. + + +libeufin-bank Flows +^^^^^^^^^^^^^^^^^^^ + +* Admin functionality + + * Login + + * Credential change + + * Conversion settings + + * Bank account creation + + * Test transfers + +* Normal account functionality + + * Transfers + + * Transfer to the exchange should bounce + + * Withdrawals + + * (conversion-only): Test cash-in + + * (conversion-only): Test cash-out + + * Lower cash-out limit enforced + + * 2FA for withdrawals, cash-out + + +Merchant Backend SPA Flows +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +* Instance creation + +* Simple bank account setup + +* Order creation + + * Pay order (with short wire transfer deadline) + + * Check that money from order arrive at the bank with the right subject + +* Extended bank account setup + + * Add Taler Bank Revenue API + + * Check bank transfer list (for wire transfer of previously paid+wired order) + + * Check order payment status goes to "final" automatically + +* TOTP Device Management + + * Add device + + * Edit device (set new secret, export new secret as QR code) + + * Delete device + +* Templates + + * Add template + + * Edit template + + * Add TOTP device to template + + * Edit TOTP device associated with template + + * Pay template + + * Check TOTP code matches + + * Remove TOTP device from template + + * Delete template + + + +Regio Deployment +^^^^^^^^^^^^^^^^ + +* Deployment Automation (deployment.git/regional-currency) + + * Test with Debian bookworm + + * Test with Ubuntu mantic + + * Check logs for errors + + * Test with telesign (SMS) + + * Set up EBICS integration + + * Check that ToS is configured + +* Deployment Functionality + + * All flows of the wallet should work (see ``Wallet Flows`` above) + + * All flows of libeufin-bank should work (see ``libeufin-bank Flows`` above) + + * Merchant backend should work (see ``Merchant Backend SPA Flows`` above) + + * Check logs + + +Android Merchant PoS +^^^^^^^^^^^^^^^^^^^^ + +* Test against demo.taler.net + + +Android Cashier App +^^^^^^^^^^^^^^^^^^^ + +* Test against demo.taler.net + + +CI +^^ + +* https://buildbot.taler.net/#/waterfall +* CI should pass + + +Debian Repository +^^^^^^^^^^^^^^^^^ + +* Debian + + * repo at https://deb.taler.net/apt/debian/ + * supported codename(s): bookworm + + +* Ubuntu: + + * repo at https://deb.taler.net/apt/ubuntu/ + * supported codename(s): mantic + + +GNU Release +^^^^^^^^^^^ + +* Release announcement +* FTP upload -- cgit v1.2.3 From dedcfc666173b1782381b7a880d1e68ccaadfe87 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Fri, 8 Mar 2024 22:25:34 +0100 Subject: specification update for #8000 / exchange protocol v19 --- core/api-exchange.rst | 29 +++++++++++++++++++++++++---- 1 file changed, 25 insertions(+), 4 deletions(-) diff --git a/core/api-exchange.rst b/core/api-exchange.rst index 429170ce..b8979520 100644 --- a/core/api-exchange.rst +++ b/core/api-exchange.rst @@ -62,7 +62,7 @@ possibly by using HTTPS. as well as the list of possible KYC requirements. This endpoint is largely for the SPA for AML officers. Merchants should use ``/keys`` which also contains the protocol version and currency. - This specification corresponds to ``current`` protocol being version **18**. + This specification corresponds to ``current`` protocol being **v19**. **Response:** @@ -81,7 +81,7 @@ possibly by using HTTPS. name: "taler-exchange"; // URN of the implementation (needed to interpret 'revision' in version). - // @since v18, may become mandatory in the future. + // @since **v18**, may become mandatory in the future. implementation?: string; // Currency supported by this exchange, given @@ -103,7 +103,7 @@ possibly by using HTTPS. name: string; // Code of the currency. - // Deprecated in protocol v18 for the exchange + // Deprecated in protocol **v18** for the exchange // and in protocol v6 for the merchant. currency: string; @@ -197,7 +197,7 @@ possibly by using HTTPS. // Set to true if this exchange allows the use // of reserves for rewards. - // @deprecated in protocol v18. + // @deprecated in protocol **v18**. rewards_allowed: false; // EdDSA master public key of the exchange, used to sign entries @@ -282,6 +282,17 @@ possibly by using HTTPS. // a `TALER_MasterWireDetailsPS` // with purpose ``TALER_SIGNATURE_MASTER_WIRE_DETAILS``. master_sig: EddsaSignature; + + // Display label wallets should use to show this + // bank account. + // Since protocol **v19**. + bank_label?: string; + + // *Signed* integer with the display priority for + // this bank account. Optional, 0 if missing. + // Since protocol **v19**. + priority?: Integer; + } .. ts:def:: AccountRestriction @@ -1102,6 +1113,16 @@ Management operations authorized by master key // become active immediately! Used ONLY to detect replay attacks. validity_start: Timestamp; + // Display label wallets should use to show this + // bank account. + // Since protocol **v19**. + bank_label?: string; + + // *Signed* integer with the display priority for + // this bank account. + // Since protocol **v19**. + priority?: Integer; + } .. http:post:: /management/wire/disable -- cgit v1.2.3 From f7836f5bf9010c7546fb132fdcc6659072729f5a Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Fri, 8 Mar 2024 23:16:15 +0100 Subject: document 'display-hint' option to taler-exchange-offline --- manpages/taler-exchange-offline.1.rst | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/manpages/taler-exchange-offline.1.rst b/manpages/taler-exchange-offline.1.rst index 378c6312..bd8cd793 100644 --- a/manpages/taler-exchange-offline.1.rst +++ b/manpages/taler-exchange-offline.1.rst @@ -277,6 +277,14 @@ Afterwards, optional arguments can be given: REST API that allows merchants and wallets to determine the current conversion rate. + * ``display-hint`` $PRIORITY $LABEL: specifies that this bank account should + be shown to the user with the given numeric $PRIORITY (higher is earlier) + 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 0 + 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 -- cgit v1.2.3 From b974b4dc18a0010db78f5982a97e120b056b8632 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Sat, 9 Mar 2024 20:48:08 +0100 Subject: spec for #8608 --- core/api-merchant.rst | 26 +++++++++++++++++++++++++- 1 file changed, 25 insertions(+), 1 deletion(-) diff --git a/core/api-merchant.rst b/core/api-merchant.rst index d21d8073..ebd5647d 100644 --- a/core/api-merchant.rst +++ b/core/api-merchant.rst @@ -123,7 +123,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 **10**. + This specification corresponds to ``current`` protocol being version **11**. **Response:** @@ -3048,6 +3048,30 @@ Removing template Using template ---------------- +.. http:get:: [/instances/$INSTANCE]/templates/$TEMPLATE_ID + + This is used to obtain information about a specific template by wallets + before they ask the user to fill in details. + This endpoint is available since protocol **v11**. + + **Response:** + + :http:statuscode:`200 OK`: + The backend has successfully returned the detailed information about a specific template. + Returns a `WalletTemplateDetails`. + :http:statuscode:`404 Not found`: + The instance or template(ID) is unknown to the backend. + + .. ts:def:: WalletTemplateDetails + + interface WalletTemplateDetails { + + // Hard-coded information about the contrac terms + // for this template. + template_contract: TemplateContractDetails; + } + + .. http:post:: [/instances/$INSTANCES]/templates/$TEMPLATE_ID This using template can be modified by everyone and will be used to create order. -- cgit v1.2.3 From 72dcd025f7f036812125573d91ed92ab1625a307 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Sun, 10 Mar 2024 12:12:52 +0100 Subject: work on #8602 --- frags/deploying-tos.rst | 45 ++++++++++++++ frags/regional-system-on.rst | 28 +++++++++ libeufin/regional-automated-manual.rst | 76 +++++++---------------- libeufin/regional-custom-manual.rst | 108 +++++++++++++++++++-------------- 4 files changed, 158 insertions(+), 99 deletions(-) create mode 100644 frags/deploying-tos.rst create mode 100644 frags/regional-system-on.rst diff --git a/frags/deploying-tos.rst b/frags/deploying-tos.rst new file mode 100644 index 00000000..5b389f44 --- /dev/null +++ b/frags/deploying-tos.rst @@ -0,0 +1,45 @@ +.. + This file is part of GNU TALER. + Copyright (C) 2014-2024 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 + + +Configuring exchange terms +========================== + +You can use your own terms of service and privacy policy. You can use the default templates in ``/usr/share/taler/terms`` as a guide. +Assuming you have custom terms of service and privacy policy ``rst`` teamplte files at ``TOS_PATH`` and ``PRIVACY_PATH``, the following commands generate the terms files: + +.. code-block:: console + + # taler-terms-generator -i "$TOS_PATH" + # taler-terms-generator -i "$PRIVACY_PATH" + +You now have to specify the terms file names in the exchange config: + +.. code-block:: console + + # TERMS_ETAG="$(basename "$TOS_PATH" .rst)" + # PRIVACY_ETAG="$(basename "$PRIVACY_PATH" .rst)" + +.. code-block:: ini + + [exchange] + TERMS_ETAG=${TERMS_ETAG} + PRIVACY_ETAG=${PRIVACY_ETAG} + +Make sure to restart taler-exchange after changing these configuration options: + +.. code-block:: console + + # systemctl restart taler-exchange.target diff --git a/frags/regional-system-on.rst b/frags/regional-system-on.rst new file mode 100644 index 00000000..7a150cbf --- /dev/null +++ b/frags/regional-system-on.rst @@ -0,0 +1,28 @@ +.. + This file is part of GNU TALER. + Copyright (C) 2014-2024 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 + + +System ON! +========== + +The last step is to enable libeufin-nexus to :ref:`import incoming bank +transactions ` (cash in) and to :ref:`trigger +outgoing bank transactions ` (cash out). + +.. code-block:: console + + # systemctl enable --now libeufin-nexus.target + +.. FIXME: explain how to test if libeufin is working! diff --git a/libeufin/regional-automated-manual.rst b/libeufin/regional-automated-manual.rst index b199aa92..645e000f 100644 --- a/libeufin/regional-automated-manual.rst +++ b/libeufin/regional-automated-manual.rst @@ -105,8 +105,8 @@ The script will start by installing the required packages and then asking you fu #. Whether to use TLS or not. You should answer ``y`` in most cases. #. Whether to setup SMS two-factor authentication using `Telesign `_, multi-factor authentication is strongly recommended, especially when regional currency can be converted to fiat currency. This requires `a Customer ID and an API Key `_. You should answer ``y`` in most cases. #. The admin password for the bank. Be absolutely sure to enter a very, very long and high-entropy password, preferably using the autogenerated one. -#. Whether to generate terms of service (ToS) for the exchange from default templates. -#. Whether to generate a privacy policy for the exchange from default templates. +#. Whether to generate terms of service (ToS) for the exchange from default templates. +#. Whether to generate a privacy policy for the exchange from default templates. The information you entered as well as the generated bank admin password will be stored in a file called ``config/user.conf``. If you run the script in @@ -230,62 +230,30 @@ The EBICS setup is finished once the bank keys have been accepted. Configuring the Exchange for Conversion +++++++++++++++++++++++++++++++++++++++ -By default, the exchange is setup to perform conversion without any restrictions. You may configure restrictions on the bank accounts that may originate the funds, for example, to prevent international wire transfers that may expose you to additional compliance risks: +In our automated setup the second account is automatically set up correctly +without fees or special restrictions. However, various additional +*restrictions* and *options* could be configured. Details are explained in +the :ref:`regional conversion setup ` section for the +manual setup and in the the manpage of ``taler-exchange-offline``. -.. code-block:: console - - # Make sure environment variables are available - $ source config/user.conf - - $ sudo -u taler-exchange-offline taler-exchange-offline \ - enable-account \ - "${CONVERSION_PAYTO}" \ - conversion-url "${PROTO}://bank.$DOMAIN_NAME/conversion-info/" \ - # restrictions ... - upload - -.. note:: - Refer to the manpage ``taler-exchange-offline`` for a full array of possible restrictions. - -System ON! -++++++++++ - -The last step is to enable libeufin-nexus to :ref:`import incoming bank -transactions ` (cash in) and to :ref:`trigger -outgoing bank transactions ` (cash out). - -.. code-block:: console - - # systemctl enable --now libeufin-nexus.target - -Configuring exchange terms -++++++++++++++++++++++++++ - -You can use your own terms of service and privacy policy. You can use the default templates in ``/usr/share/taler/terms`` as a guide. -Assuming you have custom terms of service and privacy policy ``rst`` teamplte files at ``TOS_PATH`` and ``PRIVACY_PATH``, the following commands generate the terms files: -.. code-block:: console - - # taler-terms-generator -i "$TOS_PATH" - # taler-terms-generator -i "$PRIVACY_PATH" - -You now have to specify the terms file names in the exchange config: - -.. code-block:: console - - # TERMS_ETAG="$(basename "$TOS_PATH" .rst)" - # PRIVACY_ETAG="$(basename "$PRIVACY_PATH" .rst)" +.. include:: ../frags/regional-system-on.rst +.. include:: ../frags/deploying-tos.rst +.. include:: ../frags/regional-manual-use.rst -.. code-block:: ini - [exchange] - TERMS_ETAG=${TERMS_ETAG} - PRIVACY_ETAG=${PRIVACY_ETAG} +Installing Updates +++++++++++++++++++ -Make sure to restart taler-exchange after changing these configuration options: +The standard procedure for installing updates is to: -.. code-block:: console + * First, make a backup (!) + * Stop Taler services + * Install new version + * Upgrade databases + * Start Taler services - # systemctl restart taler-exchange.target - -.. include:: ../frags/regional-manual-use.rst +The "upgrade.sh" script in the "regional-currency/" folder of "deployment.git" +shows how to do the above steps *except* for the backup. For the backup, all +critical bits of data will be in the Postgresql databases. Thus, we recommend +following the database manual on making backups. diff --git a/libeufin/regional-custom-manual.rst b/libeufin/regional-custom-manual.rst index 8477c18d..fcd1229e 100644 --- a/libeufin/regional-custom-manual.rst +++ b/libeufin/regional-custom-manual.rst @@ -72,6 +72,11 @@ Now you have to set the conversion rates and the ``admin`` debt limit via the ba Configuring the Exchange for Conversion +++++++++++++++++++++++++++++++++++++++ +An exchange that supports currency conversion needs to advertise two bank +accounts, one in the regional currency and a second in the fiat currency. The +conversion logic ensures that wire transfers in either account are +immediately reflected in the other account. + This section explains how to enable currency conversion at the exchange, which is critical for wallets to know how to wire fiat currency to an exchange to obtain regional currency. @@ -90,75 +95,88 @@ the possibility of currency conversion (cash in): .. code-block:: console - # taler-exchange-offline \ + # source config/user.conf + # sudo -u taler-exchange-offline \ + taler-exchange-offline \ + wire-fee now iban "${CURRENCY}":0 "${CURRENCY}":0 \ enable-account \ - payto://iban/$IBAN?receiver-name=$NAME \ - conversion-url "$CONVERSION_URL" \ - debit-restriction \ - deny \ + "${CONVERSION_PAYTO}" \ + conversion-url "${PROTO}://bank.$DOMAIN_NAME/conversion-info/" \ + display-hint 10 "CHF" \ + debit-restriction deny \ credit-restriction \ regex \ 'payto://iban/.*/CH.*?receiver-name=.*' \ 'Swiss only' \ '{ "de" : "nur Schweiz", \ - "fr" : "Suisse uniquement" }' + "fr" : "Suisse uniquement" }' \ upload Here, the ``$CONVERSION_URL`` must be set to the base URL of the conversion endpoint of the bank, which should be -``https://bank.$DOMAIN/conversion-info/`` in our setup. Note that you can -leave out the "credit-restriction" if you want to allow international inbound -wire transfers. The "debit-restriction" is largely mandatory as in this setup -the taler-exchange-transfer is only configured to deal with the regional +``https://bank.$DOMAIN/conversion-info/`` in our setup. + +The above commands set up the exchange to perform conversion with a +restriction to only accept credit transfers from Swiss bank accounts. You may +want to configure such restrictions on the bank accounts that may originate +funds to prevent international wire transfers that may expose you to +additional compliance risks. + +You can leave out the "credit-restriction" if you want to allow international +inbound wire transfers. + +The "debit-restriction" is largely mandatory as in this setup the +``taler-exchange-transfer`` is only configured to deal with the regional currency bank. Crediting fiat bank accounts must thus be done via the cash-out functionality of the regional currency bank account. +The "display-hint" gives priority (10) for the fiat cash-in account over the +regional currency account in the withdraw dialog of the wallets and labels the +account with "CHF". + .. note:: The above command adds a **second** bank account to the exchange. You (or the guided setup script) should have already enabled the regional currency bank account (without any "conversion-url"). -System ON! -++++++++++ - -The last step is to enable libeufin-nexus to :ref:`import incoming bank -transactions ` (cash in) and to :ref:`trigger -outgoing bank transactions ` (cash out). - -.. code-block:: console - - # systemctl enable --now libeufin-nexus.target - - -Configuring exchange terms -++++++++++++++++++++++++++ - -You can use your own terms of service and privacy policy. You can use the default templates in ``/usr/share/taler/terms`` as a guide. -Assuming you have custom terms of service and privacy policy ``rst`` teamplte files at ``TOS_PATH`` and ``PRIVACY_PATH``, the following commands generate the terms files: +.. include:: ../frags/regional-system-on.rst +.. include:: ../frags/deploying-tos.rst +.. include:: ../frags/regional-manual-use.rst -.. code-block:: console - # taler-terms-generator -i "$TOS_PATH" - # taler-terms-generator -i "$PRIVACY_PATH" +Maintenance ++++++++++++ -You now have to specify the terms file names in the exchange config: +The ``taler-exchange-offline`` commands given above set fees only for the +current year (``now``). Thus, before January 1st of each year, you must to set +up new fees for the new calendar year. In a regional currency setup, this +typically requires up to three annual settings: .. code-block:: console - # TERMS_ETAG="$(basename "$TOS_PATH" .rst)" - # PRIVACY_ETAG="$(basename "$PRIVACY_PATH" .rst)" - -.. code-block:: ini - - [exchange] - TERMS_ETAG=${TERMS_ETAG} - PRIVACY_ETAG=${PRIVACY_ETAG} + # YEAR=2025 # edit if necessary + # FIAT_CURRENCY=CHF # edit if necessary + # REGIO_CURRENCY=NETZBON # edit if necessary + # sudo -u taler-exchange-offline \ + taler-exchange-offline \ + wire-fee "$YEAR" \ + iban "${FIAT_CURRENCY}":0 "${FIAT_CURRENCY}":0 \ + wire-fee "$YEAR" \ + x-taler-bank "${REGIO_CURRENCY}":0 "${REGIO_CURRENCY}":0 \ + global-fee $YEAR \ + "${REGIO_CURRENCY}:0" \ + "${REGIO_CURRENCY}:0" \ + "${REGIO_CURRENCY}:0" + 4w 6y 4 \ + upload + +If the fees are not all zero, simply change the respective place to specify +a non-zero fee. -Make sure to restart taler-exchange after changing these configuration options: - -.. code-block:: console - - # systemctl restart taler-exchange.target +.. note:: -.. include:: ../frags/regional-manual-use.rst + Additionally, the denomination signing keys will only have been + pre-generated for some time, depending on your ``LOOKAHEAD_SIGN`` + configuration option. Thus, you may need to periodically run + the "taler-exchange-offline download sign upload" sequence as well! -- cgit v1.2.3 From 85e4a88881a77abf6f9928f226a1b78c925a608a Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Sun, 10 Mar 2024 12:49:03 +0100 Subject: fix bash JSON (#8602) --- libeufin/regional-custom-manual.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/libeufin/regional-custom-manual.rst b/libeufin/regional-custom-manual.rst index fcd1229e..580168f3 100644 --- a/libeufin/regional-custom-manual.rst +++ b/libeufin/regional-custom-manual.rst @@ -108,8 +108,7 @@ the possibility of currency conversion (cash in): regex \ 'payto://iban/.*/CH.*?receiver-name=.*' \ 'Swiss only' \ - '{ "de" : "nur Schweiz", \ - "fr" : "Suisse uniquement" }' \ + '{"de":"nur Schweiz","fr":"Suisse uniquement"}' \ upload Here, the ``$CONVERSION_URL`` must be set to the base URL of the conversion -- cgit v1.2.3 From 528e9af0603abbba9b46b7eec0bd46933ae7bdbb Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Sun, 10 Mar 2024 19:26:49 +0100 Subject: document p2p push --- taler-wallet.rst | 47 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 47 insertions(+) diff --git a/taler-wallet.rst b/taler-wallet.rst index 1d1a3991..4a975340 100644 --- a/taler-wallet.rst +++ b/taler-wallet.rst @@ -192,6 +192,53 @@ Manual withdrawing --amount EUR:5 +P2P push payments +----------------- + +The following code generates a P2P push transaction over 1 CHF +with an expiration time of 30 days (assuming the wallet has a +sufficient balance): + +.. code-block:: console + + $ taler-wallet-cli p2p initiate-push-debit \ + --purse-expiration="30 d" \ + --summary="The summary" \ + CHF:1 + +The final URL can then be found in the transaction list: + +.. code-block:: console + + $ taler-wallet-cli transactions + +Background wallet +----------------- + +A wallet can be launched in the background: + +.. code-block:: console + + $ taler-wallet-cli advanced serve & + +You can then run various Taler operations faster against +this one persistent instance: + +.. code-block:: console + + $ taler-wallet-cli --wallet-connection=wallet-core.sock ... + +Here ``...`` needs to be changed to the commando to run. +Make sure to run + +.. code-block:: console + + $ taler-wallet-cli --wallet-connection=wallet-core.sock \ + run-until-done + +to wait for pending transactions to complete. + + Testing an exchange deployment ------------------------------ -- cgit v1.2.3 From 2edc5e47bce285f6ef8c11dc1b4fabf01e510eea Mon Sep 17 00:00:00 2001 From: Javier Sepulveda Date: Mon, 11 Mar 2024 09:05:46 +0100 Subject: Forcing git add, to add image files - Taler monitoring rst --- images/grafana-postgres-exporter.png | Bin 0 -> 244971 bytes images/kuma.png | Bin 0 -> 244687 bytes images/taler-monitoring-infrastructure.png | Bin 0 -> 85006 bytes images/uptime-kuma-edit.png | Bin 0 -> 116550 bytes images/uptime-kuma-from-grafana.png | Bin 0 -> 345702 bytes 5 files changed, 0 insertions(+), 0 deletions(-) create mode 100644 images/grafana-postgres-exporter.png create mode 100644 images/kuma.png create mode 100644 images/taler-monitoring-infrastructure.png create mode 100644 images/uptime-kuma-edit.png create mode 100644 images/uptime-kuma-from-grafana.png diff --git a/images/grafana-postgres-exporter.png b/images/grafana-postgres-exporter.png new file mode 100644 index 00000000..a51c28f0 Binary files /dev/null and b/images/grafana-postgres-exporter.png differ diff --git a/images/kuma.png b/images/kuma.png new file mode 100644 index 00000000..d98772a1 Binary files /dev/null and b/images/kuma.png differ diff --git a/images/taler-monitoring-infrastructure.png b/images/taler-monitoring-infrastructure.png new file mode 100644 index 00000000..05f29704 Binary files /dev/null and b/images/taler-monitoring-infrastructure.png differ diff --git a/images/uptime-kuma-edit.png b/images/uptime-kuma-edit.png new file mode 100644 index 00000000..23b85dad Binary files /dev/null and b/images/uptime-kuma-edit.png differ diff --git a/images/uptime-kuma-from-grafana.png b/images/uptime-kuma-from-grafana.png new file mode 100644 index 00000000..c42b8660 Binary files /dev/null and b/images/uptime-kuma-from-grafana.png differ -- cgit v1.2.3 From f3cf0a283c328ebc71cfdbcf2894429066014a96 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Mon, 11 Mar 2024 09:41:46 +0100 Subject: -fix typo --- taler-user-guide.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/taler-user-guide.rst b/taler-user-guide.rst index 127218fb..8e42c0d2 100644 --- a/taler-user-guide.rst +++ b/taler-user-guide.rst @@ -322,7 +322,7 @@ Mustach templating engine: * timestamp: time of the refund (in nanoseconds since 1970) * order_id: the ID of the order that received the refund * :ref:`contract_terms `: the full JSON of the contract terms of the refunded order -* refund_amout: the amount that was being refunded +* refund_amount: the amount that was being refunded * reason: the reason entered by the merchant staff for granting the refund; be careful, you probably want to inform your staff if a webhook may expose this information to the consumer -- cgit v1.2.3 From 3f14606f7a2320e73afd681ac093204fd3582223 Mon Sep 17 00:00:00 2001 From: Matyja Lukas Adam Date: Tue, 12 Mar 2024 10:38:33 +0100 Subject: update donau api --- core/api-donau.rst | 26 ++++++++++---------------- 1 file changed, 10 insertions(+), 16 deletions(-) diff --git a/core/api-donau.rst b/core/api-donau.rst index 9ef69c92..09f644ec 100644 --- a/core/api-donau.rst +++ b/core/api-donau.rst @@ -15,6 +15,8 @@ @author Christian Grothoff @author Pius Loosli + @author Lukas Matyja + @author Johannes Casaburi ===================== The Donau RESTful API @@ -68,23 +70,11 @@ long-term offline signing key of the Donau, which clients should cache. **Request:** - :query last_issue_date: Optional argument specifying the maximum value of - any of the ``stamp_start`` members of the - donation unit keys of a ``/keys`` response that is - already known to the client. Allows the Donau to - only return keys that have changed since that - timestamp. The given value must be an unsigned - 64-bit integer representing seconds after 1970. If - the timestamp does not exactly match the - ``stamp_start`` of one of the donation unit keys, all - keys are returned. - **Response:** :http:statuscode:`200 OK`: The Donau responds with a `DonauKeysResponse` object. This request should - virtually always be successful. It only fails if the Donau is misconfigured or - has not yet been provisioned with key signatures via ``taler-donau-offline``. + virtually always be successful. It only fails if the Donau is misconfigured. **Details:** @@ -229,7 +219,7 @@ long-term offline signing key of the Donau, which clients should cache. **Response:** :http:statuscode:`200 OK`: - The body is a `VersionResponse`. + The body is a `DonauVersionResponse`. .. ts:def:: DonauVersionResponse @@ -555,6 +545,7 @@ The GET status requests require an authorized bearer token as well. interface Charity { charity_pub: EddsaPublicKey; name: string; + url: string; max_per_year: Amount; receipts_to_date: Amount; current_year: Integer; @@ -580,8 +571,11 @@ The GET status requests require an authorized bearer token as well. interface CharityRequest{ charity_pub: EddsaPublicKey; - max_per_year: Amount; name: string; + url: string; + max_per_year: Amount; + receipts_to_date: Amount; + current_year: Integer; } .. ts:def:: CharityResponse @@ -614,7 +608,7 @@ The GET status requests require an authorized bearer token as well. **Response:** - :http:statuscode:`200 OK`: + :http:statuscode:`204 No content`: The request was successful. :http:statuscode:`403 Forbidden`: -- cgit v1.2.3 From e3eb9659f541202b05092206e3a23c0aa247dfe9 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Tue, 12 Mar 2024 11:37:13 +0100 Subject: #8502: latest image --- images/regional-arch.png | Bin 126574 -> 117525 bytes 1 file changed, 0 insertions(+), 0 deletions(-) diff --git a/images/regional-arch.png b/images/regional-arch.png index 952b7e60..a3691aea 100644 Binary files a/images/regional-arch.png and b/images/regional-arch.png differ -- cgit v1.2.3 From 7feba2db0349be12482658df77773efc85f40915 Mon Sep 17 00:00:00 2001 From: Antoine A <> Date: Thu, 14 Mar 2024 02:04:46 +0100 Subject: update corebank API --- core/api-corebank.rst | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/core/api-corebank.rst b/core/api-corebank.rst index 851fc3ba..5a257257 100644 --- a/core/api-corebank.rst +++ b/core/api-corebank.rst @@ -626,6 +626,12 @@ Transactions // query string parameter of the 'payto' field. In case it // is given in both places, the payto_uri's takes the precedence. amount: string; + + // Nonce to make the request idempotent. Requests with the same + // ``request_uid`` that differ in any of the other fields + // are rejected. + // @since v4, will become mandatory in the next version. + request_uid?: ShortHashCode; } **Response:** @@ -644,6 +650,7 @@ Transactions * ``TALER_EC_BANK_SAME_ACCOUNT`` : creditor account is the same than ``USERNAME``. * ``TALER_EC_BANK_UNKNOWN_CREDITOR`` : creditor account was not found. * ``TALER_EC_BANK_UNALLOWED_DEBIT`` : the account does not have sufficient funds. + * ``TALER_EC_BANK_TRANSFER_REQUEST_UID_REUSED``: an operation with the same ``request_uid`` but different details has been submitted before. **Details:** -- cgit v1.2.3 From e8f307fe6911fdb53793e21168618c63b88b435e Mon Sep 17 00:00:00 2001 From: Joel-Haeberli Date: Thu, 14 Mar 2024 08:52:35 +0100 Subject: docs: add nonce2ecash docs --- core/api-nonce2ecash.rst | 163 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 163 insertions(+) create mode 100644 core/api-nonce2ecash.rst diff --git a/core/api-nonce2ecash.rst b/core/api-nonce2ecash.rst new file mode 100644 index 00000000..9e69e954 --- /dev/null +++ b/core/api-nonce2ecash.rst @@ -0,0 +1,163 @@ +.. + This file is part of GNU TALER. + + Copyright (C) 2014-2024 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 + + @author Joel Häberli + +=========================== +The nonce2ecash RESTful API +=========================== + +.. note:: + + **This API is experimental and not yet implemented** + +This chapter describe the APIs that third party providers need to integrate to allow +withdrawals through indirect payment channels like credit cards or ATM. + +.. contents:: Table of Contents + +-------------- +Authentication +-------------- + +Terminals which authenticate against the nonce2ecash API must provide their respective +access token. Therefore they provide a ``Authorization: Bearer $ACCESS_TOKEN`` header, +where `$ACCESS_TOKEN`` is a secret authentication token configured by the exchange and +must begin with the RFC 8959 prefix. + +---------------------------- +Configuration of nonce2ecash +---------------------------- + +.. http:get:: /config + + Return the protocol version and configuration information about the nonce2ecash API. + + **Response:** + + :http:statuscode:`200 OK`: + The exchange responds with a `Nonce2ecashConfig` object. This request should + virtually always be successful. + + **Details:** + + .. ts:def:: Nonce2ecashConfig + + interface Nonce2ecashConfig { + // Name of the API. + name: "taler-nonce2ecash"; + + // libtool-style representation of the nonce2ecash protocol version, see + // https://www.gnu.org/software/libtool/manual/html_node/Versioning.html#Versioning + // The format is "current:revision:age". + version: string; + } + +----------------------------- +Withdrawing using nonce2ecash +----------------------------- + +Withdrawals with a nonce2ecash are based on withdrawal operations which register a withdrawal identifier +(nonce) at the nonce2ecash component. The provider must first create a unique identifier for the withdrawal +operation (the ``WITHDRAWAL_ID``) to interact with the withdrawal operation and eventually withdraw using the wallet. + +.. http:post:: /withdrawal-operation + + Initiate the withdrawal operation, identified by the ``WITHDRAWAL_ID``. + + **Request:** + + .. ts:def:: WithdrawRegistration + + interface WithdrawRegistration { + // Maps a nonce generated by the provider to a reserve public key generated by the wallet. + withdrawal_id: ShortHashCode; + + // Reserve public key generated by the wallet. + // According to TALER_ReservePublicKeyP (https://docs.taler.net/core/api-common.html#cryptographic-primitives) + reserve_pub_key: EddsaPublicKey; + + // Optional amount for the withdrawal. + amount?: Amount; + + // Id of the terminal of the provider requesting a withdrawal by nonce. + // Assigned by the exchange. + provider_terminal_id: SafeUint64; + } + + **Response:** + + :http:statuscode:`204 No content`: + The withdrawal was successfully registered. + :http:statuscode:`400 Bad request`: + The ``WithdrawRegistration`` request was malformed or contained invalid parameters. + :http:statuscode:`500 Internal Server error`: + The registration of the withdrawal failed due to server side issues. + +.. http:get:: /withdrawal-operation/$WITHDRAWAL_ID + + Query information about a withdrawal operation, identified by the ``WITHDRAWAL_ID``. + + **Response:** + + :http:statuscode:`200 Ok`: + The withdrawal was found and is returned in the response body as ``Withdrawal``. + :http:statuscode:`404 Not found`: + nonce2ecash does not have a withdrawal registered with the specified ``WITHDRAWAL_ID``. + + **Details** + + .. ts:def:: Withdrawal + + interface Withdrawal { + + // Reserve public key generated by the wallet. + // According to TALER_ReservePublicKeyP (https://docs.taler.net/core/api-common.html#cryptographic-primitives) + reserve_pub_key: EddsaPublicKey; + } + +.. http:post:: /withdrawal-operation/$WITHDRAWAL_ID + + Notifies nonce2ecash about an executed payment for a specific withdrawal. + + **Request:** + + .. ts:def:: PaymentNotification + + interface PaymentNotification { + + // Unique identifier of the provider transaction. + provider_transaction_id: string; + + // Specifies the amount which was payed to the provider (without fees). + // This amount shall be put into the reserve linked to by the withdrawal id. + amount: Amount; + + // Fees associated with the payment. + fees: Amount; + } + + **Response:** + + :http:statuscode:`204 No content`: + nonce2ecash received the ``PaymentNotification`` successfully and will further process + the withdrawal. + :http:statuscode:`400 Bad request`: + The ``PaymentNotification`` request was malformed or contained invalid parameters. + :http:statuscode:`404 Not found`: + nonce2ecash does not have a withdrawal registered with the specified ``WITHDRAWAL_ID``. + :http:statuscode:`500 Internal Server error`: + The ``PaymentNotification`` could not be processed due to server side issues. -- cgit v1.2.3 From b19e504c032db698b73c20b3fb9871d51789da40 Mon Sep 17 00:00:00 2001 From: Christian Blättler Date: Fri, 15 Mar 2024 10:10:13 +0100 Subject: DD46: contract choices should only represent different inputs and outputs --- design-documents/046-mumimo-contracts.rst | 54 +++++++++++++++---------------- 1 file changed, 27 insertions(+), 27 deletions(-) diff --git a/design-documents/046-mumimo-contracts.rst b/design-documents/046-mumimo-contracts.rst index 5f1d1d98..4daa7465 100644 --- a/design-documents/046-mumimo-contracts.rst +++ b/design-documents/046-mumimo-contracts.rst @@ -143,6 +143,33 @@ The contract terms v1 will have the following structure: // More info about the merchant (same as in v0). merchant: Merchant; + // Human-readable description of the contract. + summary: string; + + // Map from IETF BCP 47 language tags to localized summaries. + summary_i18n?: { [lang_tag: string]: string }; + + // URL that will show that the order was successful after + // it has been paid for. Optional. When POSTing to the + // merchant, the placeholder "${ORDER_ID}" will be + // replaced with the actual order ID (useful if the + // order ID is generated server-side and needs to be + // in the URL). + // Note that this placeholder can only be used once. + // Either fulfillment_url or fulfillment_message must be specified. + fulfillment_url?: string; + + // Message shown to the customer after paying for the order. + // Either fulfillment_url or fulfillment_message must be specified. + fulfillment_message?: string; + + // Map from IETF BCP 47 language tags to localized fulfillment + // messages. + fulfillment_message_i18n?: { [lang_tag: string]: string }; + + // List of products that are part of the purchase (see `Product`). + products: Product[]; + // After this deadline has passed, no refunds will be accepted. refund_deadline: Timestamp; @@ -232,33 +259,6 @@ The contract terms v1 will have the following structure: interface ContractChoice { - // Human-readable description of the choice. - summary: string; - - // Map from IETF BCP 47 language tags to localized summaries. - summary_i18n?: { [lang_tag: string]: string }; - - // URL that will show that the order was successful after - // it has been paid for. Optional. When POSTing to the - // merchant, the placeholder "${ORDER_ID}" will be - // replaced with the actual order ID (useful if the - // order ID is generated server-side and needs to be - // in the URL). - // Note that this placeholder can only be used once. - // Either fulfillment_url or fulfillment_message must be specified. - fulfillment_url?: string; - - // Message shown to the customer after paying for the order. - // Either fulfillment_url or fulfillment_message must be specified. - fulfillment_message?: string; - - // Map from IETF BCP 47 language tags to localized fulfillment - // messages. - fulfillment_message_i18n?: { [lang_tag: string]: string }; - - // List of products that are part of the purchase (see `Product`). - products: Product[]; - // List of inputs the wallet must provision (all of them) to // satisfy the conditions for the contract. inputs: ContractInput[]; -- cgit v1.2.3 From df78b4db6eb5820cd3f2eab592c329777bbc28fd Mon Sep 17 00:00:00 2001 From: Christian Blättler Date: Fri, 15 Mar 2024 10:10:48 +0100 Subject: DD46: remove limits struct --- design-documents/046-mumimo-contracts.rst | 35 +------------------------------ 1 file changed, 1 insertion(+), 34 deletions(-) diff --git a/design-documents/046-mumimo-contracts.rst b/design-documents/046-mumimo-contracts.rst index 4daa7465..7d234110 100644 --- a/design-documents/046-mumimo-contracts.rst +++ b/design-documents/046-mumimo-contracts.rst @@ -214,47 +214,14 @@ The contract terms v1 will have the following structure: // contract without storing it separately in their database. extra?: any; - // Fee limits and wire account details by currency. - limits: { [currency: string]: CurrencyLimit }; - } - -.. ts:def:: CurrencyLimit - - interface CurrencyLimit { - - // The hash of the merchant instance's wire details. - h_wire: HashCode; - - // Wire transfer method identifier for the wire method associated with ``h_wire``. - // The wallet may only select exchanges via a matching auditor if the - // exchange also supports this wire method. - // The wire transfer fees must be added based on this wire transfer method. - wire_method: string; - // Maximum total deposit fee accepted by the merchant for this contract. max_fee: Amount; - // Maximum wire fee accepted by the merchant (customer share to be - // divided by the ``wire_fee_amortization`` factor, and further reduced - // if deposit fees are below ``max_fee``). Default if missing is zero. - max_wire_fee?: Amount; - - // Over how many customer transactions does the merchant expect to - // amortize wire fees on average? If the exchange's wire fee is - // above ``max_wire_fee``, the difference is divided by this number - // to compute the expected customer's contribution to the wire fee. - // The customer's contribution may further be reduced by the difference - // between the ``max_fee`` and the sum of the actual deposit fees. - // Optional, default value if missing is 1. 0 and negative values are - // invalid and also interpreted as 1. - wire_fee_amortization?: number; - // Exchanges that the merchant accepts for this currency. exchanges: Exchange[]; } - .. ts:def:: ContractChoice interface ContractChoice { @@ -267,7 +234,7 @@ The contract terms v1 will have the following structure: // once the contract is paid. outputs: ContractOutput[]; - // Map from authority labels to meta data abou the + // Map from authority labels to meta data about the // respective token authority. token_types: { [authority_label: string]: TokenAuthority }; -- cgit v1.2.3 From 657f5135d0d8b8d5af2d6ed3c24738c86db7a54d Mon Sep 17 00:00:00 2001 From: Christian Blättler Date: Fri, 15 Mar 2024 12:25:14 +0100 Subject: DD46: move token_types to top level to reduce duplication --- design-documents/046-mumimo-contracts.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/design-documents/046-mumimo-contracts.rst b/design-documents/046-mumimo-contracts.rst index 7d234110..714b5822 100644 --- a/design-documents/046-mumimo-contracts.rst +++ b/design-documents/046-mumimo-contracts.rst @@ -209,6 +209,10 @@ The contract terms v1 will have the following structure: // signing the deposit confirmation. choices: ContractChoice[]; + // Map from authority labels to meta data about the + // respective token authority. + token_types: { [authority_label: string]: TokenAuthority }; + // Extra data that is only interpreted by the merchant frontend. // Useful when the merchant needs to store extra information on a // contract without storing it separately in their database. @@ -234,10 +238,6 @@ The contract terms v1 will have the following structure: // once the contract is paid. outputs: ContractOutput[]; - // Map from authority labels to meta data about the - // respective token authority. - token_types: { [authority_label: string]: TokenAuthority }; - } .. ts:def:: ContractInput -- cgit v1.2.3 From 8c15fb22511d8d536190aaddb720a8de82b3a8a3 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Sun, 17 Mar 2024 12:04:44 +0100 Subject: update DD23 requirements --- design-documents/023-taler-kyc.rst | 45 ++++++++++++++++++++++++++++++++++++-- 1 file changed, 43 insertions(+), 2 deletions(-) diff --git a/design-documents/023-taler-kyc.rst b/design-documents/023-taler-kyc.rst index d34241d7..39a414e4 100644 --- a/design-documents/023-taler-kyc.rst +++ b/design-documents/023-taler-kyc.rst @@ -44,6 +44,46 @@ Taler needs to run KYC checks in the following circumstances: * key: reserve (=KYC account) long term public key per wallet (encoded as payto:// URI) +There are many different possible KYC/AML flows: + +* In-person validation by AML staff +* Validation involving local authorities and post-office +* Online validation + * Forms to be supplied by user + * Interactive video + * Documents to be supplied +* Forms to be filled by AML staff + +Additionally, the process is dynamic and conditional upon various decisions: + +* Individual vs. business +* PEP or non-PEP +* Hit on sanctions list +* Type of business (trust, foundation, listed on stock market, etc.) +* Need for plausibilization (via documents by user or staff research) +* Periodic updates (of customer data, of sanction lists) and re-assessment + +There are also various outcomes: + +* normal operation +* normal operation but with AML staff investigating +* held, requesting customer documentation +* held, AML staff reviewing evidence +* automatically frozen until certain day (due to sanctions) +* institutionally frozen until certain day (due to order by state authority) + +Finally, we need to produce statistics: + +* number of incidents reported (voluntarily, required) +* number of business relationships at any point in time +* number of risky business relationships (PEP, etc.) +* begin/end-date of relationships (data retained for X years after end of relationship) + +As a result, we largely end up in a large state machine where the AML staff has +serious flexibiltiy while the user needs guidance as to the possible next moves +and/or to the current state of their account (where some information must not be +disclosed). + Proposed Solution @@ -103,8 +143,9 @@ Access is ``authenticated`` by also passing the hash of the payto://-URI. initiate a KYC process are not very sensitive.) Given this triplet, the ``/kyc-check/`` endpoint returns either the (positive) KYC status or redirects the client (202) to the next required stage of the KYC process. The -redirection must be for an HTTP(S) endpoint to be triggered via a simple HTTP GET. As this endpoint is involved in every KYC check at the beginning, this is also the place where we can -integrate the payment process for the KYC fee. +redirection must be for an HTTP(S) endpoint to be triggered via a simple HTTP +GET. As this endpoint is involved in every KYC check at the beginning, this +is also the place where we can integrate the payment process for the KYC fee. The specific KYC provider to be executed depends on the configuration (see below) which specifies a ``$PROVIDER_SECTION`` for each authentication procedure. -- cgit v1.2.3 From 7bdff12a38e5276dd5438013337fd2702a56597e Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Sun, 17 Mar 2024 12:17:15 +0100 Subject: update DD23 requirements --- design-documents/023-taler-kyc.rst | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/design-documents/023-taler-kyc.rst b/design-documents/023-taler-kyc.rst index 39a414e4..18f867bf 100644 --- a/design-documents/023-taler-kyc.rst +++ b/design-documents/023-taler-kyc.rst @@ -49,9 +49,11 @@ There are many different possible KYC/AML flows: * In-person validation by AML staff * Validation involving local authorities and post-office * Online validation + * Forms to be supplied by user * Interactive video * Documents to be supplied + * Forms to be filled by AML staff Additionally, the process is dynamic and conditional upon various decisions: @@ -89,6 +91,21 @@ disclosed). Proposed Solution ================= +We allow certain **conditions** to trigger a single specific **measures**. +For the different measures, we define: + +* Who has to do something (AML staff, user, nobody) +* The specific operational mode (normal, held on staff, held on user, frozen) + the account is to transition to +* What to show to the user (normal, information required, pending, etc.) +* For a user: + + * Web page template with instructions to render + * The check to run (if any) and measures on failure + * An external helper to run on success to determine the next measure + based on data provided in the measure + + Terminology ^^^^^^^^^^^ -- cgit v1.2.3 From e5cdc25062f0941d5ad9f8e4e8a3b2c6671abc68 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Sun, 17 Mar 2024 14:26:18 +0100 Subject: update DD23 requirements --- design-documents/023-taler-kyc.rst | 38 ++++++++++++++++++++++++++++++++------ 1 file changed, 32 insertions(+), 6 deletions(-) diff --git a/design-documents/023-taler-kyc.rst b/design-documents/023-taler-kyc.rst index 18f867bf..44275a94 100644 --- a/design-documents/023-taler-kyc.rst +++ b/design-documents/023-taler-kyc.rst @@ -81,13 +81,23 @@ Finally, we need to produce statistics: * number of risky business relationships (PEP, etc.) * begin/end-date of relationships (data retained for X years after end of relationship) +For this high-level monitoring, we need certain designated critical events to +be tracked in the system statistics: + + * account opened + * set to high risk + * set to low risk + * suspicious activity report filed with authority + * account frozen + * account unfrozen + * account closed + As a result, we largely end up in a large state machine where the AML staff has serious flexibiltiy while the user needs guidance as to the possible next moves and/or to the current state of their account (where some information must not be disclosed). - Proposed Solution ================= @@ -95,15 +105,29 @@ We allow certain **conditions** to trigger a single specific **measures**. For the different measures, we define: * Who has to do something (AML staff, user, nobody) -* The specific operational mode (normal, held on staff, held on user, frozen) +* The specific operational state (normal, held on staff, held on user, frozen) the account is to transition to -* What to show to the user (normal, information required, pending, etc.) -* For a user: +* Specification of required context inputs (w. templating, e.g. amount set dynamically) +* What state to show to the user (normal, information required, pending, etc.) +* For user-interactive states: * Web page template with instructions to render - * The check to run (if any) and measures on failure + * The check to set up (if any) and measure on failure * An external helper to run on success to determine the next measure - based on data provided in the measure + based on context and data provided in the measure + +* For (AML) staff-interactive states the UI provides the ability to: + + * file forms and upload documentation (without state transition) + * decide on next measure (providing context); here, the exchange needs + to expose the list of available measures and required context for each + +* Non-interactive measures (normal operation, account frozen) need: + + * Expiration time (in context) + * Measure to trigger upon expiration, again with context + (renew documents, resume normal operation, etc.) + Terminology @@ -123,6 +147,8 @@ Terminology * **Logic**: Logic refers to a specific bit of code (realized as an exchange plugin) that enables the interaction with a specific *provider*. Logic typically requires *configuration* for access control (such as an authorization token) and possibly the endpoint of the specific *provider* implementing the respective API. +* **Measure**: Describes the possible outgoing edges from one state in the state machine (including how to show the current state). + * **Provider**: A provider performs a specific set of *checks* at a certain *cost*. Interaction with a provider is performed by provider-specific *logic*. * **Type of operation**: The operation type determines which Taler-specific operation has triggered the KYC requirement. We support four types of operation: withdraw (by customer), deposit (by merchant), P2P receive (by wallet) and (high) wallet balance. -- cgit v1.2.3 From 201686c4372b1c163bdf860b9e0ea460727fa2b0 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Mon, 18 Mar 2024 12:09:10 +0100 Subject: more work on DD23 --- design-documents/023-taler-kyc.rst | 82 ++++++++++++++++++++++++-------------- 1 file changed, 51 insertions(+), 31 deletions(-) diff --git a/design-documents/023-taler-kyc.rst b/design-documents/023-taler-kyc.rst index 44275a94..21df9d43 100644 --- a/design-documents/023-taler-kyc.rst +++ b/design-documents/023-taler-kyc.rst @@ -19,7 +19,7 @@ Requirements The solution should support fees to be paid by the user for the KYC process (#7365). -Taler needs to run KYC checks in the following circumstances: +Taler needs to take *measures* based on the following primary *triggers*: * Customer withdraws money over a monthly threshold @@ -44,17 +44,22 @@ Taler needs to run KYC checks in the following circumstances: * key: reserve (=KYC account) long term public key per wallet (encoded as payto:// URI) -There are many different possible KYC/AML flows: +* Import of new sanctions lists and triggering of measures against matches of existing + customer records against the list + + +For the different *measures*, there are various different possible KYC/AML *checks* +that could happen: * In-person validation by AML staff +* Various forms to be filled by AML staff * Validation involving local authorities and post-office -* Online validation - - * Forms to be supplied by user +* Online validation, sometimes with multiple options (like KYC for multiple people): + + * Forms to be supplied by user (different types of ID) * Interactive video - * Documents to be supplied - -* Forms to be filled by AML staff + * Documents to be supplied (business register) + * Address validation (e-mail or phone or postal) Additionally, the process is dynamic and conditional upon various decisions: @@ -65,21 +70,26 @@ Additionally, the process is dynamic and conditional upon various decisions: * Need for plausibilization (via documents by user or staff research) * Periodic updates (of customer data, of sanction lists) and re-assessment -There are also various outcomes: +There are also various *outcomes*: -* normal operation -* normal operation but with AML staff investigating -* held, requesting customer documentation -* held, AML staff reviewing evidence +* normal operation (with expiration date) +* normal operation but with AML staff investigating (new measure) +* held, requesting customer documentation (new measure) +* held, AML staff reviewing evidence for plausibilization (new measure) * automatically frozen until certain day (due to sanctions) * institutionally frozen until certain day (due to order by state authority) +The outcome of a *check* can trigger further *measures* (including +expiration of the outcome state). + + Finally, we need to produce statistics: * number of incidents reported (voluntarily, required) * number of business relationships at any point in time * number of risky business relationships (PEP, etc.) -* begin/end-date of relationships (data retained for X years after end of relationship) +* number of frozen transactions (authority vs. sanction) with start-date and end-date +* start-data and end-date of relationships (data retained for X years after end of relationship) For this high-level monitoring, we need certain designated critical events to be tracked in the system statistics: @@ -101,26 +111,30 @@ disclosed). Proposed Solution ================= -We allow certain **conditions** to trigger a single specific **measures**. -For the different measures, we define: +We allow certain *conditions* to *trigger* a single specific *measures*. +For the different *measures*, we define: * Who has to do something (AML staff, user, nobody) -* The specific operational state (normal, held on staff, held on user, frozen) - the account is to transition to -* Specification of required context inputs (w. templating, e.g. amount set dynamically) -* What state to show to the user (normal, information required, pending, etc.) -* For user-interactive states: +* Contextual input data to be provided (with templating, e.g. amount set dynamically based on the *trigger*) +* A *check* to be performed +* A *program* that uses data from the *check* as well as *context* data + to determine an *outcome* which is the specific operational state + (normal, held on staff, held on user, frozen, etc.) the account is to transition to +* What information about the state to show to the user (normal, information required, pending, etc.) - * Web page template with instructions to render - * The check to set up (if any) and measure on failure - * An external helper to run on success to determine the next measure - based on context and data provided in the measure +* For user-interactive checks: -* For (AML) staff-interactive states the UI provides the ability to: + * Web page template with instructions to render (with either a form to fill or links to external checks); + here the context could provide an array of choices! + * Possibly an external check to set up (if any); for cost-reasons, we should only do one at a time, + and probably should then always redirect the browser to that check. + * A *measure* to take on failure of the external check - * file forms and upload documentation (without state transition) - * decide on next measure (providing context); here, the exchange needs - to expose the list of available measures and required context for each +* For (AML) staff-interactive checks: + + * UI to file forms and upload documentation (without state transition) + * UI to decide on next measure (providing context); here, the exchange needs + to expose the list of available *measures* and required *context* for each * Non-interactive measures (normal operation, account frozen) need: @@ -133,12 +147,14 @@ For the different measures, we define: Terminology ^^^^^^^^^^^ -* **Check**: A check establishes a particular attribute of a user, such as their name based on an ID document and lifeness, mailing address, phone number, taxpayer identity, etc. +* **Check**: A check establishes a particular attribute of a user, such as their name based on an ID document and lifeness, mailing address, phone number, taxpayer identity, etc. Checks may be given *context* (such as whether a customer is an individual or a business) to run correctly. Checks can also be AML staff inserting information for plausibilization. Checks result in an *outcome* being decided by an external AML *program*. * **Condition**: A condition specifies when KYC is required. Conditions include the *type of operation*, a threshold amount (e.g. above EUR:1000) and possibly a time period (e.g. over the last month). * **Configuration**: The configuration determines the *legitimization rules*, and specifies which providers offer which *checks* at what *cost*. +* **Context**: Context is information provided as input into a *check* and *program* to customize their execution. The context is initially set by the *trigger*, but may evolve as the *account* undergoes *measures*. For each *check* and *program*, the required *context* data must be specified. + * **Cost**: Metric for the business expense for a KYC check at a certain *provider*. Not in any currency, costs are simply relative and non-negative values. Costs are considered when multiple choices are allowed by the *configuration*. * **Expiration**: KYC legitimizations may be outdated. Expiration rules determine when *checks* have to be performed again. @@ -147,10 +163,14 @@ Terminology * **Logic**: Logic refers to a specific bit of code (realized as an exchange plugin) that enables the interaction with a specific *provider*. Logic typically requires *configuration* for access control (such as an authorization token) and possibly the endpoint of the specific *provider* implementing the respective API. -* **Measure**: Describes the possible outgoing edges from one state in the state machine (including how to show the current state). +* **Measure**: Describes the possible outgoing edges from one state in the state machine (including how to show the current state). Each edge is given some *context* and a *check* to be performed as well as a *program* to decide the *outcome* and the next *measure*. + +* **Outcome**: Describes the account state that an account ends up in due to the result of a *check*. Outcomes can be that an account is frozen (no transactions possible until freeze expires), held (no transactions possible until another *measure* has been taken), or operating normally. * **Provider**: A provider performs a specific set of *checks* at a certain *cost*. Interaction with a provider is performed by provider-specific *logic*. +* **Program**: An AML helper *program* is given *context* about the current state of an account and the data from a *check* to compute the *outcome*. For example, a *program* may look at the "PEP" field of a KYC check and decide if the outcome is to put the account into ``normal`` or ``held-for-manual-review`` state. A *program* operating on an AML form filed by AML staff will likely be trivial and directly apply the explicit decision taken by the staff member. + * **Type of operation**: The operation type determines which Taler-specific operation has triggered the KYC requirement. We support four types of operation: withdraw (by customer), deposit (by merchant), P2P receive (by wallet) and (high) wallet balance. -- cgit v1.2.3 From 621d7c1988bce77051c8230b1cbbc1dee21586c2 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Mon, 18 Mar 2024 13:06:23 +0100 Subject: more KYC thoughts --- design-documents/023-taler-kyc.rst | 82 +++++++++++++++++++++++++++++++------- 1 file changed, 68 insertions(+), 14 deletions(-) diff --git a/design-documents/023-taler-kyc.rst b/design-documents/023-taler-kyc.rst index 21df9d43..01e3ec7f 100644 --- a/design-documents/023-taler-kyc.rst +++ b/design-documents/023-taler-kyc.rst @@ -143,6 +143,46 @@ For the different *measures*, we define: (renew documents, resume normal operation, etc.) +We need some customer-driven interactivity in KYB/KYC process, for example the +user may need to be given choices (address vs. phone, individual vs. business, +order in which to provide KYC data of beneficiaries). As a result, the +exchange needs to serve some "master" page for measures where the user is +shown the next step(s) or choices (which person to collect KYC data on, +whether to run challenger on phone number of physical address, etc.). +That page should also potentially contain a form to allow the customer to +directly upload documents to us (like business registration) instead of to +some KYC provider. This is because KYC providers may not be flexible +enough. + +Similarly, the AML staff will need to be able to trigger rather complex +KYB/KYC processes, like "need KYC on X and Y and Z" or "phone number or +mailing address" or "please upload form A/T/S". Here in particular it +should be possible to request not only filled forms, but arbitrary +documents. + + +Documentation +^^^^^^^^^^^^^ + +* We must define risk-profile (902.4, 905.1) +* We must document the specific setup, likely not just the INI file +* We probably should have some key AMLA file attributes, such as: + + * File opened, file closed (keep data for X years afterwards!) + * low-risk or high-risk business relationship + * PEP status + * business domain + * authority notification dates (possibly multiple) with + voluntary or mandatory notification classification + +* There must be a page with an overview of AMLA files with opening + and closing dates and an easy way to determine for any day the + number of open AMLA files + +* Technically, we also need a list of at-risk transactions and of + frozen transactions, but given that we can really only freeze + on an account-basis, I think there is nothing to do here + Terminology ^^^^^^^^^^^ @@ -287,21 +327,14 @@ Configuration Options The configuration specifies a set of providers, one per configuration section: [kyc-provider-$PROVIDER_ID] -# How expensive is it to use this provider? -# Used to pick the cheapest provider possible. -COST = NUMBER # Which plugin is responsible for this provider? LOGIC = PLUGIN_NAME -# Which type of user does this provider handle? -# Either INDIVIDUAL or BUSINESS. -USER_TYPE = INDIVIDUAL -# Which checks does this provider provide? -# List of strings, no specific semantics. -PROVIDED_CHECKS = SMS GOVID PHOTO +# Which check does this provider provide? +PROVIDED_CHECK = SMS # Plus additional logic-specific options, e.g.: AUTHORIZATION_TOKEN = superdupersecret FORM_ID = business_legi_form -# How long is the check considered valid? +# How long is the data from this check considered valid? EXPIRATION = DURATION The configuration also specifies a set of legitimization @@ -312,10 +345,8 @@ requirements, one per configuration section: # Must be one of WITHDRAW, DEPOSIT, P2P-RECEIVE # or WALLET-BALANCE. OPERATION_TYPE = WITHDRAW -# Required checks to be performed. -# List of strings, must individually match the -# strings in one or more provider's PROVIDED_CHECKS. -REQUIRED_CHECKS = SMS GOVID +# Required measure to be performed. +REQUIRED_MEASURE = SWISSNESS # Threshold amount above which the legitimization is # triggered. The total must be exceeded in the given # timeframe. Can be 'forever'. @@ -326,6 +357,29 @@ THRESHOLD = AMOUNT TIMEFRAME = DURATION +Finally, the configuration specifies a set of measures, +one per configuration section: + +[aml-measure-$MEASURE_NAME] +# Program to run on the context and check data to +# determine the outcome and next measure. +PROGRAM = /bin/true +# Check to run as part of this measure. Optional. +CHECK = CHECK_NAME +# Form to show to the user as part of this measure. +FORM = FORM_NAME + +For each FORM_NAME, there then must be + +* A HTML template (Mustach) that is instantiated with the + JSON form context to produce a page to be shown to the user +* A helper program (named after the form) that can: + + * Generate a list of required context attributes + for the helper (!) + * Validate and convert an input JSON with context + attributes into the JSON form context + Exchange Database Schema ^^^^^^^^^^^^^^^^^^^^^^^^ -- cgit v1.2.3 From b924e099b65f9578d3012fe5969a4152c303e017 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Mon, 18 Mar 2024 23:08:59 +0100 Subject: spec updates for protocol v12, fixes #7948 --- core/api-merchant.rst | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) diff --git a/core/api-merchant.rst b/core/api-merchant.rst index c1bbf058..efc2d5b9 100644 --- a/core/api-merchant.rst +++ b/core/api-merchant.rst @@ -123,7 +123,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 **11**. + This specification corresponds to ``current`` protocol being version **12**. **Response:** @@ -1696,6 +1696,11 @@ Inspecting inventory This is used to return the list of all items in the inventory. + **Request:** + + :query limit: *Optional*. At most return the given number of results. Negative for descending by row ID, positive for ascending by row ID. Default is ``20``. Since protocol **v12**. + :query offset: *Optional*. Starting ``product_serial_id`` for an iteration. Since protocol **v12**. + **Response:** :http:statuscode:`200 OK`: @@ -1719,6 +1724,8 @@ Inspecting inventory // Product identifier, as found in the product. product_id: string; + // ``product_serial_id`` of the product in the database. + product_serial: integer; } @@ -2066,9 +2073,11 @@ Inspecting orders :query paid: *Optional*. If set to yes, only return paid orders, if no only unpaid orders. Do not give (or use "all") to see all orders regardless of payment status. :query refunded: *Optional*. If set to yes, only return refunded orders, if no only unrefunded orders. Do not give (or use "all") to see all orders regardless of refund status. :query wired: *Optional*. If set to yes, only return wired orders, if no only orders with missing wire transfers. Do not give (or use "all") to see all orders regardless of wire transfer status. - :query delta: *Optional*. takes value of the form ``N (-N)``, so that at most ``N`` values strictly older (younger) than ``start`` and ``date_s`` are returned. Defaults to ``-20`` to return the last 20 entries (before ``start`` and/or ``date_s``). + :query delta: *Optional*. takes value of the form ``N (-N)``, so that at most ``N`` values strictly older (younger) than ``start`` and ``date_s`` are returned. Defaults to ``-20`` to return the last 20 entries (before ``start`` and/or ``date_s``). Deprecated in protocol **v12**. Use *limit* instead. + :query limit: *Optional*. At most return the given number of results. Negative for descending by row ID, positive for ascending by row ID. Default is ``20``. Since protocol **v12**. :query date_s: *Optional.* Non-negative date in seconds after the UNIX Epoc, see ``delta`` for its interpretation. If not specified, we default to the oldest or most recent entry, depending on ``delta``. - :query start: *Optional*. Row number threshold, see ``delta`` for its interpretation. Defaults to ``INT64_MAX``, namely the biggest row id possible in the database. + :query start: *Optional*. Row number threshold, see ``delta`` for its interpretation. Defaults to ``INT64_MAX``, namely the biggest row id possible in the database. Deprecated in protocol **v12**. Use *offset* instead. + :query offset: *Optional*. Starting ``product_serial_id`` for an iteration. Since protocol **v12**. :query timeout_ms: *Optional*. Timeout in milliseconds to wait for additional orders if the answer would otherwise be negative (long polling). Only useful if delta is positive. Note that the merchant MAY still return a response that contains fewer than ``delta`` orders. :query session_id: *Optional*. Since protocol **v6**. Filters by session ID. :query fulfillment_url: *Optional*. Since protocol **v6**. Filters by fulfillment URL. -- cgit v1.2.3 From 6f68e4f3f922370763d8bafbbabdc13027c6a04f Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Mon, 18 Mar 2024 23:24:00 +0100 Subject: spec protocol v13 for #8638 --- core/api-merchant.rst | 24 +++++++++++++++++++++--- 1 file changed, 21 insertions(+), 3 deletions(-) diff --git a/core/api-merchant.rst b/core/api-merchant.rst index efc2d5b9..ef745dc2 100644 --- a/core/api-merchant.rst +++ b/core/api-merchant.rst @@ -123,7 +123,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 **12**. + This specification corresponds to ``current`` protocol being version **13**. **Response:** @@ -2895,9 +2895,27 @@ Adding templates // This parameter is optional. otp_id?: string; - // Additional information in a separate template. + // Fixed contract information for orders created from + // this template. template_contract: TemplateContractDetails; - } + + // Key-value pairs matching a subset of the + // fields from `template_contract` that are + // user-editable defaults for this template. + // Since protocol **v13**. + editable_defaults: Object; + + // Required currency for payments. Useful if no + // amount is specified in the `template_contract` + // but the user should be required to pay in a + // particular currency anyway. Merchant backends + // may reject requests if the `template_contract` + // or `editable_defaults` do + // specify an amount in a different currency. + // This parameter is optional. + // Since protocol **v13**. + required_currency?: string; + } .. ts:def:: TemplateContractDetails -- cgit v1.2.3 From b1ce4c8a16241c1819f1f76aa54b777c10ecea8c Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Mon, 18 Mar 2024 23:24:29 +0100 Subject: spec protocol v13 for #8638 -- optional argument --- core/api-merchant.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/core/api-merchant.rst b/core/api-merchant.rst index ef745dc2..2c44a570 100644 --- a/core/api-merchant.rst +++ b/core/api-merchant.rst @@ -2903,7 +2903,7 @@ Adding templates // fields from `template_contract` that are // user-editable defaults for this template. // Since protocol **v13**. - editable_defaults: Object; + editable_defaults?: Object; // Required currency for payments. Useful if no // amount is specified in the `template_contract` -- cgit v1.2.3 From ad973a639086ed1317f11881bae19fc4d124de09 Mon Sep 17 00:00:00 2001 From: Sebastian Date: Tue, 19 Mar 2024 12:28:11 -0300 Subject: fixing typo --- core/api-merchant.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/core/api-merchant.rst b/core/api-merchant.rst index 2c44a570..d9c6611f 100644 --- a/core/api-merchant.rst +++ b/core/api-merchant.rst @@ -592,7 +592,7 @@ are for incomplete payments for an order and never for established contracts. :http:statuscode:`200 OK`: The merchant accepted the request, and passed it on to the exchange. The body is a - a `merchant refund response `. Note that the exchange + a `abort response `. Note that the exchange MAY still have encountered errors in processing. Those will then be part of the body. Wallets MUST carefully consider errors for each of the coins as returned by the exchange. -- cgit v1.2.3 From 95056b563c0e60406af8835ec19f2d9d54c11bf0 Mon Sep 17 00:00:00 2001 From: Joel Häberli Date: Tue, 19 Mar 2024 20:30:23 +0100 Subject: docs: add withdrawal status to response --- core/api-nonce2ecash.rst | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/core/api-nonce2ecash.rst b/core/api-nonce2ecash.rst index 9e69e954..ad7c4997 100644 --- a/core/api-nonce2ecash.rst +++ b/core/api-nonce2ecash.rst @@ -127,6 +127,13 @@ operation (the ``WITHDRAWAL_ID``) to interact with the withdrawal operation and // Reserve public key generated by the wallet. // According to TALER_ReservePublicKeyP (https://docs.taler.net/core/api-common.html#cryptographic-primitives) reserve_pub_key: EddsaPublicKey; + + // Status of the withdrawal + // pending : the operation is pending parameters selection (exchange and reserve public key) + // selected : the operations has been selected and is pending confirmation + // aborted : the operation has been aborted + // confirmed: the transfer has been confirmed and registered by the bank + withdrawal_status: EddsaPublicKey; } .. http:post:: /withdrawal-operation/$WITHDRAWAL_ID -- cgit v1.2.3 From f6dfc9b3218e582511f6352180d0af86deac25ae Mon Sep 17 00:00:00 2001 From: Antoine A <> Date: Wed, 20 Mar 2024 12:31:40 +0100 Subject: Update corebank API --- core/api-corebank.rst | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/core/api-corebank.rst b/core/api-corebank.rst index 5a257257..afab932c 100644 --- a/core/api-corebank.rst +++ b/core/api-corebank.rst @@ -464,6 +464,14 @@ Account Management // Opaque unique ID used for pagination. // @since v4, will become mandatory in the next version. row_id?: Integer; + + // Current status of the account + // active: the account can be used + // deleted: the account has been deleted but is retained for compliance + // reasons, only the administrator can access it + // Default to 'active' is missing + // @since v4, will become mandatory in the next version. + status?: "active" | "deleted"; } .. _bank-account-info: -- cgit v1.2.3