Land multi-chain EVM funding for Filecoin payments

[snissn]

Goal

Support Filecoin and seven selected external EVM networks as input chains for Filecoin payment funding, using any exact Squid-supported token that produces a valid route to the FIL and/or USDFC needed by the command.

The selected source networks are:

CLI name	Chain ID
filecoin	314
arbitrum (arb remains accepted)	42161
ethereum	1
base	8453
optimism	10
polygon	137
avalanche	43114
bnb	56

Done means payments fund and payments setup --auto can safely resolve an explicitly selected source token on one of these networks, quote and execute a valid Squid route, verify Filecoin wallet arrival, and continue through the existing Filecoin Pay flow.

Why This Exists

The current implementation supports only native USDC on Arbitrum One. Chain ID 42161, the USDC address and six decimals, the source client, Squid router, native-gas ceiling, status requests, retry text, fixtures, and documentation are all Arbitrum-specific.

Squid exposes a broader EVM chain/token catalog and valid routes from the selected networks. Filecoin Pin should use that catalog as a dynamic token allowlist while retaining a deliberately small, reviewable set of input networks.

Product Contract

• The user explicitly supplies one --from-chain and one --from-token.
• --from-token accepts an exact contract address or a unique symbol on the selected chain.
• Ambiguous symbols fail before signing and list the matching addresses; they are never guessed.
• Native tokens have an explicit, documented selector.
• Squid catalog membership is required, but catalog membership alone does not authorize spending.
• A current route must satisfy all chain, token, owner, amount, destination, target/spender, expiry, slippage, and user-cap checks.
• The existing Filecoin Pin/Synapse funding planners remain authoritative for required FIL and USDFC.
• --max-source-amount remains an invocation-wide cap across all acquisition legs and is parsed in the resolved token's decimals.
• One invocation spends one selected source token only.
• The same EVM address controls the source and Filecoin wallets.
• Direct Filecoin funding paths remain direct and make no Squid or source-RPC call.
• Calibration and devnet acquisition continue to fail closed.

Issue Graph And Gate Ownership

Issue	Role	Depends on	Blocks	Authoritative gate
Resolve Squid-supported EVM source assets safely	source contract / decision gate	none	execution substrate	The fixed chain set, dynamic token resolution, native-token handling, and trusted target/spender policy are unambiguous and covered by sanitized fixtures.
Generalize Squid execution across selected EVM source chains	reusable execution substrate	source contract	both CLI integrations	No Arbitrum/token-decimal/router assumption remains in planning, execution, status, recovery, or Filecoin same-chain handling.
Support selected EVM sources in payments fund	first user-facing integration	execution substrate	setup parity, final validation	payments fund uses one explicit resolved source safely while preserving direct funding, estimator, cap, recovery, and exit-code behavior.
Reuse selected EVM sources in payments setup --auto	entry-point parity	payments fund integration	final validation	Automatic setup reuses the same resolved source and execution layer without changing its target, deposit, approval, or ready-summary semantics.
Document and verify multi-chain EVM payment funding	documentation and final validation	both CLI integrations; existing #6 for the first-route mainnet gate	parent closure	Deterministic, live read-only, and representative funded checks prove the supported behavior without claiming every catalog token was funded.

source contract
      ↓
EVM execution substrate
      ↓
payments fund
      ↓
payments setup --auto
      ↓
documentation and production validation
      ↓
parent complete

Existing-Issue Disposition

• Land supported-token self-funding in Filecoin Pin CLI #1 is retained as the original self-funding tracker.
• Validate the first supported Filecoin token-acquisition route #2–Reuse token acquisition in payments setup --auto #5 are retained as completed first-route implementation history.
• Harden, document, and verify Filecoin CLI self-funding #6 remains the authoritative first-route mainnet gate.
• This graph owns source-network and source-token breadth. Its implementation work may proceed while Harden, document, and verify Filecoin CLI self-funding #6 is open, but its production-ready gate may reuse and depends on Harden, document, and verify Filecoin CLI self-funding #6's successful first-route result.
• No existing issue is superseded or closed by this graph.

Scope

• Filecoin plus the seven named external EVM source networks.
• Runtime Squid chain/token catalog validation inside the fixed network boundary.
• Unique-symbol and exact-address token selection.
• Native and ERC-20 source tokens.
• Dynamic token decimals, chain-aware RPC verification, route targets/spenders, source native gas, and status requests.
• Filecoin same-chain routes that preserve enough FIL for transaction gas and subsequent Filecoin Pay work.
• Recovery state bound to the exact source chain and token.
• Both payments fund and payments setup --auto.
• Deterministic tests, live read-only route probes, representative funded validation, and user documentation.

Non-Goals

• --suggest-sources, wallet balance scanning, portfolio discovery, or route recommendations.
• Automatic source choice or automatic spending.
• Combining balances from multiple tokens or networks.
• Arbitrary ERC-20 addresses absent from Squid's current catalog.
• Cosmos, Sui, Solana, or other non-EVM sources.
• EVM networks outside the selected eight.
• A static whitelist of token symbols such as USDC/USDT/DAI.
• Fiat/card funding, custody, gas sponsorship, or contract changes.
• Changes to Filecoin Pin/Synapse funding estimates.
• Enabling acquisition on Calibration or devnet.

Completion Phases

Code complete

• Source contract and dynamic catalog gate complete.
• Chain/token-neutral execution and recovery complete.
• payments fund integration complete.
• payments setup --auto integration complete.
• Focused tests and repository-required build, lint, typecheck, unit, integration, and browser gates pass.
• Direct funded-wallet paths still make no provider/source-RPC call.
• Unsupported networks, tokens, routes, and destination networks fail before signing.

Code-complete PRs may merge before funded validation when the broader routes remain experimental and the remaining production checks are explicitly owned by the final child.

Production ready

• Existing Harden, document, and verify Filecoin CLI self-funding #6 first-route mainnet gate passes or its exact current-head evidence is reused.
• Live read-only route checks cover the selected chain set without treating mutable provider data as permanent.
• One non-Arbitrum external ERC-20 route succeeds end to end.
• One Filecoin same-chain route succeeds while retaining the required FIL reserve.
• Both CLI entry points are represented across the funded checks.
• Reruns do not duplicate source spending.
• Documentation explains dynamic token eligibility, exact selection, gas, caps, fallbacks, and current limitations.

Funded execution is not required for every token in Squid's mutable catalog.

Test-First And Performance Classification

Child	First behavior or invariant	Test-first mode	Performance class	Required evidence
source contract	Selected-chain catalog entries resolve deterministically; ambiguous/unsupported inputs fail closed	Fixture/contract red-green-refactor, with an exploratory exception for live API inspection	Possibly performance-relevant	Bounded catalog calls, timeouts, sanitized fixtures, no call on direct paths
execution substrate	A non-Arbitrum ERC-20 and Filecoin native source execute through the same safe state machine without fixed decimals/router/chain assumptions	Red-green-refactor plus recovery fault injection	Possibly performance-relevant	Provider/RPC call-count guardrails and operational stage timing
payments fund	Explicit resolved source funds only authoritative wallet shortfalls and preserves direct behavior	Red-green-refactor	Not performance-relevant	Focused CLI/integration tests and terminal output
payments setup --auto	Existing setup target flows through the shared source and reaches the unchanged ready summary	Red-green-refactor	Not performance-relevant	Focused CLI/integration tests and terminal output
documentation/validation	Current-head matrix proves the claimed network/token policy without overclaiming exhaustive funded coverage	Environment-smoke exception with deterministic regression tests	Not performance-relevant	Exact commands, current head, sanitized transaction IDs/output, rerun result

Provider latency and route duration are observational. Material new calls on the direct path or unbounded calls on the acquisition path are blocking regressions.

Branch And PR Policy

• Follow AGENTS.md and CONTRIBUTING.md.
• Use a topic branch and draft PR for each PR-bearing child.
• Use a Conventional Commit PR title and reference the owning issue.
• Do not commit or push without explicit user permission.
• Include terminal output for CLI-visible changes.
• Request automated review only after code, tests, documentation, and PR description are coherent.
• Resolve latest-head CI and review findings before mergeability is claimed.
• Merge into this fork's master only with explicit user authorization.

Completion Criteria

• Every child exit gate is complete.
• Every completion gate has one authoritative owner.
• The selected network boundary and dynamic token policy are documented and enforced.
• Existing direct, estimator, maximum-spend, recovery, and exit-code behavior remains compatible.
• Filecoin same-chain and external EVM paths are both proven.
• No token, route, or spender is trusted from a display symbol alone.
• No secret or generated operator report is committed to the repository.
• No balance-based suggestion feature is represented as shipped.

[snissn]

Codex issue graph execution state

Last updated: 2026-07-27

repo: snissn/filecoin-pin
base_ref: master
base_sha: 6ff5b67
mode: execute-and-merge
merge_authorized: true
merge_scope: issues 14-19, adopted prerequisite issue 6, and graph CI prerequisite PRs 21-22
max_parallel_agents: 1
max_agent_depth: 1
upstream_draft: filecoin-project/filecoin-pin#630
durable_state: this comment

Dependency graph

PR #21 base CI repair
  ↓
PR #22 ANSI-safe recovery commands
  ↓
#15 source contract / PR #20
  ↓
#16 execution substrate / PR #23
  ↓
#17 payments fund / PR #24
  ↓
#18 payments setup --auto / PR #25 ─┐
#17 ─────────────────────────────────┼→ #19 documentation and production validation → #14
#6 funded mainnet gate ──────────────┘

Issues #15-#18 are code complete and merged into the fork's master. Issue #6
did not block that implementation work. It remains a prerequisite for the
funded mainnet checks in #19.

Node state

Node	State	Result
PR #21	merged	Base lint and cross-platform payment-test repair, merge 872f435
PR #22	merged	ANSI-safe generated recovery commands, merge 26bf51b
#15 / PR #20	merged	Fixed eight-network boundary and safe dynamic Squid token resolution, merge 29689461
#16 / PR #23	merged	Chain/token-neutral quote, execution, cap, status, recovery, and Filecoin same-chain substrate, merge cd2aeb50
#17 / PR #24	merged	Selected EVM sources in payments fund, merge 9e7db54
#18 / PR #25	merged	Shared selected-source flow in payments setup --auto, merge 6ff5b67
#6	blocked	Requires an authorized, hard-capped funded mainnet environment and active-spend account
#19	running	Unfunded validation and documentation closeout; funded mainnet execution excluded
#14	open	Closes after #19 passes

Validation and review log

• PR feat(payments): resolve Squid source assets safely #20 exact head 077d76d passed focused source-catalog tests, the full
  repository suite, build/typecheck/lint, independent review, and exact-head
  Codex review.
• PR feat: generalize Squid source execution #23 exact head 420135d9 passed 125 focused tests, the full repository
  suite, package-import checks, build/typecheck/Biome/diff checks, independent
  review, CodeRabbit, and exact-head Codex review with no unresolved threads.
• PR feat(payments): support selected EVM sources in payments fund #24 exact head 0660febc passed full and focused tests,
  build/Biome/diff checks, independent review, CodeRabbit, and exact-head Codex
  review with no unresolved threads.
• PR feat(payments): reuse selected sources in setup --auto #25 exact head 215ef692 passed 247 focused tests and the full 73-file
  repository suite: 964 passed and 11 skipped. Build, typecheck, Biome, CLI
  help, published package import, independent review, CodeRabbit, and
  exact-head Codex review passed with no unresolved threads.
• Upstream Actions run
  30324170169
  passed at merged fork head 6ff5b67 on current and LTS Node.js across Ubuntu,
  macOS, and Windows, plus both browser jobs.
• Upstream draft PR
  filecoin-project/filecoin-pin#630
  points at exact head 6ff5b67 and remains a draft.

Merge log

• Base sync: upstream 8121d9b merged into fork master as f516528.
• PR fix(ci): restore cross-platform payment checks #21 merged as 872f435.
• PR fix(payments): keep retry commands executable with colors enabled #22 merged as 26bf51b.
• PR feat(payments): resolve Squid source assets safely #20 closed Resolve Squid-supported EVM source assets safely #15 and merged as 29689461.
• PR feat: generalize Squid source execution #23 closed Generalize Squid execution across selected EVM source chains #16 and merged as cd2aeb50.
• PR feat(payments): support selected EVM sources in payments fund #24 closed Support selected EVM sources in payments fund #17 and merged as 9e7db54.
• PR feat(payments): reuse selected sources in setup --auto #25 closed Reuse selected EVM sources in payments setup --auto #18 and merged as 6ff5b67.

Remaining gate

The code-complete portion of this graph is finished. No funded mainnet
transaction was performed.

Issue #19 still requires current read-only route observations and representative
funded mainnet checks, including a non-Arbitrum external ERC-20 route and a
Filecoin same-chain route across the two CLI entry points. Its funded work
depends on #6's disposable mainnet wallet, source assets and gas, Filecoin
assets, active-spend account, RPC access, and an approved hard spending cap.

The existing testnet-only key cannot satisfy that mainnet gate. Until #6 and #19
pass, #14 stays open and upstream PR filecoin-project#630 stays draft.

Unfunded closeout resumed

• Resume base: fork master at 6ff5b67.
• Active scope: deterministic matrix audit, live read-only Squid route probes, local foc-devnet, Calibration direct-path validation, and documentation reconciliation.
• Explicitly excluded: funded mainnet signing, source approvals, route execution, and spending.
• Routing: coordinator owns environments, live calls, GitHub state, and merge decisions; one bounded worker audits deterministic coverage and documentation gaps.
• Next durable transition: Document and verify multi-chain EVM payment funding #19 becomes mergeable or is reduced to a documented mainnet-only blocker.