boxtime 1.0.0

Cointime economics framework implementation for the Ergo blockchain.

boxtime

Cointime economics framework implementation for the Ergo blockchain.

Description

Boxtime is a Python library that implements the 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

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. Required only for price-related methods.

Quickstart

Basic cointime metrics

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:

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)

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.