Setup & Configuration

🔐 Security First: Throughout this setup, remember that your validator's priv_validator_key.json is the most critical file. It must ONLY exist on ONE active node at a time. Running the same key on multiple nodes simultaneously will result in double signing, leading to permanent jail and slashing of your stake.

Node Installation

Binary Installation

# Clone the repository
git clone https://github.com/Bitplanet-L1/Bitplanet-CosmosEVM.git
cd Bitplanet-CosmosEVM

# Build and install the evmd binary
make install

# Verify installation
evmd version

Docker Installation

For operators preferring containerized deployments:

# Clone the repository
git clone https://github.com/Bitplanet-L1/Bitplanet-CosmosEVM.git
cd Bitplanet-CosmosEVM

# Use docker-compose for quick setup
docker-compose up -d chain

# Check logs
docker-compose logs -f chain

Docker Compose Ports:

Automatic port mapping for all services (26656, 26657, 1317, 9090, 8545, 8546)
Data persisted in Docker volumes
Use for development/testing, not recommended for production validators

Production Docker Setup:

Note: There is no official public Docker image. You must build the image locally from the repository's Dockerfile.

System Service Setup

Create a systemd service for automatic restarts and monitoring:

Configuration Parameters

Initialize Node

⚠️ CRITICAL SECURITY CHOICE: Keyring Backend

The keyring backend determines how your validator keys are stored:

For Production (REQUIRED):

--keyring-backend file - Keys encrypted with password (RECOMMENDED)
--keyring-backend os - Uses system keyring (macOS Keychain, Windows Credential Manager, etc.)

For Testing/Development Only:

--keyring-backend test - UNENCRYPTED keys stored in plain text on disk
NEVER use in production - anyone with file access can steal your keys and funds

This documentation uses file backend throughout all examples.

Key Configuration Files

Location: $HOME/.evmd/config/

config.toml - Tendermint consensus and networking configuration
app.toml - Application-level settings (API, gRPC, EVM)
genesis.json - Chain genesis state
node_key.json - P2P node identity (DO NOT share)
priv_validator_key.json - Validator signing key (CRITICAL - backup securely)

Critical Configuration Settings

config.toml:

app.toml:

Network Joining

Genesis Setup

For New Networks (Genesis Validators):

For Existing Networks (Post-Genesis Validators):

Validator Key Management

🚨 CRITICAL SECURITY WARNING: Double Signing Prevention

NEVER run the same validator key on multiple nodes simultaneously! This will result in:

Permanent jail - Your validator will be permanently banned from the network
Slashing penalty - Significant portion of your stake will be burned (typically 5%)
Loss of reputation - Permanent record of double signing violation

Best Practices:

Only ONE active node should have your priv_validator_key.json at any time
Before migrating validators, ALWAYS stop the old node first
Keep secure backups but NEVER restore keys to a second node while the first is running

If you accidentally start multiple nodes:

IMMEDIATELY stop ALL nodes
Identify which node is properly synced
Delete priv_validator_key.json from ALL other nodes
Start ONLY the chosen node

Create Validator Keys:

🔐 Security Reminder: Always use --keyring-backend file or os for production. Never use test backend as it stores keys unencrypted. See "Keyring Backend" security section above.

Backup Critical Files:

Create Validator

⚠️ CRITICAL: Before creating a validator, ensure you understand the rule that your priv_validator_key.json must ONLY exist on ONE active node at a time!

Prerequisites:

Node fully synced with network
Validator account funded with sufficient tokens
Understanding of double signing penalties

Understanding the parameters:

pubkey: Your validator's consensus public key
amount: How much to stake (1,000 BPL in this example)
moniker: Your validator's display name (choose something unique)
commission-rate: Your commission (0.10 = 10%)
commission-max-rate: Maximum commission you can set (0.20 = 20%)
commission-max-change-rate: Max daily change (0.01 = 1% per day)
min-self-delegation: Minimum self-stake to remain active

Important Notes:

Amount: Must be in base units (1 bplcoin = 10^18 base units). Ensure you have more than this amount for transaction fees.
Commission rates: Once set, commission-max-rate cannot be changed. Choose carefully as it limits your future earning flexibility.
Commission changes: Limited by commission-max-change-rate. Example: if set to 0.01, you can only change commission by 1% per day.
Min-self-delegation: If your self-delegation falls below this amount, your validator automatically becomes inactive.

💡 Gas Settings

--gas auto: Automatically estimates gas needed
--gas-adjustment 1.5: Adds 50% buffer to estimation (matches join_validator.sh script)
This ensures your transaction succeeds even if gas estimation is slightly off

ℹ️ Validator Status

New validators may show as "jailed" initially if they're not signing blocks. This is normal for Method 1 since you're not running a local node. See Unjailing Your Validator below.

Managing Your Validator

Once your validator is running, you'll need to perform regular management tasks.

Checking Validator Status

Monitor your validator's current state:

Unjailing Your Validator

If your validator gets jailed due to downtime:

⚠️ Why Validators Get Jailed

Validators are jailed for:

Downtime: Missing too many blocks (usually >5% over a window)
Double signing: Running the same validator key on multiple nodes (results in permanent jail and slashing)

Always ensure you have only one node running with your validator keys.

Important: You can only unjail after the jailed_until time has passed. Check this with:

Delegating to Your Validator

Increase your self-delegation:

Firewall & Security

Basic Firewall Configuration

Next Steps

Review hardware requirements in Hardware Requirements
Learn about daily operations in Operations
Follow step-by-step procedures in Runbooks
Troubleshoot issues in Troubleshooting

PreviousHardware Requirements

NextOperations

Last updated 9 months ago