Land the current Privy console funding stack

## Goal

Land the current Privy console funding stack with one durable issue owner per PR, explicit dependency order, and exact-head validation after every retarget.

## Review guide

Live state refreshed 2026-09-15 HST (2026-09-16 UTC). “Unresolved” means current, non-outdated GitHub review threads. A formal `CHANGES_REQUESTED` decision can remain after every thread is resolved and requires reviewer reapproval.

| PR | Area | Primary scope | Effort | Review |
|---|---|---|---|---|
| [#413](https://github.com/FilOzone/filecoin-pay-explorer/pull/413) | **Privy / wallet**
Core | Authentication, stable wallet identity, login states, wagmi bridge | **Hard** · 1,052 lines
(+991/−61) | Natalie + SgtPooki
**Approved** · 0 unresolved |
| [#414](https://github.com/FilOzone/filecoin-pay-explorer/pull/414) | **Shared funding**
Core architecture | Central funding host, shared dialogs, transaction-chain ownership | **Hard** · 1,056 lines
(+768/−288) | SgtPooki
**Changes requested** · 0 unresolved |
| [#415](https://github.com/FilOzone/filecoin-pay-explorer/pull/415) | **Squid / funding**
Core | Direct USDC-to-USDFC deposits, recovery, and removal of the superseded guided flow | **Hard** · 7,783 lines
(+3,558/−4,225) | Natalie + SgtPooki
**Changes requested** · 0 unresolved |
| [#416](https://github.com/FilOzone/filecoin-pay-explorer/pull/416) | **Squid / funding**
Core | Balance-aware ETH/USDC/USDT/DAI/WETH/WBTC selection | **Hard** · 1,363 lines
(+1,198/−165) | Natalie + SgtPooki
**Changes requested** · 0 unresolved |
| [#417](https://github.com/FilOzone/filecoin-pay-explorer/pull/417) | **Squid / funding**
Feature | Optional FIL gas top-up within the Squid route | **Medium** · 594 lines
(+562/−32) | SgtPooki
**Approved** · 0 unresolved |
| [#418](https://github.com/FilOzone/filecoin-pay-explorer/pull/418) | **Privy + Squid**
Feature | Buy Base USDC by card and continue into Squid | **Hard** · 1,145 lines
(+1,069/−76) | SgtPooki
**Changes requested** · 0 unresolved |
| [#419](https://github.com/FilOzone/filecoin-pay-explorer/pull/419) | **Shared funding**
Reliability | Route gasless Add Service users through Add Funds or faucet | **Medium** · 623 lines
(+571/−52) | SgtPooki
**Approved** · 0 unresolved |
| [#420](https://github.com/FilOzone/filecoin-pay-explorer/pull/420) | **Shared console**
UI/UX | Responsive tables, mobile header, touch targets | **Medium** · 80 lines
(+61/−19) | SgtPooki
**Changes requested** · 0 unresolved |
| [#421](https://github.com/FilOzone/filecoin-pay-explorer/pull/421) | **Squid / funding**
Reliability | Live-fee budgeting and consistent review/execution pricing | **Hard** · 1,502 lines
(+1,315/−187) | SgtPooki
**Approved** · 0 unresolved |
| [#422](https://github.com/FilOzone/filecoin-pay-explorer/pull/422) | **Squid / funding**
UI/UX | Exchange rate, progress timeline, clearer errors | **Medium** · 763 lines
(+728/−35) | SgtPooki
**Changes requested** · 0 unresolved |
| [#423](https://github.com/FilOzone/filecoin-pay-explorer/pull/423) | **Privy / wallet**
Reliability | Extension logout, embedded-key export, chain confirmation | **Hard** · 465 lines
(+435/−30) | Natalie
**Changes requested** · 0 unresolved |
| [#424](https://github.com/FilOzone/filecoin-pay-explorer/pull/424) | **Shared console / data**
Reliability | Refresh account data after confirmed mutations | **Medium** · 232 lines
(+216/−16) | Natalie
**Changes requested** · 0 unresolved |
| [#425](https://github.com/FilOzone/filecoin-pay-explorer/pull/425) | **Shared console**
UI/UX | Readable toast descriptions under dark system themes | **Easy** · 35 lines
(+35/−0) | Natalie approved
SgtPooki: **changes requested**
0 unresolved |
| [#426](https://github.com/FilOzone/filecoin-pay-explorer/pull/426) | **Squid / funding**
Reliability | Reliable post-approval allowance reads | **Medium** · 346 lines
(+304/−42) | Natalie + SgtPooki
**Changes requested** · 0 unresolved |
| [#429](https://github.com/FilOzone/filecoin-pay-explorer/pull/429) | **Privy / configuration**
Reliability | Development Privy fallbacks for previews | **Easy** · 77 lines
(+43/−34) | SgtPooki
**Approved** · 0 unresolved |
| [#430](https://github.com/FilOzone/filecoin-pay-explorer/pull/430) | **Privy + Squid**
Reliability | Modal stacking and FIL top-up default | **Easy** · 98 lines
(+72/−26) | Natalie approved
SgtPooki: **changes requested**
0 active unresolved · 1 outdated |
| [#431](https://github.com/FilOzone/filecoin-pay-explorer/pull/431) | **Squid + Filecoin Pay**
Reliability | Balance guard and correct rail-settlement chain | **Medium** · 279 lines
(+268/−11) | SgtPooki
**Approved** · 0 unresolved |

Why each PR has this effort rating

- **#413 — Hard:** Wallet identity spans Privy, wagmi, reconnection, and login states.
- **#414 — Hard:** Broad state-ownership refactor affecting shared dialogs and transaction flow.
- **#415 — Hard:** Cross-chain execution, locking, persistence, recovery, and retirement of the duplicate guided flow.
- **#416 — Hard:** Multi-token balances and selection feed directly into fund movement.
- **#417 — Medium:** Concentrated change, but it modifies route calculations and native-gas funding.
- **#418 — Hard:** External provider state, durable recovery, wallet matching, and duplicate prevention.
- **#419 — Medium:** Bounded flow with funding, faucet, and pre-submission timing states.
- **#420 — Medium:** Straightforward code, but needs visual and interaction checks across viewports.
- **#421 — Hard:** Fee estimation and quote consistency affect fund-moving transactions.
- **#422 — Medium:** Progress and error states must match the execution lifecycle.
- **#423 — Hard:** Small diff with security-sensitive key export and wallet/chain behavior.
- **#424 — Medium:** Asynchronous invalidation, address variants, and delayed refresh races.
- **#425 — Easy:** Isolated presentation fix with focused coverage.
- **#426 — Medium:** Narrow change requiring block-pinned RPC and retry reasoning.
- **#429 — Easy:** Small configuration fallback with documentation and focused tests.
- **#430 — Easy:** Two small, localized UI defaults with direct tests.
- **#431 — Medium:** Compact but protects balances and pins writes to the correct chain.

Related work from [#358](https://github.com/FilOzone/filecoin-pay-explorer/pull/358), [#359](https://github.com/FilOzone/filecoin-pay-explorer/pull/359), and [#361](https://github.com/FilOzone/filecoin-pay-explorer/pull/361) now lives in [#415](https://github.com/FilOzone/filecoin-pay-explorer/pull/415) and [#416](https://github.com/FilOzone/filecoin-pay-explorer/pull/416). Natalie, could you review [#415](https://github.com/FilOzone/filecoin-pay-explorer/pull/415) first, then [#416](https://github.com/FilOzone/filecoin-pay-explorer/pull/416)?

**Review effort:** Easy = isolated change · Medium = multiple states or manual validation · Hard = core wallet, funding, persistence, or cross-chain behavior.

LoC counts additions and deletions in each PR’s own diff, including tests but excluding lockfiles. For #413, this excludes 4,948 changed lines in `pnpm-lock.yaml`.

## PRs by category

- **Privy:** [#413](https://github.com/FilOzone/filecoin-pay-explorer/pull/413), [#418](https://github.com/FilOzone/filecoin-pay-explorer/pull/418), [#423](https://github.com/FilOzone/filecoin-pay-explorer/pull/423), [#429](https://github.com/FilOzone/filecoin-pay-explorer/pull/429), [#430](https://github.com/FilOzone/filecoin-pay-explorer/pull/430)
- **Squid/funding core and features:** [#414](https://github.com/FilOzone/filecoin-pay-explorer/pull/414), [#415](https://github.com/FilOzone/filecoin-pay-explorer/pull/415), [#416](https://github.com/FilOzone/filecoin-pay-explorer/pull/416), [#417](https://github.com/FilOzone/filecoin-pay-explorer/pull/417), [#419](https://github.com/FilOzone/filecoin-pay-explorer/pull/419)
- **UI/UX:** [#420](https://github.com/FilOzone/filecoin-pay-explorer/pull/420), [#422](https://github.com/FilOzone/filecoin-pay-explorer/pull/422), [#425](https://github.com/FilOzone/filecoin-pay-explorer/pull/425)
- **Transaction/data reliability:** [#421](https://github.com/FilOzone/filecoin-pay-explorer/pull/421), [#424](https://github.com/FilOzone/filecoin-pay-explorer/pull/424), [#426](https://github.com/FilOzone/filecoin-pay-explorer/pull/426), [#431](https://github.com/FilOzone/filecoin-pay-explorer/pull/431)

**UI review note:** Review each PR’s code in its individual diff, but use the latest [#431 preview](https://github.com/FilOzone/filecoin-pay-explorer/pull/431) for integrated UI testing. Please make any resulting UI fixes in #431 to avoid restacking the chain. Earlier previews require `NEXT_PUBLIC_PRIVY_APP_ID` and `NEXT_PUBLIC_PRIVY_CLIENT_ID` in the Vercel Preview environment.

## Current evidence

Audited 2026-09-15 HST (2026-09-16 UTC):

- Default branch: `staging` at `79f0d65fd1ad215855a96b956b41d2cf413cde17`.
- Active chain: staging → #413 → #414 → #415 → #416 → #417 → #418 → #419 → #420 → #421 → #422 → #423 → #424 → #425 → #426 → #429 → #430 → #431, linked on GitHub as stack #469.
- The stack is current with staging: #413 is 23 commits ahead and 0 behind, every descendant targets its immediate predecessor, and all 17 PRs report `MERGEABLE`.
- #413 is at `d827e261`, `APPROVED` / `CLEAN`, with all 10 current checks successful.
- The former guided top-up deletion follow-up landed in #415 at `f5169ed4`; its #414 review thread is resolved, so no layer 18 is required.
- #415 is at `58292116`. Its final hardening commit validates Squid cost-token chain IDs and decimals in the shared parser and adds regression coverage. All 10 current checks succeed.
- The #415 change was restacked through #431. #421’s adjacent parser conflict retained both gas-limit parsing and the new metadata guards; exact-top local build, test, type-check, lint, and format gates passed.
- #431 is at `ec15b004`, based on #430, `APPROVED`, and all 10 current checks including Vercel succeed.
- Formal approvals: #413, #417, #419, #421, #429, and #431. Formal `CHANGES_REQUESTED`: #414, #415, #416, #418, #420, #422, #423, #424, #425, #426, and #430; these need reviewer reapproval even though no active thread remains.
- There are zero active unresolved review threads across the stack. #430 retains one unresolved but outdated thread, which is not counted as active.
- All 17 owning issues remain open until their PRs land.
- Earlier implementation PRs #400–#407 and #412 are closed as superseded and were not merged.
- #393 is the historical tracker for the earlier graph and is superseded by this issue.

## Authoritative dependency ledger

| Layer | Owning issue | Pull request | Depends on | Role | Performance class |
|---:|---|---|---|---|---|
| 1 | #381 | #413 | staging | Privy login and embedded-wallet foundation | Not material |
| 2 | #394 | #414 | #381 / #413 | Shared Add Funds host and entry points | Not material |
| 3 | #395 | #415 | #394 / #414 | Direct Squid USDC deposit | Relevant to route execution |
| 4 | #396 | #416 | #395 / #415 | Curated balance-aware payment sources | Relevant to quote/source work |
| 5 | #377 | #417 | #396 / #416 | Direct 0.05 FIL fee top-up mechanism | Money-path correctness |
| 6 | #397 | #418 | #377 / #417 | Privy card funding | Money/recovery correctness |
| 7 | #398 | #419 | #397 / #418 | Add Service return-to-funding flow | Not material |
| 8 | #399 | #420 | #398 / #419 | Responsive account tables and header | UI responsiveness |
| 9 | #437 | #421 | #399 / #420 | Live fee budgeting and bounded headroom | Relevant; bounded polling/simulation |
| 10 | #438 | #422 | #437 / #421 | Squid rate and execution progress | Not material |
| 11 | #439 | #423 | #438 / #422 | Wallet exit, export, and chain switching | Security/correctness |
| 12 | #440 | #424 | #439 / #423 | Post-mutation account refresh | Relevant; bounded active-query refetch |
| 13 | #441 | #425 | #440 / #424 | Dark-mode toast readability | Not material |
| 14 | #442 | #426 | #441 / #425 | Allowance read at approval block | Relevant; one bounded RPC read |
| 15 | #443 | #429 | #442 / #426 | Public Privy development defaults | Not material |
| 16 | #444 | #430 | #443 / #429 | Funding-dialog sequencing and FIL default | Not material |
| 17 | #445 | #431 | #444 / #430 | Browser-audited funding regressions | Money/chain/recovery correctness |

Every owning issue remains open until its current PR lands. Historical text in reused issues is retained for attribution, but each issue's leading current-execution note defines its active boundary.

## Scope

- Preserve the 17-layer dependency order above.
- Keep one issue owner and reciprocal issue/PR links for every active PR.
- Resolve review, CI, and conflicts against each PR's exact current head.
- Retarget each descendant to staging only after its predecessor merges, then revalidate.
- Close an owning issue only when its PR is merged or its full scope is explicitly remapped.

## Non-goals

- Reopening or merging superseded PRs.
- Deleting branches.
- Performing a live payment.
- Treating successful checks on an ancestor head as evidence for a retargeted descendant.
- Merging any PR or changing implementation code in this tracker update.

## Non-blocking follow-ups

- [#454](https://github.com/FilOzone/filecoin-pay-explorer/issues/454): investigate MetaMask multi-account disconnect semantics. This issue is not part of the dependency ledger or completion criteria, does not block any PR in the current stack, and defers any implementation until after #431 lands.

## Validation policy

- Use focused tests for the child issue's stated invariants.
- Before merge, require the repository's full build, test, type-check, lint, and format gates for the exact candidate head.
- Re-run affected money, chain, recovery, and browser regressions after any restack or conflict resolution.
- For performance-relevant layers, keep polling, refetching, simulation, retries, and RPC reads bounded as stated in the child ticket.

## Completion criteria

- Every ledger issue has a merged current PR or an explicit durable replacement mapping.
- Every descendant has been retargeted to staging in dependency order and revalidated at its resulting head.
- Required review decisions and checks are green for the exact merge candidates.
- #431 remains conflict-free and its recovery invariants are revalidated at the final merge candidate.
- Final evidence is recorded here before this tracker is closed.