This guide will walk you through the process of setting up and running a TRUF.NETWORK (TN) node. By following these steps, you’ll be able to deploy a node, optionally become a validator, and contribute to the TN.

​
Prerequisites

Before you begin, ensure you have the following:

  1. Docker & Docker Compose: Required for running the PostgreSQL image.
sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg lsb-release build-essential
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
  | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
  https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" \
  | sudo tee /etc/apt/sources.list.d/docker.list >/dev/null
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin
  • After installation, enable and start Docker:
sudo systemctl enable docker
sudo systemctl start docker
  • Add your user to the docker group to run Docker commands without sudo:
sudo usermod -aG docker $USER
newgrp docker
  1. PostgreSQL Client: Required for state sync and database operations.
sudo apt-get install -y postgresql-client-16
  1. Go: Required for building kwild binary
LATEST_GO_VERSION=$(curl -sSL https://go.dev/VERSION?m=text | head -n1)
echo "Installing ${LATEST_GO_VERSION}..."
curl -fsSL "https://go.dev/dl/${LATEST_GO_VERSION}.linux-amd64.tar.gz" \
  -o "${LATEST_GO_VERSION}.linux-amd64.tar.gz"
sudo rm -rf /usr/local/go
sudo tar -C /usr/local -xzf "${LATEST_GO_VERSION}.linux-amd64.tar.gz"
rm "${LATEST_GO_VERSION}.linux-amd64.tar.gz"
  • After installation, add Go to PATH:
grep -qxF 'export GOPATH=$HOME/go' ~/.bashrc \
  || echo 'export GOPATH=$HOME/go' >> ~/.bashrc
grep -qxF 'export PATH=$PATH:/usr/local/go/bin:$GOPATH/bin' ~/.bashrc \
  || echo 'export PATH=$PATH:/usr/local/go/bin:$GOPATH/bin' >> ~/.bashrc
  • Reload your terminal:
source ~/.bashrc
  1. Taskfile (go-task):
go install github.com/go-task/task/v3/cmd/task@latest
  1. Kwild Binary

You have two options to get the kwild binary:

  1. Download from Releases:
  • Visit TRUF.NETWORK Node Releases
  • Download the latest release for your operating system (e.g., tn_2.0.1_linux_amd64.tar.gz)
  • Extract the binary and move it to your system path:
tar -xzf tn_2.0.1_linux_amd64.tar.gz
sudo mv kwild /usr/local/bin/
  1. Build from Source:
git clone https://github.com/trufnetwork/node.git
cd node
task build

The built binary will be in the .build directory. Move it to your system path:

sudo mv .build/kwild /usr/local/bin/

Apply new docker group:

newgrp docker

​
Verify Installation

Before you move forward to Node Setup, verify that everything installed correctly and of the right version:

docker --version
docker compose version
pg_dump --version
go version
task --version
kwild version

​
Node setup

​
1. Clone TN Node Operator Repository

From your root directly, clone the TRUF.NETWORK node operator repository:

git clone https://github.com/trufnetwork/truf-node-operator.git
cd truf-node-operator

​
2. Generate Initial Configuration

Use kwild to create your initial configuration file:

kwild setup init \
  --genesis ./configs/network/v2/genesis.json \
  --root ./my-node-config \
  --p2p.bootnodes "4e0b5c952be7f26698dc1898ff3696ac30e990f25891aeaf88b0285eab4663e1#ed25519@node-1.mainnet.truf.network:26656,0c830b69790eaa09315826403c2008edc65b5c7132be9d4b7b4da825c2a166ae#ed25519@node-2.mainnet.truf.network:26656"

For detailed instructions on configuration options more relevant to a production setup, refer to our Configuration Guide.

​
3. Enable State Sync

This will configure your node to use state sync for faster synchronization with the network. Edit the config.toml file using the following command:

sed -i '/\[state_sync\]/,/^\[/ s/enable = false/enable = true/' ./my-node-config/config.toml
sed -i 's/trusted_providers = \[\]/trusted_providers = ["0c830b69790eaa09315826403c2008edc65b5c7132be9d4b7b4da825c2a166ae#ed25519@node-2.mainnet.truf.network:26656"]/' ./my-node-config/config.toml

​
4. Set Up PostgreSQL

For a quick setup, run Kwil’s pre-configured PostgreSQL Docker image:

docker run -d -p 5432:5432 --name tn-postgres \
    -e "POSTGRES_HOST_AUTH_METHOD=trust" \
    -v tn-pgdata:/var/lib/postgresql/data \
    --shm-size=1gb \
    kwildb/postgres:latest

The command above:

  • -v tn-pgdata:/var/lib/postgresql/data: Creates a persistent volume named ‘tn-pgdata’ to store database data
  • --shm-size=1gb: Allocates 1GB of shared memory for PostgreSQL operations (recommended for better performance)

​
5. Create systemd service for kwild and PostgreSQL

# Create systemd service for kwild
sudo tee /etc/systemd/system/kwild.service << EOF
[Unit]
Description=TRUF.NETWORK Node Service
After=network.target tn-postgres.service
Requires=tn-postgres.service

[Service]
Type=simple
User=$USER
WorkingDirectory=$(pwd)
ExecStart=$(which kwild) start -r ./my-node-config
Restart=always
RestartSec=10
LimitNOFILE=65535

[Install]
WantedBy=multi-user.target
EOF
# Create systemd service for PostgreSQL
sudo tee /etc/systemd/system/tn-postgres.service << EOF
[Unit]
Description=TRUF.NETWORK PostgreSQL Service
After=docker.service
Requires=docker.service

[Service]
Type=simple
User=$USER
ExecStart=docker start -a tn-postgres
ExecStop=docker stop tn-postgres
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
EOF

​
6. Run TN Node

Before you proceed, ensure your firewall allows incoming connections on:

  • JSON-RPC port (default: 8484)
  • P2P port (default: 6600)
sudo systemctl daemon-reload
sudo systemctl enable tn-postgres
sudo systemctl enable kwild
sudo systemctl start tn-postgres
sudo systemctl start kwild

Security Warning: It is recommended to not expose port 5432 publicly in production environments.

​
7. Verify Node Synchronization

To become a validator, ensure your node is fully synced with the network:

Use this command to check node sync status. Look for syncing: false in the output, and check that your best_block_height is close to the current network height.

kwild admin status

​
8. Become a Validator (Optional)

To upgrade your node to a validator:

  1. Ensure your node is fully synced with the network.
  2. Submit a validator join request:
kwild validators join
  1. Wait for approval from existing validators. You can check your join request status with:
kwild validators list-join-requests

Existing validators must approve your request. For each existing validator needed to approve:

kwild validators approve <your-node-id>

The node ID format for validator operations is: <public key>#<key type>. For example:

kwild validators approve 03dbe22b9922b5c0f8f60c230446feaa1c132a93caa9dae83b5d4fab16c3404a22#secp256k1

You can find your node’s public key and key type by running:

kwild key info --key-file ./my-node-config/nodekey.json

Note: If you used a different directory name during setup (not ./my-node-config), replace the path with your actual node configuration directory path.

You can always reach out to the community for help with the validator process.

​
9. Submit Your Node to Available Node List (Optional)

To help others discover your node:

  1. Fork the TN repository.
  2. Add your node information to the configs/network/available_nodes.json file.
  3. Submit a Pull Request with your changes.

We’ll review and merge your PR to include your node in the network’s seed list.

​
Network Configuration Files

Essential network configuration files are located in the configs/network/ directory:

  • v2/genesis.json: The network’s genesis file.
  • v2/network-nodes.csv: List of available nodes for peer discovery.

When setting up your node, refer to these files for network-specific parameters and peer information.

​
Node ID Format

Node IDs in TRUF.NETWORK follow the format: <public key>#<key type>@<IP address>:<port>

You can find your node ID by running:

kwild key info --key-file ./my-node-config/nodekey.json

​
Additional Resources

For further assistance, join our Discord community or open an issue on our GitHub repository.

Welcome to the TRUF.NETWORK! Your participation helps build a more robust and decentralized data infrastructure.

​
Troubleshooting

​
Installing pg_dump for Snapshots

To enable state sync functionality, you’ll need pg_dump installed. Here’s how to install it:

For Ubuntu/Debian:

sudo apt-get update
sudo apt-get install postgresql-client-16

For CentOS/RHEL:

sudo yum install postgresql16

For macOS (using Homebrew):

brew install postgresql@16

Verify the installation:

pg_dump --version

Security Warning: It is recommended to not expose port 5432 publicly in production environments.

​
Status

Use this command to view node logs in real-time

sudo journalctl -u kwild -f

This command will provide last 100 lines of logs

sudo journalctl -u kwild -n 100

To view logs with precise timestamp use

sudo journalctl -u kwild -f --output=short-precise

Use this command to check service status

sudo systemctl status kwild

​
Docker Container Status

To check the status of your Docker containers:

docker ps

​
PostgreSQL Logs

To view PostgreSQL container logs:

docker logs tn-postgres

​
System Boot Logs

To view logs since the last system boot:

sudo journalctl -u kwild -b