Placeholder and Zoltar Start Here

Placeholder is the market layer. Zoltar is the forkable oracle layer underneath it. A normal market stays inside one security pool: Traders mint ETH-backed shares, REP vaults provide backing, and local escalation tries to settle disputes without forking the wider system.

Only the hard cases leave that local path. If escalation cannot pick a single answer safely, Zoltar records the fork and defines explicit child branches. Child universes materialize only when migration or deployChild first uses one of those branches, and Placeholder migrates the market into whichever branches users choose to keep using.

After a fork, a holder can build migration balance by initiating the fork or adding parent REP after the fork. Calling splitMigrationRep mints child REP in each selected fork branch, with each branch receiving at most the source balance.

A normal market begins in one pool, forks only after sustained local non-decision, and then resumes in whichever child branches users keep using. That same sequence drives the rest of Placeholder: pool creation, trading, escalation, fork migration, then repair or redemption.

Keep one distinction in mind throughout: Zoltar decides how disagreement is represented, while Placeholder decides how a market is collateralized, disputed, migrated, and repaired around that oracle layer.

Mental Model

The stack has four layers. Zoltar defines the question and the possible branches of truth. Placeholder runs the market inside one branch until disagreement becomes strong enough that the branch itself has to split.

Layer Owns Why it exists Primary contracts
Zoltar Universes, questions, forks, and REP splitting. Truth disputes can create explicit branches instead of forcing one global answer immediately. Zoltar, ZoltarQuestionData, ReputationToken
Placeholder market layer Security pools, shares, vault accounting, and local disputes. Most markets should settle locally; forks are the recovery path when local disagreement remains economically sustained. SecurityPool, ShareToken, EscalationGame
Fork recovery Vault migration, child-pool setup, and collateral repair. After a fork, users need usable child pools in the branches they choose to continue using. SecurityPoolForker, child SecurityPool
Solvency oracle A fresh REP/ETH price for withdrawals, allowance updates, and liquidations. REP backs ETH-denominated obligations, so solvency checks need a bounded, contestable price. OpenOraclePriceCoordinator, OpenOracle
Market lifecycle overview A market starts from a Zoltar question, trades in a security pool, enters local escalation if disputed, then either resolves locally or moves through fork migration, auction repair, and redemption. Question Zoltar data Pool trade shares Escalate local REP Resolve Fork Migrate repair, redeem

Lifecycle MapThe normal path is question, pool, escalation, and local resolution. The fork path adds child-pool migration, optional auction repair, and branch-specific redemption.

Actors and Assets

These are the recurring roles in the lifecycle. If you only want the basic picture, focus on traders, REP vaults, and fork participants first.

Actor or asset What it does Role in the flow
Traders Mint and redeem complete sets of Invalid, Yes, and No shares. They interact with ETH collateral and share balances.
REP vaults Deposit REP into a security pool and choose bond allowance, the amount of REP-backed exposure they permit. They provide underwriting capacity and earn fees, but can be liquidated if under-backed.
Escalation depositors Move vault-backed REP into an escalation outcome after question end. They are trying to resolve the local market before a fork is needed.
Fork participants Reproduce parent-universe migration balance, the REP value available after a fork, into selected child universes, with each child capped by the source balance. They decide which branch they treat as useful; Zoltar does not choose for them.
Auction bidders Bid ETH for child-universe REP when a child pool needs collateral repair. The auction repairs ETH collateral instead of selecting truth.
Reporters and disputers Post and dispute OpenOracle REP/WETH reports. They support solvency pricing, not market resolution.

Happy Path

Most markets are supposed to end here. The market stays in one universe, uses one pool, and resolves locally without a fork.

  1. A question is registered in ZoltarQuestionData.
  2. A Placeholder origin pool is deployed for a binary question in an unforked universe.
  3. Vaults deposit REP into SecurityPool and set security-bond allowance.
  4. Traders mint complete sets with ETH and later redeem finalized winning shares.
  5. After the question end time, local escalation can resolve to a strict leading outcome. If every outcome has no deposits after the running cost becomes non-zero, Invalid wins. Otherwise it remains unresolved while at least two outcomes still meet the running cost; as running cost rises, one outcome may remain above cost and become the strict leader. Additional deposits can change that balance picture or, if two balances reach nonDecisionThreshold, open the fork flow.

The design tries this path first because local resolution is cheaper and less disruptive than splitting the whole universe. A fork is available when local capital remains split across outcomes strongly enough that a single local answer would be unsafe.

Fork Path

Fork handling has two entry branches. One branch starts when local escalation cannot safely collapse the dispute into one answer. The other starts when another market has already forked the universe first, so this pool must migrate into the child branches that fork has now defined. In both cases, a fork preserves disagreement instead of hiding it.

In the own-escalation branch, the local escalation game reaches non-decision when two or more outcomes cross the fixed threshold, and then Zoltar forks the parent universe on the disputed question. In the external-fork branch, another market or caller has already forked the universe first, so this pool enters migration through that existing fork without requiring its own local escalation game to reach non-decision.

  1. Callers create child pools and split pool REP for selected valid branches. Vault owners and share holders migrate their own positions into the child branch they choose.
  2. Child pools receive proportional collateral and REP state.
  3. If collateral is short, the truth auction sells child REP for ETH repair.

No contract declares one branch canonical. The system creates the branches and leaves users, applications, and future economic activity to coordinate on the branch they consider truthful.

Oracle Path

The REP/ETH oracle is a side system, not a truth system. It gives SecurityPool a fresh price for solvency-sensitive actions: REP withdrawal, bond allowance changes, and liquidation. It does not resolve market truth.

The coordinator stores a scaled REP-per-ETH price. A higher value means ETH is more expensive in REP terms, so more REP is required to cover the same ETH-denominated obligation.

One Example Market End to End

Imagine the question is Will Example City receive more than 10 inches of rain in 2027? Placeholder treats it as a binary market: Invalid, Yes, and No.

The example below walks through the same lifecycle in one place so the terms from the earlier sections appear in the order a user encounters them.

1 completeSet = 1 Invalid + 1 Yes + 1 No

Complete SetThe example market trades outcome shares. Deposited ETH mints complete sets through cashToShares, and redemption converts winning shares back to ETH through sharesToCash at the pool's current collateral-per-share rate. A one-ETH claim is only the initial simplifying case before fees or collateral changes alter that rate.

Stage What happens Primary contracts Why this stage exists
Pool creation The question is registered and an origin security pool is deployed. ZoltarQuestionData, SecurityPoolFactory Question data lives globally; market eligibility lives in Placeholder.
Trading Traders mint complete sets, while vaults deposit REP and set bond allowance. SecurityPool, ShareToken ETH backs shares; REP backs the security capacity around that ETH.
Escalation After question end, vault-backed REP can be locked behind Invalid, Yes, or No. SecurityPool.depositToEscalationGame, EscalationGame Local capital gets a chance to settle the market before a universe fork.
Local resolution If one outcome wins locally, winning shares redeem and escalation deposits settle. redeemShares, withdrawFromEscalationGame This is the cheaper happy path; no universe split is needed.
Fork path If non-decision is reached, Zoltar forks and Placeholder migrates pool state into selected child pools. Zoltar, SecurityPoolForker The protocol preserves disagreement explicitly instead of forcing one branch.
Auction repair If a child pool needs ETH collateral, it sells child REP through the truth auction. UniformPriceDualCapBatchAuction The auction repairs collateral instead of deciding truth.
Redemption Users redeem or continue trading in the child branch they treat as useful. SecurityPool, ShareToken Applications and users coordinate on branches after Zoltar creates them.

Concept Glossary by Lifecycle Stage

The terms stay grouped by the stage where they first become useful, so the same lifecycle order keeps the vocabulary anchored to the mechanism that needs it.

Stage Terms to know Plain-language anchor
Question and pool setup Universe, question id, outcome labels, origin pool. Zoltar stores possible answers; Placeholder deploys an origin pool only for eligible questions.
Trading and underwriting Complete set, share token, vault, security-bond allowance, retention rate. ETH backs tradable shares; REP vaults provide backing and receive fees.
Escalation Start bond, activation delay, running cost, binding capital, non-decision threshold. Vault-backed REP competes locally before the system asks Zoltar to fork.
Fork migration Child universe, migration balance, migration proxy, child pool, carry snapshot. A fork creates branches; Placeholder moves pool state into the selected branch.
Auction repair ETH raise cap, REP sale cap, clearing tick, underfunded threshold. Weak child-pool collateral can be repaired by selling some child REP for ETH.
Solvency oracle REP/ETH price, staged operation, freshness window, liquidation threshold. Operations that change REP backing or ETH exposure need a fresh contestable price.

Documentation Map

Each link below follows one part of the lifecycle into contract-level detail.

Goal Document
Understand the application layer from end to end. Placeholder whitepaper
Understand universes, question encoding, forks, and REP splitting. Zoltar whitepaper
Understand truth-auction clearing and settlement. Auction design
Understand REP/ETH price requests, staging, and attack model. OpenOracle integration
Understand punitive REP-seizure liquidation math, chunking limits, and incentives. Liquidation design
Look up edge cases and contract guardrails. Operator reference
Understand how the local dispute contract is split across Solidity modules. EscalationGame architecture