Specification

Overview

VRE commits the rules of an outcome on Solana before the result exists. Anyone can later recompute the result from the transaction signature, using only public RPC data, and compare it with what the program recorded.

What a MATCH proves

• The rules did not change. Participants, weights or scores, formula and winner count are the exact bytes stored on-chain under the committed artifact hash, and that artifact was bound to the runtime before resolution.
• The winners follow from the rules. Replaying the committed bytes with the randomness the program recorded yields the same winners, in the same order.
• The records agree. Input, output, winner count, winner ids and effect digests match across the event, the resolution account and the replay.

What it does not prove

• That the list was fair. VRE proves the list did not change after commit, not that it was complete or honest when committed.
• That the operator could not foresee the result on every path. This depends on the randomness source; see §02.
• That a prize was paid. Attestation paths prove the winners. Paying them is the integrator's step.

Network

A plain Markdown copy of this page for agents and tools lives at /spec.md, indexed from /llms.txt.

Resolution Model

Every path has the same shape: commit the rules, bind a runtime to them, resolve, replay.

1. Commit. submit_compiled_artifact, init_compiled_artifact_chunk, write_compiled_artifact_chunk and finalize_compiled_artifact store the artifact bytes in chunk accounts keyed by their SHA-256. review_compiled_artifact, signed by the ProgramConfig admin, approves the artifact for binding.
2. Bind. initialize_outcome_config creates a runtime, identified by runtime_id, bound to one artifact hash.
3. Resolve. One of the paths in §06 writes an OutcomeResolution account and emits a resolution event.
4. Replay. Any verifier rebuilds the artifact from its chunks, recomputes randomness and winners, and compares them with the records (§04).

Randomness sources

The resolved slots and slot hashes are written into the resolution account and the event, so replay never needs historical SlotHashes.

Which path the public endpoints use today

Artifact Formats

Rules are serialized into a binary artifact that starts with the magic "W3O1" and a u16 format version. All integers are little-endian. An artifact is at most 8,192 bytes. Participant ids are printable ASCII, zero-padded to 64 bytes, and strictly ascending by bytes.

Artifacts resolved through rng_v2 must be payout-free: the header payout and every effect amount are zero. The program then records who won, and the integrator pays.

Selection rules

• weighted_random. Round r takes a u64 from the first 8 bytes of the randomness when r = 0, and from SHA-256 of a domain tag, the randomness and r otherwise. It selects the entry whose cumulative weight covers u64 mod total_weight among entries not yet chosen.
• rank_desc. Score descending, ties by order ascending.
• rank_asc. Score ascending, ties by order ascending.
• first_n. order ascending.
• closest_to. |score − target| ascending, computed in 128 bits, ties by order ascending.
• Compact winner digest. On rng_v2 the program binds the full winner list as winner_claim_hash = SHA256("VRE_RNG_V2_WINNERS" ‖ count_u16le ‖ Σ(len_u8 ‖ id_bytes)).

W3O1 v1–v3 layout (fmt 1, 2, 3)

Compact V1.1 layout (fmt 5)

Scale layout (fmt 6, 7)

Composite, conditions and slot layouts are encoded and replayed by the SDK modules listed in §08.

Verification

Given a transaction signature and a program ID, the verifier:

1. Fetches the transaction logs and finds the resolution event emitted by that program. Conditions and slot events go to their dedicated replays.
2. Loads the runtime's OutcomeConfig, the OutcomeResolution, the ApprovedOutcomeArtifact header and, for rng_v2, the RngV2State.
3. Checks the artifact hash is the same in the event, config, resolution and header, and that the artifact is finalized with a status that allows binding.
4. Rebuilds the artifact from its chunk accounts and re-hashes it.
5. Recomputes the randomness: from master_seed for rng_v1, from the recorded slots and slot hashes for rng_v2, checking any operator reveal against its commitment.
6. Replays winner selection. Compact artifacts replay the on-chain table; scale artifacts fetch the snapshot from the committed URI or a hash-addressed mirror (see Snapshot sources in §08) and check its hash, count and Merkle root.
7. Compares input, output, winner count, winner ids and their padding, winner digest and effect digest. All equal: MATCH / OK. Otherwise the first failing check is returned as the reason.

HTTP response

Request fields: signature (or sig) and an optional programId, which defaults to the canonical program. RPC and local-artifact overrides are disabled on the public host.

SDK result

verifyOutcome returns the same data with status and reason in place of verification_result and verification_reason. Fields appear only when they apply.

Reason codes

MATCH always carries OK. A MISMATCH carries one of these codes.

Canonical Program

One program on devnet carries every path. Integrators use it directly; a dedicated instance is possible under a partner agreement.

Key separation

The upgrade authority can replace the code and nothing else. The ProgramConfig admin signs operational calls, including review_compiled_artifact, and cannot upgrade the program, so a compromised operator host cannot swap the code. Both are single keys on devnet. Mainnet governance is decided separately and is not implied by the devnet setup.

ProgramConfig

Account addresses

Protocol fee

fee_lamports is 0 on devnet and can be changed by the admin without an upgrade. When set, it is charged by resolve_outcome* and settle_rng_v2 from the calling operator, snapshotted at prepare_rng_v2 and taken from the stake at attest_winners, and charged on paid sortition registration. Verification is always free.

Instructions

Compute and heap

rng_v2 prepare_rng_v2, settle_rng_v2 and attest_winners on a compact artifact parse the whole outcome table on-chain. Add ComputeBudgetProgram.requestHeapFrame up to 256 KiB and a compute limit of about 1.4M units. Measured on 103 entries: settle 174k–266k CU, attest 142k–231k CU. Other instructions keep the default 32 KiB heap.

Resolution Paths

Single-phase settle (v1.2) · default

prepare_rng_v2 fixes the rules, the stake and three future target slots, 8, 16 and 24 slots ahead. A Solana leader produces four slots in a row, so the first target is always at least two leader groups after the slot that included prepare, and the three targets fall in three different leader groups. Groups are not validators: one validator can lead several groups, and a skipped target moves to the next produced slot after the previous resolved one. A devnet draw on 2026-09-13 shows both: eight slots were skipped, targets ending 680, 688, 696 resolved to 688, 689, 696, and one validator produced all three. Measured over 5,000 recent slots on 2026-09-13: on mainnet one validator produced two of the three hashes in 3.1% of draws with these offsets, against 2.3% with 75/90/105, and never all three; on devnet, with 12 leaders and a 22.5% skip rate, one validator produced two or more in about 73% of draws and all three in about 10%, whatever the offsets. After the last target slot and before expiry, the same operator calls settle_rng_v2, which reads SlotHashes, derives the randomness, resolves the artifact and writes the resolution. The operator cannot predict the result. It can still choose not to settle; the prepared draw then remains visible on-chain and expires through expire_rng_v2, which refunds the stake. The public draw endpoints run this path in one request.

Two-phase seal and attest (v1.3.2)

1. prepare — the operator opens the draw with a stake and a bounty.
2. seal — seal_randomness is permissionless. Once the target slots land, anyone can seal, fixing the outcome and earning the bounty.
3. attest — attest_winners, by the operator or the configured attester, records the resolution, takes the fee and refunds the rest of the stake.
4. expire — a never-sealed draw expires and its bounty goes to the treasury; a sealed draw not attested by the deadline, 480 slots after expiry, can be closed by anyone with expire_sealed_rng_v2.

Use it when the operator has an interest in the result and must not be able to back out.

Compact artifacts on rng_v2

Since 2026-09-09 both rng_v2 lifecycles accept compact formats 1, 2, 3, 5 and 8, not only scale format 7. For compact artifacts the program selects the winners itself, so callers pass empty winner arguments; non-empty ones fail with RngV2CompactArgsMustBeEmpty. The resolution stores winner_claim_hash as the digest of the winner list, and the list is emitted in OutcomeResolvedV5. Scale artifacts keep caller-claimed winners proved by snapshot replay and emit OutcomeResolvedV4. Both must be payout-free. SDK 0.9.1 verifies these draws, and the public draw endpoints resolve through this path.

Sortition-by-Claim (v1.4.0)

Entrants register sha256(secret ‖ ticket_id ‖ draw_id) before a deadline. seal_sortition_draw fixes omega from three future slot hashes, 75, 90 and 105 slots after the draw was created; registration must close before the first of them. Each entrant claims by revealing the secret and wins when sha256(secret ‖ omega) < threshold.

• Cost. A claim uses about 8,200 CU, under the 10k budget.
• Coverage. 5 of 5 negative cases rejected.
• Distribution. 200 draws of 100 tickets with 10 expected winners: mean 9.7, variance 8.76, against a binomial mean of 10 and variance 9.

Winners claim for themselves, so the operator pays nothing per winner. Fits airdrops, allowlists and mass rewards.

Sortition economics (v1.4.1)

An optional fee layer, byte-compatible with 1.4.0 draws. fee_mode selects an entry_fee_lamports at registration and a close_skim_bps skim at close. close_split(rent, skim_bps) guarantees refund + skim == rent. Measured: paid register 18,096 CU, init economics 5,234 CU, close 9,643 CU, sweep of two tickets 18,459 CU; 9 of 9 negative cases rejected.

Conditions (fc7)

Scores committed prediction slips, each a set of legs with odds, against revealed match facts, and ranks entrants. The off-chain scorer at POST /api/conditions/score is byte-identical to on-chain resolve_conditions, which uses about 15,700 CU. The event ConditionsResolvedV1 carries winners_digest, facts_ref_root and winning_score_sum. VRE proves the ranking; payout stays with the partner.

Slot spins (SF1)

prepare_slot_spin binds the player, the bet and the committed game before the entropy exists. settle_slot_spin derives randomness from future slot hashes, replays the reels from the artifact, applies the max-win cap and pays the bound player from the vault. The public demo game runs on its own devnet program, 6R5n5uPTj1bg4xz6P3xCmVkyorTySbLQQZuENe8SSaKK; verify its spins with the SDK and that program ID.

Unicorn-G entropy (B8) · implemented, not deployed

An alternative entropy source: a VDF output verified on-chain with an embedded Groth16 verifier. It was measured on devnet in June 2026: seal with verification 247,476 CU, attest 61,466 CU, and a wrong proof rejected as InvalidUnicornGProof. Its instructions sit behind a build feature that the canonical program is not built with. Before mainnet it needs the circuit soundness fix and a trusted-setup ceremony.

HTTP API

Base URL https://verifiableoutcome.online. JSON in, JSON out. Draw endpoints sign with the server's operator key, so callers never hold one. A draw resolves through rng_v2 inside the request: the server commits the rules, waits for the future target slots, about 10 seconds, then settles and replays, so a draw call takes 12–45 seconds in total.

The canonical program binds only artifacts approved by the ProgramConfig admin, so a draw cannot be resolved there with your own wallet; the API runs it with the operator key. Sortition instructions need no admin and can be sent from any funded wallet (§08).

Limits and statuses

Statuses: 200 success; 400 validation error; 401 missing or unknown key; 403 key without the needed permission; 404 unknown conditions round, or an account that does not exist (AccountNotInitialized); 409 a scale-shaped body sent to a draw endpoint, a duplicate snapshot chunk, or a program state conflict (SortitionRegistrationOpen, SortitionRegistrationClosed, SortitionClaimWindowClosed, SortitionAlreadyClaimed, AccountAlreadyInUse for a reused id); 413 participant table too large for a compact artifact; 422 the program rejected the input (SortitionPredicateNotMet for a losing ticket, InvalidSortitionSecret, other InvalidSortition*); 429 rate limit, counted from the start of the previous draw; 500 server-side failure; 503 partner config absent on the host; 504 devnet timeout, retry.

When the program rejects an instruction the body carries error_code (the program error name), error_number and a readable error: { "ok": false, "error": "Sortition predicate not met", "error_code": "SortitionPredicateNotMet", "error_number": 6045 }.

Public, no key

Scoring conditions without a key

Leg encoding: op 1 adds, for totals, and 2 subtracts, for 1x2; comparison 0 greater, 1 less, 2 equal; line_x2 is the line times two, totals only. For full-match goals stat_key 1 is side one and 2 is side two.

Live raffle with a wallet

With requireWorldId, the caller sends a World ID 4.0 proof; the server verifies it and reserves its nullifier, so one human enters once. The public host runs World ID in staging, through the simulator. Wallet pages read only the address through the Wallet Standard and never ask to sign.

Partner API

Every partner endpoint takes x-api-key: vresk_<32 hex>. Keys are issued on request in Telegram and stored server-side only. Draws additionally require draw_enabled on the key.

Partner draw fields

• formula. weighted_random, rank_desc, rank_asc, first_n or closest_to.
• participants. At least 2 objects with a unique id of up to 64 printable ASCII bytes, plus weight or score as the formula needs. The compact artifact holds about 100 entries; use the snapshot flow above for more.
• winners_count. 1 to 10, not more than the participants.
• target. Required for closest_to; a signed safe integer.
• use_case. raffle, airdrop or competition; informational.
• Scale-shaped body. mode: "scale", scale: true, public_proof: true or standard_version: "1.2" on this endpoint returns 409 with route: "scale_snapshot" and the snapshot endpoints.
• artifact_slot. The slot where these exact rules were first committed; identical rules reuse one artifact, so it can predate the draw.

SDK

verifiable-outcome-sdk is the TypeScript library for building artifacts and verifying outcomes. It is an ES module for Node 18 and later.

Verify from a terminal

Verify a transaction

Build an artifact

Exports

The operator resolve client and the rng_v2 prepare-and-settle client are not in the published package: draws run through the HTTP API. verifyOutcome and vre verify do not replay sortition transactions; the claim instruction enforces the sortition predicate on-chain.

Snapshot sources

snapshot_uri is opaque to the program. It is part of the hashed artifact, so a draw commits to where the list was published, and the file itself is checked against snapshot_hash. The verifier tries, in order:

1. a local copy (--snapshot-file);
2. the committed URI: https:// as is, irys-devnet://<id> through devnet.irys.xyz and gateway.irys.xyz, irys:// through gateway.irys.xyz, ar:// through arweave.net and turbo-gateway.com;
3. mirrors by hash, <mirror>/sha256/<snapshot_hash>.jsonl: https://verifiableoutcome.online by default, override with --snapshot-mirror or VRE_SNAPSHOT_MIRRORS.

A source whose bytes do not hash to snapshot_hash is skipped. If no source serves the file, the result is ERR_SNAPSHOT_UNAVAILABLE. Moving to other storage needs no program upgrade: new draws commit a different URI, and older draws keep verifying through mirrors. Irys devnet drops uploads after about 60 days; the VRE mirror keeps every snapshot it published.

File format: one JSON object per line, {{"id","order","weight"}} for weighted_random, {{"id","order"}} for first_n, {{"id","order","score"}} otherwise, each ending in a newline, sorted by id bytes. Leaf = SHA-256(SHA-256(line)); node = SHA-256(left ‖ right), the last node is duplicated on odd levels; a proof is a list of {{ position, sibling }} from the leaf upward, where position is the side the sibling sits on. verifySnapshotMerkleProof checks a line and proof against the on-chain merkle_root.

Measured on devnet on 2026-09-15: 10,001 participants, finalized in 23 s, replayed to MATCH from the committed URI alone. On a local validator, 100,001 participants (8 MB) took 24 s.

Use Cases