How to run a NEAR validator node

Introduction

Now is the good time to learn how to run validator on NEAR!

Sooo, In this guide, I’ll show you how to run a validator on the NEAR mainnet. This easy, step-by-step guide will help you quickly join and validate the NEAR network, contribute to its decentralization and resilience, and earn validator rewards along the way!

As a NEAR community member, I’ve been running a NEAR node for over two years, starting with Stake Wars 3 (2022). In this guide, I’ll provide you with a detailed, step-by-step tutorial so you can set up your own NEAR full node based on my experience all these years! 

I’m excited to share everything I’ve learned, offering clear, detailed instructions to guide you through the process of setting up your own validator node on NEAR! Let’s reach 1000 active validators on NEAR! 

Why should you run a NEAR node?

NEAR is the blockchain with a huge amount of activities in web3 space but the minimum requirement for running a node is relatively lightweight, cheap to run, and much easier to maintain compared to other networks.

Top blockchains by activities, source: Artemis.

And here is the minimum hardware requirement for running a node on some popular chains (by network activities)

Basically the requirement for NEAR node is like a consumer laptop that you can find in pretty much anywhere (it’s would better to run on a gaming laptop IMHO 😆).

The cool thing about NEAR is that you don’t need a mainframe (> 512GB ram, 300TB disk space) or even have to set up a whole database center to run and you actually can be profitable without the Foundation cover basis cost, unlike other chains!

Of course, for the node, the powerful machine, the better it performs!
I personally run my node in a machine with 32gb of RAM and 2TB NVME SSD on 12 CPU cores, which costs around 70$/month.

Other reasons are when you need to run applications that heavily depend on RPC performance and/or availability, develop and deploy contracts on a local (independent and isolated) node (sometimes called “localnet”) or quickly extract blockchain data that can be used for chain analytics, block explorer, etc…

That’s pretty much reason to be bullish 🐂 on running a NEAR node, so we start now!

Installation

Requirements

• You can use any Linux distribution but for this guide I will use Ubuntu, the requirement for Ubuntu version is 20.04 or newer, mine is running 22.04
• Minimum hardware requirement:
  • 8GB of RAM (recommended 16gb+)
  • ~1 TB of NVME SSD ( recommended 1.5TB+ )
  • CPU with 8 cores, CPU features: CMPXCHG16B, POPCNT, SSE4.1, SSE4.2, AVX, SHA-NI
  • 1GB network connection.

Setup

Setup NEAR mainnet

You will need a NEAR address for running the node, this address will also get network rewards for running an active validator.

• Create a FREE named NEAR address here: https://wallet.meteorwallet.app I created lncvalidator.near for this guide
  
• Deposit around 31 NEAR to the address, 30 NEAR needed for creating the staking pool and will be locked for storage, you can recover those NEAR later if you don’t run the node anymore.
• Import the account to https://app.mynearwallet.com/

Install libraries and Nearcore

Now is the fun part, let’s setup the NEAR node, login to your server and run the following commands first to update OS, install tools and libraries (near-cli, node, Python, Git, docker…).

Please note: All commands in this guide will be needed to run under root user!

sudo apt update && sudo apt upgrade -y && sudo apt install -y git binutils-dev libcurl4-openssl-dev zlib1g-dev libdw-dev libiberty-dev cmake gcc g++ python3 docker.io protobuf-compiler libssl-dev pkg-config clang llvm awscli tmux jq ccze nodejs npm

sudo npm install -g n && n stable && npm install -g near-cli

Install Rust

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

source "$HOME/.cargo/env"

rustup -V

During the installation, if asked, just press Yes and default for everything!

Clone the nearcore repo, choose the latest stable branch for mainnet and build the nearcore from source

cd ~ && git clone https://github.com/near/nearcore && cd nearcore/ && git checkout <VERSION>

make release

echo 'export NEAR_ENV=mainnet' >> ~/.bashrc

source ~/.bashrc

for the VERSION, get the latest mainnet release version here: https://github.com/near/nearcore/releases, for example, the current version is 2.2.1, so the checkout command will become git checkout 2.2.1.

This build process (make release) will take around 15 minutes, you need to wait for it before going to next commands.

Authorize wallet

near login

Note: This command launches a web browser allowing for the authorization of a full access key to be copied locally.

1 – Copy the link in your browser

2 – Grant Access to Near CLI

3 – After Grant, you will see a page like this, go back to console

4 – Enter your wallet and press Enter

Initialize & Start the Node

Definitions:

• <pool_id> or pool_id – your pool name, for example lncvalidator
• <full_pool_id> or full_pool_id – xxx.poolv1.near, where xxx is your pool_id
• <accountId> or accountId – xxx.near where xxx your account name, for example lncvalidator.near

cd ~/nearcore && target/release/neard init --chain-id="mainnet" --account-id=<full_pool_id>

Set your full_pool_id, example: xxx.poolv1.near, where xxx is your pool_id, for example: lncvalidator.poolv1.near

Download the latest genesis and config, if config already exist just delete it and download a new one:

cd ~/.near && rm genesis.json && rm config.json

wget -c https://s3-us-west-1.amazonaws.com/build.nearprotocol.com/nearcore-deploy/mainnet/genesis.json

wget -c https://s3-us-west-1.amazonaws.com/build.nearprotocol.com/nearcore-deploy/mainnet/config.json

Generate the Key and Copy the file generated to mainnet folder, make sure to replace your <full_pool_id> (in this case, lncvalidator.poolv1.near )

near generate-key <full_pool_id>

cp ~/.near-credentials/mainnet/<full_pool_id>.json ~/.near/validator_key.json

nano ~/.near/validator_key.json

• Change “account_id” => full_pool_id , in this case, lncvalidator.poolv1.near
• Change “private_key” to “secret_key”

Note: The account_id must match the staking pool contract name or you will not be able to sign blocks.
File content must be something like this

Note: If your node has only less than 1TB disk space, you will need to lower “epoch data to keep” to avoid disk full issue.
edit ~/.near/config.json and reduce “gc_num_epochs_to_keep” to 3 instead of default 5:

Setup Systemd so the node will always run with the system

sudo nano /etc/systemd/system/neard.service

Paste:

Description=NEARd Daemon Service
[Service]
Type=simple
User=root
WorkingDirectory=/root/.near
ExecStart=/root/nearcore/target/release/neard run
Restart=on-failure
RestartSec=30
KillSignal=SIGINT
TimeoutStopSec=45
KillMode=mixed
[Install]
WantedBy=multi-user.target

After that, enable the service:

sudo systemctl enable neard

Sync data: To sync data faster, we can download the backup archive instead of waiting for node sync with other peers.

• Install s5cmd: https://github.com/peak/s5cmd/releases

cd ~/.near

mkdir data

cd data

aws s3 --no-sign-request cp s3://near-protocol-public/backups/mainnet/rpc/latest .

LATEST=$(cat latest)

s5cmd --no-sign-request sync s3://near-protocol-public/backups/mainnet/rpc/$LATEST/*.

Note: If your disk space has only 1TB, in some cases you may run out of disk space during the download, in that case, the trick is just simply stop the download process, restart the node and wait for it to sync from peers. (since we already reduce gc_num_epochs_to_keep, so the node will only keep 3 most recent epoch and it should fit your server disk)

After the data sync completed, we now can start the node:

sudo systemctl start neard

If you need to make a change to service in the config.json file, the node also need to be reloaded:

sudo systemctl reload neard

Watch logs

Command:

journalctl -n 100 -f -u neard | ccze -A

Check the running status of the validator node. If “Validator” is showing up in the log, your pool is selected in the current validators list.

Becoming an active Validator

In order to become a validator and enter the validator set, a minimum set of success criteria must be met.

• The node must be fully synced
• The validator_key.json must be in place
• The contract must be initialized with the public_key in validator_key.json
• The account_id must be set to the staking pool contract id
• There must be enough delegations to meet the minimum seat price. See the seat price here. or here
• A proposal must be submitted by pinging the contract
• Once a proposal is accepted a validator must wait 2-3 epoch to enter the validator set
• Once in the validator set the validator must produce great than 90% of assigned blocks or your node will be kick out

Check the running status of the validator node. If “Validator” is showing up, your pool is selected in the current validators list.

Deploy your staking pool contract

NEAR uses a staking pool factory with a whitelisted staking contract to ensure delegators’ funds are safe. In order to run a validator on NEAR, a staking pool must be deployed to a NEAR account and integrated into a NEAR validator node. Delegators must use a UI or the command line to stake to the pool. A staking pool is a smart contract that is deployed to a NEAR account.

Note: STAKING POOL CONTRACT CANNOT HAVE WRITE ACCESS TO ALL SUB ACCOUNTS FUNDS OR DATA, this also applies for any sub accounts on NEAR.

Deploy a Staking Pool Contract

Calls the staking pool factory, creates a new staking pool with the specified name, and deploys it to the indicated accountId.

For Mainnet

near call poolv1.near create_staking_pool '{"staking_pool_id": "<pool_id>", "owner_id": "<accountId>", "stake_public_key": "<public key>", "reward_fee_fraction": {"numerator": 5, "denominator": 100}}' --accountId="<accountId>" --amount=30 --gas=300000000000000

From the example above, you need to replace:

• pool_id: Staking pool name, the factory automatically adds its name to this parameter, creating {pool_id}.{staking_pool_factory}.
  example “lncvalidator”
• owner_id:: The NEAR account that will manage the staking pool. Usually your main NEAR account.
• public_key: The public key in your validator_key.json file.
• 5: The fee the pool will charge (e.g. in this case 5 over 100 is 5% of fees), usually validator takes 5% fee
• accountId: The NEAR account deploying the staking pool.

full_pool_id: <pool_id>.poolv1.near , it’s lncvalidator.poolv1.near in this case

Be sure to have at least 30 NEAR available, it is the minimum required for storage.

Final command will look something like this:

near call poolv1.near create_staking_pool '{"staking_pool_id": "lncvalidator", "owner_id": "lncvalidator.near", "stake_public_key": "ed25519:A9RdmNFxxx", "reward_fee_fraction": {"numerator": 5, "denominator": 100}}' --accountId="lncvalidator.near" --amount=30 --gas=300000000000000

To change the pool parameters, such as changing the amount of commission charged to 1% in the example below, use this command:

near call <full_pool_id> update_reward_fee_fraction '{"reward_fee_fraction": {"numerator": 1, "denominator": 100}}' --accountId <account_id> --gas=300000000000000

You will see something like this:

If there is a “True” at the End. Your pool is created.

Congrats! You have now configure your Staking pool up and running 🚀🚀🚀🚀

Manage your staking pool contract

Retrieve the owner ID of the staking pool

near view <full_pool_id> get_owner_id '{}'

Issue this command to retrieve the public key the network has for your validator

near view <full_pool_id> get_staking_key '{}'

If the public key does not match you can update the staking key like this (replace the pubkey below with the key in your validator.json file)

near call <full_pool_id> update_staking_key '{"stake_public_key": "<public key>"}' --accountId <accountId>

Working with Staking Pools

NOTE: Your validator must be fully synced before issuing a proposal or depositing funds.

Proposals and Pings

In order to get a validator seat you must first submit a proposal with an appropriate amount of stake. Proposals are sent for epoch +2. Meaning if you send a proposal now, if approved, you would get the seat in 3 epochs. You should submit a proposal every epoch to ensure your seat. To send a proposal we use the ping command. A proposal is also sent if a stake or unstake command is sent to the staking pool contract.

To note, a ping also updates the staking balances for your delegators. A ping should be issued each epoch to keep reported rewards current on the pool contract. You could set up a ping using a cron job with a ping script here.

Create a new file on /home/root/scripts/ping.sh and fill this:

#!/bin/sh
# Ping call to renew Proposal added to crontab

export NEAR_ENV=mainnet
export LOGS=/home/root/logs
export POOLID=<full_pool_id>
export ACCOUNTID=<account_id>

echo "---" >> $LOGS/all.log
date >> $LOGS/all.log

near call $POOLID ping '{}' --accountId $ACCOUNTID --gas=300000000000000 >> $LOGS/all.log

near proposals | grep $POOLID >> $LOGS/all.log
near validators current | grep $POOLID >> $LOGS/all.log
near validators next | grep $POOLID >> $LOGS/all.log

Create logs folder:

mkdir $HOME/logs

Change execute permission for ping.sh file:

chmod +x $HOME/scripts/ping.sh

Create a new crontab, I personally setup it to run running every 8 hours:

crontab -e

Fill this and save

0 */8 * * * sh /home/root/scripts/ping.sh

List crontab to see it is running:

crontab -l

Review your logs

cat $HOME/logs/all.log

That is it, now you need to have enough delegated tokens to be an active validator, welcome to decentralized Near Protocol and earning rewards along the way 🚀🚀🚀🚀 💪💪💪💪 🛳️🛳️🛳️👽👽👽🛸🛸🛸

Network optimizations

To optimize the network settings for better performance, execute the following commands:

MaxExpectedPathBDP=8388608
sudo sysctl -w net.core.rmem_max=$MaxExpectedPathBDP
sudo sysctl -w net.core.wmem_max=$MaxExpectedPathBDP
sudo sysctl -w net.ipv4.tcp_rmem="4096 87380 $MaxExpectedPathBDP"
sudo sysctl -w net.ipv4.tcp_wmem="4096 16384 $MaxExpectedPathBDP"
sudo sysctl -w net.ipv4.tcp_slow_start_after_idle=0

These changes do not persist across system restarts. To apply them automatically on boot, add the following in /etc/sysctl.d/local.conf:

net.core.rmem_max = 8388608
net.core.wmem_max = 8388608
net.ipv4.tcp_rmem = 4096 87380 8388608
net.ipv4.tcp_wmem = 4096 16384 8388608
net.ipv4.tcp_slow_start_after_idle = 0

Optional: Submitting Pool Information

Adding pool information helps delegators and also helps with outreach for upgrades and other important announcements: https://github.com/zavodil/near-pool-details.

The available fields to add are: https://github.com/zavodil/near-pool-details/blob/master/FIELDS.md.

The identifying information that we ask the validators to provide are: Name, Description, Url, Telegram, Twitter,…

Example commands:

Replace <full_pool_id> with your pool address, for example: lncvalidator.poolv1.near
Replace <accountId> with your authenticated wallet address, lncvalidator.near for this case

near call pool-details.near update_field '{"pool_id": "<full_pool_id>", "name": "url", "value": "https://yoururl.com"}' --accountId=<accountId> --gas=200000000000000

near call pool-details.near update_field '{"pool_id": "<full_pool_id>", "name": "twitter", "value": "<twitter>"}' --accountId=<accountId> --gas=200000000000000

near view pool-details.near get_all_fields '{"from_index": 0, "limit": 3}'

near view pool-details.near get_fields_by_pool '{"pool_id": "<full_pool_id>"}'

The info will show like this: (source: NearScope)

Maintaining the node

it’s important to maintain your node and keep it running stable, here is a few important things you need to know

Node status codes

• RED: update your node ASAP!!1!!!, something critical happended, I repeat, update-it-AS-SOON-AS-POSSIBLE!!
• YELLOW: you need to update the node, but it is not too urgent for now.
  Find our more here: https://near-nodes.io/maintenance/maintenance#runtime-alerts

NEAR Validator community on Telegram

Join the group to get node update, supports and mores, please use this group for questions and discussions related to validation on NEAR
https://t.me/near_validators

Update new node version

When there is a new node version, you will get a notification on the Telegram Validator group, run this command to update the node.

cd ~/nearcore && git fetch && export NEAR_RELEASE_VERSION=<node_version> && git checkout $NEAR_RELEASE_VERSION && make release && sudo systemctl stop neard && sudo systemctl start neard

Replace <node_version> with the correct nearcore release version.

Monitor the node performance

Monitor the node in a Pro way:
https://near-nodes.io/validator/validator-bootcamp#grafana

Monitor the node in a degen way:
I created a small bot to help you quickly monitor the validator uptime here, you can take a look:
https://x.com/cuongdc_real/status/1839769081723138239

Withdraw your rewards

Basically just login to any wallet on NEAR and claim your validator rewards at the wallet staking section.

Resources

• NEAR Validators concept: https://docs.near.org/concepts/basics/validators
• NEAR Nodes – The official NEAR Validator docs that every validators should take a look: https://near-nodes.io/
• MainnetGo – NEAR Validator Guide🚀: https://github.com/Open-Shard-Alliance/MainnetOnboarding/blob/main/MainnetGO.md
• Calculate NEAR staking rewards: https://www.stakingrewards.com/asset/near-protocol
• View validators info on these websites
  • https://near-staking.com/
  • https://nearblocks.io/node-explorer
  • https://legacy.explorer.near.org/nodes/validators

Conclusion

 

Thank you so much for reading this far! That’s everything I wanted to share about running a validator on NEAR.
In my experience, running a NEAR node is straightforward and almost bug-free, with far fewer issues compared to other high-activity chains. NEAR requires significantly fewer server resources due to its sharding with Nightshade. Plus, you earn rewards along the way!

Speaking of rewards, soon, NEAR validators will also have the opportunity to earn rewards for running the MPC network, which contributes to NEAR’s Chain Abstraction service for the broader Web3 ecosystem. With its vision of building the Open Web through Chain Abstraction and User-Owned AI, NEAR is poised to see even more network activity, giving validators the chance to earn additional rewards.

As a validator, your role is crucial in securing a high-performance network like NEAR. By safeguarding NEAR, you are also supporting many applications built on the network, such as Kaiching (a cashback app used by millions in Singapore), Sweatcoin (a health and fitness app with 100 million users worldwide), HOT (a Web3 wallet that serves as a gateway for new crypto users), and Ref Finance (a decentralized exchange on NEAR).

These apps serve millions of users daily, and as a validator, you’re essential in helping them maintain their services and grow!