AGENTS.md · Chia-Network/chia-blockchain

Sections

1. Dev Setup
2. Testing
3. Running the Simulator
4. Linting and Type Checking
5. Repo-Specific Traps
6. Load-Bearing Directories
7. Contribution Workflow
8. Worked Example: Adding an RPC Endpoint
9. Definition of Done
10. Chia Domain Primer
11. Security / Anti-Goals

First lines (shown under the repo's Apache-2.0 license)

# Chia Context

This repo ships curated architectural context for coding agents.

Start with `.cursor/context/INDEX.md` for routing, critical invariants,
cross-module coupling, architecture overview, and the module table.

For focused work, read the matching context doc under `.cursor/context/` before
broad source exploration. For review or audit work, also check
`.cursor/context/global-invariants.md`.

Cursor behavior is guided by `.cursor/rules/`, including context routing,
test harness selection, and repository tooling guardrails. Bugbot review
guidance lives in `.cursor/BUGBOT.md`.

---

> **Modifying this repo?** Read on — dev setup, test commands, and repo-specific traps below.
>
> **Building on Chia (not modifying this repo)?** See the [Agent Developer Reference](https://github.com/Chia-Network/chia-for-agents).
>
> **Stuck on an error from push_tx?** See the [Error Catalogue](https://github.com/Chia-Network/chia-for-agents/blob/main/REFERENCE.md#error-catalogue).

## Dev Setup

```bash
sh install.sh -d       # Creates venv, installs all deps including dev
. ./activate           # Activate the venv
```

**Always use `tools/py` and `tools/pytest`** — never bare `python`, `python3`, `pip`, or `pytest`. This is enforced by `.cursor/rules/use-venv-wrappers.mdc`.

## Testing

**Never run the full test suite locally** — it takes hours and requires pre-generated plots. Run only the directory relevant to your change:

```bash
tools/pytest chia/_tests/<relevant_directory>/ -v -n auto
```

Tests mirror the source layout:

| You changed                           | Run tests in                                                                                                  |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `chia/full_node/`                     | `chia/_tests/core/full_node/`                                                                                 |
| `chia/full_node/full_node_rpc_api.py` | `chia/_tests/core/test_full_node_rpc.py` (specific RPC handler test file, not the broader `full_node/` suite) |
| `chia/wallet/`                        | `chia/_tests/wallet/`                                                                                         |
| `chia/consensus/`                     | `chia/_tests/blockchain/`                                                                                     |
| `chia/rpc/`                           | `chia/_tests/rpc/`                                                                                            |
| `chia/data_layer/`                    | `chia/_tests/core/data_layer/`                                                                                |
| `chia/server/`                        | `chia/_tests/core/server/`                                                                                    |
| `chia/cmds/`                          | `chia/_tests/cmds/`                                                                                           |
| `chia/simulator/`                     | `chia/_tests/simulation/`                                                                                     |

Where to put a new test: tests live in `chia/_tests/`, not a top-level `tests/` directory. Note that `full_node` and `data_layer` tests nest under `chia/_tests/core/` — check the existing tree before creating a new file.

## Running the Simulator

```bash
sh install.sh -d && . ./activate
chia dev sim create -d                # Creates a local testnet (non-interactive)
chia dev sim farm                  # Farm a block
chia dev sim farm --blocks 3       # Farm multiple blocks
```

The simulator uses the same mTLS infrastructure as a real node. See `chia/simulator/` and `.cursor/context/simulator.md` for details.

## Linting and Type Checking

```bash
ruff format && ruff check --fix    # Format + lint (must pass)
tools/py -m mypy .                 # Type checking (uses mypy.ini.template config)
```

**mypy config:** This repo uses `mypy.ini.template` with exclusion lists (`mypy-exclusions.txt`, `mypy-strict-bytes-exclusions.txt`). If you add a new module, you may need to add it to the exclusion list until it's fully typed. Run `tools/py manage-mypy.py` to regenerate `mypy.ini` from the template.

## Repo-Specific Traps

1. **`chia_rs` boundary.** Many types (`CoinSpend`, `SpendBundle`, `Coin`, `CoinRecord`, `BlockRecord`, etc.) have moved to `chia_rs` (Rust). `chia/types/` still has Python wrappers and additional modules. Check imports in nearby code before adding new ones.

2. **`make_spend()`, not `CoinSpend()`.** Use `from chia.types.coin_spend import make_spend` to create coin spends. It handles `Program` → `SerializedProgram` conversion correctly. Don't construct `CoinSpend` directly.

3. **Amount `0` = empty bytes.** In CLVM, the integer `0` encodes to zero-length bytes, NOT `b'\x00'`. This affects coin ID computation. See `.cursor/context/types.md`.

4. **Protocol message hashes.** Protocol messages have computed hashes. If you change a message schema in `chia/protocols/`, you must regenerate hashes. CI will catch this.

5. **New modules need mypy exclusion.** Add your new module to `mypy-exclusions.txt` if it's not fully typed yet, otherwise CI mypy will fail.

6. **Generated files.** Some files are auto-generated — do not hand-edit. Check for generation scripts or comments at the top.

7. **Commits must be signed.** Branch protection enforces signed commits. See `CONTRIBUTING.md` for setup instructions.

8. **`poetry lock`, not `poetry lock --no-update`.** The `--no-update` flag was removed in Poetry 2.0. Just run `poetry lock`.

## Load-Bearing Directories

Not all directories carry the same risk:

| Directory    | Risk        | Notes                                                  |
| ------------ | ----------- | ------------------------------------------------------ |
| `consensus/` | 🔴 Critical | Changes require a CHIP proposal + hard fork schedule   |
| `types/`     | 🔴 High     | Serialization changes can break the network            |
| `protocols/` | 🔴 High     | Message changes require hash regeneration              |
| `full_node/` | 🟡 Medium   | Core node logic, mempool, block validation             |
| `wallet/`    | 🟡 Medium   | Complex state management, many sub-wallets             |
| `rpc/`       | 🟡 Medium   | API surface — breaking changes affect all consumers    |
| `plotters/`  | 🟢 Low      | External plotter integrations                          |
| `cmds/`      | 🟢 Low      | CLI wrappers                                           |
| `util/`      | 🟢 Low      | Utility functions (but `db_wrapper.py` is higher risk) |

## Contribution Workflow

| Who                   | Branch from                    | PR target      |
| --------------------- | ------------------------------ | -------------- |
| External contributors | Fork `main`                    | PR to `main`   |
| Chia org members      | `main`                         | PR to `main`   |
| **Emergency fixes**   | **`latest`** (current release) | PR to `latest` |

Emergency fixes branch from `latest`, not `main`. This is the most important row in this table.

## Worked Example: Adding an RPC Endpoint

1. Add the handler in `chia/full_node/full_node_rpc_api.py`:

   ```python
   async def my_new_endpoint(self, request: dict[str, Any]) -> EndpointResult:
       # Implementation
       return {"success": True, "data": result}
   ```

2. Add the typed client method in `chia/full_node/full_node_rpc_client.py`:

   ```python
   async def my_new_endpoint(self, param: str) -> dict[str, Any]:
       return await self.fetch("my_new_endpoint", {"param": param})
   ```

3. Add tests in `chia/_tests/core/test_full_node_rpc.py`

4. Run: `tools/pytest chia/_tests/core/ -v -n auto -k test_my_new_endpoint`

## Definition of Done

1. `ruff format && ruff check --fix` — no warnings
2. `tools/py -m mypy .` — clean (or new module added to exclusions)
3. `tools/pytest chia/_tests/<relevant_directory>/ -v -n auto` — all pass
4. Commit is signed
5. PR targets the correct branch (`main` or `latest`)

## Chia Domain Primer

Agents modifying this codebase benefit from understanding Chia's core concepts. A full domain primer — coinset model, CLVM, spend bundles, condition opcodes, and common pitfalls — is maintained at [`.cursor/context/domain-primer.md`](.cursor/context/domain-primer.md) (if present) or in the [Agent Developer Reference](https://github.com/Chia-Network/chia-for-agents/blob/main/resources/coin-model.md).

Key concepts in brief:

- **Coin model (UTXO).** Each coin = parent_coin_info + puzzle_hash + amount. Coin ID = SHA256 of those three fields.
- **Puzzles and solutions.** Coins are locked by CLVM programs. Spending reveals the puzzle and provides a solution that produces conditions (CREATE_COIN, AGG_SIG_ME, etc.).
- **Spend bundles.** A transaction = list of CoinSpends + one aggregated BLS12-381 signature.
- **Mempool.** Transactions enter the mempool before block inclusion. Fee priority is cost-based.
- **35 condition opcodes.** Canonical source: `chia/types/condition_opcodes.py`.