Domain application architecture

A Char domain application owns application state for an ordered stream of domain outcomes.

Char handles operator stake, leader selection, attestations, roll construction, and roll lookup. Your application defines what each ballot means and what to do when a ballot outcome is observed.

Define

• Domain: the stable identifier for your app or rollup.
• Ballots: the sequence of decisions in that domain.
• Payloads: the small value operators vote on for each ballot.
• Producer rule: when your app should produce a payload.
• Roll handler: how an observed roll updates application state.
• Cursor store: the next ballot your app still needs to reconcile.
• Finality policy: how many Bitcoin confirmations you wait before treating a roll as final.
• Recovery path: how missed ballots are replayed after downtime.

App contract

Most integrations reduce to three application hooks:

• Produce payload: given a ballot, return the payload your app wants operators to attest.
• Accepted submission: record that the local node accepted your payload submission, without assuming the ballot is decided.
• Observed roll: validate the roll against app rules, apply it idempotently, and advance the cursor.

Keep the cursor in your own database. Store enough roll metadata to retry safely: domain, ballot, roll hash, data hash, payload, and any block context your app uses for finality.

Runner responsibilities

A runner sits between your app and a local Char node. It should:

1. read domain info to find the next ballot,
2. check whether the loaded wallet controls the selected leader before submitting,
3. ask your app to produce a payload only when it should submit,
4. submit the payload through the node,
5. read or reconcile rolls from the persisted cursor,
6. call your roll handler in ballot order.

The simplest integration is via ZMQ, but polling can be used in other contexts as well. Both paths should converge on the same cursor and the same roll handler.

Related pages: /docs/apps/zmq, /docs/apps/polling.