[9] feat(checkout): use any route for wallet payments, EVM-only

[tomiiide]

Which Linear task is linked to this PR?

N/A

Why was it implemented this way?

This branch builds on checkout/08-activity-and-polish and adds the wallet-any-route work plus an EVM-only restriction for checkout.

• Wallet pays via any route. The wallet funding flow pays directly from the connected wallet, so it keeps the integrator's full route set (no Intent Factory deposit-only override). Deposit flows (transfer/exchange/cash) still force the IF-only allow-list to surface a deposit-address route.
• Connected wallets as destination recipients. The destination step offers already-connected wallets matching the destination ecosystem, and seeds the connected wallet as the default recipient in wallet flows.
• EVM-only for now. Checkout forces chains.types to EVM-only, cascading to chain lists, token lists, route quotes, and the wallet menu (which now honors chains.types). The native gas token is hidden from source-token selection in the IF deposit flows, since IF cannot accept it; the wallet flow keeps full token support.

Token-type filtering is handled naturally by the existing chain-type config rather than a parallel token allow-list, reusing useTokens/useChains/useAvailableChains.

Visual showcase (Screenshots or Videos)

Not included; UI changes are funding-source/token-list filtering. Recommend a manual pass in the playground to confirm non-EVM chains/wallets/tokens are hidden and an EVM to EVM quote resolves.

Checklist before requesting a review

• I have performed a self-review and testing of my code.
• This pull request is focused and addresses a single problem.
• If this PR modifies the Widget API or adds new features that require documentation, I have updated the documentation in the public-docs repository.

[changeset-bot]

🦋 Changeset detected

Latest commit: a622864

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 4 packages

Name	Type
@lifi/widget-checkout	Minor
@lifi/widget	Minor
nft-checkout	Patch
tanstack-router-example	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[vinzenzLIFI]

Checkout manual testing — findings

Did a first manual pass on this branch. Tested so far:

• Pay from Wallet — end-to-end on Ethereum mainnet, completed successfully.
• Transfer Crypto (deposit-address / smartDeposits) — end-to-end on Ethereum mainnet (hit the refund path; see notes).
• Deposit with Cash (Transak) — up to the Transak payment screen.

This is a first pass, not exhaustive — more testing will follow (see "Not tested yet" below). Findings so far:

🐞 Bugs (widget)

1. Back from the refund screen lands in a "Transaction details" limbo
After a deposit refunds, pressing Back navigates to the Transaction Details page, which polls /v1/status?txHash=<deposit-contract-creation-hash>&fromChain=1&toChain=1 → 404 in a loop. Result: a permanent "Processing transaction" screen with misleading "USDC received / Swapped to stETH" steps that never resolve and contradict the refund.
→ The tx hash being polled is the deposit address's contract-creation tx, not the user's transfer. Once the flow is refunding, it shouldn't poll a tx-hash status (or should use the user's send tx). Related backend gap: the status response omits the user's initial send tx + sender address (thread).

2. Cancel-from-Transak → first Back press does nothing
Repro: Deposit with cash → Transak opens → close Transak (returns to amount screen) → click Back → no reaction; a second click works.
Cause: the cancel handler does navigate({ to: enterAmount, replace: true }) (CheckoutTransactionStatusPage.tsx:120), which replaces the status route with a second /enter-amount entry sitting right on top of the existing one. The first router.history.go(-1) (Header.tsx:71) pops to an identical /enter-amount → no visible change.
→ Fix: pop back with router.history.go(-1) instead of replace-navigating to enterAmount.

3. Cash flow doesn't forward amount/currency to Transak
Selecting "Deposit with cash" clears the amount (SelectSourcePage.tsx:232) and opens the Transak session without a fiatAmount, so Transak shows its own default "You pay 250 EUR" — including a currency that may not match the one selected in the checkout currency step. We should forward a sensible default amount and the selected currency.

ℹ️ Known issues (not widget bugs — for reference)

• Refund on simulation failure is expected (IF retries, then refunds); the stETH-on-mainnet flakiness that triggered it on develop is known instability → CORE-360, IF edge-case thread.
• Transfer-crypto unsupported on Arbitrum (IF is EVM-mainnet-only for now) → IF integration channel.
• Cash refund returns funds to the Transak wallet, not the user — open design question → thread.

🧪 Not tested yet

This branch's changes still to verify (#794):

• EVM-only enforcement — non-EVM chains, tokens, and wallets (wallet menu) are hidden.
• Native gas token hidden in IF flows — ETH absent from the transfer/cash source-token list, but available in pay-from-wallet.
• Connected wallets as destination recipients — the recipient picker on the destination step.

General:

• Custom destination address — typed address / ENS validation (only used a connected wallet so far).
• Pending / resume — close mid-deposit and remount (resumePending).
• onError / onClose integrator callbacks (onSuccess seen via pay-from-wallet).

Blocked on a test account / payment method:

• Connect Exchange (Mesh), e2e — no exchange test account. Also, connecting a self-custody wallet via Mesh failed: MetaMask never popped up and Mesh showed "Oops it looks like you denied the connection request" (nothing was actually denied). Likely the known multi-wallet-extension collision — the console showed window.ethereum conflicts ("Cannot redefine property: ethereum"), already acknowledged (dev-chains thread). Needs a re-test with only MetaMask enabled before filing.
• Deposit with wallet address (Mesh) — unclear if implemented; avoided wasting funds.
• Deposit with Cash — post-payment callback — no test card / Apple Pay / GPay, so tested only up to the Transak screen; funds arrive → IF executes → final status still needs a run.

[vinzenzLIFI]

🐛 Mesh deposit flow — UI flicker on the failure→refund transition

Tested the Mesh (exchange) handoff e2e with real funds. Final "Refund complete" screen is correct, but on the way there the UI briefly shows funds-received → regresses to a loading/watching spinner → then the refund screen.

Root cause (IF, already known — not a new bug): the deposit-address /status regresses PENDING → INTENT_SIMULATION_FAILURE → NOT_FOUND → REFUND_IN_PROGRESS → DONE/REFUNDED. The intermediate NOT_FOUND is the IF status-regression Tomi already raised with Georgi → thread. A hotfix landed ~Jun 15 but the simulation-failure path still regresses (Tomi's Jun 16 follow-up; reconfirmed in my Jun 18 test).

Widget resilience gap (this is the part we can fix here): the status hook treats any NOT_FOUND as "pre-deposit, keep watching" and discards the last real status — useCheckoutTransactionStatus.ts#L123:

const resolvedStatus = data && data.status !== 'NOT_FOUND' ? data : undefined

So one regressive NOT_FOUND collapses resolvedStatus/phase and the render falls back to the watching screen (CheckoutTransactionStatusPage.tsx#L253), un-showing the real state. Suggested fix: latch the last non-NOT_FOUND status and never downgrade on a later NOT_FOUND (deposit-address path); later real updates still overwrite it. Same guard should cover the resume path (CheckoutTransactionStatusPage.tsx#L126-148), which currently bails to enter-amount on NOT_FOUND — a manual reload during that window would lose the refund screen.

This makes the UX resilient regardless of the IF fix timeline.

[vinzenzLIFI]

⚠️ UX gap — a recently-started deposit can be abandoned because it isn't tracked yet

Surfaced while testing the Mesh/Transak deposit flows. This is not a crash or a logic defect — the code behaves as written. It's a gap in the user journey: there's a path where a real, in-flight deposit gets dropped and the user is sent back to the start, with no way to recover it from the UI.

The path that breaks (the scenario to protect against):

1. User starts a deposit (Connect Exchange / Deposit with Cash, or Transfer Crypto) → widget begins watching for the deposit.
2. User leaves to their wallet / exchange to send the funds.
3. Something interrupts them — a technical hiccup, wallet error, app switch, tab reload — and they come back and reopen / restart checkout to continue.
4. They pick up the in-progress deposit to keep tracking it.
5. But the deposit is very recent, so IF hasn't found/indexed it yet and returns NOT_FOUND.
6. The flow reads that single NOT_FOUND as "this deposit never happened," drops the tracked deposit and aborts back to the start — even though the funds may already be on their way and could land seconds later.

Why it's a journey gap, not a one-liner: NOT_FOUND is ambiguous — it means both "nothing was ever sent" and "we just haven't found it yet" (provider / IF indexing delay). The flow currently assumes the first meaning the instant it sees NOT_FOUND on resume, which is exactly wrong in the window right after a deposit starts. How a not-yet-found deposit should be treated (how long to keep waiting, how the user exits, what's reassured vs. terminal) is a product/UX decision, so I'm deliberately not prescribing a fix here.

Direction (intentionally open): the guiding principle is don't abandon a deposit that could still arrive. NOT_FOUND should lean toward "keep waiting"; ending the flow should come from the user (clearly, and non-destructively — the deposit stays recoverable) or from a genuine terminal signal, not from a transient "not yet."

Where it surfaces (for whoever picks it up — not a prescribed fix): the resume path lands on the status page (buildResumeNavigation.ts:69-79), which on a resumed record with no tx hash treats the first NOT_FOUND as terminal — clears the persisted record and redirects to amount entry (CheckoutTransactionStatusPage.tsx:126-148). Cash/exchange records are written confirmed-no-hash with a depositAddress and no hash (usePendingCheckoutWriter.ts:160-172), so they fall straight into this path.

Reproduced live (2026-06-22): completed a Mesh sandbox deposit → record persisted (confirmed-no-hash, exchange) → reloaded → reopened → tapped the "Deposit in progress" card → status poll returned NOT_FOUND → the pending record was deleted from localStorage and the user bounced to amount entry. Confirmed it deletes immediately on the first NOT_FOUND.

Related (separate, IF-side): the NOT_FOUND-after-a-real-status regression already raised with Core → thread. The two compound each other but are distinct.