065-exchange-base-url-migration.rst (3599B)
1 DD 65: Exchange Base URL Migration 2 ################################## 3 4 Summary 5 ======= 6 7 This design document describes the process for migrating an exchange to a different base URL. 8 9 Motivation 10 ========== 11 12 The base URL of an exchange is a static property of the exchange, and it is not 13 intended to be changed. However, there are still scenarios where changing it is 14 required. 15 16 Requirements 17 ============ 18 19 * Existing wallets should continue working with minimal disruption 20 21 Proposed Solution 22 ================= 23 24 The proposed migration strategy works automatically / without user intervention 25 *only* for wallets. Merchants are required to add an entry for the new exchange 26 base URL to their configuration. 27 28 Wallet Support 29 -------------- 30 31 To support automatic migration, wallet-core has a list of *migration plans*. Each migration plan 32 is a tuple ``(oldExchangeBaseUrl, newExchangeBaseUrl)``. 33 34 Once the wallet detects that a migration is required, it executes the following steps: 35 36 1. Replace all occurrences of the old exchange base URL with the new exchange base URL in the wallet database. 37 2. Add a migration log entry to the database with ``(oldExchangeBaseUrl, newExchangeBaseUrl, migrationTimestamp)`` 38 39 The wallet runs a migration check when one of the following conditions applies: 40 41 * C1 (unavaliable exchange): 42 43 * The wallet updates an exchange entry (manually or scheduled), requests ``/keys``, and encounters 44 either an error response. 45 exchange entry. 46 * There is a migration plan for the old exchange to a new exchange. 47 * The new exchange returns a well-formed ``/keys`` response with a ``base_url`` that matches 48 the new exchange base URL 49 50 * C2 (mismatching base URL): 51 52 * The wallet updates an exchange entry (manually or scheduled), requests ``/keys``, and 53 the ``base_url`` of the ``/keys`` response do not match the base URL of the 54 exchange entry. 55 * There is a migration plan for the old exchange to a new exchange. 56 * The new exchange returns a well-formed ``/keys`` response with a ``base_url`` that matches 57 the new exchange base URL 58 59 Exchange Migration 60 ------------------ 61 62 If the new exchange base URL is also served by a new host, the following 63 data needs to be transferred: 64 65 1. The exchange postgresql database 66 2. (Optional) The exchange software security module keys, including denomination 67 signing keys. 68 69 If step (2) is omitted, the exchange will issue new signing and denomination keys, 70 which will in turn need to be signed by the offline key. 71 72 Overall Migration Steps 73 ----------------------- 74 75 1. Add a migration plan record (from old to new exchange base URL) in wallet-core. 76 2. Deploy all wallets with updated wallet-core. 77 3. Wait for some grace period to allow users time to update. 78 4. Do the following steps in parallel: 79 80 * Establish a reverse proxy from the old exchange URL to the new exchange base URL 81 * Migrate the exchange to the new base URL 82 83 5. Leave the reverse proxy from the old to new exchange in place for the validity 84 of the ``/keys`` response (typically one week). 85 86 During step (4), there will be minor downtime until both sub-steps have been 87 completed. 88 89 90 Definition of Done 91 ================== 92 93 N/A 94 95 Alternatives 96 ============ 97 98 * Do not support migrations 99 * Allow the exchange itself to announce the migration 100 101 * Technically complex, requires signature or has bad security implications 102 103 Drawbacks 104 ========= 105 106 * The merchant still needs to manually add the new exchange 107 * Complexity 108 109 Discussion / Q&A 110 ================ 111 112 (This should be filled in with results from discussions on mailing lists / personal communication.)