mujina-miner

Open source Bitcoin mining software written in Rust for ASIC mining hardware.

Developer Preview: This software is under heavy development and not ready for production use. The code is made available for developers interested in contributing, learning about Bitcoin mining protocols, or evaluating the architecture. APIs, protocols, and features are subject to change without notice. Documentation is incomplete and may be inaccurate. Use at your own risk.

Overview

mujina-miner is a modern, async Rust implementation of Bitcoin mining software designed to communicate with various Bitcoin mining hash boards via USB serial interfaces. Part of the larger Mujina OS project, an open source, Debian-based embedded Linux distribution optimized for Bitcoin mining hardware.

Features

• Heterogeneous Multi-Board Support: Mix and match different hash board types in a single deployment; hot-swappable, no need to restart when adding or removing boards
• Hackable & Extensible: Clear, modular architecture with well-documented internals - designed for modification, experimentation, and custom extensions
• Reference-Grade Documentation: Thorough documentation at every layer, from chip protocols to system architecture, serving as both implementation guide and educational resource
• API-Driven Control: REST API for all operations---implement your own control strategies, automate operations, or build custom interfaces on top
• Open-Source, Open-Contribution: Active development with open contribution; not code dumps or abandonware, a living project built by the entire community
• Accessible Development: Start developing with minimal hardware; a laptop and a single Bitaxe board is enough to contribute meaningfully

Supported Hardware

Currently supported:

• Bitaxe Gamma with BM1370 ASIC

Planned support:

• EmberOne with BM1362 ASIC
• EmberOne with Intel BZM2 ASICs
• Antminer S19j Pro hash boards
• Any and all ASIC mining hardware

Documentation

Project Documentation

• Architecture Overview - System design and component interaction
• Contribution Guide - How to contribute to the project
• Code Style Guide - Formatting and style rules
• Coding Guidelines - Best practices and design patterns

Protocol Documentation

• BM13xx ASIC Protocol - Serial protocol for BM13xx series mining chips
• Bitaxe-Raw Control Protocol - Management protocol for Bitaxe board peripherals

Hardware Documentation

• Bitaxe Gamma Board Guide - Hardware and software interface documentation for Bitaxe Gamma

Build Requirements

Linux

On Debian/Ubuntu systems:

sudo apt-get install libudev-dev

The libudev-dev package provides header files for building, and depends on the libudev package which provides the library for runtime.

macOS

macOS support is planned, but USB discovery using IOKit is not yet implemented.

Building

# Build the workspace
cargo build

# Run unit tests (no hardware required)
cargo test

Running

At this point in development, configuration is done via environment variables. Once configuration storage and API functionality are more complete, persistent configuration will be available through the REST API and CLI tools.

Pool Configuration

Connect to a Stratum v1 mining pool:

MUJINA_POOL_URL="stratum+tcp://localhost:3333" \
MUJINA_POOL_USER="bc1qce93hy5rhg02s6aeu7mfdvxg76x66pqqtrvzs3.mujina" \
MUJINA_POOL_PASS="custom-password" \
cargo run

The password defaults to "x" if not specified.

Without MUJINA_POOL_URL, the miner runs with a dummy job source that generates synthetic mining work, which is useful for testing hardware without a pool connection.

Log Levels

Control output verbosity with RUST_LOG:

# Info level (default) -- shows pool connection, shares, errors
cargo run

# Debug level -- adds job distribution, hardware state changes
RUST_LOG=mujina_miner=debug cargo run

# Trace level -- shows all protocol traffic (serial, network, I2C)
RUST_LOG=mujina_miner=trace cargo run

Target specific modules for focused debugging:

# Trace just the Stratum v1 client
RUST_LOG=mujina_miner::stratum_v1=trace cargo run

# Debug Stratum v1, trace BM13xx protocol
RUST_LOG=mujina_miner::stratum_v1=debug,mujina_miner::asic::bm13xx=trace cargo run

Combine pool configuration with logging as needed:

RUST_LOG=mujina_miner=debug \
MUJINA_POOL_URL="stratum+tcp://localhost:3333" \
MUJINA_POOL_USER="your-address.worker" \
cargo run

Protocol Analysis Tool

The mujina-dissect tool analyzes captured communication between the host and mining hardware, providing detailed protocol-level insights for BM13xx serial commands, PMBus/I2C power management, and fan control.

See tools/mujina-dissect/README.md for detailed usage and documentation.

License

This project is licensed under the GNU General Public License v3.0 or later. See the LICENSE file for details.

Contributing

We welcome contributions! Whether you're fixing bugs, adding features, improving documentation, or simply exploring the codebase to learn about Bitcoin mining protocols and hardware, your involvement is valued.

Please see our Contribution Guide for details on how to get started.

Related Projects

• Bitaxe - Open-source Bitcoin mining hardware designs
• bitaxe-raw - Firmware for Bitaxe boards
• EmberOne - Open-source Bitcoin mining hashboard
• emberone-usbserial-fw - Firmware for EmberOne boards