Useful Commands for Story Aeneid Testnet

This page provides a comprehensive collection of useful commands for managing your Story node on the Aeneid testnet. These commands are organized by category for easy reference.

Prerequisites

Before using validator commands, ensure you have:

Environment Setup: Create a .env file in the same directory as your story binary:

# ~/.env
PRIVATE_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

IP Tokens: Ensure your account has sufficient IP tokens for operations
Validator Key: Have a validator key file (priv_validator_key.json) ready

warning

Never add the 0x prefix to your private key in the .env file. Keep your private key secure and never share it.

Validator Operations

Validator Key Export

Export and view your validator key information:

# Basic validator key export
./story validator export

# Export with EVM key to .env file
./story validator export --export-evm-key --evm-key-path .env

# Export to custom location
./story validator export --export-evm-key --evm-key-path /path/to/backup/

# Use custom key file
./story validator export --keyfile /path/to/priv_validator_key.json

Expected Output:

Compressed Public Key (hex): xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Compressed Public Key (base64): xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Uncompressed Public Key (hex): xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
EVM Address: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Validator Address: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Delegator Address: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Validator Creation

Create a new validator on the network:

# Basic validator creation (unlocked tokens)
./story validator create \
  --stake 1024000000000000000000 \
  --moniker "My Validator" \
  --rpc https://rpc-aeneid-story.blocknth.com \
  --chain-id 1315 \
  --commission-rate 1000

# Validator creation with locked tokens
./story validator create \
  --stake 1024000000000000000000 \
  --moniker "My Validator" \
  --rpc https://rpc-aeneid-story.blocknth.com \
  --chain-id 1315 \
  --commission-rate 1000 \
  --unlocked=false

# Advanced validator creation
./story validator create \
  --stake 2048000000000000000000 \
  --moniker "My Validator" \
  --rpc https://rpc-aeneid-story.blocknth.com \
  --chain-id 1315 \
  --commission-rate 500 \
  --max-commission-rate 2000 \
  --max-commission-change-rate 100 \
  --explorer https://aeneid.storyscan.io

Available Flags:

--stake: Amount to self-delegate in wei (default: 1024000000000000000000)
--moniker: Validator name visible on network
--chain-id: Chain ID (default: 1315 for Aeneid testnet)
--commission-rate: Commission rate in bips (1% = 100 bips, default: 1000)
--max-commission-rate: Maximum commission rate in bips (default: 2000)
--max-commission-change-rate: Maximum commission change rate in bips (default: 1000)
--unlocked: Use unlocked tokens (default: true)

Validator Staking

Stake additional tokens to your validator:

# Basic staking
./story validator stake \
  --stake 512000000000000000000 \
  --rpc https://rpc-aeneid-story.blocknth.com \
  --chain-id 1315

# Staking with delegation ID
./story validator stake \
  --stake 1024000000000000000000 \
  --delegation-id 1 \
  --rpc https://rpc-aeneid-story.blocknth.com \
  --chain-id 1315

Validator Unstaking

Unstake tokens from your validator:

# Basic unstaking
./story validator unstake \
  --unstake 256000000000000000000 \
  --rpc https://rpc-aeneid-story.blocknth.com \
  --chain-id 1315

# Unstaking with delegation ID
./story validator unstake \
  --unstake 512000000000000000000 \
  --delegation-id 1 \
  --rpc https://rpc-aeneid-story.blocknth.com \
  --chain-id 1315

Stake-on-behalf Operations

Allow others to stake on your behalf:

# Stake on behalf of delegator
./story validator stake-on-behalf \
  --delegator-address xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \
  --validator-pubkey xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \
  --stake 1024000000000000000000 \
  --rpc https://rpc-aeneid-story.blocknth.com \
  --chain-id 1315

Unstake-on-behalf Operations

Allow others to unstake on your behalf:

# Unstake on behalf of delegator
./story validator unstake-on-behalf \
  --delegator-address xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \
  --validator-pubkey xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \
  --unstake 512000000000000000000 \
  --rpc https://rpc-aeneid-story.blocknth.com \
  --chain-id 1315

Validator Unjail

Unjail your validator if it has been jailed:

# Basic unjail
./story validator unjail \
  --rpc https://rpc-aeneid-story.blocknth.com \
  --chain-id 1315

# Unjail on behalf of delegator
./story validator unjail-on-behalf \
  --delegator-address xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \
  --validator-pubkey xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \
  --rpc https://rpc-aeneid-story.blocknth.com \
  --chain-id 1315

Validator Rollback

Rollback validator to a previous state:

# Rollback validator
./story validator rollback \
  --rpc https://rpc-aeneid-story.blocknth.com \
  --chain-id 1315

Validator Redelegation

Redelegate tokens between validators:

# Basic redelegation
./story validator redelegate \
  --validator-src-pubkey xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \
  --validator-dst-pubkey xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \
  --redelegate 1024000000000000000000 \
  --rpc https://rpc-aeneid-story.blocknth.com \
  --chain-id 1315

# Redelegate on behalf of delegator
./story validator redelegate-on-behalf \
  --delegator-address xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \
  --validator-src-pubkey xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \
  --validator-dst-pubkey xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \
  --redelegate 1024000000000000000000 \
  --rpc https://rpc-aeneid-story.blocknth.com \
  --chain-id 1315

Operator Management

Manage operators for your delegator account:

# Set operator
./story validator set-operator \
  --operator xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \
  --rpc https://rpc-aeneid-story.blocknth.com \
  --chain-id 1315 \
  --story-api http://localhost:1317

# Remove operator
./story validator unset-operator \
  --operator xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \
  --rpc https://rpc-aeneid-story.blocknth.com \
  --chain-id 1315 \
  --story-api http://localhost:1317

Address Management

Manage reward and withdrawal addresses:

# Set rewards address
./story validator set-rewards-address \
  --rewards-address xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \
  --story-api http://localhost:1317

# Set withdrawal address
./story validator set-withdrawal-address \
  --withdrawal-address xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \
  --story-api http://localhost:1317

Commission Management

Update validator commission rates:

# Update commission rate
./story validator update-validator-commission \
  --commission-rate 5000 \
  --rpc https://rpc-aeneid-story.blocknth.com \
  --chain-id 1315

System Management

Service Control

# Check service status
systemctl status story-geth
systemctl status story

# Start services
systemctl start story-geth
systemctl start story

# Stop services
systemctl stop story-geth
systemctl stop story

# Restart services
systemctl restart story-geth
systemctl restart story

# Enable services to start on boot
systemctl enable story-geth
systemctl enable story

# View real-time logs
journalctl -u story-geth.service -f -o cat
journalctl -u story.service -f -o cat

# View recent logs (last hour)
journalctl -u story-geth.service --since "1 hour ago"
journalctl -u story.service --since "1 hour ago"

# View error logs only
journalctl -u story-geth.service -p err
journalctl -u story.service -p err

Node Verification

Sync Status Checks

EC_PORT=8545
CL_PORT=26657
# Check execution client sync status
curl -X POST -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","method":"eth_syncing","params":[],"id":1}' \
  http://localhost:${EC_PORT} | jq .

# Check latest block number
curl -X POST -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' \
  http://localhost:${EC_PORT} | jq .

# Check consensus client sync status
curl -s http://localhost:${CL_PORT}/status | jq .

Network Information

CL_PORT=26657
# Get network peers
curl http://localhost:${CL_PORT}/net_info | jq '.result.peers'

# Get validator set
curl http://localhost:${CL_PORT}/validators | jq '.result.validators'

# Check consensus state
curl http://localhost:${CL_PORT}/consensus_state

Configuration Management

Update Configuration Files

# Update persistent peers
peers=$(curl -sS https://rpc-aeneid-story.blocknth.com/net_info | \
  jq -r '.result.peers[] | "\(.node_info.id)@\(.remote_ip):\(.node_info.listen_addr)"' | \
  awk -F ':' '{print $1":"$(NF)}' | paste -sd, -)

sed -i -e "s|^persistent_peers *=.*|persistent_peers = \"$peers\"|" \
  /data/story/consensus/data/config/config.toml

# Enable Prometheus monitoring
sed -i.bak -e 's|^prometheus *=.*|prometheus = true|' \
  /data/story/consensus/data/config/config.toml

Troubleshooting

Common Issues

# Check if ports are in use
sudo lsof -i :8545
sudo lsof -i :26657
sudo lsof -i :1317

# Check firewall status
sudo ufw status

# Check disk space for logs
du -sh /var/log/journal/

# Clear old logs (if disk space is low)
journalctl --vacuum-time=7d

# Check JWT file permissions
ls -la /data/story/execution/.jwt.hex

Performance Monitoring

# Monitor resource usage
iotop
iostat -x 1

# Check network bandwidth
iftop

# Monitor system load
watch -n 1 'uptime; echo; free -h; echo; df -h'

Network Security

# Check open ports
nmap localhost

# Configure firewall rules
sudo ufw allow 26656/tcp
sudo ufw allow 26657/tcp
sudo ufw allow 1317/tcp
sudo ufw deny 8545/tcp  # Restrict RPC access

Maintenance

Regular Maintenance Tasks

# Update system packages
sudo apt update && sudo apt upgrade -y

# Clean up old snapshots
find /data/story/snapshot -name "*.tar.lz4" -mtime +7 -delete

# Rotate logs
sudo logrotate -f /etc/logrotate.conf

# Check for disk space
df -h | awk '$5 > "80%" {print $0}'

Quick Reference

Command	Description
`systemctl status story-geth`	Check execution client status
`systemctl status story`	Check consensus client status
`journalctl -u story-geth -f`	Follow execution client logs
`journalctl -u story -f`	Follow consensus client logs
`curl localhost:26657/status`	Check node sync status
`curl localhost:8545`	Test EVM RPC endpoint
`curl localhost:1317`	Test Cosmos REST API
`./story validator export`	Export validator key information
`./story validator create`	Create new validator
`./story validator stake`	Stake tokens to validator
`./story validator unstake`	Unstake tokens from validator

Validator Migration

When migrating a validator to a new machine:

# Step 1: Stop the original validator node
sudo systemctl stop story.service

# Step 2: Disable the Story service to prevent automatic restarts
sudo systemctl disable story.service

# Step 3: Delete the Story service file to prevent it from starting on reboot
sudo rm /etc/systemd/system/story.service

# Step 4: Back up the validator key file securely
cp ~/.story/story/config/priv_validator_key.json /backup/priv_validator_key_$(date +%Y%m%d_%H%M%S).json

# Step 5: Remove the validator key file from the current server
rm ~/.story/story/config/priv_validator_key.json

tip

Always run health checks regularly and keep your system updated. Monitor logs for any unusual activity or errors.

warning

Keep your validator private key secure and never share it. Always backup important configuration files before making changes. Never run two instances of the same validator simultaneously to avoid double-signing penalties.

info

For more detailed information about Story network operations, refer to the official Story Foundation documentation.

Prerequisites​

Validator Operations​

Validator Key Export​

Validator Creation​

Validator Staking​

Validator Unstaking​

Stake-on-behalf Operations​

Unstake-on-behalf Operations​

Validator Unjail​

Validator Rollback​

Validator Redelegation​

Operator Management​

Address Management​

Commission Management​

System Management​

Service Control​

Node Verification​

Sync Status Checks​

Network Information​

Configuration Management​

Update Configuration Files​

Troubleshooting​

Common Issues​

Performance Monitoring​

Network Security​

Maintenance​

Regular Maintenance Tasks​

Quick Reference​

Validator Migration​