Zoltar White Paper

Zoltar is the base oracle layer in this repository. It does not run a market. It registers questions, records forks, and lets REP holders move value from a parent universe into one or more child universes after a fork.

Zoltar preserves disagreement explicitly. Instead of picking one winner onchain when a dispute becomes irresolvable inside one branch, Zoltar creates the valid child branches and lets later coordination determine which branch matters economically.

Zoltar supports both categorical and scalar questions, treats Invalid as a legitimate answer state, and keeps market collateral, trading, and underwriting logic out of the oracle layer. In Zoltar terminology, Invalid is a valid answer branch for a well-formed question, while Malformed means an encoded answer option is rejected before it can become a branch or final answer.

Zoltar's lifecycle has six contract-visible steps, from question registration through post-fork coordination.

Zoltar has one job: define the truth-layer objects that higher-level applications can rely on. It does not implement the market, collateral, or underwriting system built on top of it elsewhere in the repo. Its role is narrower and more fundamental:

• register questions
• encode valid answer spaces
• represent forks as child universes
• mint and burn child-universe REP
• turn migration balances into selected child REP

In practice, that means an application can hand Zoltar a question, later trigger a fork if disagreement persists, and then consume the child-universe structure that Zoltar defines. Applications therefore depend on the same order in operation: question, disagreement, fork, then child-universe state.

Core Contract Map

• Zoltar: universe forks and REP splitting
• ZoltarQuestionData: question registry and outcome encoding
• ReputationToken: child-universe REP minted and burned by Zoltar
• ScalarOutcomes: scalar formatting and interpolation logic

A universe is one branch of protocol state. The Zoltar.Universe struct stores the minimum data needed to identify that branch and connect it to its parent:

• forkTime: when the universe forked
• forkQuestionId: the question id recorded by forkUniverse and used to define child branches
• forkingOutcomeIndex: the outcome index represented by the universe when it is a child
• reputationToken: the REP token used inside that universe
• parentUniverseId: the parent branch

Universe 0 is the genesis universe. Its REP token is an external genesis token configured in Constants.GENESIS_REPUTATION_TOKEN. Child universes are identified deterministically as:

Deterministic child ids make each branch reproducible from parent universe and outcome index alone. Child universes are deployed lazily when a forked branch is actually needed.

Global Question Scope

Questions are global protocol objects in Zoltar. forkUniverse checks that the target universe exists, still has supply, has not already forked, and that the supplied question exists and has ended. It does not require the question to have been created for that universe. Applications that need a stricter universe/question relationship enforce it above Zoltar.

The threshold is a REP commitment large enough to force branch creation, but it is not itself a choice of the winning branch. The constructor stores forkThresholdDivisor; the current deployment default is 20.

Initiating a fork requires supplying the computed threshold. With the default divisor, that is 5% of the universe's theoretical supply before integer flooring. The full threshold deposit leaves the parent universe: forkUniverse burns or transfers that entire parent-REP amount and reduces the parent theoretical supply by the full threshold. The burn divisor then controls how much child-REP minting credit the initiator receives. Under the current deployment default forkBurnDivisor = 5, one fifth of the threshold is an uncredited haircut and the remaining four fifths becomes the initiator's migration balance.

Genesis REP cannot be burned natively, so the contract transfers it to the configured burn address. Child-universe REP is minted and burned directly by ReputationToken under Zoltar’s control.

A child's theoretical supply is a maximum for REP that can be minted in that branch. It starts from the parent's pre-fork theoretical supply and subtracts only the uncredited haircut. The initiator's remaining threshold deposit is migration credit, so it remains part of the maximum amount that could be minted in each child.

Repeated-fork threshold decay

Along one lineage, let theoreticalSupplyBeforeForkₙ be the theoretical supply before fork n. With the mainnet threshold divisor of 20 and burn divisor of 5, the exact integer recurrence is forkThresholdₙ = floor(theoreticalSupplyBeforeForkₙ / 20), haircutₙ = floor(forkThresholdₙ / 5), and theoreticalSupplyBeforeForkₙ₊₁ = theoreticalSupplyBeforeForkₙ - haircutₙ. This is close to multiplying supply by 0.99 at each generation, but both Solidity flooring operations matter once supply becomes small.

These depths require more than a thousand consecutive forks along the same surviving branch before escalation parameters become incompatible. They are therefore remote limits rather than near-term fork incentives. Implementers should nevertheless treat the first boundary as an explicit parameter limit: SecurityPool initializes an escalation game's non-decision threshold as half the current fork threshold, while EscalationGame requires that value to be strictly greater than its starting bond. A deployment expected to survive thousands of recursive forks needs either a minimum fork threshold or a compatible rule for scaling escalation parameters.

Once a universe forks, child universes can be deployed lazily through deployChild. A user can also add more REP into the migration balance with addRepToMigrationBalance. The core post-fork action is splitMigrationRep, which lets a holder mint child-universe REP for non-malformed outcome indices. Supplying no outcome indices is accepted as a no-op at the Zoltar layer.

For categorical questions, Invalid and any in-range categorical outcome are allowed, while out-of-range values are rejected. For scalar questions, only well-formed scalar encodings are allowed.

The fork question defines the child-branch shape for the whole universe. A child branch may therefore be keyed by Invalid, a categorical outcome index, or a scalar encoding depending on which parent-universe question forkUniverse used for the fork. Downstream applications should treat that branch selector as universe-level metadata rather than assume every child branch is binary.

At the implementation level, splitMigrationRep validates each selected outcome against the parent universe's fork question, lazily deploys any missing child universe, and records how much of the caller's migration balance has already been minted into each child. A caller cannot mint more into one child than the source migration balance available to that caller, but the same source balance can be reproduced into multiple valid children.

Zoltar is a Colored Coins-style system, so its security argument depends on user behavior and value concentration rather than on the contract being able to identify one objectively correct branch onchain.

• users can choose which child universe to continue using after a fork
• users prefer to continue in the universe they regard as truthful
• the protocol itself does not know which universe is truthful and treats all valid branches symmetrically
• most durable economic activity concentrates in the branch that users expect other users to keep using
• dishonest or abandoned branches may continue to exist, but are assumed to retain little long-term value compared with the branch that market participants keep coordinating around

A fork only creates branches. If users and future activity concentrate in the branch they regard as truthful, the value of child-universe REP also concentrates there. Holders can reproduce a migration balance into multiple valid child universes, subject to the per-child cap and the gas and coordination costs of doing so. The economic pressure is therefore value concentration: REP in an abandoned branch may keep existing, but it is expected to have little long-term value compared with REP in the branch that markets keep using.

Global forks are migrations, not permanent shutdowns

Zoltar questions are global protocol objects: any existing question whose end time has passed can identify the branches of any still-unforked universe. Recording the fork stops new operational changes in parent-universe pools so that their accounting cannot move while it is being snapshotted. Placeholder provides permissionless, user-driven paths to migrate REP, shares, vault positions, collateral, and unresolved escalation state into child-universe pools. A child pool can return to the operational state once the migration window and any required truth-auction and finalization transactions complete. Timely progress therefore depends on callers submitting those transactions and on the available migration participation. The parent boundary is a transition into child universes, not an intended permanent freeze of market activity.

A caller cannot trigger that transition for free under normal parameters. The caller supplies the full fork threshold in parent REP, loses the uncredited haircut, and receives migration credit for only the remainder. Existing REP holders can migrate their own positions and benefit from the reduced supply in the branches where economic activity continues. Consequently, an unrelated fork is economically evaluated as a costly forced migration: its risk is operational migration latency and coordination burden, while its deterrent is the initiator's threshold commitment and permanent haircut.

Likewise, a question with many valid outcomes creates more possible children, but it does not multiply value in the branch that ultimately retains economic coordination. Deploying and using many children costs gas, and REP in abandoned branches is expected to have little value. Outcome count by itself is therefore a gas and state-growth consideration, not a demonstrated value-extraction attack.

ZoltarQuestionData.QuestionData stores title, description, start and end time, scalar metadata such as numTicks, displayValueMin, displayValueMax, and answerUnit.

Question ids are deterministic hashes of the question data. For categorical questions, that hash path also includes the sorted categorical outcome options. For scalar questions, there are no categorical labels to include, so the id is determined from the scalar question fields alone.

Categorical Questions

Categorical questions store sorted outcome labels. The implementation requires labels to be non-empty and strictly ordered by hash: each label's keccak256(abi.encode(label)) value must be lower than the previous label's hash, so callers provide labels in descending hash order. The contract stores the labels in outcomeLabels[questionId]. Any number of categorical outcomes can exist at the Zoltar level as long as those conditions hold.

Scalar Questions

Scalar questions store no categorical labels. Instead, numTicks, displayValueMin, displayValueMax, and answerUnit define the answer space. At creation time, scalar questions must satisfy numTicks > 0 and displayValueMax > displayValueMin.

Onchain, each scalar answer is encoded into a single uint256 that packs:

• the highest bit as an invalid flag
• a 120-bit first payout numerator
• a 120-bit second payout numerator

The all-zero encoding is the canonical Invalid answer for scalar questions. For a valid scalar answer, the two payout numerators must sum exactly to numTicks:

At the helper and UI level, a scalar tick index named tickIndex is encoded as:

• firstPayoutNumerator = numTicks - tickIndex
• secondPayoutNumerator = tickIndex
• highest bit = 1

ScalarOutcomes interprets secondPayoutNumerator as the position along the scalar range:

displayValueMin and displayValueMax are stored as 18-decimal fixed-point display bounds. Formatting divides the atomic result by 1e18 and trims trailing zeroes. For example, with displayValueMin = 0, displayValueMax = 10e18, numTicks = 6, and secondPayoutNumerator = 1, the atomic value is floor(10e18 / 6), which displays as 1.666666666666666666 rather than an unrounded real number.

At the Zoltar layer, market type support comes from how questions and outcomes are encoded in ZoltarQuestionData.

• categorical questions, implemented as an ordered array of non-empty outcome labels
• scalar questions, implemented as a tick-based numeric range with no categorical labels

Zoltar can represent arbitrary categorical questions and scalar questions, while higher-level protocols may choose narrower market shapes on top of it. It defines answer spaces and forkable resolution state, not the collateralized trading mechanics that may later be attached to those questions.

Zoltar distinguishes Invalid answers from Malformed answers.

This distinction matters because malformed answers are rejected, while Invalid remains a valid branch and a valid final outcome.

Consider a universe parentUniverse and a question forkQuestion. After that question ends, forkUniverse can record it as the fork question for parentUniverse.

1. forkUniverse(parentUniverse, forkQuestion) records forkQuestion as the fork question for parentUniverse.
2. Child universes are defined deterministically from parentUniverse and each valid outcome index.
3. The fork initiator’s full parent-REP deposit leaves parent supply, and the post-haircut amount becomes migration balance.
4. Any REP holder can add more REP into migration balance for the forked universe.
5. REP holders call splitMigrationRep to mint child-universe REP across the outcome branches they support.

At that point, Zoltar has turned one disputed universe into multiple child universes with separate reputation tokens. The higher-level economic meaning of those branches is left to protocols built on top.

Zoltar provides a generalized branching oracle layer for categorical and scalar questions. Rather than forcing a single answer when disagreement persists, it turns unresolved decisions into explicit child universes and lets REP holders split post-fork claims across one or more selected branches.

In that sense it closely follows the Colored Coins model: the protocol branches state first, and later coordination determines which branch carries durable value.