Running a Kwil Node
The kwild
command starts the blockchain and the database services of the Kwil node. This guide provides step-by-step instructions to launch a Kwil node.
Root Directory
This is the default directory to store all the configuration and data such as blockchain data, SQL database data, signed messages, etc, unless specified otherwise.
home_dir/
|- genesis.json
|- config.toml
|- private_key
|- abci/ # chain root directory, stores blockchain data & config
| |- data/
The default root directory is ~/.kwild
. You can override this configuration by setting the KWILD_ROOT_DIR
environment variable or using the --root-dir
command line flag.
Requirements
The kwild
commands on this page assume you have configured a PostgreSQL host
as described in Installation.
Quickstart
Quickstart mode can be used to swiftly deploy a node without delving into the configuration details. To run in this mode, use the kwild
command with the --autogen
flag.
kwild --autogen
This command will auto-generate the necessary configuration in the root directory and starts the node using this configuration. This also create a new private chain with the initialized node as its sole member and validator.
It's crucial to note, however, that the node operates under a default configuration in the quickstart mode. For production deployments, it's highly recommended to tailor the configuration to your specific needs, as discussed in subsequent sections.
Configuration
Running a Kwil node requires genesis.json
, config.toml
and private_key
files. All these configuration files must be present under the root directory. This section describes in detail on how to initialize the root directory with these configuration files.
Private Keys
Kwil nodes use ed25519 keys for validator related operations. Refer to the key management guide for generating these node keys. The default location of private_key is root_dir/private_key
. You can override this configuration by setting the KWILD_APP_PRIVATE_KEY_PATH
environment variable using the app.private-key-path
command line flag, or
setting the app.private_key_path
in the config.toml
.
Genesis File (genesis.json)
To deploy a new Kwil network, copy the sample genesis.json into root_dir/abci/config/genesis.json
. Manually update the chain_id
, initial_height
, app_hash
configurations in the genesis.json
file.
To start the node as a validator, the node's public key in hex format must be listed under the validators
in the genesis file as shown below. Refer to the key management guide to view the public key, address and node ID corresponding to the node's private key.
"validators": [
{
"pub_key": "71d79c64ffb46e8f6c36f1429066a9d92f6adf5bbe546204e40ec5559478b6aa",
"power": 1,
"name": "validator-0"
}
],
Refer to the genesis specification for advanced configuration options.
To connect a node to an existing network, obtain the genesis file from the desired network and set it as the genesis file for that node.
Config File (config.toml)
Copy the sample config.toml into root_dir/config.toml
and update the configuration as required.
Notable options include the RPC and HTTP server settings such as app.jsonrpc_listen_addr
, chain.rpc.listen_addr
and chain.p2p.listen_addr
.
There are two settings related to establishing connections to other network nodes:
chain.p2p.persistent_peers
is used to maintain persistent connections with certain nodes.chain.p2p.seeds
specifies special seed nodes or services from which additional peer addresses are obtained.
The above fields can be empty if the network is made up of a standalone node.
Refer to the configuration specification for more options on tuning a Kwil application.
Configuration Override
The Kwil application supports the ability to override the configuration at node startup through the command line flags and environment variables.
Use --help or -h
for detailed information on all the parameters that can be overwritten through command line flags.
For instance, to modify the log level and chain RPC address during the node startup, you can use one of the following methods:
KWILD_LOG_LEVEL=debug
KWILD_CHAIN_RPC_LISTEN_ADDRESS="tcp://127.0.0.1:26656"
kwild --root-dir "path/to/root/dir"
kwild --root-dir "path/to/root/dir" --log.level "debug" --chain.rpc.listen-addr "tcp://127.0.0.1:26656"
KWILD_LOG_LEVEL=debug
KWILD_CHAIN_RPC_LISTEN_ADDRESS="tcp://127.0.0.1:26656"
kwild --root-dir "path/to/root/dir" --log.level "info" --chain.rpc.listen-addr "tcp://192.168.1.20:30000"
If both flags and env variables are set, flags take precedence over environment variables. Therefore, in this example, the Kwil application uses info
log level and RPC listen address as tcp://192.168.1.20:30000
.
Option names in the TOML configuration file and environment variables use underscores ("_") to separate words within the name, while the command line flags use dashes ("-").
Refer to the translation guide for more information on mapping the config parameters to the command line flags and environment variables.
Deploy a Kwil Network
A private Kwil network with a standalone node can be deployed by running kwild
as shown below:
kwild --root-dir "path/to/root/dir"
The root directory must have the required configuration for the node to start successfully. If you are using quickstart mode, this root directory will be generated for you if it does not exist.
Whether this node starts as a validator or a non-validator is determined by its presence in the initial validator list within the genesis file.
Connecting To A Kwil Network
To connect to an existing Kwil network during startup:
Obtain the
genesis.json
for the desired network from a network authority, and ensure that it is placed in yourroot-dir
.Set
chain.p2p.seeds
and/orchain.p2p.persistent-peers
.seeds
is a comma-separated list ofnodeid@ip:port
seed nodes used to obtain initial peer addresses, whilepersistent-peers
are peers to stay connected to.Start
kwild
.In the following examples, we are setting
persistent-peers
to two known network nodes with whichkwild
should maintain persistent connections.Command line flag: --chain.p2p.persistent-peerskwild --root-dir "path/to/root/dir" --chain.p2p.persistent-peers "[email protected]:26656,[email protected]:26656"
Environment variable: KWILD_CHAIN_P2P_PERSISTENT_PEERSKWILD_CHAIN_P2P_PERSISTENT_PEERS="[email protected]:26656,[email protected]:26656"
kwild --root-dir "path/to/root/dir"persistent_peers option in config.toml[chain.p2p]
persistent_peers = "[email protected]:26656,[email protected]:26656"
kwild --root-dir "path/to/root/dir"Note that this node joins the network by default as a non-validator. Please refer to the Validator Guide for more information on becoming a validator node.
Kwil Admin Tools
The kwil-admin setup
tools can be used to quickly setup the configuration required for running either a standalone node or a network of nodes. Refer to the setup guide for more information on its usage.