From 41cd81bd17468b7502ad0494a71d34fc960cff23 Mon Sep 17 00:00:00 2001 From: Florian Dold Date: Sat, 16 Nov 2019 14:28:28 +0100 Subject: wallet API design --- taler-wallet.rst | 183 ++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 182 insertions(+), 1 deletion(-) (limited to 'taler-wallet.rst') 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)". -- cgit v1.2.3