diff options
Diffstat (limited to 'taler-wallet.rst')
| -rw-r--r-- | taler-wallet.rst | 273 |
1 files changed, 254 insertions, 19 deletions
diff --git a/taler-wallet.rst b/taler-wallet.rst index 5dc47c5f..4a975340 100644 --- a/taler-wallet.rst +++ b/taler-wallet.rst @@ -1,18 +1,78 @@ -GNU Taler Wallet Developer 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 <http://www.gnu.org/licenses/> + + +Wallet Manual +############# The GNU Taler wallet allows customers to withdraw and spend digital cash. +.. contents:: Table of Contents + :depth: 1 + :local: + + +WebExtension Wallet +=================== + +Building from source +-------------------- + +.. code-block:: console + + $ git clone https://git.taler.net/wallet-core.git + $ cd wallet-core + $ ./configure + $ make webex-stable + # Packaged extension now available as: + # dist/taler-wallet-$VERSION.zip + + +Android Wallet +============== + +Please see :ref:`Build-apps-from-source` in the :doc:`taler-developer-manual`. + + +iOS Wallet +========== + +Please see :ref:`Build-iOS-from-source` in the :doc:`taler-developer-manual`. + .. _command-line-wallet: Command-line Wallet =================== -The command-line wallet is used primarily for testing by developers. +This section 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. Building from source -------------------- +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, +thus setting ``$INSTALL_PREFIX`` to a directory in ``$HOME``. + .. code-block:: console $ git clone https://git.taler.net/wallet-core.git @@ -52,8 +112,78 @@ To use the wallet as a library in your own project, run: $ npm install taler-wallet +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 + + Manual withdrawing -================== +------------------ .. code-block:: console @@ -61,26 +191,132 @@ Manual withdrawing --exchange https://exchange.eurint.taler.net/ \ --amount EUR:5 -WebExtension Wallet + +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 +------------------------------ + +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://iban/$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 + +.. _withdraw-simulation: + + +Paying for an order =================== -Building from source --------------------- +.. 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 - $ git clone https://git.taler.net/wallet-core.git - $ cd wallet-core - $ ./configure - $ make webex-stable - # Packaged extension now available as: - # dist/taler-wallet-$VERSION.zip + $ 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. -Android Wallet -============== -Please see :ref:`Build-apps-from-source` in the :doc:`taler-developer-manual`. APIs and Data Formats @@ -103,7 +339,7 @@ following envelope: export interface WalletSuccess { type: "response"; - operation: string, + operation: string; // ID to correlate success response to request id: string; // Result type depends on operation @@ -114,7 +350,7 @@ following envelope: export interface WalletError { type: "error"; - operation: string, + operation: string; // ID to correlate error response to request id: string; error: WalletErrorInfo; @@ -262,7 +498,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 tipping (accepting/refusing a tip) * Test refunds * Test for :ref:`session-based payments <repurchase>` * Test case for auto-refunds |