Universal Miner

A Python orchestrator that connects to a Smart Mining server and automatically mines the most profitable cryptocurrency at any given time. It manages miner binaries, switches algorithms on demand, and exposes a local Stratum proxy so standard miners (lolminer, T-Rex…) can connect without any knowledge of the Smart Mining protocol.

How it works

lolminer / T-Rex
  │  classic Stratum TCP
  ▼
Internal Stratum Proxy (localhost)   ← Universal Miner acts as a pool
  │  Smart Mining protocol
  ▼
Smart Mining Server                  ← decides which coin to mine
  │
  ▼
Actual mining pools (2miners, etc.)

1. Universal Miner downloads and verifies the required miner binaries.
2. It connects to the Smart Mining server and subscribes with your wallets.
3. When the server sends set_algo (e.g. kawpow), the right miner is started and pointed at the local Stratum proxy.
4. The proxy transparently bridges Stratum ↔ Smart Mining in both directions.
5. On the next set_algo, the current miner is stopped and a new one is started automatically.

Requirements

• Linux (x86-64)
• Python 3.10+

Installation

git clone <repo-url>
cd universal_miner

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Configuration

Copy and edit config.json:

{
    "miners_dir": "./miners",
    "log": {
        "enabled": true,
        "dir": "./logs"
    },
    "proxy": {
        "host": "127.0.0.1",
        "port": 3333
    },
    "smart_mining": {
        "host": "pool.luminousmining.com",
        "port": 3333,
        "worker": "rig01",
        "password": "x"
    },
    "miners": [
        {
            "name": "lolminer",
            "version": "1.88",
            "download_url": "https://github.com/Lolliedieb/lolMiner-releases/releases/download/{version}/lolMiner_v{version}_Lin64.tar.gz",
            "log": { "enabled": true, "file": true },
            "extra_args": {
                "default": ["--watchdog", "exit"],
                "RVN": []
            }
        }
    ],
    "coins": [
        {
            "tag": "RVN",
            "algo": "kawpow",
            "wallet": "YOUR_RVN_WALLET",
            "miner": "lolminer",
            "pool_host": "rvn.2miners.com",
            "pool_port": 2020
        }
    ]
}

Key fields

Field	Description
miners_dir	Root directory where miner binaries are stored (<miners_dir>/<name>/)
proxy.port	Port on which the local Stratum server listens
smart_mining	Connection details for the Smart Mining server
miners[].download_url	Supports a {version} placeholder resolved automatically
miners[].log.enabled	Stream miner stdout to the console
miners[].log.file	Write miner output to <log.dir>/<name>.log
miners[].extra_args.default	Extra CLI flags added to every invocation
miners[].extra_args.<TAG>	Additional flags added when mining a specific coin
coins[].algo	Algorithm name sent by the Smart Mining server (e.g. kawpow)

Usage

Download miners only

Verify or download the configured miner binaries without connecting to the Smart Mining server:

.venv/bin/python main.py --download-only

Start the orchestrator

.venv/bin/python main.py

Use a custom config file:

.venv/bin/python main.py --config /path/to/config.json

Stop

Ctrl+C or SIGTERM — the current miner is stopped cleanly before exit.

Expected output

[10:00:01][smart_mining] Connecting to pool.luminousmining.com:3333…
[10:00:01][smart_mining] Connected
[10:00:01][smart_mining] Subscribed with 2 coin(s)
[10:00:01][proxy] Listening on 127.0.0.1:3333
[10:00:02][smart_mining] set_algo → kawpow
[10:00:02][manager] set_algo → kawpow  (coin: RVN, miner: lolminer)
[10:00:02][lolminer] Started (pid 12345)
[10:00:03][lolminer] GPU 0: 28.5 MH/s

Running tests

# Full test suite
.venv/bin/pytest

# Single test file
.venv/bin/pytest sources/tests/test_miner_manager.py

# Single test
.venv/bin/pytest sources/tests/test_miner_manager.py::test_on_algo_starts_lolminer_for_kawpow

# With output (useful when debugging)
.venv/bin/pytest -s

Project structure

universal_miner/
├── main.py                  # Entry point — CLI, download phase, async orchestration
├── config.json              # Your configuration
├── requirements.txt
└── sources/
    ├── logger.py            # log(component, message) → [HH:MM:SS][component] message
    ├── config/
    │   └── loader.py        # load_config() + typed dataclasses
    ├── downloader/
    │   ├── base.py          # BaseDownloader — HTTP download, version check
    │   ├── lolminer.py
    │   └── trex.py
    ├── smart_mining/
    │   ├── protocol.py      # JSON-RPC serialisation / parsing
    │   └── client.py        # Blocking TCP connection to the SM server
    ├── proxy/
    │   ├── server.py        # asyncio Stratum TCP server
    │   ├── stratum.py       # Stratum message builders / parsers
    │   └── bridge.py        # Routes messages between miners and the SM server
    └── miner/
        ├── process.py       # subprocess wrapper with stdout routing
        └── manager.py       # Starts/switches the right miner on set_algo

Adding a new miner

1. Create sources/downloader/<name>.py, subclass BaseDownloader, implement binary_name and extract().
2. Register it in sources/downloader/__init__.py under DOWNLOADERS.
3. Add the miner entry to config.json (name must match the registry key).