Peer Roles in Monolythium

Monolythium uses explicit peer roles that go beyond standard Cosmos SDK terminology. This document defines each role precisely to prevent operator confusion, configuration drift, and sync failures.

Overview

Different node types serve different purposes. Conflating them causes problems:

• Using seed nodes for blocksync fails silently
• Using pruned nodes for genesis sync causes replay divergence
• Exposing validators to public networks creates attack surface

This guide explains what each role does and when to use it.

---

1. Seed Nodes

Seed nodes exist for peer discovery only. They do not serve blocks.

What seed_mode=true Does

When a CometBFT node runs with seed_mode=true:

1. It accepts incoming connections
2. It exchanges address book entries with the connecting peer
3. It disconnects immediately after the exchange
4. It never sends blocks, headers, or state data

What Seed Nodes Cannot Do

Capability	Seed Node
Exchange peer addresses	Yes
Serve blocks for blocksync	No
Serve state for statesync	No
Maintain persistent connections	No
Help a node catch up	No

When to Use Seed Nodes

• Initial peer discovery when joining a network
• Finding peers when your address book is empty
• DNS-based seed infrastructure for public networks

When NOT to Use Seed Nodes

• Genesis sync: Seeds disconnect before sending any blocks
• Catching up: Seeds cannot help you sync
• Persistent connections: Seeds reject long-lived connections

Common Mistake

Operators often configure seeds expecting them to help with blocksync. This fails silently. The node connects, receives addresses, disconnects, and then must find actual peers to sync from.

If your node is stuck at height 0 with seeds configured, this is likely the cause.

---

2. Bootstrap Nodes

Bootstrap nodes are a Monolythium-specific concept. They do not exist in standard Cosmos SDK tooling.

Why Bootstrap Nodes Exist

Standard Cosmos SDK relies on PEX (peer exchange) to find sync sources. This creates problems:

• PEX may return pruned nodes that cannot serve early blocks
• PEX may return nodes with different genesis or app versions
• Random peer selection introduces replay nondeterminism
• Operators cannot guarantee deterministic sync paths

Bootstrap nodes solve this by providing known-good archive peers for initial sync.

Bootstrap Node Requirements

Setting	Value	Reason
seed_mode	false	Must maintain connections and serve blocks
pruning	nothing	Must have all blocks from height 1
earliest_block_height	1	Verified full archive
Connection type	persistent_peers	Ensures stable sync source

How Bootstrap Sync Works

1. New node starts with pex = false
2. Node connects to bootstrap peers via persistent_peers
3. Node syncs deterministically from height 1
4. After sync completes, operator can enable PEX for ongoing operation

Why This Matters

Without bootstrap nodes, two operators joining the same network might:

• Sync from different peer sets
• Encounter different block ordering during replay
• Produce different app hashes at the same height

Bootstrap nodes eliminate this class of failures.

---

3. Persistent Peers

The persistent_peers setting in config.toml enforces long-lived connections to specific peers.

Behavior

• Node maintains connections to all listed peers
• Reconnects automatically if disconnected
• Does not remove these peers from the address book

Typical Uses

Use Case	Configuration
Validator ↔ Validator	Private persistent peering
Validator ↔ Sentry	Sentry as sole persistent peer
Bootstrap sync	Bootstrap nodes as persistent peers
Cross-datacenter	Stable links between infrastructure

Important Limitation

Setting persistent_peers to point at seed_mode=true nodes is useless. The seed node will disconnect immediately regardless of persistence settings.

---

4. Validators

Validators are a consensus role, not a configuration flag.

What Validators Do

• Participate in consensus
• Propose blocks when selected
• Sign pre-votes and pre-commits
• Submit to slashing conditions

What Makes a Node a Validator

A node becomes a validator when:

1. It has a registered validator key (priv_validator_key.json)
2. The associated operator address has bonded stake
3. The validator is in the active set

Validator Security Requirements

Requirement	Reason
No public RPC	Prevents query DoS and tx injection
Sentry architecture	Hides validator IP from network
Private peering only	No random PEX connections
Firewall rules	Only allow sentry IPs

What Validators Should NOT Do

• Expose RPC endpoints publicly
• Rely on PEX for peer discovery
• Connect directly to seed nodes
• Run without sentry protection in production

---

5. Archive Nodes

Archive refers to data retention, not network behavior.

What Archive Means

An archive node stores complete blockchain history:

• All blocks from height 1
• All state at every height (if pruning=nothing)
• Full transaction index (if enabled)

Archive vs Other Roles

Aspect	Archive Node	Seed Node	Validator
Stores full history	Yes	Irrelevant	Optional
Serves blocksync	Yes	No	Yes
Signs blocks	No	No	Yes
seed_mode	false	true	false

When You Need Archive

• Running a bootstrap node
• Providing blocksync to new nodes
• Historical queries and indexing
• Snapshot generation

Archive Does Not Mean

• The node is a seed (archive nodes can serve blocks; seeds cannot)
• The node is a validator (archive is about storage, not consensus)
• The node must be public (archive nodes can be private)

---

6. Sentry Nodes

Sentry nodes protect validators from direct network exposure.

Architecture

Internet
    │
    ▼
┌─────────┐
│ Sentry  │◄──── Public peers connect here
└────┬────┘
     │
     ▼ (private network)
┌─────────┐
│Validator│◄──── Never exposed to public
└─────────┘

Sentry Configuration

Setting	Sentry	Validator
pex	true	false
persistent_peers	Validator	Sentry only
Public IP	Yes	No
Firewall	Open P2P	Sentry IPs only

Why Sentries Matter

• Validators are high-value targets
• Direct exposure enables DoS attacks
• IP disclosure enables targeted attacks
• Sentries absorb network abuse

---

7. Why Monolythium Does This Differently

Standard Cosmos SDK tooling assumes operators understand these distinctions. In practice:

• Documentation conflates seeds and persistent peers
• No standard "bootstrap" concept exists
• PEX is treated as sufficient for all sync scenarios
• Operators learn through failure

Monolythium's Approach

Problem	Standard Cosmos	Monolythium
Genesis sync source	PEX (random)	Bootstrap nodes (deterministic)
Peer role confusion	Implicit	Explicit documentation
Config drift	Possible	Detected via monoctl config doctor
Replay divergence	Silent failure	Prevented by bootstrap sync

What This Prevents

1. Silent replay failures: Random sync sources may have incompatible state
2. Config drift: Wrong chain IDs or EVM chain IDs go undetected
3. Operator confusion: Unclear why sync fails with seeds configured
4. Nondeterminism: Different operators get different results

---

8. Summary Table

Role	seed_mode	Serves Blocks	Persistent	Used for Sync	Signs Blocks
Seed	true	No	No	No	No
Bootstrap	false	Yes	Yes	Yes	No
Archive	false	Yes	Optional	Yes	No
Validator	false	Yes	Yes	No	Yes
Sentry	false	Yes	Yes	Indirect	No

---

Quick Reference

I want to...

Goal	Use
Find peers when starting fresh	Seed nodes
Sync from genesis deterministically	Bootstrap nodes
Run a public RPC endpoint	Archive node (not seed)
Participate in consensus	Validator behind sentries
Protect my validator	Sentry architecture
Serve historical queries	Archive node

My node is stuck at height 0

1. Check if you only have seeds configured (seeds don't serve blocks)
2. Add bootstrap nodes as persistent_peers
3. Set pex = false during initial sync
4. Verify bootstrap nodes are archive nodes with earliest_block_height = 1

---

Related Documentation

• Join Network - Step-by-step network joining
• Seeds and Peers - Configuration reference
• Seed Deployment - Running seed infrastructure