Run a Private Cluster on the QuarkChain Testnet 2.0

zgw edited this page Feb 2, 2019 · 39 revisions

The use of Testnet 2.0 is subject to our terms and conditions available at:

Quick Start - Use Docker Image to Start a Cluster and Mining

Here we provide detailed instructions for running a cluster and starting the mining process using a pre-built docker image. If you are interested in building everything from scratch, please refer to this Dockerfile for more details.

# NOTE the version should be in sync with the release version, e.g. qcgg/pyquarkchain:testnet2.4.0
$ docker pull qcgg/pyquarkchain:testnet<version> 

# recommend using some window management tool to start
# different programs, for example `screen` or `tmux`.
$ docker run -it -p 38291:38291 -p 38391:38391 -p 38491:38491 -p 38291:38291/udp qcgg/pyquarkchain:testnet<version> 
# if you already have synced data available, can mount it during running docker (note the -v flag)
$ docker run -v /path/to/data:/code/pyquarkchain/quarkchain/cluster/qkc-data/testnet24 -it -p 38291:38291 -p 38391:38391 -p 38491:38491 -p 38291:38291/udp qcgg/pyquarkchain:testnet<version> 

# (optional) if you want to download data quickly without validating the blocks,
# you can download a snapshot of the database by running the following command.
# Every 12 hours a snapshot of the database will be taken and uploaded by the QuarkChain team.
# Once you start your cluster using the downloaded database your cluster only need to sync
# the blocks mined in the past 12 hours or less.
curl$(curl -s --output data.tar.gz && tar xvfz data.tar.gz
mv data /path/to/data  # then mount the data folder as in previous "docker run" command

# INSIDE the container
# IMPORTANT: update coinbase address for mining
# refer to [Configure the Network] section( if unclear
# Use the following command or directly modify `testnet/2.4/cluster_config_template.json`
/code/pyquarkchain# python3 quarkchain/tools/
# start the cluster
/code/pyquarkchain# python3 quarkchain/cluster/ --cluster_config /code/pyquarkchain/testnet/2.4/cluster_config_template.json

# to start mining in another screen (outside of container)
# note this is only a sample mining program. feel free to change 
# `` and ``
# for example, to disable debug print, should change `Miner.mine_loop` constructor
# arg in ``
$ docker ps  # find container ID
$ docker exec -it <container ID> quarkchain/tools/ -c /code/pyquarkchain/testnet/2.4/cluster_config_template.json -p 8 -h localhost

# Or, you can specify the full shard key which you want to mine, the command should be:
$ docker exec -it <container ID> python3 quarkchain/tools/ --config /code/pyquarkchain/testnet/2.4/cluster_config_template.json --worker 1 --shard <full shard key>

Configure the Network

First, you'll need to set up the configuration of your network, which all nodes need to be aware of and agree upon. We provide an example config JSON in the repo (testnet/2.4/cluster_config_template.json). Note that many parameters in the config are part the consensus, please be very cautious when changing them. For example, COINBASE_AMOUNT is one such parameter, changing it to another value effectively creates a fork in the network.

To set up mining, you need to open the config and specify your own coinbase address in each shard (under QUARKCHAIN.CHAINS[].COINBASE_ADDRESS) or the root chain (under QUARKCHAIN.ROOT.COINBASE_ADDRESS).

Note: The coinbase address you copied should start from the 3rd character. Please remove the first two characters "0x" from the coinbase address.

Following is a snippet of the config for a single shard.

                "CONSENSUS_TYPE": "POW_ETHASH",
                "CONSENSUS_CONFIG": {
                    "TARGET_BLOCK_TIME": 10,
                    "REMOTE_MINE": true
                "GENESIS": {
                    "ROOT_HEIGHT": 0,
                    "VERSION": 0,
                    "HEIGHT": 0,
                    "HASH_PREV_MINOR_BLOCK": "0000000000000000000000000000000000000000000000000000000000000000",
                    "HASH_MERKLE_ROOT": "0000000000000000000000000000000000000000000000000000000000000000",
                    "EXTRA_DATA": "497420776173207468652062657374206f662074696d65732c206974207761732074686520776f727374206f662074696d65732c202e2e2e202d20436861726c6573204469636b656e73",
                    "TIMESTAMP": 1519147489,
                    "DIFFICULTY": 3000,
                    "GAS_LIMIT": 12000000,
                    "NONCE": 0,
                    "ALLOC": {}
                "COINBASE_ADDRESS":  "D50F23E410711C1391F5Ef88fC11245e564c76840000EF5e", 
                "COINBASE_AMOUNT": 5,
                "GAS_LIMIT_EMA_DENOMINATOR": 1024,
                "GAS_LIMIT_ADJUSTMENT_FACTOR": 1024,
                "GAS_LIMIT_MINIMUM": 5000,
                "GAS_LIMIT_MAXIMUM": 9223372036854775807,

Note the coinbase address is your Quarkchain wallet address (20-byte recipient + 4-byte shard key). If you do not have one, please create one from our online testnet wallet

Testnet 2.0 mining configuration

Chains Hash Algorithm Target Block Time
Root Chain Ethash with Guardian 60 seconds
4 shards Ethash 10 seconds
2 shards Double Sha256 10 seconds
2 shards Qkchash 10 seconds
Chain Shard Hash Algo Parameter (-s/--shards) for
0 0 Ethash 1
1 0 Ethash 65537
2 0 Ethash 131073
3 0 Ethash 196609
4 0 Double Sha256 262146
4 1 Double Sha256 262147
5 0 Qkchash 327682
5 1 Qkchash 327683

Launch a Private Cluster

With the mining state defines in the above JSON file, you can start running the cluster with P2P network on a single machine. The default cluster has 8 shards and 8 slaves.

python3 quarkchain/cluster/ --cluster_config /path/to/cluster_config_template.json
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.