Architecture

Services, programs and boundaries

Four systems (indexing, entropy, derivation and rendering) connected only by commitments. Solana stores the commitments; off-chain workers do the heavy lifting; nothing touches $OOMI transfers.

Chain: Solana
Programs: Anchor (Rust)
Workers: TypeScript
Store: PostgreSQL

1System

Select a component for details. Status dots reflect reality: only the website and its data adapter exist today.

Built (local)SpecifiedDesignedEvaluatingNot started

2Services

Services
Service	Runtime	Responsibility
Indexer	TS worker (Railway/Fly)	Ingest $OOMI activity via Helius webhooks / LaserStream; dedupe; finality; backfill
Window builder	same worker, cron	Apply the rule version → capped per-identity signals → canonical snapshot → root
Round orchestrator	state machine	commit_snapshot → QRNG request + commit → wait for drand B → reveal → derive
Public API	read-only HTTP	/v1/state, /v1/rounds/:id, /v1/rounds/:id/snapshot.json (immutable, CDN-cached)
Render pipeline	queue worker	Art direction and composites from decided traits
Agent	worker + Claude API	Observe → draft → suggest, human review; no keys, no spending
Website	Next.js on Vercel	Reads everything through one typed data adapter

3Solana programs

Small Anchor programs that store commitments, never logic that could block a token transfer. Upgrade authority sits with a Squads multisig (≥ 3/5) behind a 48h timelock. Every privileged role is separate, and the commit key is low-balance and rotatable.

world-registry

specified

Singleton configuration for the flagship world: roles, rule versions, pause switch.

world-registry accounts
Account	Seeds	Fields	Size
World	["world", world_id]	version, admin, rule_authority, commit_authority, paused, current_rule_version[32], epoch_len_secs, bump	~180 B

world-registry instructions
Instruction	Signer	Guards
init_world	admin (multisig)	one-shot per world_id
publish_rule_version(hash, uri)	rule_authority	only between windows; emits hash of the rule table
set_roles	admin	48h timelock
pause / unpause	admin	blocks commits only; never touches $OOMI transfers

events: RuleVersionPublished · RolesChanged · Paused

entropy-registry

specified

Round commitments: snapshot root, QRNG commit/reveal, beacon round, final entropy.

entropy-registry accounts
Account	Seeds	Fields	Size
Round	["round", world, epoch_le]	epoch, snapshot_root[32], snapshot_uri_hash[32], committed_slot, qrng_commit[32], beacon_round, entropy?[32], status, bump	~240 B (≈0.0025 SOL rent)
Publisher	["publisher", world, provider_id]	provider_id, kind, active, added_at	~90 B

entropy-registry instructions
Instruction	Signer	Guards
commit_snapshot(epoch, root, uri_hash)	commit_authority	now ≥ window_end + buffer; one-shot per epoch
commit_qrng(epoch, qc)	commit_authority	snapshot committed in an earlier slot; one-shot
reveal(epoch, q, beacon_round, beacon_sig)	commit_authority	SHA-256(domain‖epoch‖q) = qc; beacon_round = rule(committed_slot)
fallback(epoch, beacon_round, beacon_sig)	anyone	after deadline D2 with no reveal

events: SnapshotCommitted · QrngCommitted · EntropyRevealed · EntropyFallback

evolution-registry

specified

Outcome commitments per round and opt-in holder identity records.

evolution-registry accounts
Account	Seeds	Fields	Size
Outcomes	["outcomes", world, epoch]	outcomes_root[32], derivation_version, count	~80 B
Identity	["identity", world, owner]	owner, linked_at, stage, last_epoch, profile_hash[32]	~120 B (refundable)

evolution-registry instructions
Instruction	Signer	Guards
commit_outcomes(epoch, root)	commit_authority	round status Revealed \| Fallback
link_identity	owner	opt-in; payer funds rent
unlink_identity	owner	closes PDA, refunds rent
update_profile_hash	commit_authority	requires a committed outcomes root

events: OutcomesCommitted · IdentityLinked · IdentityUnlinked

fee-treasury

designed

Optional: pay $OOMI for deterministic items (cosmetics, renders, credits) with published routing.

fee-treasury accounts
Account	Seeds	Fields	Size
Treasury	["treasury", world]	mint, vault (PDA-owned ATA), routes[≤4](dest, bps), burn_bps ≤ 3000, admin	~260 B

fee-treasury instructions
Instruction	Signer	Guards
pay_for(item_id, amount)	payer	TransferChecked into vault; item price table
sweep	anyone	distributes per routes; burns burn_bps
set_routes	admin	Σ bps = 10000; timelocked

events: Purchase · Swept · RoutesChanged

transfer-hook (optional)

evaluating

Only for a new Token-2022 mint, and only if a feature truly needs transfer-synchronous bookkeeping.

transfer-hook (optional) accounts
Account	Seeds	Fields	Size
ExtraAccountMetaList	["extra-account-metas", mint]	≤ 2 extra accounts	small

transfer-hook (optional) instructions
Instruction	Signer	Guards
Execute (transfer-hook interface)	(Token-2022 CPI)	deterministic, < 20k CU, no network calls, never fails a transfer for business reasons

Why the transfer hook is optional

A Token-2022 hook can only exist on a new mint, runs inside every transfer, and fails the transfer if it errors or if a router omits its extra accounts. Oomi only needs to observe activity, which an indexer does without touching settlement. The hook stays off unless a feature truly needs transfer-synchronous state and passes a venue-by-venue test.

4Indexing integrity

Indexing rules
Concern	Rule
Commitment level	UI may show confirmed; snapshots use finalized slots only, plus a buffer after closes_at
Duplicates	Webhooks are at-least-once: raw keyed by signature; movements by (signature, ix_path, token_account)
Forks / drops	Nightly reconciliation re-reads the window at finalized; dropped txs are marked and excluded
Attribution	Net per-owner delta from pre/post token balances, so multi-hop swaps collapse to one movement
Programs	Token `Tokenkeg…` and Token-2022 `TokenzQd…` layouts both parsed
Not an action	A transfer is not a signal. Pools and vaults are tagged as venues
Audit	Raw payloads kept ≥ 1 year; windows link to the exact rows they used

5Data model

postgres (sketch)

raw_tx(signature PK, slot, block_time, commitment, payload jsonb, source, received_at)
token_movement(signature, ix_path, slot, mint, program_id, owner, token_account,
               delta numeric(40,0), kind, venue, finalized,
               UNIQUE(signature, ix_path, token_account))
window(epoch PK, opens_at, closes_at, rule_version, status)
signal(epoch, identity_id, kind, value, capped_value, evidence jsonb, PK(epoch, identity_id, kind))
snapshot(epoch PK, canonical_json jsonb, root bytea, committed_tx, committed_slot)
round(round_id PK, epoch, provider, qrng_commit, beacon_round, beacon_sig,
      qrng_bytes, entropy, receipt_hash, status, requested_at, revealed_at)
outcome(round_id, identity, seed, traits jsonb, rule_version, PK(round_id, identity))
agent_draft(id PK, trigger, category, content, status, reviewer, model, cost_usd)
audit_log(id, actor, action, subject, detail jsonb, at)

6Agent

Oomi's planned AI personality observes the world and drafts content in its own voice. Humans approve anything that leaves the building.

Agent permission levels
Level	Can	Gate
L0 Observe	Read window aggregates, round records, approved lore, public mentions	Read-only tools
L1 Draft	Write posts, story beats and art directions into a review queue	Never publishes
L2 Suggest	Propose events, flag lore conflicts	Needs a human action
L3 Execute	Post an already-approved draft	Locked until security review and owner sign-off

No private key, seed phrase or spending authority is ever in the model's context.
External text (mentions, submissions) is quoted as data and never obeyed as instructions.
Every draft passes schema validation, a banned-claims check (no price talk), a lore check, and human review.

7Security model

Key threats
Threat	Mitigation
Operator biases an outcome	Seal before entropy; QRNG committed before beacon; fixed fallback
Provider biases bytes	Mixed with drand; receipts stored; provider can't know B
Withholding / re-roll	Deterministic fallback; anyone can trigger it after D2
Sybil or wash influence	Caps, √-scaling, time-weighting, clustering heuristics; no transfer counts
Commit key compromise	Scoped to commit instructions, low balance, rotatable via multisig
Malicious upgrade	Multisig + timelock; published diffs; eventual immutability
Token made untradable	Standard SPL, no hook, no tax
Agent prompt injection	Data/instruction separation, tool allowlists, human review, no publish tool
Fake contract addresses	One source of truth: the Token Address button on this site

8Environments & keys

Environments
Env	Chain	Secrets
local	none (test vectors)	none
dev	devnet	dev RPC + QRNG keys, devnet commit key
staging	mainnet (read-only)	read-only RPC key
prod	mainnet	host secret manager; commit key scoped and low-balance; upgrade keys on hardware wallets

Only TWITTER_LINK, TOKEN_ADDRESS and SITE_URL are public. Everything else stays server-side and out of logs.

9Extensibility

Oomi launches as one flagship character. Every table and program account is namespaced by world_id, so other communities could later opt in to their own evolving companion with the same guarantees: read-only observation, commit-before-entropy and reproducible derivation. That comes after the flagship ships and has been reviewed.