13. GNU Taler Wallet Developer Manual

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

13.1. Command-line Wallet

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

13.1.1. Building from source

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

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

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

13.2. Manual withdrawing

$ taler-wallet-cli advanced withdraw-manually \
    --exchange https://exchange.eurint.taler.net/ \
    --amount EUR:5

13.3. WebExtension Wallet

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

13.4. Android Wallet

Please see Building apps from source in the Developer’s Manual.

13.5. APIs and Data Formats

Warning

These APIs are still a work in progress and not final.

13.5.1. Envelope Format

All API responses and notifications are returned in the following envelope:

type WalletResponseEnvelope =
 | WalletSuccess
 | WalletError
 | WalletNotification
export interface WalletSuccess {
  type: "response";
  operation: string,
  // ID to correlate success response to request
  id: string;
  // Result type depends on operation
  result: unknown;
}
export interface WalletError {
  type: "error";
  operation: string,
  // ID to correlate error response to request
  id: string;
  error: WalletErrorInfo;
}
export interface WalletSuccess {
  type: "notification";

  // actual type is WalletNotification,
  // to be documented here
  payload: any;
}
export interface WalletErrorInfo {
  // Numeric error code defined defined in the
  // GANA gnu-taler-error-codes registry.
  talerErrorCode: number;

  // English description of the error code.
  talerErrorHint: string;

  // English diagnostic message that can give details
  // for the instance of the error.
  message: string;

  // Error details, type depends
  // on talerErrorCode
  details: unknown;
}

13.5.2. Balances

Balances are the amounts of digital cash held by the wallet.

name

"getBalances"

description

Get a list of balances per currency.

response
interface BalancesResponse {
  // a list of balances sorted by currency.
  // (currencies with shorter names first, then lexically ascending).
  //
  // Note: Even when a currency has no balance, but pending or past transactions,
  //       it should be included in this list with a balance of zero.
  balances: Balance[];
}
// Balance for one currency.
// The currency can be derived from any of the
// "Amount" fields, as the currency is present even
// when the amount is zero.
interface Balance {
  // The total Amount that is currently available to be spent
  // including amounts tied up in ongoing refresh operations. These are hidden from the user.
  // If the user tries to spend coins locked up this way,
  // the wallet will give an error message different from "insufficient balance".
  available: Amount;

  // the total incoming amount that will be added to the available balance
  // when all pending transactions succeed (including internal refreshes)
  pendingIncoming: Amount;

  // the total outgoing amount that will be subtracted from the available balance
  // when all pending transactions succeed (including internal refreshes)
  pendingOutgoing: Amount;

  // true if the balance requires user-interaction, e.g. accepting a tip
  // (DEV: can be left out of a first implementation)
  requiresUserInput: boolean;
}

13.5.3. Transactions

Transactions are all operations or events that affect the balance.

Name

"getTransactions"

Description

Get a list of past and pending transactions.

Request
interface TransactionsRequest {
  // return only transactions in the given currency, if present
  currency?: string;

  // if present, results will be limited to transactions related to the given search string
  search?: string;
}
Response
interface TransactionsResponse {
  // a list of past and pending transactions sorted by pending, timestamp and transactionId.
  // In case two events are both pending and have the same timestamp,
  // they are sorted by the transactionId
  // (i.e. pending before non-pending transactions, newer before older
  //  and if all equal transactionId lexically ascending).
  transactions: Transaction[];
}
interface Transaction {
  // opaque unique ID for the transaction, used as a starting point for paginating queries
  // and for invoking actions on the transaction (e.g. deleting/hiding it from the history)
  transactionId: string;

  // the type of the transaction; different types might provide additional information
  type: TransactionType;

  // main timestamp of the transaction
  timestamp: Timestamp;

  // true if the transaction is still pending, false otherwise
  // If a transaction is not longer pending, its timestamp will be updated,
  // but its transactionId will remain unchanged
  pending: boolean;

  // if present, the transaction encountered a fatal error that needs to be shown to the user
  error?: TransactionError;

  // Raw amount of the transaction (exclusive of fees or other extra costs)
  amountRaw: Amount;

  // Amount added or removed from the wallet's balance (including all fees and other costs)
  amountEffective: Amount;
}
type TransactionType = (
  TransactionWithdrawal |
  TransactionPayment |
  TransactionRefund |
  TransactionTip |
  TransactionRefresh
)
interface TransactionError {
  // TALER_EC_* unique error code.
  // The action(s) offered and message displayed on the transaction item depend on this code.
  ec: number;

  // English-only error hint, if available.
  hint?: string;

  // Error details specific to "ec", if applicable/available
  details?: any;
}
interface WithdrawalDetailsForManualTransfer {
  type: "manual-transfer";

  // Payto URIs that the exchange supports.
  // Already contains the amount and message.
  exchangePaytoUris: string[];

  // Public key of the newly created reserve.
  // Not useful for the UI, but required for integration testing.
  reservePub: string;
}
interface WithdrawalDetailsForTalerBankIntegrationApi {
  type: "taler-bank-integration-api";

  // Set to true if the bank has confirmed the withdrawal, false if not.
  // An unconfirmed withdrawal usually requires user-input and should be highlighted in the UI.
  // See also bankConfirmationUrl below.
  confirmed: boolean;

  // If the withdrawal is unconfirmed, this can include a URL for user
  // initiated confirmation.
  bankConfirmationUrl?: string;
}
// This should only be used for actual withdrawals
// and not for tips that have their own transactions type.
interface TransactionWithdrawal extends Transaction {
  type: string = "withdrawal",

  // Exchange that was withdrawn from.
  exchangeBaseUrl: string;

  // Amount that has been subtracted from the reserve's balance for this withdrawal.
  amountRaw: Amount;

  // Amount that actually was (or will be) added to the wallet's balance.
  // Should always be shown as a positive amount.
  amountEffective: Amount;

  // Further details
  withdrawalDetails: WithdrawalDetails;
}
interface TransactionPayment extends Transaction {
  type: string = "payment",

  // Additional information about the payment.
  info: OrderShortInfo;

  // Wallet-internal end-to-end identifier for the payment
  // (assigned before the order is even downloaded, thus the name).
  proposalId: string;

  // The current status of this payment.
  status: PaymentStatus;

  // Amount that must be paid for the contract
  amountRaw: Amount;

  // Amount that was paid, including deposit, wire and refresh fees.
  // Should always be shown as a negative amount.
  amountEffective: Amount;
}
interface OrderShortInfo {
  // Order ID, uniquely identifies the order within a merchant instance
  orderId: string;

  // More information about the merchant
  merchant: Merchant;

  // Summary of the order, given by the merchant
  summary: string;

  // Map from IETF BCP 47 language tags to localized summaries
  summary_i18n?: { [lang_tag: string]: string };

  // List of products that are part of the order
  products: Product[];

  // URL of the fulfillment, given by the merchant
  fulfillmentUrl?: string;

  // Message shown to the user after the payment is complete.
  fulfillmentMessage?: string;

  // Map from IETF BCP 47 language tags to localized fulfillment messages
  fulfillmentMessage_i18n: { [lang_tag: string]: string };
}
enum PaymentStatus {
  // Explicitly aborted after timeout / failure
  Aborted = "aborted",

  // Payment failed, wallet will auto-retry.
  // User should be given the option to retry now / abort.
  Failed = "failed",

  // Paid successfully
  Paid = "paid",

  // Only offered, user must accept / decline
  Offered = "offered",

  // User accepted, payment is processing.
  Accepted = "accepted",
}
interface TransactionRefund extends Transaction {
  type: string = "refund",

  // ID for the transaction that is refunded
  refundedTransactionId: string;

  // Additional information about the refunded payment
  info: OrderShortInfo;

  // Part of the refund that couldn't be applied because the refund permissions were expired
  amountInvalid: Amount;

  // Amount that has been refunded by the merchant.
  // Corresponds to amountRefundGranted from the applyRefund response.
  amountRaw: Amount;

  // Amount will be added to the wallet's balance after fees and refreshing.
  // Should always be shown as a positive amount.
  amountEffective: Amount;
}
interface TransactionTip extends Transaction {
  type: string = "tip",

  // The current status of this tip.
  status: TipStatus;

  // Exchange that the tip will be (or was) withdrawn from
  exchangeBaseUrl: string;

  // More information about the merchant that sent the tip
  merchant: Merchant;

  // Raw amount of the tip, without extra fees that apply
  amountRaw: Amount;

  // Amount will be (or was) added to the wallet's balance after fees and refreshing.
  // Should always be shown as a positive amount.
  amountEffective: Amount;
}
enum TipStatus {
  // Only offered, user must accept / decline
  Offered = "offered",

  // User accepted, tip is processing.
  Accepted = "accepted",

  // User declined.
  Declined = "declined",

  // Received successfully
  Received = "received",
}
// A transaction shown for refreshes that are not associated to other transactions
// such as a refresh necessary before coin expiration.
// It should only be returned by the API if the effective amount is different from zero.
interface TransactionRefresh extends Transaction {
  type: string = "refresh",

  // Exchange that the coins are refreshed with
  exchangeBaseUrl: string;

  // Raw amount that is refreshed
  amountRaw: Amount;

  // Amount that will be paid as fees for the refresh.
  // Should always be shown as a negative amount.
  amountEffective: Amount;
}
Name

"deleteTransaction"

Description

Delete a transaction by ID.

Request
interface DeleteTransactionRequest {
  // Transaction ID (opaque!) as returned in
  // the transaction list response.
  transactionId: string;
}
Response

Returns an empty object

13.5.4. Refunds

Name

"applyRefund"

Description

Process a refund from a taler://refund URI.

Request
interface WalletApplyRefundRequest {
  talerRefundUri: string;
}
Response
interface WalletApplyRefundResponse {
  // Identifier for the purchase that was refunded
  // DEPRECATED:  Will disappear soon.
  contractTermsHash: string;

  amountEffectivePaid: Amount;

  amountRefundGranted: Amount;

  amountRefundGone: Amount;

  pendingAtExchange: boolean;

  // Short info about the order being refunded.
  info: OrderShortInfo;
}

13.5.5. Exchange Management

List Exchanges

Name

"listExchanges"

Description

List all exchanges.

Response
interface ExchangesListResponse {
  exchanges: ExchangeListItem[];
}
interface ExchangeListItem {
  exchangeBaseUrl: string;
  currency: string;
  paytoUris: string[];
}

Add Exchange

Name

"addExchange"

Description

Add an exchange.

Request
interface ExchangeAddRequest {
  exchangeBaseUrl: string;
}
Response

On success, the response is an ExchangeListItem.

Force Exchange Update

Name

"forceUpdateExchange"

Description

Force updating an exchange. Re-queries current cryptographic key material, wire information and terms of service from the exchange. Also applies denomination revocations if applicable.

Request
interface ExchangeForceUpdateRequest {
  exchangeBaseUrl: string;
}
Response

On success, the response is an ExchangeListItem.

Get Terms of Service

Name

"getExchangeTos"

Description

Get the exchange’s current ToS and which version of the ToS (if any) the user has accepted.

Request
interface ExchangeGetTosRequest {
  exchangeBaseUrl: string;
}
Response
interface GetExchangeTosResult {
  // Markdown version of the current ToS.
  content: string;

  // Version tag of the current ToS.
  currentEtag: string;

  // Version tag of the last ToS that the user has accepted,
  // if any.
  acceptedEtag: string | undefined;
}

Set Accepted Terms of Service Version

Name

"setExchangeTosAccepted"

Description

Store that the user has accepted a version of the exchange’s ToS.

Request
interface ExchangeGetTosRequest {
  exchangeBaseUrl: string;
  acceptedEtag: string;
}
Response

On success, the response is an empty object.

13.5.6. Withdrawal

A typical API sequence for bank-integrated withdrawals can for example look like this:

  1. "getWithdrawalDetailsForUri" returns an amount and default exchange
  2. "getWithdrawalDetailsForAmount" returns fee information and that ToS are not accepted
    1. "getExchangeTos" are shown to the user and return currentEtag
    2. "setExchangeTosAccepted" called with currentEtag after user accepted
  3. "acceptWithdrawal" after the user confirmed withdrawal with associated fees

A typical API sequence for manual withdrawals can for example look like this:

  1. "listExchanges" shows a list of exchanges to the user who picks one and an amount
  2. "getWithdrawalDetailsForAmount" returns fee information and that ToS are not accepted
    1. "getExchangeTos" are shown to the user and return currentEtag
    2. "setExchangeTosAccepted" called with currentEtag after user accepted
  3. "acceptManualWithdrawal" after the user confirmed withdrawal with associated fees

Get Details For Bank-integrated Withdrawal

Name

"getWithdrawalDetailsForUri"

Description

Get information about exchanges for a bank-integrated withdrawal from a taler://withdraw URI.

Request
interface GetWithdrawalUriDetailsRequest {
  talerWithdrawUri: string;
}
Response
interface WithdrawalDetailsForUri {
  // The amount that the user wants to withdraw
  amount: Amount;

  // Exchange suggested by the wallet
  defaultExchangeBaseUrl?: string;

  // A list of exchanges that can be used for this withdrawal
  possibleExchanges: ExchangeListItem[];
}

Get Withdrawal Details

Name

"getWithdrawalDetailsForAmount"

Description

Get information about fees and exchange for a withdrawal of a given amount. Can be used for both bank-integrated and manual withdrawals.

Request
interface WithdrawalDetailsRequest {
  exchangeBaseUrl: string;
  amount: Amount;
}
Response
interface WithdrawalDetails {
  // Did the user accept the current version of the exchange's terms of service?
  tosAccepted: boolean;

  // Amount that will be transferred to the exchange.
  amountRaw: Amount;

  // Amount that will be added to the user's wallet balance.
  amountEffective: Amount;
}

Accept Bank-integrated Withdrawal

Name

"acceptWithdrawal"

Description

Accept a bank-integrated withdrawal, where the bank transfers funds automatically.

Request
interface AcceptWithdrawalRequest {
  talerWithdrawUri: string;
  exchangeBaseUrl: string;
}
Response
interface AcceptWithdrawalResponse {
  // a URL for user initiated confirmation.
  bankConfirmationUrl?: string;
}

Accept Manual Withdrawal

Name

"acceptManualWithdrawal"

Description

Accept a manual withdrawal, where the user has to transfer funds manually.

Request
interface AcceptManualWithdrawalRequest {
  exchangeBaseUrl: string;
  amount: Amount;
}
Response
interface AcceptManualWithdrawalResponse {
  // Payto URIs to fund the withdrawal,
  // with amount and message provided.
  exchangePaytoUris: string[];
}

13.5.7. Deposits

Deposits are direct payments into a payment target (given via a payto URI). They don’t involve a merchant.

Name

"createDepositGroup"

Description

Deposit funds directly into a payment target.

Request
interface CreateDepositGroupRequest {
  depositPaytoUri: string;
  amount: Amount;
}
Response
interface CreateDepositGroupResponse {
  depositGroupId: string;
}

13.5.8. Payments

Prepare Pay

Name

"preparePay"

Description

Fetch information about a payment request from a merchant.

Request
interface PreparePayRequest {
  talerPayUri: string;
}
Response
interface PreparePayPaymentPossibleResponse {
  status: "payment-possible";

  proposalId: string;

  // Verbatim contract terms as generated by the merchant.
  contractTerms: ContractTerms;

  // Amount that the merchant is asking for.
  amountRaw: Amount;

  // Amount that will effectively be subtracted from the wallet's
  // balance when accepting this proposal.
  amountEffective: Amount;
}
interface PreparePayInsufficientBalanceResponse {
  status: "insufficient-balance";

  proposalId: string;

  // Amount that the merchant is asking for.
  amountRaw: Amount;

  // Verbatim contract terms as generated by the merchant.
  contractTerms: ContractTerms;
}
interface PreparePayAlreadyConfirmedResponse {
  status: "already-confirmed";

  proposalId: string;

  // Did the payment succeed?
  paid: boolean;

  // Amount that the merchant is asking for.
  amountRaw: Amount;

  // Amount that will be subtracted from the wallet balance
  amountEffective: Amount;

  // Verbatim contract terms as generated by the merchant.
  contractTerms: ContractTerms;
}

Confirm Payment

Name

"confirmPay"

Description

Confirm making a payment.

Request
interface ConfirmPayRequest {
  proposalId: string;
}
Response
interface ConfirmPayResultDone {
  type: "done";

  contractTerms: ContractTerms;
}
// Payment was marked as confirmed,
// but the attempt(s) to pay were not successful yet.
interface ConfirmPayPending {
  type: "pending";

  lastError: TransactionError;
}
type ConfirmPayResult =
  | ConfirmPayResultDone;
  | ConfirmPayResultPending;

Abort Failed Payment

Name

"abortFailedPayWithRefund"

Description

Abort a failed payment and try to get a refund for the partially paid amount.

Request
export interface AbortPayWithRefundRequest {
  proposalId: string;
}
Response

On success, the response is an empty object.

13.5.9. Tipping API Calls

Preparing a tip

Name

"prepareTip"

Description

Prepare to accept a tip based in a taler://tip URI.

Request
interface PrepareTipRequest {
  talerTipUri: string;
}
Response
interface PrepareTipResult {
  // Unique ID for the tip assigned by the wallet.
  // Typically different from the merchant-generated tip ID.
  walletTipId: string;

  // Has the tip already been accepted?
  accepted: boolean;
  tipAmountRaw: Amount;
  tipAmountEffective: Amount;
  exchangeBaseUrl: string;
  expirationTimestamp: Timestamp;
}

Accepting a tip

Name

"acceptTip"

Description

Prepare to accept a tip based in a taler://tip URI.

Request
interface AcceptTipRequest {
  walletTipId: string;
}
Response

On success, the response is an empty object.

13.5.10. Testing API calls

The following API calls are useful for testing.

Withdraw balance from the TESTKUDOS environment

Name
"withdrawTestkudos"
Description
Withdraw a balance from the TESTKUDOS environment.
Request
The request parameters are ignored.
Response
On success, the response is an empty object.

Withdraw balance from a test environment

Name

"withdrawTestBalance"

Description

Withdraw a balance from a test environment.

Request
interface WithdrawTestBalanceRequest {
  amount: string;
  bankBaseUrl: string;
  exchangeBaseUrl: string;
}
Response

On success, the response is an empty object.

Run integration test

Name

"runIntegrationTest"

Description

Run a basic integration test that does a withdrawal, payment, refund and again a payment. Useful to generate test data in the integration tests of other components.

Request
interface IntegrationTestArgs {
  exchangeBaseUrl: string;
  bankBaseUrl: string;
  merchantBaseUrl: string;
  merchantApiKey: string;
  amountToWithdraw: string;
  amountToSpend: string;
}
Response

On success, the response is an empty object.

Make a test payment

Name

"testPay"

Description

Make a test payment with existing funds.

Request
interface TestPayArgs {
  merchantBaseUrl: string;
  merchantApiKey: string;
  amount: string;
  summary: string;
}

Dump all coins to JSON

Name

"dumpCoins"

Description

Make a test payment with existing funds.

Request

The request object is ignored.

Response
interface CoinDumpJson {
  coins: Array<{
    /**
     * The coin's denomination's public key.
     */
    denom_pub: string;
    /**
     * Hash of denom_pub.
     */
    denom_pub_hash: string;
    /**
     * Value of the denomination (without any fees).
     */
    denom_value: string;
    /**
     * Public key of the coin.
     */
    coin_pub: string;
    /**
     * Base URL of the exchange for the coin.
     */
    exchange_base_url: string;
    /**
     * Remaining value on the coin, to the knowledge of
     * the wallet.
     */
    remaining_value: string;
    /**
     * Public key of the parent coin.
     * Only present if this coin was obtained via refreshing.
     */
    refresh_parent_coin_pub: string | undefined;
    /**
     * Public key of the reserve for this coin.
     * Only present if this coin was obtained via refreshing.
     */
    withdrawal_reserve_pub: string | undefined;
    /**
     * Is the coin suspended?
     * Suspended coins are not considered for payments.
     */
    coin_suspended: boolean;
  }>;
}

Suspend/unsuspend a coin

A suspended coin will not be used by the wallet for payments. This functionality is only used for testing.

Name

"setCoinSuspended"

Description

Make a test payment with existing funds.

Request
interface SetCoinSuspendedRequest {
  coinPub: string;
  suspended: boolean;
}
Request

On success, the response is an empty object.

13.5.11. Global Errors

  • Backup/Sync/Anastasis failed
  • refresh after pay failed for multiple attempts (depending on online status)
  • scheduled refresh (to avoid expiration) failed
  • general recoups (?)
  • failed recoup
  • (maybe) fatal errors during withdrawal
  • pending refund failed permanently (?)

13.6. Integration Tests

13.6.1. 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).

The database file for the wallet can be selected with the --wallet-db option. This option must be passed to the taler-wallet-cli command and not the subcommands. If the database file doesn’t exist, it will be created.

The following example does a simple withdrawal recoup:

# 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

$ coins=$(taler-wallet-cli --wallet-db=mydb.json advanced dump-coins)

# 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]')

# The exchange revokes the denom
$ taler-exchange-keyup -r $rd
$ taler-deployment-restart

# 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"

# Update exchange /keys so recoup gets scheduled
$ taler-wallet-cli --wallet-db=mydb.json exchanges update -f https://exchange.int.taler.net/

# Block until scheduled operations are done
$ taler-wallet-cli --wallet-db=mydb.json run-until-done

# 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

To test refreshing, force a refresh:

$ taler-wallet-cli --wallet-db=mydb.json advanced force-refresh "$coin_pub"

To test zombie coins, use the timetravel option. It must be passed to the top-level command and not the subcommand:

# 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/

13.6.2. Test Cases

Things we already have tests for:

  • Can the wallet recoup coins and spend them? [link]

Things we still need tests for:

  • Does the wallet do retries correctly when the exchange is not reachable? Or when the merchant is not reachable? Or the bank? This can be tested by temporarily killing those services.
  • How does the wallet deal with processing the same taler://(pay|withdraw) URI twice?
  • Test tipping (accepting/refusing a tip)
  • Test refunds
  • Test for session-based payments
  • Test case for auto-refunds (scenario where the vending machine finds out that its motor is broken, so it automatically gives a refund)
  • Does the wallet report “insufficient balance” correctly (as opposed to, say, crashing)?
  • Perf tests: How does the wallet handle withdrawing a LOT of coins?
  • Are the transaction history and pending operations reported correctly?

Tests for things the wallet doesn’t handle correctly yet:

  • What happens if the wallet double-spends a coin? (Easy to test by copying the wallet DB before spending and then running a spend again with the old DB).
  • What happens when a reserve is changed between accepting withdrawal and actually withdrawing coins? (This is harder to test. Might not be possible with the current CLI. The idea would be be to have some --inhibit=withdraw flag that tells the wallet to not actually withdraw, so we can change the reserve state and then resume the wallet.)
  • What happens if the exchange suddenly has a completely new list of denominations on offer?
  • What happens if the exchange changes its master public key? The wallet should handle this gracefully even if we have coins with that exchange, provided that the old denominations can be recouped. (That one is pretty difficult!)
  • Does the wallet handle payment aborts correctly?

There are test cases that require us to modify the communication between the wallet and exchange.

  • What does the wallet do when the exchange/merchant announce an incompatible protocol version?
  • What happens if some signature made by the exchange/merchant is garbage?
  • What if the exchange reports a double-spend and the proof it gives us is invalid?

13.6.3. Integration Test and Fault Injection Framework

This section describes the current approach to integration testing in the wallet.

It’s all based on a TypeScript harness process, which itself implements the fault injection proxy (async and in-process)!

The new approach consists of the following parts:

1. A strongly typed, convenient helper library to easily set up and run arbitrary Taler deployments and run test cases. These components plug together as easily as lego bricks, even with multiple exchanges/merchants/banks/etc. Logs and clean shutdown (even on SIGINT or errors) are handled properly. (Support for auditors is still pending but needed to fully test the wallet.)

This is how a simple withdrawal and payment test case looks like: https://git.taler.net/wallet-core.git/tree/packages/taler-integrationtests/src/test-payment.ts

(What’s particularly nice is that all our docs contain TypeScript definitions for all API request bodies. So just copying them into the test harness gives us auto-completion and compile-time checks to avoid typos. The wallet’s JSON validation machinery is also re-used.)

2. A fault injection proxy that can be plugged between the services and/or the wallet. It runs alongside the test harness, and can thus can use arbitrary custom logic. There’s no dependency for it other than built-in Node.JS libraries. Simple fault injections are just as easy to set up as with the twister.

The following test case (a) logs all requests and responses to the test harness stdout and (b) at a certain point, starts dropping the next 10 requests to the exchange (testing the wallet’s retry logic):

https://git.taler.net/wallet-core.git/tree/packages/taler-integrationtests/src/test-payment-fault.ts#n165

3. All util functionality from JS wallet-core, such as the Taler crypto, amount/date/etc. handling and JSON parsing/validation (the wallet is now more modular and easier to use as a library) can be used in the integration tests, even if a different wallet (Kotlin, whatever) is tested via the CLI.

4. A bunch of test cases that use (1)-(3). These are significantly more readable and hackable than other test approaches we had, while allowing for more complex scenarios. There are still way too few tests though!

5. A test runner (written in bash) that runs test cases based on a glob pattern and reports the results.

Injecting a fault is as easy as:

// Set up test case
[...]

exchangeProxy.addFault({
  beforeResponse(ctx: FaultInjectionResponseContext) {
     if (cond1) { // Drop some responses
       ctx.dropResponse = true;
       return;
     } else if (cond2) { // modify some others
       ctx.responseBody = Buffer.from(`{"oops": true}`, "utf-8");
       return;
     }
     // Other things that can be modified:
     // - drop/modify the request, not just the response
     // - modify headers
     // - modify status codes
  }
});

await doSomethingWithTheWallet();

exchangeProxy.clearFault();

await doMoreWithTheWallet();

To make the configuration easy, an ExchangeService (or MerchantService, BankService etc.) can be wrapped in a FaultInjectedExchangeService, which implements the ExchangeServiceInterface:

// create exchange and two merchants
const exchange = await setupExchange(...);
const merchant1 = ...;
const merchant2 = ...;

// Add exchange to merchant-accepted exchanges.
// This will adjust the config.
merchant1.addExchange(exchange);

// Wrap exchange in fault injection proxy
const faultInjectedExchange: ExchangeServiceInterface
  = new FaultInjectedExchangeService(t, exchange1, 8085);

// Merchant 2 talks to the exchange over fault injection,
// and thus must use the "twisted" base URL.
merchant2.addExchange(faultInjectedExchange);

The package for the integration tests is here:

https://git.taler.net/wallet-core.git/tree/packages/taler-integrationtests

The shortcut to run all integration tests is

./bootstrap && ./configure --prefix=... \
   && make install integrationtests

(From the root of the whole repo. If you’re developing tests, it’s way faster to just run “make compile install” once and then use “./testrunner” from the taler-integrationtests package.)