Metadata-Version: 2.3
Name: boxtime
Version: 0.1.0
Summary: Cointime economics framework implementation for the Ergo blockchain.
Project-URL: Repository, https://github.com/4EYESConsulting/boxtime
Author-email: Luca D'Angelo <ldgaetano@protonmail.com>
License: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.10
Requires-Dist: coingecko-sdk
Requires-Dist: pydantic>=2
Requires-Dist: requests
Description-Content-Type: text/markdown

# boxtime

Cointime economics framework implementation for the Ergo blockchain.

## Description

Boxtime is a Python library that implements the [Cointime Economics](https://insights.glassnode.com/introducing-cointime-economics/) framework for Ergo. It connects to an Ergo node to compute coinblocks created, destroyed, and stored — and optionally enriches the data with ERG/USD prices from CoinGecko for plotting and analysis.

## Installation

```bash
pip install boxtime
```

## Prerequisites

- **Ergo Node** — a running node with the extra blockchain indexer enabled (`ergo.node.extraIndex = true`).
- **CoinGecko API key** *(optional)* — a free Demo API key from [coingecko.com/en/api](https://www.coingecko.com/en/api). Required only for price-related methods.

## Quickstart

### Basic cointime metrics

```python
from boxtime import Cointime

ct = Cointime(node_url="http://127.0.0.1:9053")

# Coinblocks created at a single height (= circulating supply in nanoERGs)
cbc = ct.coinblocks_created(500_000)

# Coinblocks destroyed at a single height
cbd = ct.coinblocks_destroyed(500_000)

# Coinblocks stored (CBC - CBD)
cbs = ct.coinblocks_stored(500_000)

# Totals over a range
total_cbc = ct.total_coinblocks_created(500_000, 500_100)
```

### Price-enriched data (for plotting)

Pass a CoinGecko API key to unlock price methods:

```python
ct = Cointime(
    node_url="http://127.0.0.1:9053",
    coingecko_api_key="CG-your-demo-key",
)

# Current ERG/USD spot price
price = ct.get_price()

# Price history between two block heights
history = ct.get_price_history(500_000, 510_000)

# Coinblocks created with matched price data — ready to plot
data_points = ct.get_coinblocks_created(500_000, 510_000)
for dp in data_points:
    print(dp.height, dp.timestamp, dp.value, dp.price)
```

Each `CointimeDataPoint` bundles `height`, `timestamp`, `value` (cointime metric in nanoERG-blocks), and `price` (ERG/USD). Only block timestamps that exactly match a CoinGecko price timestamp are included.

## API Overview

### `Cointime` — main entry point

**Primitive metrics** (single height):
- `coinblocks_created(height)` — circulating supply at height
- `coinblocks_destroyed(height)` — sum of `input.value × lifespan` for all inputs
- `coinblocks_stored(height)` — CBC − CBD

**Aggregate metrics** (height range, inclusive):
- `total_coinblocks_created(start_height, end_height)`
- `total_coinblocks_destroyed(start_height, end_height)`
- `total_coinblocks_stored(start_height, end_height)`

**Price methods** (require CoinGecko API key):
- `get_price()` — current ERG/USD spot price
- `get_price_history(start_height, end_height)` — `List[PricePoint]`

**Convenience methods** (require CoinGecko API key):
- `get_coinblocks_created(start_height, end_height)` — `List[CointimeDataPoint]`
- `get_coinblocks_destroyed(start_height, end_height)` — `List[CointimeDataPoint]`
- `get_coinblocks_stored(start_height, end_height)` — `List[CointimeDataPoint]`

### Underlying clients

For advanced use, the individual clients are also exported:

- `ErgoNodeClient(node_url, api_key)` — Ergo node REST API (transactions, boxes, blocks, emission, balances)
- `CoinGeckoClient(api_key)` — CoinGecko price data (current price, history, history by date)

```python
from boxtime import ErgoNodeClient

node = ErgoNodeClient("http://127.0.0.1:9053")
info = node.get_node_info()
tx = node.get_transaction("tx_id_here")
```

## License

This project is licensed under the [MIT License](LICENSE).
