docs(assets-controller): add architecture diagrams under docs-temp

[Prithpal-Sooriya]

Explanation

Exploratory: adds a docs-temp/ folder inside the new packages/assets-controller package containing architecture diagrams that explain the controller's middleware, pipelines, fallback behaviour and token filtering. Diagrams were authored as JSON specs and rendered with the Archify skill.

Documentation-only. package.json publishes dist/ only, so nothing here is built, published, or imported.

Diagrams

Diagram	Kind	Question it answers
01-component-map	architecture	What exists, how callers reach it, and which data source claims which chain
02-fetch-pipeline	workflow	What getAssets awaits, and what it defers to a background lane
03-fallback-cascade	sequence	How one EVM chain degrades from Accounts API to RPC to per-asset calls
04-tracking-lifecycle	lifecycle	Why tracking is or is not running, and what stop and destroy each release
05-evm-rpc-dataflow	dataflow	How tracked state becomes one aggregate3 call and then decoded balances
06-event-stack	workflow	How handleAssetsUpdate composes a different middleware stack per source
07-token-filtering	workflow	The three moments a spam token can be filtered out, and what each removes
08-spam-verdict	dataflow	How one candidate token turns into a keep or drop verdict
09-visibility-gate	workflow	Why a token that is in state still does not come back from a read

The diagrams pair up. 02 and 06 are the two halves of the middleware architecture: 02 is the fetch stack a caller drives, 06 is the event stack an incoming update drives. 07, 08 and 09 cover filtering: 07 is when a token is judged as spam and 08 is how that verdict is reached, both on the write path; 09 is the separate read path that decides what a caller gets back.

Each diagram ships in four forms — the .json source, a self-contained interactive .html viewer (guided views, light/dark, hover focus), a flat .png, and a self-contained .svg. The PNG and SVG are exported from the delivered viewer, so the image always matches the validated artifact.

Component map

Event stack composition

Where a spam token gets filtered out

Spam verdict

Read path visibility gate

What the filtering diagrams say

07-token-filtering puts the three write-path filtering moments side by side as three lanes, because each answers "when" differently:

• On a websocket push — TokenDataSource.occurrenceFilterMiddleware, added to the event stack only for AccountActivityDataSource and only with basic functionality on. It judges brand-new EVM ERC-20s before DetectionMiddleware, so a below-floor airdrop is never detected, enriched, priced or persisted.
• In the enrichment stage — TokenDataSource.assetsMiddleware, inside the parallel Token ∥ Price stage. This is the one filter both the fetch stack and the event stack share.
• On keyring unlock — cleanSpamAssets, run from the KeyringController:unlock handler before #updateActive(), gated on unlocked + basic functionality + assetsUnifyState.useUnlockCleanup. It is the only pass that edits state that was already saved.

The failure modes differ on purpose and the diagram calls this out: both pipeline filters fail open (a Token API error keeps every candidate), while the unlock sweep deletes nothing when a call fails.

08-spam-verdict follows a single candidate through the decision: the exemption list (native assets, custom assets, balance-only heals, staking contracts and mUSD), then the split into the EVM occurrence floor from /v1/suggestedOccurrenceFloors (default 3) versus the non-EVM Blockaid scan via PhishingController:bulkScanTokens, then what a drop actually removes — including the stub metadata, which has to go so the token cannot look known and be exempted as a heal on the next pass.

09-visibility-gate covers the other axis, because "filtered" also means "in state but not returned". #getAssetFromState re-evaluates four gates on every read — balance present, metadata present, assetPreferences.hidden unset, and chain in scope (enabled network, and not a native token on a chain that has none) — and the aggregate balance selectors apply the same hidden and enabled-network rules. None of these delete anything, so a hidden row keeps refreshing in the background.

Verification

All nine pass archify deliver at the showcase quality profile (9/9 artifact checks, 0 composition errors). All except 04-tracking-lifecycle also pass archify visual-check containment at 1440×900, 1600×1000, 1920×1080 and 2048×1320 in both themes. The lifecycle renderer pins its three band rows to fixed y coordinates, which gives it a vertical budget that cannot fit a 1440px-wide desktop viewport without the page scrolling; Archify's own bundled lifecycle example overflows the same way. The diagram itself renders correctly — only the page scrolls.

Repo checks run: oxfmt --check (repo-wide), eslint, constraints, readme-content:check, codeowners:check, and the package's changelog:validate.

Note on .oxfmtrc.json

The delivered .html viewers are generated artifacts whose bytes are checksummed by archify, so one ignorePatterns entry (packages/*/docs-temp/*.html) keeps yarn lint:misc from reformatting them.

References

n/a — exploratory documentation.

Checklist

• I've updated the test suite for new or updated code as appropriate — n/a, documentation only
• I've updated documentation (JSDoc, README.md) as appropriate
• I've highlighted breaking changes using the "BREAKING" category above as appropriate — none
• I've prepared draft pull requests for clients and consumer packages to resolve any breaking changes — n/a

_{To show artifacts inline, enable in settings.}

  

[Prithpal-Sooriya]

@cursor can you also use the skill to generate how and when tokens are filtered (where in the middleware flow, and also unlock event, etc)

[cursor]

Added three diagrams for token filtering, pushed to #10134. Reading the code turned up two genuinely different kinds of filtering, so I split them rather than forcing one diagram to carry both.

07-token-filtering answers "when", as three lanes side by side, because there are three separate moments and they behave differently:

• On a websocket push — TokenDataSource.occurrenceFilterMiddleware. Only added to the event stack for AccountActivityDataSource, and only with basic functionality on. The important part is that it sits before DetectionMiddleware, so a below-floor airdrop is never detected, enriched, priced or persisted at all.
• In the enrichment stage — TokenDataSource.assetsMiddleware, inside the parallel Token ∥ Price stage. This is the only filter both the fetch stack and the event stack share.
• On keyring unlock — cleanSpamAssets, from the KeyringController:unlock handler before #updateActive(). It is the only pass that touches state that was already saved.

The two failure modes are opposite and the diagram calls that out: both pipeline filters fail open, so a Token API error keeps every candidate, while the unlock sweep deletes nothing if a call fails.

08-spam-verdict answers "how", following one candidate through the decision: the exemption list, then the split into the EVM occurrence floor from /v1/suggestedOccurrenceFloors (default 3) versus the non-EVM Blockaid scan via PhishingController:bulkScanTokens, then what a drop actually removes. That last part includes the stub metadata, which has to go so the token cannot look known and get exempted as a balance heal on the next pass.

09-visibility-gate is the one I added after noticing that "filtered" also means "in state but not returned". #getAssetFromState re-checks four gates on every read — balance present, metadata present, assetPreferences.hidden unset, and chain in scope — and the aggregate balance selectors apply the same hidden and enabled-network rules. None of these delete anything, which is worth being explicit about: hideAsset only sets a preference, so the balance keeps getting polled while the row is gone.

All three pass archify deliver at the showcase profile and visual-check containment in both themes at all four desktop viewports, and each ships as JSON source, interactive HTML, PNG and SVG like the existing six. oxfmt --check, eslint and the package changelog validation are all clean.