Settings

This section provides a detailed overview of the operational parameters available in the config.toml file for configuring a Kwil node. These settings are grouped into three categories: chain-specific configurations related to the underlying blockchain operations, app-specific configurations that dictate the Kwil application's behavior, and logging configurations. Below are the explanations for each parameter:

[log]

• level: This variable specifies the logging level of the Kwil application. By default, the level is set to info.

• rpc_level: This variable specifies the logging level for the RPC server, which must be higher than the general log level. No default.

• output_paths: This variable specifies where logs are written to. You can designate multiple paths, separated by commas. By default, logs are directed to stdout and kwild.log.

• format: This variable specifies the log format, which can be either plain or json. The default is json.

• time_format: This variable specifies the time format for logs. Options include epochfloat, epochmilli, and rfc3339milli. The default is epochfloat.

[app]

This section holds configurations specific to the Kwil application's operation.

• jsonrpc_listen_addr: This variable specifies the address where the daemon's JSON-RPC server listens for connections. The default is 0.0.0.0:8484.

• admin_listen_addr: This variable specifies the address where the daemon's admin JSON-RPC server listens for connections. The default is /tmp/kwild.socket.

• admin_pass: The password for the kwil admin service. May be empty. No default.

• admin_notls: Toggle TLS on the admin server. Automatically disabled for unix socket or loopback listen addresses.

• pg_db_host: PostgreSQL database host (UNIX socket path or IP address with no port). The default is 127.0.0.1 (localhost).

• pg_db_port: PostgreSQL database port (may be omitted for UNIX socket hosts). The default is 5432.

• pg_db_user: PostgreSQL database user (should be a "superuser"). The default is kwild.

• pg_db_pass: PostgreSQL database pass (may be omitted for some pg_hba.conf configurations). No default.

• pg_db_name: PostgreSQL database name (override database name). The default is kwild.

• private_key_path: This variable specifies the path for node's private key. If left unspecified, it defaults to ./private_key relative to the root directory.

• profile_mode: This variable sets the kwild profiling module. Options are http, cpu, mem, mutex, and block. No default.

• profile_file: The kwild profile output file path. Not enabled by default. This setting does not apply for http profiling.

• rpc_timeout: The timeout for the JSON-RPC server. Default is 45s.

• db_read_timeout: The timeout for database reads initiated by RPC requests. Default is 5s.

• extension_endpoints: This variable specifies the endpoints for extensions, separated by commas.

• tls_cert_file: This variable specifies the file path containing a certificate to enable TLS on the JSON-RPC server. This path can be either absolute or relative to the specified root directory. If unspecified, the JSON-RPC server's communications remain unencrypted.

• tls_key_file: This variable specifies the file path containing the corresponding private key that enables TLS on the JSON-RPC server. Like the tls_cert_file, this path can be either absolute or relative to the specified root directory. If unspecified, the JSON-RPC server's communications remain unencrypted.

• hostname: This variable sets the Kwil JSON-RPC server's hostname. No default.

• genesis_state: This variable specifies the path to the snapshot file to be used for the initial state of the node. If the node is configured to start with initial state and this variable is not set, the node will fail to start. No default.

  [app.snapshots]

  This section contains configurations for managing the snapshots of the kwild database.

  • enabled: This variable enables creation and serving of snapshots to support state sync on nodes joining the network. Default is false.

  • snapshot_dir: This variable specifies the path to the snapshots directory. Default is snapshots.

  • recurring_height: This variable specifies the heights (multiples of heights) at which the database is snapshotted. The default is 14400, which is around 1 snapshot per day considering block rate of 1 block per 6 seconds

  • max_snapshots: This variable specifies the maximum number of snapshots to store on disk. The default is 3 snapshots.

[chain]

This section contains configuration specific to the CometBFT-based blockchain.

• moniker: This variable specifies a custom, human-readable name for the node.

  [chain.rpc]

  This section offers configurations for managing the blockchain's RPC service.

  • listen_addr: This variable specifies the listening address for the blockchain's RPC server. Default is tcp://127.0.0.1:26657.

  • broadcast_tx_timeout: This variable specifies the time to wait for a transaction to be committed when authored with --sync flag in the CLI. Default is 15s.

  [chain.consensus]

  This section provides configurations for managing blockchain consensus. These are only important for validators. They should be set according to the network configuration.

  • timeout_propose: This variable specifies the time to wait for a proposal block before prevoting nil. Default timeout is 3s.

  • timeout_prevote: This variable specifies the time to wait after receiving +2/3 prevotes. Default timeout is 2s.

  • timeout_precommit: This variable specifies the time to wait after receiving +2/3 precommits. Default timeout is 2s.

  • timeout_commit: This variable specifies the time to wait after committing a block before starting on the new height. Default timeout is 6s.

  [chain.p2p]

  This section outlines configurations for the P2P service, which manages peer-to-peer connectivity within the blockchain network.

  • listen_addr: This variable specifies the address for listening to the incoming peer connections. Default is tcp://0.0.0.0:26656.

  • external_address: This variable specifies the address for peers to connect to. If left empty, it defaults to the same port as the listen_addr and will introspect based on the listener.

  • persistent_peers: This variable specifies a comma-separated list of nodes to consistently connect to. No default.

  • pex: A toggle to enable peer exchange, an ongoing function of the node used to share known peers with other nodes. Default is true.

  • seeds: This variable specifies a comma-separated list of seed nodes or dedicated seeders services used to provide peer addresses when bootstrapping. This is unused if there are entries in the address book. No default.

  • seed_mode: A toggle to run in a special "seed mode" where kwild constantly crawls the network to obtain a large address book, which it shares with incoming nodes before disconnecting them. A node running with this setting would be used only to bootstrap other nodes via their seeds setting. This is not appropriate for a validator or an RPC service provider. Default is false.

  • addr_book_strict: A toggle for enforcing strict address routability rules. By default, nodes with routable addresses are considered for connection. However, if this setting is disabled, non-routable IP addresses, like addresses in a private network can be added to the address book.

  • max_num_inbound_peers: This variable specifies the maximum number of inbound peers. Default is 40.

  • max_num_outbound_peers: This variable specifies the maximum number of outbound peers to connect to, excluding persistent peers. Default is 10.

  • unconditional_peer_ids: This variable specifies a comma separated list of node ID's that will always have connections (re)established, regardless of the connection limits. No default.

  • allow_duplicate_ip: A toggle to prevent multiple peers from using the same IP address. Default is true.

  [chain.mempool]

  This section discusses the configurations for the blockchain's transaction mempool.

  • size: This variable specifies the mempool's maximum transaction count. Default is 5000.

  • max_tx_byte: This variable specifies the maximum size of any one transaction in the mempool. Default is 4MB.

  • max_txs_bytes: This variable specifies the limit on the total size of all transactions in the mempool. Default is 2^29 bytes.

  • cache_size: This variable specifies the cache size used to filter previously seen transactions. Default is 10000 bytes.

  [chain.statesync]

  This section provides configuration to enable state sync instead of block sync to catchup with the network.

  • enable: This variable toggles the state sync feature on or off. By default, the state sync feature is disabled and the node uses block sync to catch up with the network.

  • snapshot_dir: This variable specifies the path to the directory where the received snapshot is stored. Default is rcvdSnaps.

  • rpc_servers: This variable specifies a list of trusted snapshot providers. It is a comma-seperated list of chain RPC servers and requires atleast 2 servers to enable statesync. These servers act as the source-of-truth for the snapshot integrity and also responsible for creating, distributing and validating snapshots. These servers should have snapshot configuration enabled.

  • discovery_time: This variable specifies the time to spend discovering snapshots before offering the latest snapshot to the ABCI application. The default is 15s. The node will repeat this process until it finds a valid snapshot. If there are no snapshots available in the network, restart the node with block sync enabled to make progress with the node syncing. Default is 15s.

  • chunk_request_timeout: This variable specifies the timeout duration before re-requesting a chunk, possibly from a different peer. Default is 10s.

This is the structure in which these configs must appear in the config.toml file.

Sample config.toml

Here is an example of a config.toml file with complete configuration:

sample config.toml file

# NOTE: Any path below can be absolute (e.g. "/var/myawesomeapp/data") or
# relative to the home directory (e.g. "data")

# Root Directory Structure:
# RootDir/
#   |- genesis.json   (genesis file for the network)
#   |- config.toml   (app and chain configuration for running the kwild node)
#   |- private_key   (node's private key)
#   |- abci/
#   |   |- addrbook.json  (peer routable addresses for the kwild node)
#   |   |- data/
#   |   |   |- blockchain db files/dir (blockstore.db, state.db, etc)
#   |   |- info/
#   |- signing/
#   |- snapshots/
#   |- rcvdSnaps/

# Only the config.toml and genesis file are required to run the kwild node
# The rest of the files & directories are created by the kwild node on startup

#######################################################################
###                    Logging Config Options                       ###
#######################################################################

[log]

# Output level for logging, default is "info". Other options are "debug", "error", "warn", "trace"
level = "info"

# RPC systems' logging level. Must be higher than log.level.
rpc_level = ""

# Consensus engine's logging level. Must be higher than log.level.
consensus_level = ""

# DB driver's logging level. Must be higher than log.level.
db_level = ""

# Output paths for the logger, can be stdout or a file path
output_paths = ["stdout", "kwild.log"]

# Output format: 'plain' or 'json'
format = "json"

# Time format: "epochfloat" (default), "epochmilli", or "rfc3339milli"
time_format = "epochfloat"

#######################################################################
###                      App Config Options                         ###
#######################################################################

[app]

# Node's Private key
private_key_path = "private_key"

# TCP or UNIX socket address for the KWILD App's JSON-RPC server to listen on
jsonrpc_listen_addr = "localhost:8484"

# Unix socket or TCP address for the KWILD App's Admin server to listen on
admin_listen_addr = "/tmp/kwild.socket"

# Timeout on requests on the user RPC servers
rpc_timeout = "45s"

# Timeout on database reads initiated by the user RPC service
db_read_timeout = "5s"

# List of Extension endpoints to be enabled ex: ["localhost:50052", "169.198.102.34:50053"]
extension_endpoints = []

# PostgreSQL database host (UNIX socket path or IP address with no port)
pg_db_host = "/var/run/postgresql"

# PostgreSQL database port (may be omitted for UNIX socket hosts)
pg_db_port = "5432"

# PostgreSQL database user (should be a "superuser")
pg_db_user = "kwild"

# PostgreSQL database pass (may be omitted for some pg_hba.conf configurations)
pg_db_pass = ""

# PostgreSQL database name (override database name, default is "kwild")
pg_db_name = "kwild"

# The admin RPC server can require a password, if set. Ensure the connection is
# encrypted since the password is sent unencrypted in the HTTP Authorization
# header. Not needed if client authentication is done with mutual TLS (clients.pem).
# admin_pass = ""

# Disable TLS on the admin service server. It is automatically disabled for a
# UNIX socket or loopback TCP listen address. This setting can disable it for
# any TCP listen address.
admin_notls = false

# The path to a file containing certificate that is used to create the HTTPS server.
# Might be either absolute path or path related to the kwild root directory.
# If the certificate is signed by a certificate authority,
# the certFile should be the concatenation of the server's certificate, any intermediates,
# and the CA's certificate.
# NOTE: both tls_cert_file and tls_key_file must be present for CometBFT to create HTTPS server.
# Otherwise, HTTP server is run.
tls_cert_file = ""

# The path to a file containing matching private key that is used to create the HTTPS server.
# Might be either absolute path or path related to the kwild root directory.
# NOTE: both tls_cert_file and tls_key_file must be present for CometBFT to create HTTPS server.
# Otherwise, HTTP server is run.
tls_key_file = ""

# Kwild Server hostname
hostname = ""

# Path to the snapshot file to restore the database from.
# Used during the network migration process.
genesis_state = ""

#######################################################################
###                     Extension Configuration                     ###
#######################################################################

[app.extensions]

# Oracle extensions can be enabled by adding the following configuration
# Each oracle extension configuration is defined under a subsection identified by the 
# oracle extension name [app.extensions.<oracle_extension-name>]
# The configuration options for each oracle extension are defined as key-value pairs under the subsection.
# Only string values are supported for these configuration options.
# For example, to enable the Ethereum listener extension, the configuration would look like:
# [app.extensions.eth_listener]
# rpc_provider = "https://mainnet.infura.io/v3/YOUR_INFURA_API_KEY"
# contract_address = "0xYOUR_CONTRACT_ADDRESS"

#######################################################################
###                     Snapshots Configuration                     ###
#######################################################################

[app.snapshots]

# Enables snapshots
enabled = true

# Path to the snapshots directory
snapshot_dir = "snapshots"

# Specifies the block heights(multiples of recurring_height) at which the snapshot should be taken
recurring_height = {{.AppCfg.Snapshots.RecurringHeight}}

# Maximum number of snapshots to store
max_snapshots = 3

#######################################################################
###                 Chain  Main Base Config Options                 ###
#######################################################################

[chain]

# A custom human readable name for this node
moniker = ""

#######################################################################
###                 Advanced Configuration Options                  ###
#######################################################################

#######################################################
###       RPC Server Configuration Options          ###
#######################################################

[chain.rpc]

# TCP or UNIX socket address for the RPC server to listen on
listen_addr = "tcp://127.0.0.1:26657"

# Timeout for each broadcast tx commit
broadcast_tx_timeout = "15s"

#######################################################
###         Consensus Configuration Options         ###
#######################################################

[chain.consensus]

# How long we wait for a proposal block before prevoting nil
timeout_propose = "3s"

# How long we wait after receiving +2/3 prevotes for “anything” (ie. not a single block or nil)
timeout_prevote = "2s"

# How long we wait after receiving +2/3 precommits for “anything” (ie. not a single block or nil)
timeout_precommit = "2s"

# How long we wait after committing a block, before starting on the new
# height (this gives us a chance to receive some more precommits, even
# though we already have +2/3).
timeout_commit = "6s"

#######################################################
###           P2P Configuration Options             ###
#######################################################

[chain.p2p]

# Address to listen for incoming connections
listen_addr = "tcp://0.0.0.0:26656"

# Address to advertise to peers for them to dial
# If empty, will use the same port as the listening address,
# and will introspect on the listener or use UPnP
# to figure out the address. ip and port are required
# example: 159.89.10.97:26656
external_address = ""

# Comma separated list of nodes to keep persistent connections to (used for bootstrapping)
# Nodes should be identified as id@host:port, where id is the hex encoded CometBFT address.
# Example: "[email protected]:26656,[email protected]:26656"
persistent_peers = ""

# Set true for strict address routability rules
# Set false for private or local networks
addr_book_strict = false

# Maximum number of inbound peers
max_num_inbound_peers = 40

# Maximum number of outbound peers to connect to, excluding persistent peers
max_num_outbound_peers = 10

# List of node IDs, to which a connection will be (re)established ignoring any existing limits
unconditional_peer_ids = ""

# Toggle to disable guard against peers connecting from the same ip.
allow_duplicate_ip = true

# Enable gossiping of peer information
pex = true

# Seed nodes used to obtain peer addresses. Only used if the peers in the
# address book are unreachable.
seeds = ""

# Seed mode, in which node constantly crawls the network and looks for
# peers. If another node asks it for addresses, it responds and disconnects.
#
# It is recommended to instead run a dedicated seeder like https://github.com/kwilteam/cometseed.
#
# Requires peer-exchange to be enabled.
seed_mode = false

#######################################################
###          Mempool Configuration Options          ###
#######################################################

[chain.mempool]
# Maximum number of transactions in the mempool
size = 5000

# Limit the total size of all txs in the mempool.
# This only accounts for raw transactions (e.g. given 1MB transactions and
# max_txs_bytes=5MB, mempool will only accept 5 transactions).
max_txs_bytes = 536870912

# Limit the size of any one transaction in mempool.
max_tx_bytes = 4194304

# Size of the cache (used to filter transactions we saw earlier) in transactions
cache_size = 10000

#######################################################
###         State Sync Configuration Options        ###
#######################################################

[chain.statesync]
# State sync rapidly bootstraps a new node by discovering, fetching, and restoring a state machine
# snapshot from peers instead of fetching and replaying historical blocks. Requires some peers in
# the network to take and serve state machine snapshots. State sync is not attempted if the node
# has any local state (LastBlockHeight > 0). The node will have a truncated block history,
# starting from the height of the snapshot.
enable = true

# SnapshotDir is the directory to store the received snapshot chunks.
snapshot_dir = "rcvdSnaps"

# Trusted snapshot providers (comma-separated chain RPC servers) are the source-of-truth for the snapshot integrity.
# Snapshots are accepted for statesync only after verifying the snapshot metadata (snapshot hash, chunk count, height etc.) 
# with these trusted snapshot providers. At least 1 trusted snapshot provider is required for enabling state sync.
rpc_servers = "http://rpc1:26657,http://rpc2:26657"

# Time spent discovering snapshots before offering the best(latest) snapshot to the application.
# If no snapshots are discovered, the node will redo the discovery process until snapshots are found.
# If network has no snapshots, restart the node with state sync disabled to sync with the network.
# Current default is 15s, as only snapshot metadata is requested in the discovery process. 
# Adjust this value according to the network latencies of your peers.
discovery_time = "15s"

# The timeout duration before re-requesting a chunk, possibly from a different
# peer (default: 1 minute), if the current peer is unresponsive to the chunk request.
chunk_request_timeout = "10s"

# Note: If the requested chunk is not received for a duration of 2 minutes (hard-coded default), 
# the state sync process is aborted and the node will fall back to the regular block sync process.

Config Override

Every config.toml entry can be overridden using either environment variables or command line flags.

The order of priority is flags > env variables > config.toml > defaults.

The structure of config.toml is hierarchical, using sections and subsections. Below are the rules to translate a field from config.toml to environment variables or command line flags.

Translation rules

config.toml

[section]
field = "val"

[section.subsection]
other_field = "val"

The corresponding command line flags and environment variables for field and other_field are as follows:

Flag	Environment Variable
--section.field	KWILD_SECTION_FIELD
--section.subsection.other-field	KWILD_SECTION_SUBSECTION_OTHER_FIELD

The one exception to the above is for configuring values in the app.extensions section of the config.toml. Extension configs must be specified after all others, and must be delimited from the rest of the command line arguments by a double dash --:

kwild --autogen --app.private_key_path ./private_key -- --extension.<extension-name>.<config-key> <config-value>