# Dev Environment

## Prerequisites
Docker Engine (Linux) or Colima (Mac). See `docs/docker.md` for installation.

## Quick Start
```bash
nohup ./scripts/dev.sh start &    # start (takes ~3-6 min first time)
tail -f nohup.out                  # watch progress
./scripts/dev.sh health            # verify all services healthy
./scripts/dev.sh stop              # stop and clean up
```
Do not launch services individually — `dev.sh` enforces phased startup with health gates.

## Restart Modes
- `./scripts/dev.sh restart --light` — Fast (~10-20s): only webapp + txnbot, preserves Anvil/Ponder state. Use for frontend changes.
- `./scripts/dev.sh restart --full` — Full (~3-6min): redeploys contracts, fresh state. Use for contract changes.

## Environments
Supported: `BASE_SEPOLIA_LOCAL_FORK` (default Anvil fork), `BASE_SEPOLIA`, and `BASE`. Match contract addresses and RPCs accordingly.

## Ports
The stack uses these ports:
| Port  | Service    |
|-------|------------|
| 8545  | Anvil      |
| 5173  | webapp     |
| 5174  | landing    |
| 42069 | Ponder     |
| 43069 | txnBot     |
| 5100  | Otterscan  |
| 8081  | Caddy      |

Check with `lsof -i :<port>` if startup fails.

## Docker Topology
- `docker-compose.yml` has NO `depends_on`. Service ordering is handled by `scripts/dev.sh`.
- Startup phases: anvil+postgres → bootstrap → ponder → webapp/landing/txn-bot → caddy → smoke test.
- Shared bootstrap: `scripts/bootstrap-common.sh` (sourced by both local dev and CI).
- 20GB disk limit enforced. `dev.sh stop` auto-prunes. Named volumes for `node_modules`.
- All services have log rotation (30MB max per container) and PostgreSQL WAL limits configured.

## kraiken-lib Build
- Run `./scripts/build-kraiken-lib.sh` before `docker-compose up` so containers mount a fresh `kraiken-lib/dist` from the host.
- `scripts/watch-kraiken-lib.sh` rebuilds on file changes (requires inotify-tools) and restarts dependent containers automatically.
- The dev script runs the build automatically on `start`, but manual rebuilds are needed if you change kraiken-lib while the stack is already running.

## Common Pitfalls
- **Docker disk full**: `dev.sh start` refuses to run if Docker disk usage exceeds 20GB. Fix: `./scripts/dev.sh stop` (auto-prunes) or `docker system prune -af --volumes`.
- **Stale Ponder state**: If Ponder fails with schema errors after contract changes, delete its state: `rm -rf services/ponder/.ponder/` then `./scripts/dev.sh restart --full`.
- **kraiken-lib out of date**: If services fail with import errors or missing exports, rebuild: `./scripts/build-kraiken-lib.sh`.
- **Container not found errors**: `dev.sh` expects Docker Compose v2 container names (`harb-anvil-1`, hyphens not underscores). Verify with `docker compose version`.
- **Port conflicts**: See Ports table above. Check with `lsof -i :<port>` if startup fails.
- **npm ci failures in containers**: Named Docker volumes cache `node_modules/`. If dependencies change and installs fail, remove the volume: `docker volume rm harb_webapp_node_modules` (or similar), then restart.

## Handy Commands
```bash
foundryup                          # update Foundry toolchain
anvil --fork-url https://sepolia.base.org  # manual fork for diagnosing outside dev.sh

# inspect services while stack is running
curl http://localhost:8081/api/txn/status
curl -X POST http://localhost:8081/api/graphql \
  -d '{"query":"{ stats(id:\"0x01\"){kraikenTotalSupply}}"}'
cast call <POOL> "slot0()"         # inspect pool state
PONDER_NETWORK=BASE_SEPOLIA_LOCAL_FORK npm run dev  # focused Ponder debugging (inside services/ponder/)
```