summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
Diffstat
-rw-r--r--frags/installing-debian.rst2
-rw-r--r--index.rst3
-rw-r--r--libeufin/nexus-tutorial.rst115
-rw-r--r--manpages/taler-exchange-benchmark.1.rst2
-rw-r--r--manpages/taler-exchange-dbinit.1.rst2
-rw-r--r--manpages/taler-exchange-httpd.1.rst2
-rw-r--r--manpages/taler.conf.5.rst4
-rw-r--r--taler-developer-manual.rst2
-rw-r--r--taler-exchange-manual.rst52
-rw-r--r--taler-merchant-manual.rst11
-rw-r--r--taler-wallet-cli-manual.rst136
-rw-r--r--taler-wallet.rst4
12 files changed, 247 insertions, 88 deletions
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::
diff --git a/index.rst b/index.rst
index c64f8c85..5fa291f8 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
+ taler-wallet
design-documents/index
anastasis
libeufin/index
diff --git a/libeufin/nexus-tutorial.rst b/libeufin/nexus-tutorial.rst
index 6ef78829..c00b9d4e 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 <https://bugs.gnunet.org/view.php?id=6719>`__
+ 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
-----------------------------
@@ -165,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 <https://bugs.gnunet.org/view.php?id=6720>`__).
-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:
@@ -187,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``,
@@ -280,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.
@@ -291,22 +328,16 @@ list of transactions, and making a payment.
Request history of transactions
===============================
-..
-
- FIXME: explain why requesting the history
- goes through these two-phases.
+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.
-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::
@@ -316,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
==============
-..
-
- FIXME: explain why payments go through these two-phases.
+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.
-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``.
@@ -356,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
====================
@@ -415,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
=======================
@@ -436,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
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/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?
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')
diff --git a/taler-exchange-manual.rst b/taler-exchange-manual.rst
index b7935fb7..a2cab433 100644
--- a/taler-exchange-manual.rst
+++ b/taler-exchange-manual.rst
@@ -412,18 +412,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 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
+- ``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:
@@ -431,7 +431,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:
@@ -443,9 +443,9 @@ 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].
+- via configuration option ``CONFIG``, under section ``[exchangedb-BACKEND]``.
For example, the demo exchange is configured as follows:
.. code-block:: ini
@@ -581,26 +581,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
@@ -609,7 +609,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
@@ -619,8 +619,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.
@@ -927,6 +927,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:
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 <Bank-account>`.
Running the benchmark command
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.
generated by cgit v1.2.3 (git 2.39.1) at 2024-04-26 22:36:59 +0000