From a1ae94973e9a549acb022c009f06828ec12d21f3 Mon Sep 17 00:00:00 2001 From: Florian Dold Date: Tue, 24 Mar 2020 16:37:40 +0530 Subject: remove outdated wallet docs --- taler-wallet.rst | 210 +------------------------------------------------------ 1 file changed, 1 insertion(+), 209 deletions(-) diff --git a/taler-wallet.rst b/taler-wallet.rst index 1889c585..bb9b34e8 100644 --- a/taler-wallet.rst +++ b/taler-wallet.rst @@ -77,212 +77,4 @@ Android Wallet APIs and Data Formats ===================== -This section describes the wallet backend API. The goal of this API is to -be easy to consume without having to implement Taler-specific data formats -or algorithms. This is why some redundancy is present, for example in -how amounts are returned. - -Balance -------- - -The balance is computed with different types of "slicing": - -* ``byExchange``: Balance by the exchange it was withdrawn from -* ``byAuditor``: Balance by each auditor trusted by the wallet -* ``byCurrency``: Balance by currency - -Each balance entry contains the following information: - -* ``amountCurrent``: Amount available to spend **right now** -* ``amountAvailable``: Amount available to spend after refresh and withdrawal - operations have completed. -* ``amountPendingOutgoing``: Amount that is allocated to be spent on a payment - but hasn't been spent yet. -* ``amountPendingIncoming``: Amount that will be available but is not available yet - (from refreshing and withdrawal) -* ``amountPendingIncomingWithdrawal``: Amount that will be available from pending withdrawals -* ``amountPendingIncomingRefresh``: Amount that will be available from pending refreshes - - -History -------- - -All events contain a ``type``, a ``timestamp`` and a ``eventUID``. When -querying the event history, a level can be specified. Only events with a -verbosity level ``<=`` the queried level are returned. - -The following event types are available: - -``exchange-added`` - Emitted when an exchange has ben added to the wallet. - -``exchange-update-started`` - Emitted when updating an exchange has started. - -``exchange-update-finished`` - Emitted when updating an exchange has started. - -``reserve-created`` (Level 1) - A reserve has been created. Contains the following detail fields: - - * ``exchangeBaseUrl`` - * ``reservePub``: Public key of the reserve - * ``expectedAmount``: Amount that is expected to be in the reserve. - * ``reserveType``: How was the reserve created? Can be ``taler-withdraw`` when - created by dereferencing a ``taler://pay`` URI or ``manual`` when the reserve - has been created manually. - -``reserve-bank-confirmed`` (Level 1) - Only applies to reserves with ``reserveType`` of ``taler-withdraw``. - This event is emitted when the wallet has successfully sent the details about the - withdrawal (reserve key, selected exchange). - -``reserve-exchange-confirmed`` (Level 0) - This event is emitted the first time that the exchange returns a success result - for querying the status of the resere. - - * ``exchangeBaseUrl`` - * ``reservePub``: Public key of the reserve - * ``currentAmount``: Amount that is expected to be in the reserve. - -``reserve-exchange-updated`` (Level 0) - Emitted when a reserve has been updated **and** the remaining amount has changed. - -``withdraw-started`` (Level 1) - Emitted when the wallet starts a withdrawal from a reserve. Contains the following detail fields: - - * ``withdrawReason``: Why was the withdraw started? Can be ``initial`` (first withdrawal to drain a - reserve), ``repeat`` (withdrawing from a manually topped-up reserve) or ``tip`` - * ``withdrawRawAmount``: Amount that is subtracted from the reserve, includes fees. - * ``withdrawEffectiveAmount``: Amount that will be added to the balance. - -``withdraw-coin-finished`` (Level 2) - An individual coin has been successfully withdrawn. - -``withdraw-finished`` (Level 0) - Withdraw was successful. Details: - - * ``withdrawRawAmount``: Amount that is subtracted from the reserve, includes fees. - * ``withdrawEffectiveAmount``: Amount that will be added to the balance. - -``order-offered`` (Level 1) - A merchant has offered the wallet to download an order. - -``order-claimed`` (Level 1) - The wallet has downloaded and claimed an order. - -``order-pay-confirmed`` (Level 0) - The wallet's user(-agent) has confirmed that a payment should - be made for this order. - -``pay-coin-finished`` (Level 2) - A coin has been sent successfully to the merchant. - -``pay-finished`` (Level 0) - An order has been paid for successfully for the first time. - This event is not emitted for payment re-playing. - -``refresh-started`` (Level 1) - A refresh session (one or more coins) has been started. Details: - - * ``refreshReason``: One of ``forced``, ``pay`` or ``refund``. - -``refresh-coin-finished`` (Level 2) - Refreshing a single coin has succeeded. - -``refresh-finished`` (Level 0) - A refresh session has succeeded. - -``tip-offered`` (Level 1) - A tip has been offered, but not accepted yet. - -``tip-accepted`` (Level 1) - A tip has been accepted. Together with this event, - a corresponding ``withdraw-started`` event is also emitted. - -``refund`` (Level 0) - The wallet has been notified about a refund. A corresponding - ``refresh-started`` event with ``refreshReason`` set to ``refund`` - will be emitted as well. - - -Pending Operations ------------------- - - -``exchange-update``: - Shown when exchange information (``/keys`` and ``/wire``) is being updated. - -``reserve``: - Shown when a reserve has been created (manually or via dereferencing a ``taler://withdraw`` URI), - but the reserve has not been confirmed yet. - - Details: - - * ``reserveType``: How was the reserve created? Can be ``taler-withdraw`` when - created by dereferencing a ``taler://pay`` URI or ``manual`` when the reserve - has been created manually. - * ``expectedAmount``: Amount we expect to be in the reserve. - * ``status``: Either ``new`` or ``confirmed-bank``. - * ``lastError``: If present, contains the last error pertaining to the reserve, - either from the bank or from the exchange. - - **Rendering**: The pending operation is rendered as "waiting for money transfer". - -``withdrawal`` - Shown when a withdrawal is in progress (either from a reserve in the wallet or - from tipping). - - Details: - - * ``exchangeBaseUrl`` - * ``coinsPending`` - * ``coinsWithdrawn`` - * ``amountWithdrawn`` - * ``amountPending`` - * ``totalWithdrawnAmount``: Amount actually subtracted from the reserve, including fees - * ``totalEffectiveAmount``: Amount that will be added to the balance - * ``lastErrors``: If present, contains the last error for every coin that is - part of this withdrawal operation. - - **Rendering**: The pending operation is rendered as "withdrawing digital cash". - -``pay`` - Shown when a payment is in progress. - - Details: - - * ``amountPrice``: Price of the order that is being purchased - * ``coinsPaid``: Number of coins successfully submitted as payment. - * ``coinsPending``: Number of coins successfully submitted as payment. - * ``amountEffectivePrice``: Effective price, including fees for refreshing *and* - coins that are too small to refresh. - * ``lastErrors``: If present, contains the last error for every coin that is - part of this pay operation. - - **Rendering**: The pending operation is rendered as "paying". - -``refresh`` - Shown when a refresh is in progress, either one that's manually forced, one - after payment, or one after a refund. - - Details: - - * ``refreshReason``: One of ``forced``, ``pay`` or ``refund`` - * ``totalRefreshedAmount``: Amount that has been successfully refreshed - as part of this session - * ``coinsPending``: Number of coins that are part of the refresh operation, but - haven't been processed yet. - * ``coinsMelted``: Number of coins that have been successfully melted. - * ``coinsRefreshed``: Number of coins that have been successfully refreshed. - * ``lastErrors``: If present, contains the last error for every coin that is - part of this refresh operation. - - **Rendering**: The pending operation is rendered as "fetching change", optionally - with "(after manual request)", "(after payment") or "(after refund)". - -``refund`` - Shown when a merchant's refund permission is handed to the exchange. - -``tip`` - Shown when a tip is being picked up from the merchant +*TBD.* -- cgit v1.2.3 From 149de84d66c86fdd324bb4fe6eb239651c69b78a Mon Sep 17 00:00:00 2001 From: Florian Dold Date: Tue, 24 Mar 2020 17:58:47 +0530 Subject: instructions for integration tests with the wallet --- taler-wallet.rst | 61 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 61 insertions(+) diff --git a/taler-wallet.rst b/taler-wallet.rst index bb9b34e8..995237bd 100644 --- a/taler-wallet.rst +++ b/taler-wallet.rst @@ -78,3 +78,64 @@ APIs and Data Formats ===================== *TBD.* + + + +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 `__). + +The following example does a simple withdrawal recoup: + +.. code-block:: sh + + # Withdraw digital cash + $ taler-wallet-cli --wallet-db=mydb.json 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) + + # Find coin we want to revoke + $ rc=$(echo "$coins" | jq -r '[.coins[] | select((.denom_value == "INTKUDOS:5"))][0] | .coin_pub') + # Find the denom + $ rd=$(echo "$coins" | jq -r '[.coins[] | select((.denom_value == "INTKUDOS:5"))][0] | .denom_pub_hash') + # Find all other coins, which will be suspended + $ susp=$(echo "$coins" | jq --arg rc "$rc" '[.coins[] | select(.coin_pub != $rc) | .coin_pub]') + + # The exchange revokes the denom + $ taler-exchange-keyup -r $rd + $ 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" + + # Update exchange /keys so recoup gets scheduled + $ taler-wallet-cli --wallet-db=mydb.json exchanges update -f https://exchange.int.taler.net/ + + # Block until scheduled operations are done + $ taler-wallet-cli --wallet-db=mydb.json 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 -m https://backend.int.taler.net/ -k sandbox -a "INTKUDOS:1" -s "foo" + $ taler-wallet-cli --wallet-db=mydb.json run-until-done + + +To test refreshing, force a refresh: + +.. code-block:: sh + + $ taler-wallet-cli --wallet-db=mydb.json advanced force-refresh "$coin_pub" + + +To test zombie coins, use the timetravel option, it **must** be passed to the top-level command and not the subcommand: + +.. code-block:: sh + + # Update exchange /keys with time travel, value in microseconds + $ taler-wallet-cli --timetravel=1000000 --wallet-db=mydb.json exchanges update -f https://exchange.int.taler.net/ + -- cgit v1.2.3 From da863232486aee72eebf3f76000329f27e5163f5 Mon Sep 17 00:00:00 2001 From: Florian Dold Date: Tue, 24 Mar 2020 18:07:54 +0530 Subject: clarifications --- taler-wallet.rst | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/taler-wallet.rst b/taler-wallet.rst index 995237bd..25e4c17b 100644 --- a/taler-wallet.rst +++ b/taler-wallet.rst @@ -87,6 +87,10 @@ 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 `__). +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 +the subcommands. If the database file doesn't exist, it will be created. + The following example does a simple withdrawal recoup: .. code-block:: sh @@ -132,7 +136,8 @@ To test refreshing, force a refresh: $ taler-wallet-cli --wallet-db=mydb.json advanced force-refresh "$coin_pub" -To test zombie coins, use the timetravel option, it **must** be passed to the top-level command and not the subcommand: +To test zombie coins, use the timetravel option. It **must** be passed to the +top-level command and not the subcommand: .. code-block:: sh -- cgit v1.2.3