CKPOOL + CKPROXY + libckpool by Con Kolivas

Ultra low overhead massively scalable multi-process, multi-threaded modular bitcoin mining pool, proxy, passthrough, and library in c for Linux.

CKPOOL is code provided free of charge under the GPLv3 license

---

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 capitalise 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 ckpool.
• 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:

• Simple pool.
• Simple proxy without the limitations of hashrate inherent in other proxy solutions when talking to ckpool.
• 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.
• 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.

---

BUILDING:

Building ckpool requires no dependencies outside of the basic build tools and yasm on any linux installation. Optional zmq notification support (ckpool only) requires the zmq devel library installed.

Basic build:

sudo apt-get install build-essential yasm ./configure make

Building with zmq (this is not required for ckproxy):

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

Building from git also requires autoconf and automake:

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

Binaries will be built in the src/ subdirectory. Binaries generated will be: ckpool - The main pool back end ckproxy - A link to ckpool that automatically starts it in proxy mode ckpmsg - An application for passing messages in libckpool format to ckpool notifier - An application designed to be run with bitcoind's -blocknotify to notify ckpool of block changes.

Installation is NOT required and ckpool can be run directly from the directory it's built in but it can be installed with: sudo make install

---

RUNNING:

ckpool supports the following options:

-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

-c tells ckpool to override its default configuration filename and load the specified one. If -c is not specified, ckpool looks for ckpool.conf, in proxy mode it looks for ckproxy.conf, in passthrough mode for ckpassthrough.conf and in redirector mode for ckredirector.conf

-g will start ckpool as the group ID specified.

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

-h displays the above help

-k will make ckpool shut down an existing instance of ckpool with the same name, killing it if need be. Otherwise ckpool 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 ckpool 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 will change the ckpool process name to that specified, allowing multiple different named instances to be running. By default the variant names are used: ckpool, ckproxy, ckpassthrough, ckredirector, cknode.

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

-p will start ckpool 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 ckpool for it to scale to large hashrates. Standalone mode is Optional.

-R will start ckpool 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 tells ckpool which directory to place its own communication sockets (/tmp by default)

-u Userproxy mode will start ckpool 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.

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

---

CONFIGURATION

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

Ckpool takes a json encoded configuration file in ckpool.conf by default or ckproxy.conf in proxy or passthrough mode unless specified with -c. Sample configurations for ckpool and ckproxy 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:

"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 tells ckpool this btcd is using the notifier and does not need to be polled for block changes. If no btcd is specified, ckpool will look for one on localhost:8332 with the username "user" and password "pass".

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

"btcaddress" : This is the bitcoin address to try to generate blocks to.

"btcsig" : This is an optional signature to put into the coinbase of mined blocks.

"blockpoll" : This is the frequency in milliseconds for how often to check for new network blocks and is 100 by default. It is intended to be a backup only for when the notifier is not set up and only polls if the "notify" field is not set on a btcd.

"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 minimise unnecessary communications with unauthorised 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

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

"serverurl" : This is the IP(s) to try to bind ckpool 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.

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

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

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

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

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

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

"zmqblock" : Optional interface to use for zmq blockhash notification - ckpool only. Requires use of matched bitcoind -zmqpubhashblock option. Default: tcp://127.0.0.1:28332