Veritrus Proof Format, version 1
Status: DRAFT, not yet published. Version 1.0-draft.1, 2026-10-14. This document may still change. Once version 1 is published, it will not change: corrections will appear as dated errata, and any change to the format will be a new version. Proofs made under version 1 will always be checkable against this document.
The key words MUST, MUST NOT, SHOULD and MAY are to be read as in RFC 2119.
1. Purpose and scope
A Veritrus proof shows that an execution (in version 1, a draw of one winning entry) was carried out exactly as declared:
- its inputs were fixed before the outcome could be known;
- its outcome depends on randomness that nobody (not the platform, not the entrants, not Veritrus) could know or choose in advance;
- its outcome can be recomputed by anyone, and was;
- its records were signed by Veritrus and placed in an append-only public log.
This document defines the data formats, the computation, and the procedure a checker follows to verify a proof without trusting Veritrus. Section 9 states what a valid proof does and doesn’t establish. A conforming checker MUST reproduce the test cases in section 11 exactly.
Version 1 defines one execution type, draw.one. Section 10 describes how further types are added.
2. Conventions
- Hash: SHA-256 (FIPS 180-4).
H(x)is the 32-byte SHA-256 digest of the bytesx. - Binary values are written as lowercase hexadecimal, two characters per byte. Checkers MUST reject uppercase hex.
- Integers in JSON are whole numbers within ±(2^53 − 1). Fractions, exponents,
NaNand infinities MUST NOT appear. - u32be(n) and u64be(n) are an unsigned integer as 4 or 8 bytes, big-endian.
- field(x) is
u32be(length of x) ‖ x: a byte string prefixed with its length, so concatenated fields can’t be confused.‖is concatenation. - UTF-8(s) is the UTF-8 encoding of the string
s. - Times are UTC timestamps in the exact form
YYYY-MM-DDTHH:MM:SS.sssZ(always three fractional digits, alwaysZ), e.g.2026-10-13T23:44:06.276Z. A time MUST re-serialize to the same string. “ms” below means milliseconds since 1970-01-01T00:00:00.000Z.
2.1 Canonical JSON
Everything that is hashed or signed is first serialized as canonical JSON: RFC 8785 (JSON
Canonicalization Scheme), restricted by the integer rule above, so every number is written as a plain
decimal integer (-0 as 0). Object keys are sorted by their UTF-16 code units; there is no
whitespace; strings use the JSON escaping of RFC 8785. Fields whose value is absent MUST NOT appear;
null is a value and is written. JCS(v) is the UTF-8 bytes of the canonical JSON of v.
2.2 Identifiers
- A random id is 16 random bytes in lowercase base32 (RFC 4648 alphabet
a-z2-7, no padding): 26 characters matching^[a-z2-7]{26}$. - A holder (an entrant) is identified by a random id chosen by the platform: a pseudonym, never a name. The platform alone can map it to a person.
- An execution id is
ex_followed by a random id:^ex_[a-z2-7]{26}$. Veritrus chooses it. - A reference (
groupRef,clientRef,clientId) matches^[A-Za-z0-9._:-]{1,64}$. References are opaque to Veritrus (e.g. a platform’s group and play UUIDs).
3. Inputs (draw.one)
The inputs are a JSON object:
{ "type": "draw.one", "groupRef": "<reference>", "entries": [ { "row": 1, "holder": "<random id>" } ], "params": {} }
entriesMUST contain 1 to 10,000 entries. Each entry has exactly the fieldsrow(an integer ≥ 1) andholder(a random id). Rows MUST be unique. A holder MAY appear in several entries (one ticket per row). Entries are sorted byrow, ascending, in canonical form.paramsis an empty object in version 1.- No other fields are allowed, at any level. (This keeps personal data out by construction.)
The inputs fingerprint is
inputsHash = hex( H( JCS({ "v": 1, "type", "groupRef", "entries" (sorted), "params": {} }) ) )
4. Public randomness: the drand beacon
Version 1 uses the drand “quicknet” beacon of the League of Entropy:
| Parameter | Value |
|---|---|
| Chain hash | 52db9ba70e0cc0f6eaf7803dd07447a1f5477735fd3f661792ba94600c84e971 |
| Scheme | bls-unchained-g1-rfc9380 |
| Genesis time | 1692803367 (seconds since the epoch) |
| Period | 3 seconds |
| Group public key (BLS12-381 G2, 96 bytes) | 83cf0f2896adee7eb8b5f01fcad3912212c437e0073e911fb90022d3e760183c8c4b450b6a0a6c3ac6a5776a2d1064510d1fec758c921cc22b0e17e63aaf4bcb5ed66304de9cf809bd274ca73bab4af5a6e9c76a4bc09e76eae8991ef5ece45a |
Round times. Round r (r ≥ 1) is published at roundTime(r) = 1692803367000 + (r − 1) × 3000 ms.
roundAtOrAfter(t) is 1 if t ≤ 1692803367000, else ⌈(t − 1692803367000) / 3000⌉ + 1.
Round signature. A round’s signature is a 48-byte compressed BLS12-381 G1 point. It is valid if it
verifies against the group public key for the message H(u64be(r)), hashed to G1 per RFC 9380 with the
domain separation tag BLS_SIG_BLS12381G1_XMD:SHA-256_SSWU_RO_NUL_. The round’s randomness is
hex(H(signature)).
Checkers MUST verify the round signature themselves; they MUST NOT rely on a relay’s claim.
5. The execution
5.1 Commit
When the platform triggers the draw, Veritrus:
- checks and canonicalizes the inputs (section 3) and computes
inputsHash; - draws a 32-byte server seed from a cryptographically secure generator and computes the
commitment
hex(H(serverSeed)); the seed stays secret until the result; - records
committedAt(now) andrunAt = committedAt + runInSeconds × 1000ms, whererunInSecondsis an integer from 0 to 3600 chosen by the platform; - fixes the beacon round
round = roundAtOrAfter(max(runAt, committedAt + 1)): the first round published at or afterrunAtand strictly aftercommittedAt. That round cannot exist when the commitment is made, even whenrunInSecondsis 0; - signs the commit record (section 6) and appends it to the log (section 7).
The platform MAY supply a client seed: 1 to 64 bytes, fixed in the commit. If absent it is null.
5.2 Run
At or after roundTime(round), Veritrus obtains that round’s signature, verifies it, and computes the
winner:
message = field(UTF-8("veritrus/v1/draw")) ‖ field(inputsHash, 32 bytes) ‖ field(randomness, 32 bytes)
‖ field(clientSeed bytes, or the empty string if null) ‖ field(UTF-8(executionId))
block_i = HMAC-SHA256(key = serverSeed, data = message ‖ u32be(i)), i = 0, 1, 2, …
The blocks, in order, form a stream of big-endian 32-bit words (eight per block). For n entries:
- if
n = 1, the index is 0 (no words are read); - otherwise, let
limit = 2^32 − (2^32 mod n); read words until one,x, satisfiesx < limit; the index isx mod n. (Rejection sampling: every entry has exactly the same chance.)
The winner is the entry at that index in the sorted entries. Veritrus then reveals the server seed in a signed result record and appends it to the log. If the beacon round is not yet available, Veritrus waits; it MUST NOT substitute another source of randomness.
5.3 Cancel
Before runAt (and only then), the platform MAY cancel. Veritrus then signs a cancel record and
appends it to the log; the execution is never drawn. At or after runAt, cancellation MUST be refused
and the only way forward is to run. (After runAt, the outcome may already be computable by someone
holding the server seed, so a later cancel could be used to discard an unwanted result.)
6. Records and signatures
Every record has "v": 1 and a kind.
Commit record:
| Field | Value |
|---|---|
v, kind |
1, "commit" |
executionId |
the execution id |
clientId |
the platform’s reference at Veritrus |
clientRef |
the platform’s reference for the execution, or null |
type |
"draw.one" |
inputs |
{ "groupRef", "entries" (sorted), "params": {} } |
inputsHash |
section 3 |
commitment |
hex(H(serverSeed)) |
clientSeed |
hex, or null |
committedAt, runAt |
times |
beacon |
{ "chain": <chain hash>, "round": <round> } |
Result record:
| Field | Value |
|---|---|
v, kind |
1, "result" |
executionId |
as committed |
commitHash |
the record hash (section 7) of the signed commit |
beacon |
{ "chain", "round", "signature", "randomness" } |
serverSeed |
the revealed seed, hex |
result |
{ "index": <index>, "winner": { "row", "holder" } } |
completedAt |
time |
Cancel record: v, kind: "cancel", executionId, commitHash, cancelledAt (a time) and
reason (a string of at most 200 characters, or null).
Signing. A record is signed with Ed25519 (RFC 8032) over
UTF-8("veritrus/v1/record\n") ‖ JCS(record)
and published as a signed record { "record": <record>, "signature": { "alg": "ed25519", "keyId": <key id>, "value": <64-byte signature, hex> } }. The key id is "ed25519:" followed by
the first 16 hex characters of hex(H(public key)), where the public key is the 32-byte Ed25519 key.
7. The public log
Every signed record (commit, result, cancel) is appended to an append-only log. Each entry is
{ "seq": 1, "kind": "commit", "executionId": "ex_…", "recordHash": "…", "prevHash": "…", "entryHash": "…" }
recordHash = hex(H(JCS(signed record)))(the record and its signature);prevHashis the previous entry’sentryHash; forseq = 1it is 32 zero bytes;entryHash = hex(H(prevHash bytes ‖ recordHash bytes));seqstarts at 1 and increases by 1.
Changing any past entry changes every later entryHash, so a checker that knows a recent entry (the
head) can detect any rewrite of history before it.
Inclusion. An entry is in the log if, in the chain of entries from seq = 1 to a head the checker
trusts, it appears unchanged at its seq and the chain links (each prevHash equals the previous
entryHash; each entryHash recomputes). This section will change before publication: a tree-based
log with short inclusion proofs, and heads witnessed by third parties and anchored on public
blockchains, will replace “read the whole chain”.
8. Verification procedure
Given a signed commit, optionally a signed result or cancel, optionally their log entries, and a set of Veritrus public keys the checker trusts, a checker MUST perform every applicable check below. The proof is valid only if every check passes; if any fails, the result MUST NOT be presented as verified. Checkers SHOULD report each check by name.
Commit
- Signed by Veritrus:
kindiscommit,vis 1, and the signature verifies under a trusted key whose key id matches (section 6). - Well-formed: the execution id, commitment (32 bytes) and client seed (null, or 1–64 bytes) are well-formed.
- Inputs match their fingerprint: the inputs pass section 3 and recompute to
inputsHash. - Run time within limits:
0 ≤ runAt − committedAt ≤ 3600seconds. - Beacon round is the first after the commit and
runAt:beacon.chainis the quicknet chain hash andbeacon.round = roundAtOrAfter(max(runAt, committedAt + 1)). - In the public log (if an entry is given): its
recordHash,kindandexecutionIdmatch this signed record, and itsentryHashrecomputes.
Result (if present)
- Signed by Veritrus (as 1).
- Belongs to this commit: same
executionId, andcommitHashis the commit’s record hash. - Revealed seed matches the commitment:
hex(H(serverSeed)) = commitment. - Uses the committed beacon round: same chain and round as the commit.
- Beacon round signed by drand: the round signature verifies (section 4).
- Beacon randomness matches its signature:
randomness = hex(H(signature)). - Completed after the beacon round:
completedAt ≥ roundTime(round). - The draw recomputes to the same winner: section 5.2 gives the same index and winner.
- In the public log (as 6).
Cancel (if present)
- Signed by Veritrus (as 1).
- Belongs to this commit (as 8).
- Made before
runAt:committedAt ≤ cancelledAt < runAt. - In the public log (as 6).
Log inclusion (RECOMMENDED): the entries are in the published log up to a head the checker trusts (section 7).
A commit with neither a result nor a cancel is pending: checks 1–6 still apply.
9. Security considerations
What a valid proof establishes. The inputs were fixed when the commit was signed; the winner was computed exactly as above from those inputs, a seed committed before the beacon round existed, and that round’s public randomness; and the records have not changed since they were logged.
What it does not establish. That the inputs were fair or complete (who could enter, and whether every entry was included, is the platform’s responsibility); that an operator is honest in other respects; or that an activity is lawful where the reader is.
Trust assumptions. Predicting or steering an outcome would require both the server seed (secret until the result) and the beacon value (unknowable before its round). Veritrus cannot know the beacon value early; drand’s members cannot know the seed. The beacon is assumed to be produced by fewer than its threshold of colluding members; even if that failed, they would still lack the server seed. The Ed25519 keys must be kept secret by Veritrus; a stolen key could sign false records, which is why checkers should pin keys and why the log is chained and (in future) witnessed and anchored.
Timing. Because the round is the first strictly after the commit, nobody can commit with a round
whose value is already known. Because cancellation ends at runAt, and the round is at or after
runAt, nobody can cancel once the outcome could be known.
Withholding. A party that could compute an outcome early might try not to run an execution. Every commit is logged, so a commit with no result and no cancel is visible to everyone.
Privacy. Records contain pseudonymous holder ids and opaque references, never names or contact
details. Holder ids stable within a group let readers of the log see that an anonymous holder took
part or won there more than once, and groupRef shows which executions share a group.
Signature verification. Veritrus produces canonical RFC 8032 signatures. Checkers MAY accept signatures under the ZIP-215 verification rules (as the reference checker does).
10. Keys and versions
- Veritrus publishes its public keys (key id, public key, status
currentorretired) athttps://apis.veritrus.com/v1/keysand on veritrus.com. Checkers SHOULD pin keys obtained independently and treat any difference as an alarm. - Keys are rotated with overlap. Retired keys remain published forever, so old proofs keep verifying. A compromised key is retired immediately and announced; proofs signed with it after the announced time are not valid.
- New execution types are added as new values of
type, each with its own section, inputs, computation and test cases, and its own domain tag in place of"veritrus/v1/draw". Existing types never change. - A change to anything in this document is a new version (
"v": 2), with its own domain tags.
11. Test cases
The file test-vectors/v1.json (published with this document) contains five worked cases (a small
board with a 60-second countdown, a full 200-row board, a single entry drawn with no countdown, a
case with a client seed, and a cancelled execution) with every input, the exact signed records and
the log entries they must produce. The cases use real drand quicknet rounds and a test signing
key derived from a public string (never trust proofs signed with it). A conforming implementation
MUST reproduce every case byte for byte, and its checker MUST accept every case.
Worked example (case panama-small-60s), step by step:
| Step | Value |
|---|---|
| Entries (sorted rows) | 1, 2, 4, 5, 7, 9 (n = 6) |
executionId |
ex_24xetqsofkvlmqboyr2ymc3fam |
committedAt / runAt |
2023-09-27T08:28:23.300Z / 2023-09-27T08:29:23.300Z (60 s) |
| Beacon round (5.1 step 4) | 1000000, published at 2023-09-27T08:29:24.000Z: the first round at or after runAt |
inputsHash |
50e945a49fa0bef7768118f340527a46b1af18bfbdd7ef4f5182546745dc5b00 |
serverSeed / commitment |
f52fe4579cc1b2f4f849e1732cb20862a67c348ae73a8c76e02fb52e4e8b77b2 / efb93f0801ac403f29e7f73e91019cec71fee1fe8fed61544dd27581551e916f |
| Round randomness | b22aad4794f7451896f7a371aa46106fd84d919f3f569acd5b2fddf1d1440af3 |
| Draw message (129 bytes) | 00000010 76657269747275732f76312f64726177 ‖ 00000020 50e945a4…dc5b00 ‖ 00000020 b22aad47…440af3 ‖ 00000000 (no client seed) ‖ 0000001d 65785f3234…66616d (the execution id) |
block_0 |
0477910f2f1e5d0fcdb21715b73a1e29556aeebbd57d137ada80fa9b4fb92e01 |
| First word | 0x0477910f = 74944783 |
limit for n = 6 |
2^32 − (2^32 mod 6) = 4294967292; 74944783 < limit, so it’s accepted |
| Index | 74944783 mod 6 = 1 |
| Winner | entries[1] = row 2, holder f6cha45crapxuq5ug7j5vsy3gq |
The full message in hex is
0000001076657269747275732f76312f647261770000002050e945a49fa0bef7768118f340527a46b1af18bfbdd7ef4f5182546745dc5b0000000020b22aad4794f7451896f7a371aa46106fd84d919f3f569acd5b2fddf1d1440af3000000000000001d65785f323478657471736f666b766c6d71626f797232796d633366616d.
Reference implementation: @veritrus/core (the checker is @veritrus/core/verify). This draft is
derived from it and from its test cases; where they disagree, that is a bug to be fixed before
publication.