FilOzone / FilOzone/filecoin-pay-explorer

feat(explorer): make Squid source-token selection balance-aware

Open
#356 0 comments 0 reactions 0 assignees View on GitHub
enhancement
Dominant language
TypeScript
Stars
3
Forks
7
Avg merge
5d 14h
Merged PRs (30d)
47

Description

## Description

Follow-up to #320. The Squid top-up flow currently loads the complete supported-token catalog for the selected source chain, puts the native token first, and reads a balance only after the user selects a token. Balance-based filtering and sorting were intentionally deferred until the Explorer had a shared batched balance source.

This matters because a source chain can expose hundreds of supported tokens. On 2026-08-26 the live Squid catalog contained 1,068 entries for Base alone, so issuing an independent browser RPC request for every token is not acceptable.

Source context: https://github.com/FilOzone/filecoin-pay-explorer/pull/320#issuecomment-5376562045

## Goal

Make source-token selection balance-aware so users can quickly find tokens held by the connected wallet without losing access to the complete Squid-supported catalog when balances are loading, incomplete, or unavailable.

## Scope

- Load source-token balances only for the selected source chain and connected account.
- Use a reusable batched balance source, such as bounded failure-tolerant multicall chunks; do not issue one independent request per catalog token.
- Read the native-token balance separately from ERC-20 `balanceOf` calls.
- Cache and invalidate balance inventory by account, chain, and relevant catalog identity.
- Show positive-balance tokens first, with the native token first when it has a positive balance.
- Default the selector to wallet-held tokens after balance inventory succeeds, while preserving an explicit way to search or show all supported tokens.
- Treat failed or unreadable token balances as unknown rather than silently classifying them as zero.
- On partial or complete balance-source failure, preserve the complete catalog and expose a non-blocking retry state instead of dead-ending token selection.
- Reuse a known inventory balance for the selected token when it is current, avoiding an immediate duplicate balance request.
- Preserve existing source-network changes, invalid-selection handling, quoting, allowance checks, and native-gas balance checks.

## Non-goals

- Discovering arbitrary wallet assets outside Squid's supported-token catalog.
- Loading balances across all supported source chains before the user selects one.
- Pre-quoting every token or ranking tokens by route quality.
- Treating a positive balance as proof that a token is trusted or verified.
- Replacing the source selectors tracked by #343.
- Performing the broader guided-funding orchestration refactor tracked by #342.

## Done criteria

- [ ] A connected wallet with held Squid-supported tokens sees those tokens before zero-balance or unknown-balance catalog entries.
- [ ] Users can still search or reveal the complete supported-token catalog.
- [ ] Native and ERC-20 balances are loaded through bounded requests for only the selected chain.
- [ ] Duplicate catalog addresses are not queried more than once.
- [ ] Individual token-call failures do not fail the entire inventory.
- [ ] Account or network changes cannot display stale balances from the previous selection.
- [ ] Loading, empty-wallet, partial-failure, full-failure, and retry states remain usable and accessible.
- [ ] Selecting a token still shows its balance and preserves the existing quote and acquisition safety checks.
- [ ] Unit tests cover balance partitioning and ordering, including native, zero, duplicate, and unknown balances.
- [ ] Data-layer tests cover batching, partial failures, cache identity, and stale account/network responses.
- [ ] Component tests cover the wallet-token default, showing all tokens, retry behavior, and token selection.
- [ ] `pnpm build`, `pnpm test`, `pnpm type-check`, `pnpm lint`, and `pnpm format` pass.

## Coordination

- #343 owns the styled searchable source selectors. This issue owns balance inventory and balance-aware list behavior; coordinate landing order to avoid rebuilding or conflicting with that selector work.
- #342 owns the broader component and orchestration split. The balance source should be reusable and compatible with that direction, but #342 is not a prerequisite.

Contributor guide

No contributing guide indexed for this repository

Research direction

Start by reviewing the existing Squid top-up source-token flow and the context in #320, then coordinate with the selector work in #343 and orchestration work in #342. Use the listed unit, data-layer, and component test requirements to define the balance states and ordering, and verify completion with pnpm build, pnpm test, pnpm type-check, pnpm lint, and pnpm format.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
frontend
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.