Tutorial: Creating and Joining a Network
In this tutorial, we will:
- Create a node and start a new network;
- Create a second node and configure it to join the network;
- Add the second node to the network as a non-validating peer;
- Upgrade the second node to a validator.
In order to do this tutorial, you will need to install the kwild
and kwil-admin
binaries,
as well as have docker
installed.
Creating The First Node
Creating The Node's Files
To create the node's configuration files, a new genesis.json
, and a new keypair, we will use the kwil-admin
tool:
kwil-admin setup init --root-dir ./testnet/node0
The ./testnet/node0
folder will be the "root" directory for kwild
that
contains the configuration files, including genesis.json
and config.toml
.
Running The Node
To run the first node, we will need to start a properly configured PostgreSQL instance. We will use a default pre-configured image provided by
Kwil. For information on how this can be configured manually, see the node's PostgreSQL configuration section.
Once the PostgreSQL instance is running, we can start the node using the kwild
binary:
# Run Postgres
docker run -d -p 5432:5432 --name kwil-postgres -e "POSTGRES_HOST_AUTH_METHOD=trust" \
kwildb/postgres:latest
# Run the node
kwild --root-dir ./testnet/node0 --app.admin-listen-addr /tmp/node0.sock --app.pg-db-port 5432
The command then runs the local Kwil network, and begins producing blocks.
We override the default app.admin-listen-addr
because in this tutorial, we will be running two nodes on the same machine.
To allow us to interact with both nodes' admin RPCs, we will make them listen on different UNIX sockets.
Getting The Node's Info
In order to allow other nodes to join, we will need to expose our node's information publicly. Other operators can then set us as a peer, and request to join the network as a validator.
To get our node's information, we can use the kwil-admin
tool, specifying the UNIX socket that our admin RPC is listening on:
$ kwil-admin node status --rpcserver /tmp/node0.sock
{
"node": {
"chain_id": "kwil-chain-WfnGxpWd",
"name": "MacBook-Pro-7.local",
"node_id": "b624b3395f22f8cb57cf86d58cbcd6b355d12e18", # node ID
"proto_ver": 8,
"app_ver": 0,
"block_ver": 11,
"listen_addr": "tcp://0.0.0.0:26656", # p2p address
"rpc_addr": "tcp://127.0.0.1:26657"
},
"sync": {
"app_hash": "",
"best_block_hash": "",
"best_block_height": 0,
"best_block_time": "1969-12-31T18:00:00-06:00",
"syncing": false
},
"validator": {
"pubkey": "22cbbb666c26b2c1f42502df72c32de4d521138a1a2c96121d417a2f341a759c",
"power": 1
}
}
The node.node_id
and node.listen_addr
fields can be given to the second node as a persistent peer, in the format: node-id@p2p-address
.
For the above node, we would have [email protected]:26656
. We change 0.0.0.0
to an IP address that the second node can reach: 127.0.0.1
.
Creating A Second Peer Node
Using the kwil-admin
tool to create the second node's directories and configs, we can specify where to find the genesis file and any
peers that it should try to connect to when starting up. Since both nodes are running locally, we need to specify
new addresses for the different endpoints, so that the second node does not conflict with the first node:
Ensure that you replace b624b3395f22f8cb57cf86d58cbcd6b355d12e18
with your own node's ID.
kwil-admin setup init --root-dir ./testnet/node1 --genesis ./testnet/node0/genesis.json \
--chain.p2p.persistent-peers [email protected]:26656 \
--app.jsonrpc-listen-addr=localhost:8485 --app.admin-listen-addr=/tmp/node1.sock \
--chain.rpc.listen-addr=tcp://127.0.0.1:26658 --chain.p2p.listen-addr=tcp://127.0.0.1:26655
Start the second node to verify that it was created correctly:
# Run Postgres
docker run -d -p 5431:5432 --name kwil-postgres-1 -e "POSTGRES_HOST_AUTH_METHOD=trust" \
kwildb/postgres:latest
# Run the node
kwild --root-dir=./testnet/node1 --app.pg-db-port 5431
If done correctly, you should be able to see the second node's logs, and it should be able to read the network logs.
Upgrading The Second Node To A Validator
To upgrade the second node to a validator, we will use the kwil-admin
tool to:
- Request to join the network as a validator, from the second node
- Approve the request, from the first node
We will use the configured UNIX socket to communicate with the nodes.
Requesting To Upgrade
To request to join from the second node:
kwil-admin validators join --rpcserver /tmp/node1.sock
To check that the request was successful, we can get a list of pending join requests:
$ kwil-admin validators list-join-requests --rpcserver /tmp/node0.sock
Pending join requests (1 approval needed):
Candidate | Power | Approvals | Expiration
-------------------------------------------------------------------+-------+-----------+------------
a2d8e307117695c8d0d3adbda136cb2ad630c43b8672a0eba46d79501831b794 | 1 | 0 | 16728
Approving The Request
The first node must vote to approve the second node's join request. Using the kwil-admin
tool, the first node can
vote to approve the second node by running the kwil-admin validators approve
command and passing the second node's public key:
kwil-admin validators approve <node_pubkey> \
--rpcserver /tmp/node0.sock
If the requesting node's public key is unknown, all pending requests and their public keys can be retrieved with the kwil-admin validators list-join-requests
command.
And that's it! The second node should now be a validator on the network. To verify this, we can use the kwil-admin
tool to get the list of validators:
$ kwil-admin validators list --rpcserver /tmp/node0.sock
Current validator set:
0. {pubkey = 22cbbb666c26b2c1f42502df72c32de4d521138a1a2c96121d417a2f341a759c, power = 1}
1. {pubkey = a2d8e307117695c8d0d3adbda136cb2ad630c43b8672a0eba46d79501831b794, power = 1}
Cleanup
If you wish to reset this tutorial, you will need to stop the nodes and Postgres containers, remove the testnet
directory, and remove the Postgres container:
# Stop the nodes using Ctrl+C
# Stop the Postgres containers
docker stop kwil-postgres
docker stop kwil-postgres-1
# Remove the Postgres containers
docker rm kwil-postgres
docker rm kwil-postgres-1
# Remove the testnet directory
rm -rf ./testnet
Conclusion
In this tutorial, we have:
- Created a node and started a network;
- Created a second node and configured it to join the network;
- Added the second node to the network as a non-validating peer;
- Upgraded the second node to a validator.