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 the public getAssets lifecycle and adds UI-facing state with concurrency rules; mistakes could show wrong loading indicators or affect overlapping refresh behavior, though scope is limited to forced fetches and nothing is persisted.

Overview
Adds transient, non-persisted controller state so the UI can tell when specific accounts are waiting on a forced assets fetch: assetsLoadingStatus ('loading' | 'loaded') plus internal assetsLoadingTokens to handle overlapping getAssets calls safely.

A @trackAssetsLoading decorator wraps getAssets and only updates this state when forceUpdate: true (cache reads and background-style calls are ignored). Accounts are marked loading at call start and settled to loaded in a finally block (including on failure); older in-flight fetches cannot flip an account to loaded while a newer fetch still owns the token.

New exports: AssetsLoadingStatus and loading selectors (getAccountLoadingStatus, isAccountLoading, group/selected-group helpers). State metadata keeps loading fields off persisted snapshots (persist: false for both).

Also fixes the temporary tempHealAssetsInfoMetadata constructor path to merge healed fields via a full state spread instead of passing a partial object into update.

^{Reviewed by Cursor Bugbot for commit d02e8ba. 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.}