Skip to main content

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)

Source distribution for crunch-node 0.1.0
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)

Table of built distributions (wheels) for crunch-node 0.1.0
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page