feat(payments): support selected EVM funding sources

[snissn]

Summary

This draft adds optional source funding to payments fund and payments setup --auto on Filecoin mainnet.

Users choose one source network, one token, and a maximum source amount. New acquisitions support Filecoin, Arbitrum, Ethereum, Polygon, Avalanche, and BNB Chain. The token must resolve unambiguously in the current Squid catalog and return a valid route to the FIL or USDFC required by the command.

The existing Filecoin Pin funding calculations determine the wallet shortfall. The source-funding layer requests only that shortfall, validates the route and spending limits, waits for the assets to reach the Filecoin wallet, and then continues through the existing Filecoin Pay deposit and approval flow.

If the wallet already has enough FIL and USDFC, the direct path remains unchanged and does not request a quote or sign a source transaction. External source funding remains disabled on Calibration and local devnet.

Base and Optimism are not available for new acquisitions. Their total transaction fees include OP Stack fee components that are not bounded by the transaction-level gas fields used by the current hard native-spend ceiling. Earlier Base or Optimism checkpoints with already-broadcast transactions remain recoverable without quoting or signing another source transaction.

Current status

The implementation work tracked by #15, #16, #17, and #18 is complete on the fork.

This includes:

• runtime resolution against Squid chain and token catalogs within the six-network boundary;
• native-token and ERC-20 sources with catalog-derived token decimals;
• chain-aware RPC, route, spender, expiry, quote, and spending-limit checks;
• proportional re-quoting when an initial quote exceeds the amount needed for the shortfall;
• explicit failure for provider minimums while preserving transient provider errors;
• Filecoin same-chain handling that preserves FIL needed for later transactions;
• recovery data tied to the exact wallet, source network, token, and recorded balance target;
• receipt and provider-status recovery without blind resubmission;
• bounded Filecoin balance polling after a recovered route is confirmed;
• cleanup of confirmed approval-only checkpoints after direct Filecoin funding satisfies the recorded target;
• integration with both payments fund and payments setup --auto;
• deterministic unit and mocked integration coverage for direct funding, acquisition, interruption, recovery, and rerun behavior;
• local-devnet deposit, approval, fail-closed, and rerun checks;
• Calibration direct-fund and fresh-account setup/approval checks;
• live read-only FIL and USDFC route validation from the six selected source networks, without signing or submitting a source transaction.

Local validation on the merged fork head passed 73 test files: 977 tests passed and 11 were skipped. The final implementation commit also received an exact-head Codex review with no major issues found.

The current upstream head is a87a8b23370e7062f7682b3499479e45381e0092. The full upstream Actions matrix passed on current and LTS Node.js across Ubuntu, macOS, and Windows, including both browser jobs: Actions run 30340494489.

Work remaining before review

This PR remains a draft and is not ready for maintainer review because the funded mainnet checks have not run.

#6 and #19 own that remaining work:

• execute one supported external ERC-20 route under the approved source-token and native-fee caps;
• execute one additional external-network route;
• execute one Filecoin same-chain route while preserving the FIL reserve;
• represent both CLI entry points across the funded checks;
• verify FIL and USDFC arrival, the production Filecoin Pay deposit and approval, and no duplicate source spending on rerun;
• test payments fund --days against active mainnet spend and confirm initial mainnet setup reaches ready.

#15 → #16 → #17 → #18 ┐
                        ├→ #19 → #14
#6 ────────────────────┘

No funded mainnet transaction has been completed for this draft, so it does not claim production readiness.

Safety and recovery

The funding path:

• uses the same owner address on the source network and Filecoin;
• spends one explicitly selected source token per command;
• keeps total source-token spending within the user limit;
• enforces a selected-chain native-fee ceiling before source signing;
• validates chain, token, owner, destination, amounts, contracts, spenders, expiry, slippage, and refreshed quotes before signing;
• checks Filecoin wallet balances before depositing into Filecoin Pay;
• saves non-sensitive recovery information so interrupted commands can reconcile submitted transactions without submitting the route again;
• excludes private keys, provider credentials, credential-bearing RPC URLs, and raw signed payloads from logs and recovery data.

This scope does not include wallet balance scanning, source recommendations, automatic source selection, combining multiple source tokens, non-EVM networks, or additional EVM networks.

[snissn]

The two blocking spend-bound findings have been resolved in the current draft head:

• Successful seed quotes are now proportionally downscaled and re-quoted even when the seed already covers the shortfall. Explicit provider-minimum rejections fail closed, while transient provider errors remain visible.
• Base and Optimism are excluded from new acquisitions because the current transaction-level native-fee ceiling cannot bound every OP Stack fee component. Filecoin, Arbitrum, Ethereum, Polygon, Avalanche, and BNB Chain remain available.

The review follow-ups are also complete: earlier Base and Optimism checkpoints remain recovery-only, recovered routes wait for Filecoin balance propagation, RPC mismatch errors include the actual chain ID, and confirmed approval-only checkpoints can be cleared after direct funding satisfies their saved target.

Validation on the fork passed 977 tests with 11 skipped, and the final implementation commit received an exact-head Codex review with no major issues found. This PR remains draft because the funded mainnet checks are still outstanding.

[SgtPooki]

this PR is ginormous. I am wondering if this complicated logic belongs in a separate library that we consume and use in filecoin-pin..

[SgtPooki]

this feels unnecessary? I don't think we would need to define what a payments smoke test is?

[snissn]

Separating makes sense.. let me sketch out what that can look like and what can be simplified

[snissn]

@SgtPooki good idea - I think this plan captures your suggestion:

• i'll build the payments library / move the payments code into a new repo I own here: https://github.com/snissn/squid-evm-funding
• build a new implementation of this PR on top of that repo and close this PR.
• When we get closer to ready to merge the new PR or after we merge it we can move the squid-evm-funding repo to a new owner

[SgtPooki]

@snissn before we go too far down that path, lets sync up. I think the code should probably belong in the FilOzone/filecoin-project github org, but I'm not wholly convinced all this code is necessary to begin with

[snissn]

Superseded by #637. The replacement limits the Filecoin Pin integration to interactive payments fund, moves Squid route planning and execution into the separate library, and removes automatic setup integration, repository-local recovery machinery, and smoke-test tooling from this PR. This reduces the upstream change from 47 files and 14,334 added lines to 14 files and 832 added lines. Closing this draft so there is one active review target; its discussion remains available here.