aiostratum_proxy: A Python repository from zhguanw

aiostratum_proxy is a Stratum Protocol proxy (ie cryptocurrency/mining) built using Python3. It was built to be a modern, code-concise, extensible, and fast replacement for existing aging Stratum Protocol proxy solutions & implementations.

Requires Python 3.5 or greater (built with asyncio using async/await syntax)
Extensible: easily implement new coin/algorithm 'stratum-like' protocols as dynamically-loaded, external Python3 modules (via config file)
Can run multiple proxies at the same time (ie. mine different coins on different pools)
Each proxy supports up to 65536 miner connections (per pool connection), each mining a separate nonce space (dependent on miner support)
Supports plaintext and secure connections (ie. TLS/SSL) for both incoming miner connections and outgoing pool connections
Plain socket transport only (ie. not JSONRPC over HTTP, HTTP Push, or HTTP Poll); this is the defacto standard in the cryptocurrency space

Donations

I built this on my own time, outside of my day job. If you find this mining proxy useful, donate to help continue development. I value my time.

BTC: 1BS4QYAFiya4tsjyvHeY945biKnDj6bRA4
LTC: LTN1LPGnJjHMKq4DcuQYifQgLfT4Phmn9d
ETH: 0x4B005e68D323bdABD8eeD1D415117Ff1B57b3EC5
BTCP: b1CACK65UTwzmHGw2VvyozdPsRLMb8utGLg
ZCL: t1eoqTqyatJzL2rErW83waZLQHZLKuipMbi

Installation

Installation is simple:

pip install aiostratum-proxy

However, for an isolated and more robust installation, you should consider using Python virtual environments:

# this will create a directory 'containing' the Python3 virtual environment
python3 -m venv aiostratum_proxy

cd aiostratum_proxy

# this will install the aiostratum-proxy package
bin/pip install aiostratum-proxy

# verify the installation by checking the package version
bin/aiostratum-proxy --version

Usage

Installation creates a new command-line shortcut called aiostratum-proxy; it has built-in command-line help, just run:

bin/aiostratum-proxy --help

A config file is needed for the proxy to run; you can generate one:

bin/aiostratum-proxy --generate-config > proxy-config.yaml

Open and edit the generated proxy-config.yaml in a text editor. The config file's syntax is YAML (here's a good guide to YAML).

To run aiostratum-proxy, pass it your edited config file:

bin/aiostratum-proxy --config proxy-config.yaml

Supported Algorithms/Coins

aiostratum-proxy was designed to be modular and extensible when it comes to coin and algorithm support. This is done via miner+pool protocol module pairs (more on this below).

Current support includes:

any coin based on Equihash (ZCash, ZClassic, Bitcoin Gold, Bitcoin Private, etc):
- miner module: aiostratum_proxy.protocols.equihash.EquihashWorkerProtocol
- pool module: aiostratum_proxy.protocols.equihash.EquihashPoolProtocol
(EXPERIMENTAL/UNTESTED/probably not working just yet) Bitcoin (and related coins):
- miner module: aiostratum_proxy.protocols.stratum.StratumWorkerProtocol
- pool module: aiostratum_proxy.protocols.stratum.StratumPoolProtocol

As you can see, it is possible for a protocol implementation (ie. both the worker & pool sides) to support multiple coins, assuming they share some common ancestry or have heavily borrowed technical decisions.

Add Support for New Coins & Algorithms

The terms 'Stratum' and 'Stratum Protocol' are used broadly (perhaps too much so) in the cryptocurrency ecosystem. The concept behind the Stratum protocol started with the specific desire to improve the efficiency of Bitcoin mining pools.

In time, the rise of altcoins demanded a similar approach to managing the communications between miners and pools. For whatever reason, most altcoins have tweaked the original Stratum spec to their needs, borrowing and learning from prior mistakes.

To add support for a new coin or algorithm, there are two options:

Use an existing protocol implementation and tweak; note that this means if there are future changes, it may have cascading impacts (see the Equihash protocol pair as an example, it is based off of the Stratum protocol pair)
Create a new protocol pairing by implementing both BasePoolProtocol (to handle connections to pools) and BaseWorkerProtocol (to handle incoming miner connections)

For example, if you were implementing Monero support:

Create a new Python module with the Monero 'worker' and 'pool' protocol class implementations
Add the new Monero worker/pool classes to your proxy config file
You will need to ensure your Python module is visible within PYTHONPATH to use it within your proxy YAML config file
Consider submitting it as a pull request to aiostratum_proxy! If so, you would place the new module alongside the existing Equihash implementation at aiostratum_proxy.protocols.monero

Future Considerations

Community involvement is appreciated. Code review, pull requests for bug fixes & new protocols, reporting issues, spreading the word - all appreciated.

TODO:

Community feedback on the following is appreciated.

More coin/algo support
Complete mining.set_extranonce support
Consider additional authentication improvements (currently miners aren't authenticated)
- authenticate miners locally within proxy via config
- authenticate miners via passthru to pool; would require per-pool mappings of username/password for fallback pools in config?
Consider immediate reply to miner share submissions instead of waiting for pool response
HAProxy PROXY protocol support

zhguanw/aiostratum_proxy