[taler-docs] branch master updated: wallet API design

[gnunet]

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

dold pushed a commit to branch master
in repository docs.

The following commit(s) were added to refs/heads/master by this push:
     new 41cd81b  wallet API design
41cd81b is described below

commit 41cd81bd17468b7502ad0494a71d34fc960cff23
Author: Florian Dold <address@hidden>
AuthorDate: Sat Nov 16 14:28:28 2019 +0100

    wallet API design
---
 libeufin/ebics.rst |   5 +-
 taler-wallet.rst   | 183 ++++++++++++++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 186 insertions(+), 2 deletions(-)

diff --git a/libeufin/ebics.rst b/libeufin/ebics.rst
index 58c22d2..2840a1c 100644
--- a/libeufin/ebics.rst
+++ b/libeufin/ebics.rst
@@ -157,6 +157,9 @@ EBICS Glossary
   V001
     FTAM encryption algorithm ("Verschlüsselung"), superseeded in EBICS by 
E002.
 
+  E002
+    EBICS encryption process, used to encrypt the order payload.
+
   X002
     Identification and authentication signature in H004 and H005.
 
@@ -221,7 +224,7 @@ Relevant Order Types
    Download order types for which there is new data available.
 
   HTD
-   Type: Download, Optional 
+   Type: Download
 
    Download information about a subscriber.  From German "Teilnehmerdaten".
 
diff --git a/taler-wallet.rst b/taler-wallet.rst
index 50bf0ef..06f696d 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)".
 

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