Security Guide

This guide covers security best practices for Monolythium node operators, including key management, server hardening, and safe operational procedures.

Key Types

Monolythium uses three types of keys, each serving a different purpose:

Key Type	Algorithm	Purpose	Management
Account Keys	secp256k1	Sign transactions, hold funds	BIP39 mnemonic, monarch keys account
Validator Keys	ed25519	Sign consensus votes (blocks)	monarch keys validator, stored in priv_validator_key.json
Node Keys	ed25519	P2P identity	Auto-generated, stored in node_key.json

Account Keys

Account keys are derived from a BIP39 mnemonic phrase. When you create an account key with monarch keys account create, the mnemonic is displayed exactly once. Write it down and store it securely offline.

# Create a new account key
monarch keys account create my-key
# IMPORTANT: Write down the mnemonic phrase immediately

# Recover from mnemonic
monarch keys account recover my-key

# List keys (safe, shows addresses only)
monarch keys account list

# Show key details (mono1... and 0x... addresses)
monarch keys account show my-key

Validator Keys

Validator keys are used to sign consensus votes. The key file (priv_validator_key.json) is the most sensitive file on your server. If compromised, an attacker can double-sign and cause your validator to be permanently slashed.

# Generate a new validator key
monarch keys validator create

# Export with AES-256-GCM encryption
monarch keys validator export

# Import from encrypted file
monarch keys validator import /path/to/exported-key.json

Node Keys

Node keys identify your node on the P2P network. They are auto-generated during monarch init and stored in node_key.json. While less sensitive than validator keys, they should still be protected since they identify your node.

---

SSH Key Management

All remote access to your node servers should use SSH key-based authentication.

Recommendations

• Use ed25519 keys (stronger and faster than RSA):

  ssh-keygen -t ed25519 -C "monolythium-node" -f ~/.ssh/mono_node

• Passphrase-protect every key
• Use dedicated keys per server -- do not reuse keys across unrelated infrastructure
• Disable password authentication in /etc/ssh/sshd_config:

  PasswordAuthentication no

• Restrict SSH access by IP when possible using AllowUsers or firewall rules

---

Validator Key Backup

Losing your validator key means losing your validator. Backup procedures:

Using Monarch CLI

# Backup all keys (account + validator + node)
monarch backup keys
# Creates an encrypted backup archive

# Restore from backup
monarch backup restore /path/to/backup/

Manual Export

# Export validator key with AES-256-GCM encryption
monarch keys validator export
# Prompts for an encryption password
# Creates an encrypted file you can store offline

Backup Storage

• Store backups in at least two offline locations (USB drive, safety deposit box)
• Never store unencrypted key backups on cloud storage
• Never email or message key material
• Test restoration periodically to verify backups are valid

---

Monarch Connect Security

Monarch Connect is designed to manage nodes without compromising security:

Aspect	How It Works
SSH key paths	Only the file path is stored in the app, never the key contents
Passphrases	Handled through the OS system keyring (macOS Keychain, Linux Secret Service, Windows Credential Manager)
Command sanitization	All user input is sanitized before being passed to the remote shell
RPC whitelist	Only pre-approved RPC endpoints can be queried
CSP	Content Security Policy prevents external resource loading
Network	Zero additional ports opened on servers -- everything runs over SSH

---

MCP Security

Monarch Connect includes an MCP (Model Context Protocol) server for integration with tools like Claude Desktop and Claude Code.

Protection	Detail
Transport	Stdio only -- no network ports opened
Read-only default	9 of 12 tools are read-only
Authorization	Each server must be individually authorized for MCP access
Read-write opt-in	node_start, node_stop, node_restart require explicit per-server opt-in
RPC endpoints	Whitelisted -- MCP cannot query arbitrary RPC paths

---

Password Handling

Monarch CLI never stores passwords on disk:

• Passwords for keyring operations are prompted interactively
• For automation, pass via the --password flag:

  monarch validator register --from my-key --password "$(cat /secure/password)" --yes

• The password flag value is not logged or written to any file
• Environment variables for passwords are cleared after use

---

Server Hardening

Automated Hardening

monarch harden

This command applies recommended security settings including:

• SSH configuration hardening
• Firewall rule suggestions
• File permission fixes
• Unnecessary service identification

Firewall Rules

monarch firewall

Prints recommended UFW rules for your node role:

# Example output for a validator node
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow 22/tcp        # SSH
sudo ufw allow 26656/tcp     # P2P (LythiumBFT)
# Do NOT expose 26657 (RPC), 1317 (REST), 8545 (EVM) on validators
sudo ufw enable

Validator Port Exposure

Validators should only expose port 26656 (P2P) and 22 (SSH). Do not expose RPC (26657), REST (1317), gRPC (9090), or EVM (8545/8546) ports on validator nodes. Use sentry nodes to serve public traffic.

---

Double-Signing Prevention

Double-signing (signing two different blocks at the same height) results in severe slashing and is irreversible. This most commonly happens when migrating a validator to a new server.

Safe Migration Procedure

Follow this exact order:

1. Stop the old validator and verify it is fully stopped:

   # On the OLD server
   monarch stop
   monarch status   # Confirm process is not running

2. Wait for at least one block to pass after stopping

3. Export the validator key from the old server:

   # On the OLD server
   monarch keys validator export
   # Transfer the encrypted file to the new server via secure channel

4. Import the validator key on the new server:

   # On the NEW server
   monarch keys validator import /path/to/exported-key.json

5. Start the new validator only after confirming the old one is stopped:

   # On the NEW server
   monarch start
   monarch status   # Verify signing has resumed

Never Run Two Validators with the Same Key

If both the old and new validators sign blocks simultaneously, your validator will be permanently slashed for double-signing. There is no recovery from this. Always stop the old validator and verify it is stopped before starting the new one.

---

AI Safety

When using the Claude AI integration in Monarch Connect or any other AI tool:

• Never share private keys, mnemonics, or passwords with AI tools
• Never paste key material into chat interfaces
• Use monarch commands for all key operations -- they handle secrets safely
• AI tools can view node status, logs, and metrics but should never have access to key material
• Review AI-suggested commands before executing them
• The MCP integration is specifically designed to prevent AI access to sensitive data

---

Security Checklist

Use this checklist for new node deployments:

• SSH key authentication enabled, password auth disabled
• Dedicated ed25519 SSH key with passphrase for this server
• Firewall configured (only P2P and SSH exposed for validators)
• Validator key backed up in two offline locations
• Account mnemonic written down and stored offline
• File permissions correct (chmod 600 on key files)
• Node running as a dedicated non-root user
• monarch doctor passes all security checks
• Sentry architecture configured (validators behind sentries)
• Auto-start enabled with monarch enable-boot
• Metrics collection enabled with monarch metrics enable
• Notification alerts configured with monarch notify setup

---

Related

• Monarch CLI -- CLI commands for key management and hardening
• Monarch Connect -- Desktop GUI security model
• Validator Operations -- Full validator lifecycle
• Troubleshooting -- Common security-related issues