# 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 reads pre-computed coinblocks created, destroyed, and stored — plus daily ERG/USD prices — from a Postgres database (Supabase-hosted by default).

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

# Run tests
pip install -e ".[test]"
pytest
```

## 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. Supports two backends:
  - **Default (Supabase)**: `Cointime()` — uses `supabase-py` (PostgREST) with an embedded publishable API key.
  - **Custom (asyncpg)**: `Cointime(database_url="postgresql://...")` — direct Postgres connection.

### Data Models (`src/boxtime/models/`)
- `cointime/` — `CointimeDataPoint` model (height, timestamp, value, price) returned by convenience methods

### Key Domain Concepts
- **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

### Database Tables
- `cointime` — pre-computed cointime data per block height (`height`, `timestamp`, `cbc`, `cbd`, `cbs`)
- `erg_prices` — daily ERG/USD prices (`date`, `price_usd`)

## Code Conventions
- All public methods are synchronous; asyncpg internals use `_run_sync` (ThreadPoolExecutor + asyncio.run)
- Methods return `Optional[T]` — `None` indicates no data found
- Backend is lazy-initialized on first use (Supabase client or asyncpg pool with SSL)
- Supabase path uses PostgREST query builder; asyncpg path uses raw SQL
- All public symbols are re-exported from `src/boxtime/__init__.py`
