HashScope Documentation¶

A man-in-the-middle (MITM) proxy for Bitcoin mining, sitting between miners and pools to capture, decode, and visualize Stratum protocol messages in real-time.

Quick Start

Get started in 5 minutes

Quick Start Guide
Architecture

Understand the system design

System Architecture
Agent Fleet

Distributed testing with Nostr

Agent Fleet Guide
Developer Guide

Development setup and standards

Developer Guide

Key Features¶

Transparent Proxy: Relays traffic between miners and pools without corrupting messages
Real-time Capture: Captures every message with full metadata
Stratum v1 Parsing: Decodes JSON-RPC messages with best-effort parsing
Web Interface: Modern React UI for visualizing message flow
WebSocket Streaming: Live updates as messages flow through the proxy
Session Management: Track multiple miner connections independently
Filtering & Search: Filter by session, direction, method, or search across all data
Distributed Agent Fleet: Scale load testing across multiple agents via Nostr relay
Real-time Telemetry: Monitor agent performance and pool responses

Getting Started¶

# Set your pool configuration
export POOL_HOST=stratum+tcp://your-pool.com
export POOL_PORT=3333

# Start HashScope
docker compose up -d

# Point your miner to localhost:3333
# Open http://localhost:3000 in your browser

For complete setup instructions, see the Quick Start Guide.

Features¶

This documentation includes:

Interactive Mermaid diagrams for system architecture visualization
Code syntax highlighting with copy-to-clipboard
Full-text search across all documentation
Dark/Light mode support
Mobile responsive design

Repository¶

GitHub: https://github.com/256foundation/HashScope
Issues: https://github.com/256foundation/HashScope/issues

License¶

This project is licensed under the MIT License - see the LICENSE file for details.