coordinator-node 0.1.0__tar.gz

coordinator_node-0.1.0/.dev.env

@@ -0,0 +1,28 @@
+POSTGRES_USER=starter
+POSTGRES_PASSWORD=starter
+POSTGRES_DB=starter
+POSTGRES_HOST=localhost
+POSTGRES_PORT=5432
+MODEL_RUNNER_NODE_HOST=localhost
+MODEL_RUNNER_NODE_PORT=9091
+MODEL_RUNNER_TIMEOUT_SECONDS=60
+PROJECT_DIR=.
+
+# During development, workers might be launched from the IDE. This allows receiving the model runner IP as localhost.
+MODEL_ORCHESTRATOR_NETWORK=null
+
+# Starter profile (BTC + Pyth)
+CRUNCH_ID=starter-challenge
+MODEL_BASE_CLASSNAME=tracker.TrackerBase
+CHECKPOINT_INTERVAL_SECONDS=60
+
+INFERENCE_INPUT_BUILDER=node_template.extensions.default_callables:default_build_inference_input
+INFERENCE_OUTPUT_VALIDATOR=node_template.plugins.pyth_updown_btc:validate_probability_up_output
+RAW_INPUT_PROVIDER=node_template.plugins.pyth_updown_btc:build_raw_input_from_pyth
+SCORING_FUNCTION=node_template.plugins.pyth_updown_btc:score_brier_probability_up
+GROUND_TRUTH_RESOLVER=node_template.plugins.pyth_updown_btc:resolve_ground_truth_from_pyth
+MODEL_SCORE_AGGREGATOR=node_template.extensions.default_callables:default_aggregate_model_scores
+LEADERBOARD_RANKER=node_template.extensions.default_callables:default_rank_leaderboard
+
+PYTH_HERMES_URL=https://hermes.pyth.network
+PYTH_TIMEOUT_SECONDS=5

coordinator_node-0.1.0/.dockerignore

@@ -0,0 +1,2 @@
+.venv
+deployment

coordinator_node-0.1.0/.gitignore

@@ -0,0 +1,18 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+.idea
+
+data/
+
+# Local challenge implementations/workspaces
+crunch-implementations/
+*.DS_Store

coordinator_node-0.1.0/.local.env

@@ -0,0 +1,43 @@
+# ── Postgres ──────────────────────────────────────────────
+POSTGRES_USER=starter
+POSTGRES_PASSWORD=starter
+POSTGRES_DB=starter
+POSTGRES_HOST=postgres
+POSTGRES_PORT=5432
+
+# ── Competition identity ─────────────────────────────────
+CRUNCH_ID=starter-challenge
+# CRUNCH_PUBKEY=                        # on-chain crunch address (for emissions)
+
+# ── Model runner ─────────────────────────────────────────
+MODEL_RUNNER_NODE_HOST=model-orchestrator
+MODEL_RUNNER_NODE_PORT=9091
+MODEL_RUNNER_TIMEOUT_SECONDS=60
+MODEL_BASE_CLASSNAME=tracker.TrackerBase
+
+# ── Feed (data source) ──────────────────────────────────
+FEED_SOURCE=pyth
+FEED_SUBJECTS=BTC
+FEED_KIND=tick
+FEED_GRANULARITY=1s
+FEED_POLL_SECONDS=5
+FEED_BACKFILL_MINUTES=180
+FEED_CANDLES_WINDOW=120
+FEED_RECORD_TTL_DAYS=90
+# FEED_RETENTION_CHECK_SECONDS=3600
+
+# ── Scoring ──────────────────────────────────────────────
+SCORING_FUNCTION=coordinator_node.extensions.default_callables:default_score_prediction
+CHECKPOINT_INTERVAL_SECONDS=60
+
+# ── Checkpoint / Emissions ───────────────────────────────
+# CHECKPOINT_INTERVAL_SECONDS=604800    # weekly (default)
+# COMPUTE_PROVIDER_PUBKEY=              # wallet pubkey for compute provider rewards
+# DATA_PROVIDER_PUBKEY=                 # wallet pubkey for data provider rewards
+
+# ── Pyth-specific ────────────────────────────────────────
+PYTH_HERMES_URL=https://hermes.pyth.network
+PYTH_TIMEOUT_SECONDS=5
+
+# ── Scheduled predictions (optional) ─────────────────────
+# SCHEDULED_PREDICTION_CONFIGS_PATH=config/scheduled_predictions.json

coordinator_node-0.1.0/.production.env

@@ -0,0 +1,39 @@
+# ── Postgres ──────────────────────────────────────────────
+POSTGRES_USER=<CHANGE_ME>
+POSTGRES_PASSWORD=<CHANGE_ME>
+POSTGRES_DB=<CHANGE_ME>
+POSTGRES_HOST=postgres
+POSTGRES_PORT=5432
+# READONLY_USER_PASSWORD=<CHANGE_ME>
+
+# ── Competition identity ─────────────────────────────────
+CRUNCH_ID=<CHANGE_ME>
+CRUNCH_PUBKEY=<CHANGE_ME>
+
+# ── Model runner ─────────────────────────────────────────
+MODEL_RUNNER_NODE_HOST=model-orchestrator
+MODEL_RUNNER_NODE_PORT=9091
+MODEL_RUNNER_TIMEOUT_SECONDS=60
+MODEL_BASE_CLASSNAME=tracker.TrackerBase
+
+# ── Feed (data source) ──────────────────────────────────
+FEED_SOURCE=pyth
+FEED_SUBJECTS=BTC
+FEED_KIND=tick
+FEED_GRANULARITY=1s
+FEED_POLL_SECONDS=5
+FEED_BACKFILL_MINUTES=180
+FEED_CANDLES_WINDOW=120
+FEED_RECORD_TTL_DAYS=90
+
+# ── Scoring ──────────────────────────────────────────────
+SCORING_FUNCTION=coordinator_node.extensions.default_callables:default_score_prediction
+
+# ── Checkpoint / Emissions ───────────────────────────────
+CHECKPOINT_INTERVAL_SECONDS=604800
+# COMPUTE_PROVIDER_PUBKEY=<CHANGE_ME>
+# DATA_PROVIDER_PUBKEY=<CHANGE_ME>
+
+# ── Pyth-specific ────────────────────────────────────────
+PYTH_HERMES_URL=https://hermes.pyth.network
+PYTH_TIMEOUT_SECONDS=5

coordinator_node-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

coordinator_node-0.1.0/Dockerfile

@@ -0,0 +1,16 @@
+FROM python:3.12-slim
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    libpq5 \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+COPY pyproject.toml ./
+RUN uv sync --no-install-project
+
+ENV VIRTUAL_ENV=/app/.venv
+ENV PATH="$VIRTUAL_ENV/bin:$PATH"
+
+COPY coordinator_node ./coordinator_node

coordinator_node-0.1.0/Makefile

@@ -0,0 +1,15 @@
+COMPOSE := docker compose -f docker-compose.yml --env-file .local.env
+
+.PHONY: deploy down logs test
+
+deploy:
+	$(COMPOSE) up -d --build
+
+down:
+	$(COMPOSE) down
+
+logs:
+	$(COMPOSE) logs -f
+
+test:
+	uv run python -m pytest tests/ -x -q

coordinator_node-0.1.0/PKG-INFO

@@ -0,0 +1,120 @@
+Metadata-Version: 2.4
+Name: coordinator-node
+Version: 0.1.0
+Summary: Runtime engine for Crunch coordinator nodes
+Project-URL: Homepage, https://github.com/crunchdao/coordinator-node-starter
+Project-URL: Repository, https://github.com/crunchdao/coordinator-node-starter
+License-Expression: MIT
+Requires-Python: >=3.12
+Requires-Dist: fastapi>=0.100.0
+Requires-Dist: model-runner-client>=0.10.0
+Requires-Dist: psycopg2-binary>=2.9
+Requires-Dist: python-binance>=1.0
+Requires-Dist: requests>=2.28
+Requires-Dist: sqlmodel>=0.0.14
+Requires-Dist: uvicorn>=0.20
+Description-Content-Type: text/markdown
+
+# crunch-node
+
+Runtime engine for Crunch coordinator nodes. Published as `crunch-node` on PyPI, imported as `coordinator_node`.
+
+```bash
+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`:
+
+```python
+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:
+
+```python
+{
+    "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
+
+```bash
+uv run pytest tests/ -q
+```

coordinator_node-0.1.0/README.md

@@ -0,0 +1,103 @@
+# crunch-node
+
+Runtime engine for Crunch coordinator nodes. Published as `crunch-node` on PyPI, imported as `coordinator_node`.
+
+```bash
+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`:
+
+```python
+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:
+
+```python
+{
+    "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
+
+```bash
+uv run pytest tests/ -q
+```

coordinator_node-0.1.0/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: coordinator-node-starter
+description: Use when creating or customizing a Crunch coordinator node from this template repository and defining competition contracts before implementation.
+---
+
+# Coordinator Node Starter
+
+Use this repository as the **base template source** for new Crunch coordinator nodes.
+
+- This repo provides: `coordinator_core/` + `node_template/`
+- You create: `crunch-<name>` (public package) and `crunch-node-<name>` (private runnable node)
+- The coordinator agent should guide users through required design decisions before code changes
+
+---
+
+## Template Usage Model (Required)
+
+When the user wants a new Crunch, use the CLI-first scaffold flow:
+
+1. Create an upfront answers file (JSON/YAML) for deterministic setup decisions.
+2. Run preflight to halt on busy local ports.
+3. Run `coordinator init` (with `--answers` and optional `--spec`).
+4. Implement challenge logic in generated `crunch-<name>`.
+5. Run generated node verification flow in `crunch-node-<name>`.
+
+Reference: `docs/flow.md`.
+
+This repository is the **template and contract baseline**, not the long-term identity of a specific Crunch.
+
+---
+
+## Required Crunch Definition (Must Be Explicit)
+
+Before implementation, the agent must help the user define and validate these six points:
+
+1. **Define Model Interface**
+2. **Define inference input**
+3. **Define inference output**
+4. **Define scoring function**
+5. **Define ModelScore**
+6. **Define checkpoint interval**
+
+If any point is missing, stop implementation and ask follow-up questions.
+
+---
+
+## Competition Design Checklist (Conversation Flow)
+
+### 0. Project Name (ask first)
+Ask:
+> What should we call this Crunch? (used for `crunch-<name>` and `crunch-node-<name>`)
+
+### 1. Define Model Interface
+Ask:
+> What methods must participant models implement, and what are runtime constraints (timeout, state, allowed libs)?
+
+Output required:
+- base class contract in `crunch-<name>`
+- model runner `base_classname` to configure in node runtime
+
+### 2. Define inference input
+Ask:
+> What raw data enters the system, and what transformed payload is sent to models?
+
+Output required:
+- input builder callable signature: `build_input(raw_input) -> dict`
+- optional schema artifact in `crunch-<name>`
+
+### 3. Define inference output
+Ask:
+> What should `predict` return (shape, length, validation rules, failure rules)?
+
+Output required:
+- output contract in `crunch-<name>`
+- validator callable signature: `validate_output(inference_output) -> dict`
+
+### 4. Define scoring function
+Ask:
+> How are predictions scored against ground truth, and how are invalid outputs handled?
+
+Output required:
+- scoring callable signature: `score_prediction(prediction, ground_truth) -> {value, success, failed_reason}`
+- callable path in node config: `SCORING_FUNCTION=...`
+
+### 5. Define ModelScore
+Ask:
+> How should per-model performance be aggregated and represented?
+
+Output required:
+- model-score aggregator callable signature: `aggregate_model_scores(scored_predictions, models) -> list[dict]`
+- JSON-serializable score payload strategy (`score_payload_jsonb`)
+
+### 6. Define checkpoint interval
+Ask:
+> What scoring/predict loop interval do you want for this Crunch node?
+
+Output required:
+- `CHECKPOINT_INTERVAL_SECONDS` value for `crunch-node-<name>`
+- rationale for cadence vs cost/latency
+
+---
+
+## Where To Implement In This Structure
+
+### Stable core contracts
+- `coordinator_core/infrastructure/db/db_tables.py`
+- `coordinator_core/entities/*`
+- `coordinator_core/services/interfaces/*`
+
+### Default runtime template
+- `node_template/workers/*`
+- `node_template/services/*`
+- `node_template/infrastructure/db/*`
+- `node_template/config/extensions.py`
+- `node_template/config/runtime.py`
+- `node_template/extensions/default_callables.py`
+
+Current operational defaults in this template:
+- `predict-worker` and `score-worker` configure INFO logging and emit lifecycle/idle logs.
+- `ScoreService` attempts repository rollbacks on loop exceptions (where `rollback()` is available).
+
+### Crunch-specific extension points
+Set callable paths in env/config:
+- `INFERENCE_INPUT_BUILDER`
+- `INFERENCE_OUTPUT_VALIDATOR`
+- `SCORING_FUNCTION`
+- `MODEL_SCORE_AGGREGATOR`
+- `LEADERBOARD_RANKER`
+- `CHECKPOINT_INTERVAL_SECONDS`
+
+---
+
+## Post-Deployment Verification (Mandatory)
+
+After any change, run (from generated `crunch-node-<name>`):
+
+```bash
+# 1) Optional preflight from repo root
+coordinator preflight --ports 3000,5432,8000,9091
+
+# 2) Rebuild + start
+make deploy
+
+# 3) E2E verification
+make verify-e2e
+
+# 4) Structured runtime log capture for analysis
+make logs-capture
+
+# 5) Basic API checks
+curl -s http://localhost:8000/healthz
+curl -s http://localhost:8000/reports/models
+curl -s http://localhost:8000/reports/leaderboard
+```
+
+Artifacts to inspect:
+- `RUNBOOK.md` (generated in node workspace)
+- `runtime-services.jsonl` (from `make logs-capture`)
+- `process-log.jsonl` (generated in workspace root)
+
+Do not declare completion if verification fails.
+
+---
+
+## Sub-skills
+
+Use these focused skills when needed:
+
+- `coordinator-data-sources` → customize data feeds / inference input sources
+- `coordinator-prediction-format` → customize inference input/output contracts
+- `coordinator-scoring` → customize scoring + ModelScore aggregation
+- `coordinator-leaderboard-reports` → customize ranking and report endpoints
+
+(These skill files remain at their existing repository paths for compatibility with the agent harness.)

coordinator_node-0.1.0/base/Makefile

@@ -0,0 +1,17 @@
+# Workspace-level convenience — proxies to node/
+.PHONY: deploy down logs verify-e2e check-models
+
+deploy:
+	cd node && make deploy
+
+down:
+	cd node && make down
+
+logs:
+	cd node && make logs
+
+verify-e2e:
+	cd node && make verify-e2e
+
+check-models:
+	cd node && make check-models

coordinator_node-0.1.0/base/README.md

@@ -0,0 +1,14 @@
+# starter-challenge
+
+Coordinator workspace. Run from `node/`:
+
+```bash
+cd node
+make deploy
+make verify-e2e
+```
+
+## Structure
+
+- `node/` — competition infrastructure (docker-compose, config, scripts)
+- `challenge/` — participant-facing package (tracker, scoring, examples)

coordinator_node-0.1.0/base/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: starter-challenge-workspace
+summary: Agent runbook for this generated Crunch workspace.
+---
+
+# starter-challenge workspace skill
+
+## Fast path (from workspace root)
+
+```bash
+cd node
+make deploy
+make verify-e2e
+make logs-capture
+```
+
+## Where logs and diagnostics live
+
+- Live service logs: `cd node && make logs`
+- Captured runtime logs: `node/runtime-services.jsonl`
+- Lifecycle audit: `process-log.jsonl`
+- Additional troubleshooting: `node/RUNBOOK.md`
+
+## Where to edit code
+
+- **Challenge behavior** (tracker, scoring, examples):
+  `challenge/starter_challenge/`
+- **Runtime contract** (types, callables, emission config):
+  `node/runtime_definitions/contracts.py`
+- **Node config** (.env, deployment, schedules):
+  `node/`
+
+## Validation after changes
+
+```bash
+cd node
+make verify-e2e
+```

coordinator_node-0.1.0/base/challenge/README.md

@@ -0,0 +1,17 @@
+# challenge
+
+Public challenge package.
+
+Primary package: `starter_challenge`
+
+Implement participant-facing files in:
+
+- `tracker.py`
+- `scoring.py`
+- `examples/mean_reversion_tracker.py`
+- `examples/trend_following_tracker.py`
+- `examples/volatility_regime_tracker.py`
+
+Node-private runtime callables live in:
+
+- `../node/runtime_definitions/`

coordinator_node-0.1.0/base/challenge/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: starter-challenge-challenge
+summary: Agent instructions for implementing challenge logic.
+---
+
+# Challenge skill - challenge
+
+## Primary implementation files
+
+- `starter_challenge/tracker.py` — model interface (participants implement this)
+- `starter_challenge/scoring.py` — scoring function for local self-eval
+- `starter_challenge/examples/` — quickstarter implementations
+
+## Runtime contract (node-private)
+
+- `../node/runtime_definitions/contracts.py` — CrunchContract defining types, scoring, emission
+
+## Development guidance
+
+- Keep participant-facing challenge logic in this package.
+- Keep runtime contracts and deployment config in `../node/`.
+- The scoring function in `scoring.py` is used for local self-eval.
+  The runtime scoring callable is configured in `contracts.py`.
+
+## Validate from node workspace
+
+```bash
+cd ../node
+make verify-e2e
+```