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
git fetch --tags
git checkout v1.0.2
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.

Find the RPC section and set:

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

8. Start and Sync the Node

Start:

shardeumd start \
  --home $HOME/.mainnet/$NODE_ID \
  --chain-id shardeum_8118-1 \
  --p2p.seeds ... \
  --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 | jq '.SyncInfo'
tail -f $HOME/.mainnet/$NODE_ID/node.log

Wait until fully synced.

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 the ports required for your deployment:

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)

Check the installed Shardeum binary path:

command -v shardeumd

Use the returned path for ExecStart.

Create the service file:

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

Example:

[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 <same-seed-list-used-above> \
  --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, and use the same seed list specified in the startup instructions above.

Also, if the node is already running from the manual startup command above, stop that process before starting it as a systemd service.

Enable:

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

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 dedicated indexing services in parallel where required.

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://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