Contents

12.48. DD 48: Wallet Exchange Lifecycle and Management

12.48.1. Summary

This design document covers the lifecycle and management of exchanges in the wallet.

12.48.2. Motivation

The current wallet implementation lacks requests to manage exchanges. It also always fetches the /keys info of all exchanges, because it doens’t distinguish between used and preset/added exchanges.

12.48.3. Requirements

The following properties of of exchanges managed by the wallet are important:

  • is the exchange used for something (coins, (account-)reserves, purses, …)

  • did the user (ever) accept the ToS?

  • does the exchange have newer ToS available?

  • is a current version of /keys (including former /wire) downloaded?

  • were there errors downloading or checking the keys info?

  • is the exchange permanently added or ephemeral?

    • ephemeral exchange records are created when the user checks fees of an exchange but doesn’t use it, they would typically be hidden in the UI

12.48.4. Proposed Solution

12.48.4.1. Exchange Entry Status

The wallet exposes three separate status fields for each exchange entry:

  • the entry status

  • the update status

  • the ToS status

12.48.4.1.1. Entry Status

  • preset: Exchange record has been added to the exchange (typically as a hardcoded preset in wallet-core). While the exchange can be selected for operations, the wallet doesn’t update the status yet, i.e. no /keys queries are done.

  • ephemeral: Exchange has been updated (or update has been attempted) at least once (for example as part of checking the fees for a transaction using the exchange). However, the exchange is not yet used for any resource in the wallet. In this state, the exchange record will be garbage-collected eventually.

  • used: The exchange is known and used, the wallet regularly queries /keys.

Transitions:

  • A transition from used to ephemeral is not possible, since this would eventually remove preset exchanges and likely confuse the user.

12.48.4.1.2. Update Status

  • initial: Not updated, no need to update

  • initial-update: Update pending, possibly with error

  • suspended: Exchange was manually disabled, should not be contacted anymore, but record is kept in the wallet. Mostly useful for testing.

  • unavailable-update: The exchange is currently unavailable to be used for withdrawals, but it is possible that the exchange starts working again in the future. The wallet will re-try contacting the exchange. The wallet will still try operations that spend coins, but the user might be warned about the bad exchange status.

    Examples:

    • The exchange updated to a new protocol version that is incompatible with the wallet

    • The exchange advertises a new master public key. This might be a temporary configuration issue or malicious attack.

    • The exchange only advertises outdated denomination keys, making new withdrawals impossible.

  • ready: Exchange is useable.

  • ready-update: Exchange is useable, but currently being updated. If it is discovered that the information from the exchange is indeed too outdated (unknown signing key in response, no denomination), the entry must transition to outdated-update.

  • outdated-update: Information in the wallet’s DB about the exchange is too old to be used, it must be updated before proceeding.

12.48.4.1.3. ToS Status

  • pending: The wallet is still trying to download the ToS. Possibly the last download attempt failed, will be reflected in an error details object.

  • proposed: The user needs to accept the current ToS.

  • accepted: The user has accepted the latest version of the ToS.

  • missing-tos: The terms of service are missing, the exchange did not configure any.

12.48.4.2. Management Requests

  • listExchanges: List exchanges with their status info.

  • addExchange: Adds an exchange, entry status will be ephemeral until the user actually uses the exchange.

  • getExchangeResources: List resources (number of coins, reserves, …) associated with the exchange.

  • deleteExchange({exchangeUrl: string, purge: boolean}): Removes an exchange. Unless purge: true is specified, only an exchange without any associated resources can be deleted.

  • getExchangeTos({exchangeUrl: string, acceptLanguage?: string[], acceptFormat?: string[]}) => { language: string, mime: string, content: string, altLanguages: string[] }

FIXME: Purging should probably delete all resources associated with the exchange. But does it also remove the associated transactions?

12.48.4.3. ToS Management

The wallet only stores the last accepted ToS ETag and the ETag last offered by the exchange. The ToS contents are not stored by the wallet database (and thus not included in backups). However, the wallet implementation may cache the /terms response on the level of the HTTP client.

In future iterations, the UI might specify the prefered language and content type for /terms, so that the wallet can already download the full response (not just HEAD).

12.48.5. Definition of Done

  • states implemented in wallet-core

  • exchange management specified on a UI level

  • webex implemented

  • android wallet implemented

  • ios wallet implemented

12.48.6. Discussion / Q&A

  • Should there be a “permanently failed” update state?

    • dold => I don’t think so, as it means that temporary configuration issues on the side of the exchange might permanently brick users’ wallets. The wallet should always re-try contacting the exchange and of course possibly report information to the auditor.

previous

12.47. DD 47: STEFAN

next

12.49. DD 49: Authentication