> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tayho.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Local development

> Install, build, test, and run Tayho contracts, TypeScript packages, APIs, indexer, and workers locally.

# 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

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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.

```bash theme={null}
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

```bash theme={null}
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.