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

CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## Unreleased
 
+- added: Account-level `accountCache.json` with the wallet states, custom tokens, and plugin settings the account boot needs. A warm login seeds Redux from it and emits the account right after the currency plugins load, before the account repo syncs, and every cached wallet then seeds from a single bulk dispatch. The deferred file loads overwrite the seeded state authoritatively, and user changes made during the window win over the values those loads read. First login (no cache) boots exactly as before.
+- 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.
+- added: Cached wallets' engine startup is staggered through a limited-concurrency queue (8 at a time) instead of all racing at login. Asking for a wallet via `waitForCurrencyWallet`, calling an engine- or storage-backed method, or un-pausing it moves it to the front of the queue. Wallets without a cache skip the queue, so first login is unaffected.
+- 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.
+- changed: `EdgeCurrencyWallet.balanceMap` keeps its object identity when an engine re-reports an unchanged balance.
+
 ## 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/account/account-api.ts

@@ -31,6 +31,7 @@ import {
 } from '../../types/types'
 import { makeEdgeResult } from '../../util/edgeResult'
 import { base58 } from '../../util/encoding'
+import { bumpEngineQueue } from '../currency/currency-selectors'
 import { saveWalletSettings } from '../currency/wallet/currency-wallet-files'
 import { getPublicWalletInfo } from '../currency/wallet/currency-wallet-pixie'
 import {
@@ -724,6 +725,10 @@ export function makeAccountApi(ai: ApiInput, accountId: string): EdgeAccount {
     },
 
     async waitForCurrencyWallet(walletId: string): Promise<EdgeCurrencyWallet> {
+      // Asking for a wallet is the "the user wants this one" signal,
+      // so move its engine startup to the front of the queue:
+      bumpEngineQueue(ai, walletId)
+
       return await new Promise((resolve, reject) => {
         const check = (): void => {
           const wallet = this.currencyWallets[walletId]

src/core/account/account-cache-file.ts

@@ -0,0 +1,17 @@
+import { makeJsonFile } from '../../util/file-helpers'
+import { asAccountCacheFile } from './account-cleaners'
+
+/**
+ * Cached account boot state, stored on the account's local disklet.
+ * See `asAccountCacheFile` for the schema.
+ */
+export const ACCOUNT_CACHE_FILE = 'accountCache.json'
+export const accountCacheFile = makeJsonFile(asAccountCacheFile)
+
+/**
+ * Tuning for the account boot-state cache saver.
+ * Tests override the throttle to run quickly.
+ */
+export const accountCacheSaverConfig = {
+  throttleMs: 5000
+}

src/core/account/account-cleaners.ts

@@ -4,11 +4,20 @@ import {
   asNumber,
   asObject,
   asOptional,
-  asString
+  asString,
+  asValue,
+  Cleaner
 } from 'cleaners'
 
 import { asBase16 } from '../../types/server-cleaners'
-import { EdgeDenomination, EdgeToken } from '../../types/types'
+import {
+  EdgeDenomination,
+  EdgePluginMap,
+  EdgeToken,
+  EdgeTokenMap,
+  EdgeWalletState,
+  EdgeWalletStates
+} from '../../types/types'
 import { asJsonObject } from '../../util/file-helpers'
 import { SwapSettings } from './account-types'
 
@@ -92,3 +101,42 @@ export const asGuiSettingsFile = asObject({
 export const asCustomTokensFile = asObject({
   customTokens: asObject(asObject(asEdgeToken))
 })
+
+/**
+ * Cached account boot state, stored on the account's local disklet.
+ * This is what the deferred account file loads would produce,
+ * so wallet pixies can start before the account repo syncs.
+ * Values are last-known and explicitly allowed to be stale;
+ * the authoritative loads overwrite them within seconds.
+ * Never contains private key material: wallet keys stay in the
+ * encrypted login stash, which is already in memory at login.
+ * Plugin settings are deliberately excluded: unlike wallet states
+ * and token definitions, they can hold credentials (custom node
+ * auth, API keys), which must never leave the encrypted repo.
+ */
+export interface AccountCacheFile {
+  version: 1
+  customTokens: EdgePluginMap<EdgeTokenMap>
+  /**
+   * True when the account has legacy Airbitz-repo wallets. Their
+   * wallet infos cannot be cached (they contain private keys), so
+   * such accounts boot cold rather than briefly hiding wallets.
+   */
+  legacyWallets: boolean
+  walletStates: EdgeWalletStates
+}
+
+const asEdgeWalletState = asObject<EdgeWalletState>({
+  archived: asOptional(asBoolean),
+  deleted: asOptional(asBoolean),
+  hidden: asOptional(asBoolean),
+  migratedFromWalletId: asOptional(asString),
+  sortIndex: asOptional(asNumber)
+})
+
+export const asAccountCacheFile: Cleaner<AccountCacheFile> = asObject({
+  version: asValue(1),
+  customTokens: asObject(asObject(asEdgeToken)),
+  legacyWallets: asOptional(asBoolean, false),
+  walletStates: asObject(asEdgeWalletState)
+})

src/core/account/account-files.ts

@@ -42,6 +42,26 @@ function different(a: any, b: any): boolean {
   return false
 }
 
+/**
+ * Waits until the account's storage wallet exists. A cache-seeded
+ * login emits the account API object before `addStorageWallet` runs,
+ * so methods that touch the synced repo pend briefly instead of
+ * throwing during that window. Rejects if the account logs out.
+ */
+export function waitForAccountRepo(
+  ai: ApiInput,
+  accountId: string
+): Promise<unknown> {
+  return ai.waitFor(props => {
+    const accountState = props.state.accounts[accountId]
+    if (accountState == null) {
+      throw new Error('The account was logged out')
+    }
+    const { accountWalletInfo } = accountState
+    if (props.state.storageWallets[accountWalletInfo.id] != null) return true
+  })
+}
+
 /**
  * Loads the legacy wallet list from the account folder.
  */
@@ -148,6 +168,7 @@ export async function changeWalletStates(
   accountId: string,
   newStates: EdgeWalletStates
 ): Promise<void> {
+  await waitForAccountRepo(ai, accountId)
   const { accountWalletInfo, walletStates } = ai.props.state.accounts[accountId]
   const disklet = getStorageWalletDisklet(ai.props.state, accountWalletInfo.id)
 
@@ -189,7 +210,11 @@ export async function changeWalletStates(
 
   ai.props.dispatch({
     type: 'ACCOUNT_CHANGED_WALLET_STATES',
-    payload: { accountId, walletStates: { ...walletStates, ...toWrite } }
+    payload: {
+      accountId,
+      walletStates: { ...walletStates, ...toWrite },
+      changedIds: walletIds
+    }
   })
 }
 
@@ -202,6 +227,7 @@ export async function changePluginUserSettings(
   pluginId: string,
   userSettings: object
 ): Promise<void> {
+  await waitForAccountRepo(ai, accountId)
   const { accountWalletInfo } = ai.props.state.accounts[accountId]
   const disklet = getStorageWalletDisklet(ai.props.state, accountWalletInfo.id)
 
@@ -237,6 +263,7 @@ export async function changeSwapSettings(
   pluginId: string,
   swapSettings: SwapSettings
 ): Promise<void> {
+  await waitForAccountRepo(ai, accountId)
   const { accountWalletInfo } = ai.props.state.accounts[accountId]
   const disklet = getStorageWalletDisklet(ai.props.state, accountWalletInfo.id)