Zoltar + Augur Placeholder

This repository contains two protocol layers:

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

The codebase is split into two main parts:

• solidity/ contains the contracts, tests, and generated contract artifacts
• ui/ contains the Preact frontend that reads from those contracts

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

Start a local chain with anvil, then run the setup step once and launch the app:

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

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

bun run app:watch

Browser Simulation

The UI also supports a walletless browser-local simulation mode for manual QA.

1. Run bun run setup
2. Run bun run app:serve
3. 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 default seeded scenario is ?simulate=1&simScenario=baseline
• 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
• Uniswap-backed REP pricing is intentionally disabled in simulation mode, so quote-dependent UI paths degrade instead of using mainnet liquidity
• The simulation chain is ephemeral and exists only in the current browser tab 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

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

Notes

• bun run setup is the quickest way to bootstrap a fresh checkout.
• bun install --frozen-lockfile must be run before standalone commands like bun run tsc on a fresh checkout.
• 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.
• 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.