From 21cb01c46c97903683a2706115ad59f84d49ebca Mon Sep 17 00:00:00 2001 From: Thien-Thi Nguyen Date: Thu, 21 Jan 2021 17:28:59 -0500 Subject: s/taler-exchange-keyup/taler-exchange-offline/ (four instances) --- manpages/taler-exchange-benchmark.1.rst | 2 +- manpages/taler-exchange-dbinit.1.rst | 2 +- manpages/taler-exchange-httpd.1.rst | 2 +- taler-developer-manual.rst | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/manpages/taler-exchange-benchmark.1.rst b/manpages/taler-exchange-benchmark.1.rst index 81b8e614..56710e5d 100644 --- a/manpages/taler-exchange-benchmark.1.rst +++ b/manpages/taler-exchange-benchmark.1.rst @@ -87,7 +87,7 @@ that table are always erased during a single benchmark run. See Also ======== -taler-exchange-dbinit(1), taler-exchange-keyup(1), taler-merchant-benchmark(1), +taler-exchange-dbinit(1), taler-exchange-offline(1), taler-merchant-benchmark(1), taler-exchange-httpd(1), taler.conf(5) Bugs diff --git a/manpages/taler-exchange-dbinit.1.rst b/manpages/taler-exchange-dbinit.1.rst index 8221b8e8..e2a5d4c9 100644 --- a/manpages/taler-exchange-dbinit.1.rst +++ b/manpages/taler-exchange-dbinit.1.rst @@ -58,7 +58,7 @@ Its options are as follows: See Also ======== -taler-exchange-httpd(1), taler-exchange-keyup(1), +taler-exchange-httpd(1), taler-exchange-offline(1), taler-exchange-reservemod(1), taler.conf(5). Bugs diff --git a/manpages/taler-exchange-httpd.1.rst b/manpages/taler-exchange-httpd.1.rst index d8462a6c..8cb4d4a1 100644 --- a/manpages/taler-exchange-httpd.1.rst +++ b/manpages/taler-exchange-httpd.1.rst @@ -111,7 +111,7 @@ SIGNALS See Also ======== -taler-exchange-dbinit(1), taler-exchange-keyup(1), +taler-exchange-dbinit(1), taler-exchange-offline(1), taler-exchange-reservemod(1), taler.conf(5). Bugs diff --git a/taler-developer-manual.rst b/taler-developer-manual.rst index ac258a5f..acbae6db 100644 --- a/taler-developer-manual.rst +++ b/taler-developer-manual.rst @@ -916,7 +916,7 @@ Naming conventions * logging * tools use their full name in GNUNET_log_setup - (i.e. 'taler-exchange-keyup') and log using plain 'GNUNET_log'. + (i.e. 'taler-exchange-offline') and log using plain 'GNUNET_log'. * pure libraries (without associated service) use 'GNUNET_log_from' with the component set to their library name (without lib or '.so'), which should also be their directory name (i.e. 'util') -- cgit v1.2.3 From c939bd1579a8ad97bb7937e130cc2ef90c6e233c Mon Sep 17 00:00:00 2001 From: Thien-Thi Nguyen Date: Thu, 21 Jan 2021 19:12:02 -0500 Subject: do s/\(taler\)-helper-crypto-\(rsa|eddsa\)/\1-exchange-secmod-\2/ (two instances) --- manpages/taler.conf.5.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/manpages/taler.conf.5.rst b/manpages/taler.conf.5.rst index 62875575..dc9dcb40 100644 --- a/manpages/taler.conf.5.rst +++ b/manpages/taler.conf.5.rst @@ -185,7 +185,7 @@ SECM_ESIGN_PUBKEY EXCHANGE RSA CRYPTO HELPER OPTIONS ---------------------------------- -The following options must be in the section "[taler-helper-crypto-rsa]". +The following options must be in the section "[taler-exchange-secmod-rsa]". LOOKAHEAD_SIGN How long do we generate denomination and signing keys ahead of time? @@ -214,7 +214,7 @@ configuration sections described below. EXCHANGE EDDSA CRYPTO HELPER OPTIONS ------------------------------------ -The following options must be in the section "[taler-helper-crypto-eddsa]". +The following options must be in the section "[taler-exchange-secmod-eddsa]". LOOKAHEAD_SIGN How long do we generate denomination and signing keys ahead of time? -- cgit v1.2.3 From 8dcdf846f429119109cd3c78e3da4e0e4806addb Mon Sep 17 00:00:00 2001 From: Thien-Thi Nguyen Date: Thu, 21 Jan 2021 23:49:09 -0500 Subject: tidy section ‘Serving’ MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - mark up ‘[exchange]’ - upcase and mark up each option - mark up ‘tcp’, ‘unix’ - downcase ‘is’ (where did that come from?!?) - downcase ‘mask’ --- taler-exchange-manual.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/taler-exchange-manual.rst b/taler-exchange-manual.rst index d9709e0f..d6dcc934 100644 --- a/taler-exchange-manual.rst +++ b/taler-exchange-manual.rst @@ -391,18 +391,18 @@ Serving The exchange can serve HTTP over both TCP and UNIX domain socket. -The following values are to be configured in the section [exchange]: +The following values are to be configured in the section ``[exchange]``: -- serve: must be set to tcp to serve HTTP over TCP, or unix to serve +- ``SERVE``: must be set to ``tcp`` to serve HTTP over TCP, or ``unix`` to serve HTTP over a UNIX domain socket -- port: Set to the TCP port to listen on if serve Is tcp. +- ``PORT``: Set to the TCP port to listen on if serve is ``tcp``. -- unixpath: set to the UNIX domain socket path to listen on if serve Is - unix +- ``UNIXPATH``: set to the UNIX domain socket path to listen on if serve is + ``unix`` -- unixpath_mode: number giving the mode with the access permission MASK - for the unixpath (i.e. 660 = rw-rw—-). +- ``UNIXPATH_MODE``: number giving the mode with the access permission mask + for the ``UNIXPATH`` (i.e. 660 = ``rw-rw---``). .. _Currency: -- cgit v1.2.3 From cbf961c716d15b397f9712ce4a2a0abdcfbb9ee8 Mon Sep 17 00:00:00 2001 From: Thien-Thi Nguyen Date: Thu, 21 Jan 2021 23:51:32 -0500 Subject: tidy section ‘Serving’ (cont'd) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - capitalize first word in sentence - at period at end of sentence --- taler-exchange-manual.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/taler-exchange-manual.rst b/taler-exchange-manual.rst index d6dcc934..ee745e44 100644 --- a/taler-exchange-manual.rst +++ b/taler-exchange-manual.rst @@ -393,15 +393,15 @@ The exchange can serve HTTP over both TCP and UNIX domain socket. The following values are to be configured in the section ``[exchange]``: -- ``SERVE``: must be set to ``tcp`` to serve HTTP over TCP, or ``unix`` to serve - HTTP over a UNIX domain socket +- ``SERVE``: Must be set to ``tcp`` to serve HTTP over TCP, or ``unix`` to serve + HTTP over a UNIX domain socket. - ``PORT``: Set to the TCP port to listen on if serve is ``tcp``. -- ``UNIXPATH``: set to the UNIX domain socket path to listen on if serve is - ``unix`` +- ``UNIXPATH``: Set to the UNIX domain socket path to listen on if serve is + ``unix``. -- ``UNIXPATH_MODE``: number giving the mode with the access permission mask +- ``UNIXPATH_MODE``: Number giving the mode with the access permission mask for the ``UNIXPATH`` (i.e. 660 = ``rw-rw---``). .. _Currency: -- cgit v1.2.3 From 9542aa619e076041e2bc2a046fe22ea9a1e5cbf3 Mon Sep 17 00:00:00 2001 From: Thien-Thi Nguyen Date: Thu, 21 Jan 2021 23:54:10 -0500 Subject: tidy section ‘Serving’ (cont'd) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - upcase ‘serve’, mark up - diction: s/values/options/ --- taler-exchange-manual.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/taler-exchange-manual.rst b/taler-exchange-manual.rst index ee745e44..d7c33139 100644 --- a/taler-exchange-manual.rst +++ b/taler-exchange-manual.rst @@ -391,14 +391,14 @@ Serving The exchange can serve HTTP over both TCP and UNIX domain socket. -The following values are to be configured in the section ``[exchange]``: +The following options are to be configured in the section ``[exchange]``: - ``SERVE``: Must be set to ``tcp`` to serve HTTP over TCP, or ``unix`` to serve HTTP over a UNIX domain socket. -- ``PORT``: Set to the TCP port to listen on if serve is ``tcp``. +- ``PORT``: Set to the TCP port to listen on if ``SERVE`` is ``tcp``. -- ``UNIXPATH``: Set to the UNIX domain socket path to listen on if serve is +- ``UNIXPATH``: Set to the UNIX domain socket path to listen on if ``SERVE`` is ``unix``. - ``UNIXPATH_MODE``: Number giving the mode with the access permission mask -- cgit v1.2.3 From 69d2095cbe5e5ad962a8dcd34d45371ac156343c Mon Sep 17 00:00:00 2001 From: Thien-Thi Nguyen Date: Thu, 21 Jan 2021 23:57:42 -0500 Subject: mark up ‘[taler]’ MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- taler-exchange-manual.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/taler-exchange-manual.rst b/taler-exchange-manual.rst index d7c33139..7d933c16 100644 --- a/taler-exchange-manual.rst +++ b/taler-exchange-manual.rst @@ -410,7 +410,7 @@ Currency -------- The exchange supports only one currency. This data is set under the -respective option ``CURRENCY`` in section [taler]. +respective option ``CURRENCY`` in section ``[taler]``. .. _Database: -- cgit v1.2.3 From 95a97c6addb282026e6c5bfd4de2c0c4214b229e Mon Sep 17 00:00:00 2001 From: Thien-Thi Nguyen Date: Thu, 21 Jan 2021 23:59:13 -0500 Subject: mark up ‘[exchangedb-BACKEND]’ MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- taler-exchange-manual.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/taler-exchange-manual.rst b/taler-exchange-manual.rst index 7d933c16..530da4b0 100644 --- a/taler-exchange-manual.rst +++ b/taler-exchange-manual.rst @@ -424,7 +424,7 @@ choosing the backend, it is mandatory to supply the connection string - via an environment variable: TALER_EXCHANGEDB_POSTGRES_CONFIG. -- via configuration option CONFIG, under section [exchangedb-BACKEND]. +- via configuration option CONFIG, under section ``[exchangedb-BACKEND]``. For example, the demo exchange is configured as follows: .. code-block:: ini -- cgit v1.2.3 From f5fd956d4fc343c920815c8901a7e9040bd160df Mon Sep 17 00:00:00 2001 From: Thien-Thi Nguyen Date: Thu, 21 Jan 2021 23:59:36 -0500 Subject: mark up ‘TALER_EXCHANGEDB_POSTGRES_CONFIG’ MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- taler-exchange-manual.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/taler-exchange-manual.rst b/taler-exchange-manual.rst index 530da4b0..7982dd36 100644 --- a/taler-exchange-manual.rst +++ b/taler-exchange-manual.rst @@ -422,7 +422,7 @@ exchange is going to use. So far, only ``db = postgres`` is supported. After choosing the backend, it is mandatory to supply the connection string (namely, the database name). This is possible in two ways: -- via an environment variable: TALER_EXCHANGEDB_POSTGRES_CONFIG. +- via an environment variable: ``TALER_EXCHANGEDB_POSTGRES_CONFIG``. - via configuration option CONFIG, under section ``[exchangedb-BACKEND]``. For example, the demo exchange is configured as follows: -- cgit v1.2.3 From 89c78648167f69d1b256d1de7c2e71495929c950 Mon Sep 17 00:00:00 2001 From: Thien-Thi Nguyen Date: Thu, 21 Jan 2021 23:59:46 -0500 Subject: mark up ‘CONFIG’ MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- taler-exchange-manual.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/taler-exchange-manual.rst b/taler-exchange-manual.rst index 7982dd36..e104cc0e 100644 --- a/taler-exchange-manual.rst +++ b/taler-exchange-manual.rst @@ -424,7 +424,7 @@ choosing the backend, it is mandatory to supply the connection string - via an environment variable: ``TALER_EXCHANGEDB_POSTGRES_CONFIG``. -- via configuration option CONFIG, under section ``[exchangedb-BACKEND]``. +- via configuration option ``CONFIG``, under section ``[exchangedb-BACKEND]``. For example, the demo exchange is configured as follows: .. code-block:: ini -- cgit v1.2.3 From d80f3acbbfad16dc3a03d2d1ca380bdf1996f335 Mon Sep 17 00:00:00 2001 From: Thien-Thi Nguyen Date: Fri, 22 Jan 2021 00:11:00 -0500 Subject: tidy section ‘Terms of service’ MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - mark up ‘[exchange]’ - mark up ‘TERMS_ETAG’ - mark up ‘TERMS_DIR’ - fix typo: s/an HTML/an HTML format/ - change markup of filename from " to `` --- taler-exchange-manual.rst | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/taler-exchange-manual.rst b/taler-exchange-manual.rst index e104cc0e..3e375bf0 100644 --- a/taler-exchange-manual.rst +++ b/taler-exchange-manual.rst @@ -560,26 +560,26 @@ if none are configured, the exchange will return a simple statement saying that there are no terms of service available. To configure the terms of service response, there are two options -in the [exchange] section: +in the ``[exchange]`` section: -- TERMS_ETAG: The current "Etag" to return for the terms of service. +- ``TERMS_ETAG``: The current "Etag" to return for the terms of service. This value must be changed whenever the terms of service are updated. A common value to use would be a version number. - Note that if you change the TERMS_ETAG, you MUST also provide - the respective files in TERMS_DIR (see below). -- TERMS_DIR: The directory that contains the terms of service. + Note that if you change the ``TERMS_ETAG``, you MUST also provide + the respective files in ``TERMS_DIR`` (see below). +- ``TERMS_DIR``: The directory that contains the terms of service. The files in the directory must be readable to the exchange process. -The TERMS_DIR directory structure must follow a particular layout. -First, inside of TERMS_DIR, there should be sub-directories using +The ``TERMS_DIR`` directory structure must follow a particular layout. +First, inside of ``TERMS_DIR``, there should be sub-directories using two-letter language codes like "en", "de", or "jp". Each of these directories would then hold translations of the current terms of service into the respective language. Empty directories are permitted in case translations are not available. Then, inside each language directory, files with the name of the -value set as the TERMS_ETAG must be provided. The extension of +value set as the ``TERMS_ETAG`` must be provided. The extension of each of the files should be typical for the respective mime type. The set of supported mime types is currently hard-coded in the exchange, and includes HTML, PDF and TXT files. If other files are @@ -588,7 +588,7 @@ present, the exchange may show a warning on startup. Example ^^^^^^^ -A sample file structure for a TERMS_ETAG of "v1" would be: +A sample file structure for a ``TERMS_ETAG`` of "v1" would be: - TERMS_DIR/en/v1.txt - TERMS_DIR/en/v1.html @@ -598,8 +598,8 @@ A sample file structure for a TERMS_ETAG of "v1" would be: - TERMS_DIR/de/v1.pdf - TERMS_DIR/fr/v1.pdf -If the user requests an HTML with language preferences "fr" followed by "en", -the exchange would return "TERMS_DIR/en/v1.html" lacking an HTML version in +If the user requests an HTML format with language preferences "fr" followed by "en", +the exchange would return ``TERMS_DIR/en/v1.html`` lacking an HTML version in French. -- cgit v1.2.3 From 50b3023f6a1d794e284fce019540356f541b8412 Mon Sep 17 00:00:00 2001 From: Florian Dold Date: Sat, 23 Jan 2021 20:51:39 +0100 Subject: fix Debian instructions --- frags/installing-debian.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/frags/installing-debian.rst b/frags/installing-debian.rst index 3c6cac6e..2c36e98a 100644 --- a/frags/installing-debian.rst +++ b/frags/installing-debian.rst @@ -41,7 +41,7 @@ into your keyring and update the package lists: .. code-block:: console - # wget -O - https://taler.net/taler-systems.gpg.key | apt-sign add - + # wget -O - https://taler.net/static/taler-systems.gpg.key | apt-key add - # apt update .. note:: -- cgit v1.2.3 From f63f4cea078f26fd5a371762e7da960c1d6794a0 Mon Sep 17 00:00:00 2001 From: Florian Dold Date: Sun, 24 Jan 2021 14:12:00 +0100 Subject: reference developer manual correctly --- index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.rst b/index.rst index 1a4d56c5..e6893db2 100644 --- a/index.rst +++ b/index.rst @@ -60,7 +60,7 @@ Documentation Overview taler-bank-manual taler-backoffice-manual taler-auditor-manual - developers-manual.rst + taler-developer-manual.rst design-documents/index anastasis libeufin/index -- cgit v1.2.3 From e39a7196e91cfeac1b93c00d22161ffd6f07434a Mon Sep 17 00:00:00 2001 From: Florian Dold Date: Sun, 24 Jan 2021 14:29:25 +0100 Subject: debian instructions --- libeufin/nexus-tutorial.rst | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/libeufin/nexus-tutorial.rst b/libeufin/nexus-tutorial.rst index 6ef78829..95c2e76c 100644 --- a/libeufin/nexus-tutorial.rst +++ b/libeufin/nexus-tutorial.rst @@ -19,6 +19,28 @@ steps in "Setting up the Sandbox". Installing LibEuFin =================== +.. warning:: + + LibEuFin does not yet ship with any systemd unit files. + + There is an `open bug report `__ + for this issue. + + +Installation on Debian +---------------------- + +.. include:: ../frags/installing-debian.rst + +To install LibEuFin, you can now simply run: + +.. code-block:: console + + # apt install libeufin + +Run-time dependencies +--------------------- + LibEuFin has the following run-time dependencies: * OpenJDK 11 @@ -26,6 +48,9 @@ LibEuFin has the following run-time dependencies: * python3-click (can be installed via ``pip3 install click``) * python3-requests (can be installed via ``pip3 install requests``) +These dependencies only need to be installed manually when building from source +or using the prebuilt binaries. + Downloading prebuilt binaries ----------------------------- -- cgit v1.2.3 From ce6f02324134436a5ddb5875ca1259a66168e135 Mon Sep 17 00:00:00 2001 From: Florian Dold Date: Sun, 24 Jan 2021 15:20:21 +0100 Subject: add wallet CLI manual --- index.rst | 3 +- taler-wallet-cli-manual.rst | 136 ++++++++++++++++++++++++++++++++++++++++++++ taler-wallet.rst | 4 +- 3 files changed, 140 insertions(+), 3 deletions(-) create mode 100644 taler-wallet-cli-manual.rst diff --git a/index.rst b/index.rst index e6893db2..94862209 100644 --- a/index.rst +++ b/index.rst @@ -53,7 +53,7 @@ Documentation Overview core/index taler-exchange-manual taler-merchant-manual - taler-wallet + taler-wallet-cli-manual taler-nfc-guide.rst taler-merchant-api-tutorial taler-merchant-pos-terminal @@ -61,6 +61,7 @@ Documentation Overview taler-backoffice-manual taler-auditor-manual taler-developer-manual.rst + taler-wallet design-documents/index anastasis libeufin/index diff --git a/taler-wallet-cli-manual.rst b/taler-wallet-cli-manual.rst new file mode 100644 index 00000000..8007f6b0 --- /dev/null +++ b/taler-wallet-cli-manual.rst @@ -0,0 +1,136 @@ +GNU Taler Wallet CLI Manual +########################### + +This manual describes how to use the GNU Taler wallet command line +interface (CLI). + +The the wallet CLI is targeted at developers and operators, but not meant to be +used by customers. It exposes all functionality that the more user-friendly +interfaces (Android app, browser extension) offer. However, it provides more +diagnostics and advanced features as well. + +Installation +------------ + +The easiest way to install the wallet is via NPM. Note that a recent version of +Node.JS (``>=12.20.1``) is required. + +We recommend to install the wallet package on a per-user basis. +To do so, configure node and adjust your ``$PATH``: + +.. code-block:: console + + $ npm set prefix $HOME/.npm-global + $ export PATH=$HOME/.npm-global:$PATH + +Now the wallet CLI can be installed without requiring elevated permissions: + +.. code-block:: console + + $ npm set prefix $HOME/.npm-global + + +Getting Help +------------ + +The wallet CLI comes with built-in help. Invoke the wallet CLI (or any subcommand) with the ``--help`` flag to get help: + +.. code-block:: console + + $ taler-wallet-cli --help + Usage: taler-wallet-cli COMMAND + + Command line interface for the GNU Taler wallet. + + Options: + -h, --help Show this message and exit. + --wallet-db=VALUE location of the wallet database file + --timetravel=VALUE modify system time by given offset in microseconds + --inhibit=VALUE Inhibit running certain operations, useful for debugging and testing. + --no-throttle Don't do any request throttling. + -v, --version + -V, --verbose Enable verbose output. + + Commands: + advanced Subcommands for advanced operations (only use if you know what you're doing!). + api Call the wallet-core API directly. + backup Subcommands for backups + balance Show wallet balance. + deposit Subcommands for depositing money to payto:// accounts + exchanges Manage exchanges. + handle-uri Handle a taler:// URI. + pending Show pending operations. + run-pending Run pending operations. + run-until-done Run until no more work is left. + testing Subcommands for testing GNU Taler deployments. + transactions Show transactions. + +Completing operations +--------------------- + +Note that the CLI does not run as a background daemon. When starting +operations that don't immediately finish, the wallet needs to be run explicitly +to finish any pending tasks: + + +.. code-block:: console + + # Do one attempt to finish all pending operations + $ taler-wallet-cli run-pending + + # Run until all work is done + $ taler-wallet-cli run-until-done + +Resetting the wallet +-------------------- + +The wallet can be reset by deleting its database file. By default, the database file +is ``$HOME/.talerwalletdb.json``. + + +Handling taler:// URIs +---------------------- + +Many interactions with the Taler wallet happen by scanning QR codes or special +headers on Websites. To emulate this with the command line interface, run the following +command: + +.. code-block:: console + + $ taler-wallet-cli handle-uri $URI + + +Testing an exchange deployment +------------------------------ + +The following series of commands can be used to check that an exchange deployment +is functional: + +.. code-block:: console + + # This will now output a payto URI that money needs to be sent to in order to allow withdrawal + # of taler coins + $ taler-wallet-cli advanced withdraw-manually --exchange $EXCHANGE_URL --amount EUR:10.50 + + # Show the status of the manual withdrawal operation + $ taler-wallet-cli transactions + + # Once the transfer has been made, try completing the withdrawal + $ taler-wallet-cli run-pending + + # Check status of transactions and show balance + $ taler-wallet-cli transactions + $ taler-wallet-cli balance + + # Now, directly deposit coins with the exchange into a target account + # (Usually, a payment is made via a merchant. The wallet provides + # this functionality for testing.) + $ taler-wallet-cli deposit create EUR:5 payto://sepa/$IBAN + + # Check if transaction was successful. + # (If not, fix issue with exchange and run "run-pending" command again) + $ taler-wallet-cli transactions + + # The wallet can also track if the exchange wired the money to the merchant account. + # The "deposit group id" can be found in the output of the transactions list. + $ taler-wallet-cli deposit track $DEPOSIT_GROUP_ID diff --git a/taler-wallet.rst b/taler-wallet.rst index f5784a22..a87ee09c 100644 --- a/taler-wallet.rst +++ b/taler-wallet.rst @@ -1,5 +1,5 @@ -GNU Taler Wallet Manual -####################### +GNU Taler Wallet Developer Manual +################################# The GNU Taler wallet allows customers to withdraw and spend digital cash. -- cgit v1.2.3 From d27be298fbbc186fc2c96d5ad74a74c557603051 Mon Sep 17 00:00:00 2001 From: Florian Dold Date: Sun, 24 Jan 2021 16:04:41 +0100 Subject: mention caveats --- libeufin/nexus-tutorial.rst | 20 ++++++++++++++++---- 1 file changed, 16 insertions(+), 4 deletions(-) diff --git a/libeufin/nexus-tutorial.rst b/libeufin/nexus-tutorial.rst index 95c2e76c..1e3deb9f 100644 --- a/libeufin/nexus-tutorial.rst +++ b/libeufin/nexus-tutorial.rst @@ -190,10 +190,21 @@ Use the following command to run the nexus service: $ libeufin-nexus serve --port 5001 By default, the SQLite3 database ``/tmp/libeufin-nexus.sqlite3`` will be used. +The database can be specified as a JDBC connection URI with the +``--db-conn-string=$DBCONN`` option. Only *SQLite* and *PostgreSQL (only via +TCP)* are supported right now. + +.. warning:: + + For production-grade deployments of LibEuFin, we do not recommend specifying the + secret database credentials via command line arguments, as can will expose + those credentials to other users. + + Instead, the DB connection string should be specified in an environment variable + (which can be set in the systemd unit via an ``EnvironmentFile`` option) + once LibEuFin supports this (see the corresponding + `bug tracker entry `__). -We recommend using the ``--db-conn-string=$DBCONN`` option. It instructs Nexus -to reach the database addressed by the JDBC connection URI. Only *SQLite* and -*PostgreSQL (only via TCP)* are supported right now. For example: @@ -212,7 +223,8 @@ to create less privileged users is offered. .. note:: - Privilege separation is not fully implemented yet. + User and permissions management in LibEuFin is still under development. + In particular, permissions for non-superusers are very limited at the moment. The command line interface needs the following three values to be defined in the environment: ``LIBEUFIN_NEXUS_URL``, ``LIBEUFIN_NEXUS_USERNAME``, -- cgit v1.2.3 From 1a34d067d2b6c4d96ffb438ecc7ca3cd78913d91 Mon Sep 17 00:00:00 2001 From: Florian Dold Date: Sun, 24 Jan 2021 16:10:57 +0100 Subject: language / formatting --- libeufin/nexus-tutorial.rst | 70 +++++++++++++++++---------------------------- 1 file changed, 27 insertions(+), 43 deletions(-) diff --git a/libeufin/nexus-tutorial.rst b/libeufin/nexus-tutorial.rst index 1e3deb9f..c00b9d4e 100644 --- a/libeufin/nexus-tutorial.rst +++ b/libeufin/nexus-tutorial.rst @@ -317,10 +317,10 @@ step is needed to let the user pick a custom name for such accounts. connections \ import-bank-account \ --offered-account-id testacct01 \ - --nexus-bank-account-id $CUSTOM_RENAMING_FOR_ACCOUNT \ + --nexus-bank-account-id $LOCAL_ACCOUNT_NAME \ $CONNECTION_NAME -Once a Nexus user imported a bank account (``$CUSTOM_RENAMING_FOR_ACCOUNT``) +Once a Nexus user imported a bank account (``$LOCAL_ACCOUNT_NAME``) under a certain connection (``$CONNECTION_NAME``), it is possible to accomplish the usual operations for any bank account: asking for the list of transactions, and making a payment. @@ -328,22 +328,16 @@ list of transactions, and making a payment. Request history of transactions =============================== -.. +The LibEuFin nexus keeps a local copy of the bank account's transaction +history. Before querying transactions locally, it is necessary +to request transactions for the bank account via the bank connection. - FIXME: explain why requesting the history - goes through these two-phases. - -It is first needed to tell Nexus to download the latest news -from the bank, and then ask it again to return the results. - -This command asks Nexus to *download the latest bank statements*: +This command asks Nexus to download the latest transaction reports/statements +through the bank connection: .. code-block:: console - $ libeufin-cli \ - accounts \ - fetch-transactions \ - $CUSTOM_RENAMING_FOR_ACCOUNT + $ libeufin-cli accounts fetch-transactions $LOCAL_ACCOUNT_NAME .. note:: @@ -353,36 +347,32 @@ This command asks Nexus to *download the latest bank statements*: reports). Once Nexus stored all the information in the database, the -client can ask to actually **see** the transactions: +client can ask to actually see the transactions: .. code-block:: console - $ libeufin-cli accounts \ - transactions \ - $CUSTOM_RENAMING_FOR_ACCOUNT + $ libeufin-cli accounts transactions $LOCAL_ACCOUNT_NAME Make a payment ============== -.. +Payments pass through two phases: preparation and submission. The preparation +phase assigns the payment initiation a unique ID, which prevents accidental +double submissions of payments in case of network failures or other +disruptions. - FIXME: explain why payments go through these two-phases. - -Payments pass through two phases: preparation and submission. The following command prepares a payment: .. code-block:: console - $ libeufin-cli \ - accounts \ - prepare-payment \ + $ libeufin-cli accounts prepare-payment \ --creditor-iban $IBAN_TO_SEND_MONEY_TO \ --creditor-bic $BIC_TO_SEND_MONEY_TO \ --creditor-name $CREDITOR_NAME \ --payment-amount $AMOUNT \ --payment-subject $SUBJECT \ - $CUSTOM_RENAMING_FOR_ACCOUNT + $LOCAL_ACCOUNT_NAME Note: the ``$AMOUNT`` value needs the format ``X.Y:CURRENCY``; for example ``10:EUR``, or ``1.01:EUR``. @@ -393,11 +383,9 @@ in the next step, to **send the payment instructions to the bank**: .. code-block:: console - $ libeufin-cli \ - accounts \ - submit-payment \ - --payment-uuid $UUID \ - $CUSTOM_RENAMING_FOR_ACCOUNT + $ libeufin-cli accounts submit-payment \ + --payment-uuid $UUID \ + $LOCAL_ACCOUNT_NAME Automatic scheduling ==================== @@ -452,12 +440,10 @@ INI and HIA secret keys will be restored for the requesting user. .. code-block:: console - $ libeufin-cli \ - connection \ - restore-backup \ - --passphrase $SECRET \ - --backup-file $BACKUP_FILE \ - $CONNECTION_NAME + $ libeufin-cli connection \ restore-backup + --passphrase $SECRET \ + --backup-file $BACKUP_FILE \ + $CONNECTION_NAME Creating a Taler facade ======================= @@ -473,12 +459,10 @@ existing bank account / connection pair. .. code-block:: console - $ libeufin-cli \ - facades \ - new-facade \ - --facade-name $FACADE_NAME \ - $CONNECTION_NAME \ - $CUSTOM_RENAMING_FOR_ACCOUNT + $ libeufin-cli facades new-facade \ + --facade-name $FACADE_NAME \ + $CONNECTION_NAME \ + $LOCAL_ACCOUNT_NAME At this point, the additional *taler-wire-gateway* (FIXME: link here to API here) API becomes offered by the Nexus. The purpose -- cgit v1.2.3 From 0fed8caec0e78b81d5505332da2d2cde0e553e50 Mon Sep 17 00:00:00 2001 From: Florian Dold Date: Sun, 24 Jan 2021 16:21:16 +0100 Subject: reference wallet manual --- taler-exchange-manual.rst | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/taler-exchange-manual.rst b/taler-exchange-manual.rst index 3e375bf0..7d6703a2 100644 --- a/taler-exchange-manual.rst +++ b/taler-exchange-manual.rst @@ -906,6 +906,14 @@ of ``taler-exchange-offline``. under highly unusual (“emergency”) conditions and not in normal operation. +Testing a deployment +==================== + +We recommend testing whether an exchange deployment is functional by using the +Taler wallet command line interface. The tool can be used to withdraw and +deposit electronic cash via the exchange without having to deploy and operate a +separate merchant backend and storefront. For more information, see +:doc:`taler-wallet-cli-manual`. .. _Diagnostics: -- cgit v1.2.3 From 678c18fed256b70f45c47540b7ad12ed10c9286a Mon Sep 17 00:00:00 2001 From: Thien-Thi Nguyen Date: Sun, 24 Jan 2021 20:48:07 -0500 Subject: replace ‘code-block:: console’ w/ :ref: MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit background: --- taler-merchant-manual.rst | 11 ++--------- 1 file changed, 2 insertions(+), 9 deletions(-) diff --git a/taler-merchant-manual.rst b/taler-merchant-manual.rst index e038d607..283512d5 100644 --- a/taler-merchant-manual.rst +++ b/taler-merchant-manual.rst @@ -1498,15 +1498,8 @@ Note that the public key must match the exchange's private key and that the Postgres database must exist before launching the benchmark. You also will need to ensure that the Exchange's -details are setup, usually by running - -.. code-block:: console - - $ taler-exchange-wire -c $CONFIG_FILE - $ taler-exchange-keyup -c $CONFIG_FILE - -where "$CONFIG_FILE" should be replaced by -the configuration file that is to be used. +details are setup. +For details, see the :ref:`Exchange Operator Manual `. Running the benchmark command -- cgit v1.2.3