feat: add ASCA, goal savings and collective fund stack types

[RonTuretzky]

Summary

Adds frontend support for three new stack types, backed by the new contracts in saving-circles PR #184:

Type	Contract	Routes
ASCA — flexible savings + credit lines	AccumulatingSavingCircles	/new/asca, /ascas/[id]
Goal savings — save toward a target	GoalSavingCircles	/new/goal, /goals/[id]
Collective fund — save together, spend together (white-label)	CollectiveFundCircles	/new/collective, /funds/[id]

Everything is behind feature flags (asca, goalSavings, collectiveFund in NEXT_PUBLIC_FEATURES): with flags off the app renders exactly as before (verified by building with the new env vars absent and flags off).

What's included

• Type picker on /new — four cards; ROSCA keeps the exact existing tutorial → form flow, the three new cards are feature-gated.
• Creation wizards per type (react-hook-form + zod, mirroring the existing form): ASCA (borrow limit % ≤ 100, interest %/period, period length, repayment periods), Goal (target amount, deadline, optional beneficiary vs reclaim mode), Collective (on-chain fund name, voting period, approval threshold). Each parses its creation event for the id and generates the standard EIP-712 StacksInvite links (same domain, per-contract verifyingContract).
• Detail pages: ASCA (pool stats, your savings/withdrawable/pending interest, credit line, loan + due countdown, deposit/withdraw/borrow/repay/claim, liquidate overdue members, owner deactivate); Goal (progress bar, state chip, deadline countdown by block time, deposit/withdraw/release/cancel per state rules); Collective (on-chain name — the fund IS the brand, pool balance, shares + previewWithdraw, proposals list with vote/execute, new-proposal form, deposit/donate/rage-quit).
• Join flow: /stacks/join handles type=asca|goal|collective (per-type contract, display card, redirect).
• Home + account: feature-gated sections listing your goals/funds/ASCAs via the contracts' reverse indexes; ROSCA carousel untouched.
• Plumbing: src/lib/stack-types.ts discriminator; Zod env vars (optional, zero-address defaults) + constants; hand-mirrored ABIs; per-contract tx hooks through the useSimulateAndSponsorTx pipeline; full contract-error maps; modal variants + presenter branches; make update-env picks up the new deployment keys.

Supabase

• New migration add_stack_type: stack_type text not null default 'rosca' on stacks_metadata (idempotent). Not pushed to any environment — run pnpm db:push:<env> when deploying.
• New types use prefixed metadata ids (asca:<id>, goal:<id>, collective:<id>) so id spaces across contracts can't collide; bare ids remain ROSCA. /api/stacks/metadata and /api/stacks/invite accept the optional stackType.

Deployment notes

• New env vars (all optional; features stay hidden without them): NEXT_PUBLIC_ASCA_CONTRACT_ADDRESS, NEXT_PUBLIC_GOAL_SAVINGS_CONTRACT_ADDRESS, NEXT_PUBLIC_COLLECTIVE_FUND_CONTRACT_ADDRESS.
• Flip features per deployment via NEXT_PUBLIC_FEATURES, e.g. {"asca":{"enabled":true},"goalSavings":{"enabled":true},"collectiveFund":{"enabled":true}}.
• The contracts/lib/saving-circles submodule bump to include the new contracts is deliberately left out of this PR — bump it once saving-circles PR feat(yield): draft UI to show + claim saving-circle yield #184 merges to dev.

Gates

pnpm lint (0 errors), pnpm build (all routes compile, strict TS), pnpm format:check — all green on every commit; husky lint-staged passed throughout.

Verified end to end on-chain

Added e2e/onchain-journey/ — a test-only harness that drives this UI (no test hooks, no mocked contracts) against a local anvil fork of Gnosis, and asserts every step with an independent viem read. A green run means the app's wiring produced the on-chain effect, not that the script did. The assertion reads load the app's own ABIs straight out of src/lib/abis/*.ts, so a drifted ABI fails the run. Each journey opens two browser sessions (two real wallets) so invite/join/vote are genuinely a second party, and a third wallet that is never a member is used as beneficiary/recipient.

What the journeys assert

• ASCA — create (token, borrow limit, interest rate, repayment periods, period length read back from getFund and compared exactly; a deliberately fractional 2.5% is asserted as 250 bps on chain and as "2.5% per period" rendered back in the UI) → invite + join from wallet Add local SavingCircles deployment script #2 (isMember, usedNonces, roster) → deposits from both (savings, totalSavings, poolCash, creditLineOf, and the exact ERC-20 spend) → borrow (principal, Borrowed.dueDate == borrow time + N periods, tokens actually moved, pool cash debited) → time warp + repay (principal 0, Repaid.interestPaid > 0, accInterestPerShare grew, interest split across both savers) → claimInterest (wallet receives exactly pendingInterestOf) → withdraw (savings back to 0, tokens returned).
• Goal savings — create with a beneficiary (getGoal: target, the deadline picked in the form, beneficiary) → invite + join → deposits (contributions, totalDeposited, goalReached still false below target) → crossing the target (goalReached latch, GoalReached, state Funded) → release (beneficiary receives the whole pot including overshoot, state Released, goal emptied) → a second goal in reclaim mode (no beneficiary): deposit, then withdraw refunds the contribution exactly.
• Collective fund — create with an on-chain name and approval threshold (getFund: name, voting period, approvalThresholdBps) → invite + join (isMember, memberIndex, roster) → deposits (sharesOf 1:1, totalShares, poolBalance) → propose (snapshotted electorate and requiredYes as the ceil of the threshold, proposer auto-vote, state Active) → vote from member Add local SavingCircles deployment script #2 (yesVotes == 2, state Passed, and the card's "2 yes / 2 required" compared to the chain) → execute (recipient paid exactly, pool debited) → rage-quit withdraw (payout equals floor(shares * poolBalance / totalShares) exactly — the amounts are chosen so the division has a remainder).

No app bugs were found, and no assertion was weakened to get green. Classes of bug these would have caught: wrong arg order/encoding in create, wrong decimals, percent→bps rounding, a mis-wired button (each action is opened from its own panel and confirmed in its modal, and the on-chain effect is required), and a broken read (previewWithdraw is compared to the floor formula).

GIFs — recorded straight from these runs and documented in docs/STACK_TYPES.md, which also writes up all four stack types (routes, contract, env var, feature flag, user flow) and is linked from the README and docs/ARCHITECTURE.md:

ASCA	create → invite → deposit → borrow → repay → claim interest → withdraw
Goal savings	create with beneficiary → deposit → cross the target → release → reclaim-mode goal + refund
Collective fund	create → deposit for shares → propose → vote → execute → rage-quit withdraw

How to run it

cd e2e/onchain-journey
npm install                        # playwright + viem, isolated from the app's pnpm workspace
npx playwright install chromium
npm test                           # = bash run.sh

run.sh reuses an anvil on :8545 and a dev server on :3001 if they are up (and starts them if not), checks the contract addresses in .env.local have code, funds the test wallets with gas and BREAD, runs the three journeys, and exits non-zero on any failed assertion. It never resets chain state — every journey reads nextId and asserts against the id it creates, so it is repeatable against a dirty chain.

Why the app needed one small change

Privy's embedded wallet cannot be driven from localhost: Turnstile CAPTCHA is enabled and localhost isn't in the app's allowed_domains, so an automated login is impossible — and every write in the app funnels through useSponsoredTx → Privy's useSendTransaction. Rather than mock anything, the app now has a local-only E2E wallet mode (src/lib/e2e.ts) that switches @breadcoop/ui's authProvider to "general" — a mode the design system already ships and supports, which derives the connected user from wagmi — and routes signing through wagmi's injected connector.

It is triple-gated and can never be true in a deployed environment:

1. NEXT_PUBLIC_NODE_ENV === "local" — never true on a deployed build
2. NEXT_PUBLIC_E2E_WALLET === "true" — explicit opt-in
3. NEXT_PUBLIC_CHAIN_ID === 31337 — anvil only, never a real network

The app never holds a private key: the harness injects a pure EIP-1193 proxy (announced over EIP-6963, with a wagmi store preseed so there is no connect modal); reads go to the fork RPC and signing is delegated to the harness's Node process. run.sh ends with check-bundle.sh, a hard grep gate that fails if any signing key ever appears in .next. The signers are the public anvil dev accounts, funded only on the local fork.

Two known, deliberate limitations of the local mode — both off-chain only, neither affecting any assertion: POST /api/stacks/metadata 400s because the route requires a privyUserId and there is no Privy user in this mode (the call is fire-and-forget, so names/invite links just aren't persisted to Supabase during a run); and /api/shorten 500s locally with a dummy SPOO_TOKEN, so the modal falls back to long invite URLs. Loosening the metadata route's identity model is flagged rather than done — it needs an explicit decision on how a bare wallet address maps to a users row.

[netlify]

✅ Deploy Preview for app-stacks ready!

Name	Link
🔨 Latest commit	fe0fbad
🔍 Latest deploy log	https://app.netlify.com/projects/app-stacks/deploys/6a78e911f18bc50008fb7ecf
😎 Deploy Preview	https://deploy-preview-150--app-stacks.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

---

To edit notification comments on pull requests, go to your Netlify project configuration.