feat(payments): add interactive Squid funding to payments fund

[snissn]

What changed

This adds an optional way for interactive payments fund to acquire the FIL needed for gas and the USDFC needed for a requested Filecoin Pay deposit.

• Users explicitly choose a source chain, token, RPC URL, and source-token limit.
• Supported source chains are Filecoin, Arbitrum, Ethereum, Base, Optimism, Polygon, Avalanche, and BNB Chain.
• Source tokens may be selected by native, address, or an unambiguous symbol in Squid's current catalog.
• Before signing, the CLI shows the quoted source spend, the source-token limit, and the buffered network-fee limit.
• After the tokens arrive on Filecoin, the existing payment planner and deposit flow continue unchanged.

Direct wallet funding remains the default. Squid is not contacted unless all four source options are supplied and the wallet has a positive FIL or USDFC shortfall. This path is limited to Filecoin Mainnet, interactive terminals, and owner private-key authentication. payments setup --auto, Calibration, and devnet are unchanged.

Provider route planning and transaction execution use the published @filecoin-project/squid-evm-funding v0.3.1 package. Filecoin Pin ships with the public Filecoin Squid integrator ID and supports SQUID_INTEGRATOR_ID as an optional override.

If a process stops after confirmation, a small pending marker blocks another acquisition attempt until the user verifies both chains and removes it.

This supersedes #630, which implemented the provider, automatic-setup integration, persistence framework, fixtures, and smoke-test tooling directly in Filecoin Pin.

Checks

• Clean frozen installation of @filecoin-project/squid-evm-funding@0.3.1
• pnpm run build
• pnpm test — 755 passing, 11 skipped across 69 files

Remaining validation

No funded mainnet route has been executed at this exact Filecoin Pin and library revision. A low-value capped run still needs to verify FIL and USDFC arrival, the Filecoin Pay deposit, and a rerun without a second acquisition.

Tracked in snissn/filecoin-pin#31.

[snissn]

@codex review

[snissn]

@codex review

[snissn]

@codex review

[snissn]

@codex review

Please review exact head 5b0563d69a6a33681a1fee352d90d1c2306b8d72. This revision pins the already-reviewed library implementation to its merged v0.1.0 release; all current-head CI checks are green.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[Copilot]

Pull request overview

Copilot reviewed 13 out of 14 changed files in this pull request and generated no new comments.

Files not reviewed (1)

• pnpm-lock.yaml: Generated file

Suppressed comments (2)

src/payments/squid-funding.ts:170

• acquirePaymentShortfalls() calls validateFundingSourceOptions() but ignores its false return value. If this function is ever called with missing source options, it will continue and fail later with Unsupported source chain: (missing) (or hit the as string casts), which is a confusing error path. Make this fail closed with a clear error (or return early) when no source options were provided.

export async function acquirePaymentShortfalls(input: AcquirePaymentShortfallsInput): Promise<void> {
  const destinationRequirements = requirements(input)
  if (destinationRequirements.length === 0) return
  validateFundingSourceOptions(input.options)
  if (input.synapse.chain.id !== filecoinMainnet.id) {

src/payments/squid-funding.ts:255

• If unlink(path) fails after executeSquidFunding() succeeds, this function will throw and make the CLI treat the acquisition as failed even though tokens may already have been acquired on-chain. Marker cleanup should be best-effort to avoid turning a successful route into a reported failure.

    await unlink(path)

[snissn]

I think the unresolved question here is how to handle the squid integrator id. This context is for a CLI, so each user would be running it separately. It definitely doesn't make sense for each user to have their own squid id. I think we need to decide one of these two options, with a) possibly being invalid and b) being my preference.

a) we are OK with our squid application id being in the repo/publicaly accessible and users simply use it (Dependent on seeing the TOS and expectations of the squid id)
b) we have the CLI connect to the filecoin pay explorer service which handles the 'squid id required' api calls for them - relevant PR FilOzone/filecoin-pay-explorer#320

My immediate follow up is to look into the squid api key / id details and see if it's meant to be a public facing application ID or a private API "key"

[snissn]

OK so it looks like it is not a secret and is an identifier more like a username

Follow-up: Squid’s integrator ID is intended as a public project/integration identifier, not a secret credential. Their official browser widget embeds it directly in client-side configuration, and their API permits direct cross-origin requests carrying x-integrator-
id. The registration form also scopes it to the integrating project rather than individual users.

I think the clean solution is therefore to register or confirm a production ID for Filecoin Pin, ship it as the CLI default, and retain SQUID_INTEGRATOR_ID only as an optional override. We should confirm with Squid that distributed CLI use is covered by the
registration and terms before embedding it. A proxy through Explorer should not be necessary.

I personally went through the steps here https://docs.squidrouter.com/getting-started/integrator-quickstart for an identifier labeled filecoin-testing-{snip} and got a reply with an id very shortly after the request

[snissn]

OK Great so since it's a public identifier, i'll update the PR to use the one I generated, and if we want to we can update it to different key than filecoin-testing-94a4a25a-d40b-41cb-b148-e96098862

[snissn]

Added the public Filecoin Squid integrator ID as the default in aaeec19; SQUID_INTEGRATOR_ID remains an optional override. Build and all tests pass (755 passed, 11 skipped).

[snissn]

Updated this PR to the published @filecoin-project/squid-evm-funding@0.2.0 release in 4dc8229. The CLI now consumes the price-only plan type, and its fixture enforces that contract. Validation passes: full test suite (69 files, 755 passed, 11 skipped), build, lint, type-check, focused Squid tests (13/13), and diff checks. Package release: https://github.com/FilOzone/squid-evm-funding/releases/tag/v0.2.0

[snissn]

Updated the CLI to @filecoin-project/squid-evm-funding@0.2.1 in 75b906a. This release retains the best feasible quote when a later refinement quote slips just below the target, avoiding the spurious “could not converge” result caused by quote-price jitter.

Local validation passed: frozen install, build, 69 test files (755 passed, 11 skipped), type-check, lint, and diff checks. Independent review found no issues.

[snissn]

Updated to @filecoin-project/squid-evm-funding@0.2.2 in 87d73f8. The release adds 1% planning headroom after an insufficient price quote, accepts the first sufficient follow-up quote, and retains an eight-call fallback. Local build, tests, lint, and type-check pass.

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	@​filecoin-project/​squid-evm-funding@​0.3.1

View full report

[snissn]

Updated the CLI to @filecoin-project/squid-evm-funding@0.3.1 in 44ba287. I also made Squid source-chain native route fees explicit in the confirmation and clarified the separate transaction-gas cap in b8659f3. Local validation passed: build, all 69 test files (755 passed, 11 skipped), and two independent local reviews.