fix(icons): show USDT0's icon, for new and existing users

[piyalbasu]

TL;DR

USDT0 shows no icon in the wallet, and once it has failed for a user it never comes back — not on reload, not on restart.

Two things cause it. USDT0 is carried by two of the default asset lists: Soroswap, with a direct HTTPS icon, and LOBSTR, with an ipfs.io gateway URL. That gateway serves the image to curl but returns 403 to a browser User-Agent, so an <img> can never load it. Icon lookup was keeping whichever list it read last, which handed the browser the one URL it cannot fetch. And when that image failed, the failure was recorded to disk as "this asset has no icon", which lookup reads as "already tried, don't look again" — a verdict that was only ever meant to last a session.

This makes the first matching list win, since the list order is the user's priority order, and makes the cache stop reporting those stale "no icon" records. Users already stuck recover on their first load after upgrading — no migration needed: the fresh lookup overwrites the old entry.

Four lines of production code.

Verifying

1. On master, hold USDT0:GATISXX6BZ6NC7IKQBY37CJD4SOZL3CYZJWXEDG6JVIY4WBS6KXJHN6Q on Mainnet and open the account view — no icon, and it stays missing across reloads.
2. Check the stored value in the service worker console:

   chrome.storage.local.get("cachedAssetIcons", (r) =>
     console.log(r.cachedAssetIcons["USDT0:GATISXX6BZ6NC7IKQBY37CJD4SOZL3CYZJWXEDG6JVIY4WBS6KXJHN6Q"])
   );

   → null
3. Load this branch and open the account view. The icon appears, and the same check returns "https://docs.usdt0.to/downloads/usdt0/Symbol_USDT0_Secondary.png" — the stale record is gone from disk.

Confirmed end to end in a local build against the prod backend.

---

Implementation details (for agents)

Root cause

1. getIconFromTokenLists iterated the lists in order, but its break only exited the inner record loop. The outer loop over lists ran to completion, so the last matching list overwrote every earlier match. Ordering is meant to be priority (stellar.expert → Soroswap → LOBSTR), so USDT0 resolved to LOBSTR's ipfs.io URL instead of Soroswap's docs.usdt0.to.
2. https://ipfs.io/ipfs/bafkreifaalohkkikosp27qp6qczwaffwseejvoaafkgv7ahyrqvejmpqou returns 200 to curl and 403 to a browser User-Agent — isolated to the UA alone, other headers make no difference. So the <img> always failed.
3. onError → retryAssetIcon writes iconUrl: null to CACHED_ASSET_ICONS_ID, then consults only getIconUrlFromIssuer (home domain → SEP-1 TOML).
4. That fallback can never succeed for this asset: Horizon reports home_domain: null for the issuer, with thresholds {0,0,0} and a single signer at weight 0 — the account is permanently locked and can never set one. A valid stellar.toml with the right image does exist at usdt0.to, but the wallet has no way to discover that domain.
5. getAssetIcons skips any asset whose cached value is null, with a comment saying the null "is only stored in Redux, so we will re-try on next app reload". It wasn't — retryAssetIcon persisted it, so the skip outlived the session. With no icon there is no <img>, so nothing fires the onError that would have retried: the asset could not recover on its own.

What changed

Label the outer loop and break out of it on the first match:

freighter/@shared/api/helpers/getIconFromTokenList.ts

Lines 20 to 55 in 6701092

	}) => {
	let verifiedToken = {} as AssetListReponseItem;
	let canonicalAsset = undefined as string | undefined;
	// The lists arrive in the user's configured order, which is a priority order:
	// the first list carrying the asset wins. Without the labeled break below the
	// outer loop runs to completion and the LAST matching list silently overwrites
	// earlier, higher-priority entries.
	listLoop: for (const data of assetsListsData) {
	const list = data.assets;
	if (list) {
	for (const record of list) {
	if (contractId) {
	const regex = new RegExp(contractId, "i");
	if (record.contract && record.contract.match(regex) && record.icon) {
	verifiedToken = record;
	canonicalAsset = getCanonicalFromAsset(code, contractId);
	break listLoop;
	}
	}
	if (
	issuerId &&
	record.issuer &&
	record.issuer === issuerId &&
	record.code === code &&
	record.icon
	) {
	verifiedToken = record;
	canonicalAsset = getCanonicalFromAsset(code, issuerId);
	break listLoop;
	}
	}
	}
	}
	if (verifiedToken?.icon) {

Leave null entries out when reading the persisted icon cache:

freighter/extension/src/background/messageListener/handlers/getCachedAssetIconList.ts

Lines 1 to 24 in 6701092

	import { DataStorageAccess } from "background/helpers/dataStorageAccess";
	import { CACHED_ASSET_ICONS_ID } from "constants/localStorageTypes";
	export const getCachedAssetIconList = async ({
	localStore,
	}: {
	localStore: DataStorageAccess;
	}) => {
	const assetIconCache =
	(await localStore.getItem(CACHED_ASSET_ICONS_ID)) || {};
	return {
	// A null entry records that a lookup came up empty, and getAssetIcons reads
	// one as "already tried, don't look again". That was only ever meant to
	// last a session, but this cache is on disk, so the verdict outlived it: an
	// asset whose icon failed once stayed iconless for good, with no way back —
	// no icon means no <img>, so nothing fires the error handler that would
	// have retried. Leaving nulls out makes them ordinary cache misses, and the
	// fresh lookup overwrites the stale entry.
	icons: Object.fromEntries(
	Object.entries(assetIconCache).filter(([, iconUrl]) => iconUrl),
	),
	};
	};

Filtering on read rather than deleting on write is what makes this a four-line fix instead of a storage migration: a stale entry becomes an ordinary cache miss, and getIconFromTokenLists already writes what it finds, so the fresh lookup overwrites it on disk. It also makes retryAssetIcon's existing iconUrl: null message finally mean what it intended — clear this entry — with no change to that handler.

The in-session memo is deliberately untouched. It lives in Redux (saveIconsForBalances), which is where getAssetIcons' comment always claimed it lived; filtering at the storage boundary separates the two cleanly.

Verification

• New tests: the first matching list wins by issuer and by contract ID (both previously returned the later list's icon); the cache read drops nulls, passes real icons through, and handles an empty cache.
• Full suite: 1773 passed, 0 failed, and tsc --noEmit clean — identical to master.
• Manually confirmed against the prod backend: stored null → icon renders → stored value replaced with the working URL.

Follow-ups / out of scope

• LOBSTR's list entry is broken. It ships an ipfs.io URL that no browser can load. Worth reporting upstream — ordering saves us here only because Soroswap happens to list USDT0 too. It is the only such entry across all three default lists today (stellar.expert serves everything from meta.stellar.expert, all browser-loadable).
• Nothing checks that a chosen icon URL actually loads. Ordering fixes the known case; a list shipping a URL browsers reject is only caught by loading it. Explored in fix(icons): keep the asset icon that actually loads, not the first one listed #2993 and deliberately not carried here — it needs a per-URL verdict cache and concurrency control to stay off the balances render path, which is a much larger change than a hotfix should carry.
• AssetIcon latches its error state. Once an image fails, the row keeps the broken-image glyph for the life of the component even if a working URL arrives, so a successful retry is invisible until the popup is reopened. Pre-existing and unrelated to these two lines, but it is why the existing retry path appears to do nothing.

[github-actions]

PR Preview build is ready: https://github.com/stellar/freighter/releases/tag/untagged-05f821b2b89f6f22d0ec
Backend: sandbox (piyalbasu). SDF collaborators only — install instructions in the release description.

[Copilot]

Pull request overview

Fixes missing USDT0 icons by respecting token-list priority and retrying persisted icon misses.

Changes:

• Uses the first matching token-list icon.
• Filters persisted null icon entries.
• Adds regression coverage.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

File	Description
extension/src/popup/helpers/__tests__/getIconFromTokenLists.test.js	Tests issuer and contract list priority.
extension/src/background/messageListener/handlers/getCachedAssetIconList.ts	Excludes persisted null icon entries.
extension/src/background/messageListener/handlers/__tests__/getCachedAssetIconList.test.ts	Tests cache filtering behavior.
@shared/api/helpers/getIconFromTokenList.ts	Stops lookup after the first matching list.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated no new comments.

Suppressed comments (1)

extension/src/background/messageListener/handlers/getCachedAssetIconList.ts:21

• Please reference a tracking issue in this TODO (for example, TODO(#1234): ...) so the planned cache cleanup cannot be silently forgotten.

    // TODO: this is a read-side workaround, not the real fix. It hides bad data

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.

Suppressed comments (1)

extension/src/background/messageListener/handlers/getCachedAssetIconList.ts:21

• This TODO has no tracking reference, so the deferred storage migration/cache-contract work can be lost after this hotfix. Freighter's review guidance requires TODOs to reference an issue; please link the issue that owns these follow-up steps (for example, TODO(#…):).

    // TODO: this is a read-side workaround, not the real fix. It hides bad data

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated no new comments.

Suppressed comments (1)

extension/src/background/messageListener/handlers/getCachedAssetIconList.ts:21

• This new TODO is not linked to a tracked issue, so the acknowledged cache-design follow-up can be lost after this PR merges. Please reference a GitHub issue in the TODO (for example, TODO(#1234): ...) or remove the TODO and track the work elsewhere.

    // TODO: this is a read-side workaround, not the real fix. It hides bad data

[JakeUrban]

What is a "cold popup open"? What is the consequence of re-running the lookup chain for nulls besides USDT0?

[piyalbasu]

"cold popup open" just means opening the extension for the first time (so no ephemeral data, like balances, has been cached). I can make this wording a bit more clear.

The consequence of re-running the lookup chain is just a couple of seconds of the loading icon state as we retry the icon (non-blocking). Previously, we wouldn't bother retrying and just say "this previously was not found" and show the default icon

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated no new comments.

Suppressed comments (1)

extension/src/background/messageListener/handlers/getCachedAssetIconList.ts:21

• Please link this substantial follow-up to a tracking issue (for example, TODO(#NNNN): ...). The repository guidance requires TODOs to carry an issue reference so the acknowledged persistent retry cost and cache redesign are not lost.

    // TODO: this is a read-side workaround, not the real fix. It hides bad data

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated no new comments.

Suppressed comments (1)

extension/src/background/messageListener/handlers/getCachedAssetIconList.ts:58

• This removes negative caching on every read, not just for stale upgrade data. As the new comment above notes, any genuinely iconless asset will now repeat token-list, Horizon, and possibly stellar.toml lookups each time a popup flow loads icons. That adds recurring latency and third-party traffic across swap, send, manage-assets, and history. Please retain an expiring negative-cache value (and separately invalidate legacy permanent nulls) so transient failures recover without making permanent misses retry on every popup open.

    icons: Object.fromEntries(
      Object.entries(assetIconCache).filter(([, iconUrl]) => iconUrl),