Run an RPC Node

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

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

Clone the Shardeum EVM repository:

git clone https://github.com/shardeum/shardeum-evm.git
cd shardeum-evm

Fetch the latest release tags and check out the currently supported testnet release:

git fetch --tags
git checkout <supported-testnet-release>

Replace <supported-testnet-release> with the release tag currently supported for Shardeum testnet.

Build and install the binary (may take several minutes):

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=testnet

4. Initialize the Node

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

5. Copy Genesis File

cp config/environments/testnet-genesis.json \
  $HOME/.testnet/$NODE_ID/config/genesis.json
jq -r '.chain_id' $HOME/.testnet/$NODE_ID/config/genesis.json

6. Configure Pruning

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

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

Find the RPC section and set:

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

If you require complete historical state, run an Archive Node instead using:

pruning = "nothing"

7. Enable JSON-RPC

Edit $HOME/.testnet/$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"

8. Start and Sync the Node

Start:

shardeumd start \
  --home $HOME/.testnet/$NODE_ID \
  --chain-id shardeum-testnet \
  --p2p.seeds "[email protected]:27656,[email protected]:27656,[email protected]:27656" \
  --p2p.laddr tcp://0.0.0.0:27656 \
  --rpc.laddr tcp://127.0.0.1:26657 \
  > $HOME/.testnet/$NODE_ID/node.log &

Monitor:

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

Wait until fully synced.

9. Optional: Enable gRPC and 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 or testing flow.

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

11. systemd Service (Recommended)

Check the installed Shardeum binary path:

command -v shardeumd

Create the service file:

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

Example content:

[Unit]
Description=Shardeum Testnet RPC Node
After=network-online.target
 
[Service]
User=root
ExecStart=<shardeumd-binary-path> start \
  --home /root/.testnet/rpcnode \
  --chain-id shardeum-testnet \
  --p2p.seeds "[email protected]:27656,[email protected]:27656,[email protected]: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 and use the same testnet seed list specified above.

If the node is already running from the manual startup command, stop that process before starting the systemd service.

Reload systemd, then enable and start the service:

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

12. Scaling RPC Nodes (Optional)

For higher traffic or team-based testing:

• 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 internal infrastructure 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-testnet -f

Query JSON-RPC:

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

14. Troubleshooting

RPC endpoint not responding

• Confirm JSON-RPC is enabled in app.toml
• Confirm IP binding is correct
• Check firewall rules
• Check that the node is fully synced

High latency

• Check CPU, memory, disk I/O, and network utilization
• Review RPC request volume and rate limits
• Confirm that the node remains fully synced
• Add additional RPC nodes behind a proxy if required

Node stuck catching up

• Check peers
• Restart node
• Verify time sync (NTP)
• Confirm you are using the correct testnet chain ID and genesis file

15. Important Notes

• Testnet Chain ID: shardeum-testnet
• EVM Chain ID: 8119
• Network: Shardeum EVM Testnet (subject to change)
• Genesis File: Use the testnet genesis file included with the supported release.
• Archive Mode: Use pruning = "nothing" only when complete historical state is required.
• Testnet configuration may change between testnet phases.

RPC Node Setup Complete

Your RPC node is operational and ready to serve JSON-RPC and WebSocket traffic for the Shardeum testnet.

Use this setup for:

• Testing environments
• dApp and wallet integrations
• Indexers and infra services
• Exchange and backend validation flows