Jayverse — feature-design hub

Entry point for the Jayverse feature designs. The umbrella plan (services, repo/agent map, build order) lives in ../tasks/09-02-jayverse.md; this file is the design hub — it answers the cross-cutting architecture question below and indexes the per-service design docs.

See also: rails shortlist — a cross-cutting menu of what each Jayverse product can build on, by need (oracles, cross-chain, AA, execution, payments…).

Contents

• Per-service design docs
• Phase overview
• Open Questions
• Running each service
• Chainlink — infra Jayverse uses, not builds
• History

Per-service design docs

Each service jay commented on gets a jayverse-<service>.md design doc: user scenario, what the web app shows, the flow/user journey, a basic imaginable feature, and how to implement it — grounded in the existing services so they cooperate rather than sit alone.

(#1–9 are the committed services; #10 Dark Horse is candidates, not committed — including Base App, moved from #8. Detail lives in jayverse-darkhorse.md.)

Completed — built, past design

Once a service moves from design into a running build it leaves the drafting list above and lands here, so "what's still a draft" vs "what actually runs" stays legible at a glance.

Every doc is a design draft for review, not built work — the implementation status stays in the umbrella plan's Remaining sections and in each service repo.

Phase overview (at a glance)

Each service's own jayverse-*.md carries its full Phases (build order) table; this is the cross-service snapshot. Three phase columns — where a service has more than three phases, the extras are crammed into the last column (Wallet's P3 + P4, etc.). ✅ = that phase is built.

It also doubles as a running log. When something gets implemented that wasn't in the plan, add it to that project's currently-ongoing phase cell and mark it ✅ — e.g., a new Wallet capability lands under Wallet's Phase 2. That way the overview records what actually happened, not only the original plan (jay, 2026-09-11).

Open Questions

Should the web app and the API be separated between Rabbit and Verex?

jay's concern: if every app runs inside the Rabbit portal on rabbit cloud, that one instance carries the load of the whole ecosystem.

Short answer: yes — separate the APIs into their own Cloud Run services; keep Rabbit a thin portal. This is already what the umbrella plan's cloud split implies; this doc makes it explicit.

The rule: one portal, many backends

• Rabbit stays a thin portal. The plan's principle already says "Rabbit imports, it doesn't contain" — it shows a service by importing that service's UI (npm package / git submodule) or by linking/proxying to the running service. The portal's own Cloud Run instance therefore serves navigation, auth, and light read UI, not the heavy per-service work.
• Every service's API is its own Cloud Run service. jayverse-defi-api, jayverse-personas-api, the verex API, etc. each deploy independently, scale independently (Cloud Run autoscales per service), and a spike in one cannot starve the portal or another service. This is the whole reason the burden concern goes away: the portal instance never runs another service's compute.
• Money-moving vs. read-only decides the cloud, not the separation. The plan's 4:4 split already routes market-coupled services (Verex, DeFi, Unity worker, Bridge) to verex cloud and portal/AI/read services (Rabbit, Personas, Wallet, Auditor) to rabbit cloud. Separation is orthogonal: within either cloud, each API is still its own service.

Where the web (frontend) lives — the placement decision (jay, 2026-09-07)

The rule jay settled on: web consolidates, APIs split, Verex is the one exception.

• All web apps live in rabbit cloud — one portal, one domain (jaylabs.xyz/<service>), one login. A frontend is light (SSR/static + client fetch), so co-locating them costs little and buys a single deploy surface for the UI.
• APIs keep the 4:4 split by money-movement, regardless of where their web is served.
• Verex is the exception: its web stays in verex cloud, beside its own API — it's heavy, independently branded, and already live at verex.jaylabs.xyz.

Why this holds up: a web app in rabbit cloud calling an API in verex cloud is just HTTPS — API→API or browser→API, exactly how rabbit's live console already calls the verex prod API today. Most web→API traffic is client-side fetch from the browser, which hits the API directly no matter which cloud served the page, so cross-cloud placement adds no hot-path latency. The API is always its own Cloud Run service either way, so the burden answer is unchanged: each API autoscales alone.

Rabbit has no separate API server today (jay asked, 2026-09-07). Rabbit is one Next.js Cloud Run service; its "API" is Next.js route handlers under app/api/* baked into that same service. So "Rabbit API" in the table is fused into the portal for now — web + route handlers in one instance, which is exactly the thin-portal shape we want. Split it into a standalone rabbit-api service only if that backend later grows heavy enough to autoscale on its own. The other three rabbit-cloud APIs (Personas, Wallet, Auditor) are their own services from the start.

Hosted infra is not in the split (jay asked, 2026-09-07). The ERC-4337 bundler and paymaster are not Jayverse services — the bundler is a hosted relay (thirdweb for v1, Pimlico as the portable alternative) and never something we implement. Locally, where an anvil fork can't reach a hosted bundler, we self-relay (EntryPoint.handleOps from a funded account) instead of running one; the local-vs-Sepolia switch lives in jayverse-rabbit.md §7. Treat other such infra the same way: rented/hosted, behind an environment selector, outside the 4:4 count.

Concrete guidance for the burden worry

1. Rabbit portal = one small Cloud Run service (max-instances low; it only routes + light UI).
2. Each service API = its own Cloud Run service, its own repo, its own deploy.sh, its own DB.
3. Shared chain config/addresses via the jayverse-rails package so no service hardcodes another.
4. Cross-service calls go API→API over HTTPS, never in-process — that's what keeps one service's load off another's instance (exactly how rabbit's live console already calls the verex API).

Net: the portal never carries another service's compute, so "all apps in rabbit cloud" is not a single-instance burden — it's several small autoscaling services that happen to share a GCP project.

Running each service on the terminal

Each service is its own repo (sibling folders under ~/work), its own pnpm/Foundry project. The six study webs have their port baked into their dev script by the rule port = 3000 + (service #) × 10, so plain pnpm dev opens the right one and they never collide. Rabbit portal (:3100) and Verex web (:3000) keep their own defaults. Services with contracts need a local anvil started first.

Ports: the six study webs bake their port into dev (3000 + # × 10) — DeFi :3030, Personas :3040, Game :3050, Wallet :3060, Token :3070, Auditor :3080, Number :3090 — so pnpm dev alone is right and they run side by side. Unchanged: Rabbit portal :3100, Verex web :3000 / API :4000, anvil :8545.

†OFA (#8) nominally maps to :3080 too, the slot the now-completed Auditor still bakes in. OFA is contracts-first (Foundry + anvil), so a web harness is optional; if you add one, run it or the Auditor one at a time, or reassign OFA's port.

Chainlink — infra Jayverse uses, not builds

Chainlink's oracle stack (Data Feeds, CCIP, Proof of Reserve, VRF, Automation) is settlement-rail infrastructure Jayverse consumes, not reimplements. This is the dependency map — where each product plugs in, and the one place an oracle deliberately cannot help. Not a build; a map. (Product names verified against chain.link, 2026-09-09.)

The one deliberate non-use — pricing a self-made token. Verex prices YES/NO with LMSR, and JYVE is priced by a constant-product mini-AMM (price = reserve ratio), not a feed — because a token that trades only in our own market has no external truth an oracle could report. Oracles carry external facts onto the chain; where there is no external fact, an oracle is the wrong tool. (Rationale: jayverse-token-bridge.md.)

Proof of Reserve answers the Liquid class. The liquid-issuance-not-authorization PoC showed a mint bug producing valid-but-unbacked units that a correct peg-out faithfully honored — authorization checked the actor, nothing checked the object's backing. Proof of Reserve is that missing check: an external attestation of reserves a redeem path reads to refuse units the reserve cannot cover. It does not fix the mint bug; it stops the drain from being honored. A mint-invariant (conservation) test plus a PoR read (backing) covers both halves the incident exposed.

The rule: use the rail, don't rebuild it — and know the one place it doesn't reach. Every feed is also a dependency with a failure mode, so each cooperation above carries its "if the feed is wrong" line in code (staleness check / fallback), not just in this table.

History

The original Rabbit feature-design index (this file's pre-Jayverse content) now lives in README-history.md — this file used to hold it; it was split out 2026-09-09. The Jayverse hub was merged in from the former README-Jayverse.md, which has since been removed — its links now point here.

Naming (jay asked, 2026-09-07). Chosen README-Jayverse.md over Jayverse-README.md, for one reason: keeping the README prefix makes it sort right next to README.md in every file listing, so the two "start here" docs sit together. Per-service design docs are named jayverse-<service>.md so they group under one prefix and are obvious as a set.