Verafy specification

Version 0.0.2-alpha, November 6, 2026. Covers Verafy Harness (this repo) and Verafy Chain (Verafyai/verafyChain).

Scored 66% overall at v0.0.2-alpha (see SCORECARD.md).

This is an alpha spec for a prototype. Nothing here describes a running network, and there is no token. Every number is labeled measured (our own runs, with a date), vendor-reported (by whoever built the tool), modeled (computed from those, in packages/economics) or illustrative (an assumption to replace).

How to read this spec

• Requirement IDs are stable. AREA-NNN never changes meaning; a dropped requirement keeps its ID, marked removed in the changelog.
• Status is one of verified, built, partial, designed, planned or research (defined in requirements.json). The tables below are generated from that file by npm run score -- --write, so the status here always matches what the scoring pass checks.
• The scoring pass (npm run score) checks each claim against the code: a file, a function, or a test in npm test. A claim whose check fails scores zero. See SCORECARD.md.
• Versioning. Semantic versions with a pre-release tag. Alpha means the shape can still change. A change of status, a new requirement or a reworded one bumps the patch number; a change of architecture bumps the minor number. Every version is a git tag and a GitHub release, with notes in CHANGELOG.md.

The system in one picture

 contract in words ──▶ ethics gate ──▶ atomizer ──▶ router ───────────────┬──▶ settled (screen or panel)
 (verafy.asc/1)        (planned)        PACK         ROUTE                 │
                                                       │ L2 only           │
                                                       ▼                   │
                                       packer ──▶ prover, proven once ──▶ verifiers (sampled)
                                       PACK       PROVE                    │
                                                                           ▼
                        jury rules: commit, reveal, agreement against the bar (CORE, JURY)
                                                                           │
                                     TinySVM settles the exit exactly (SETTLE)
                                                                           │
                    record: Verafy Chain block (CHAIN) or Solana accounts per the SIMDs (SOL)
                                                                           │
                 banker pays and gets paid in existing tokens; light client watches escrow (BANK, LIGHT)

Principles that bind every part

From PRINCIPLES.md: payment agnostic (no token, ever); natural language first; embedded ethics; checkable and verifiable; agent friendly; context is evidence; no single model or lab; nothing is erased; legible to people; open and forkable; honest about what runs. A design that conflicts with a principle loses, or goes through the amendment process.

CORE: the protocol

A contract is a compressed intention: instructions, pinned context, a question with a closed answer type, a bar, payment and declared exits. Jurors commit to a hashed vote, then reveal it; agreement is measured against the bar; a below-bar ruling never pays jurors; the exit's diff must conserve totals.

JURY: juries, live runs, audits and challenges

Juries span labs and are drawn from the parent block hash. Auditors from other labs re-check sealed rulings; challenges append, never erase; a below-bar ruling's escrow funds a wider jury.

CHAIN: the Verafy Chain node

A block exists only when a jury rules. The node keeps a mempool of funded contracts, coordinates juries, gossips commitments and reveals, rotates sealers and verifies every block. Batching closes an L2 block by value or by time; the encrypted queue keeps contracts sealed until the jury is drawn.

SETTLE: TinySVM

The AI judges and TinySVM settles: a restricted LiteSVM sidecar that runs only pinned programs (escrow, bond, ledger and exit programs) under a compute cap. It runs side by side with runtime.js, and any disagreement is a fault. TinySVM decides nothing.

LIGHT: reading source chains

Escrow stays on its own chain. The harness reads it from several independent RPC providers and treats disagreement as unknown, never a guess. Intake checks funding before a jury is drawn; the outbox confirms a trigger landed.

BANK: the routing agent

Four blocks: the keyblock (keys encrypted, scoped keys out), the banker (accept any allowed token, convert at the best checked quote), the API router (pay AI APIs, provers and hosts, metered) and the payment wallet (caps, allowlist, never the bond). The Banker is a deterministic service, not an AI agent; a read-only advisor may report and flag but holds no keys. Full design in banker.md.

PACK: proof packing and the prompt compressor

FlashProve proves at most 1,024 tokens, about 750 words, per request; each proof takes about 9 s of H100 time, produces 18.78 MB and takes 17 s to verify (vendor-reported). Proving one request per proof wastes the window and pays for every proof in full. So requests are compiled before any model sees them:

1. Atomize. Each contract becomes atoms: one question each, a closed answer type, only the deciding facts, every fact pinned. An exact composition rule, written as code with integer math, turns atom answers into the contract's outcome. UNKNOWN goes to the contract's declared fallback, never a guess.
2. Dedupe. The same question over the same evidence has the same hash, so contracts that share a question share one slot and one proof.
3. Pack. Atoms fill 1,024-token requests first-fit, about 16 to 18 per request in tests; slot order is shuffled by the block hash; a reply that misses or mangles any slot is rejected whole.
4. Compress what can't be atomized. A brief (the question, the exits and only the deciding facts, each cited) stands in for a long contract. Plain dense English, never invented shorthand: models read English tokens best.
5. Check fidelity. A proof covers the atoms, not whether they capture the contract. Every plan or brief is agreed by the parties or ruled FAITHFUL by an unproven panel from several labs before it is used.

In a test block, 60 contracts became 120 atoms, 61 after dedupe, in 4 requests at 85% fill (measured on the packer with mock models).

ROUTE: multi-model routing

Every question starts at the cheapest tier that can answer it safely: a fast System 1 screen (such as Jev), then panels of small, mid-size and frontier models, each spanning labs. A unanimous panel stops; a split one moves up. Three signals decide where a question goes: the screen's probability, juror disagreement, and the question itself (its stakes, type and the contract's floor). The router is plain code; no model decides routing.

Guardrails:

• Shadow mode by default. The screen sizes juries and logs what it would have settled. It settles nothing until its cutoffs are calibrated and an operator turns settling on.
• Calibrated cutoffs. Per question type, the lowest probability at which the screen's accuracy, as a Wilson lower bound on labeled examples, matches the jury it replaces. Too few examples means no cutoff. Live audits withdraw a cutoff whose accuracy drops.
• The contract's floor is never lowered. The screen can only add scrutiny. L2 questions never take a screen's answer, because a closed model cannot carry a proof.
• Audits. A share of settled answers, drawn from the block hash, is re-checked at the top tier.

What a screen is worth is not known yet. Jev's figures are its maker's (70 to 500 ms, about $0.0004 a decision, 67.8% on its benchmark against 73 to 74% for frontier models); its coverage on our questions needs a calibration run.

PROVE: proofs of inference

The proven lane is set by the contract, never by difficulty. While only one model is provable, each packed request is proven once by a prover drawn from the block hash, and other jurors verify; lab diversity returns when a second model is provable. Proofs are attached after the reveal; an L2 ruling is final only when every counted proof verifies; a missing or failed proof drops the vote and records a fault. Proofs and their data stay off chain; a block carries one Merkle root over them.

COT: disclosed reasoning

Each vote carries reasoning, and the commitment covers it, so reasoning cannot be rewritten after the outcome is known. Rulings record each juror's reasoning hash. Next: step-wise reasons that cite a pin per step, so a challenge can point at the step where the logic broke. In the proven lane, reasoning uses the 1,024-token window (full reasoning roughly doubles cost per contract, modeled), so proven jurors give short reasons. Written reasoning is evidence to check, not a guarantee of what drove the answer.

GOV: constitution, ethics and amendments

Block 0 is a draft Constitution with Embedded Ethics, to be ratified by the first jury consensus. Every governance change passes a constitution check, then an ethics check. Amendments go through seven stages and can never weaken entrenched clauses.

SOL: settling on Solana

In theory, no separate chain is needed: the three draft SIMDs describe every part of this as ordinary Solana programs, with no changes to Solana. Two pieces would still need adding: fair juror draws (slot data can be nudged) and availability for the off-chain data. Proof packing needs a small amendment so many attestations can point at one shared proof. A dedicated Verafy Chain is worth building only if the Solana version hits real limits.

ECON: economics

All of it lives in packages/economics, with tests that pin every vector, and renders at harness.verafy.ai/economics. Headline results (modeled, defaults: an H100 at $4.00 an hour, FlashProve's vendor-reported speed):

Once packed, the fidelity checks cost more than the proofs (at 1,000 contracts: $3.26 against $1.29), so the next savings are in cheaper checks. A cascade from a screen to frontier models comes out about 4 times cheaper and 3 times faster on average than sending everything to a frontier jury (illustrative tier shares), but a hard question pays every tier.

AGENT: plugins

Your agent is a client, never a juror: the MCP server has no vote, key or funds tool, contract text comes back as evidence, and live calls need a flag and a spend cap.

DEPLOY: deploy and run anywhere

A harness is one long-running process: verafy harness serve. It registers with nodes, watches their mempools, and serves commit, reveal and proof. It refuses a commit on any contract no watched node holds, so nobody can spend its model budget from outside. Open commitments are written to disk before they leave, so a restart can still reveal.

verafy up gets that process running wherever the operator wants it: on this machine with Node or Docker, on a DigitalOcean or Hetzner server it creates, or on any cloud from a first-boot script. The model key goes to a mode-600 file or the server's user data; a cloud token is used once and never stored. Hardware profiles pick an open-weights model the machine can hold (modeled memory). verafy testnet up runs a whole testnet on one machine, scripted by default so it costs nothing, and can settle every ruling on a local Solana validator.

Releases ship as a source tarball, single-file binaries, a container image and an install script, all from one workflow on a version tag.

SITE: sites and docs

OPS: security and operations

EXT: collaborations and data

Muse (semantic version control) proposed two small experiments: targeted certification from semantic diffs, and poisoned evidence with signed provenance. Both fit the harness as pinned manifests, with no dependency in core.

Decisions waiting on Rex

Requirements marked needs Rex in the tables, plus: the block-close defaults, prove-once for L2, packing defaults, allowed brief modes, the Banker's target token, treasury, chains, caps and screening, whether to rent a FlashProve machine, and whether to publish the MCP server. From v0.0.2-alpha: whether Verafy runs hosted harnesses (DEPLOY-010), devnet SOL for the Solana program (SOL-002), Jev access for the calibration run (ROUTE-007), turning on Banker execution with a funded scoped wallet, and the illustrative defaults: block close (10% warm-up, 1-hour maximum wait), the 600-second proof deadline, the ethics panel sizes, bar and screening fee, and the amendment escrow shares.

Scorecard

Generated by npm run score -- --write from requirements.json. Do not edit by hand.

Overall: 66% of the spec, weighted. 119 requirements: 8 verified, 68 built, 18 planned, 13 partial, 8 designed, 4 research.

A requirement scores its status (verified 100%, built 80%, partial 50%, designed 25%, planned 10%, research 0%) only if every check passes. A score is how far the build is along the spec, not a measure of quality.

verafyChain checks were skipped: no checkout found. Those claims are flagged unverified.

Gaps, by impact

Impact is weight times the points still missing. Needs Rex marks a decision only Rex can make.