Metadata-Version: 2.0
Name: aiostratum-proxy
Version: 1.0.0
Summary: Python3 asyncio stratum protocol mining proxy
Home-page: https://github.com/wetblanketcc/aiostratum_proxy
Author: wetblanketcc
Author-email: 35851045+wetblanketcc@users.noreply.github.com
License: MIT
Description-Content-Type: UNKNOWN
Keywords: async asyncio aio crypto cryptocurrency blockchain mining stratum protocol proxy pool equihash bitcoinlitecoin
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Topic :: System :: Networking
Requires-Python: >=3.5
Requires-Dist: aiojsonrpc2 (==1.0.0)
Requires-Dist: PyYAML (==3.12)

**``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 <https://github.com/Animosity/CraftIRC/wiki/Complete-idiot's-introduction-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:

1. 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)
2. 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:

1. Create a new Python module with the Monero ‘worker’ and ‘pool’
   protocol class implementations
2. Add the new Monero worker/pool classes to your proxy config file
3. You will need to ensure your Python module is visible within
   ``PYTHONPATH`` to use it within your proxy YAML config file
4. **Consider `submitting it as a pull
   request <https://github.com/wetblanketcc/aiostratum_proxy/pulls>`__
   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 <https://github.com/wetblanketcc/aiostratum_proxy>`__, `pull
requests for bug fixes & new
protocols <https://github.com/wetblanketcc/aiostratum_proxy/pulls>`__,
`reporting
issues <https://github.com/wetblanketcc/aiostratum_proxy/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

Related & Informative Links
^^^^^^^^^^^^^^^^^^^^^^^^^^^

1. `Stratum Protocol
   Specification <https://slushpool.com/help/manual/stratum-protocol>`__
2. `Stratum Protocol Specification
   Draft <https://docs.google.com/document/d/17zHy1SUlhgtCMbypO8cHgpWH73V5iUQKk_0rWvMqSNs/edit?hl=en_US>`__
3. `Stratum Protocol Bitcoin Wiki
   Page <https://en.bitcoin.it/wiki/Stratum_mining_protocol>`__
4. `Original Bitcointalk.org Stratum
   Announcement <https://bitcointalk.org/index.php?topic=108533.0>`__
5. `Follow-on Bitcointalk.org Stratum
   Discussion <https://bitcointalk.org/index.php?topic=557991.0>`__


