Install BTC.COM Pool

Supported OS

Ubuntu 14.04 LTS, 64 Bits
Ubuntu 16.04 LTS, 64 Bits
macOS Sierra or later

BTCPool has a known compatibility issue with 32-bit operating systems. btccom#38

If you want to run BTCPool on a 32-bit operating system, you must fix the problem first. Or, choose a 64-bit operating system.

Build

[Need fix] If you are the first time build btcpool, you could run bash install/install_btcpool.sh instead of exec these shell commands one by one.

cd /work
wget https://raw.githubusercontent.com/btccom/btcpool/master/install/install_btcpool.sh
bash ./install_btcpool.sh

Install dependency

Ubuntu

apt-get update
apt-get install -y build-essential autotools-dev libtool autoconf automake pkg-config cmake \
                   openssl libssl-dev libcurl4-openssl-dev libconfig++-dev \
                   libboost-all-dev libgmp-dev libmysqlclient-dev libzookeeper-mt-dev \
                   libzmq3-dev libgoogle-glog-dev libhiredis-dev zlib1g zlib1g-dev \
                   libprotobuf-dev protobuf-compiler

Notice: It is no longer recommended to install libevent-dev from the software source. The release and stable version of libevent will cause a dead lock bug in sserver (issue #75). It is recommended that you manually build the libevent from its master branch with commands at below.

Sometimes one or two packages will fail due to dependency problems, and you can try aptitude.

apt-get update
apt-get install -y aptitude

aptitude install build-essential autotools-dev libtool autoconf automake pkg-config cmake \
                   openssl libssl-dev libcurl4-openssl-dev libconfig++-dev \
                   libboost-all-dev libgmp-dev libmysqlclient-dev libzookeeper-mt-dev \
                   libzmq3-dev libgoogle-glog-dev libhiredis-dev zlib1g zlib1g-dev \
                   libprotobuf-dev protobuf-compiler

# Input `n` if the solution is `NOT INSTALL` some package.
# Eventually aptitude will give a solution that downgrade some packages to allow all packages to be installed.

build libevent from its master branch

Notice: the release and stable version of libevent will cause a dead lock bug in sserver (issue #75), so use the code from the master branch.

git clone https://github.com/libevent/libevent.git
cd libevent
./autogen.sh
./configure --disable-shared
make && make install

build librdkafka-v0.9.1

wget https://github.com/edenhill/librdkafka/archive/0.9.1.tar.gz
tar zxvf 0.9.1.tar.gz
cd librdkafka-0.9.1
./configure && make && make install

# if you want to keep static libraries only
rm -v /usr/local/lib/librdkafka*.so /usr/local/lib/librdkafka*.so.*

macOS

Please install brew first.

brew install cmake openssl libconfig boost mysql zmq gmp libevent zookeeper librdkafka hiredis

glog-v0.3.4

wget https://github.com/google/glog/archive/v0.3.4.tar.gz
tar zxvf v0.3.4.tar.gz
cd glog-0.3.4
./configure && make && make install

Build BTCPool

CMake Options

There are some cmake options that can change the behavior of compiler, enable or disable optional features of BTCPool, or link BTCPool with different blockchains.

Option Name	Values	Default Value	Description
CMAKE_BUILD_TYPE	Release, Debug	Release	Build type
JOBS	A number, between 1 to your CPU cores' number.	1	Concurrent jobs when building blockchain's source code that linking to BTCPool.
CHAIN_TYPE	BTC, BCH, BSV, UBTC, SBTC, LTC, ZEC	No default value, you must define it.	Blockchain's type that you want to BTCPool linking to.
CHAIN_SRC_ROOT	A path of dir, such as `/work/bitcoin`.	No default value, you must define it.	The path of blockchain's source code that you want to BTCPool linking to.
OPENSSL_ROOT_DIR	A path of dir, such as `/usr/local/opt/openssl`.	No definition is required by default, and cmake will automatically look for it.	The path of `openssl`'s source code. The macOS user may need to define it if cmake cannot find it automatically.
POOL__WORK_WITH_STRATUM_SWITCHER	ON, OFF	OFF	Build a special version of pool's stratum server, so you can run it with a stratum switcher. See also: Stratum Switcher.
POOL__USER_DEFINED_COINBASE	ON, OFF	OFF	Build a special version of pool that allows user-defined content to be inserted into coinbase input. TODO: add documents about it.
POOL__USER_DEFINED_COINBASE_SIZE	A number (bytes), from 1 to the maximum length that coinbase input can hold	10	The size of user-defined content that inserted into coinbase input. No more than 20 bytes is recommended.
POOL__INSTALL_PREFIX	A path of dir, such as `/work/btcpool.btc`.	/work/bitcoin.[btc\|bch\|sbtc\|ubtc]	The install path of `make install`. The deb package that generated by `make package` will install to the same path.
POOL__GENERATE_DEB_PACKAGE	ON, OFF	OFF	When it enabled, you can generate a deb package with `make package`.

Building commands (example)

build BTCPool that linking to Bitcoin

mkdir /work
cd /work
wget -O bitcoin-0.16.0.tar.gz https://github.com/bitcoin/bitcoin/archive/v0.16.0.tar.gz
tar zxf bitcoin-0.16.0.tar.gz

git clone https://github.com/btccom/btcpool.git
cd btcpool
mkdir build
cd build

# Release build with 4 jobs:
cmake -DJOBS=4 -DCHAIN_TYPE=BTC -DCHAIN_SRC_ROOT=/work/bitcoin-0.16.0 ..
make -j4

# Release build at macOS:
cmake -DCHAIN_TYPE=BTC -DCHAIN_SRC_ROOT=/work/bitcoin-0.16.0 -DOPENSSL_ROOT_DIR=/usr/local/opt/openssl ..
make

# Debug build:
cmake -DCMAKE_BUILD_TYPE=Debug -DCHAIN_TYPE=BTC -DCHAIN_SRC_ROOT=/work/bitcoin-0.16.0 ..
make

# Build a special version of pool's stratum server, so you can run it with a stratum switcher:
# Important: This version of sserver CANNOT run independently, `Illegal params` will throw
# if you try to connect it directly without using StratumSwitcher.
# Don't use `-DPOOL__WORK_WITH_STRATUM_SWITCHER=ON` if you don't know what StratumSwitcher is.
cmake -DJOBS=4 -DCHAIN_TYPE=BTC -DCHAIN_SRC_ROOT=/work/bitcoin-0.16.0 -DPOOL__WORK_WITH_STRATUM_SWITCHER=ON ..
make -j4

build BTCPool that linking to BitcoinCash ABC

mkdir /work
cd /work
wget -O bitcoin-abc-0.18.5.tar.gz https://github.com/Bitcoin-ABC/bitcoin-abc/archive/v0.18.5.tar.gz
tar zxf bitcoin-abc-0.18.5.tar.gz

git clone https://github.com/btccom/btcpool.git
cd btcpool
mkdir build
cd build

# Release build with 4 jobs:
cmake -DJOBS=4 -DCHAIN_TYPE=BCH -DCHAIN_SRC_ROOT=/work/bitcoin-abc-0.18.5 ..
make -j4

# Release build at macOS:
cmake -DCHAIN_TYPE=BCH -DCHAIN_SRC_ROOT=/work/bitcoin-abc-0.18.5 -DOPENSSL_ROOT_DIR=/usr/local/opt/openssl ..
make

# Debug build:
cmake -DCMAKE_BUILD_TYPE=Debug -DCHAIN_TYPE=BCH -DCHAIN_SRC_ROOT=/work/bitcoin-abc-0.18.5 ..
make

# Build a special version of pool's stratum server, so you can run it with a stratum switcher:
# Important: This version of sserver CANNOT run independently, `Illegal params` will throw
# if you try to connect it directly without using StratumSwitcher.
# Don't use `-DPOOL__WORK_WITH_STRATUM_SWITCHER=ON` if you don't know what StratumSwitcher is.
cmake -DJOBS=4 -DCHAIN_TYPE=BCH -DCHAIN_SRC_ROOT=/work/bitcoin-abc-0.18.5 -DPOOL__WORK_WITH_STRATUM_SWITCHER=ON ..
make -j4

Note: bitcoin-abc-0.17.1 and earlier are incompatible with current BTCPool, you will meet this error:

/work/bitcoin-abc-0.17.1/src/crypto/libbitcoin_crypto_base.a not exists!

build BTCPool that linking to Bitcoin SV

mkdir /work
cd /work
wget -O bitcoin-sv-0.1.0.tar.gz https://github.com/bitcoin-sv/bitcoin-sv/archive/v0.1.0.tar.gz
tar zxf bitcoin-sv-0.1.0.tar.gz

git clone https://github.com/btccom/btcpool.git
cd btcpool
mkdir build
cd build

# Release build with 4 jobs:
cmake -DJOBS=4 -DCHAIN_TYPE=BSV -DCHAIN_SRC_ROOT=/work/bitcoin-sv-0.1.0 ..
make -j4

# Release build at macOS:
cmake -DCHAIN_TYPE=BSV -DCHAIN_SRC_ROOT=/work/bitcoin-sv-0.1.0 -DOPENSSL_ROOT_DIR=/usr/local/opt/openssl ..
make

# Debug build:
cmake -DCMAKE_BUILD_TYPE=Debug -DCHAIN_TYPE=BSV -DCHAIN_SRC_ROOT=/work/bitcoin-sv-0.1.0 ..
make

# Build a special version of pool's stratum server, so you can run it with a stratum switcher:
# Important: This version of sserver CANNOT run independently, `Illegal params` will throw
# if you try to connect it directly without using StratumSwitcher.
# Don't use `-DPOOL__WORK_WITH_STRATUM_SWITCHER=ON` if you don't know what StratumSwitcher is.
cmake -DJOBS=4 -DCHAIN_TYPE=BSV -DCHAIN_SRC_ROOT=/work/bitcoin-sv-0.1.0 -DPOOL__WORK_WITH_STRATUM_SWITCHER=ON ..
make -j4

build BTCPool that linking to UnitedBitcoin

mkdir /work
cd /work
wget -O UnitedBitcoin-2.2.0.3.tar.gz https://github.com/UnitedBitcoin/UnitedBitcoin/archive/v2.2.0.3.tar.gz
tar zxf UnitedBitcoin-2.2.0.3.tar.gz

# install libdb that UnitedBitcoin's wallet required
apt-get install -y software-properties-common
add-apt-repository -y ppa:bitcoin/bitcoin
apt-get -y update
apt-get install -y libdb4.8-dev libdb4.8++-dev

# UnitedBitcoin will build failed with `--disable-wallet`, so we have to build it manually with wallet
cd UnitedBitcoin-2.2.0.3
./autogen.sh
./configure --disable-bench --disable-tests
make -j4

cd ..
git clone https://github.com/btccom/btcpool.git
cd btcpool
mkdir build
cd build

# Release build with 4 jobs:
cmake -DJOBS=4 -DCHAIN_TYPE=UBTC -DCHAIN_SRC_ROOT=/work/UnitedBitcoin-2.2.0.3 ..
make -j4

# Release build at macOS:
cmake -DCHAIN_TYPE=UBTC -DCHAIN_SRC_ROOT=/work/UnitedBitcoin-2.2.0.3 -DOPENSSL_ROOT_DIR=/usr/local/opt/openssl ..
make

# Debug build:
cmake -DCMAKE_BUILD_TYPE=Debug -DCHAIN_TYPE=UBTC -DCHAIN_SRC_ROOT=/work/UnitedBitcoin-2.2.0.3 ..
make

# Build a special version of pool's stratum server, so you can run it with a stratum switcher:
# Important: This version of sserver CANNOT run independently, `Illegal params` will throw
# if you try to connect it directly without using StratumSwitcher.
# Don't use `-DPOOL__WORK_WITH_STRATUM_SWITCHER=ON` if you don't know what StratumSwitcher is.
cmake -DJOBS=4 -DCHAIN_TYPE=UBTC -DCHAIN_SRC_ROOT=/work/UnitedBitcoin-2.2.0.3 -DPOOL__WORK_WITH_STRATUM_SWITCHER=ON ..
make -j4

build BTCPool that linking to SuperBitcoin

Warning: Support for SuperBitcoin is outdated and lacks maintenance. Existing code may not be compatible with the current SuperBitcoin blockchain.

In addition, if you have a plan to maintain the SuperBitcoin supporting, you are welcome to make a pull request.

mkdir /work
cd /work
wget -O SuperBitcoin-0.17.1.tar.gz https://github.com/superbitcoin/SuperBitcoin/archive/v0.17.1.tar.gz
tar zxf SuperBitcoin-0.17.1.tar.gz

git clone https://github.com/btccom/btcpool.git
cd btcpool
mkdir build
cd build

# Release build with 4 jobs:
cmake -DJOBS=4 -DCHAIN_TYPE=SBTC -DCHAIN_SRC_ROOT=/work/SuperBitcoin-0.17.1 ..
make -j4

# Release build at macOS:
cmake -DCHAIN_TYPE=SBTC -DCHAIN_SRC_ROOT=/work/SuperBitcoin-0.17.1 -DOPENSSL_ROOT_DIR=/usr/local/opt/openssl ..
make

# Debug build:
cmake -DCMAKE_BUILD_TYPE=Debug -DCHAIN_TYPE=SBTC -DCHAIN_SRC_ROOT=/work/SuperBitcoin-0.17.1 ..
make

# Build a special version of pool's stratum server, so you can run it with a stratum switcher:
# Important: This version of sserver CANNOT run independently, `Illegal params` will throw
# if you try to connect it directly without using StratumSwitcher.
# Don't use `-DPOOL__WORK_WITH_STRATUM_SWITCHER=ON` if you don't know what StratumSwitcher is.
cmake -DJOBS=4 -DCHAIN_TYPE=SBTC -DCHAIN_SRC_ROOT=/work/SuperBitcoin-0.17.1 -DPOOL__WORK_WITH_STRATUM_SWITCHER=ON ..
make -j4

build BTCPool that linking to Litecoin

mkdir /work
cd /work
wget -O litecoin-0.16.3.tar.gz https://github.com/litecoin-project/litecoin/archive/v0.16.3.tar.gz
tar zxf litecoin-0.16.3.tar.gz

git clone https://github.com/btccom/btcpool.git
cd btcpool
mkdir build
cd build

# Release build with 4 jobs:
cmake -DJOBS=4 -DCHAIN_TYPE=LTC -DCHAIN_SRC_ROOT=/work/litecoin-0.16.3 ..
make -j4

# Debug build:
cmake -DCMAKE_BUILD_TYPE=Debug -DCHAIN_TYPE=LTC -DCHAIN_SRC_ROOT=/work/litecoin-0.16.3 ..
make -j4

build BTCPool that linking to ZCash

mkdir /work
cd /work
wget -O zcash-2.0.4.tar.gz https://github.com/zcash/zcash/archive/v2.0.4.tar.gz
tar zxf zcash-2.0.4.tar.gz

git clone https://github.com/btccom/btcpool.git
cd btcpool
mkdir build
cd build

# Release build with 4 jobs:
cmake -DJOBS=4 -DCHAIN_TYPE=ZEC -DCHAIN_SRC_ROOT=/work/zcash-2.0.4 ..
make -j4

# Debug build:
cmake -DCMAKE_BUILD_TYPE=Debug -DCHAIN_TYPE=ZEC -DCHAIN_SRC_ROOT=/work/zcash-2.0.4 ..
make -j4

How about ETH/ETC/Beam/Grin/Decred/Bytom?

Please use the build that linking to Bitcoin (-DCHAIN_TYPE=BTC).

Init btcpool

init the running folders

Now create folder for btcpool, if you are going to run all service in one machine you could run install/init_folders.sh as below.

cd /work/btcpool/build
bash ../install/init_folders.sh

setup full-nodes

Before starting btcpool's services, at least one bitcoin full-node needs to be setup. Which full-node to use depends on the blockchain you want to mining.

Also start Rsk node or Namecoin node if merged mining for any of those chains.

The following are some dockerfiles of full-nodes:

Bitcoin: docker for Bitcoin Core
BitcoinCash: docker for Bitcoin ABC
UnitedBitcoin: docker for UnitedBitcoin
SuperBitcoin: docker for SuperBitcoin
Litecoin: docker for Litecoin Core
Namecoin: docker for Namecoin Core
RSK: docker for RSKJ
Ethereum:
- docker for Parity
- docker for Geth
Decred: docker for dcrd
Beam: docker for Beam Node

If you want to merge-mining more than one chains that follow Bitcoin Merged Mining Specification (likes Namecoin, ElastOS, etc), you can running a Merged Mining Proxy and let the pool's nmcauxmaker connect to it.

init MySQL databases & tables

The pool's statshttpd, slparser and blkmaker will write miners', users' & blockchains' information to mysql. We recommend that you create two databases and import the corresponding tables.

# create database `bpool_local_db`, `bpool_local_stats_db`
# and import tables with mysql command-line client.
cd /work/btcpool/install
mysql -h xxx -u xxx -p

CREATE DATABASE bpool_local_db;
USE bpool_local_db;
-- for BTC/BCH/BSV/UBTC/SBTC/LTC/ZEC
SOURCE bpool_local_db.sql;
-- for other chains (use one of them)
SOURCE bpool_local_db_BEAM.sql;
SOURCE bpool_local_db_Bytom.sql;
SOURCE bpool_local_db_Decred.sql;
SOURCE bpool_local_db_ETH.sql;
SOURCE bpool_local_db_Grin.sql;

CREATE DATABASE bpool_local_stats_db;
USE bpool_local_stats_db;
SOURCE bpool_local_stats_db.sql;

(optional) install Redis

If you want to install Redis as your statshttpd's optional storage, refer to .

User list API

You need to implement a HTTP API for stratum server (sserver). The API is use to fetch user list in incremental model. Stratum Server will call this API every few seconds, interval is about 10 seconds. When Stratum Server start, it will fetch again and again util no more users.

Should works as below.

#
# `last_id` is the offset. pagesize is 5. total user count is 8.
#
$ curl http://xxx.xxx.xxx/GetUserList?last_id=0
{"err_no":0,"err_msg":null,"data":{"litianzhao":1,"spica":2,"fazhu":3,"kevin":4,"kevin1":5}}

# fetch next page
$ curl http://xxx.xxx.xxx/GetUserList?last_id=5
{"err_no":0,"err_msg":null,"data":{"kevin2":6,"kevin3":7,"Miles":8}}

# fetch next page, no more users
$ curl http://xxx.xxx.xxx/GetUserList?last_id=8
{"err_no":0,"err_msg":null,"data":{}}

There is a demo for the API: btccom#16 (comment)

There are more reference implementations here, including a user list with automatic registration enabled and a user list with POOL__USER_DEFINED_COINBASE=ON: install/api-sample

use `supervisor` to manager services.

#
# install supervisor
#
apt-get install supervisor

#
# change open file limits
# (add 'minfds=65535' in the [supervisord] section of supervisord.conf)
#
cat /etc/supervisor/supervisord.conf | grep -v 'minfds\s*=' | sed '/\[supervisord\]/a\minfds=65535' | tee /etc/supervisor/supervisord.conf
#
# maker the change effective
#
service supervisor restart


#
# copy processes' config files for supervisor
#
cd /work/btcpool/build/install/supervisord/

################################################################################
# for common server
################################################################################
cp gbtmaker.conf      /etc/supervisor/conf.d
cp jobmaker.conf      /etc/supervisor/conf.d
cp blkmaker.conf      /etc/supervisor/conf.d
cp sharelogger.conf   /etc/supervisor/conf.d
#
# if you need to enable watch other pool's stratum job. poolwatcher will 
# generate empty getblocktemplate when they find a new height stratum job 
# from other pools. this could reduce pool's orphan block rate.
#
cp poolwatcher.conf   /etc/supervisor/conf.d
#
# enable namecoin merged mining
#
cp nmcauxmaker.conf   /etc/supervisor/conf.d
#
# enable rsk merged mining
#
cp ../install/supervisord/gwmaker.conf   /etc/supervisor/conf.d

#
# start services: gbtmaker, jobmaker, blkmaker, sharelogger...
#
$ supervisorctl
> reread
> update
> status


#
# start your stratum server(see below) and add some miners to the pool, after make
# some shares than start 'slparser' & 'statshttpd'
#
cp slparser.conf      /etc/supervisor/conf.d
cp statshttpd.conf    /etc/supervisor/conf.d

# start services: slparser, statshttpd
$ supervisorctl
> reread
> update
> status


################################################################################
# for stratum server
################################################################################
cp sserver.conf       /etc/supervisor/conf.d

$ supervisorctl
> reread
> update
> status

mining-coin switcher

StratumSwitcher is a BTCPool's module that writed by golang. It provides a per user's mining-coin switching capability controlled by the user self or a pool administrator.

There are 3 processes to provide the capability:

~~StratumSwitcher~~ (Deprecated. Use sserver itself to achieve the same features.)
Switcher API Server
Init User Coin

A zookeeper is needed as a notification channel, and a new user-coin-map API need be provided to the Switcher API Server.

The module currently has only Chinese documents. Welcome to translate it and initiate a pull request.

Tips: sserver currently has all features of StratumSwitcher built in and is more stable than StratumSwitcher. Therefore, it is not recommended to use StratumSwitcher anymore.

But you still need the Switcher API Server and Init User Coin from the btcpool-go-modules repo to achieve the chain switching.

Here is an example of a sserver configuration file that supports chain switching: sserver(multi-chains).cfg.

Upgrade btcpool

Check release note and upgrade guide. Maybe add some config options to config file or change something of database table.

Get the latest codes and rebuild:

cd /work/btcpool/build
git pull
cmake ..
make

use supervisorctl to restart your services:

$ supervisorctl
> restart xxxx

Incompatible upgrade

Upgrading to BTCPool 2.3.0 requires additional operations on sharelogger, slparser and statshttpd due to incompatible sharelog format changes.

See UPGRADE-BTCPool.md for more information.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

INSTALL-BTCPool.md

INSTALL-BTCPool.md

Install BTC.COM Pool

Build

Install dependency

Ubuntu

macOS

Build BTCPool

CMake Options

Building commands (example)

Init btcpool

init the running folders

setup full-nodes

init MySQL databases & tables

(optional) install Redis

User list API

use `supervisor` to manager services.

mining-coin switcher

Upgrade btcpool

Incompatible upgrade

Files

INSTALL-BTCPool.md

Latest commit

History

INSTALL-BTCPool.md

File metadata and controls

Install BTC.COM Pool

Build

Install dependency

Ubuntu

macOS

Build BTCPool

CMake Options

Building commands (example)

Init btcpool

init the running folders

setup full-nodes

init MySQL databases & tables

(optional) install Redis

User list API

use supervisor to manager services.

mining-coin switcher

Upgrade btcpool

Incompatible upgrade

use `supervisor` to manager services.