feat(assets-controller): add transient per-account loading state for user-visible fetches

[Prithpal-Sooriya]

Description

Adds a transient, non-persisted per-account loading state to AssetsController, published only while assets are being fetched for specific user-visible UX moments (account switch, unlock), plus selectors for the UX layer to read it.

Problem

The UI has no signal for "an assets fetch is in flight because the user just did something" (switched accounts / unlocked the wallet). Balance state can't be used to infer this (stale balances are indistinguishable from fresh ones), and getAssets is called constantly in the background (polling, price/currency/tx refreshes) — so "any fetch in flight" is not the same as "the user is waiting".

Approach

• New state field: assetsLoadingStatus: Record<AccountId, AssetsLoadingTrigger> where AssetsLoadingTrigger = 'accountSwitch' | 'unlock'. A string-literal union was chosen over Record<_, boolean>: the key's presence already encodes "loading", the value tells the UI which moment is loading (so it can render the right skeleton/label), and the union is extensible for future triggers without a second field or a breaking change.
• Transient by construction: the field's state metadata is persist: false (with includeInStateLogs, includeInDebugSnapshot, usedInUi set). A restarted client always begins with no fetch in flight, so nothing is persisted and no migration is needed.
• Scoped opt-in: getAssets accepts a new optional trigger option. Only the two user-action call sites pass it — #handleAccountGroupChanged ('accountSwitch') and #runStartupRefresh ('unlock'). Every other getAssets caller (polling, price updates, tx confirmations, currency changes, network events) is unchanged and never publishes loading state, so the indicator cannot flap due to background work.
• Lifecycle in getAssets: the public method is now a thin wrapper — set the entries, try { await } finally { clear } — around the extracted, unchanged fetch pipeline (#getAssetsInternal). Entries are cleared conditionally (only if they still hold this fetch's trigger), so an older fetch settling can never clobber a newer fetch's marker for the same account.
• Selectors: getAccountLoadingStatus(state, accountId), isAccountLoading(state, accountId), getAccountsLoadingStatus(state), isAnyAccountLoading(state) are exported from the package index for the UX team, mirroring the existing selectors/balance.ts pattern.

getAssets complexity & decorator evaluation (design note)

The requested analysis of getAssets complexity and whether a TypeScript decorator would be cleaner:

• getAssets was already a long, multi-stage pipeline (force-update fast/slow paths, middleware chain, merge/replace modes). The loading concern is not deeply entangled with that logic — it is a strict request-scoped lifecycle (set → run → clear). Modeling it inside the pipeline body would have raised cyclomatic complexity and added error-handling paths through ~180 lines that today have none.
• A decorator (@withLoadingStatus) was evaluated and rejected:
  • No precedent: there are zero decorators in the entire monorepo; the codebase's established idiom for wrapping controller methods is functional composition (e.g. withTrace in src/utils/trace.ts). Introducing the first decorator raises toolchain risk (the repo's tsconfig does not enable experimentalDecorators; the TC39 stage-3 decorators proposal has evolving semantics) and review cost.
  • Not a generic concern: the wrapper is parameter-aware (per-account keys from the first argument, trigger from an options bag property) — a decorator would need bespoke argument inspection anyway, buying no reuse for other methods.
  • Discoverability: decorators hide control flow from readers and from the generated action types; an explicit wrapper keeps the lifecycle visible at the method signature, which is what AssetsController-method-action-types.ts (auto-generated from AssetsController['getAssets']) naturally picks up.
• The chosen standard implementation adds ~10 lines to getAssets and two small private helpers, with zero cyclomatic-complexity growth in the fetch pipeline itself (its body moved verbatim to #getAssetsInternal). This is the smallest diff that satisfies the lifecycle requirement while staying within repo idioms.

Related issues

• https://consensyssoftware.atlassian.net/browse/ASSETS-3907

Checklist

• I've updated the changelog (Unreleased → Added, packages/assets-controller/CHANGELOG.md).
• Tests added/updated: 7 new controller tests covering set/clear per trigger, no-trigger fetches, event wiring (accountSwitch, unlock), stateChanged emission, non-persistence via deriveStateFromMetadata, and concurrent-fetch marker safety; 12 selector tests.
• yarn workspace @metamask/assets-controller run test — 1034/1034 passing.
• Monorepo yarn build (type check) passing.
• yarn eslint … --fix --prune-suppressions and yarn lint:misc:check clean on touched files; AssetsController-method-action-types.ts regenerated via yarn workspace @metamask/assets-controller run messenger-action-types:generate.

Test plan

1. yarn workspace @metamask/assets-controller run test — all suites pass.
2. Gated-client unit tests observe assetsLoadingStatus mid-flight (Accounts API calls frozen via an armed gate) and after release — entries present exactly while the fetch is in flight and cleared on settle.
3. deriveStateFromMetadata test asserts the field is excluded from persisted state.

---

Note

Medium Risk
Changes getAssets lifecycle and new UI-facing state around fetch concurrency; behavior is scoped to forced updates but affects account-switch/unlock UX paths.

Overview
Adds transient, non-persisted per-account loading signals on AssetsController so the UI can tell when a forced assets fetch is in flight.

New state includes assetsLoadingStatus ('loading' | 'loaded') and internal assetsLoadingTokens to attribute in-flight work. getAssets is wrapped with @trackAssetsLoading, which marks requested accounts as loading at the start of forceUpdate: true calls and settles them to 'loaded' in a finally block (including on failure). Cache-only calls without forceUpdate are not tracked, and overlapping fetches cannot clear a newer invocation’s marker.

Loading selectors are exported (getAccountLoadingStatus, isAccountLoading, group/selected-group helpers). Metadata marks assetsLoadingStatus as UI-visible but persist: false. Tests cover account switch, unlock, queued switches, concurrent fetches, failures, and persistence exclusion.

Also adjusts the temporary ASSETS-3346 heal path to merge healed fields via a spread inside update.

^{Reviewed by Cursor Bugbot for commit 14b4d9d. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Stale Bugbot comment from a previous run.

[Prithpal-Sooriya]

Look through self-review comments

[cursor]

Stale Bugbot comment from a previous run.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 5355bd1. Configure here.}