4. GNU Taler Wallet Manual

The GNU Taler wallet allows customers to withdraw and spend digital cash.

4.1. Command-line Wallet

The command-line wallet is used primarily for testing by developers.

4.1.1. Building from source

$ git clone https://git.taler.net/wallet-core.git
$ ./bootstrap
$ cd wallet-core
$ ./configure --prefix=$INSTALL_PREFIX
$ make && make install

The wallet command-line interface should then be available as taler-wallet-cli under $INSTALL_PREFIX/bin.

4.1.2. Installation via NPM

The wallet can also obtained via NPM, the Node Package Manager.

To install the wallet as a global package, run:

$ npm install -g taler-wallet
# check if installation was successful
$ taler-wallet-cli --version

To install the wallet only for your user, run:

$ npm install -g --prefix=$HOME/local taler-wallet
# check if installation was successful
$ taler-wallet-cli --version
# If this fails, make sure that $HOME/local/bin is in your $PATH

To use the wallet as a library in your own project, run:

$ npm install taler-wallet

4.2. WebExtension Wallet

4.2.1. Building from source

$ git clone https://git.taler.net/wallet-core.git
$ cd wallet-core
$ ./configure
$ make webex-stable
# Packaged extension now available as:
# dist/taler-wallet-$VERSION.zip

4.3. Android Wallet

TBD.

4.4. 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.

4.4.1. 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

4.4.2. 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.

4.4.3. 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