ckpool/README

CKPOOL + CKDB + libckpool by Con Kolivas and Andrew Smith.

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


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


---
BUILDING:

Building ckpool standalone without ckdb has no dependencies outside of the
basic build tools on any linux installation.

sudo apt-get install build-essential
./configure --without-ckdb
make


Building with ckdb requires installation of the postgresql development library.

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


Building from git also requires autoconf and automake

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


Binaries will be built in the src/ subdirectory.


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


It is anticipated that pool operators wishing to set up a full database based
installation of ckpool+ckdb 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: