Local development

Prerequisites

Node.js 22.23.1 from the repository .node-version
Bun 1.3.13 from packageManager
Foundry with Solidity 0.8.28 support
Git with submodules initialized for contract dependencies
PostgreSQL and Redis when exercising durable coordination, API credentials, or multi-replica behavior

git submodule update --init --recursive
bun install --frozen-lockfile
bun run build
bun run typecheck

The repository is a Bun workspace orchestrated by Turborepo. Root build, test, typecheck, and lint tasks delegate to packages and apps; package-local commands are faster while iterating.

Workspace map

Path	Stack	First commands
`packages/contracts`	Foundry/Solidity	`bun run --cwd packages/contracts test`
`packages/protocol`	TypeScript, ABI/codecs	`bun run --cwd packages/protocol test`
`packages/sdk`	TypeScript, viem/ethers adapters	`bun run --cwd packages/sdk test`
`apps/api`	Bun/Elysia/Drizzle	`bun run --cwd apps/api dev`
`apps/indexer`	Ponder	`bun run --cwd apps/indexer codegen`, then `dev`
`apps/keeper`	Bun/Effect/Drizzle/BullMQ	`bun run --cwd apps/keeper start:<role>`
`apps/market-data`	Bun/Elysia	`bun run --cwd apps/market-data dev`
`apps/frontend`	Vite	`bun run --cwd apps/frontend dev`

Use the checked-in .env.example and apps/keeper/env/*.env.example files as schemas. Copy into a gitignored local file and replace placeholders; never edit a template with a real credential.

Contracts: no-IR is mandatory

The default Foundry profile does not enable via_ir. This is a product constraint, not a local optimization:

bun run --cwd packages/contracts test:non-ir
bun run --cwd packages/contracts test
bun run --cwd packages/contracts lint

Do not fix a stack-depth regression by enabling IR. Reduce function scope, use typed structs, or split logic while retaining ABI and invariant coverage. Generated protocol ABIs come from the current contract build:

bun run gen:abi

Commit generated ABI changes with the Solidity change that caused them.

Local infrastructure modes

Unit mode

Most tests use memory adapters and deterministic fake RPC/fetch implementations. They require no network, database, Redis, signer, or Railway access.

Integration mode

Use local PostgreSQL and Redis for Drizzle migrations, queue/outbox behavior, API credential storage, transaction reconciliation, and multi-replica tests. Apply migrations explicitly before starting runtime processes:

bun run --cwd apps/api db:migrate
bun run --cwd apps/keeper migrate

Ponder uses local PGlite when DATABASE_URL is absent. Set its start block to the earliest deployed Tayho contract block; using a convenient later block creates an invalid projection.

Chain mode

Contract and runtime qualification can use a local Anvil/fork or the development HyperEVM deployment. Live signing tests use dedicated development wallets only. Never point local tests at production signers or production coordination stores.

Running services

Start only the roles needed for the flow. A typical read/API loop is indexer, API, and frontend. A relayed-action loop adds PostgreSQL, Redis, engine, and relayer.

bun run --cwd apps/indexer dev
bun run --cwd apps/api dev
bun run --cwd apps/keeper start:engine
bun run --cwd apps/keeper start:relayer

Other keeper entrypoints are automation, oracle, attester, guardian, revenue, and auditor. Each process must use its matching environment template. Do not combine roles into one process or key pool.

Test layers

Layer	Command	Purpose
Focused unit	`bun test <path>`	Fast behavior while editing
Package	`bun run --cwd <workspace> test`	Workspace contract
Root	`bun run test`	Build-dependent monorepo regression
Types	`bun run typecheck`	Cross-workspace TypeScript/Foundry compile
Contracts	`forge test` through package script	Solidity units, fuzz, invariants
Ponder runtime	`bun run --cwd apps/indexer test:runtime`	Opt-in patched runtime startup
Documentation	`bun run docs:check`	Content, generated specs, examples, Mintlify

Run the narrow suite first, then the owning workspace suite, then root gates proportional to the change. Schema, deployment, signing, and public API changes require their focused integration suites.

Documentation preview

bun run docs:dev
bun run docs:dev:engineering

The first command previews anonymous content. The second includes engineering pages. Repository classification checks are necessary but do not replace the deployed partial-authentication acceptance gate.

​Local development

​Prerequisites

​Workspace map

​Contracts: no-IR is mandatory

​Local infrastructure modes

​Unit mode

​Integration mode

​Chain mode

​Running services

​Test layers

​Documentation preview