Zoltar + Augur Statoblast

This repository contains two protocol layers:

• Zoltar: the forkable oracle base layer
• Augur Statoblast: the prediction-market application layer built on top of Zoltar

The codebase is split into these main areas:

• solidity/ contains contracts, protocol test support, tests, and generated contract artifacts
• ui/ contains the Preact frontend, organized by application shell, feature, and protocol-client boundaries
• shared/ contains runtime-neutral TypeScript used by Solidity tooling and the UI
• docs/ contains the published protocol documentation
• scripts/ contains repository-wide build, validation, and test orchestration

Inside ui/ts, route-specific code belongs under features/<domain>, cross-feature UI primitives remain in components, application composition belongs in app, and contract reads and writes belong in protocol.

Protocol documentation lives in docs/:

• Security model — normative participant, market, asset, deployment, client, data, Ethereum, account-authority, and cryptographic assumptions A01–A28
• OpenOracle tradeoffs — audit orientation for intentionally unbounded oracle notional and paid rolling disputes
• Truth-auction clearing — funded and underfunded clearing mechanics
• Start here guide

For oracle audit classification, use the OpenOracle tradeoffs and attack model. For weak-demand auction behavior, use Truth-auction clearing. The invariant catalog owns the current requirement, status, and evidence for EXT-05 recursive-fork gas behavior.

Deterministic deployment outputs live in the generated mainnet and Sepolia manifests. The repo keeps those files as source-of-truth data instead of maintaining separate prose pages for the same addresses.

Prerequisites

• Bun 1.3+
• Foundry anvil for local chain work

Setup

On a fresh checkout, start with the root dependency install:

bun install --frozen-lockfile

Then run the full bootstrap:

bun run setup

Install anvil if it is not already available:

bun run install:anvil

Important:

• bun run setup is the fastest way to get to a working repo after the root install.
• Standalone commands like bun tsc, bun run tsc, and bun run test assume the root dependencies are already installed.
• If you skip the initial bun install --frozen-lockfile, fresh checkouts can fail with missing packages such as bun-types.

Local Development

After completing Setup, start a local chain and launch the app:

1. Start anvil
2. Run bun run app:serve

If you are iterating on the app and want rebuilds, use:

bun run app:watch

RPC Configuration

The mainnet UI read backend defaults to https://ethereum.dark.florist; Sepolia defaults to its profile RPC at https://ethereum-sepolia-rpc.publicnode.com. You can override the active network's default without changing code:

• Add ?rpcUrl=https://your-rpc.example to the app URL
• Set localStorage['zoltar.rpcUrl']
• Set globalThis.__ZOLTAR_RPC_URL__ before bootstrapping the app
• Set the ZOLTAR_RPC_URL environment variable for environments that inject process.env

Sepolia

Open the application with ?network=sepolia in either the page query or route query (for example, #/deploy?network=sepolia). The application then uses Sepolia chain ID 11155111, its configured public RPC, Sepolia Etherscan links, and Sepolia-specific deterministic contract addresses.

The Sepolia deployment flow includes WETH and genesis REP before the contracts that depend on them. Initial Sepolia REP holders and exact 18-decimal balances are defined in shared/ts/sepoliaRepAllocations.ts. Changing that list also changes the deterministic genesis REP address and every dependent deployment address. See the Genesis REP deployment procedure for constructor guards and recovery steps.

Sepolia quote-dependent actions query live, network-local Uniswap liquidity. The OpenOracle integration guide owns the quote-source order and address-selection details.

Browser Simulation

The UI also supports a walletless browser-local simulation mode for manual QA. After completing Setup:

1. Run bun run app:serve
2. Open http://localhost:12345/?simulate=1

This mode does not require a wallet extension or anvil. Instead, it boots a Tevm-backed in-browser chain, seeds the QA accounts with ETH, WETH, and REP, and leaves the application contracts undeployed so the UI starts on the deploy flow.

Simulation mode details:

• The activation flag is ?simulate=1
• The flag is intentionally not restricted to localhost or development builds; production deployments may expose it as a browser-local demo and manual-QA path
• Production users should treat any ?simulate=1 URL as a local sandbox. Simulated balances, deployments, blocks, quotes, and transactions are local to the browser and are not evidence of mainnet state.
• The default seeded scenario is ?simulate=1&simScenario=baseline
• Supported seeded scenarios are simScenario=baseline, simScenario=deployed, simScenario=security-pool, simScenario=securitypoolx2, and simScenario=securitypoolx2-auction
• The yellow simulation banner exposes developer-only controls for account switching, reset, block mining, time travel, blockchain time, block count, transaction count, and artificial transaction receipt delay
• Its Mint 1 million REP control credits only the selected QA account inside the tab-local simulation. It raises the simulated REP theoretical supply and, when Zoltar is deployed, synchronizes the genesis universe supply and fork threshold. It does not request a wallet transaction or mint on mainnet or Sepolia. Resetting the simulation or closing the tab discards unsaved credited REP; an explicitly saved or exported simulation snapshot can restore it only inside another browser-local simulation. On public Sepolia, Genesis REP remains limited to the constructor-fixed allocation list; mainnet REP is unaffected.
• Simulation does not call Uniswap. Supported REP/ETH, REP/WETH, and REP/USDC quote paths use the configured browser-local mock; unsupported pairs degrade. Simulation prices are not evidence of mainnet liquidity.
• Mainnet and Sepolia quote-dependent flows rely on live RPC data and available network-local Uniswap liquidity under A24 client and RPC integrity. Available and representative liquidity is an official-client limitation, not a protocol security assumption. If a quote is stale, unavailable, or unsupported, affected client actions should remain blocked or degraded rather than falling back to simulated prices.
• The live simulation chain is ephemeral and exists only in the current browser tab session; explicitly saved or exported snapshots can recreate its state in a later browser-local session

Common Commands

Run the full app in development mode. This includes contract generation and the frontend build pipeline:

bun run app:serve

Watch and rebuild the full app pipeline:

bun run app:watch

Build the full app:

bun run app:build

Regenerate contract bindings and UI vendor assets:

bun run generate

Compile the Solidity contracts:

bun run compile-contracts

Run the full test suite:

bun run test

Run the launch-focused fork, auction, and exit invariant gate:

bun run test:launch-invariants

Run coverage across every canonically discovered TypeScript test:

bun run coverage

Run full coverage, including the slow Solidity bytecode trace phase:

bun run coverage:full

Type-check the TypeScript code:

bun run tsc

Format the codebase:

bun run format

Run linting:

bun run lint

Auto-fix lint issues:

bun run lint:fix

Run dead-code analysis:

bun run knip

Auto-fix dead-code findings:

bun run knip:fix

Measure Solidity gas costs:

bun run gas-costs

By default, gas-costs starts an isolated Anvil node. To measure against an existing local node instead, start Anvil in one terminal:

anvil --host 127.0.0.1 --port 8545 --chain-id 1 --block-base-fee-per-gas 0 --gas-price 0 --no-priority-fee

Then run gas-costs against it from another terminal:

ANVIL_RPC=http://127.0.0.1:8545 bun run gas-costs

Use ANVIL_RPC=http://host.docker.internal:8545 bun run gas-costs when the command runs from a container that reaches the host through Docker routing.

Notes

• bun run tsc is a pure typecheck for the app TypeScript, the Solidity-side TypeScript utilities, and the Bun build/dev scripts. It does not regenerate shared assets or vendor output.
• bun run test runs the TypeScript check first, then executes the test suite.
• bun run test:launch-invariants is the targeted pre-release gate for adversarial fork, truth-auction, unresolved escalation carry, and auction edge-case invariants.
• bun run coverage runs every canonically discovered TypeScript test, reports weighted coverage for UI, shared, and tooling source, counts statically identified executable lines and functions in unloaded source as zero-hit coverage, and checks product TypeScript from the origin/main merge base through committed, staged, unstaged, and untracked task changes. Set COVERAGE_BASE_REF or pass --base-ref to the reporter to use another comparison ref. Use bun run coverage:full to enforce the same policy with the slower Solidity bytecode trace phase.
• The legacy ui:* commands still exist as compatibility aliases, but app:* names are the clearer entrypoints because they run more than frontend-only work.
• The repo uses exact dependency versions for reproducible installs.