Prototype docs. APIs may change while SDKs and verifier libraries harden.
Roll consumption
Consumers read one ordered stream per domain:
ballot 0 -> outcome
ballot 1 -> outcome
ballot 2 -> outcome
Use ZMQ to wake the consumer, then getreferendumresolution to fetch the next ballot. Polling can also be used directly in contexts where notifications are not available.
The consumer should apply rolls through one ordered path. ZMQ and polling can both trigger work, but both should read the same next_ballot cursor and call the same application handler.
Store
- domain preimage,
- next ballot pointer,
- roll hash,
- data hash,
- applied payload,
- whether the roll is soft-final or final.
Apply the roll and advance the cursor in the same database transaction when possible. If the app crashes after applying but before advancing, the handler should be safe to replay.
Gaps
Do not skip a missing ballot silently. If ballot N + 1 is available but ballot N is missing, keep polling from N until it resolves or your app explicitly records the gap.
Reorgs
Treat new rolls as soft-final until the underlying Bitcoin block has enough confirmations for your application.
If a roll hash changes during that window, reconcile application state.
Trust model
Run your own Char-enabled node. Do not make a random remote RPC server your trust root.