README

ASICseer Pool
Calin Culianu <calin.culianu@gmail.com>

Ultra low overhead massively scalable multi-process, multi-threaded modular
Bitcoin Cash mining pool, proxy, passthrough, library and database interface in
C for Linux. Features SPLNS-style payout scheme.

asicseer-pool is code provided free of charge under the GPLv3 license but its
development is mostly paid for by commissioned funding.

Please consider contributing if you are running it on a pool or contributing to
the authors listed in AUTHORS if you use this code to aid funding further
development.

Updated and maintained by:
    Calin Culianu <calin.culianu@gmail.com>
    bitcoincash:qplw0d304x9fshz420lkvys2jxup38m9symky6k028

===

This software is originally based on the work of Con Kolivas' ckpool
   [ckpool-splns](https://bitbucket.org/ckolivas/ckpool-splns/)

It has been updated and reworked to add features and to support Bitcoin Cash
(rather than Bitcoin).

* Removed segwit
* Added larger merkle tree support (for mining 32MB blocks)
* Added cash address support
* Configurable pool fee support
   - Features 20% of pool fee as a dev donation to Calin (me), and Bitcoin Cash
     Node wallets, by default.
* Added "mindiff_overrides" which allows a pool to give out larger minimum and
  starting difficulty for stratum clients matching a particular user agent
  string (useful for NiceHash, which requires pools have a high difficulty).
* Updated asicseer-db (formerly ckdb) sources to actually compile on modern
  Linux
* Added ZMQ support for new block notifications
* Removed asicseer-db, removed all sql, HTML, & php files related to this.
* Updated source tree to use cmake, removed autotools-based build.
* Added optional "solo" mining mode (-B / --solo).
* Fixed bugs

BUILDING
---

A relatively recent, C++-20-capable compiler is required.

$ sudo apt-get install build-essential libzmq3-dev cmake
$ mkdir build && cd build
$ cmake ..
$ make

Compiled files will appear in the src/ subdirectory relative to the build
directory.

---

Original README follows (modified by Calin from the original to reflect added
config options):

---

Original: ckpool + ckdb + libckpool by Con Kolivas and Andrew Smith.

---
LICENSE:

GNU Public license V3. See included COPYING for details.


---
DESIGN:

Architecture:
- Low level hand coded architecture relying on minimal outside libraries beyond
  basic glibc functions for maximum flexibility and minimal overhead that can be
  built and deployed on any Linux installation.
- Multiprocess & multithreaded design to scale to massive deployments and
  capitalize on modern multicore/multithread CPU designs.
- Minimal memory overhead.
- Utilises ultra reliable unix sockets for communication with dependent
  processes.
- Modular code design to streamline further development.
- Standalone library code that can be utilised independently of asicseer-pool.
- Same code can be deployed in many different modes designed to talk to each
  other on the same machine, local lan or remote internet locations.

Modes of deployment:
- Comprehensive pooled mining solution with a postgresql database interface.
- Passthrough node(s) that combine connections to a single socket which can be
  used to scale to millions of clients and allow the main pool to be isolated
  from direct communication with clients.
- Proxy nodes with a database that act as a single client to the upstream pool
  while storing full client data of their own.
- Simple proxy without the limitations of hashrate inherent in other proxy
  solutions when talking to asicseer-pool.
- Simple pool without a database.
- Library for use by other software.

Features:
- Bitcoind communication to unmodified bitcoind with multiple failover to local
  or remote locations.
- Local pool instance worker limited only by operating system resources and can
  be made virtually limitless through use of multiple downstream passthrough
  nodes.
- Proxy and passthrough modes can set up multiple failover upstream pools.
- Optional share logging.
- Virtually seamless restarts for upgrades through socket handover from exiting
  instances to new starting instance.
- Configurable custom coinbase signature.
- Configurable instant starting and minimum difficulty.
- Rapid vardiff adjustment with stable unlimited maximum difficulty handling.
- New work generation on block changes incorporate full bitcoind transaction set
  without delay or requiring to send transactionless work to miners thereby
  providing the best bitcoin network support and rewarding miners with the most
  transaction fees.
- Event driven communication based on communication readiness preventing slow
  communicating clients from delaying low latency ones.
- Stratum messaging system to running clients.
- Accurate pool and per client statistics.
- Multiple named instances can be run concurrently on the same machine.
- SPLNS payout scheme (payout directly to users for each block found)


---
BUILT BINARIES:

Binaries will be built in the src/ subdirectory. Binaries generated will be:
asicseer-pool - The main pool back-end.
asicseer-pmsg - An application for passing messages in libasicseerpool format
                to asicseer-pool/asicseer-db.
notifier      - An application designed to be run with bitcoind's -blocknotify
                to notify asicseer-pool of block changes. It is recommended
                that you not use this application but instead configure
                bitcoind to use ZMQ -zmqpubhashblock= and set the "zmq" field
                for each bitcoind.


Installation is NOT required and asicseer-pool can be run directly from the
directory it's built in.

---
RUNNING:

asicseer-pool supports the following options:

-A | --standalone (unused)
-B | --solo
-c CONFIG | --config CONFIG
-g GROUP | --group GROUP
-H | --handover
-h | --help
-k | --killold
-L | --log-shares
-l LOGLEVEL | --loglevel LOGLEVEL
-N | --node
-n NAME | --name NAME
-P | --passthrough
-p | --proxy
-R | --redirector
-s SOCKDIR | --sockdir SOCKDIR
-u | --userproxy
-v | --version


-A Standalone mode (defunct). This option currently does nothing but used
to tell the program not to use asicseer-db. It only exists now for backward
compatibility.

-B Solo mining mode. Payouts will give all of the reward (minus fees) to the
miner that solved the block. Use this if you intend to run a solo mining pool.
This option does not work with any of the following: -N, -P, -p, -R, -u.
** Note ** In solo mining mode, all miner clients must have valid BCH addresses
as their username prefix otherwise they will be rejected.

-c <CONFIG> tells asicseer-pool to override its default configuration filename
and load the specified one. If -c is not specified, asicseer-pool looks for:
asicseer-pool.conf, in proxy mode it looks for asicseer-proxy.conf, in
passthrough mode for asicseer-passthrough.conf and in redirector mode for
asicseer-redirector.conf

-g <GROUP> will start asicseer-pool as the group ID specified.

-H will make asicseer-pool attempt to receive a handover from a running
incidence of asicseer-pool with the same name, taking its client listening
socket and shutting it down.

-h displays the above help

-k will make asicseer-pool shut down an existing instance of asicseer-pool with
the same name, killing it if need be. Otherwise asicseer-pool will refuse to
start if an instance of the same name is already running.

-L will log per share information in the logs directory divided by block height
and then workbase.

-l <LOGLEVEL will change the log level to that specified. Default is 5 and
maximum debug is level 7.

-N will start asicseer-pool in passthrough node mode where it behaves like a
passthrough but requires a locally running bitcoind and can submit blocks
itself in addition to passing the shares back to the upstream pool. It also
monitors hashrate and requires more resources than a simple passthrough. Be
aware that upstream pools must specify dedicated IPs/ports that accept
incoming node requests with the nodeserver directive described below.

-n <NAME> will change the asicseer-pool process name to that specified,
allowing multiple different named instances to be running. By default the
variant names are used: asicseer-pool, asicseer-proxy, asicseer-passthrough,
asicseer-redirector, asicseer-node.

-P will start asicseer-pool in passthrough proxy mode where it collates all
incoming connections and streams all information on a single connection to an
upstream pool specified in asicseer-proxy.conf . Downstream users all retain
their individual presence on the master pool. Standalone mode is implied.

-p will start asicseer-pool in proxy mode where it appears to be a local pool
handling clients as separate entities while presenting shares as a single user
to the upstream pool specified. Note that the upstream pool needs to be a
asicseer-pool for it to scale to large hashrates. Standalone mode is Optional.

-R will start asicseer-pool in a variant of passthrough mode. It is designed
to be a front end to filter out users that never contribute any shares. Once an
accepted share from the upstream pool is detected, it will issue a redirect to
one of the redirecturl entries in the configuration file. It will cycle over
entries if multiple exist, but try to keep all clients from the same IP
redirecting to the same pool.

-s <SOCKDIR> tells asicseer-pool which directory to place its own communication
sockets (/tmp by default)

-u Userproxy mode will start asicseer-pool in proxy mode as per the -p option
above, but in addition it will accept username/passwords from the stratum
connects and try to open additional connections with those credentials to the
upstream pool specified in the configuration file and then reconnect miners to
mine with their chosen username/password to the upstream pool.

-v Prints the program version and exits immediately.

---
CONFIGURATION

At least one bitcoind is mandatory in asicseer-pool mode with the minimum
requirements of server, rpcuser and rpcpassword set.

asicseer-pool takes a JSON encoded configuration file in asicseer-pool.conf by
default or asicseer-proxy.conf in proxy or passthrough mode unless specified
with -c. Sample configurations for asicseer-pool and asicseer-proxy are included
with the source. Entries after the valid json are ignored and the space there
can be used for comments. The options recognised are as follows:

"bchaddress" :
    This is the bitcoin cash address for the pool. All pool fees go to this
    address. It is also used as the fallback address for leftover dust or in
    case a worker address is invalid. Both legacy and cashaddr formats are
    supported.

"bchsig" :
    This is optional text to put into the coinbase transaction of mined blocks.
    It will be verbatim copied to the coinbase scriptsig (max 96 bytes).

    You may specify either a string or an array of strings here. If an array is
    specified, then a string will be randomly picked from the array each time
    a new coinbase transaction is generated.

    Example 1:

        "bchsig" : "/This is my pool's only sig - Use BCHN/

    Example 2:

        "bchsig" : [
            "/This is a sig/",
            "/This is another sig/"
        ]

"blocking_timeout" :
    The number of seconds to wait for a client that stopped responding to our
    packets (on the TCP level) before considering them out-to-lunch, and closing
    the connection.  Defaults to 60 seconds.  Do not set this below 10.  If you
    wish to disable idle protection of clients, set this to a high value
    e.g. 999999999.

"blockpoll" :
    The frequency in milliseconds for how often to check for new network blocks
    (default: 100). This is intended to be a backup only for when the notifier
    and/or zmq are not set up and only polls if neither the "notify" nor "zmq"
    fields are not set on a btcd.

"btcd" :
    This is an array of bitcoind(s) with the options: "url", "auth" and "pass"
    which match the configured bitcoind. The optional boolean field "notify", if
    true, tells asicseer-pool that this bitcoind is using the notifier, and does
    not need to be polled for block changes.

    Additionally, the string option "zmq" : "tcp://ip.to.bitcoind:port" can be
    specified per btcd in which case the software will subscribe to the
    bitcoind's ZMQ pub "hashblock" notification to receive blockchain change
    notifications. This requires bitcoind be configured with the same
    -zmqpubhashblock= option. The option "zmq", if present, also implies
    "notify" : true. It is highly recommended that pool operators use this zmq
    facility to receive blockchain change notifications from bitcoind, since it
    is the lowest-latency mechanism available, and it reduces overhead as
    compared to polling.

    If no btcd is specified, asicseer-pool will look for one on localhost:8332
    with the username "user" and password "pass". The maintainers of this
    software recommend BCHN as the bitcoind node implementation to use, since it
    has the fastest JSON-RPC implementation.

    Example:

        "btcd" : [
            {
               "url" : "192.168.0.101:8332",
               "auth" : "someuser1",
               "pass" : "somepass1",
               "zmq" : "tcp://192.168.0.101:28332"
            },
            {
               "url" : "192.168.0.15:8332",
               "auth" : "someuser2",
               "pass" : "somepass2",
               "zmq" : "tcp://192.168.0.15:28332"
            },
            {
               "url" : "192.168.0.151:8332",
               "auth" : "this_one_polls",
               "pass" : "zzz",
               "notify" : false
            }
        ]

"disable_dev_donation":
    Defaults false. If true, disable dev donations specified in donation.h.

"fee_discounts":
    Offer discounts to specific users, keyed off their mining address. 1.0 =
    full fee discount, 0.0 = no fee discount. All users default to 0.0 (no
    discount) if unspecified.

    Example:

        "fee_discounts" : {
           "address1" : 0.25,
           "address2" : 0.33,
           "address3" : 1.0
        }

"logdir" :
    Which directory to store pool and client logs. Default "logs"

"maxclients" :
    Optional upper limit on the number of clients asicseer-pool will accept
    before rejecting further clients.

"maxdiff" :
    Optional maximum diff that vardiff will clamp to where zero is no maximum.

"mindiff" :
    Minimum diff that vardiff will allow miners to drop to. Default 1

"mindiff_overrides" :
    Optional JSON object (dictionary) of useragent, mindiff pairs.

    Example:

        "mindiff_overrides" : {
            "nicehash" : 500000,
            "foohash" : 750000
        }

    This is a mechanism to support a raised minimum difficulty for clients
    connecting to the pool based on their "useragent" string (that they normally
    send via `mining.subscribe` on initial connect). The "useragent" specified
    here is a prefix match (case insensitive). If a client's useragent matches
    the specified prefix, then it will have its minimum and starting difficulty
    set to the override value. Note: The override values specified here cannot
    be lower than the pool's "mindiff" setting -- they must always be higher
    (similarly this value must also be below "maxdiff"). This mechanism was
    initially designed so that NiceHash clients can connect to a pool and get a
    special-cased raised difficulty (since NiceHash refuses to operate if share
    difficulty is < 500000, as of the time of this writing).

"nodeserver" :
    This takes the same format as the serverurl array and specifies additional
    IPs/ports to bind to that will accept incoming requests for mining node
    communications. It is recommended to selectively isolate this address to
    minimize unnecessary communications with unauthorized nodes.

"nonce1length" :
    This is optional allowing the extranonce1 length to be chosen from 2 to 8.
    Default 4

"nonce2length" :
    This is optional allowing the extranonce2 length to be chosen from 2 to 8.
    Default 8

"pool_fee" :
    The percentage to pay out to the pool "bchaddress" for each found block, as
    a floating point percentage of the total mining reward. If unspecified, 1.0
    is the default (1%). The pool fee is taken from the total coinbase reward.
    Set this value to 0.0 to disable. Values >= 100.0 will be clamped to 100.0.
    The pool_fee will appear as the first output in the coinbase transaction.

"proxy" :
    This is an array in the same format as btcd above but is used in proxy and
    passthrough mode to set the upstream pool and is mandatory.

"redirecturl" :
    This is an array of URLs that asicseer-pool will redirect active miners to
    in redirector mode. They must be valid resolvable URLs+ports.

"serverurl" :
    This is the IP(s) to try to bind asicseer-pool uniquely to, otherwise it
    will attempt to bind to all interfaces in port 3333 by default in pool mode
    and 3334 in proxy mode. Multiple entries can be specified as an array by
    either IP or resolvable domain name but the executable must be able to bind
    to all of them and ports up to 1024 usually require privileged access.

"single_payout_override":
    A string, which should be a valid BCH address. If this is specified the
    coinbase tx generator will completely skip SPLNS payouts in coinbase and
    will put all miner rewards into a single output which is to the specified
    address. This option is offered as a work-around for T17 issues where
    multiple SPLNS payouts crash Bitmain mining rigs, so we must simply pay
    the mining reward to a signle address. Since SPLNS payouts directly to
    users in coinbase are disabled when this is specified, the pool operator
    is expected to settle debts privately with miners. This setting is an
    advanced setting for a special case and is not normally recommended.

"startdiff" :
    Starting diff that new clients are given. Default 42

"update_interval" :
    This is the frequency that stratum updates are sent out to miners and is set
    to 30 seconds by default to help perpetuate transactions for the health of
    the bitcoin network.

"version_mask" :
    This is a mask of which bits in the version number it is valid for a client
    to alter and is expressed as an hex string. Eg "00fff000" Default is
    "1fffe000".