PROTOCOL ARCHITECTURE
Components, data flow and trust boundaries
How a proposal moves through the system, which component is responsible for each step, and what happens when a step fails.
Components
| component | responsibility | implementation |
|---|---|---|
| web + API | Marketing site, documentation, versioned JSON API, SIWE sessions | Next.js on Vercel (Node.js runtime, Fluid Compute) |
| records database | Capabilities, suites, baselines, proposals, experiments, evaluation and lineage records, challenges, chain events | Postgres (Neon) via Drizzle; records stored as documents next to query columns |
| experiment runner | Executes candidate and baseline under fixed limits; validates and measures outside the solver process | Vercel Sandbox microVM, deny-all network, ephemeral |
| job queue | At-least-once delivery of experiment jobs with retries | Upstash QStash when configured; inline post-response execution otherwise |
| indexer | Reads registry events behind a confirmation depth and projects them onto records | Vercel Cron, every minute |
| reconciler | Requeues stale runs, commits pending evaluations, syncs statuses, purges expired nonces and keys | Vercel Cron, every ten minutes |
| registry contract | Commitments for proposals, evaluations and challenges; evaluator set; pause; two-step ownership | KuxerRegistry v0.1 on Robinhood Chain · 4663 |
Data flow
- A contributor signs in with their wallet (SIWE) and submits a proposal: capability, baseline, optional validated parents, title, summary, method and JavaScript source. The service hashes the source and the proposal document and stores both.
- An
INITIALexperiment is queued. The worker generates the public development set from the suite's published seed and the held-out set from a server-derived seed whose commitment is on the suite record. - Inside the sandbox the trusted harness feeds instances to the baseline and the candidate over a line protocol, times each round trip, validates tours and computes lengths. It writes one result document; the worker validates it against the schema and hashes it.
- The evaluation policy derives metrics and regressions and creates an
EvaluationRecordwith statusPENDING_REPLICATIONorREJECTED. Replication experiments are queued for pending records. - Each replication is compared instance by instance with the reference run. Agreement moves the record to
VALIDATEDand writes aLineageRecord; divergence rejects it with a nondeterminism regression. - The contributor may anchor the proposal on-chain from their wallet. Once anchored, the operator's evaluator signer commits the evaluation record hash and status; later status changes are pushed and the indexer confirms them from events.
Trust boundaries
- Contributor wallet: proves identity by signature; never shares keys. Anchoring is a transaction the contributor signs; the server only verifies the receipt.
- Registry service: trusted to store records faithfully. Every record exposes its canonical hash so stored content can be checked against on-chain commitments.
- Sandbox: the only place untrusted code runs. No network egress, no secrets, fresh VM per experiment, discarded afterwards. Scoring happens in the harness process, not the solver process.
- Evaluator signer: a keyed operator account that attests evaluation hashes on-chain. Its power is bounded by the contract: it cannot alter proposals, and its membership changes are delayed and logged.
- Contract owner: resolves challenges, queues evaluator changes, can pause writes. No authority over record content or scientific truth.
On-chain and off-chain responsibilities
| data | where | why |
|---|---|---|
| record ids and content hashes | on-chain | integrity and ordering, verifiable by anyone |
| evaluation status codes | on-chain | public, append-only history of validation and challenges |
| contributor and evaluator addresses | on-chain | attribution and accountability |
| source code, instances, logs, results | off-chain | size, flexibility, and the ability to keep sensitive material private |
| research documents | off-chain | versioned text; hashes can be committed when needed |
| secrets, datasets, weights, prompts | never on-chain | irreversible publication and leakage risk |
Failure modes
| failure | behaviour |
|---|---|
| sandbox unavailable or harness crash | experiment marked FAILED with the error; the reconciler requeues up to three attempts; the proposal stays EVALUATING |
| candidate times out or returns invalid tours | recorded per instance; the evaluation is REJECTED with timeout or invalid-solutions regressions |
| replication diverges | evaluation REJECTED with a nondeterminism regression; the reference run stays visible |
| RPC unavailable | indexer records the error and retries next minute; the status panel shows the indexer as unavailable |
| proposal not anchored | evaluation stays off-chain with chain: null; committed automatically after the contributor anchors |
| database unavailable | API returns 503 service_unavailable; pages show an unavailable state instead of simulated data |
| contract paused | writes revert with EnforcedPause; challenge resolution still works; the service keeps records off-chain and retries later |
See the architecture overview for the layer model and the contracts page for the registry interface.