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