# AGENTS.md

This file provides guidance to AI coding agents when working with code in this repository.

## Project Overview
Boxtime is a Cointime Economics framework implementation for the Ergo blockchain. It connects to an Ergo node to compute coinblocks created, destroyed, and stored, and optionally enriches data with ERG/USD prices from CoinGecko.

## Build & Run Commands
```bash
# Install in editable mode
pip install -e .

# Or with pixi
pixi install
```

## Architecture

The project uses a `src/` layout with the package at `src/boxtime/`.

### Clients (`src/boxtime/clients/`)
- `cointime_client.py` — `Cointime` class: main entry point. Accepts `node_url`, `node_api_key`, and optional `coingecko_api_key`. Provides coinblocks created/destroyed/stored metrics and price-enriched convenience methods.
- `ergo_node_client.py` — `ErgoNodeClient`: wraps the Ergo Node REST API (requires `ergo.node.extraIndex = true`). Methods for transactions, boxes, blocks, chain slices, emission, and balances.
- `coingecko_client.py` — `CoinGeckoClient`: wraps the CoinGecko API via `coingecko-sdk`. Provides current price, price history, and price-at-date for ERG.

### HTTP (`src/boxtime/http/`)
- `http.py` — shared `http_get` helper using `requests`. Returns parsed JSON or `None` on failure.

### Data Models (`src/boxtime/models/`)
- `node/` — Pydantic models for Ergo node entities: `Transaction`, `ErgoBox`, `BlockHeader`, `Asset`, `DataInput`, `SpendingProof`, `PowSolutions`, `EmissionInfo`
- `price/` — `PricePoint` and `PriceHistory` models for CoinGecko data
- `cointime/` — `CointimeDataPoint` model (height, timestamp, value, price) returned by convenience methods
- `helpers/` — `Balance` model (derived from unspent boxes)

### Key Domain Concepts
- **Box**: Ergo's UTXO model — outputs that can be spent as inputs in transactions
- **Coinblocks Created (CBC)**: circulating supply at a block height (in nanoERGs)
- **Coinblocks Destroyed (CBD)**: sum of `input.value × (height - inclusion_height)` for all inputs in a block
- **Coinblocks Stored (CBS)**: CBC − CBD

## Code Conventions
- API client methods return `Optional[Model]` or `Optional[List[Model]]` — `None` indicates failure
- Error handling uses `requests` exception types with logging; no exceptions are raised to the caller
- Models use `Field(alias="...")` to map camelCase API responses to snake_case Python attributes
- All public symbols are re-exported from `src/boxtime/__init__.py`
