specification
Normative source · v0
This page is a human-readable summary. The authoritative copy lives in the spec repo. If the two ever drift, the repo wins.
1. poll objectLink to this section
{
"v": 0,
"kind": "oc-vote/poll",
"creator": "<btc address>",
"question": "<single-line UTF-8, <= 280 bytes>",
"options": [ { "id": "<matches [a-z0-9_\\-]{1,32}>", "label": "..." } ],
"deadline": "<iso8601 UTC>",
"snapshot_block": <positive integer | "deadline">,
"weight_mode": "one_per_address" | "sats" | "sats_days" | "<registry>",
"weight_params": <object | null>,
"min_sats": <non-negative integer>,
"min_days": <non-negative integer>,
"mode": "public" | "secret",
"reveal_pk": "<32-byte hex X25519 pubkey> | null",
"tiebreak": "latest" | "first",
"notes": "<optional UTF-8, <= 2048 bytes> | null",
"created_at": "<iso8601 UTC>",
"sig": { "alg": "bip322", "pubkey": "<creator>", "value": "<base64>" }
}
poll_id = SHA256(canonical bytes of poll with sig.value = "") expressed as
lowercase hex.
Publication (SPEC §3.4): an addressable Nostr event of kind 30080. The t
tags are the ones readers query: vote.ochk.io and the CLI find a poll by
{"kinds":[30080],"#t":["<poll_id>"]}, so a poll without them is never found.
kind = 30080
tags = [
["d", "oc-vote:poll:<poll_id>"],
["t", "<poll_id>"],
["t", "oc-vote-poll"],
["t", "<creator>"],
["poll_id", "<poll_id>"],
["creator", "<creator>"],
["deadline", "<deadline>"],
["snapshot", "<snapshot_block, or deadline>"],
["mode", "public" | "secret"]
]
content = canonical bytes of the poll, sig.value included
pubkey = any fresh Nostr key; the BIP-322 sig inside content is the proof
Integration → publish from code has a working example.
2. ballot objectLink to this section
{
"v": 0,
"kind": "oc-vote/ballot",
"poll_id": "<hex>",
"voter": "<btc address>",
"option": "<option id> | null",
"attestation_id": "<oc attestation id> | null",
"secret": null | {
"envelope": <oc-lock v2 envelope>,
"commit": "<sha256 hex of commit_msg>"
},
"created_at": "<iso8601 UTC>",
"sig": { "alg": "bip322", "pubkey": "<voter>", "value": "<base64>" }
}
ballot_id = SHA256(canonical bytes with sig.value = "").
Publication (SPEC §4.5): kind 30081. Each ballot event has its own Nostr key,
so relays keep a voter's earlier ballots; the tiebreak (§6 step 3 below) picks
one. Talliers find ballots by {"kinds":[30081],"#t":["<poll_id>"]}. They
verify each event under NIP-01, and each ballot's own signature, before
de-duplicating by ballot_id, since ballot_id leaves sig.value out (SPEC
§6.5, Discovering the ballots), and take them as complete only at the read floor
(§10 below). A poll is rejected only when no copy of it verifies, and a reveal
is taken from a copy that verifies (SPEC §10 item 1).
kind = 30081
tags = [
["d", "oc-vote:ballot:<poll_id>:<voter>"],
["t", "<poll_id>"],
["t", "oc-vote-ballot"],
["t", "<voter>"],
["poll_id", "<poll_id>"],
["voter", "<voter>"],
["ballot_id", "<ballot_id>"]
]
content = canonical bytes of the ballot, sig.value included
3. anchoring a ballot (SPEC §4.6)Link to this section
A poll whose deadline is on or after 2026-11-15T00:00:00Z is an anchored
poll: whether a ballot is in time is decided by the Bitcoin block that commits
to its ballot_id. A poll with an earlier deadline is clock-dated: it is
tallied by created_at, and its tally says so (§6 below). The poll's bytes are
the same either way.
The anchor is an OC Stamp v1 envelope (kind 30083) over the
ballot. The stamped bytes are the ballot's canonical bytes with sig.value
emptied, the bytes ballot_id hashes.
content.hash = "sha256:" || ballot_id
content.length = length of those bytes
content.mime = "application/vnd.oc-vote.ballot+json"
Any address may sign the stamp: the voter, the poll's creator, or anyone. The
stamp proves only that ballot_id existed before its anchor block; who signed
it says nothing about the ballot. Find the stamps over a ballot by
{"kinds":[30083],"#t":["sha256:<ballot_id>"]}.
Anchor height. anchor_height(b) is the lowest block height among the
stamps over b whose OpenTimestamps anchor you verified yourself. A stamp
counts toward it only if:
- its id reconstructs (OC Stamp §8.1 step 3);
- its
content.hash, read from the rebuilt stamp, equals"sha256:" || ballot_id(b). You MUST check this: the#ttag that found the stamp is relay metadata, outside the stamp id.content.lengthandcontent.mimedo not bear on priority; - its proof walks from that id to a Bitcoin attestation whose block header you
checked yourself (OC Stamp §6.3, §7.2 step 2). The height is that of the
earliest such attestation in the proof, never a declared
block_heightthat disagrees.
You MUST query several relays and keep every stamp over a ballot that any of
them returns, never one per ballot or one per d tag: several stamps can cover
one ballot, and copies of one stamp carry different proofs as calendars upgrade
them. Take the lowest height you verified across all of them. The stamp's own
signature does not bear on priority, and you MAY skip it. A ballot with no such
stamp has no anchor height.
An anchor you could not check, because a block header could not be read, is not a missing anchor. Until you can check every stamp you hold, you MUST NOT produce a final tally.
What the anchor decides. Whether a ballot's bytes existed in time, and nothing else. When the ballot was published does not bear on it.
Close. H_close is the greatest block height whose median_time_past ≤
deadline, the block a "deadline" snapshot resolves to. It is known once a
block whose median_time_past is after deadline exists; until then it is
none. G is 36 blocks, about six hours, for calendar aggregation and block
inclusion.
- A final tally of an anchored poll counts a ballot only if
anchor_height(b) ≤ H_close + G; any other ballot is dropped withE_NOT_ANCHORED. - The tally is final only once
H_closeis known and your chain tip is at leastH_close + G + 6. Before that it is provisional: it counts every ballot that passes the other checks, anchored or not, and says how many of them are not yet anchored at or belowH_close + G.
How late a ballot can count. median_time_past is the median of the last
eleven block times, so it trails the clock by about six blocks: H_close is
usually mined about an hour after deadline. A ballot dated at or before
deadline but cast after it can therefore still be anchored at or below
H_close + G and count.
Who anchors.
- A voter's client SHOULD stamp each ballot it publishes, submit the stamp id to at least two calendars, publish the stamp, and republish it once upgraded. As the deadline nears it SHOULD tell its voter when their ballot has no confirmed anchor yet.
- Anyone may anchor any ballot they can see. vote.ochk.io runs a convenience anchorer that stamps every ballot it observes for an open anchored poll and publishes the stamps. A voter may rely on it for liveness; it is never required, anyone can run another, and a tally depends only on the anchors, not on who made them. It works within published limits, per run (every ten minutes): at most 300 new stamps, shared round-robin across polls, and at most 50 per poll, in the order it first saw the ballots (never by a date a publisher chose); at most 50 polls read, chosen at random when more are open. What a limit leaves waits for a later run, and every stamp it made is upgraded and republished whatever the limits. Its health page says when a limit left work, and voters' clients anchor their own ballots, as above. Its address is on the OC Vote overview.
- The OpenTimestamps calendars are trusted for liveness only: they can delay a proof, not backdate one.
4. reveal object (secret mode)Link to this section
{
"v": 0,
"kind": "oc-vote/reveal",
"poll_id": "<hex>",
"reveal_sk": "<32-byte hex X25519 secret>",
"revealed_at": "<iso8601 UTC>",
"sig": { "alg": "bip322", "pubkey": "<creator>", "value": "<base64>" }
}
Publication (SPEC §6.3): kind 30082.
kind = 30082
tags = [
["d", "oc-vote:reveal:<poll_id>"],
["t", "<poll_id>"],
["t", "oc-vote-reveal"],
["poll_id", "<poll_id>"]
]
content = canonical bytes of the reveal, sig.value included
Accepting a reveal (SPEC §10.3): for an anchored poll, a tallier MUST NOT accept
one until its chain tip is at least H_close + G + 6, and never while H_close
is none. For a clock-dated poll, it MUST NOT accept one while its own clock
reads before deadline. revealed_at is the creator's statement and decides
neither. A reveal whose reveal_sk is not the X25519 secret key for the poll's
reveal_pk is rejected.
The multi-letter tags (poll_id, creator, voter, …) are diagnostics. Relays
index single-letter tags only, so a reader MUST NOT depend on them.
5. canonicalization (SPEC §7)Link to this section
- UTF-8 JSON with keys sorted lexicographically at every level.
- No insignificant whitespace.
poll.options[]preserves creator-declared order (spec's own exception to pure RFC 8785).- Numbers: integers plain, no floats expected.
- Strings:
\uXXXXonly for control chars,",\. Everything else literal. - Final byte: LF (0x0a).
- Depth: a poll, ballot or reveal nests at most 32 levels of objects and arrays, the object itself being level 1. One nested deeper is malformed: a verifier rejects it and a tally does not count it (vectors v17, v18).
Reference: RFC 8785.
6. tally algorithm (SPEC §8)Link to this section
Pure function over (poll, ballots, UTXO snapshot, chain tip, and, for an
anchored poll, H_close and each ballot's anchor height):
- Drop ballots whose
poll_id≠ target, whosecreated_atis notiso8601_utcor is afterdeadline, and, in a final tally of an anchored poll, whose anchor is not at or belowH_close + G(E_NOT_ANCHORED). - Verify every
voterBIP-322 signature (unless skipped). - De-duplicate per voter using
poll.tiebreak(latestorfirst). The key is(anchor_height, created_at, ballot_id)in an anchored poll and(created_at, ballot_id)in a clock-dated one;latestpicks the greater,firstthe lesser. In a provisional tally an unanchored ballot sorts after every height. - If
mode == secretand no accepted reveal: return{state: awaiting_reveal}. - If secret: unseal each ballot via
reveal_sk, verify commit, substitute option. - Resolve
snapshot_blockto integer if "deadline" (H_close). If the snapshot block is not yet known or has fewer than 6 confirmations, return{state: deferred, code: E_REORG}. - For each voter: compute
weight = weight_for_mode(utxos_at(voter, H)). - Sum weights per option.
Returns {state, snapshot_block, turnout, tallies, counted}. state is
tallied once the tally is final, and provisional for an anchored poll whose
H_close is unknown or whose chain tip is below H_close + G + 6. A
provisional result adds unanchored: how many counted ballots have no anchor at
or below H_close + G yet (no anchor at all while H_close is none).
basisis on every result,awaiting_revealanddeferredincluded:"anchored"or"voter_clocks". A client MUST show a"voter_clocks"tally as dated by the voters, and a"provisional"tally as not yet final.close_heightis on every result for an anchored poll:H_close, ornullwhile it isnone.countedlists theballot_idthat stood for each voter after the tiebreak and any reveal (steps 3–5), withdrawals and ballots that weigh zero included, as lowercase hex in ascending order.
A secret-mode anchored poll is never provisional: its reveal is accepted only
once the tally can be final, so until then it is awaiting_reveal. A ballot
found after a tally counts in a later tally under the same rules; a client that
shows the earlier tally SHOULD show it apart, and MUST NOT fold it into that
tally's figures. See tally algorithm for the full
walk-through.
7. weight modes (SPEC §5)Link to this section
Given U = qualifying UTXOs at snapshot H, aged ≥ min_days:
- one_per_address:
1ifsum(U) ≥ min_sats, else0. - sats:
sum(U)if≥ min_sats, else0. - sats_days:
sum(u.value × min(age_days(u), cap_days)), gated bymin_sats. Requiresweight_params.cap_days.
See weight modes for when to pick which.
8. error codes (SPEC §9)Link to this section
| code | meaning |
|---|---|
E_ | BIP-322 did not verify |
E_ | ballot's poll_id does not match |
E_ | created_at > deadline |
E_ | ballot's option not in poll.options |
E_ | revealed option does not match commit |
E_ | voter weight = 0 (below min_sats/min_days) |
E_ | secret-mode poll past deadline, no reveal |
E_ | anchored poll: no anchor at or below H_; dropped from a final tally |
E_ | snapshot block not yet known or < 6 confirmations; tally deferred |
E_ | client does not implement weight_mode |
9. nostr kindsLink to this section
| kind | object | tag namespace |
|---|---|---|
| 30080 | poll | oc- |
| 30081 | ballot (one event per ballot; tiebreak picks) | oc- |
| 30082 | reveal | oc- |
10. compliance checklistLink to this section
A client is v0 compliant iff it:
- canonicalizes identically (all test vectors pass)
- verifies every BIP-322 signature before counting
- implements
one_per_address,sats, andsats_days - enforces
min_sats/min_days - de-duplicates per voter per tiebreak
- keeps publishing a poll, a ballot or a reveal until at least two of the relays talliers ask, each asked alone, serve back a copy that verifies (every one, when they ask fewer than two), and reports it as counted or published only then (SPEC §3.4)
- treats its ballots as complete, or a reveal as absent, only when the read
floor of the relays it asked answered in full, each read paged with
untiluntil a page comes back short, and none was cut off: the number asked, less 2, plus 1, never fewer than one (four of five). Below it, a clock-dated poll gets no count, an anchored poll's tally is at most provisional, never final (a secret-mode one staysawaiting_reveal), and a short reveal read never givesawaiting_reveal(SPEC §6.5) - defers tally while the snapshot block is unknown or has < 6 confirmations
- in an anchored poll, verifies ballot anchors against block headers, counts
only ballots anchored at or below
H_close + Gin a final tally, and labels a tally provisional until the tip reachesH_close + G + 6 - in an anchored poll, keeps every stamp over each ballot from every relay,
checks each rebuilt stamp's
content.hashagainstballot_id, takes the lowest anchor it verified, and produces no final tally while any anchor cannot be checked - labels a clock-dated tally as dated by the voters' own clocks, and reports
basison every result - lists the ballots a tally counted, and shows a ballot found after a tally apart from it
- never reveals partial secret-mode tallies before a valid reveal event
- verifies
secret.commitat reveal time - emits the spec's error codes
11. read the real specLink to this section
oc-vote-protocol/SPEC.md (opens in a new tab)
— the normative version, with full canonicalization edge cases and test vectors.