# Local Development Guide

Run the entire Cortex agentic commerce protocol stack locally in under 5 minutes.

## Prerequisites

- [Docker](https://docs.docker.com/get-docker/) (for Anvil + Postgres)
- [Foundry](https://book.getfoundry.sh/getting-started/installation) (`forge`, `cast`, `anvil`)
- [Node.js](https://nodejs.org/) >= 18
- PostgreSQL client tools (`psql`, `pg_isready`) — installed with Postgres or Homebrew

## Quick Start (one command)

```bash
make install   # first time only — installs all deps
make e2e       # starts infra, deploys, launches services, runs demo
```

## Step-by-Step

### 1. Install Dependencies

```bash
make install
```

### 2. Start Infrastructure

Starts Anvil (local EVM on port 8545) and Postgres (port 5433 by default) via Docker Compose.

```bash
make up
```

If port 5433 is in use, choose another host port and pass the matching database URL through the rest of the flow:

```bash
POSTGRES_PORT=55433 DATABASE_URL=postgresql://ai_chain:ai_chain@localhost:55433/ai_chain make up
DATABASE_URL=postgresql://ai_chain:ai_chain@localhost:55433/ai_chain make deploy
DATABASE_URL=postgresql://ai_chain:ai_chain@localhost:55433/ai_chain API_PORT=3012 make services
API_PORT=3012 make demo
```

### 3. Deploy Contracts

Deploys AgentRegistry, IntentBook, PolicyModule, AttestationRegistry, SolverRegistry, AttestorRegistry, and CommerceRegistry to the local Anvil chain. Writes contract addresses and well-known Anvil keys to `ops/.env.deployed`.

```bash
make deploy
```

### 4. Start Services

Starts the indexer, solver, and API as background processes.

```bash
make services
```

Services:
- **Indexer** — polls Anvil for contract events, writes to Postgres
- **Solver** — watches for open intents, simulates and fills them
- **API** — REST server on `http://localhost:3001`

Logs are written to `ops/indexer.log`, `ops/solver.log`, `ops/api.log`.

### 5. Run the Demo

Executes the end-to-end demo scenario:

```bash
make demo
```

The demo:
1. Registers an agent identity
2. Registers solver, attestor, merchant, service, and facilitator records
3. Sets spend limit, target allowlist, and signed payment policies
4. Submits an EIP-712 signed swap intent
5. Waits for the solver to fill the intent
6. Commits a commerce quote, records a receipt, and resolves a dispute
7. Queries API endpoints, including commerce analytics, and prints results

### 6. Tear Down

```bash
make down    # stop services + infra
make clean   # also remove volumes and generated files
```

## Useful Commands

| Command | Description |
|---------|-------------|
| `make up` | Start Anvil + Postgres |
| `make deploy` | Deploy contracts |
| `make services` | Start indexer/solver/API |
| `make demo` | Run end-to-end demo |
| `make down` | Stop everything |
| `make clean` | Full cleanup |
| `make logs` | Tail all service logs |
| `make e2e` | Full end-to-end in one shot |

## Ports

| Service | Port |
|---------|------|
| Anvil (RPC) | 8545 |
| Postgres | 5433 |
| REST API | 3001 |
| Web dashboard | 3000 |

## Environment

All services read from `ops/.env.deployed`, which is auto-generated by `make deploy`. To customize, edit the values after deployment or set env vars before starting services.

## Troubleshooting

**Anvil not starting:** Check if port 8545 is in use (`lsof -i :8545`).

**Postgres connection refused:** Ensure Docker is running and port 5433 is free.

**Solver not filling intents:** Check `ops/solver.log`. The solver needs a valid `INTENT_BOOK_ADDRESS`.

**API returns empty results:** The indexer may need a few seconds to catch up. Check `ops/indexer.log`.