Metadata-Version: 1.2
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
Description: **``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>`__
        
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
