Seed Node Deployment

This guide covers deploying a seed node for any Monolythium network (Testnet or Mainnet). Seed nodes help new nodes discover peers and are essential network infrastructure.

Prerequisites

Hardware: 4+ vCPU, 8GB+ RAM, 500GB+ SSD
OS: Ubuntu 24.04 LTS or Debian 12
Network: Static public IP, open firewall for P2P port
Software: Go 1.24+ (for building from source)

Network Selection

Choose your target network. All configuration is fetched from the canonical registry:

Network	Chain ID	Status	Registry URL
Testnet	mono_6940-1	Active	peers.json
Mainnet	mono_6941-1	Planned	peers.json

Docker Deployment Removed

Docker-based seed node deployment is no longer supported. Use the systemd-based setup below or Monarch CLI for streamlined deployment.

Full Setup (Systemd)

1. Install Binary

# Clone repository
git clone https://github.com/monolythium/mono-chain.git
cd mono-chain

# Checkout release
git checkout <release-tag>

# Build and install
make install
sudo mv $(go env GOPATH)/bin/monod /usr/local/bin/

# Verify
monod version

2. Fetch Network Configuration

# Set your network
NETWORK=testnet

# Fetch all configuration from registry
REGISTRY_URL="https://raw.githubusercontent.com/mono-labs-org/mono-core-peers/prod/networks/${NETWORK}/peers.json"
GENESIS_URL=$(curl -s $REGISTRY_URL | jq -r '.genesis_url')
GENESIS_SHA=$(curl -s $REGISTRY_URL | jq -r '.genesis_sha256')
CHAIN_ID=$(curl -s $REGISTRY_URL | jq -r '.chain_id')
SEEDS=$(curl -s $REGISTRY_URL | jq -r '.seeds | join(",")')
PERSISTENT_PEERS=$(curl -s $REGISTRY_URL | jq -r '.persistent_peers | join(",")')
P2P_PORT=$(curl -s $REGISTRY_URL | jq -r '.port_scheme.seeds.p2p')
RPC_PORT=$(curl -s $REGISTRY_URL | jq -r '.port_scheme.seeds.rpc')

# Display configuration
echo "=== Network Configuration ==="
echo "Network: $NETWORK"
echo "Chain ID: $CHAIN_ID"
echo "P2P Port: $P2P_PORT"
echo "RPC Port: $RPC_PORT"
echo "Persistent Peers: $PERSISTENT_PEERS"

3. Initialize Node

# Create monod user
sudo useradd -r -s /sbin/nologin -m -d /var/lib/monod monod

# Initialize node
sudo -u monod monod init "seed-$(hostname)" --network-id $CHAIN_ID --home /var/lib/monod

# Download genesis
sudo curl -sL $GENESIS_URL -o /var/lib/monod/config/genesis.json
sudo chown monod:monod /var/lib/monod/config/genesis.json

# Verify genesis SHA256
echo "$GENESIS_SHA  /var/lib/monod/config/genesis.json" | sha256sum -c -

4. Configure Seed Mode

Edit /var/lib/monod/config/config.toml:

[p2p]
# Enable seed mode - node will crawl network and respond to peer requests
seed_mode = true

# Listen address for P2P connections
laddr = "tcp://0.0.0.0:26656"

# Advertise your public IP
external_address = "YOUR_PUBLIC_IP:26656"

# Persistent peers to connect to (validators or other seeds)
# Get this from the network registry
persistent_peers = "nodeid@host:port,..."

# Increase peer limits for seed nodes
max_num_inbound_peers = 100
max_num_outbound_peers = 50

Apply peers from registry:

# Use monarch (recommended) or manual sed
monarch repair \
  --home /var/lib/monod \
  --persistent-peers "$PERSISTENT_PEERS"

# Or manually (be careful with sed!):
# Only replace exact key matches to avoid corrupting other config values
sudo -u monod sed -i "s|^persistent_peers = .*|persistent_peers = \"$PERSISTENT_PEERS\"|" /var/lib/monod/config/config.toml
sudo -u monod sed -i "s|^seed_mode = .*|seed_mode = true|" /var/lib/monod/config/config.toml

5. Create Systemd Service

cat <<EOF | sudo tee /etc/systemd/system/${NETWORK}-seed.service
[Unit]
Description=Monolythium Seed Node (${NETWORK})
After=network-online.target
Wants=network-online.target

[Service]
User=monod
Group=monod
Type=simple
ExecStart=/usr/local/bin/monod start --home /var/lib/monod
Restart=always
RestartSec=3
LimitNOFILE=65535

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable ${NETWORK}-seed

6. Configure Firewall

# Required: P2P port (default 26656)
sudo ufw allow 26656/tcp comment "Monolythium P2P"

# Optional: RPC port (only if you need remote access)
# sudo ufw allow 26657/tcp comment "Monolythium RPC"

sudo ufw reload

Network-specific ports:

Check the registry for custom port schemes:

curl -s $REGISTRY_URL | jq '.port_scheme'

Some networks (like Testnet) use non-standard ports for multi-validator setups. If connecting to validators on custom ports, ensure those ports are allowed.

7. Start and Verify

# Start the service
sudo systemctl start ${NETWORK}-seed

# Check status
sudo systemctl status ${NETWORK}-seed

# View logs
sudo journalctl -u ${NETWORK}-seed -f

# Verify sync status
curl -s localhost:26657/status | jq '.result.sync_info'

# Check peer count
curl -s localhost:26657/net_info | jq '.result.n_peers'

Seed Mode Configuration

Seeds have specific configuration requirements:

Setting	Value	Description
`seed_mode`	`true`	Enable seed mode behavior
`max_num_inbound_peers`	`100+`	Accept many incoming connections
`max_num_outbound_peers`	`50+`	Actively discover peers
`addr_book_strict`	`true`	Only allow routable addresses
`pex`	`true`	Enable peer exchange

Pruning Policy

Seeds don't need full block history. Use aggressive pruning:

In app.toml:

[pruning]
pruning = "custom"
pruning-keep-recent = "100"
pruning-keep-every = "0"
pruning-interval = "10"

This keeps only the last 100 blocks, significantly reducing disk usage.

Common Issues

No Peers Found

Verify firewall allows P2P port:
```
sudo ufw status | grep 26656
```

Check persistent_peers format:

grep persistent_peers /var/lib/monod/config/config.toml
# Should be: nodeid@host:port

Verify validators are reachable:

# From the registry
PEERS=$(curl -s $REGISTRY_URL | jq -r '.persistent_peers[]')
for peer in $PEERS; do
  HOST=$(echo $peer | cut -d@ -f2 | cut -d: -f1)
  PORT=$(echo $peer | cut -d: -f2)
  echo "Testing $HOST:$PORT"
  nc -zv $HOST $PORT 2>&1
done

Config Corruption

If config.toml was corrupted by manual editing, regenerate it:

sudo systemctl stop ${NETWORK}-seed
sudo -u monod monod init "seed-$(hostname)" --network-id $CHAIN_ID --home /var/lib/monod --overwrite
# Re-apply genesis and config

AppHash Mismatch

If the seed reports an AppHash mismatch, reset state:

sudo systemctl stop ${NETWORK}-seed
sudo -u monod monod tendermint unsafe-reset-all --home /var/lib/monod --keep-addr-book
sudo systemctl start ${NETWORK}-seed

Register Your Seed

Once your seed is stable and synced, submit it to the network registry:

Get your node ID:

monod tendermint show-node-id --home /var/lib/monod

Submit a PR to mono-core-peers adding your seed to networks/<network>/peers.json:
```
{
  "seeds": [
    "your_node_id@your_ip:26656"
  ]
}
```

Prerequisites​

Network Selection​

Full Setup (Systemd)​

1. Install Binary​

2. Fetch Network Configuration​

3. Initialize Node​

4. Configure Seed Mode​

5. Create Systemd Service​

6. Configure Firewall​

7. Start and Verify​

Seed Mode Configuration​

Pruning Policy​

Common Issues​

No Peers Found​

Config Corruption​

AppHash Mismatch​

Register Your Seed​

See Also​