feat(frontend): cache and page ERC20 transaction history

[sbpublic]

Motivation

An ERC20 token view re-fetched the token's entire transfer history from Etherscan on every single load — loadErcTransactions never touched the backend cache, which reached only the native EVM and Solana paths. That is one tokentx request per token per load against a 5-call/second budget, plus the spam filter's RPC calls, and history was capped at whatever one response returns: older transfers were unreachable forever, because nothing stored them.

Implements docs/ai/spec-driven-development/specs/2026-08-14-impr-cache-erc20-transaction-history.md (added in #13729). Second of the two PRs the spec's Delivery section describes: #13729 carried the behaviour-neutral prep, this one is the change.

Changes

• Stored history for ERC20 and vault tokens. The load reads one stored page, asks Etherscan only for transfers newer than the newest stored block, shows both, and saves what it fetched. Collectibles have no backend key, so they neither read the cache nor take an incremental start block — structurally unchanged, not just unchanged by accident.
• Paging dispatches on the token. Older history came from txlist, which answers for the chain's own coin; running it for a token would have appended another asset's transactions under that token. A fungible token now pages tokentx bounded by the oldest row on screen. loadNextEthUserTransactions takes the token instead of three ids and a cursor, since all four follow from it.
• One place derives the backend key, lowercasing the contract address. The backend holds it as a bare String and compares it byte-for-byte, while our token list is checksummed and Etherscan is lowercase — two casings would be two histories of one token.
• Saves are chunked. save_user_transactions rejects a batch over 500 outright instead of storing part of it. The native path never hit this because it only ever offers an incremental slice; a token's first save is its whole history. Chunked in the shared service, since the limit is the backend's rather than any one chain's.
• The scroll gate now admits anything with a backend storage key.
• Vault mint/burn normalisation is applied for display only. The backend keeps rows as the chain reported them, so stored rows pass through the convention on the way out, not just fetched ones.
• PRODUCT.md gains a transaction-history section — it had none for either path.
• A refresh keeps pages already scrolled in. Once a token's load is incremental, the batch is the newest stored page plus anything newer, so replacing the store slot with it would discard every older page the user scrolled in — and the refresh timer runs this path every 30 seconds. Cached tokens prepend; collectibles keep replacing, since their history is still fetched whole and there the replacement is a real refresh. This is the same defect fix(frontend): keep scrolled-in transaction history across the periodic refresh #13732 fixes on the native path, which this PR would otherwise reintroduce for ERC20.

Divergence from the spec: none in substance. The spec's loadOlderFromEtherscan branch became a shared erc-transfers.services.ts so the initial load and the paging path share one spam-filtered fetch, rather than each holding its own copy.

#13732 has since merged to main and been merged in here. It conflicted only on the store-max helper's name, kept as maxBlockNumberInStore because it now serves the ERC path as well as the native one; hasStoredEthTransactions collapsed into a single declaration as intended.

Tests

• array.utils.spec.ts — chunk splits in order, handles an exact fit, an empty input, and a degenerate size without losing data.
• user-transactions.services.spec.ts (lib) — an oversized save is split into batches the backend accepts; a failing batch reports failure.
• user-transactions.utils.spec.ts (eth) — the key per token kind, the contract lowercased so one contract is never two histories, nothing for non-EVM or collectible tokens.
• eth-transactions.services.spec.ts — reads the stored page under the contract key, asks Etherscan only for newer transfers, shows stored and fetched together, keeps the cursor of the page below, saves under the contract key, and never reaches the backend for a collectible. Plus, for the refresh: pages already scrolled in survive it, the cursor is left alone once the list has been built, and a token that is not cached still has its list replaced. The refresh test's two sets of rows carry fixed, disjoint hashes rather than the mock's random ones, since the store deduplicates by hash.
• eth-user-transactions.services.spec.ts — pages tokentx rather than txlist, with the right endBlock; appends to the token's slot; reads and writes under the contract key; pages nothing for a collectible.
• EthTransactionsScroll.spec.ts — an ERC20 token pages like the chain coin; a collectible does not.
• npm run format, npm run lint -- --max-warnings 0, npm run check (0 errors), npm run check:tests (0 errors), and 3874 tests pass across tests/eth (plus the touched lib specs).

Not visually verified — it needs an account with more than one page of transfers on one token.

---

🤖 Generated with Claude Code — Claude Opus 5 (claude-opus-5)