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.

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

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

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

Verify the genesis file:

ls -lh $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

Full nodes can use pruning to manage storage usage.

Edit:

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

The 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 --home $HOME/.testnet/$NODE_ID | jq '.SyncInfo'

Or tail the log:

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

Wait until fully synced.

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

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/<node-id> with the corresponding user and node-home path.

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 "[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 <node-id> with the node ID configured earlier.

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

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

Under the existing [json-rpc] section, set:

enable = true
address = "0.0.0.0:8545"
ws-address = "0.0.0.0:8546"

Restart the node after saving the changes.

If using systemd:

sudo systemctl restart shardeumd-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

If this node is intentionally serving public JSON-RPC, also allow:

sudo ufw allow 8545/tcp   # JSON-RPC
sudo ufw allow 8546/tcp   # WebSocket

Then enable and check the firewall:

sudo ufw enable
sudo ufw status

11. Node Management Commands

Sync Status

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

Node ID

shardeumd comet show-node-id --home $HOME/.testnet/$NODE_ID

Check Peers

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

Logs

journalctl -u shardeumd-testnet -f

Or

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.