[taler-docs] branch master updated (d7b0316 -> 149de84)

[gnunet]

This is an automated email from the git hooks/post-receive script.

dold pushed a change to branch master
in repository docs.

    from d7b0316  the big EC rename
     new a1ae949  remove outdated wallet docs
     new 149de84  instructions for integration tests with the wallet

The 2 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails.  The revisions
listed as "add" were already present in the repository and have only
been added to this reference.


Summary of changes:
 taler-wallet.rst | 225 ++++++++++---------------------------------------------
 1 file changed, 39 insertions(+), 186 deletions(-)

diff --git a/taler-wallet.rst b/taler-wallet.rst
index 1889c58..995237b 100644
--- a/taler-wallet.rst
+++ b/taler-wallet.rst
@@ -77,212 +77,65 @@ 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.
+*TBD.*
 
-``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
-------------------
+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>`__).
 
-``exchange-update``:
-  Shown when exchange information (``/keys`` and ``/wire``) is being updated.
+The following example does a simple withdrawal recoup:
 
-``reserve``:
-  Shown when a reserve has been created (manually or via dereferencing a 
``taler://withdraw`` URI),
-  but the reserve has not been confirmed yet.
+.. code-block:: sh
 
-  Details:
+  # 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
 
-  * ``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.
+  $ coins=$(taler-wallet-cli --wallet-db=mydb.json advanced dump-coins)
 
-  **Rendering**: The pending operation is rendered as "waiting for money 
transfer".
+  # 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]')
 
-``withdrawal``
-  Shown when a withdrawal is in progress (either from a reserve in the wallet 
or
-  from tipping).
+  # The exchange revokes the denom
+  $ taler-exchange-keyup -r $rd
+  $ taler-deployment-restart
 
-  Details:
+  # 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"
 
-  * ``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.
+  # Update exchange /keys so recoup gets scheduled
+  $ taler-wallet-cli --wallet-db=mydb.json exchanges update -f 
https://exchange.int.taler.net/
 
-  **Rendering**: The pending operation is rendered as "withdrawing digital 
cash".
+  # Block until scheduled operations are done
+  $ taler-wallet-cli --wallet-db=mydb.json run-until-done
 
-``pay``
-  Shown when a payment is in progress.
+  # 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
 
-  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.
+To test refreshing, force a refresh:
 
-  **Rendering**: The pending operation is rendered as "paying".
+.. code-block:: sh
 
-``refresh``
-  Shown when a refresh is in progress, either one that's manually forced, one
-  after payment, or one after a refund.
+  $ taler-wallet-cli --wallet-db=mydb.json advanced force-refresh "$coin_pub"
 
-  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.
+To test zombie coins, use the timetravel option, it **must** be passed to the 
top-level command and not the subcommand:
 
-  **Rendering**: The pending operation is rendered as "fetching change", 
optionally
-  with "(after manual request)", "(after payment") or "(after refund)".
+.. code-block:: sh
 
-``refund``
-  Shown when a merchant's refund permission is handed to the exchange.
+  # 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/
 
-``tip``
-  Shown when a tip is being picked up from the merchant

-- 
To stop receiving notification emails like this one, please contact
address@hidden.