crunch-node
Runtime engine for Crunch coordinator nodes. Published as crunch-node on PyPI, imported as coordinator_node.
pip install crunch-node
Architecture
Pipeline
Feed → Input → Prediction → Score → Snapshot → Checkpoint → On-chain
Workers:
| Worker | Purpose |
|---|---|
feed-data-worker |
Ingests feed data (Pyth, Binance, etc.) via WebSocket + backfill |
predict-worker |
Event-driven: gets data → ticks models → collects predictions |
score-worker |
Resolves actuals → scores predictions → writes snapshots → rebuilds leaderboard |
checkpoint-worker |
Aggregates snapshots → builds EmissionCheckpoint for on-chain submission |
report-worker |
FastAPI: leaderboard, predictions, feeds, snapshots, checkpoints, emissions |
Contract
All type shapes and behavior are defined in a single CrunchContract:
from coordinator_node.contracts import CrunchContract
class CrunchContract(BaseModel):
raw_input_type: type[BaseModel] = RawInput
output_type: type[BaseModel] = InferenceOutput
score_type: type[BaseModel] = ScoreResult
scope: PredictionScope = PredictionScope()
aggregation: Aggregation = Aggregation()
# Callables
resolve_ground_truth: Callable = default_resolve_ground_truth
aggregate_snapshot: Callable = default_aggregate_snapshot
build_emission: Callable = default_build_emission
Feed Dimensions
| Dimension | Example | Env var |
|---|---|---|
source |
pyth, binance | FEED_SOURCE |
subject |
BTC, ETH | FEED_SUBJECTS |
kind |
tick, candle | FEED_KIND |
granularity |
1s, 1m | FEED_GRANULARITY |
Status Lifecycles
Input: RECEIVED → RESOLVED
Prediction: PENDING → SCORED / FAILED / ABSENT
Checkpoint: PENDING → SUBMITTED → CLAIMABLE → PAID
Emission Checkpoints
Checkpoints produce EmissionCheckpoint matching the on-chain protocol:
{
"crunch": "<pubkey>",
"cruncher_rewards": [{"cruncher_index": 0, "reward_pct": 350_000_000}, ...],
"compute_provider_rewards": [...],
"data_provider_rewards": [...],
}
reward_pct uses frac64 (1,000,000,000 = 100%).
Report API
| Endpoint | Description |
|---|---|
GET /reports/leaderboard |
Current leaderboard |
GET /reports/models |
Registered models |
GET /reports/predictions |
Prediction history |
GET /reports/feeds |
Active feed subscriptions |
GET /reports/snapshots |
Per-model period summaries |
GET /reports/checkpoints |
Checkpoint history |
GET /reports/checkpoints/{id}/emission |
Raw emission (frac64) |
GET /reports/checkpoints/{id}/emission/cli-format |
CLI JSON format |
GET /reports/emissions/latest |
Latest emission |
POST /reports/checkpoints/{id}/confirm |
Record tx_hash |
PATCH /reports/checkpoints/{id}/status |
Advance status |
Scaffolding
Use crunch-cli init-workspace <name> to create a new competition workspace from the base/ template.
Development
uv run pytest tests/ -q
Metadata
Release files for crunch-node 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| crunch_node-0.1.0.tar.gz | 177.7 kB | Without provenance | Details for crunch_node-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| crunch_node-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for crunch_node-0.1.0-py3-none-any.whl |
Total release size: 233.3 kB
Release files / crunch_node-0.1.0.tar.gz
| Download URL | crunch_node-0.1.0.tar.gz |
|---|---|
| Size | 177.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9f0f978aa795663116c68b6df9d7c6d4aab2fd326cb5f4f9c7ad87f6e46c14f7
|
|
BLAKE2b-256 checksum How to use checksums |
f35e8ed05ad3da237637056222c34706412a2b20a6fec2f71a2136bb6c2e0604
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.2
|
Release files / crunch_node-0.1.0-py3-none-any.whl
| Download URL | crunch_node-0.1.0-py3-none-any.whl |
|---|---|
| Size | 55.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d1ed6a3369f144601d652880cc7ecda5cbed53a1842d4fe40b53fbd6c7499817
|
|
BLAKE2b-256 checksum How to use checksums |
c73ee11728baa22a23cd5fc26545f5c1b26d7bec5e5af8dc9f22f594535cb056
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.2
|
Security for crunch-node 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.