Draft: 1.0-draft.1 (2026-10-14). Not yet published as a standard; it may still change.Download the test cases (JSON)

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:

  1. its inputs were fixed before the outcome could be known;
  2. its outcome depends on randomness that nobody (not the platform, not the entrants, not Veritrus) could know or choose in advance;
  3. its outcome can be recomputed by anyone, and was;
  4. 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 bytes x.
  • 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, NaN and 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, always Z), 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": {} }
  • entries MUST contain 1 to 10,000 entries. Each entry has exactly the fields row (an integer ≥ 1) and holder (a random id). Rows MUST be unique. A holder MAY appear in several entries (one ticket per row). Entries are sorted by row, ascending, in canonical form.
  • params is 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:

  1. checks and canonicalizes the inputs (section 3) and computes inputsHash;
  2. 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;
  3. records committedAt (now) and runAt = committedAt + runInSeconds × 1000 ms, where runInSeconds is an integer from 0 to 3600 chosen by the platform;
  4. fixes the beacon round round = roundAtOrAfter(max(runAt, committedAt + 1)): the first round published at or after runAt and strictly after committedAt. That round cannot exist when the commitment is made, even when runInSeconds is 0;
  5. 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, satisfies x < limit; the index is x 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);
  • prevHash is the previous entry’s entryHash; for seq = 1 it is 32 zero bytes;
  • entryHash = hex(H(prevHash bytes ‖ recordHash bytes));
  • seq starts 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

  1. Signed by Veritrus: kind is commit, v is 1, and the signature verifies under a trusted key whose key id matches (section 6).
  2. Well-formed: the execution id, commitment (32 bytes) and client seed (null, or 1–64 bytes) are well-formed.
  3. Inputs match their fingerprint: the inputs pass section 3 and recompute to inputsHash.
  4. Run time within limits: 0 ≤ runAt − committedAt ≤ 3600 seconds.
  5. Beacon round is the first after the commit and runAt: beacon.chain is the quicknet chain hash and beacon.round = roundAtOrAfter(max(runAt, committedAt + 1)).
  6. In the public log (if an entry is given): its recordHash, kind and executionId match this signed record, and its entryHash recomputes.

Result (if present)

  1. Signed by Veritrus (as 1).
  2. Belongs to this commit: same executionId, and commitHash is the commit’s record hash.
  3. Revealed seed matches the commitment: hex(H(serverSeed)) = commitment.
  4. Uses the committed beacon round: same chain and round as the commit.
  5. Beacon round signed by drand: the round signature verifies (section 4).
  6. Beacon randomness matches its signature: randomness = hex(H(signature)).
  7. Completed after the beacon round: completedAt ≥ roundTime(round).
  8. The draw recomputes to the same winner: section 5.2 gives the same index and winner.
  9. In the public log (as 6).

Cancel (if present)

  1. Signed by Veritrus (as 1).
  2. Belongs to this commit (as 8).
  3. Made before runAt: committedAt ≤ cancelledAt < runAt.
  4. 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 current or retired) at https://apis.veritrus.com/v1/keys and 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.