# SUPERB consensus protocol

Solana is the canonical ledger of SUPERB protocol consensus. It records how a
published result was produced under named rules and evidence commitments. It does
not decide linguistic truth. LITERATE rewards may consume a finalized semantic
release, but token ownership grants no semantic authority.

## State and placement

| On Solana | Off chain, committed for replay |
| --- | --- |
| Rule ID, code/config hashes, schema and challenge window | Full rule implementation |
| Separate administrator and receipt-signer public keys | Receipt private key stays in the submission service; administrator signs chain transactions |
| Evaluator ID, code/config hashes and schema | Deterministic evaluator executable |
| Contrast ID and passage/rubric hashes | Raw passages and source records |
| Ordered submission root/count and eligible root/count | Pseudonymous judgment leaves, signed receipts and eligibility decisions |
| Evidence root, input-snapshot root and artifact-manifest hash | Evidence graph, snapshots, artifact bytes and retrieval locations |
| Count result, confidence in basis points and challenge/finalization state | Independent replay and artifact retrieval |
| Semantic release root, parent, member-set root and builder hash | Full semantic release and member proofs |
| Reward root, funded epoch and immutable claim receipts | Allocation preparation and private account records |

The current program source has account models for rules, evaluators, contrasts,
consensus revisions, availability attestations, typed challenges and semantic
release lineage. It has compiled and passed a fresh local-validator transaction
run. This is development code, not a deployed or audited mainnet protocol.
`publish_consensus_epoch` requires a finalized on-chain release and writes its
ID into the reward epoch. `solana/settle.mjs` uses that instruction. The older
`publish_epoch` instruction remains in the IDL for compatibility but rejects
every call.

## A consensus revision

1. Contributors answer a contrast. When receipt signing is configured, the
   judgment and its signed, context-bound sequence receipt enter the same
   database batch. Old judgments without receipts cannot be exported as a
   protocol proposal.
2. The initial policy includes every accepted signed submission. The ordered
   log root commits to all entries; a distinct eligible root and policy hash
   commit to the decision. An inclusion proof proves membership, not by itself
   completeness. A signed receipt plus a conflicting indexed inclusion proof, or
   a checkpoint count below the receipt sequence, can demonstrate omission.
3. A canonical manifest binds exact payload hash, byte length, counts, rule and
   evaluator IDs, and retrieval locations. Evidence and any decision-critical
   snapshots are separately committed.
4. The publisher proposes a consensus record. The program checks counts and the
   integer evaluator result. Its state moves to `challengeable`.
5. A distinct key can attest the manifest hash. Typed challenges can be filed
   within the rule's bounded slot window. The administrator currently decides
   whether challenge evidence is upheld. An upheld challenge invalidates the
   revision; new results use a new account and parent link.
6. After the deadline, with no open challenges and at least one attestation,
   the program may mark the revision protocol-finalized. Clients separately
   require Solana `finalized` RPC commitment before reporting an observed result.

The current attestation proves a signature on a hash, not durable availability.
The administrator and upgrade authority remain protocol trust assumptions. A
distinct attestor key alone does not establish independence. Independent storage,
retrieval tests, objective DA challenge handling, publisher consistency checkpoints
and recovery policy remain mainnet gates.

## Exact V1 serialization

Judgments use UTF-8 bytes of `SUPERB_JUDGMENT_V1`, a zero byte, then canonical
JSON with sorted keys and no extra whitespace. The schema, network, program ID,
contrast ID, judgment ID, pseudonymous contributor commitment, answer, rubric,
rule and nonce are required. Accepted-log leaves hash
`SUPERB_SUBMISSION_LEAF_V1 || u32LE(sequence) || judgmentHash`. Internal nodes
hash `SUPERB_SUBMISSION_NODE_V1 || left32 || right32`. Odd nodes advance unchanged.
The eligible and evidence trees have distinct domain strings. Empty roots hash
the node domain with `_EMPTY` appended. Counts and confidence use integers;
confidence is basis points (`0..10000`). No floating point decides consensus.

The initial count evaluator returns `INSUFFICIENT` when non-unsure answers are
below the rule minimum, `CONTESTED` on a tie, otherwise `SAME` or `DIFFERENT`.
Confidence is the winning answer count divided by answered count in basis points,
rounded down. A tie has 5000 bps; insufficient evidence has 0. More nuanced
rules require a new registered version and replay vectors, not silent edits.
The checked-in [V1 vectors](consensus-vectors.json) cover canonical judgment
bytes, tree roots and count outcomes; `scripts/verify-consensus-vectors.py`
recomputes them independently from the JavaScript implementation.

## Semantic releases and predictions

A release records its root, parent account, consensus-member root/count,
evidence root, artifact manifest and builder hash. The local verifier checks
every included member against a finalized consensus account and the exact
release artifact, including its parent ID. The operator publication command
requires this replay before sending a transaction. A release proposal currently names one finalized seed
consensus on chain; the complete member-set relationship is challengeable and
must be independently replayed.

`predictConsensus({contrastId})` reads a specific chain-grounded contrast.
A finalized protocol record at Solana `finalized` commitment is returned as
`kind: "observed"`; a challengeable record is `kind: "estimated"` with a
provisional distribution. `predictSense({text,target})` ranks accepted senses
for a concrete passage. JEV/LAYA are optional contextual inference adapters;
they never create protocol consensus. The older `predict()` method uses a
reward-epoch release anchor and remains a legacy corpus lookup.

## Reward settlement

LITERATE is an Original SPL Token with fixed one-billion supply and nine
decimals. The work treasury receives 80%; the protocol treasury 20%. Reward
leaves remain domain-separated from judgments and semantic releases. An epoch
reserves its full allocation against treasury funds, and one claim receipt per
wallet prevents duplicate claims. Wallet binding signs an expiring nonce and
authorizes no token transfer. Reward settlement cannot change a semantic
consensus record or rewrite finalized release history.

The local program, SDK and replay tests are a protocol foundation. Mainnet
requires broader local-validator adversarial tests, independent replay across languages,
artifact availability evidence, publisher monitoring, program review, custody
controls and economic/legal gates. No current local fixture proves those gates.