---
type: reference
title: "crustybike — Distributed Mining & Topological Analysis"
description: "Distributed Bitcoin mining system: topological solver on MLX, Cartesian Miner on OpenCL/Metal, QUIC workers, TDR recovery, zero-copy Merkle."
tags: [crustybike, bitcoin, mining, mlx, opencl, metal, distributed, compute-optimization]
timestamp: 2026-07-25
---

# crustybike — Distributed Mining & Topological Analysis

A distributed Bitcoin mining system focused on topological analysis of the "Patoshi" pattern in early Bitcoin blocks. Uses Apple MLX as a tensor math library (not for ML training) for geometric determinant computation, and PyOpenCL for GPU-accelerated SHA-256 mining.

**Repository:** `/Users/alefita/workdir/crustybike/`
**Branch model:** `main` (protected), feature branches per hypothesis
**Tags:** `v0.0.1`, `v0.0.2`, `v.0.0.3`, `v2.2350-h16`

---

## Architecture

| Layer | Technology | Purpose |
|-------|-----------|---------|
| Solver | MLX (`mlx.core`) | Topological evaluation — geometric determinants on Metal GPU |
| Mining | PyOpenCL | Cartesian Miner — Double SHA-256 + DAA distance |
| Merkle | MLX + Metal | Zero-copy permutations via mx.take(), on-GPU tree construction |
| Workers | Python asyncio | QUIC-based distributed mining |
| TTS | mlx_audio | Audio generation (side feature) |

## Compute Stack

- **MLX ≥ 0.31.1** (macOS) / **MLX[cuda]** (Linux x86_64) — Tensor math, zero-copy gather
- **PyOpenCL** — GPU mining kernels
- **scikit-learn, umap-learn, pysr** — Offline analysis (notebooks)
- **No PyTorch** — Zero imports, zero references

## Kernel Architecture

### V1 (Legacy) — Scientific Validation
- `chronobreaker_combined.cl` (1272 lines, 14 kernels)
- `cartesian_miner.cl` (132 lines)

### V2 (Production) — Lean Mining
- `cartesian_miner.cl` (132 lines) — Mining kernel
- `topology_eval.cl` (193 lines) — Swift skip via discriminant

### Metal
- `cartesian_miner.metal` (128 lines) — MLX Metal conventions
- `merkle_sha256.metal` (130 lines) — On-GPU Merkle tree

## Key Optimizations

| Pattern | Description |
|---------|-------------|
| Zero-copy Merkle | `mx.take()` GPU-side gather, no host copy |
| Swift Skip | `b² - 4ac < 0` → skip dispatch entirely |
| TDR Recovery | Full OpenCL context rebuild after GPU timeout |
| Atomic CAS | `atomic_cmpxchg` for race-free nonce discovery |
| Tropa de Choque | 10 concurrent prefetch workers |
| Midstate caching | SHA-256 first chunk computed once |

## Related Pages

- [[compute-optimization]] — Hub
- [[mlx-opencl-bridge]] — Zero-copy pattern
- [[opencl-kernel-design]] — Kernel inventory
- [[gpu-async-pipelines]] — TDR recovery, prefetch architecture

## Status

- ✅ Production mining via Cartesian Miner
- ✅ Topological solver on MLX
- ✅ Zero-copy Merkle permutations
- ✅ TDR recovery
- ✅ Metal kernels present
- ⚠️ Metal kernels not explicitly loaded by Python
- ⚠️ float32 exclusively
- 🔜 Potential Metal→MLX native pipeline