Wallet cache v2 phase 1: emit currency wallets before their engines exist

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+- added: Per-wallet `walletCache.json` with each wallet's name, fiat code, enabled token IDs, and last-known balances. Currency wallets now emit their API objects as soon as this cache loads, before their engines exist, so the GUI can render the wallet list immediately at login. Engine-backed methods wait for the engine internally and reject if it fails or the wallet is deleted. First login (no cache) behaves exactly as before.
+- changed: `waitForCurrencyWallet` and `waitForAllWallets` now resolve when the wallet object exists, which can be before its engine loads.
+- changed: `wallet.otherMethods` is `{}` until the wallet's engine loads, then switches to the engine's methods.
+
 ## 2.47.1 (2026-07-17)
 
 - fixed: Revert `@nymproject/mix-fetch` to v1 (1.4.4), restoring the pinned gateway and network requester. The v2 stack shipped in 2.47.0 fails to complete small HTTPS JSON-RPC requests through most exit nodes and its exit-node auto-discovery rarely converges, which left wallets with NYM privacy enabled unable to sync or send.

src/core/actions.ts

@@ -1,4 +1,5 @@
 import {
+  EdgeBalanceMap,
   EdgeCorePlugin,
   EdgeCorePluginsInit,
   EdgeCurrencyTools,
@@ -271,6 +272,18 @@ export type RootAction =
         tools: Promise<EdgeCurrencyTools>
       }
     }
+  | {
+      // Called when the wallet's UI-state cache file loads from disk,
+      // seeding Redux before the engine exists.
+      type: 'CURRENCY_WALLET_CACHE_LOADED'
+      payload: {
+        balanceMap: EdgeBalanceMap
+        enabledTokenIds: string[]
+        fiatCurrencyCode: string
+        name: string | null
+        walletId: string
+      }
+    }
   | {
       type: 'CURRENCY_WALLET_CHANGED_PAUSED'
       payload: {

src/core/currency/currency-selectors.ts

@@ -28,20 +28,28 @@ export function getCurrencyMultiplier(
   return '1'
 }
 
+/**
+ * Throws if a wallet has been deleted mid-wait or its engine has failed,
+ * so `waitFor` conditions surface those as rejections instead of hangs.
+ */
+export function checkCurrencyWallet(props: RootProps, walletId: string): void {
+  // If the wallet id doesn't even exist, bail out:
+  if (props.state.currency.wallets[walletId] == null) {
+    throw new Error(`Wallet id ${walletId} does not exist in this account`)
+  }
+
+  // Throw the error if one exists:
+  const { engineFailure } = props.state.currency.wallets[walletId]
+  if (engineFailure != null) throw engineFailure
+}
+
 export function waitForCurrencyWallet(
   ai: ApiInput,
   walletId: string
 ): Promise<EdgeCurrencyWallet> {
   const out: Promise<EdgeCurrencyWallet> = ai.waitFor(
     (props: RootProps): EdgeCurrencyWallet | undefined => {
-      // If the wallet id doesn't even exist, bail out:
-      if (props.state.currency.wallets[walletId] == null) {
-        throw new Error(`Wallet id ${walletId} does not exist in this account`)
-      }
-
-      // Return the error if one exists:
-      const { engineFailure } = props.state.currency.wallets[walletId]
-      if (engineFailure != null) throw engineFailure
+      checkCurrencyWallet(props, walletId)
 
       // Return the API if that exists:
       if (props.output.currency.wallets[walletId] != null) {