HyperMine

HyperMine is an open-source Bitcoin mining research and control-plane platform for studying hashing performance, telemetry, rollout safety, and miner integration workflows.

Honest disclaimer

This is a research platform. CPU mining is not economically viable. This project exists to study and understand Bitcoin mining mechanics, not to generate profit.

What HyperMine does

HyperMine is designed as a modular research environment for exploring how Bitcoin mining systems behave in practice. It includes:

• CPU hashing benchmarks for naive and midstate-reuse paths
• Revenue and profitability estimation helpers
• Telemetry loading, replay, validation, and before/after comparison
• Policy simulation and dry-run control logic
• Rollout safety primitives such as canary apply, rollback, health gates, and preflight checks
• Miner onboarding and handshake discovery flows
• Vendor adapter abstractions for Antminer, WhatsMiner, and safe null adapters
• Signed verified profile workflow for payload overrides
• Persistence and audit logging for proposals, handshakes, and apply actions
• FastAPI endpoints for research, inspection, and control-plane orchestration

Architecture overview

At a high level the repository is organized around the following runtime layers:

• src/hypermine/hash_benchmark.py CPU hash benchmark engine for naive and midstate strategies
• src/hypermine/header_mutation_benchmark.py header mutation and Merkle-path benchmark helpers
• src/hypermine/economics.py expected-value BTC/USD output estimation
• src/hypermine/reporting/ interval and daily profitability reporting from CSV telemetry and market data
• src/hypermine/telemetry.py telemetry event schema, replay, and aggregate metrics
• src/hypermine/telemetry_comparison.py before/after telemetry window comparison for rollout analysis
• src/hypermine/policy/ policy models, rules, simulation, and dry-run proposal helpers
• src/hypermine/rollout.py staged rollout safety checks, telemetry validation, and health gates
• src/hypermine/adapters/ vendor abstractions, payload catalogs, and verified override support
• src/hypermine/inventory.py inventory loading and adapter factory selection
• src/hypermine/onboarding.py onboarding confidence scoring, command matrix generation, drift checks, and readiness checklists
• src/hypermine/approval.py signed approval tokens for live control actions
• src/hypermine/verified_profiles.py signed verified profile workflow for payload overrides
• src/hypermine/persistence.py proposal, handshake, and apply audit persistence backends
• src/hypermine/api/ FastAPI schemas, auth, service layer, and API app factory
• scripts/ CLI wrappers for benchmarks, API launch, simulation, reporting, and approval-token generation
• benchmarks/ manifests, templates, sample request bodies, and recorded benchmark outputs
• docs/ public English documentation, with historical internal planning material preserved under docs/internal/

Repository layout

src/hypermine/          Core package
scripts/                CLI entry points
benchmarks/templates/   Example CSV/JSON inputs
benchmarks/results/     Recorded benchmark and sample control-plane outputs
docs/                   Public English documentation
docs/internal/          Historical internal planning and research notes
tests/                  Pytest suite

Quick start

1. Install

For local development with the API and test toolchain:

python -m pip install --upgrade pip
python -m pip install -e ".[api,dev]"

If you only want the base library:

python -m pip install -e .

2. Run a quick benchmark

python scripts/run_hash_benchmark.py   --strategy midstate   --duration-seconds 10   --processes 4   --difficulty 145.04e12   --block-reward-btc 3.125

3. Run the API

python scripts/run_api.py --host 127.0.0.1 --port 8000

Then open the generated OpenAPI documentation at:

• http://127.0.0.1:8000/docs

4. Run the tests

pytest tests/

Module reference

Core package

• hypermine.hash_benchmark timed hashing benchmarks and benchmark result serialization
• hypermine.header_mutation_benchmark synthetic header mutation strategies for experimentation
• hypermine.economics expected BTC/USD production estimates from hashrate and network assumptions
• hypermine.performance_analysis benchmark-result analysis and recommendation helpers
• hypermine.manifests manifest loading and validation for benchmark campaigns

Telemetry and reporting

• hypermine.telemetry event normalization, replay, and aggregate share/power metrics
• hypermine.telemetry_comparison before/after telemetry delta reporting
• hypermine.reporting.profitability interval and daily profitability reporting from CSV templates

Control-plane logic

• hypermine.policy.models dispatch model definitions
• hypermine.policy.rules rule-based mode scoring and candidate evaluation
• hypermine.policy.simulator policy simulation engine
• hypermine.policy.controller dry-run action plan generation
• hypermine.rollout health gates, telemetry validation, and staged rollout checks

Device integration and onboarding

• hypermine.adapters.miner_api abstract miner adapter contract and null adapter
• hypermine.adapters.vendors HTTP-oriented Antminer and WhatsMiner adapter implementations
• hypermine.adapters.payload_catalog model-aware payload profiles and catalog discovery
• hypermine.adapters.override_registry verified override registry loading and profile selection
• hypermine.inventory inventory JSON parsing and adapter construction
• hypermine.onboarding confidence scoring, command matrices, firmware drift, and readiness checklist helpers
• hypermine.approval signed approval tokens for live apply
• hypermine.verified_profiles signed verified profile generation and validation

API and persistence

• hypermine.api.app FastAPI app factory and route definitions
• hypermine.api.service request execution layer for simulation, onboarding, preflight, apply, and evidence bundle workflows
• hypermine.api.auth API-key and role guard helpers
• hypermine.persistence JSONL/SQLite/PostgreSQL persistence backends for proposals, handshakes, and apply audits

Benchmarks and recorded outputs

The repository ships with historical benchmark and sample control-plane artifacts under benchmarks/results/.

Useful reference files include:

• benchmarks/results/hash-ranked.json ranked short benchmark results
• benchmarks/results/hash-midstate-10s-16p.json historical midstate benchmark sample
• benchmarks/results/current-hash-midstate-10s-20p-2026-03-30.json recent local comparison run
• benchmarks/results/profitability-report-sample.json sample profitability payload
• benchmarks/results/policy-simulation-sample.json sample policy simulation output
• benchmarks/results/dry-run-actions-sample.json sample dry-run proposal output
• benchmarks/results/apply-audit.jsonl sample apply audit log

See docs/benchmarks.md for a more detailed interpretation guide.

Examples

Simple runnable examples are provided under examples/:

• examples/run_benchmark.py
• examples/run_profitability.py
• examples/simulate_policy.py

These are intentionally small, readable entry points for new contributors.

Contributing

Please read CONTRIBUTING.md before opening a pull request.

In short:

• install the project in editable mode with dev extras
• run pytest tests/
• keep documentation honest about the limits of CPU mining
• treat all control-plane features as research and safety tooling, not profit claims

Documentation

• Public architecture notes: docs/architecture.md
• Benchmark interpretation guide: docs/benchmarks.md
• Historical internal notes: docs/internal/

License

This project is released under the MIT License.