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 verify chain data but do not participate in consensus or 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

The expected chain ID is:

shardeum-testnet

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

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

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

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 &

Verify sync status:

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

Or tail the log:

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

Wait until fully synced.

9. Optional: Enable gRPC and REST Endpoints

Edit:

$HOME/.testnet/$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 or testing flow.

Restart the node after making changes.

If using systemd:

sudo systemctl restart shardeumd-rpc-testnet

10. Firewall Configuration

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

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

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:

The example below assumes the node was installed and initialized as the root user. If you used another system user, replace User=root and /root/.testnet/rpcnode with the corresponding user and node-home path.

[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.

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 --home $HOME/.testnet/$NODE_ID | 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