asicseer-pool: A C repository from MiningCryptoLive

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.
* 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)

---
BUILDING:

** NOTE from Calin: The below is no longer accurate since we switched the
** codebase to use cmake instead of autotools.

Building asicseer-pool standalone without asicseer-db has no dependencies
outside of the basic build tools on any Linux installation.

sudo apt-get install build-essential yasm libzmq3-dev
./configure --without-asicseer-db
make

** NOTE from Calin: The below is no longer accurate since we have removed
** asicseer-db.

Building with asicseer-db requires installation of the postgresql, gsl and ssl
development libraries.

sudo apt-get install build-essential yasm libzmq3-dev libpq-dev libgsl-dev
./configure --with-asicseer-db
make

older distributions may instead require a different version of gsl:
sudo apt-get install build-essential libpq-dev libgsl0ldbl libgsl0-dev yasm

N.B.: asicseer-db also requires libssl-dev but libpq-dev depends on it and
installs it.

Building from git also requires autoconf and automake

sudo apt-get install build-essential yasm libzmq3-dev libpq-dev libgsl-dev autoconf automake libtool
./autogen.sh
./configure
make

Binaries will be built in the src/ subdirectory. Binaries generated will be:
asicseer-pool - The main pool back-end.
asicseer-db - The pool's database (only if ./configure --with-asicseer-db).
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 but it can be installed with:
sudo make install

It is anticipated that pool operators wishing to set up a full database based
installation of asicseer-pool+asicseer-db will be familiar with setting up
postgresql and associated permissions to the directories where the various
processes will communicate with each other and a web server so these will not be
documented.

---
RUNNING:

asicseer-pool supports the following options:

-A Standalone mode tells asicseer-pool not to try to communicate with
asicseer-db or log any asicseer-db requests in the rotating db logs it would
otherwise store. All users are automatically accepted without any attempt to
authorize users in any way. This option is explicitly enabled when built without
db support.

-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

-d <DB-NAME> tells asicseer-pool what the name of the db process is that it should
speak to, otherwise it will look for asicseer-db.
This option does not exist when built without db support.

-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 <DB-SOCKDIR> tells asicseer-pool which directory to look for the asicseer-db
socket to talk to.
This option does not exist when built without asicseer-db support.

-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.

asicseer-db takes the following options:

ckpmsg and notifier support the -n, -p and -s options

---
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".

MiningCryptoLive/asicseer-pool