FilOzone / FilOzone/filecoin-pay-explorer
Guided top-up: bundle FIL for gas so zero-FIL wallets can actually use their USDFC
- Dominant language
- TypeScript
- Stars
- 3
- Forks
- 7
- Avg merge
- 6d 14h
- Merged PRs (30d)
- 61
Description
> [!IMPORTANT]
> Current execution is tracked by #436. This issue now owns the direct 0.05 FIL fee top-up mechanism in PR #417, after #396 / PR #416. The fresh-open default and opt-out behavior is owned separately by #444 / PR #430; the earlier 0.25 FIL, balance-dependent, and FIL-only recovery design below is historical context rather than the current acceptance boundary.
## Problem
A wallet with no FIL can complete the guided top-up swap (USDC → USDFC lands on Filecoin), but then cannot submit the deposit transaction: `depositWithPermitAndApproveOperator` needs FIL for gas, the wallet has none, and the product offers no recovery. The user is stuck holding USDFC they cannot deposit.
The FIL "Destination gas" line in Squid quotes is a routing cost Squid pays to deliver the swap — it is not FIL delivered to the user. `planSquidTopUp` requests a single requirement (USDFC on chain 314) today.
## What to add
- Bundle FIL into the top-up **by default** (if account doesn't have any FIL), with an opt-out checkbox in the quote review (visible line item, not buried).
- **Default amount: 0.25 FIL** fixed constant (sizing rationale below). User-editable amount deferred.
- **Balance detection sets the checkbox default**: wallet FIL balance 0 → checked; has FIL → unchecked (hint: "You already have FIL for fees"). Balance-read failure → default checked.
- deposit detects the FIL shortfall and offers a FIL-only top-up re-entry.
- Copy must state the FIL goes to the **wallet** (to pay network fees), **not** to the Filecoin Pay balance.
----- AI -----
### Happy path: FIL bundled into the guided top-up
- Verify/add support in `@filecoin-project/squid-evm-funding` `planSquidFunding` for a second requirement on the same destination chain: native FIL alongside USDFC to the same recipient. Open questions: one route with native drop vs two sequential routes; per-leg failure semantics (USDFC lands, FIL leg fails → executor reports and can resume the missing leg); source==FIL edge case collapses the FIL requirement.
- `planSquidTopUp` adds the FIL requirement (0.25 FIL) when the checkbox is on.
- `SquidQuoteReview` shows a distinct line `+ network fees (FIL) — 0.25 FIL` and the checkbox row:
- Label: "Include 0.25 FIL for transaction fees"
- Hint (zero-FIL): "Your wallet has no FIL. Filecoin transactions (like depositing USDFC) need a small amount of FIL. This covers about a month of typical activity. The FIL goes to your wallet to pay network fees — not to your Filecoin Pay balance."
- Primary button copy reflects the acquisition: "Swap for USDFC + FIL" vs "Swap for USDFC".
**Acceptance:** a fresh zero-FIL wallet holding only USDC on a source chain finishes the guided flow with USDFC deposited, operator approved, and ~0.25 FIL in the wallet — no manual FIL acquisition. A FIL-holding wallet sees the box unchecked and acquires USDFC only.
### enhancement: Follow-up: FIL recovery path at deposit time
For users who opted out (or ran dry anyway):
- Before enabling the deposit action (guided step 3 and standalone deposit dialog), compare wallet FIL balance against the fee estimate.
- On shortfall: disable deposit, warn — "Not enough FIL for the network fee. This transaction needs ~N FIL, and your wallet has none. You can get a small amount of FIL the same way you topped up USDFC." — and make the primary CTA **"Get 0.25 FIL"**.
- The CTA opens the guided top-up in **FIL-only mode**: USDFC amount step skipped, quote shows only the FIL leg ("You receive 0.25 FIL (to your wallet)"), and completion returns the user to the deposit, now unblocked.
#### Sizing rationale
Client-paid ops are cheap on average but spiky:
| Op | Txs | Avg FIL | Max FIL (spike) |
|----|-----|---------|-----------------|
| depositWithPermitAndApproveOperator | 16,947 | 0.000081 | 0.189 |
| setOperatorApproval | 16,857 | 0.000063 | 0.022 |
| depositWithPermit | 2,097 | 0.000404 | 0.214 |
| deposit | 157 | 0.000111 | 0.001 |
| withdraw | 30 | 0.005157 | 0.153 |
Per-wallet monthly client-gas spend (255 wallet-months): median ≈ 0.00003 FIL, p90 ≈ 0.002, heavy non-bot user ≈ 0.07. The sizing risk is base-fee spikes (worst observed single tx: 0.19 FIL), not volume. **0.25 FIL covers a heavy month and survives the worst observed spike.**
Contributor guide
No contributing guide indexed for this repository
Research direction
Start with the current execution tracked by #436 and the direct 0.05 FIL mechanism in PR #417. Read planSquidTopUp, SquidQuoteReview, and the deposit flow; treat the fresh-open default and opt-out behavior as owned by #444/PR #430. Done means the current fee top-up boundary is implemented without taking over those separate changes.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- full-stack, payments
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 20/100