BStocks — technical reference

BStocks is a self-custodial consumer interface for Coinbase Tokenized Stocks on Base (the B20 standard). It shows prices, routes trades through DEX aggregators, builds and automates baskets, discovers yield venues, sends stock to Basenames, and explains everything it does. It never holds keys or funds, never signs on page load, and treats every external text (headlines, RSS, model output) as data, not instructions.

This document is the technical reference. The product narrative and FAQ are on the in-app page /how-it-works; the backlog is in ROADMAP.md.

1. Feature map

2. Architecture

• Next.js 16 (App Router, Turbopack), React 19, TypeScript strict, Tailwind 4, pnpm, Vitest. Server code lives in src/services (orchestration), src/providers (one adapter per external system), src/domain (types and pure rules), src/db (repositories with a memory backend and a Supabase backend), src/lib (cache, HTTP, rate gate, fallback racing, AI provider, quotas, math). UI lives in src/components, pages in src/app, route handlers in src/app/api.
• Caching. src/lib/cache.ts is an in-process TTL + stale-while-revalidate cache keyed per resource; one upstream request serves every visitor for a window. Keys marked shared (the asset registry, oracle reads, prices, feeds, Earn discovery, news, status, the statistics, the index tail) also go through a shared tier (src/lib/shared-store.ts): Upstash Redis when UPSTASH_REDIS_REST_URL/_TOKEN are set, otherwise the kv_cache table in Supabase — so on serverless, one instance computes and every other instance reads. Values are encoded with src/lib/codec.ts (bigints, Maps and Sets survive). src/lib/rate-gate.ts serialises calls to keyless APIs (GeckoTerminal ≈ 30 req/min). src/lib/http.ts provides fetchJson, per-provider circuit breakers and a metrics registry surfaced on /api/health and /status.
• Rendering. The root layout reads no cookie, so pages are not dynamic per request: pages with server data (home, markets, a stock, build, templates, baskets, profiles, automate, portfolio) carry revalidate (30–60 s) and are served from the cache between renders; wagmi hydrates the wallet connection on the client (a connected wallet shows "Connect" for a moment on a full page load). Gift receipts and pool pages stay force-dynamic. The wallet modal (@reown/appkit/react), the dithered backdrop and the 3D coins are loaded in the browser on demand (src/config/appkit.ts, src/components/fx/lazy.tsx), so a visitor who only reads prices never downloads them.
• Errors. src/lib/error-sink.ts records every error — route handlers through route(), server rendering through onRequestError in src/instrumentation.ts, the browser through src/app/error.tsx / global-error.tsx and POST /api/errors — as one counted row per distinct error in error_events. /admin lists them; /api/health counts the last hour and raises an alert past a threshold.
• Hedged fallback. src/lib/fallback.ts races a primary provider against a fallback chain with a short hedge delay; used for firm quotes.
• Warm-up. src/instrumentation.ts refreshes assets/prices at boot, runs B20 discovery (boot: 450k blocks, then every 30 min: 60k), and probes 0x hourly — on long-running Node. On Vercel (VERCEL set) it only loads the stored registry and validates the environment once (a malformed optional variable is logged and ignored rather than failing every route); vercel.json schedules /api/cron/refresh?job=discovery and ?job=sweep (Bearer CRON_SECRET) once a day, and Supabase pg_cron carries the fifteen-minute jobs (see Schedules below).
• Proxy. src/proxy.ts enforces the geoblock on execution routes (/api/trade/*, /api/earn/prepare, /api/portfolio/(plan|intent), /api/automation/prepare-run) and on writes to gifts and gift pools; the same handlers also call assertTradingAllowed themselves. There is no referral capture.
• Storage. Supabase (service role, server-side only) when SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY are set, otherwise in-memory repositories with the same interfaces. Every Supabase repo is wrapped in resilient() so a storage outage degrades to defaults instead of failing pages.

3. Onchain facts (Base mainnet, verified 2026-09-02/03)

3.1 B20 tokens (Coinbase Tokenized Stocks)

Identity is the contract address; symbols end in c. decimals = 8. scaledBalanceOf returns share-equivalents (raw × multiplier / 1e18); the UI always shows share-equivalents.

"Issued" means totalSupply > 0. "Deployed ≠ tradable": a contract with zero supply has no pool and no route; the UI labels it Not issued yet and sorts it behind live names. Trading opens automatically when supply appears.

• Transfer policy ids are sender 5 · receiver 5; policy 5 authorises any address (isAuthorized(uint64,address)), so nothing onchain blocks a holder today; pausedFeatures is empty. Pauses and policy changes are read before every action (b20-guard-service).
• extraMetadata("isin") is set per token; newUIMultiplier / effectiveAt expose scheduled multiplier changes (corporate actions).
• Coinbase deploys through 0x4ba3e29e254f25e94e61c4c9d67b37027331534d; the creator EOA is 0xe090ecbee12d4b6aee5e73ff60945f2545ef5c6f. Discovery (b20-asset-service.discoverNewAssets) scans B20Created(address indexed token, uint8 indexed variant, string name, string symbol, uint8 decimals, bytes variantEventParams) (topic0 0xfd9bf273…), keeps variant 0 with a symbol matching /^[A-Z0-9.]{1,7}c$/, requires the Coinbase creator, a Chainlink "Coinbase <TICKER>" feed and a unique ticker before auto-verifying; everything else lands in /admin as a candidate. The oracle registry answers 1e18 for any address and is therefore not used as a signal (22+ copycat NVDAc/METAc tokens exist).

3.2 Other contracts

3.3 Chainlink reference feeds

Feeds are looked up from the Chainlink Base directory (https://reference-data-directory.vercel.app/feeds-ethereum-mainnet-base-1.json, names "Coinbase <TICKER>"). They are total-return prices (multiplier already applied), heartbeat 24 h, 0.5 % deviation during US market hours. Freshness classes (src/lib/market-hours.ts): live, last-close (market closed), stale (older than ORACLE_STALENESS_SECONDS, default 93,600), frozen (paused for a corporate action). The reference is never used as an executable price.

4. Market data

Price model (src/services/price-service.ts): displayUsd is the DEX market price when a pool exists, that pool holds at least $20k, and the price is within 20% of the reference while the feed is live; otherwise the Chainlink reference (marked reference). The deviation check is mandatory rather than one of several ways to pass, because depth and correctness are different properties: TSLAc was displayed at $17,936 against a $366 reference off a pool holding $717k. When the feed is stale or frozen there is nothing to check against and the market price takes over, which is the ordinary off-hours state. executablePriceUsd comes from the provider quote; executablePriceUsd comes from the provider quote; price impact is measured against the reference or market basis. Sparklines are 7-day closes. The status model (src/lib/trading-status.ts) turns liquidity into Live (≥ $100k), Thin ($10k–100k), Very thin (a pool under $10k — labelled with a slippage warning rather than "No pool yet", which would contradict the size printed beside it), No pool (nothing at all), Not issued (zero supply), Paused. Only Live and Thin count towards "live markets" in the hero and market totals, so a $108 pool never inflates them.

4.1 A bad minute upstream is never shown as a fact

Two readings used to turn a transient failure into a claim about the stock: a totalSupply call the node did not answer was stored as 0 (so every stock read "Not issued yet" for as long as the cache held it), and a round where DexScreener and GeckoTerminal both answered nothing was cached as an empty market for its window (so every stock read "No pool" and the counters "0 live"). Both now go through src/lib/last-good.ts: the last value a loader ever produced, kept in memory and in the shared store for 30 days, replaced by the next good read and read back on the next bad one. The live-state batch (b20:live) takes the previous value per call that failed and the previous batch when the node refuses the whole multicall; the feeds (b20:feeds) likewise; the market snapshot (market:snapshot) fills each token the providers missed from its last reading for up to 24 h, keeping that reading's own updatedAt. An empty provider round is refused (keyless: no market data from any provider) rather than cached. A supply that was never read is supplyKnown: false on the asset, and isNotIssued / isIssued in trading-status.ts — the only places that decide issuance — treat it as unknown, never as zero. The counters on Home and Markets show "—" while nothing is known rather than "0".

5. Trading

5.1 Providers (src/providers/trading)

5.2 Flow

1. Indicative price (POST /api/trade/price): b20Guard.preTradeCheck (canonical asset, pause, policy, region), amount validation, then compareProviders asks every configured provider at once (2.5 s budget each), values each answer in USD at the current price minus the estimated network fee, and returns the best plus every alternative (TradeQuoteAlternative). The panel renders a route picker; auto = best net, manual = that provider only (strictProvider).
2. Firm quote (POST /api/trade/quote): the chosen provider first, hedged fallback behind it unless strict; returns calldata, spender, min received, expiry.
3. Allowance: exact amount, only to the spender the provider returned; native ETH sells skip it.
4. Simulation with eth_call before any signature; failures are explained (humanizeError).
5. Submit: EOA wallets sign sequentially; Base Account batches approval + swap atomically (EIP-5792) with sponsored gas when NEXT_PUBLIC_PAYMASTER_URL is set. Calldata carries the ERC-8021 Builder Code suffix (bc_71vd6x2w by default, NEXT_PUBLIC_BASE_BUILDER_CODE overrides it); batched sends also pass it as the EIP-5792 dataSuffix capability so smart wallets append it to the outer UserOperation callData. The site head carries base:app_id for web attribution.
6. Tracking: Submitted → Preconfirmed (Flashblocks RPC) → Confirmed; a trade record is written and matched to the chain before it counts (src/services/tx-verify-service.ts, pure checks in src/lib/chain/receipt-checks.ts): the receipt must show the stock arriving in (or leaving) the wallet the record names — who sent the transaction is never the test, a bundler or relayer may have — and the settled USDC from the receipt replaces the browser's USD figure. A record whose receipt is not in yet is kept pending and settled by the verification sweep (src/services/verify-records-service.ts, cron job verify); one the receipt contradicts is refused (TX_MISMATCH) or, if it was filed while pending, marked failed with the reason and never shown or counted. The same rule covers gifts (Transfer sender → recipient, or the escrow's GiftCreated / GiftClaimed / GiftReclaimed for that escrow id — the claimant is read from the log), Earn (the venue's Supply/Deposit/Withdraw naming the wallet), pools (PoolCreated / PoolClaimed) and the watchlist (owner session). verified_at on the row is the mark; tx_receipts keeps the receipt so the chain is asked once per hash. The activity timeline (src/lib/activity/timeline.ts, pure and tested) holds to one transaction, one row: a basket's leg trades fold into the basket, an AutoInvest run's per-stock rows fold into one run, a gift bought for someone is the gift (with the purchase price on it), gift links funded together are one row with a count, and pool deposits and claims appear as their own rows. Transfers no record explains are still read from the chain.
7. Pay with ETH: buys can sell native ETH (payWith: "ETH"); the USD amount is converted with the live ETH price; no bridge needed.
8. Gifts: buy-for-recipient delivers straight to the recipient; send-existing uses transferWithMemo(bytes32) with a reconciliation memo; both create a gift record, a public receipt page and a share sheet (Base app / X / copy). Recipients are resolved server-side: Basename forward or reverse (forward-verified), avatar, and the BStocks profile (member badge, handle when public).

5.3 Gift pools (contracts/src/GiftPool.sol)

One deposit, many equal claims — the contract behind /pools. Ownerless like GiftEscrow: no admin, no pause, no upgrade, no fee, no token allowlist; it can only pay a claimant their exact share or return the unclaimed remainder to the creator. 64 Foundry tests, including four stateful invariants (conservation, solvency, claim-count agreement, no oversold slots).

• No division onchain. The creator states the amount per claim and the contract multiplies by the slot count, so nothing rounds and no dust is stranded. splitIntoShares does the flooring in the browser and shows the creator what stays in their wallet. The invariant that follows: balanceOf(pool) >= amountPerClaim × (slots − claimed) for every leg not yet withdrawn.
• One gate, three products. gate == address(0) is an open pool (one share per address, self-claim only, so nobody can spend a pool on addresses of their own choosing). Otherwise every claim carries an EIP-712 Ticket(poolId, recipient, deadline) signed by gate — an ephemeral link key held only in the share link's fragment, or the server's campaign signer (POOL_GATE_SIGNER_KEY) which signs after verifying quests. Gated claims may be submitted by anyone, so a relayer or a sponsored smart account can pay the gas. Low-s and v ∈ {27,28} are enforced.
• Packages. Up to 8 legs (MAX_LEGS), each paying a fixed raw amount per claim, all in one claim transaction. B20 balanceOf is the raw balance and does not rebase, so a share promised at creation is the same share at claim time.
• Closing is two steps on purpose. cancel only flips a flag and moves nothing, so a stock its issuer has paused can never keep the creator from closing the pool; withdrawLeg then brings tokens home one at a time and withdraw batches the healthy ones. Base Account does both in one atomic confirmation.
• lockedUntil lets a creator give up the right to cancel for a period — an onchain-verifiable promise, shown as a Locked badge.
• Quests never reach the contract, so a new requirement is server work rather than a new deployment (src/services/quest-service.ts). They come in two grades and the app labels them everywhere — picker, claim page and creator roster:
• Checked on Base — hold-basename (reverse + forward resolution), hold-asset (balanceOf), buy-asset (candidate transactions come from trade_records, but each one is re-read from its receipt and only an ERC-20 Transfer of that asset into the claimant counts, because /api/trades is unauthenticated), sign-in (SIWE).
• Declared by the claimant — follow-bstocks, follow-x, repost-x, like-x, visit-url (any http(s) page: a site, a Discord invite, a Telegram group, a video). Nobody can read a follow, a repost, a like or a page view from outside, so POST /api/pools/[id]/attest records the claimant's own confirmation against their signed-in wallet with a timestamp, in questProof.attested keyed by quest index. The claim page opens the destination, waits out a five-second confirmation window and then attests; the row reads "Confirmed by you", never "verified", and the creator's roster tags it declared. Nothing about this is a check and the copy never says it is.
• A pool may hold up to MAX_POOL_QUESTS (8) steps and may repeat a type — three accounts to follow, two links to read — except sign-in, hold-basename and follow-bstocks, where a second copy would mean nothing (SINGLETON_QUESTS). Creator-supplied links are scheme-checked with isHttpUrl on both sides, because new URL() (and Zod's .url()) accepts javascript: and these go to window.open.
• Who claimed. PoolClaimed logs are the truth; the claim page reports its own transaction for speed (confirmed) and the daily cron sweep matches rows against logs (reconciled). Only the creator sees the roster.

6. Earn and liquidity

• Discovery (src/services/earn-opportunity-service.ts): per asset, in parallel with 7 s timeouts: Morpho (vaults via API with allRewards / netApyExcludingRewards; borrow markets by collateralAssetAddress_in), Aave V3 (reserve list onchain), Compound v3 (Comet markets), Aerodrome (v2 factory + two Slipstream factories), Uniswap v3 (factory getPool for the standard fee tiers against USDC and WETH), plus GeckoTerminal top pools for Uniswap v4 and other venues. /api/earn reports what was scanned and which venue did not answer, and the UI prints it in empty states.
• In-app execution (/api/earn/prepare → EarnDepositSheet): Morpho vaults (ERC-4626, "Powered by Morpho" + disclaimer acknowledgement), Aave V3, Compound v3; exact approval, simulation, atomic batch on Base Account; earn_actions records verified by receipt. Pools and borrow markets open on the venue while positions stay tracked here.
• Reconciliation from the chain (src/services/earn-reconcile-service.ts): the browser's record is a hint; Aave Supply/Withdraw, ERC-4626 Deposit/Withdraw and Comet Supply/Withdraw events are the truth. A cursor-driven sweep (sync_cursors, floor block 50,700,000) over every wallet the app knows fills in missing earn_actions rows and stores their receipts; it runs from the daily cron, before each statistics computation, and on demand via POST /api/admin/earn/reconcile. The activity timeline runs a per-wallet look over the last 30k blocks (incremental afterwards). Liquidity positions minted, withdrawn or harvested in the app write their own records (action deposit / withdraw / collect, provider uniswap / aerodrome, the USDC leg as the amount, both legs in USD at the pool price at the time).
• LP positions (src/services/lp-positions-service.ts): Uniswap v3 and Slipstream position managers → amounts from liquidity and ticks (src/lib/earn/lp-math.ts), USD value, range in USD per share, in/out of range, uncollected fees via a simulated collect. Counted in the portfolio total, shown on the Earn page and as an "In liquidity pools" line on the stock page.
• Liquidity map (/api/market/[address]/pools): every pool GeckoTerminal lists for a stock, with flags: prices from here, routed, LP tracked, on Earn tab, plus totals. Reserves matched onchain balances within 0.3 % when verified.
• Earn value in the portfolio: USDC positions (vault shares → assets, aToken balances, Comet balances) + LP value.

7. Strategies: Build, Community, Automate

• Build: allocation editor (sliders / exact weights, USDC cash share; locked while a plan built from it is executing), server-validated plan (POST /api/portfolio/plan) with per-leg indicative quotes, execution leg by leg with honest partial-fill state and per-leg retry (portfolio-execution). Legs the shared eligibility rule (legBlockedReason: not issued, no pool, paused, more than 2% of the pool) refuses today are deferred with the reason: policy reserve keeps their money as USDC, redistribute spreads their weight across live names. Legs that cannot be quoted are left out rather than queued to fail. "Repeat this basket on a schedule" hands the basket to Automate in the URL.
• Guided AI draft (POST /api/portfolio/intent): the request is composed from choices (theme, risk profile, cash share, exclusions, live-only) plus optional free text; the server adds market context per ticker (live or not, price, 24h move, DEX liquidity, sector tags), asks for strict JSON, re-validates symbols and weights, and returns what was sent so the UI can show it. Risk profiles bound position counts and maximum weights.
• Templates: seeded in src/content/templates.ts, stored in portfolio_templates; shown as cards with an allocation bar, live count and tags; "Load into editor" or open the template page.
• Community: published baskets (baskets, basket_votes), 7-day pulse from trade records, clones; profiles with handle, display name, bio, visibility; badges with server-computed progress (computeBadges). Votes and clones are one per signed-in wallet (basket_votes, basket_clones) and the counters move by atomic SQL increments. There is no referral programme.
• Automate: two kinds of plan, both stored in automation_rules (config_json.mode). Auto plans live in the AutoInvest contract; the row is a mirror refreshed from the chain on every read (listRulesSynced), including plans created outside the app. The keeper tick (GET|POST /api/cron/automation, src/services/auto-invest-keeper.ts) runs due plans; the owner can also run a due plan from their wallet (POST /api/automation/prepare-run → execute). Manual plans propose a due run that the owner confirms leg by leg through the same execution engine; a run moves the schedule only when something was actually bought (PATCH … action: "ran" with a summary). The target mix (drift-alert) is not a plan: it is filtered out of every plan list, cannot be run, and carries the drift threshold. Guided drafting builds a plan deterministically; free text goes through POST /api/automation/intent (live tickers only). Details: AUTO_INVEST.md.
• Rebalance (/portfolio?tab=rebalance, src/lib/portfolio/drift.ts): one drift measure for the Overview banner, the table and the proposed trades. The base is the stocks, plus cash only when the target holds a cash share; Earn and LP are never part of it. A leg trades only when it is at least 1% of the base and $5 out of line; blocked legs (same eligibility rule as Build) are shown with the reason and left out of the totals; cash is "spent" or "kept", never "sold".
• Return to target on a schedule (src/lib/portfolio/toward-target.ts, config_json.towardTarget): a manual basket plan created from the Rebalance tab against the saved target. On each run the legs are computed from the live holdings — only the stocks under target, split by how far under they are, capped at the plan's amount — and confirmed leg by leg in the wallet. It never sells and cannot be automatic (the API refuses mode: "auto" with towardTarget). A run that finds the mix within threshold is recorded as in balance (summary.inBalance) and moves to the next date rather than staying due. This is the safe form of "automatic rebalancing": bounded by the money it is given, and never a forced exit.
• Benchmark (getBenchmarkIndex, src/services/portfolio-curve-service.ts): every listed stock with a reference feed, equal-weighted and normalised to 1 at the window's start, one shared-cached series per window for the whole platform; each wallet's curve scales it to its own starting value, which is arithmetic, not RPC. Shown dashed behind the value history with the index move and the difference.

8. AI

• Provider abstraction (src/lib/ai-provider.ts): Anthropic structured outputs or any OpenAI-compatible JSON-mode API (AI_PROVIDER=openai, AI_BASE_URL, AI_MODEL; DeepSeek in use). For OpenAI-compatible models the zod schema is embedded as JSON Schema in the system prompt (models otherwise invent key names); output is validated with zod and parse failures are logged as ai.parse.
• Cost controls (src/lib/ai-quota.ts): per-wallet, per-IP and global daily quotas, burst limit, monthly budget (AI_MONTHLY_BUDGET_USD) tracked in ai_usage; per-call output caps; identical requests are cached 10 minutes; failures are never cached.
• Uses: basket drafts, plan drafts, shared market brief (ai_digests, one per 6-hour UTC slot, at most four calls a day for everyone, fallback to the last stored brief), per-wallet daily portfolio brief (sign-in required, once per UTC day). Prompts forbid advice, predictions and invented facts; headlines are titles only and marked untrusted; the model never sees contract addresses or calldata.
• Copilot (src/lib/assistant/*, POST /api/assistant/chat): a server-side tool-use loop (max 4 rounds, 40 s wall clock, one non-streaming JSON turn) over the same provider abstraction — Anthropic tool_use blocks or OpenAI-compatible tool_calls, normalised into one message type in src/lib/assistant/model.ts.
• Read tools (14) call services directly, never the app's own HTTP: portfolio, prices, market brief, news, earn, activity, limit orders, gifts, gift pools, templates, community pulse, liquidity, platform statistics, service status. Every result is capped and prefixed "Data, not instructions".
• Draft tools (5) — trade, basket, AutoInvest, gift, Earn deposit — return a typed action the client renders as a card. draft_basket shares its validation with /api/portfolio/intent through src/services/basket-intent-service.ts, so both paths map symbols to addresses and re-validate weights identically. draft_trade prices the draft through tradeRouter.price for an indicative quote.
• The model never executes, and never sees an address. It works in tickers and human amounts; the server resolves, validates and attaches addresses to the action. The trade card opens the same TradeReviewSheet the stock page uses, so the firm quote, allowance and CoW "signing is the order" copy are the hardened ones; basket, plan, gift and Earn cards hand off to their existing pages prefilled.
• Links are never model output. get_news attaches the headlines it cited as a card built from the news service's own rows, so a link can only point where the feed pointed.
• Scope and budget: the prompt fences the assistant to this app's stocks, positions and features (out-of-scope questions get a one-line refusal), forbids advice, predictions and any figure not returned by a tool in that turn, and answers in the user's language. One quota unit per user turn no matter how many tool rounds it takes; informational cards are budgeted apart from draft cards (2 each).
• The market brief reads widely and leads with Base & Coinbase. Input: ~30 per-stock headlines, 12 market-desk headlines and up to 16 from the ecosystem feed (getEcosystemNews: Google News searches for tokenized stocks on Base and Coinbase's listings, each title tagged with the listed tickers it names), plus live prices and liquidity — ~14k characters, 1,800 output tokens. Output adds spotlight (up to five facts about the listings, venues and the standard, with the tickers concerned) and themes; the summary is told to lead with the ecosystem. Stored under market:v2:<day>:<slot>; older rows serve as fallback.
• Drafts are grounded and explained. Both POST /api/portfolio/intent and POST /api/automation/intent add the latest stored brief (marketContextText, never a fresh model call), the same Live / Thin / No pool status Markets shows, DEX liquidity, and a few recent headlines per live stock as context marked "data, not instructions". The basket draft returns commentary — thesis, why each leg and its weight, what could go against it, facts from the headlines — rendered under the editor as "Why this mix" (marked "for the draft as generated" once the user edits). The plan draft returns commentary.why and commentary.watch, shown under the assistant's draft. Commentary explains a template; the prompts forbid recommending or predicting.

9. Compliance

• Coinbase Tokenized Stocks are offered to eligible persons outside the United States. GEOBLOCK_COUNTRIES (default US) + GEOBLOCK_MODE: attest (default) shows an eligibility notice and lets the visitor self-certify (HttpOnly cookie bstocks_eligibility, 30 days), block answers 451. /api/region tells the UI the country, mode and current state. Nothing onchain blocks a holder today (policy 5), so the interface rule plus the legal notice is the enforcement layer; 0x's opt-in requires block.
• What the edge closes (src/proxy.ts, covered by src/proxy.test.ts): execution routes for every method (/api/trade/*, /api/earn/prepare, /api/portfolio/{plan,quote,execute}), and writes only on /api/gifts and /api/pools — creating a gift or a pool, and asking BStocks to sign a claim ticket, is distribution of a tokenized security. Reading a receipt, the pool directory or a quest checklist is browsing and stays open everywhere.
• What the edge cannot close: the claim transaction goes straight to the contract from the claimant's wallet. The eligibility notice on /gifts/claim/[id] and /pools/[id] is the gate there, as it is for any self-custodial transfer. The give side is gated in the UI too — /gifts shows the notice instead of the create flows for a restricted visitor.
• The legal notice (footer, Settings, How it works) states: independent interface, not a Coinbase or Base product, no investment advice, templates are not recommendations, yields are variable.

10. Storage (Supabase)

trade_records, gifts, portfolio_executions + portfolio_execution_steps, portfolio_templates + portfolio_template_allocations, portfolio_snapshots (daily value history), watchlists, profiles, baskets + basket_votes + basket_clones, automation_rules, earn_actions, discovered_assets (with underlying, chainlink_feed, tags, eligible, auto_verified, creator, reason), ai_usage, ai_digests, tx_receipts (verified receipts: hash, status, block, block time — written once, shared by every instance), sync_cursors (where each chain sweep left off), kv_cache (the shared cache tier), wallet_index + chain_transfers (the app's own index of tokenized-stock transfers for the wallets it knows), error_events (one counted row per distinct error). trade_records, gifts, earn_actions and gift_pools carry verified_at / verify_note. Schema: supabase/schema.sql is the readable reference; the migrations applied through the Supabase MCP (and the files under supabase/migrations/) are the source of truth.

10.1 Statistics at scale: daily rollups

stats_daily holds one row per finished day: the day's verified events reduced to counters, distinct wallets, per-stock, per-route and per-venue totals (DayRollup, built by buildDayRollup in src/lib/stats/aggregate.ts). A day is finished once it is 35 days behind (LIVE_DAYS); the rollup cron job reduces up to 14 such days per run, oldest first and contiguously, so "the day after the latest rollup" is always the live boundary. The live computation (getPlatformStats) then reads only records created after that boundary (gifts 120 days further back, because a claim link's record predates its claim by up to 90 days) and adds the rollups for everything before, event by event the same way; the 30-day windows, the daily chart and the ledger always come from live records. A rollup that overlaps the live window is ignored rather than double-counted. Without any rollups (a fresh database) everything is read live, as before. Status counters that are not events — open links, live pools, plans, executions, profiles — still come from their tables.

11. Environment variables

• INTEGRATOR_FEE_BPS / INTEGRATOR_FEE_RECIPIENT: integrator fee on routes that can carry one and price it into the quote (KyberSwap, CoW, 0x), in basis points, capped at 100; off unless both are set. Shown on the quote, stored on the trade record (fee_bps), summed on /stats.

No CoinGecko key is used (keyless DexScreener + GeckoTerminal). Coinbase Onramp is deliberately not integrated.

12. API routes

13. Operations

• Schedules. Supabase pg_cron + pg_net (migration pg_cron_app_schedules, 2026-09-13) tick the AutoInvest keeper every 15 minutes and call the time-sensitive cron jobs (index, verify, earn, pools, rollup, stats, status) once each per quarter hour, offset a minute apart; the bearer is read from Vault under the name cron_secret (stored 2026-09-13 with node scripts/vault-cron-secret.mjs, which reads CRON_SECRET from .env and never prints it; rerun it after rotating the secret). .github/workflows/refresh.yml and keeper.yml ask for the same cadence but GitHub's schedule ran them about seven times a day; they are switched off with the repo variables REFRESH_ENABLED=false / KEEPER_ENABLED=false and can be turned back on as a fallback. Overlapping ticks are safe either way because a plan is claimed in one statement. vercel.json keeps two daily runs, ?job=discovery and ?job=sweep (the Hobby plan allows two crons; the automation entry went, pg_cron ticks the keeper); the sweep also prunes error_events older than 14 days and the daily AI counters older than 7. monitor.yml reads /api/health every 30 minutes and fails the run — GitHub emails the owner — when alerts is not empty: keeper below 0.0005 ETH, a dependency down, 20+ errors in the last hour, a storage table missing.
• Indexing. src/services/chain-index-service.ts: a wallet is scanned once when it first opens its timeline (registerWallet: 120k blocks of Transfer logs for the 13 stocks, plus a one-time Earn reconciliation), then the index job reads every stock's transfers for the blocks mined since the last sweep — one getLogs per 10k blocks however many wallets there are — and keeps the rows touching an indexed wallet. A timeline read is a table lookup plus one bounded, shared look at the unswept tail.

• /status probes: Base RPC, Chainlink feed, DexScreener, GeckoTerminal, 0x, KyberSwap, OKX, Uniswap API, Velora, Aerodrome, Morpho, Aave, Compound, DEX pools, discovery, Basenames, Supabase, AI provider, news feeds, Builder Code. HTTP 429 is reported as degraded, not down.
• /api/health exposes the metrics registry (calls, errors, last error per counter, breaker opens) in non-production or with the admin token.
• /stats is the platform ledger: headline figures per window (24h / 7d / 30d / all), trading by stock and route, strategies (baskets, AutoInvest and manual plan runs, community baskets), gifts (direct, links, pools, valued at today's price), Earn by venue, people (wallets counted once), a 30-day chart, a verification block (verified / pending / reverted / no hash / duplicates collapsed) and the latest verified transactions with Basescan links. Rules: a transaction counts only with a success receipt; one (transaction, stock, side) is one trade, merged across trade rows and execution steps; a gift bought for someone is one trade and one gift.
• Checks used in development: pnpm exec tsc --noEmit, pnpm exec eslint src, pnpm exec vitest run, pnpm exec next build.

14. RPC and provider economy

• Public data is fetched once per window and shared: assets, prices, oracle state, OHLCV, pools, earn discovery and the shared AI brief all live in the in-process cache; ten visitors cost one upstream call per window, not ten. The cache is bounded (5,000 keys, swept every two minutes).
• Per-wallet data (balances, LP positions, the portfolio snapshot) is unavoidable per user but is also cached briefly per wallet (snapshot 15 s, LP 30 s) and invalidated when the app itself records a trade.
• The activity timeline no longer scans logs per wallet: transfers come from the app's own index (chain_transfers), filled by a sweep whose cost does not depend on the number of wallets, plus one shared look at the last few thousand blocks.
• What is the same for everyone (prices, assets, feeds, discovery, the statistics) is computed once per window across all serverless instances through the shared cache tier, not once per instance.
• Client polling is deliberately slow (balances 30 s, portfolio 45 s, activity 120 s, assets 30 s against the server cache) and pauses in background tabs through React Query defaults.
• Background work (market warm-up every 30 s, status probes every 5 min) runs only while a request arrived in the last 10 minutes (src/lib/activity-pulse.ts); an idle deployment makes no calls. Asset discovery (every 30 min) and the hourly 0x probe are the only unconditional jobs.
• Status checks are cached 60 s; a single failed probe shows as degraded, an outage needs two consecutive failures; the page shows the last 12 probe results per component.