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 strategy distinguishes manual_canary research experiments from manual_bid profit-seeking opportunities.
• 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

./scripts/ratchet setup
./scripts/ratchet

./scripts/ratchet is the cockpit. It tells you exactly what to do next.

If the cockpit is in cooldown and you want the app to wait until the earliest next action, run:

./scripts/ratchet pipeline

It prints the exact monitor-only plan and asks yes/no before doing anything.

For the durable forever lifecycle supervisor:

./scripts/ratchet supervise

It persists lifecycle state in data/ratchet.sqlite. If the process crashes or the Mac reboots, start the same command again and it resumes from SQLite.

When you manually place a Braiins bid, record the exposure so the supervisor blocks new experiments:

./scripts/ratchet position open --description "Braiins order abc" --maturity-hours 72

Close it only when finished:

./scripts/ratchet position close POSITION_ID

For the native macOS SwiftUI shell:

cd macos/BraiinsRatchet
swift run BraiinsRatchetMac

For a 6-hour monitoring session:

./scripts/ratchet watch 6

Every completed watch is now treated as a ratchet experiment. It writes a run report under reports/run-*.md and appends the master ledger at reports/EXPERIMENT_LOG.md.

To inspect the experiment ledger:

./scripts/ratchet experiments

To embed an already completed manual session from stored snapshots:

./scripts/ratchet retro 2026-04-25T19:08:00+00:00 2026-04-25T21:05:00+00:00

For the human operating guide:

./scripts/ratchet explain

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"
}

Public Braiins Market Data

The collector first uses unauthenticated public web endpoints from hashpower.braiins.com; no token is needed for live price action. See docs/BRAIINS_PUBLIC_MARKET.md.

Watcher-only tokens are only relevant if we later need account-specific read-only data such as your private balance, historical fills, or order status. Owner tokens remain out of scope.

Recommendation States

• observe: do nothing.
• manual_canary: a tiny manually executed research experiment is within the configured loss budget.
• manual_bid: a manually executed bid clears profit-seeking discount and risk guardrails.

The Braiins market report distinguishes visible top-of-book from executable depth:

• best_ask_btc_per_eh_day: cheapest visible ask.
• fillable_price_btc_per_eh_day: cheapest ask level with enough unmatched supply for the configured canary-sized target PH/s.
• suggested_bid_btc_per_eh_day: fillable price plus the configured overpay cushion.

Documentation

• PROGRAM.md: research charter and ratchet rules.
• START_HERE.md: no-prior-knowledge operating instructions.
• SECURITY.md: token, computer, and trading safety guardrails.
• docs/BRAIINS_PUBLIC_MARKET.md: public market collector behavior.
• docs/RATCHET_OPERATIONS.md: day-to-day monitor cycle.
• docs/CLI_REFERENCE.md: command reference and test command.
• reports/EXPERIMENT_LOG.md: master ratchet ledger with run-level hypotheses, outcomes, and adaptations.

Tests

PYTHONPATH=src ./.venv/bin/python -m unittest discover -s tests

The tests are network-free and use fixtures for public Braiins parsing. Live collectors are intentionally separate operational checks.

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.