Private Networks

This page describes how to set up a private network to have a granular control over who can access your network.

Private Mode

Kwild nodes can be run in a private mode, where the node will only accept connections from a list of known peers. This is useful when you want to restrict access to your network to a specific set of nodes.

Private mode can be enabled by setting the private_mode field in the chain.p2p section of the config.toml as shown below:

[chain.p2p]
private_mode = true

Private mode can also be enabled by setting the --chain.p2p.private-mode flag when starting the node as shown below:

kwild -r /path/to/root/dir --chain.p2p.private-mode

tip

kwil-admin setup init --chain.p2p.private-mode can also be used to generate node configuration with private mode enabled.

Whitelist Peers

When running a Kwild node in private mode, it can be configured to only accept connections from a list of known peers. whitelist_peers field should be a comma-separated list of node IDs.

Peers can be added to the whitelist by setting the whitelist_peers field in the chain.p2p section of the config.toml as shown below:

[chain.p2p]
whitelist_peers = "b624b3395f22f8cb57cf86d58cbcd6b355d12e18,7b4b3b3b5f22f8cb57cf86d58cbcd6b355d12e18"

or

kwild -r /path/to/root/dir --chain.p2p.private-mode --chain.p2p.whitelist-peers="b624b3395f22f8cb57cf86d58cbcd6b355d12e18,7b4b3b3b5f22f8cb57cf86d58cbcd6b355d12e18"

The current set of validators, persistent peers and seed nodes are automatically added to the whitelist. Therefore, the whitelist_peers field is used to restrict which non-validating read-only nodes can sync data from your node's P2P endpoint.

The whitelist can also be updated dynamically using the kwil-admin whitelist commands. Refer to the Kwil Admin Peers Subcommand documentation for more information.

note

Seed nodes and persistent peers are automatically whitelisted. In order for a new node to maintain a connection with an existing node that is not a seed or persistent peer, the existing node must also add the new node to its whitelist and vice versa.

Onboarding a Read Node

When onboarding a new read node to the network, the new node's Node ID should be added to the whitelist of at least one of the existing network nodes. Once the new node is added to an existing node's whitelist, the new node can use the existing node's Node ID as it's persistent peer or seed node.

For example, to onboard a new node with the Node ID new-node-id to an existing node with the Node ID existing-node-id, follow the steps below:

1. From the existing node, add the new node to the whitelist as shown below:

   kwil-admin whitelist add <new-node-id>

2. From the existing node, verify that the new node is added to its whitelist:

   kwil-admin whitelist list

3. From the new node, add the existing node as a seed node or persistent peer. As seeds nodes and persistent peers are automatically whitelisted, the new node should be able to connect to the existing node without explicitly adding the existing node ID to the whitelist.

   [chain.p2p]
   seeds = "existing-node-id@localhost:26656"

   [chain.p2p]
   persistent_peers = "existing-node-id@localhost:26656"

Onboarding a Validator Node

When onboarding a new validator node to the network, the node should first be added as a read node to the network. Once the node is part of the network, the node can then request the network to become a validator.

Existing validators add the joiner node to their whitelist when they approve the validator join request. If the request is rejected (expired), the joiner node will be removed from the whitelist of all the validators that previously approved the request. Once the validator join request gets approved, the new validator node is automatically added to the whitelist of all the nodes in the network.

note

Whenever a validator is demoted, it is automatically removed from the whitelist of all the nodes in the network. The demoted validator need to follow the regular onboarding process to join back as the read node.