Skip to main content

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 or using the app.private-key-path command line flag.

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.

Genesis Validators
  "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, app.http-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:

Environment variable
KWILD_LOG_LEVEL=debug
KWILD_CHAIN_RPC_LISTEN_ADDRESS="tcp://127.0.0.1:26656"

kwild --root-dir "path/to/root/dir"
Command line flags
kwild --root-dir "path/to/root/dir" --log.level "debug" --chain.rpc.listen-addr "tcp://127.0.0.1:26656"
Both environment and command line flags
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.

tip

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 your root-dir.

  • Set chain.p2p.seeds and/or chain.p2p.persistent-peers. seeds is a comma-separated list of nodeid@ip:port seed nodes used to obtain initial peer addresses, while persistent-peers are peers to stay connected to.

  • Start kwild.

    In the following examples, we are setting persistent-peers to two known network nodes with which kwild should maintain persistent connections.

    Command line flag: --chain.p2p.persistent-peers
    kwild --root-dir "path/to/root/dir" --chain.p2p.persistent-peers "[email protected]:26656,[email protected]:26656"
    Environment variable: KWILD_CHAIN_P2P_PERSISTENT_PEERS
    KWILD_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.