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/coreShared/ contains runtime-neutral UI primitives, wallet and chain integration, shared workflows, and the simulation engine used by all three interfaces
• ui/zoltarShared/ and ui/statoblastShared/ expose reusable product libraries without application bootstrap, routing, or pages; Trading-specific capabilities currently live in the Trading application because no implementation is shared with another consumer
• ui/zoltar/ contains the Zoltar oracle operations interface (its own package, dev server, and production build)
• ui/statoblast/ contains the Augur Statoblast prediction-market operations interface (its own package, dev server, and production build)
• ui/trading/ contains the Statoblast Trading interface (its own package, dev server, and production build)
• solidity/contracts/trading/ contains the Trading contracts, shared/trading/ts/trading/ contains reusable AMM math, and contract-facing tooling and tests live under solidity/ts
• shared/ contains independently built Core, Zoltar, OpenOracle, Statoblast, and Trading runtime packages used by Solidity tooling and the UI
• docs/ contains the published protocol documentation
• tooling/ contains typed repository metadata plus CI, contract-safety, documentation, testing, and UI build/development orchestration; scripts/ retains only the pinned Uniswap deployment artifact
• bots/ contains chaos, liquidator, and OpenOracle arbitrager bots
• augurScan/ contains the read-only protocol explorer and indexer
• testnetwork/ contains the Docker Compose setup for the repository-pinned local Anvil network
• reth/ contains the Docker Compose setup for a pruned Sepolia Reth and Lighthouse node

The runnable packages (ui/zoltar, ui/statoblast, and ui/trading) are dependency leaves: they own bootstrap, routes, application composition, and tests. Reusable product capabilities live in the matching shared library, while runtime-neutral primitives, hooks, wallet/chain integration, transactions, and simulation infrastructure live in ui/coreShared/ts. Package exports and the UI boundary checker prevent shared libraries from importing runnable applications or applications from importing one another.

Protocol documentation lives in docs/documentation.html. Statoblast Trading has its own tutorials, how-to guides, and reference under solidity/docs/trading/.

Prerequisites

• Bun 1.4.2 (the version pinned by packageManager and CI)
• Node.js 20+ for the repository-wide TypeScript check

Setup

On a fresh checkout, run the complete bootstrap:

bun run setup

Important:

• bun run setup installs every independent package from its own frozen lockfile exactly once, generates shared contract and vendor inputs once, and builds the UI and test outputs in dependency order.
• Repository install helpers automatically use Bun 1.4.2 when invoked from another Bun version, avoiding local-package resolution differences between Bun releases.
• The root install includes the repository-pinned native Anvil binary on supported platforms. Set ANVIL_BIN to another installation only when overriding it intentionally.
• Standalone commands like bun tsc, bun run tsc, and bun run test assume the root dependencies are already installed.

Local Development

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

1. Start the repository-pinned local chain with bun run anvil
2. Run bun run app:serve:zoltar for Zoltar (http://localhost:4153), bun run app:serve:statoblast for Statoblast (http://localhost:12347), or bun run app:serve:trading for Trading (http://localhost:4163)

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

bun run app:watch:zoltar
bun run app:watch:statoblast
bun run app:watch:trading

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/zoltar/ts/deployment/sepoliaRepAllocations.ts. Changing that list also changes the deterministic genesis REP address and every dependent deployment address.

Testnet deployment

The testnet deployer installs the complete deterministic infrastructure. It is safe to rerun: existing contracts are skipped only when their runtime bytecode matches, and an unexpected contract at a target address stops the deployment.

Before you deploy

• Complete Setup.
• Use a dedicated testnet account and fund it with enough testnet ETH for the remaining steps.
• Use an HTTPS RPC endpoint. Loopback HTTP endpoints are accepted for local test networks.
• Ensure the deployer account has no pending transactions.

Sepolia is the default target (chain ID 11155111). A different testnet must support EIP-1559, the Cancun opcodes used by Zoltar and Uniswap V4, and the Osaka CLZ opcode used by the compiled contracts. The deployer rejects Ethereum mainnet (chain ID 1).

Deploy with GitHub Actions

Use the Deploy Testnet Contracts workflow for a deployment from main:

1. Create a protected GitHub environment named testnet-deployment.
2. Add the deployer's private key as the environment secret TESTNET_DEPLOYER_PRIVATE_KEY.
3. Open Actions → Deploy Testnet Contracts → Run workflow.
4. Select main, complete the inputs, and enter DEPLOY as the confirmation.
5. Review the job summary for each planned deployment's result and address. It includes transaction hashes for contracts deployed during the run.

Use a public RPC URL without credentials. Workflow inputs are stored in GitHub metadata and are not secret.

Deploy locally

Load PRIVATE_KEY from a secret manager or hidden prompt. Never paste the key into a command because it may be saved in shell history. For example, in Bash:

read -rsp 'Testnet deployer private key: ' PRIVATE_KEY && echo && export PRIVATE_KEY

Run the deployer with an explicit RPC endpoint and spending limits:

bun run deploy:testnet -- --rpc-url=https://rpc.example --chain-id=11155111 --max-fee-per-gas-gwei=100 --max-total-cost-eth=20

Remove the key from the shell when the command finishes:

unset PRIVATE_KEY

The deployer reads the exported PRIVATE_KEY automatically. You can instead pass the key directly, but the complete command—and therefore the key—may be saved in shell history:

bun run deploy:testnet -- --private-key=0x... --rpc-url=https://rpc.example --chain-id=11155111 --max-fee-per-gas-gwei=100 --max-total-cost-eth=20

Run bun run deploy:testnet -- --help for all options. Options other than --private-key also accept uppercase arguments after -- or environment variables.

Input	Default	Purpose
RPC_URL / --rpc-url	Required	RPC endpoint for the target network
CHAIN_ID / --chain-id	11155111	Expected decimal chain ID
MAX_FEE_PER_GAS_GWEI / --max-fee-per-gas-gwei	100	Rejects higher RPC fee suggestions
MAX_TOTAL_COST_ETH / --max-total-cost-eth	20	Caps the conservative preflight estimate and transaction budget
PRIVATE_KEY / --private-key	Required	0x-prefixed 32-byte deployer key

The defaults are authorization limits, not a spend forecast or a required balance. Before sending a transaction, the command checks the RPC chain ID, EVM features, EIP-1559 support, canonical deployer compatibility, expected bytecode, and fee limits. It then estimates only the missing deployment steps. If the conservative estimate exceeds MAX_TOTAL_COST_ETH, it exits before funding or deploying anything. Per-transaction checks enforce the same budget while the deployment runs.

If a run is interrupted, wait for all pending transactions to settle and rerun the same command. The deployer revalidates completed contracts and resumes with the first missing step. A testnet that rejects the fixed legacy transactions for the canonical deployers must provide both deployers as predeploys.

A successful local run exits with status 0 after logging each planned contract as deployed or skip and verifying the bootstrap support contracts.

Deployed infrastructure

Every deployment includes:

• deterministic WETH and genesis REP
• the canonical CREATE2 deployer and Permit2
• a deterministic Uniswap V3 factory, SwapRouter, and QuoterV2
• a Uniswap V4 PoolManager and Quoter
• the Zoltar and Augur Statoblast protocol factories and their bootstrap support contracts

The command does not create Uniswap pools or add liquidity. Protocol factories create market-specific security pools, share tokens, oracle coordinators, auctions, escalation games, delegates, and child-universe contracts later, when those features are used.

Browser Simulation

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

1. Run bun run app:serve:zoltar (Zoltar on port 4153), bun run app:serve:statoblast (Statoblast on port 12347), or bun run app:serve:trading (Trading on port 4163)
2. Open http://localhost:4153/?simulate=1, http://localhost:12347/?simulate=1, or http://localhost:4163/?simulate=1

This mode does not require a wallet extension or anvil. Instead, it boots a Tevm-backed in-browser chain and seeds the QA accounts with ETH, WETH, and REP. Zoltar and Statoblast scenarios control whether application contracts are already deployed. In Trading, simScenario=deployed deploys a seeded SecurityPool plus the Trading factory and router so its market routes are immediately usable, and the default simScenario=trading-funded additionally initializes pair liquidity and funds the simulation wallet with YES, NO, INVALID, and LP shares.

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.
• Supported seeded scenarios are simScenario=baseline, simScenario=deployed, simScenario=security-pool, simScenario=securitypoolx2, simScenario=securitypoolx2-auction, and simScenario=trading-funded
• The live simulation chain is ephemeral and exists only in the current browser tab session; only states explicitly saved from the simulation banner persist in browser storage

Common Commands

Run each interface in development mode. Each command first builds the complete dependency-ordered UI workspace, then serves the selected app:

bun run app:serve:zoltar      # Zoltar on http://localhost:4153
bun run app:serve:statoblast  # Statoblast on http://localhost:12347
bun run app:serve:trading     # Trading on http://localhost:4163

Watch the selected app and its dependencies after the complete workspace build:

bun run app:watch:zoltar
bun run app:watch:statoblast
bun run app:watch:trading

Build all UI apps:

bun run app:build

Regenerate contract bindings and UI vendor assets:

bun run generate

Compile the Solidity contracts:

bun run compile-contracts

Run the root test suite:

bun run test

Run the normal affected-project checks and print the narrower test-plan explanation:

bun run check:affected
bun run test:plan

Changes to global, unowned, CI, or repository-tooling paths make check:affected select the full registered check set. Project-owned changes select the owning project and its registry dependents. When a package's canonical check command already covers its typecheck, lint, or tests, affected validation runs that composite once instead of repeating the covered work.

Run the complete local validation suite used for CI/release parity:

bun run validate

bun run validate runs the root suite, every independent package check command, formatting, repository checks, dead-code analysis, and generated-output freshness. CI component selection, dependency expansion, cache inputs, generated outputs, and local component commands come from tooling/repo/projects.ts. A CI failure names the same root or component command used locally. Contract-size and delegate-layout failures reproduce with bun run check:contract-safety; source-size failures reproduce with bun run check:source-size.

Run every local package suite and the required browser smoke tier (after the complete fresh-checkout setup above):

bun run test:all

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 the repository-pinned Anvil in one terminal:

bun run 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:

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

Use GAS_COST_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 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.