DD 65: Exchange Base URL Migration

10.65. DD 65: Exchange Base URL Migration#

10.65.1. Summary#

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

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

10.65.3. Requirements#

  • Existing wallets should continue working with minimal disruption

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

10.65.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 either an error response. 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

  • 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

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

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

10.65.5. Definition of Done#

N/A

10.65.6. Alternatives#

  • Do not support migrations

  • Allow the exchange itself to announce the migration

    • Technically complex, requires signature or has bad security implications

10.65.7. Drawbacks#

  • The merchant still needs to manually add the new exchange

  • Complexity

10.65.8. Discussion / Q&A#

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