Skip to main content

Seeds and Peers

This guide explains how to configure seed nodes and persistent peers for your Monolythium node.

!!! info "Understanding Peer Roles" For a complete explanation of peer roles (seeds, bootstrap nodes, validators, sentries), see Peer Roles. This page covers configuration; that page explains the concepts.

Understanding Seeds vs Peers​

TypePurposeBehavior
SeedsBootstrap peer discoveryNode connects, gets peer list, then disconnects
Persistent PeersMaintained connectionsNode keeps connection open continuously
Bootstrap PeersGenesis sync sourceArchive nodes used for deterministic sync

Seeds are used for initial peer discovery. Once your node has discovered peers, it maintains its own address book and no longer needs seeds.

!!! warning "Seeds Cannot Sync Your Node" Seed nodes disconnect immediately after exchanging addresses. They do not serve blocks. If your node is stuck at height 0 with only seeds configured, you need bootstrap or persistent peers. See Peer Roles for details.

Official Seed Nodes​

Monolythium provides DNS-based seed nodes that resolve to current seed infrastructure:

Sprintnet​

seed1.sprintnet.mononodes.xyz:26656
seed2.sprintnet.mononodes.xyz:26656
seed3.sprintnet.mononodes.xyz:26656

Testnet​

seed1.testnet.mononodes.xyz:26656
seed2.testnet.mononodes.xyz:26656
seed3.testnet.mononodes.xyz:26656

Mainnet​

seed1.mainnet.mononodes.xyz:26656
seed2.mainnet.mononodes.xyz:26656
seed3.mainnet.mononodes.xyz:26656

Configuring Seeds​

Edit ~/.monod/config/config.toml:

[p2p]
# Comma-separated list of seed nodes
seeds = "seed1.sprintnet.mononodes.xyz:26656,seed2.sprintnet.mononodes.xyz:26656,seed3.sprintnet.mononodes.xyz:26656"

Configuring Persistent Peers​

For nodes that should maintain constant connections (e.g., sentry nodes to validators):

[p2p]
# Format: node_id@host:port
persistent_peers = "abc123...@peer1.example.com:26656,def456...@peer2.example.com:26656"

!!! tip "Finding Node IDs" Get a node's ID with: monod tendermint show-node-id

Peer Registry​

The official peer registry is maintained at:

https://github.com/monolythium/networks/tree/main/<network>/peers.json

This file contains verified peer information submitted by the community.

Submitting Your Peer​

To add your node to the peer registry:

  1. Ensure your node is stable and publicly accessible
  2. Get your node ID: monod tendermint show-node-id
  3. Submit a PR to the networks repository with your peer info

P2P Configuration Options​

Key settings in config.toml:

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

# Address to advertise to peers (if behind NAT)
external_address = "your-public-ip:26656"

# Maximum number of inbound peers
max_num_inbound_peers = 40

# Maximum number of outbound peers
max_num_outbound_peers = 10

# Seed mode (only for seed node operators)
seed_mode = false

# Unconditional peer IDs (always connect regardless of limits)
unconditional_peer_ids = ""

# Private peer IDs (never gossip to other peers)
private_peer_ids = ""

Sentry Node Architecture​

For validators, the recommended architecture uses sentry nodes:

                    Internet
                        |
            +-----------+-----------+
            |           |           |
         Sentry1     Sentry2     Sentry3
            |           |           |
            +-----------+-----------+
                        |
                    Validator
                   (private)

Validator Configuration​

[p2p]
# Only connect to sentries
persistent_peers = "sentry1_id@sentry1:26656,sentry2_id@sentry2:26656"

# Do not expose to public
pex = false

# Keep sentry IDs private
private_peer_ids = "sentry1_id,sentry2_id,sentry3_id"

Sentry Configuration​

[p2p]
# Connect to seeds for peer discovery
seeds = "seed1.mainnet.mononodes.xyz:26656,..."

# Always maintain connection to validator
persistent_peers = "validator_id@validator-private-ip:26656"
unconditional_peer_ids = "validator_id"

# Hide validator from other peers
private_peer_ids = "validator_id"

DNS Resolution​

Seed hostnames use DNS for service discovery:

  • A records point to current seed node IPs
  • Updates are transparent - no node config changes needed
  • Redundancy through multiple seed endpoints

This allows infrastructure changes without requiring node operators to update configuration.

Troubleshooting​

No Peers Found​

  1. Verify seed configuration syntax
  2. Check DNS resolution: dig seed1.sprintnet.mononodes.xyz
  3. Ensure port 26656 allows outbound connections
  4. Check for firewall blocking

Peer Connection Refused​

  1. Verify the peer is online and accessible
  2. Check you're using the correct node ID
  3. Ensure the peer's port 26656 is open

Address Book Issues​

Reset the address book if corrupted:

# Stop node first
sudo systemctl stop monod

# Remove address book
rm ~/.monod/config/addrbook.json

# Restart
sudo systemctl start monod

External Address Not Detected​

If behind NAT, manually set your external address:

[p2p]
external_address = "your-public-ip:26656"

Best Practices​

  1. Use DNS seeds - They're maintained and updated automatically
  2. Add persistent peers for critical connections (validator-sentry)
  3. Set external_address if behind NAT or load balancer
  4. Use private_peer_ids to hide sensitive connections
  5. Monitor peer count - Healthy nodes typically have 20-50 peers