Run an RPC Node

An RPC node provides JSON-RPC and WebSocket endpoints for developers, dApps, indexers, infrastructure providers, and partners. RPC nodes do not validate blocks and do not require staking.

RPC nodes should not expose consensus ports publicly and must follow strict security practices.

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
make install

Verify:

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. Start and Sync the Node

Start:

shardeumd start \
  --home $HOME/.mainnet/$NODE_ID \
  --chain-id shardeum_8118-1 \
  --p2p.seeds [email protected]:27656,[email protected]:27656 \
  --p2p.laddr tcp://0.0.0.0:27656 \
  --rpc.laddr tcp://127.0.0.1:26657 \
  --pruning nothing \
  > $HOME/.mainnet/$NODE_ID/node.log &

Monitor:

shardeumd status | jq '.SyncInfo'
tail -f $HOME/.mainnet/$NODE_ID/node.log

Wait until fully synced.

7. Enable JSON-RPC

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

Find the RPC section and set:

json-rpc.enable = true
json-rpc.address = "0.0.0.0:8545"
json-rpc.ws-address = "0.0.0.0:8546"

Restart your node if using systemd.

8. Optional: Enable gRPC & REST Endpoints

In app.toml:

grpc.enable = true
grpc.address = "0.0.0.0:9090"
 
api.enable = true
api.address = "0.0.0.0:1317"

Enable these only if required by your infrastructure.

9. Firewall Configuration

Expose only RPC/WebSocket ports:

sudo ufw allow 8545/tcp   # JSON-RPC
sudo ufw allow 8546/tcp   # WebSocket
sudo ufw allow 9090/tcp   # gRPC (optional)
sudo ufw allow 1317/tcp   # REST API (optional)
sudo ufw allow 27656/tcp  # P2P
sudo ufw enable

Do not expose port 26657 (Tendermint RPC) to the public. Restrict sensitive endpoints to localhost or trusted IPs.

10. systemd Service (Recommended)

Create service:

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

Example:

[Unit]
Description=Shardeum RPC Node
After=network-online.target
 
[Service]
User=root
ExecStart=/usr/local/bin/shardeumd start --home /root/.mainnet/rpcnode
Restart=on-failure
LimitNOFILE=65535
 
[Install]
WantedBy=multi-user.target

Enable:

sudo systemctl enable shardeumd-rpc
sudo systemctl start shardeumd-rpc

11. Pruning (Recommended for RPC Nodes)

RPC nodes often use custom pruning.

Edit app.toml:

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

Restart the node.

12. Scaling RPC Nodes (Optional)

For high-traffic dApps:

Use load balancers (Nginx, HAProxy, AWS ELB)
Run multiple RPC nodes behind a reverse proxy
Rate-limit requests to avoid overload
Separate "public RPC" from "private infra RPC"
Run indexing services in parallel (The Graph, SubQuery, etc.)

13. Useful Commands

Check sync:

shardeumd status | 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://<your-ip>: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

Reduce pruning window
Increase hardware resources
Add more RPC nodes behind a proxy

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