Document and verify multi-chain EVM payment funding

[snissn]

Parent tracker: #14

Depends on:

• Support selected EVM sources in payments fund #17
• Reuse selected EVM sources in payments setup --auto #18
• Existing first-route mainnet gate Harden, document, and verify Filecoin CLI self-funding #6

Goal

Document and validate the multi-chain EVM funding feature at current head without requiring a funded transfer for every token in Squid's mutable catalog.

Role And Gate Ownership

• Role: documentation and final validation
• Depends on: both CLI integrations and Harden, document, and verify Filecoin CLI self-funding #6
• Blocks: parent completion
• Authoritative gate: deterministic coverage spans the eight selected chain IDs and the dynamic token policy, live read-only probes confirm current routes, and representative funded runs cover the distinct external-chain, token-type, same-chain, and CLI-entry-point risks.

Validation Strategy

1. Deterministic no-funds matrix

• All eight selected chain IDs and accepted CLI aliases.
• Unique symbol, exact address, ambiguous symbol, native token, unsupported token, unsupported chain, and non-EVM catalog entry.
• Token decimals other than six.
• Native and ERC-20 planning/execution.
• Chain-specific router/spender validation.
• Source RPC chain mismatch.
• Invocation-wide token and source-native gas caps.
• Filecoin same-chain FIL reserve.
• Checkpoint identity, interruption, rerun, partial success, refund, needs-gas, timeout, and arrival reconciliation.
• Direct/no-op paths with zero provider/source-RPC calls.

2. Live read-only checks

• Record current Squid catalog membership for the selected networks.
• Probe at least one current token per selected network for the FIL and USDFC outputs when Squid advertises a viable route.
• Record exact chain/token addresses, quote IDs, minimum outputs, target/spender identities, expiry, and result.
• Treat provider support and liquidity as current observations, not permanent repository promises.
• Low-liquidity or unavailable routes must fail closed and do not make an otherwise correctly bounded network implementation unsafe.
• No signing or funded transfer is part of this phase.

3. Representative funded checks

Funded validation is representative, not exhaustive:

• Reuse successful current-head Harden, document, and verify Filecoin CLI self-funding #6 Arbitrum evidence for the original external ERC-20 route when the relevant code is unchanged, or rerun it if the generalized code invalidates that evidence.
• Execute one low-value non-Arbitrum external ERC-20 route end to end.
• Execute one low-value Filecoin same-chain route, native or ERC-20, while proving the FIL reserve remains sufficient.
• Represent both payments fund and payments setup --auto across these checks.
• Verify FIL/USDFC wallet arrival, Filecoin Pay deposit/approval as applicable, and no duplicate source spending on rerun.
• Use dedicated disposable wallets, explicit hard caps, approved budgets, and sanitized transaction identifiers/output.

Documentation

Update user-facing documentation to explain:

• the eight input networks;
• dynamic Squid token eligibility;
• unique-symbol versus exact-address selection;
• native-token selection;
• source and Filecoin wallet ownership;
• source RPC and chain verification;
• source token and source-native gas caps;
• Filecoin same-chain FIL reserve;
• route/approval confirmation;
• unsupported, ambiguous, low-liquidity, and provider-unavailable fallbacks;
• recovery and safe rerun behavior;
• Calibration/devnet fail-closed behavior;
• why the CLI does not scan balances or recommend sources.

Generated operator reports remain outside the repository. Do not commit private keys, provider credentials, credential-bearing RPC URLs, raw signed payloads, or portfolio/balance history.

Non-Goals

• A funded transfer for every Squid token.
• A claim that today's catalog or route liquidity is permanent.
• Balance-based suggestions.
• Expanding the chain list during closeout.
• Turning generated operator reports into versioned repository content.

Test-First And Work Log

Start

• Define the deterministic matrix and expected failures before closeout changes.
• Record current head and exact commands.
• Confirm dedicated wallet, cap, RPC, provider credential, and approved budget prerequisites without printing secrets.

Implement and validate

• Complete deterministic matrix.
• Complete live read-only route matrix.
• Complete/reuse current-head Arbitrum first-route validation.
• Complete one non-Arbitrum external ERC-20 funded run.
• Complete one Filecoin same-chain funded run.
• Exercise both CLI entry points and reruns.
• Update README, payments documentation, glossary links, help text, and changelog as appropriate.

Close

• pnpm test.
• Browser tests.
• Build, typecheck, lint, and docs generation.
• Exact current-head CI is green.
• Latest-head review findings are resolved.
• Sanitized issue/PR evidence records transaction IDs, outputs, caps, and rerun results.
• Parent tracker reflects current catalog observations separately from durable supported behavior.

Performance Classification

Not performance-relevant as an optimization. Record provider/RPC call counts, route duration, and polling count as operational observations. Unbounded retries or new provider/source-RPC calls on direct paths are blocking correctness regressions.

Branch And PR Policy

• Topic branch and draft PR for repository documentation/test changes.
• Conventional Commit PR title; PR references this issue and the parent.
• Follow AGENTS.md: obtain explicit permission before commit or push.
• Do not request automated review until deterministic tests, documentation, sanitized funded results, and latest-head CI are coherent.

Exit Gate

This issue closes when current-head deterministic and live checks support the claimed eight-network/dynamic-token contract, representative funded runs prove one non-Arbitrum external ERC-20 path and one Filecoin same-chain path across both CLI entry points, reruns do not duplicate spending, #6's first-route gate is satisfied or validly reused, and the documentation states the boundaries without implying balance discovery or exhaustive token certification.

[snissn]

Code-complete progress

The implementation dependencies are complete on the fork:

• Support selected EVM sources in payments fund #17 closed through PR feat(payments): support selected EVM sources in payments fund #24, merged as 9e7db54.
• Reuse selected EVM sources in payments setup --auto #18 closed through PR feat(payments): reuse selected sources in setup --auto #25, merged as 6ff5b67.

At exact PR #25 head 215ef692, 247 focused payment tests passed. The full
73-file repository suite passed with 964 tests and 11 skips, along with build,
typecheck, Biome, CLI help, and published-package import checks. Independent
review, CodeRabbit, and exact-head Codex review reported no unresolved findings.

After merge, upstream Actions run
30324170169
passed at exact fork head 6ff5b67b6387e26dfc14e16e5a589e763ce85e4a
on current and LTS Node.js across Ubuntu, macOS, and Windows, plus both browser
jobs.

The merged implementation covers the fixed eight-network boundary, dynamic
Squid catalog resolution, exact-address/unique-symbol/native selection, dynamic
decimals, ERC-20 and native execution, chain-aware RPC and route validation,
invocation-wide caps, Filecoin same-chain reserve handling, recovery identity,
both CLI entry points, and provider-free direct/no-op paths.

Remaining validation

This issue remains open for:

• the current live read-only route matrix;
• representative funded checks for a non-Arbitrum external ERC-20 route and a
  Filecoin same-chain route;
• coverage of both CLI entry points and no-duplicate-spend reruns;
• final documentation reconciliation against the observed routes and results.

The funded checks depend on #6's authorized mainnet wallet, source assets and
gas, RPC access, active-spend account, and approved hard cap. No funded mainnet
transaction was performed during the code-complete phase. The available
testnet-only key does not satisfy this gate.

[snissn]

Non-mainnet validation closeout

The implementation and all validation that does not require funded mainnet execution are complete on fork master at 254fa869b2c47641da6d5b34aef41b9d184d0219.

Repository changes and gates

• PR test(payments): cover all selected route policies #26 merged the all-chain trusted target/spender regression test and explicit low-liquidity/provider-unavailable direct-funding fallback.
• The full local repository gate passed before that docs/test-only PR: 73 files, 964 tests passed and 11 skipped, with build, typecheck, and Biome clean.
• The exact merged-head focused source-catalog suite passes 17/17.
• Exact-head upstream Actions run 30330531413 passed all eight current/LTS Linux, macOS, Windows, and browser jobs at 254fa869.
• Independent review found no material implementation, test, or documentation issues. CodeRabbit's one glossary-link finding was fixed in adfabf9; the thread is resolved.

The deterministic matrix now covers all eight chain IDs and aliases; dynamic address/unique-symbol/native selection; ambiguous and unsupported inputs; non-six-decimal tokens; native and ERC-20 execution; per-chain trusted targets/spenders; RPC mismatches; invocation-wide token/native-gas caps; Filecoin FIL reserve; checkpoint identity and recovery terminal states; and provider-free direct/no-op paths.

Live read-only Squid observation

Observed 2026-07-28 UTC from route logic unchanged since base 6ff5b67. No transaction was signed or submitted.

Catalog membership at observation time:

Source	Chain ID	Catalog tokens
Filecoin	314	48
Arbitrum	42161	231
Ethereum	1	491
Base	8453	1019
Optimism	10	142
Polygon	137	199
Avalanche	43114	162
BNB Chain	56	378

All 16 probes returned valid routes. Amounts and minimum outputs below are base units. Every route used target 0xce16F69375520ab01377ce7B88f5BA8C48F8D666 and approval spender 0xce16f69375520ab01377ce7b88f5ba8c48f8d666; observed quote expiry was 2026-07-28 04:36:56–04:37:20 UTC.

Source	Selected token	Decimals	Output	Quote ID	Minimum output
Filecoin	USDFC 0x80b98d3aa09ffff255c3ba4a241111ff1262f045	18	FIL	c49ca51a066c3d78944746adefe97cfb	714207919351167787
Filecoin	WFIL 0x60e1773636cf5e4a227d9ac24f20feca034ee25a	18	USDFC	97c77fba3f7d0d42f9a7bea2370a5fe3	342408407652460395
Arbitrum	USDC 0xaf88d065e77c8cc2239327c5edb3a432268e5831	6	FIL	01ec56190cf729dcf7b3ebf55d5d2f4c	710196678945548117
Arbitrum	USDC 0xaf88d065e77c8cc2239327c5edb3a432268e5831	6	USDFC	2d4fbedab6845bcbb66336e339b73872	492257531531448092
Ethereum	USDC 0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48	6	FIL	f4ceb6965221cff5488b4fdcdfefeef5	710374361307500062
Ethereum	USDC 0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48	6	USDFC	0edd4be98e377d3b1079f721d83e1c8c	492380638982005709
Base	USDC 0x833589fcd6edb6e08f4c7c32d4f71b54bda02913	6	FIL	3957db5cfc823011b28a06eebf69e9e2	710338824835112464
Base	USDC 0x833589fcd6edb6e08f4c7c32d4f71b54bda02913	6	USDFC	d115cfff77c3b83b8f4b76533968c783	492355032632290547
Optimism	USDC 0x0b2c639c533813f4aa9d7837caf62653d097ff85	6	FIL	353cff8fb1052496dab0eabd5d48e06d	710233636876836992
Optimism	USDC 0x0b2c639c533813f4aa9d7837caf62653d097ff85	6	USDFC	364bb61ca02f708fb4e43445613dcceb	492283137881164897
Polygon	USDC 0x3c499c542cef5e3811e1192ce70d8cc03d5c3359	6	FIL	aae4afea6097255c39b757e7410d3af5	710182464356590453
Polygon	USDC 0x3c499c542cef5e3811e1192ce70d8cc03d5c3359	6	USDFC	116bbfa35397255c72cc7260193ccc70	492247682935403054
Avalanche	USDC 0xb97ef9ef8734c71904d8002f8b6bc66dd9c48a6e	6	FIL	a23c7f36839e789f598c36f098546484	710276280643706907
Avalanche	USDC 0xb97ef9ef8734c71904d8002f8b6bc66dd9c48a6e	6	USDFC	e98616a7918949bd2b2f8ca65b3f87c3	492312683669299128
BNB Chain	USDC 0x8ac76a51cc950d9822d68b83fe1ad97b32cd580d	18	FIL	d8ed7178844db6a4821699bd9b01233a	710240020181959766
BNB Chain	USDC 0x8ac76a51cc950d9822d68b83fe1ad97b32cd580d	18	USDFC	0cff3747c9a2d49ce2fa8e4f8227e752	492159535769400538

The sanitized operator report remains outside the repository as required. These are time-bounded observations, not permanent token/liquidity promises.

Remaining gate

Only funded mainnet validation remains:

• Harden, document, and verify Filecoin CLI self-funding #6's original external-route acquisition/deposit/rerun gate;
• one non-Arbitrum external ERC-20 route;
• one Filecoin same-chain route with the FIL reserve preserved;
• both CLI entry points represented across those funded checks;
• no-duplicate source spending on rerun.

Issue #19 therefore remains open, but it no longer has a code, documentation, deterministic-test, live-read-only, local-devnet, Calibration, review, or CI blocker.

[snissn]

The remaining validation obligations are now mapped to #30 (deterministic, devnet, Calibration, live read-only checks, minimal documentation, and the fresh upstream draft) and #31 (funded mainnet evidence). This issue remains historical evidence for draft PR filecoin-project#630 and does not block the upstream-based replacement branch.