How to create a custom Starcoin network
starcoin supports running a user-defined blockchain network, which is convenient for users to build a private chain for testing or secondary development.
There are six built-in networks in
test, dev, halley, proxima, barnard, main.
dev are for local development,
barnard are the test networks, and the
main network is the official network.
Next, we will introduce how to build the Starcoin private network.
Initialize custom network
starcoin_generator command is used to generate genesis configuration files and genesis blocks.
Generate genesis configuration file
starcoin_generator -n <CHAIN_NAME>:<CHAIN_ID> --genesis-config <GENESIS_CONFIG> genesis_config
genesis_configsubcommand is used to generate the genesis configuration file.
- To initialize and run a custom blockchain network, you need to use the
-n, --netoption to specify the name of the chain and the id of the chain. The parameters are concatenated by
CHAIN_NAMErepresents the name of the chain, which will be used as the name of the data directory.
CHAIN_IDrepresents the id of the chain, of type
--genesis_configspecifies the configuration file used to generate the genesis block. The parameter can use the built-in blockchain network name, indicating that the network configuration is reused, such as
halley; it can also be the path of the configuration file.
For example, to generate a custom network named
my_chain with id
starcoin_generator -n my_chain:123 --genesis-config halley genesis_config
This command uses the built-in
halley network configuration as a template and generates a configuration file named
genesis_config.json in the
Parameters in the
~/.starcoin/my_chain/genesis_config.json file can be modified with an editor.
Note: If you don't want the configuration file to be generated in the default
~/.starcoin/<CHAIN_NAME> directory, you can also specify the directory with the
Generate genesis block
genesis subcommand is used to generate the genesis block.
starcoin_generator -n my_chain:123 genesis
This command generates the genesis block according to the genesis configuration file generated earlier.
The genesis configuration file in the above example is
~/.starcoin/my_chain/genesis_config.json. Of course, you can also place the
genesis_config.json file in another location and specify it with an absolute path, for example:
starcoin_generator -n my_chain:123 --genesis-config /data/conf/my_chain/genesis_config.json genesis
Running custom network nodes
Use the following command to start a custom network node:
starcoin -n my_chain:123 console
Form a custom network cluster
After starting a node, you can find the address of the node in the log or standard output, record the IP address of the machine, and then use it for networking. It may look like this:
2022-05-25T11:27:10.201604911+00:00 INFO - Self address is: /ip4/127.0.0.1/tcp/9840/p2p/12D3KooWR1p3uxnWZ2rv5mZ3Sw2i8z3gabxNEHjgkPDC2pkk19Vp
Specify the first node as the seed node by
--seed, and then start other nodes to form a network.
Note: Multiple nodes must use the same genesis configuration file to generate genesis blocks in order to form a network.
On other machines, you can add to your private network by starting a new node and specifying the IP address of the genesis node using the
starcoin -n my_chain:123 --seed /ip4/ip of genesis seed/tcp/9840/p2p/12D3KooWR1p3uxnWZ2rv5mZ3Sw2i8z3gabxNEHjgkPDC2pkk19Vp console
If you want run custom network in one local machine for test
First, start one node as the genesis seed, which is already started if you follow the steps, and check your local ip address.
Second, copy the genesis_config.json configuration file of the genesis seed node to a new directory:
cp ~/.starcoin/my_chain/genesis_config.json ~/.starcoin1/my_chain/
Third, start other node using docker with following command:
docker run --name starcoin-p1 -d -v ~/.starcoin1/:/root/.starcoin/ starcoin/starcoin:latest /starcoin/starcoin -n my_chain:123 --seed /ip4/ip of genesis seed/tcp/9840/p2p/12D3KooWR1p3uxnWZ2rv5mZ3Sw2i8z3gabxNEHjgkPDC2pkk19Vp