Swap to New Token

[CassioMG]

Summary

Enables swapping from a held token to any Stellar classic asset in a single flow — token discovery (held + popular + free-text search), Blockaid coverage on non-held destinations, and an atomic changeTrust + pathPaymentStrictSend when a trustline is needed.

This is the browser-extension counterpart to the mobile feature. See the reference PR and its design doc:

• 📱 Mobile PR: stellar/freighter-mobile#879
• 📄 Design doc: extension/specs/swap-to-new-token-design.md — kept in sync with what shipped; mirrors the mobile design doc.

Scope: 189 files changed, ~16.3k LOC across the branch:

• src/ (+ @shared) — ~7.7k lines (47%)
• tests (unit + Playwright E2E) — ~7.7k lines (47%)
• design doc — ~730 lines (4%)
• i18n (en + pt) — ~130 lines (1%)

Most of the large diffs are net-new files (new picker sections, new hooks, new sheets) plus tests written alongside them, and shared UI components that Send and the account-home balances list now reuse.

---

What's new

• useSwapTokenLookup — owns destination-token discovery: held balances, popular tokens (volume7d ∩ verified lists), and free-text search via stellar.expert. Closes a security gap: every non-held destination is Blockaid-scanned before it can be selected.
• SwapAsset picker, parameterized by selectionType — one picker drives both the Sell and Receive sides, replacing the old single-list picker.
• SwapPickerSections — the labeled sections (Your tokens / Popular / Verified / Unverified), the (i) info sheets, and the empty / Soroban / fallback states.
• SwapAmount rewrite — built on the new shared AmountCard + PercentageButtons, with a Sell/Receive layout, a swap-direction chevron, crypto⇄fiat toggle, and a debounced live "You receive" quote that updates as you type.
• Atomic transaction — buildChangeTrustOperation is extracted and prepended so a new-token swap is a single changeTrust + pathPaymentStrictSend XDR (fee split total-across-ops); Blockaid scans the combined XDR for defence in depth.
• XlmReserveSheet — a pre-flight when the account lacks XLM headroom for the new 0.5 XLM trustline reserve; offers a "Swap for 0.5 XLM" affordance, a copy-address fallback, and a "why do I need XLM?" link.
• Trustline banner + info sheet + rate row on the review screen — explains the trustline reserve up-front before the user confirms.
• Transaction details sheet (Swap + Send) — the shared review screen gains an expandable, operation-by-operation breakdown (amounts, network fee, memo, per-op fields), now surfaced in both the Swap and Send review flows.
• Unified Blockaid coverage — a single reusable BlockaidBanner across Add-a-token, Sign Transaction, Sign Message, ChangeTrust, Grant Access, and Swap; verdict-colored token badges (amber = suspicious, red = malicious); a scan-on-select recovery path so a token picked before its verdict lands still gets assessed.
• Quote-expiry recovery — Horizon op_under_dest_min / op_too_few_offers at submit are classified and surfaced as a toast, and the flow recovers to the amount screen with a fresh quote instead of dead-ending.
• Shared UI components — AmountCard, PercentageButtons, AssetListRow, and BalanceRow are now shared by Send, Swap, and the account-home balances list, removing duplicated markup.

---

Search results strategy

When the user types a search term, the picker renders three labeled, mutually-exclusive sections — chosen over a flat "Results" list so users can visually distinguish levels of trust:

1. Your tokens — held tokens matching the term.
2. Verified — verified-list tokens. The section header has an (i) icon opening a sheet explaining what the verified-token lists are.
3. Unverified — remaining stellar.expert matches. Its header has its own (i) icon for the unverified caveat.

G… issuer addresses surface the assets that account issues via stellar.expert's fuzzy ?search=. C… contract pastes fall under a Soroban-specific empty state explaining the flow is classic-only for now — Soroban contract tokens are filtered out at every stage.

---

Caching & pre-warm

Popular ("top tokens") lists are cached in two layers, keyed per network:

1. Persistent disk cache — chrome.storage.local (background-owned; the popup messages the background, matching every other cache in the codebase), with a 30-minute staleness window. Because it survives popup close, reopening the extension paints Popular straight from disk with no spinner.
2. In-memory Redux cache slice — the session working copy, read first on each open.

On open the picker reads Redux → disk → network in freshness order, using whichever layer is still fresh. Search/discover results repaint instantly from the last cached result and revalidate silently in the background (SWR-style), so re-typing a term never flashes a spinner.

Pre-warm. useSwapTopTokensPrewarm mounts on the account/home screen and — deferred ~1s past first paint, mainnet-only, aborting on unmount — populates both cache layers when the persisted entry is stale or absent. So by the time the user opens Swap the Popular list is usually already warm (the analog of mobile's tab-mount pre-warm). It costs at most one trending request per staleness window.

Blockaid asset scans are deliberately not persisted. Unlike Popular tokens, per-token Blockaid verdicts stay in an in-memory (module-scoped) cache and are re-scanned each session. Persisting verdicts to disk would carry a cache-poisoning risk — a tampered entry could mark a malicious token "safe" — so we keep them in memory only.

Defence in depth at review. The scan caches are a first-paint UX optimization. The review step still issues a fresh scanTransaction against the built XDR every time, so transaction-level signals are always evaluated live per confirmation.

---

Graceful fallback (stellar.expert unreachable)

Held-to-held swaps keep working even when stellar.expert is down:

• Popular tokens section — omitted.
• Search — degrades to held-only in-memory matches.
• Soft inline notice — "Token discovery is temporarily unavailable" is rendered at the top of the picker; non-blocking.

Path-finding is unaffected, since it uses Horizon strict-send paths, not stellar.expert.

---

Notes for reviewers

• State lives in the Redux transactionSubmission slice (destinationTokenDetails, best-path, cache slots), not a separate store.
• Overlays use the existing SlideupModal / LoadingBackground pattern rather than native bottom sheets; toasts use sonner.
• SwapAmount business logic is split into focused hooks + helpers (useSwapLiveQuote, useSwapQuoteExpiry, useSwapDestinationScan, getSwapDerivedData, …), mirroring the mobile SwapScreen decomposition, so the component stays presentation-focused.

---

Telemetry

Eight new events instrument the flow (screen-view events like swap: amount already existed on master):

Event	Fires when	Key properties
swap: picker opened	The Sell/Receive picker is opened	side (source/destination), source (cta/dropdown)
swap: source selected	A sell token is picked	tokenCode, tokenIssuer, source
swap: destination selected	A receive token is picked	tokenCode, tokenIssuer, requiresTrustline, source
swap: direction toggled	The user flips sell ⇄ receive	—
swap: xlm reserve shown	The XLM-reserve pre-flight sheet is shown	—
swap: quote expired	A quote expires at submit (Horizon op_under_dest_min / op_too_few_offers)	sourceToken, destToken, sourceAmount, destAmount, allowedSlippage, resultCode
swap: trustline added	A new-token swap settles on-chain	tokenCode, tokenIssuer
swap: success	The swap settles on-chain	sourceToken, destToken, sourceAmount, destAmount, allowedSlippage

swap: trustline added and swap: success fire post-confirmation — once the transaction actually settles, not at review time — mirroring mobile.

---

Shared Blockaid banner

Now we have a single reusable BlockaidBanner component that renders in every flow that surfaces a security verdict — SAFE renders nothing, suspicious = amber, malicious = red — replacing the old per-flow warning components. The screenshot below covers all of them: Grant access / connect, Add a token, Sign message, Sign transaction, Send review, and Swap review.

Transaction details sheet

The shared transaction-details sheet (operation-by-operation breakdown), is now available in both the Swap and Send review flows and aligned with mobile UI.

---

Testing

Manually exercised in Chrome on the popup and sidebar. Full unit suite passing locally; the Playwright E2E swap spec was updated for the new flow (12/12), and the broader Blockaid / add-token / send E2E specs were updated to the new shared components and pass.

Videos

Swapping to a new token

swap-to-new-token-hh.mov

Swapping to a held token

swap-to-held-token-hh.mov

Swapping with not enough XLM for reserves

swap-xlm-reserve-sheet.mov

Using the search input

swap-using-the-search-box.mov

Quote expiration warning + retry

swap-quote-expired-retry.mov

Swapping to/from a token with no price

swap-with-no-prices.mov

Blockaid warning

swap-blockaid-warning.mov

Graceful degradation when stellar.expert is down

swap-stellar-expert-down.mov

Amount and path errors

swap-amount-and-path-errors.mov

[CassioMG]

Code-wise, this is looking pretty good! I just left a couple of small comments plus a comment from Claude. I'm still doing some additional manual testing

Something I'm noticing - it seems like there's a few different refactors that are being folded into this PR:

1. Blockaid UX
2. SEP-42 validation
3. Webpack updates
4. Updating inputWidthContext
   plus some others

I appreciate that this work is getting done, but I'm wondering if some of this could have been separate PR's to make this diff a little smaller and the review process a little easier

@piyalbasu thanks for reviewing! Yeah, you are right that those could be separate PRs, I will keep that in mind for a next big feature like this so we ship it in smaller pieces 🚢

[piyalbasu]

1 small thing I noted, the asset list schema is being loaded 3 times when I click an asset to Swap To (assuming this is loading once for every asset list). Not a huge deal because the browser is smart enough to load it from disk cache rather than doing a roundtrip, but something worth noting:

[CassioMG]

1 small thing I noted, the asset list schema is being loaded 3 times when I click an asset to Swap To (assuming this is loading once for every asset list). Not a huge deal because the browser is smart enough to load it from disk cache rather than doing a roundtrip, but something worth noting:

@piyalbasu good catch, and exactly right — schemaValidatedAssetList runs once per enabled asset list, and each call re-fetched the same SEP-0042 schema (3 lists → 3 requests, disk-cached by the browser but still issued every time).

Fixed in c40fd69: the schema is now fetched once and memoized, so all list validations in a session reuse it — a single request instead of one per list (and it's shared across the Swap-to / search / Add-a-token flows too, not just deduped per open). A failed fetch isn't cached, so a transient error still retries on the next attempt.

[CassioMG]

1. When switching to/from token units vs. dollars, the amounts change.
2. The buy amount unexpectedly updates after I select "Review Swap".

3. When I opened the token picker for the first time, for both the buy and sell tokens, there was a decently long loading state before rendering. Can we start loading this data ahead of time, so users don't have to wait to see the tokens they can pick?

@JakeUrban the points 1 & 4 above have been fixed on both Swap and Send flows, you should see stable crypto and fiat amounts now.

About the point 3, as I mentioned earlier we are already loading data ahead of time which makes it very hard to repro the long loading time on first Swap picker open. I had to delete and reinstall the extension several times to be able to repro it once, and I also had to immediately open the picker right after opening the pop-up to be able to repro it. Then on the rare times I was able to repro it it happened just on the very first rendering, after that the result is cached and you should always see the popular tokens rendering immediately on following renders.

So from my testing it appears that it is very unlikely that a regular user will see it unless they open the Swap picker blazing fast right after updating the app version for the first time, and, in case they see it, they will only see it once because the next time there should be a cache in place already.

I'm thinking we could release it like this and revisit it in case we start seeing long loading times happening more often. How does that sound?

Thanks!