Add deterministic engine-scheduler tests

The fake plugin reports each makeCurrencyEngine call through an
onEngineCreate hook, so tests can observe creation order. Cases cover
concurrency-limited draining, waitForCurrencyWallet bumping a queued
wallet to the front, cold wallets bypassing the queue, a deleted queued
wallet giving up its place, and balanceMap identity across unchanged
balance reports.

Author: j0ntz

CHANGELOG.md

@@ -3,8 +3,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.
+- 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)
 

test/core/currency/wallet/engine-scheduler.test.ts

@@ -0,0 +1,237 @@
+import { expect } from 'chai'
+import { afterEach, beforeEach, describe, it } from 'mocha'
+
+import { engineSchedulerConfig } from '../../../../src/core/currency/wallet/engine-scheduler'
+import { walletCacheSaverConfig } from '../../../../src/core/currency/wallet/wallet-cache-file'
+import { EdgeContext, makeFakeEdgeWorld } from '../../../../src/index'
+import { snooze } from '../../../../src/util/snooze'
+import {
+  createEngineGate,
+  fakePluginTestConfig
+} from '../../../fake/fake-currency-plugin'
+import { fakeUser } from '../../../fake/fake-user'
+
+const contextOptions = { apiKey: '', appId: '', deviceDescription: 'iphone12' }
+const quiet = { onLog() {} }
+
+// Generous wait for the throttled cache saver (50ms in tests) to write:
+const SAVE_WAIT_MS = 300
+
+// Short wait to prove something has *not* happened:
+const RACE_WAIT_MS = 150
+
+interface MultiWalletWorld {
+  context: EdgeContext
+  walletIds: string[]
+}
+
+/**
+ * Logs in once, pads the account out to at least `count` fakecoin
+ * wallets, waits for their cache files to persist, and logs out.
+ * The next login on the returned context is a warm start where every
+ * wallet's engine startup enters the scheduler queue. The returned
+ * ids cover EVERY wallet in the account (the fake user starts with
+ * two), so length comparisons against engine-creation counts hold.
+ */
+async function makeMultiWalletWorld(count: number): Promise<MultiWalletWorld> {
+  const world = await makeFakeEdgeWorld([fakeUser], quiet)
+  const context = await world.makeEdgeContext({
+    ...contextOptions,
+    plugins: { fakecoin: true }
+  })
+
+  const account = await context.loginWithPIN(fakeUser.username, fakeUser.pin)
+  const walletIds = account.activeWalletIds.filter(
+    walletId => account.getWalletInfo(walletId)?.type === 'wallet:fakecoin'
+  )
+  if (walletIds.length !== account.activeWalletIds.length) {
+    throw new Error('Broken test account: unexpected non-fakecoin wallets')
+  }
+  while (walletIds.length < count) {
+    const wallet = await account.createCurrencyWallet('wallet:fakecoin', {
+      fiatCurrencyCode: 'iso:USD',
+      name: `Wallet ${walletIds.length}`
+    })
+    walletIds.push(wallet.id)
+  }
+
+  // Let the throttled saver persist each wallet's cache file:
+  await snooze(SAVE_WAIT_MS)
+  await account.logout()
+
+  return { context, walletIds }
+}
+
+/** Returns a sorted copy, so order-insensitive comparisons read cleanly. */
+function sorted(list: string[]): string[] {
+  return [...list].sort((a, b) => a.localeCompare(b))
+}
+
+/** Polls until `condition` holds, or fails the test after ~5s. */
+async function pollUntil(condition: () => boolean): Promise<void> {
+  for (let i = 0; i < 100; ++i) {
+    if (condition()) return
+    await snooze(50)
+  }
+  throw new Error('Timed out waiting for a test condition')
+}
+
+describe('engine scheduler', function () {
+  beforeEach(function () {
+    fakePluginTestConfig.engineGate = undefined
+    fakePluginTestConfig.onEngineCreate = undefined
+    walletCacheSaverConfig.throttleMs = 50
+  })
+
+  afterEach(function () {
+    fakePluginTestConfig.engineGate = undefined
+    fakePluginTestConfig.onEngineCreate = undefined
+    walletCacheSaverConfig.throttleMs = 5000
+    engineSchedulerConfig.concurrency = 8
+  })
+
+  it('runs cached startup work at the configured concurrency', async function () {
+    this.timeout(15000)
+    const { context, walletIds } = await makeMultiWalletWorld(3)
+
+    engineSchedulerConfig.concurrency = 1
+    const created: string[] = []
+    fakePluginTestConfig.onEngineCreate = walletId => created.push(walletId)
+    const { gate, release } = createEngineGate()
+    fakePluginTestConfig.engineGate = gate
+
+    const account = await context.loginWithPIN(fakeUser.username, fakeUser.pin)
+
+    // Every wallet emits from its cache while the queue is stuck:
+    await pollUntil(() =>
+      walletIds.every(walletId => account.currencyWallets[walletId] != null)
+    )
+
+    // The gate blocks the slot holder inside `makeCurrencyEngine`,
+    // so with one slot, exactly one creation can have begun:
+    await snooze(RACE_WAIT_MS)
+    expect(created.length).equals(1)
+
+    // Releasing the gate drains the queue one wallet at a time,
+    // and every engine still starts:
+    release()
+    await pollUntil(() => created.length === walletIds.length)
+    expect(sorted(created)).deep.equals(sorted(walletIds))
+    await account.logout()
+  })
+
+  it('waitForCurrencyWallet moves a queued wallet to the front', async function () {
+    this.timeout(15000)
+    const { context, walletIds } = await makeMultiWalletWorld(4)
+
+    engineSchedulerConfig.concurrency = 1
+    const created: string[] = []
+    fakePluginTestConfig.onEngineCreate = walletId => created.push(walletId)
+    const { gate, release } = createEngineGate()
+    fakePluginTestConfig.engineGate = gate
+
+    const account = await context.loginWithPIN(fakeUser.username, fakeUser.pin)
+    await pollUntil(() =>
+      walletIds.every(walletId => account.currencyWallets[walletId] != null)
+    )
+    await pollUntil(() => created.length === 1)
+
+    // Pick the wallet at the back of the line and ask for it:
+    const queued = walletIds.filter(walletId => !created.includes(walletId))
+    const target = queued[queued.length - 1]
+    await account.waitForCurrencyWallet(target)
+
+    // Once the slot frees up, the bumped wallet goes next:
+    release()
+    await pollUntil(() => created.length === walletIds.length)
+    expect(created[1]).equals(target)
+    await account.logout()
+  })
+
+  it('cold wallets skip the queue entirely', async function () {
+    this.timeout(15000)
+    const { context, walletIds } = await makeMultiWalletWorld(3)
+
+    // Erase the cache files, making the next login a cold start.
+    // Let the login's own cache save settle first, so nothing
+    // rewrites the files after the deletes:
+    const account = await context.loginWithPIN(fakeUser.username, fakeUser.pin)
+    await account.waitForAllWallets()
+    await snooze(SAVE_WAIT_MS)
+    for (const walletId of walletIds) {
+      const wallet = await account.waitForCurrencyWallet(walletId)
+      await wallet.localDisklet.delete('walletCache.json')
+    }
+    await account.logout()
+
+    engineSchedulerConfig.concurrency = 1
+    const created: string[] = []
+    fakePluginTestConfig.onEngineCreate = walletId => created.push(walletId)
+    const { gate, release } = createEngineGate()
+    fakePluginTestConfig.engineGate = gate
+
+    // Cold wallets cannot emit until their startup work runs,
+    // so they bypass the queue: every creation begins even though
+    // the single queue slot never opens:
+    const account2 = await context.loginWithPIN(fakeUser.username, fakeUser.pin)
+    await pollUntil(() => created.length === walletIds.length)
+
+    release()
+    await account2.waitForAllWallets()
+    await account2.logout()
+  })
+
+  it('a wallet deleted while queued gives up its place in line', async function () {
+    this.timeout(15000)
+    const { context, walletIds } = await makeMultiWalletWorld(3)
+
+    engineSchedulerConfig.concurrency = 1
+    const created: string[] = []
+    fakePluginTestConfig.onEngineCreate = walletId => created.push(walletId)
+    const { gate, release } = createEngineGate()
+    fakePluginTestConfig.engineGate = gate
+
+    const account = await context.loginWithPIN(fakeUser.username, fakeUser.pin)
+    await pollUntil(() =>
+      walletIds.every(walletId => account.currencyWallets[walletId] != null)
+    )
+    await pollUntil(() => created.length === 1)
+
+    // Delete a wallet that is still waiting in the queue:
+    const queued = walletIds.filter(walletId => !created.includes(walletId))
+    const deleted = queued[0]
+    await account.changeWalletStates({ [deleted]: { deleted: true } })
+
+    // The queue keeps moving: the deleted wallet never creates an
+    // engine, and the remaining wallets still get theirs:
+    release()
+    const survivors = walletIds.filter(walletId => walletId !== deleted)
+    await pollUntil(() => created.length === survivors.length)
+    expect(sorted(created)).deep.equals(sorted(survivors))
+    await snooze(RACE_WAIT_MS)
+    expect(created.includes(deleted)).equals(false)
+    await account.logout()
+  })
+
+  it('unchanged balances keep the same balanceMap object', async function () {
+    this.timeout(15000)
+    const { context, walletIds } = await makeMultiWalletWorld(1)
+
+    const account = await context.loginWithPIN(fakeUser.username, fakeUser.pin)
+    const wallet = await account.waitForCurrencyWallet(walletIds[0])
+    await account.currencyConfig.fakecoin.changeUserSettings({ balance: 20 })
+    await pollUntil(() => wallet.balanceMap.get(null) === '20')
+
+    // Re-reporting the same balance must not produce a new map:
+    const before = wallet.balanceMap
+    await account.currencyConfig.fakecoin.changeUserSettings({ balance: 20 })
+    await snooze(RACE_WAIT_MS)
+    expect(wallet.balanceMap).equals(before)
+
+    // A real change still lands:
+    await account.currencyConfig.fakecoin.changeUserSettings({ balance: 21 })
+    await pollUntil(() => wallet.balanceMap.get(null) === '21')
+    expect(wallet.balanceMap).not.equals(before)
+    await account.logout()
+  })
+})

test/fake/fake-currency-plugin.ts

@@ -37,10 +37,17 @@ export interface FakePluginTestConfig {
    * so "before the engine exists" is a deterministic state in tests.
    */
   engineGate?: Promise<void>
+
+  /**
+   * If set, receives each wallet id as its `makeCurrencyEngine` call
+   * begins (before any gate), so tests can observe creation order.
+   */
+  onEngineCreate?: (walletId: string) => void
 }
 
 export const fakePluginTestConfig: FakePluginTestConfig = {
-  engineGate: undefined
+  engineGate: undefined,
+  onEngineCreate: undefined
 }
 
 /**
@@ -444,6 +451,9 @@ export function makeFakeCurrencyPlugin(
       walletInfo: EdgeWalletInfo,
       opts: EdgeCurrencyEngineOptions
     ): Promise<EdgeCurrencyEngine> {
+      if (fakePluginTestConfig.onEngineCreate != null) {
+        fakePluginTestConfig.onEngineCreate(walletInfo.id)
+      }
       if (fakePluginTestConfig.engineGate != null) {
         await fakePluginTestConfig.engineGate
       }