Private Testnet Set up¶
Some developers may want to deploy their own BitShares blockchain locally for governance, and speed reasons. This section explains how to prepare the private testnet environment and what steps to take to be a block producing node (witness node).
Table of Contents
Warning
For the private testnet, you MUST create and set up own genesis file and also, set parameters’ values into a database configuration file (config.ini). You should not connect to the mainnet nor the public testnet.
1. Installation¶
Depending on your OS, we have the Installation guides available. To see more Installation options: Go to Installation Guide.
1-1. Download the Source files¶
Let’s get started, open a new command line interface (CLI) window and go to a directory you want to download the testnet
branch files. And run the following command lines. In this example, you create a bitshares-testnet
directory.
git clone https://github.com/bitshares/bitshares-core.git bitshares-testnet cd bitshares-testnet/ git checkout testnet git submodule update --init --recursive
1-2. Initial Compilation¶
After you download a testnet branch files in a bitshares-testnet
directory, let’s build the programs. Run the following commands. This command will create two program files (witness_node and cli_wallet).
cmake . make
You will find the compiled program files in the below folders.
program name |
directory and folder |
---|---|
witness_node |
../bitshares-testnet/programs/witness_node/ |
cli_wallet |
../bitshares-testnet/programs/cli_wallet/ |
The above installation steps are the same with the public testnet installation.
2. Create a Testnet Folder¶
Create a new folder (e.g., [Testnet-Home]
) in any location you like and copy a witness_node program and a cli_wallet program there.
Open a command prompt window and switch the current directory to [Testnet-Home]
. Your folder structure should look like the below.
../[Testnet-Home]
- witness_node // program
- cli_wallet // program
3. Genesis File¶
Attention
Discussion: #1591:Add genesis-dev.json and move genesis jsons out of root source directory.
- For a Private Testnet setup, we have a discussion about a genesis-dev.json
file. This genesis-dev file can be used with no modification to create a private testnet and produce blocks on it with the init* accounts.
Note: The --create-example-genesis
option will be removed by Feature Release (201902). Read more: #1536 Remove “create-genesis-json” startup option from witness_node
3-1. Create a Genesis File for a Private Testnet¶
The genesis file is the initial state of the network. We want to create a subdirectory named genesis
and create a file within it named my-genesis.json
. In the private testnet, we have to generate each active and owner private key. Here is a sample private testnet genesis file template, copy and past into your my-genesis.json file.
../[Testnet-Home]
- witness_node // program
- cli_wallet // program
+ /[genesis] // folder
- my-genesis.json // your private testnet genesis file. You MUST set own parameter values.
3-12 Customization of the private testnet - Genesis File¶
If you want to customize the network’s initial state, edit my-genesis.json
. This allows you to control things such as:
The accounts that exist at genesis, their names and public keys
Assets and their initial distribution (including core asset)
The initial values of chain parameters
The account / signing keys of the init witnesses (or in fact any account at all).
Here is more information about a private testnet genesis file
Note
The chain ID is a hash of the genesis state. All transaction signatures are only valid for a single chain ID. So editing the genesis file will change your chain ID, and make you unable to sync with all existing chains (unless one of them has exactly the same genesis file you do).
For testing purposes, the --dbg-init-key
option will allow you to quickly create a new chain against any genesis file, by replacing the witnesses’ block production keys.
Default Genesis
The graphene code base has a default genesis block integrated that has all witnesses, committee members and funds and a single account called nathan
available from a single private key:
5KQwrPbwdL6PhXujxW37FSSQZ1JiwsST4cqQzDeyXtP79zkvFD3
3-3. Embed Genesis (optional)¶
Once you have my-genesis.json
, you may set a cmake variable like so:
cmake -DGRAPHENE_EGENESIS_JSON="$(pwd)/genesis/my-genesis.json"
and then rebuild. Note, sometimes I’ve had to clean the build and CMake cache variables in order for GRAPHENE_EGENESIS_JSON
to take effect:
make clean
find . -name "CMakeCache.txt" | xargs rm -f
find . -name "CMakeFiles" | xargs rm -Rf
cmake -DGRAPHENE_EGENESIS_JSON="$(pwd)/genesis/my-genesis.json" .
Deleting caches will reset all cmake
variables, so if you have used instructions like build-ubuntu which tells you to set other cmake
variables, you will have to add those variables to the cmake
line above.
Tip
Embedding the genesis copies the entire content of genesis.json into the witness_node binary, and additionally copies the chain ID into the cli_wallet binary. Embedded genesis allows the following simplifications to the subsequent instructions:
You do not need to specify the
my-genesis.json
file on the witness node command line, or in the witness node configuration file.You do not need to specify the chain ID on the
cli_wallet
command line when starting a new wallet.
Embedded genesis is a feature designed to make life easier for consumers of pre-compiled binaries, in exchange for slight, optional complication of the process for producing binaries.
4. Configurations¶
4-1. Create a Data Directory¶
witness_node
startup will create a witness_node_data_dir
as a default data directory. And you will find a configuration config.ini
file in the data directory.
Note
If you want to use a different folder name and directory for the data, you have to use --data-dir
option in a startup command line and set your data directory folder path, every time when you start the witness_node. Otherwise, the witness_node_data_dir
folder and another config.ini
file will be created (if it’s not existed) and the witness_node will use the data directory.
We create a new data directory for our witness.:
./witness_node --data-dir data/my-blocktestnet --genesis-json my-genesis.json --seed-nodes "[]"
// or
./witness_node --data-dir=data/my-blocktestnet --genesis-json=my-genesis.json --seed-nodes "[]"
Note:
A
data/my-blocktestnet
directory does not exist, it will be created by starting a witness node.seed-nodes = []
creates a list of empty seed nodes to avoid connecting to default hardcoded seeds.Known issue: Missing
=
sign between input parameter and value. –> This is due to a bug of a boost 1.60. If you compile with boost 1.58, the=
sign can be omitted.
The below message means the initialization is complete. It will complete nearly instantaneously with the tiny example genesis, unless you added a ton of balances. Use ctrl + c
to close the witness node.
3501235ms th_a main.cpp:165 main] Started witness node on a chain with 0 blocks.
3501235ms th_a main.cpp:166 main] Chain ID is cf307110d029cb882d126bf0488dc4864772f68d9888d86b458d16e6c36aa74b
As a result, you should get two items:
A directory named
data/my-blocktestnet
has been created (initialized) with a file namedconfig.ini
located in it.A Chain ID. It’s displayed in the message above (i.g., Chain ID).
../[Testnet-Home]
- witness_node // program
- cli_wallet // program
+ /[genesis] // folder
- my-genesis.json // your private testnet genesis file. You have to set own parameter values.
+ /[data] // data folder
+ /[my-blocktestnet]/
+ /[blockchain]
+ /[logs]
+ /[p2p]
- config.ini // configuration file
- logging.ini
4-2. Set up Configuration¶
Open the [Testnet-Home]/data/my-blocktestnet/config.ini
file and set the following settings, uncommenting them if necessary.
Example: Configuration file - config.ini
# Endpoint for P2P node to listen on
p2p-endpoint = 127.0.0.1:11010
# Endpoint for websocket RPC to listen on
rpc-endpoint = 127.0.0.1:11011
###--> For Private Testnet, add a seed node of your own
# P2P nodes to connect to on startup (may specify multiple times)
# seed_node =
###--> For Private Testnet, this value set needs to overwrite default checkpoint.
checkpoint = []
# Pairs of [BLOCK_NUM,BLOCK_ID] that should be enforced as checkpoints.
## checkpoint = ["22668518", "0159e4e600cb149e22ef960442ca331159914617"]
# File to read Genesis State from
genesis-json = genesis/my-genesis.json
# ==============================================================================
# witness plugin options
# ==============================================================================
# Enable block production, even if the chain is stale.
enable-stale-production = false
# Percent of witnesses (0-100) that must be participating in order to produce blocks
# required-participation = 33
# If start a private testnet with the default number 33, the node won't produce blocks
####--> For Private testnet, set 0
required-participation = 0
###--> For Private Testnet, set own key pairs
# Tuple of [PublicKey, WIF private key] (may specify multiple times)
private-key = ["-- generated key --","5KQwrPbwdL6PhXujxW37FSSQZ1JiwsST4cqQzDeyXtP79zkvFD3"]
# ID of witness controlled by this node (e.g. "1.6.5", quotes are required, may specify multiple times)
# witness-id =
witness-id = "1.6.1"
witness-id = "1.6.2"
witness-id = "1.6.3"
witness-id = "1.6.4"
witness-id = "1.6.5"
witness-id = "1.6.6"
witness-id = "1.6.7"
witness-id = "1.6.8"
witness-id = "1.6.9"
witness-id = "1.6.10"
witness-id = "1.6.11"
This authorizes the witness_node
to produce blocks on behalf of the listed witness-id’s, and specifies the private key needed to sign those blocks. Normally each witness would be on a different node, but for the purposes of this testnet, we will start out with all witnesses signing blocks on a single node.
Note
It’s important to activate a 2/3 majority of the witnesses defined in the genesis file.
5. Start the Testnet (Block Production)¶
Now run witness_node again:
./witness_node --data-dir data/my-blocktestnet --enable-stale-production --seed-nodes "[]"
Warning
If you want to use a different folder name and directory for the data, you have to use --data-dir
in a startup command line and set your data directory folder path, every time you start the witnesses-node. Otherwise, the witness_node_data_dir
folder will be created and be used to generate a default config.ini
file to start the witness_node!!
Note
We did not set
--genesis-json my-genesis.json
in a command line above. Because we set the genesis file namemy-genesis.json
for the private testnet in a configurationconfig.ini
file.The
--enable-stale-production
flag tells thewitness_node
to produce on a chain with zero blocks or very old blocks. We specify the--enable-stale-production
parameter on the command line as we will not normally need it (although it can also be specified in the configuration file).The empty
--seed-nodes
is added to avoid connecting to the default seed nodes hardcoded for production. (i.e., # seed-node = )Subsequent runs which connect to an existing witness node over the p2p network, or which get blockchain state from an existing data directory, do not need to have the
--enable-stale-production
flag.
6. Obtain the Chain ID¶
(When we started a witness_node for a short time to create a data directory, we also obtained a chain ID.)
The chain ID (i.g., blockchain id) is a hash of the genesis state. All transaction signatures are only valid for a single chain ID. So editing the genesis file will change your chain ID, and make you unable to sync with all existing chains (unless one of them has exactly the same genesis file you do).
For testing purposes, the --dbg-init-key
option will allow you to quickly create a new chain against any genesis file, by replacing the witnesses’ block production keys.
Important
Each wallet is specifically associated with a single chain, specified by its chain ID. This is to protect the user from (e.g., unintentionally) using a testnet wallet on the real chain.
The chain ID is printed at witness node startup. It can also be obtained by using the API to query a running witness node with the get_chain_properties
API call:
curl --data '{"jsonrpc": "2.0", "method": "get_chain_properties", "params": [], "id": 1}' http://127.0.0.1:11011/rpc && echo
This curl
command will return a short JSON object including the chain_id
.
7. CLI wallet¶
7-1. Create a new Wallet¶
We are now ready to connect a new wallet to your private testnet witness node. You must specify a chain ID and server. Keep your witness node running. Open another Command Prompt window run this command (a blank username and password will suffice):
./cli_wallet --wallet-file my-wallet.json
--chain-id cf30711----USE-OWN-CHAIN-ID---68d9888d86b458d16e6c36aa74b
--server-rpc-endpoint ws://127.0.0.1:11011 -u '' -p ''
Note
Make sure to replace the above chain ID (i.e., blockchain id)
cf307110d0...36aa74b
with your chain ID reported by yourwitness_node
. The chain-id passed to the CLI-wallet needs to match the id generated and used by thewitness node
.--server-rpc-endpoint
- The port number is how you defined (opened)--rpc-endpoint
for the witness_node.
If you receive the new >>>
prompt, it means your wallet has been executed successfully.
Fist you need to create a new password for your wallet. This password is used to encrypt all the private keys in the wallet. For more detailed instructions, see the tutorial on How to Set a password and Unlock a Cli Wallet
7-2. Gain Access to the Genesis Stake¶
In BitShares, balances are contained in accounts. To import an account that exists in the BitShares genesis into your wallet, all you need to know its name and its private key.
In this section, we use an account name nathan
We will now import into the wallet an account called nathan
(a general purpose test account) by using the import_key
command:
unlock supersecret
import_key nathan "5KQwrPbwdL6PhXujxW37FSSQZ1JiwsST4cqQzDeyXtP79zkvFD3"
Note
nathan happens to be the account name defined in the genesis file. If you had edited your my-genesies.json
file just after it was created, you could have put a different name there. Also, note that 5KQwrPbwdL...P79zkvFD3
is the private key defined in the config.ini
file.
Now we have the private key imported into the wallet but still no funds assocciated with it. Funds are stored in genesis balance objects. These funds can be claimed, with no fee, using the import_balance
command:
import_balance nathan ["5KQwrPbwdL6PhXujxW37FSSQZ1JiwsST4cqQzDeyXtP79zkvFD3"] true
As a result, we have one account (named nathan
) imported into the wallet and this account is well funded with BTS as we have claimed the funds stored in the genesis file. You can view this account information and the balance by using the below commands:
get_account nathan
list_account_balances nathan
7-3. Create Another Account¶
We will now create another account (named alpha
) so that we can transfer funds back and forth between nathan
and alpha
.
Creating a new account is always done by using an existing account - we need it because someone (i.e. the registrar) has to fund the registration fee. Also, there is the requirement for the registrar account to have a lifetime member (LTM) status. Therefore we need to upgrade the account nathan
to LTM, before we can proceed with creating other accounts.
upgrade_account nathan true
get_account nathan
In the response, next to membership_expiration_date
you should see 1969-12-31T23:59:59
. If you get 1970-01-01T00:00:00
something is wrong and nathan
has not been successfully upgraded.
We can now register an account by using nathan
as registrar. But first we need to generate the public key for the new account. We do it by using the suggest_brain_key
command.
And the response should be something similar to this
suggest_brain_key
{
"brain_priv_key": "MYAL SOEVER UNSHARP PHYSIC JOURNEY SHEUGH BEDLAM WLOKA FOOLERY GUAYABA DENTILE RADIATE TIEPIN ARMS FOGYISH COQUET",
"wif_priv_key": "5JDh3XmHK8CDaQSxQZHh5PUV3zwzG68uVcrTfmg9yQ9idNisYnE",
"pub_key": "BTS78CuY47Vds2nfw2t88ckjTaggPkw16tLhcmg4ReVx1WPr1zRL5"
}
We can now register an account. The register_account
command allows you to register an account using only a public key:
register_account alpha BTS78CuY47Vds2nfw2t88ckjTaggPkw16tLhcmg4ReVx1WPr1zRL5 BTS78CuY47Vds2nfw2t88ckjTaggPkw16tLhcmg4ReVx1WPr1zRL5 nathan nathan 0 true
Use a public key
pub_key
which you just created bysuggest_brain_key
.
Transfer funds between accounts¶
transfer nathan alpha 100000 CORE "here is the cash" true
list_account_balances alpha
The text here is some cash
is an arbitrary memo you can attatch to a transfer. If you don’t need it, just use ""
instead.
We can now open a new wallet for alpha user:
import_key alpha 5JDh3XmHK8CDaQSxQZHh5PUV3zwzG68uVcrTfmg9yQ9idNisYnE
upgrade_account alpha true
create_witness alpha "http://www.alpha" true
Use a private key
wif_priv_key
which you just created bysuggest_brain_key
.
The get_private_key
command allows us to obtain the WIF private key corresponding to a public key. The private key must already be in the wallet:
get_private_key BTS78CuY47Vds2nfw2t88ckjTaggPkw16tLhcmg4ReVx1WPr1zRL5
> You can try to make sure your suggest_brain_key
outputs key pair. You should get the same pair of keys set.
8. Create Committee Members¶
8-1. Creating members¶
create_account_with_brain_key
create_account_with_brain_key com0 com0 nathan nathan true
create_account_with_brain_key com1 com1 nathan nathan true
create_account_with_brain_key com2 com2 nathan nathan true
create_account_with_brain_key com3 com3 nathan nathan true
create_account_with_brain_key com4 com4 nathan nathan true
create_account_with_brain_key com5 com5 nathan nathan true
create_account_with_brain_key com6 com6 nathan nathan true
8-2 Upgrading members¶
Since only lifetime members can be committee members, we need to fund these accounts transfer
and upgrade upgrade_account
them accordingly:
transfer nathan com0 100000 CORE "some cash" true
transfer nathan com1 100000 CORE "some cash" true
transfer nathan com2 100000 CORE "some cash" true
transfer nathan com3 100000 CORE "some cash" true
transfer nathan com4 100000 CORE "some cash" true
transfer nathan com5 100000 CORE "some cash" true
transfer nathan com6 100000 CORE "some cash" true
upgrade_account com0 true
upgrade_account com1 true
upgrade_account com2 true
upgrade_account com3 true
upgrade_account com4 true
upgrade_account com5 true
upgrade_account com6 true
8-3 Registering as committee member¶
We can apply for committee with create_committee_member:
create_committee_member
create_committee_member com0 "http://www.com0" true create_committee_member com1 "http://www.com1" true create_committee_member com2 "http://www.com2" true create_committee_member com3 "http://www.com3" true create_committee_member com4 "http://www.com4" true create_committee_member com5 "http://www.com5" true create_committee_member com6 "http://www.com6" true
8-4 Voting with faucet account¶
All we need to do know is vote for our own committee members:
vote_for_committee_member
vote_for_committee_member nathan com0 true true
vote_for_committee_member nathan com1 true true
vote_for_committee_member nathan com2 true true
vote_for_committee_member nathan com3 true true
vote_for_committee_member nathan com4 true true
vote_for_committee_member nathan com5 true true
vote_for_committee_member nathan com6 true true
propose_parameter_change com0 {"block_interval" : 6} true
9. Set up the Second Node¶
If you want to set up a second node (with the same genesis file) and connect it to the first node by using the p2p-endpoint
of the first node as the seed-node
for the second. The below are example settings.
Node-001: config.ini
p2p-endpoint = 127.0.0.1:11010
# seed-node = // add a seed node of your own
rpc-endpoint = 127.0.0.1:11011
Node-002: config.ini
Set the Node-001’s
p2p-endpoint
as the Node-002’sseed-node
.
p2p-endpoint = 127.0.0.1:11015
seed-node = 127.0.0.1:11010
rpc-endpoint = 127.0.0.1:11020