Run a Full Node

A full node verifies blocks, relays network data, and can optionally serve RPC endpoints for developers, dApps, and testing environments. Full nodes do not participate in consensus and do not require staking or validator setup.

Ensure you are using the correct testnet configuration, including chain ID, genesis file, and peers. Incorrect values may prevent your node from syncing.

1. System Requirements

Recommended:

OS: Ubuntu 22.04 LTS
CPU: 4 cores
RAM: 8–16 GB
Storage: 500 GB+ NVMe SSD
Network: 100 Mbps
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
```bash
 
## 2. Install Shardeum Node Binary
 
Clone the Shardeum EVM repository:
 
```bash
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>
```bash
 
Replace `<supported-testnet-release>` with the release tag currently supported for Shardeum testnet.
 
Build and install the binary (may take several minutes):
 
```bash
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

Choose a node ID and moniker (ASCII only):

NODE_ID="node0"
MONIKER="shardeum-testnet-fullnode"
 
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
 
```bash
ls -lh $HOME/.testnet/$NODE_ID/config/genesis.json
jq -r '.chain_id' $HOME/.testnet/$NODE_ID/config/genesis.json

6. Configure Pruning

Full nodes can use pruning to manage storage usage.

Default configuration is:

pruning = "default"

If you prefer custom pruning:

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

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

pruning = "nothing"

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

Note: Initial sync may take time depending on your hardware and network conditions.

Monitor:

shardeumd status | jq '.SyncInfo'

Or tail the log:

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

Wait until fully synced.

Ensure your node is connected to peers. Without peers, the node will not sync. Refer to the repository or official documentation for the latest seeds or peer configuration.

8. Optional: Run as systemd Service

Check the installed Shardeum binary path:

command -v shardeumd

Create the service file:

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

Example:

[Unit]
Description=Shardeum Testnet Full Node
After=network-online.target
 
[Service]
User=root
ExecStart=<shardeumd-binary-path> start \
  --home /root/.testnet/<node-id> \
  --chain-id shardeum-testnet \
  --p2p.seeds "<same-testnet-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, <node-id> with the node ID configured earlier, and use the same testnet seed list specified in the startup instructions above.

Reload systemd, then enable and start the service:

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

9. Optional: Enable JSON-RPC

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

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

If the node is already running as a systemd service, restart it for the changes to take effect:

sudo systemctl restart shardeumd-testnet

10. Firewall Configuration

sudo ufw allow 27656/tcp   # P2P
sudo ufw allow 8545/tcp    # JSON-RPC (optional)
sudo ufw allow 8546/tcp    # WebSocket (optional)
sudo ufw enable

For public exposure, restrict JSON-RPC access to trusted IPs or use a reverse proxy.

11. Node Management Commands

Sync Status

shardeumd status | jq '.SyncInfo'

Node ID

shardeumd comet show-node-id

Check Peers

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

Logs

journalctl -u shardeumd-testnet -f

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

Stop Node

sudo systemctl stop shardeumd-testnet

If you started the node manually instead:

pkill shardeumd

12. Troubleshooting

Node Won’t Sync

Check peer connections
Verify testnet chain ID and genesis file
Ensure correct network configuration
Verify time sync (NTP): timedatectl status
Check port 27656 is open

Out of Disk Space

Enable pruning in app.toml
Increase disk size
Avoid archive mode unless required

JSON-RPC Not Responding

Check firewall rules
Verify JSON-RPC settings
Confirm node is fully synced
Restart node/service

13. Important Notes

Testnet Chain ID: shardeum-testnet
EVM Chain ID: 8119
Network: Shardeum EVM Testnet (configuration may 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.
Backups: Back up node_key.json securely.
Testnet configuration may change between testnet phases.

Full Node Setup Complete

Your Shardeum testnet full node is now configured and syncing with the network. Once fully synced, you can use it for network testing, infrastructure experiments, and optionally serving RPC interfaces.

Run a Full Node

On this page