W Chain Website

📦Validator Node Setup

This section will guide you through setting up a Validator Node on W Chain.

Step 1: Prepare the System

Before starting, ensure your system meets the minimum requirements for running a node:

  • vCPUs: 4 or more

  • Memory: At least 16GB

  • Disk Space: At least 1TB (SSD or NVMe recommended for optimal performance)

  • Operating System: Ubuntu 20.04, 22.04, or 24.04

  • Node JS v.22 and NPM v10 or newer

  • Internet Connection: A broadband connection with at least 5Mbps upload/download speed.

It's possible to run a node from a local dedicated server, but it's recommended to run it on a professional cloud providers such as AWS, Digital Ocean, Azure or GCP.

Step 2: Install Dependencies

Make sure you have up-to-date version of Ubuntu, Git and NPM installed.

sudo apt update && sudo apt upgrade -y
sudo apt install git -y && sudo apt install npm -y

Some system may have different package manager, here we use apt, the most commonly used

Step 3: Prepare Directory

cd ~
mkdir w-chain
cd w-chain

Step 4: Download files from latest Release

To initiate a Node, you need the latest binary and genesis.json. It always available at W Chain's Github Repository for W chain Node.

You need to select the suitable binary based on your Operating System and architecture. You can contact your Cloud Computing Provider if you are not sure about yours.

In this guide, we will use the most common one: Linux (amd64), as it's widely used in AWS EC2 instances.

Download BInary File

In this example we are using v.1.0.6

You can download the latest binary file using wget or curl

curl -L -O https://github.com/w-chain/node/releases/download/v1.0.6/w-chain-node_v1.0.6_linux_amd64.tar.gz

After the download complete, print your directory contents to get the downloaded file name:

ls -lh

The file name will be in this format: "w-chain-node_" + version tag + system + "_" + architecture + ".tar.gz". Extract the file:

tar -xzf w-chain-node_v1.0.6_linux_amd64.tar.gz

Rename the file (Optional, but important for better UX):

mv w-chain-node-linux-amd64 w-chain-node

Download genesis.json

curl -L -O https://github.com/w-chain/node/releases/download/v1.0.6/genesis.json

You don't need to change anything from this genesis.json, just make sure it exists in the same directory with your binary file.

Step 5: Verify Files

Make sure both binary file and genesis.json is correctly downloaded and in stored in same directory.

Turn the binary file into executable:

chmod +x w-chain-node

Verify the version:

./w-chain-node version

[VERSION INFO] Release version = 1.0.6

Step 6: Initialize Keys and Blockchain Data Directories

This command will initialize data directory and validator keys:

./w-chain-node secrets init --data-dir main-chain --insecure

You will see the newly created public keys printed like this:

[SECRETS OUTPUT]
Public key (address) = 0x9C107AA6471e3...E9c6EdE083b8f5
BLS Public key       = 0x800f1157a49bb59f5e5d790...fe349fa19a3c323f518a4bd4aa963
Node ID              = 16Uiu2HAmVbykGW...DUpLgTw7NbDVbKf1Me4D

You can copy-paste it to some quick note to be used in next steps. We will also need the Private Key of this newly created Public Key.

cd ~/w-chain/main-chain/consensus
nano validator.key

You will see a single line of string. This is the Private Key.

Same as above, copy the Private Key and store it somewhere safe, we will use it in next step.

When you are done, exit the text editor, no need to save anything. And go back to root directory of your Node:

cd ../../

Step 7: Create Server Config

The node is basically a server that will run 24/7, responding to queries and persisting blocks to database. Instead of passing the configs as flags to server command, it's strongly recommended to store the server configs in a json/yaml file.

Run this command (in /w-chain directory) to generate server config template:

./w-chain-node server export --type json
ls -lh

You will see a file, default-config.json created.

Now, we will edit this config file to adjust with your actual server configuration.

You can use any supported text editor, in this example we use nano.

sudo nano default-config.json

This config below assuming you are following previous steps convention on directory creation. It also recommended to use absolute path, which can be different from system to system (usually /home/user/w-chain)

genesis.json location

"chain_config": "/home/ubuntu/w-chain/genesis.json",

Path to Data Directory

"data_dir": "/home/ubuntu/w-chain/main-chain",

Ports

"grpc_addr": "127.0.0.1:9632", 
"jsonrpc_addr": "0.0.0.0:8545",

NAT Address is your server/instance's Public IP

"network": {
    ...
    "libp2p_addr": "0.0.0.0:1478", 
    "nat_addr": "12.34.567.890",
    ...
}

Minimum Gas Price accepted and Seal flag

For Validator Node, Seal must be true. Per v1.0.6 Min Gas Price in W Chain Network is 8 Gwei

"price_limit": 800000000000,
"seal": true

Step 8: Utilizing Blockchain Backup File

Joining a blockchain network will require a new node to sync with other existing nodes, this can take days even weeks, depends on how long the network already running so far. We have prepared backup files to jump start the process for you.

This backup file will be updated from time to time to ensure new node operators will have closer starting point to sync their new nodes to W Chain Network

# In the ./w-chain directory
cd main-chain

Download and unpack Trie

curl -L -O https://w-chain-data.s3.eu-north-1.amazonaws.com/trie.tar.gz
tar -xzf trie.tar.gz && rm trie.tar.gz

Download and unpack Blockchain

curl -L -O https://w-chain-data.s3.eu-north-1.amazonaws.com/blockchain.tar.gz
tar -xzf blockchain.tar.gz && rm blockchain.tar.gz

Downloading and unpacking the Blockchain backup file will take some time, depends on your internet connection speed and Storage I/O rate

After this step, you should have 2 new directories (blockchain and trie), in addition to the existing consensus and libp2p.

Aligning permission and directory ownership

pwd

This will print your current working directory (i.e. /home/ubuntu/w-chain/main-chain), copy it.

ls -ld /w-chain/main-chain

you will see something like this:

drwxr-x--- 6 ubuntu ubuntu 4096 Apr 12 14:08 /data/w-chain/main-chain

based on the example above, we can see the user and user group is ubuntu:ubuntu (this may vary, depends on your system). Now, that we know the user and user group, we can align the permission:

sudo chown -R ubuntu:ubuntu /home/ubuntu/w-chain/main-chain

Now, your blockchain data is ready!

Step 9: Staking Contract

To join W Chain Network as a Validator Node, each node must stake at least 10,000,000 (10 Million) WCO. This is to ensure the Node operators to act honestly and follow the consensus, as any malicious act will result to stake slashing (rogue node will lose a part of its staked WCO).

Running Node in W Chain Network also offer a lucrative Staking Reward, which explained in more details in this section.

Clone Staking Contract Script from W Chain Repository

cd ~/w-chain
git clone https://github.com/w-chain/staking-contract.git

It should create new directory: staking-contract. Enter the directory and install the node dependencies

cd ~/w-chain/staking-contract
npm i

The process will only take few seconds, run this command next:

cp .env.example .env
sudo nano .env

This will copy the template .env and open it in a text editor, you will see this:

#JUST ADD YOUR PRIVATE KEY HERE
PRIVATE_KEY=your_private_key_here

# KEEP THIS AS IS
CONTRACT_ADDRESS=0xfAc510D5dB8cadfF323D4b979D898dc38F3FB6dF
RPC_URL=https://rpc.w-chain.com

Replace your_private_key_here with the actual Private Key you copied back in Step 6. Do not change anything else, save and exit the text editor.

Step 10: Load up the Stake

(Optional) You can import the Private Key to a wallet app for your convenience.

The next important step is to fund the Validator address (Public Key) with WCO. Please remember, you need some WCO for gas fee, too! Ideally, you should have at least 10,000,001 WCO inside this address.

After you fund the address, go to /staking-contract directory and run the stake script:

cd ~/w-chain/staking-contract
npm run cli stake 10000000

Wait for the script to process, if everything is correct, you will get the transaction hash returned.

Next, we will register BLS Public Key (obtained from Step 6). Run this command:

npm run cli registerBLSPublicKey 0x800f1157a49bb59f5e5d790...fe349fa19a3c323f518a4bd4aa963

This is an example, use your actual BLS Public Key

Wait for the script to process the on-chain call, if everything is correct, you will get the transaction hash returned.

You can use isValidator method (npm run cli isValidator <address>) to verify if your Public Key is now registered as Validator.

After you done the stake and registerBLSPublicKey, your Validator Node is ready to run!

Step 11: Create a System Service

To keep your Node instance running as a background service, you need to define the service. Run this on your terminal (inside your server/instance).

sudo nano /etc/systemd/system/w-chain-node.service

The text editor will open a blank page. Copy-paste the texts below into it:

[Unit]
Description=W Chain Validator Node
After=network.target
StartLimitIntervalSec=1

[Service]
Type=simple
User=ubuntu
ExecStart=/home/ubuntu/w-chain/w-chain-node server --config /home/ubuntu/w-chain/default-config.json

[Install]
WantedBy=multi-user.target

Then save and exit the text editor.

Once again, this is assuming you are following the directory and filename convention from previous steps. Your system may have different absolute path and different user, please adjust as needed.

Step 12: Enable and Run the Node Service

After installing new service, you have to reload the service daemon and enable the service.

sudo systemctl daemon-reload
sudo systemctl enable w-chain-node.service

Then start the service:

sudo systemctl start w-chain-node.service

Congratulations! Your node is now running and will start to catch up with the network, this may take few days, depends on the block-height and the I/O performance of your node.

Important Commands to Maintain and Monitor Your Node

Service

sudo systemctl start w-chain-node

Logging

journalctl -u w-chain-node
PreviousNon-Validator Node SetupNextW Chain Client APIs

Last updated