DD 65: Exchange Base URL Migration

23.66. DD 65: Exchange Base URL Migration#

Design status:

Accepted

Implementation status:

Implemented

DD shepherd:

TBD

Historical contributors:

Florian Dold

First published:

2025-06-25

Last substantive change:

2025-06-25

Implementation evidence:

taler-typescript-core (2025-06-23)

Normative references:

Wallet Developer Manual, Wallet-Core API Documentation

Note

Wallet migration support is implemented. The operator sequence in this DD has not yet been promoted to a deployment reference manual.

23.66.1. Summary#

This design document describes the process for migrating an exchange to a different base URL.

23.66.2. Motivation#

The base URL of an exchange is a static property of the exchange, and it is not intended to be changed. However, there are still scenarios where changing it is required.

23.66.3. Requirements#

  • Existing wallets should continue working with minimal disruption

23.66.4. Proposed Solution#

The proposed migration strategy works automatically / without user intervention only for wallets. Merchants are required to add an entry for the new exchange base URL to their configuration.

23.66.4.1. Wallet Support#

To support automatic migration, wallet-core has a list of migration plans. Each migration plan is a tuple (oldExchangeBaseUrl, newExchangeBaseUrl).

Once the wallet detects that a migration is required, it executes the following steps:

  1. Replace all occurrences of the old exchange base URL with the new exchange base URL in the wallet database.

  2. Add a migration log entry to the database with (oldExchangeBaseUrl, newExchangeBaseUrl, migrationTimestamp)

The wallet runs a migration check when one of the following conditions applies:

  • C1 (unavaliable exchange):

    • The wallet updates an exchange entry (manually or scheduled), requests /keys, and encounters an error response.

    • There is a migration plan for the old exchange to a new exchange.

    • The new exchange returns a well-formed /keys response with a base_url that matches the new exchange base URL

  • C2 (mismatching base URL):

    • The wallet updates an exchange entry (manually or scheduled), requests /keys, and the base_url of the /keys response do not match the base URL of the exchange entry.

    • There is a migration plan for the old exchange to a new exchange.

    • The new exchange returns a well-formed /keys response with a base_url that matches the new exchange base URL

23.66.4.2. Exchange Migration#

If the new exchange base URL is also served by a new host, the following data needs to be transferred:

  1. The exchange postgresql database

  2. (Optional) The exchange software security module keys, including denomination signing keys.

If step (2) is omitted, the exchange will issue new signing and denomination keys, which will in turn need to be signed by the offline key.

23.66.4.3. Overall Migration Steps#

  1. Add a migration plan record (from old to new exchange base URL) in wallet-core.

  2. Deploy all wallets with updated wallet-core.

  3. Wait for some grace period to allow users time to update.

  4. Do the following steps in parallel:

    • Establish a reverse proxy from the old exchange URL to the new exchange base URL

    • Migrate the exchange to the new base URL

  5. Leave the reverse proxy from the old to new exchange in place for the validity of the /keys response (typically one week).

During step (4), there will be minor downtime until both sub-steps have been completed.

23.66.5. Definition of Done#

  • [x] wallet-core applies configured base-URL migration plans

  • [x] migration behavior has wallet-core test coverage

  • [ ] operator migration procedure promoted to a deployment reference manual

23.66.6. Alternatives#

  • Do not support migrations

  • Allow the exchange itself to announce the migration

    • Technically complex, requires signature or has bad security implications

23.66.7. Drawbacks#

  • The merchant still needs to manually add the new exchange

  • Complexity

23.66.8. Discussion / Q&A#

(This should be filled in with results from discussions on mailing lists / personal communication.)