wallet API design

1 files changed, 182 insertions, 1 deletions

diff --git a/taler-wallet.rst b/taler-wallet.rst
index 50bf0ef9..06f696d4 100644
--- a/taler-wallet.rst
+++ b/taler-wallet.rst
@@ -70,5 +70,186 @@ Building from source
 Android Wallet
 ==============
 
-*TODO*
+*TBD.*
+
+
+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:
+
+``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.  Details:
+
+  * ``payType``: Can be ``initial`` or ``replay``
+
+``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
+------------------
+
+``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".
+
+``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)".