commit 878a1184d447ba9d1678815f6c32005303c4cb68
parent 1b46162eb686ab4fef203aac27c32228243f4798
Author: Florian Dold <florian@dold.me>
Date: Wed, 25 Jun 2025 14:46:49 +0200
document exchange migration
Diffstat:
2 files changed, 113 insertions(+), 0 deletions(-)
diff --git a/design-documents/065-exchange-base-url-migration.rst b/design-documents/065-exchange-base-url-migration.rst
@@ -0,0 +1,112 @@
+DD 65: Exchange Base URL Migration
+##################################
+
+Summary
+=======
+
+This design document describes the process for migrating an exchange to a different base URL.
+
+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.
+
+Requirements
+============
+
+* Existing wallets should continue working with minimal disruption
+
+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.
+
+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
+
+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.
+
+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.
+
+
+Definition of Done
+==================
+
+N/A
+
+Alternatives
+============
+
+* Do not support migrations
+* Allow the exchange itself to announce the migration
+
+ * Technically complex, requires signature or has bad security implications
+
+Drawbacks
+=========
+
+* The merchant still needs to manually add the new exchange
+* Complexity
+
+Discussion / Q&A
+================
+
+(This should be filled in with results from discussions on mailing lists / personal communication.)
diff --git a/design-documents/index.rst b/design-documents/index.rst
@@ -76,4 +76,5 @@ Design documents that start with "XX" are considered deprecated.
062-pq-refresh.rst
063-libeufin-conversion-rate-classes
064-kyc-operation-algo
+ 065-exchange-base-url-migration
999-template
