BraiinsRatchet/README.md

Braiins Ratchet

Monitor-only research scaffold for optimizing a manual "buy hashpower on Braiins, mine through OCEAN" strategy.

The first implementation is deliberately conservative:

• The code never places, modifies, or cancels Braiins orders.
• The default strategy emits recommendations only.
• The Braiins integration accepts a watcher-only token only.
• All mutable runtime state stays inside this repository under data/.
• The Git branch is master.
• The project uses Python standard library only.

Quick Start

python3 -m venv .venv
./.venv/bin/python -m braiins_ratchet.cli init-db
./.venv/bin/python -m braiins_ratchet.cli collect-ocean
./.venv/bin/python -m braiins_ratchet.cli evaluate

Set PYTHONPATH=src if running without installation:

PYTHONPATH=src python3 -m braiins_ratchet.cli evaluate

Import a manual Braiins market snapshot:

PYTHONPATH=src ./.venv/bin/python -m braiins_ratchet.cli import-market examples/market_snapshot.example.json
PYTHONPATH=src ./.venv/bin/python -m braiins_ratchet.cli evaluate

The JSON shape is:

{
  "timestamp_utc": "2026-04-25T12:00:00+00:00",
  "best_price_btc_per_eh_day": "0.30",
  "available_hashrate_eh_s": "0.10",
  "source": "manual"
}

Guardrail Model

braiins_ratchet.strategy can propose a manual bid, but braiins_ratchet.guardrails decides whether that proposal is admissible. The executor layer currently has no write-capable Braiins methods. If live execution is ever added, it must be a separate reviewed change and remain disabled by default.

Data Maturity

OCEAN's TIDES payout model means a canary experiment should not be scored immediately after spend completion. A spend should be treated as immature until its shares have had time to age through the pool's share-log window. The strategy therefore records both expected value and maturity notes.