Run an RPC Node

The Shardeum mainnet has successfully upgraded to v1.1.0 (Cosmos EVM v0.6.3). Network operations have resumed, and v1.1.0 is the current mainnet release. New nodes syncing from genesis must follow the historical binary instructions in the Start and Sync the Node section below. View upgrade details | Download v1.1.0

An RPC node provides JSON-RPC and WebSocket endpoints for developers, dApps, indexers, infrastructure providers, and partners. RPC nodes verify chain data but do not participate in consensus or require staking.

Do not expose the node's CometBFT RPC endpoint publicly. Only expose application RPC endpoints that are required for your deployment, and protect them with appropriate access controls and rate limiting.

1. System Requirements

Recommended:

OS: Ubuntu 22.04 LTS
CPU: 4 cores
RAM: 8–16 GB
Storage: 500 GB+ NVMe SSD
Network: High-bandwidth connection
Dependencies: git, jq, curl, make, build-essential, pkg-config
Go: v1.25+

Install dependencies:

sudo apt update
sudo apt install git jq curl make build-essential pkg-config -y

Install Go:

curl -LO https://go.dev/dl/go1.25.0.linux-amd64.tar.gz
sudo rm -rf /usr/local/go
sudo tar -C /usr/local -xzf go1.25.0.linux-amd64.tar.gz
echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.bashrc
source ~/.bashrc
go version

2. Install Shardeum Node Binary

git clone https://github.com/shardeum/shardeum-evm.git
cd shardeum-evm
git fetch --tags
git checkout v1.1.0
make install

Add the Go bin directory to PATH:

echo 'export PATH=$PATH:$HOME/go/bin' >> ~/.bashrc
source ~/.bashrc

Verify the installation:

shardeumd version
command -v shardeumd

3. Environment Variables

export SHARDEUM_CONFIG_DIR="$PWD/config"
export SHARDEUM_NETWORK=mainnet
export BINARY=$(command -v shardeumd)

4. Initialize the Node

NODE_ID="rpcnode"
MONIKER="shardeum-rpc"
 
shardeumd init "$MONIKER" \
  --chain-id shardeum_8118-1 \
  --home $HOME/.mainnet/$NODE_ID \
  --overwrite

5. Copy Genesis File

cp config/mainnet-genesis.json $HOME/.mainnet/$NODE_ID/config/genesis.json
jq -r '.chain_id' $HOME/.mainnet/$NODE_ID/config/genesis.json

6. Configure Pruning

For a typical RPC node, custom pruning helps manage storage while retaining recent state.

Edit:

$HOME/.mainnet/$NODE_ID/config/app.toml

Set:

pruning = "custom"
pruning-keep-recent = "10000"
pruning-interval = "50"

If you require complete historical state, run an Archive Node instead. Archive nodes disable pruning using --pruning nothing.

7. Enable JSON-RPC before the first start

Edit:

$HOME/.mainnet/$NODE_ID/config/app.toml

Under the existing [json-rpc] section, set:

enable = true
address = "0.0.0.0:8545"
ws-address = "0.0.0.0:8546"

8. Start and Sync the Node

Before You Start: Syncing a New Node From Genesis After a State-Breaking Upgrade

Skip this section if your node is already synced past the latest upgrade height or if you are restoring from a compatible post-upgrade snapshot.

If a compatible post-upgrade snapshot is available, use the snapshot to bootstrap the node with the current binary. The Cosmovisor instructions below are only for nodes syncing from genesis.

When syncing a new node from genesis after a state-breaking upgrade, the node must use the binary version that corresponds to each part of the chain history.

For the current Shardeum mainnet chain history:

Use v1.0.2 to sync from genesis until the upgrade at height 7,927,860.
At the upgrade, Cosmovisor switches the node to v1.1.0.
Continue syncing with v1.1.0.

Use Cosmovisor to manage the binary switch at the upgrade height.

Set Up Cosmovisor and the Required Binaries

Install Cosmovisor:

go install cosmossdk.io/tools/cosmovisor/cmd/cosmovisor@latest
 
export PATH=$PATH:$HOME/go/bin
 
cosmovisor version

Cosmovisor uses the node's home directory to store and manage the binaries required for each part of the chain history. Set the required environment variables:

export DAEMON_NAME=shardeumd
export DAEMON_HOME="$HOME/.mainnet/$NODE_ID"
export DAEMON_ALLOW_DOWNLOAD_BINARIES=false
export DAEMON_RESTART_AFTER_UPGRADE=true

Run the remaining Cosmovisor commands in the same shell session so these environment variables remain available.

Download the required Shardeum binaries from the official releases:

Important: Use the current v1.0.2 binary from the official release. An earlier v1.0.2 binary published before October 16, 2026 cannot replay Shardeum mainnet from genesis.

mkdir -p "$HOME/shardeum-binaries"
cd "$HOME/shardeum-binaries"
 
curl -L \
  -o shardeumd-v1.0.2-linux-amd64 \
  https://github.com/shardeum/shardeum-evm/releases/download/v1.0.2/shardeumd-v1.0.2-linux-amd64
 
curl -L \
  -o shardeumd-v1.1.0-linux-amd64 \
  https://github.com/shardeum/shardeum-evm/releases/download/v1.1.0/shardeumd-v1.1.0-linux-amd64

Verify the SHA-256 checksums:

echo "1b57360a1d9ad340e396105521e19237cea5d162cc68eb265f00b1fe206d8849  shardeumd-v1.0.2-linux-amd64" | sha256sum -c -
 
echo "08cf7e6a7381bc8ffabaf265a2571304353409d85a7504f3d96fcfb0b2240f89  shardeumd-v1.1.0-linux-amd64" | sha256sum -c -

Both commands should return OK.

Make the binaries executable:

chmod +x shardeumd-v1.0.2-linux-amd64
chmod +x shardeumd-v1.1.0-linux-amd64

Initialize Cosmovisor with v1.0.2 as the genesis binary:

cosmovisor init "$HOME/shardeum-binaries/shardeumd-v1.0.2-linux-amd64"

Add v1.1.0 using the exact upgrade name:

cosmovisor add-upgrade \
  v0.4.0-to-v0.6.3 \
  "$HOME/shardeum-binaries/shardeumd-v1.1.0-linux-amd64"

Verify that both binaries are in place:

"$DAEMON_HOME/cosmovisor/genesis/bin/shardeumd" version
 
"$DAEMON_HOME/cosmovisor/upgrades/v0.4.0-to-v0.6.3/bin/shardeumd" version

Cosmovisor starts with v1.0.2. When the node reaches the upgrade at height 7,927,860, it detects the onchain upgrade and switches to v1.1.0 automatically.

Start a Genesis Sync With Cosmovisor

If you followed the genesis-sync instructions above, start the node through Cosmovisor:

cosmovisor run start \
  --home $HOME/.mainnet/$NODE_ID \
  --chain-id shardeum_8118-1 \
  --p2p.seeds ab6c31d63a4a30918dea8d74fb0393e5e10477c4@34.93.180.93:27656,3c722839d9745fc13df16cdfe0eb53f219a30949@34.14.143.72:27656 \
  --p2p.laddr tcp://0.0.0.0:27656 \
  --rpc.laddr tcp://127.0.0.1:26657 \
  > $HOME/.mainnet/$NODE_ID/node.log &

Start the Node Normally

If you skipped the genesis-sync section because your node is already past the latest upgrade height or you restored from a compatible post-upgrade snapshot, start the node normally:

shardeumd start \
  --home $HOME/.mainnet/$NODE_ID \
  --chain-id shardeum_8118-1 \
  --p2p.seeds ab6c31d63a4a30918dea8d74fb0393e5e10477c4@34.93.180.93:27656,3c722839d9745fc13df16cdfe0eb53f219a30949@34.14.143.72:27656 \
  --p2p.laddr tcp://0.0.0.0:27656 \
  --rpc.laddr tcp://127.0.0.1:26657 \
  > $HOME/.mainnet/$NODE_ID/node.log &

Monitor:

shardeumd status --home $HOME/.mainnet/$NODE_ID | jq '.SyncInfo'

tail -f $HOME/.mainnet/$NODE_ID/node.log

Wait until the node is fully synced.

9. Optional: Enable gRPC & REST Endpoints

Edit:

$HOME/.mainnet/$NODE_ID/config/app.toml

Under the existing [grpc] section, set:

enable = true
address = "0.0.0.0:9090"

Under the existing [api] section, set:

enable = true
address = "tcp://0.0.0.0:1317"

Enable these only if required by your infrastructure. Restart the node after making changes.

10. Firewall Configuration

Before enabling UFW, allow SSH access so you do not lock yourself out of the server:

sudo ufw allow OpenSSH

Allow P2P traffic:

sudo ufw allow 27656/tcp

Allow the RPC endpoints required for your deployment:

sudo ufw allow 8545/tcp   # JSON-RPC
sudo ufw allow 8546/tcp   # WebSocket

If you enabled the optional gRPC or REST endpoints, also allow:

sudo ufw allow 9090/tcp   # gRPC
sudo ufw allow 1317/tcp   # REST API

Then enable and check the firewall:

sudo ufw enable
sudo ufw status

Do not expose port 26657 (CometBFT RPC) publicly. Restrict sensitive endpoints to localhost or trusted systems, and protect public RPC endpoints with suitable rate limiting and reverse-proxy controls.

11. systemd Service (Recommended)

A systemd service can automatically restart the RPC node and simplify node management.

Check the installed binary paths:

command -v shardeumd
command -v cosmovisor

Create the service file:

sudo nano /etc/systemd/system/shardeumd-rpc.service

Choose one of the following service configurations depending on how the node was started.

The examples below assume the node was installed and initialized as the root user. If you used another system user, replace User=root, /root/.mainnet/rpcnode, and /root/go/bin with the corresponding user and paths.

Standard systemd Service

Use this configuration if the node is running directly with shardeumd.

[Unit]
Description=Shardeum RPC Node
After=network-online.target
 
[Service]
User=root
ExecStart=<shardeumd-binary-path> start \
  --home /root/.mainnet/rpcnode \
  --chain-id shardeum_8118-1 \
  --p2p.seeds ab6c31d63a4a30918dea8d74fb0393e5e10477c4@34.93.180.93:27656,3c722839d9745fc13df16cdfe0eb53f219a30949@34.14.143.72:27656 \
  --p2p.laddr tcp://0.0.0.0:27656 \
  --rpc.laddr tcp://127.0.0.1:26657
Restart=on-failure
RestartSec=3
LimitNOFILE=65535
 
[Install]
WantedBy=multi-user.target

Replace <shardeumd-binary-path> with the path returned by:

command -v shardeumd

systemd Service With Cosmovisor

If you followed the genesis-sync instructions and configured Cosmovisor, use this configuration instead.

[Unit]
Description=Shardeum RPC Node
After=network-online.target
 
[Service]
User=root
Environment="DAEMON_NAME=shardeumd"
Environment="DAEMON_HOME=/root/.mainnet/rpcnode"
Environment="DAEMON_ALLOW_DOWNLOAD_BINARIES=false"
Environment="DAEMON_RESTART_AFTER_UPGRADE=true"
Environment="PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/root/go/bin"
ExecStart=<cosmovisor-binary-path> run start \
  --home /root/.mainnet/rpcnode \
  --chain-id shardeum_8118-1 \
  --p2p.seeds ab6c31d63a4a30918dea8d74fb0393e5e10477c4@34.93.180.93:27656,3c722839d9745fc13df16cdfe0eb53f219a30949@34.14.143.72:27656 \
  --p2p.laddr tcp://0.0.0.0:27656 \
  --rpc.laddr tcp://127.0.0.1:26657
Restart=on-failure
RestartSec=3
LimitNOFILE=65535
 
[Install]
WantedBy=multi-user.target

Replace <cosmovisor-binary-path> with:

command -v cosmovisor

If the node is already running from the previous section, stop the manually started process before starting it through systemd.

Then:

sudo systemctl daemon-reload
sudo systemctl enable shardeumd-rpc
sudo systemctl start shardeumd-rpc
sudo systemctl status shardeumd-rpc

View logs:

journalctl -u shardeumd-rpc -f

12. Scaling RPC Nodes (Optional)

For high-traffic dApps:

Use load balancers such as Nginx, HAProxy, or AWS ELB
Run multiple RPC nodes behind a reverse proxy
Rate-limit requests to avoid overload
Separate public RPC from private infrastructure RPC
Run dedicated indexing services in parallel where required

13. Useful Commands

Check sync:

shardeumd status --home $HOME/.mainnet/$NODE_ID | jq '.SyncInfo'

Check network peers:

curl -s http://localhost:26657/net_info | jq '.result'

Check logs:

journalctl -u shardeumd-rpc -f

Query RPC:

curl -s http://localhost:8545 \
  -X POST \
  -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'

14. Troubleshooting

RPC endpoint not responding

Confirm RPC enabled in app.toml
Confirm IP binding is correct
Check firewall rules
Check node is fully synced

High latency

Check CPU, memory, disk I/O, and network utilization
Review RPC request volume and rate limits
Confirm the node remains fully synced
Scale across additional RPC nodes if required

Node stuck catching up

Check peers
Restart node
Verify time sync (NTP)

RPC Node Setup Complete

Your RPC node is operational and serving JSON-RPC / WebSocket traffic for the Shardeum EVM mainnet.

Use this setup for:

dApp backend integrations
Indexing services
Developer environments
High-availability RPC infrastructure

Run an RPC Node

On this page