commit 81ee10ef93970023629db892302a13cd6ebfb8f4
parent 60a0f8c282416130ab8bf15b2f4187fe9e690db9
Author: Florian Dold <florian@dold.me>
Date: Mon, 28 Apr 2025 23:09:55 +0200
wallet docs: cleanup, dev experiments
Diffstat:
| M | taler-wallet.rst | | | 166 | ++++++++++++++++++++++++------------------------------------------------------- |
1 file changed, 50 insertions(+), 116 deletions(-)
diff --git a/taler-wallet.rst b/taler-wallet.rst
@@ -14,8 +14,8 @@
TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
-Wallet Manual
-#############
+Wallet Developer Manual
+#######################
The GNU Taler wallet allows customers to withdraw and spend digital cash.
@@ -167,7 +167,7 @@ Resetting the wallet
--------------------
The wallet can be reset by deleting its database file. By default, the database file
-is ``$HOME/.talerwalletdb.json``.
+is ``$HOME/.talerwalletdb.sqlite3``.
Handling taler:// URIs
@@ -274,50 +274,6 @@ 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.
-
-
-
-
APIs and Data Formats
=====================
@@ -415,7 +371,7 @@ Integration Test Example
------------------------
Integration tests can be done with the low-level wallet commands. To select which coins and denominations
-to use, the wallet can dump the coins in an easy-to-process format (`CoinDumpJson <https://git.taler.net/wallet-core.git/tree/src/types/talerTypes.ts#n734>`__).
+to use, the wallet can dump the coins in an easy-to-process format (`CoinDumpJson <https://git.taler.net/taler-typescript-core.git/tree/packages/taler-util/src/types-taler-wallet.ts#n613>`__).
The database file for the wallet can be selected with the ``--wallet-db``
option. This option must be passed to the ``taler-wallet-cli`` command and not
@@ -426,12 +382,12 @@ The following example does a simple withdrawal recoup:
.. code-block:: console
# Withdraw digital cash
- $ taler-wallet-cli --wallet-db=mydb.json testing withdraw \
+ $ taler-wallet-cli --wallet-db=mydb.sqlite3 testing withdraw \
-b https://bank.int.taler.net/ \
-e https://exchange.int.taler.net/ \
-a INTKUDOS:10
- $ coins=$(taler-wallet-cli --wallet-db=mydb.json advanced dump-coins)
+ $ coins=$(taler-wallet-cli --wallet-db=mydb.sqlite3 advanced dump-coins)
# Find coin we want to revoke
$ rc=$(echo "$coins" | \
@@ -450,29 +406,29 @@ The following example does a simple withdrawal recoup:
$ taler-deployment-restart
# Now we suspend the other coins, so later we will pay with the recouped coin
- $ taler-wallet-cli --wallet-db=mydb.json advanced suspend-coins "$susp"
+ $ taler-wallet-cli --wallet-db=mydb.sqlite3 advanced suspend-coins "$susp"
# Update exchange /keys so recoup gets scheduled
- $ taler-wallet-cli --wallet-db=mydb.json exchanges update -f https://exchange.int.taler.net/
+ $ taler-wallet-cli --wallet-db=mydb.sqlite3 exchanges update -f https://exchange.int.taler.net/
# Block until scheduled operations are done
- $ taler-wallet-cli --wallet-db=mydb.json run-until-done
+ $ taler-wallet-cli --wallet-db=mydb.sqlite3 run-until-done
# Now we buy something, only the coins resulting from recouped will be
# used, as other ones are suspended
- $ taler-wallet-cli --wallet-db=mydb.json testing test-pay \
+ $ taler-wallet-cli --wallet-db=mydb.sqlite3 testing test-pay \
-m https://backend.int.taler.net/ \
-k sandbox \
-a "INTKUDOS:1" \
-s "foo"
- $ taler-wallet-cli --wallet-db=mydb.json run-until-done
+ $ taler-wallet-cli --wallet-db=mydb.sqlite3 run-until-done
To test refreshing, force a refresh:
.. code-block:: console
- $ taler-wallet-cli --wallet-db=mydb.json advanced force-refresh "$coin_pub"
+ $ taler-wallet-cli --wallet-db=mydb.sqlite3 advanced force-refresh "$coin_pub"
To test zombie coins, use the timetravel option. It **must** be passed to the
@@ -481,59 +437,9 @@ top-level command and not the subcommand:
.. code-block:: console
# Update exchange /keys with time travel, value in microseconds
- $ taler-wallet-cli --timetravel=1000000 --wallet-db=mydb.json \
+ $ taler-wallet-cli --timetravel=1000000 --wallet-db=mydb.sqlite3 \
exchanges update -f https://exchange.int.taler.net/
-Test Cases
-----------
-
-Things we already have tests for:
-
-* Can the wallet recoup coins and spend them?
- [`link <https://git.taler.net/wallet-core.git/tree/integrationtests/test-recoup.sh>`__]
-
-Things we still need tests for:
-
-* Does the wallet do retries correctly when the exchange is not reachable?
- 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 refunds
-* Test for :ref:`session-based payments <repurchase>`
-* Test case for auto-refunds
- (scenario where the vending machine finds out that its motor is broken,
- so it automatically gives a refund)
-* Does the wallet report "insufficient balance" correctly
- (as opposed to, say, crashing)?
-* Perf tests: How does the wallet handle withdrawing a *LOT* of coins?
-* Are the transaction history and pending operations reported correctly?
-
-Tests for things the wallet doesn't handle correctly yet:
-
-* What happens if the wallet double-spends a coin?
- (Easy to test by copying the wallet DB before spending
- and then running a spend again with the old DB).
-* What happens when a reserve is changed between accepting withdrawal
- and actually withdrawing coins?
- (This is harder to test. Might not be possible with the current CLI.
- The idea would be be to have some ``--inhibit=withdraw`` flag
- that tells the wallet to not actually withdraw,
- so we can change the reserve state and then resume the wallet.)
-* What happens if the exchange suddenly has a completely new list of denominations on offer?
-* What happens if the exchange changes its master public key?
- The wallet *should* handle this gracefully
- even if we have coins with that exchange,
- provided that the old denominations can be recouped.
- (That one is pretty difficult!)
-* Does the wallet handle :ref:`payment aborts <order-abort>` correctly?
-
-There are test cases that require us to modify the communication between the wallet and exchange.
-
-* What does the wallet do when the exchange/merchant announce an incompatible protocol version?
-* What happens if some signature made by the exchange/merchant is garbage?
-* What if the exchange reports a double-spend and the proof it gives us is invalid?
-
-
Integration Test and Fault Injection Framework
----------------------------------------------
@@ -553,7 +459,7 @@ or errors) are handled properly. (Support for auditors is still pending
but needed to fully test the wallet.)
This is how a simple withdrawal and payment test case looks like:
-`<https://git.taler.net/wallet-core.git/tree/packages/taler-integrationtests/src/test-payment.ts>`__
+`<https://git.taler.net/taler-typescript-core.git/tree/packages/taler-harness/src/integrationtests/test-payment.ts>`__
(What's particularly nice is that all our docs contain TypeScript
definitions for all API request bodies. So just copying them into the
@@ -570,7 +476,7 @@ The following test case (a) logs all requests and responses to the test
harness stdout and (b) at a certain point, starts dropping the next 10
requests to the exchange (testing the wallet's retry logic):
-`<https://git.taler.net/wallet-core.git/tree/packages/taler-integrationtests/src/test-payment-fault.ts#n165>`__
+`<https://git.taler.net/taler-typescript-core.git/tree/packages/taler-harness/src/integrationtests/test-payment-fault.ts#n165>`__
3. All util functionality from JS wallet-core, such as the Taler crypto,
amount/date/etc. handling and JSON parsing/validation (the wallet is now
@@ -642,15 +548,43 @@ which implements the ``ExchangeServiceInterface``:
The package for the integration tests is here:
-`<https://git.taler.net/wallet-core.git/tree/packages/taler-integrationtests>`__
+`<https://git.taler.net/wallet-core.git/tree/packages/taler-harness>`__
-The shortcut to run all integration tests is
+The integration tests are run via the ``taler-harness`` tool.
.. code:: sh
- ./bootstrap && ./configure --prefix=... \
- && make install integrationtests
+ ./bootstrap && ./configure --prefix=... && make install
+ taler-harness run-integrationtests
+
+
+Dev Experiments
+===============
+
+Dev experiments allow simulating certain scenarios that are difficult to
+reproduce otherwise. This allows more comprehensive (manual) testing of the
+UIs.
+
+You can enable dev experiments by putting the wallet into dev mode and then
+scanning the QR code for a ``taler://dev-experiment`` URI that specifies the
+desired dev experiment.
+
+Faking Protocol Versions
+------------------------
+
+The ``start-fakeprotover`` dev experiment can be used to fake the protocol
+version reported by Taler component. It mocks the ``version`` field in the
+response to ``/config`` or ``/keys``.
+
+Usage:
+
+.. code:: none
+
+ taler://dev-experiment/start-fakeprotover?base_url=...&fake_ver=...
+
+Example:
+
+.. code:: none
-(From the root of the whole repo. If you're developing tests, it's way
-faster to just run "make compile install" once and then use
-"./testrunner" from the ``taler-integrationtests`` package.)
+ # Fake version 10:0:0 for https://exchange.demo.taler.net/
+ taler://dev-experiment/start-fakeprotover?base_url=https%3A%2F%2Fexchange.demo.taler.net%2F&fake_ver=10%3A0%3A0
