Adopt squid-evm-funding in Filecoin Pin

[snissn]

Goal

Adopt snissn/squid-evm-funding through a thin, interactive-only Filecoin Pin integration developed from upstream master, while keeping funded mainnet evidence as a separate release gate.

The active upstream draft is filecoin-project/filecoin-pin#637. The original in-repository implementation in filecoin-project#630 is closed as superseded.

Architecture Boundary

squid-evm-funding owns:

• Squid token-catalog, quote, and status behavior;
• exact FIL and USDFC shortfall route planning;
• safe EVM approval and route execution;
• route, spender, balance, nonce, and transaction-fee validation;
• destination-balance verification and sensitive-value redaction.

Filecoin Pin owns:

• authoritative FIL and USDFC wallet-shortfall calculations;
• Filecoin Pay deposit behavior;
• selected source-chain policy, source limits, CLI options, prompts, and RPC/environment resolution;
• the atomic pending marker that blocks a blind retry after interrupted execution.

The integration is intentionally limited to interactive payments fund on Filecoin Mainnet with owner private-key authentication. payments setup --auto, Calibration, and devnet behavior remain unchanged.

Issue Graph And Gate Ownership

Issue or PR	Role	Status	Authoritative gate
squid-evm-funding#10	reduced library API	Merged	Exact-head review and cross-platform CI passed; v0.1.0 is released. Upstream acceptance of the dependency form remains part of #31/filecoin-project#637 readiness.
#29	original thin-integration implementation	Closed	Historical implementation record; final scope was narrowed to interactive payments fund.
#30	deterministic validation and upstream draft	Closed	Current-head local validation passes and filecoin-project#637 remains the single upstream draft.
#31	funded mainnet evidence	Open	Representative execution proves arrival, deposit, and no duplicate acquisition before filecoin-project#637 becomes ready for review.

squid-evm-funding#10 -> #637 deterministic/CI validation -> #31 funded evidence -> ready-for-review decision

Existing Work Disposition

• Upstream PR feat(payments): support selected EVM funding sources filecoin-project/filecoin-pin#630: closed as superseded by feat(payments): add interactive Squid funding to payments fund filecoin-project/filecoin-pin#637; retain its discussion as historical design evidence.
• Upstream PR feat(payments): add interactive Squid funding to payments fund filecoin-project/filecoin-pin#637: keep draft until Verify Filecoin EVM funding on mainnet #31 passes and upstream maintainers accept the versioned dependency form.
• Land multi-chain EVM funding for Filecoin payments #14 and Document and verify multi-chain EVM payment funding #19: retain as history of the broader implementation graph.
• Resolve Squid-supported EVM source assets safely #15–Reuse selected EVM sources in payments setup --auto #18, Land supported-token self-funding in Filecoin Pin CLI #1, and Harden, document, and verify Filecoin CLI self-funding #6: retain as regression, design, and evidence history.

Documentation Minimality

• Keep README/help changes short and task-oriented.
• Define only provider-specific terms that developers need; do not add glossary entries for ordinary operational phrases.
• Keep funded evidence and generated reports outside the repository.
• Avoid route decision records or operator artifacts unless maintainers request them.

Performance Classification

The integration is possibly performance-relevant only for provider/RPC call behavior. Zero-shortfall paths make zero Squid/source-RPC calls and provider polling is bounded. No throughput benchmark is required.

Completion

• Reduced library revision is immutable and passes local lint, typecheck, tests, build, and package checks.
• Library PR feat: acquire wallet shortfalls in automatic setup #10 passes latest-head review and CI, merges, and v0.1.0 is released.
• Upstream maintainers accept the versioned dependency form.
• Filecoin Pin uses one thin adapter from interactive payments fund.
• Fresh upstream draft feat(payments): add interactive Squid funding to payments fund filecoin-project/filecoin-pin#637 is open with current deterministic tests and caveats.
• Deprecated upstream PR feat(payments): support selected EVM funding sources filecoin-project/filecoin-pin#630 is closed with a link to its replacement.
• Issue Verify Filecoin EVM funding on mainnet #31 records funded mainnet evidence against the exact Filecoin Pin and library revisions.
• Only then may feat(payments): add interactive Squid funding to payments fund filecoin-project/filecoin-pin#637 be considered ready for maintainer review.

[snissn]

Code-complete milestone reached. Fork PR #33 merged into the upstream-based integration branch, and the fresh upstream PR is open as draft filecoin-project#637 with no review requests. Issue #30 is closed. The parent remains open because funded mainnet verification in #31 has not been run; filecoin-project#637 must remain draft until that gate and the upstream dependency-version decision are complete.

[snissn]

Reduced execution graph

This comment supersedes the recovery and payments setup --auto requirements in the tracker body and closed child issues for the next implementation. Their history remains intact.

L1 Reduce squid-evm-funding to a stateless executor
  -> L2 Rebuild Filecoin Pin integration from current upstream master
      -> L3 Update upstream draft and deterministic validation
          -> #31 Funded mainnet evidence

L1 — library reduction

Keep the eight supported EVM source chains, Squid-catalog ERC-20/native tokens, exact FIL/USDFC shortfall planning, provider minimum handling, trusted route validation, exact approvals, native/source fee caps (including OP Stack total fees), Filecoin source reserve, receipt/status polling, and destination-balance verification.

Delete checkpoint/HMAC persistence, operation IDs, load/save and broadcast hooks, transaction-history reconstruction, automatic resume, manual sealing, and partial-operation state. The executor becomes plan -> validate -> execute -> verify -> return.

L2 — Filecoin Pin integration

Use Squid only from interactive payments fund, after explicit source-spend confirmation. Do not invoke Squid from payments setup --auto.

Replace the old recovery system with one conservative exclusive pending marker created immediately before execution and removed only after successful destination verification. If a process exits or any error occurs, later runs refuse until the user manually verifies chain state and removes the marker. No automatic replay or recovery state machine.

L3 — integration and upstream draft

Base the new integration on current filecoin-project/filecoin-pin:master, not the conflicted draft head. Keep tests focused on planning, transaction safety, interactive confirmation, fail-closed networks, pending-marker refusal, successful marker cleanup, and direct/zero-shortfall behavior. Update draft PR filecoin-project#637 only after current-head checks pass.

Routing and gates

Node	Repository / branch	Merge target	Gate
L1	snissn/squid-evm-funding / new reduction branch	main	focused tests, build/lint, mature review, latest-head CI
L2–L3	snissn/filecoin-pin / rebuilt integration/squid-evm-funding	upstream draft branch only	focused + full tests, browser/build/lint, mature review, latest-head CI
#31	funded environment evidence	none	remains separate; upstream PR stays draft until explicitly reconsidered

Performance classification remains provider/RPC call-count relevant only: zero-shortfall paths make zero provider/source-RPC calls and polling is bounded. No throughput benchmark is required.

[snissn]

L1 complete: FilOzone/squid-evm-funding#8 merged after exact-head review and green Linux/macOS/Windows CI. Reviewed implementation head: 1714c790567fb9f84a7c30941024a1686e25e7ff. Main merge commit: bda669309a84bc50cc4e0d7f299764d00ed71ee8. The library is now stateless and net 2,110 lines smaller than its prior main baseline; 35 tests cover the retained route, cap, fee, approval, status, and destination-verification safeguards. L2 Filecoin Pin integration is in progress from current upstream master.

[snissn]

Library packaging follow-up is complete:

• snissn/squid-evm-funding#9 merged at ad4c7f007637d9ae2ba2f2bdb48cf9f7beea01b6.
• Git dependency installs now build dist through prepare.
• A clean npm Git-consumer import is covered on Linux, macOS, and Windows.
• The Filecoin Pin integration is being repinned to this immutable commit for its full validation pass.

[snissn]

Reduced implementation complete

The reduced code path is now the head of the upstream draft: filecoin-project/filecoin-pin#637 at a9343da17605cd28c13cf9bae8d0cb03f399c87a.

• The old conflicted draft implementation was replaced with a branch based on current upstream master (08bb6c1208da13e31558be1157eed39d70ef199c).
• The draft is 14 files and +879/-9, down from 22 files and +1,826/-43.
• Squid acquisition is available only from interactive payments fund; payments setup --auto is unchanged.
• Checkpoints, operation IDs, automatic resume, broadcast hooks, and recovery state machines are absent. One exclusive pending marker prevents a blind retry after confirmation.
• Eight source chains, Squid-catalog ERC-20/native tokens, Filecoin as a source, exact shortfalls, spender/target validation, exact allowances, quote expiry/refresh, source limits, and native-fee commitments remain covered.
• The adapter pins squid-evm-funding at reviewed immutable commit ad4c7f007637d9ae2ba2f2bdb48cf9f7beea01b6.

Exact-head validation is green: 751 tests passed (11 skipped), both browser jobs passed, the Linux/macOS/Windows Node matrix passed, both Socket checks passed, and an independent exact-head review found no actionable issue. The draft is mergeable without conflicts but intentionally remains a draft.

The parent stays open for #31: a low-value funded mainnet run and an upstream-acceptable versioned library release are still required before asking maintainers for review.