Runtime Configuration & Network Launch

This guide covers runtime configuration (app.toml, config.toml) and network launch procedures. Complete these steps after your genesis file is finalized.

Related Documentation:

Pre-Genesis & Genesis Setup - Initial configuration and genesis preparation
Configuration Reference - Commands, examples, and quick reference

Overview

Once you have your network configuation and genesis file ready, you can prepare to launch the network:

Configure Runtime Settings - Set node-specific parameters in app.toml and config.toml
Distribute Genesis File - Share the final genesis file with all validators
Launch Network - Coordinate the chain start across all validators
Monitor and Maintain - Ensure healthy network operation post-launch

Runtime Configuration

Runtime configuration is set in config files located at ~/.yourchain/config/. These settings can be changed after genesis and are node-specific.

Configuration Files

Three main configuration files control your node’s runtime behavior:

app.toml - Application settings including EVM parameters, JSON-RPC server, gas prices, and API endpoints. Changes require node restart.
config.toml - CometBFT (consensus) settings including P2P networking, consensus timeouts, and mempool configuration. Changes require node restart.
client.toml - CLI client defaults including chain-id, keyring backend, and output preferences. Changes take effect immediately.

app.toml Configuration

Located at ~/.yourchain/config/app.toml, this file controls application-level settings.

Minimum Gas Prices

Show More Details

Attribute	Value
Description	Node-level minimum gas price to accept transactions into mempool
File	`app.toml`
Section	Root level
Type	String
Format	`<amount><denom>`
Default	`"0aatom"`
Adjustable	Per Node (requires restart)
Source	`server/config/migration/v0.50-app.toml:11`
Why Configure	Protect against spam and ensure validators can cover operational costs

Configuration
Recommendations

Edit app.toml:

# Minimum gas prices for the node to accept transactions
minimum-gas-prices = "1000000000atoken"

Format: <amount><denom>Examples:

"1000000000atoken" = 1 gwei
"500000000atoken" = 0.5 gwei
"0atoken" = accept all transactions (not recommended)

How it works:

Node rejects transactions with gas price below this value
Protects against spam
Should align with genesis fee market min_gas_price

JSON-RPC Configuration

Show More Details

Attribute	Value
Description	Ethereum-compatible RPC endpoints for EVM interactions
File	`app.toml`
Section	`[json-rpc]`
Type	Object containing multiple JSON-RPC configuration parameters
Default Ports	`8545` (HTTP), `8546` (WebSocket)
Default Address	`127.0.0.1:8545` (HTTP), `127.0.0.1:8546` (WebSocket)
Adjustable	Per Node (requires restart)
Source	`server/config/config.go:236-310`
Why Configure	Control API exposure, security settings, and performance limits

Standard Configuration
API Namespaces
Security Settings

[json-rpc]
# Enable JSON-RPC server
enable = true

# HTTP server address
# Use 127.0.0.1 for localhost only, 0.0.0.0 for public access
address = "0.0.0.0:8545"

# WebSocket server address
ws-address = "0.0.0.0:8546"

# API namespaces to enable
api = ["eth", "net", "web3", "txpool"]

# Gas cap for eth_call and eth_estimateGas
gas-cap = 25000000

# EVM execution timeout
evm-timeout = "5s"

# Transaction fee cap (in native token units)
txfee-cap = 1.0

# Maximum number of logs returned
logs-cap = 10000

# Maximum block range for queries
block-range-cap = 10000

# HTTP request timeout
http-timeout = "30s"

# HTTP idle timeout
http-idle-timeout = "2m0s"

# Allow unprotected transactions (only for development)
allow-unprotected-txs = false

# Maximum open connections (0 = unlimited)
max-open-connections = 0

# Enable indexer for historical queries
enable-indexer = false

Default Port: 8545 (HTTP), 8546 (WebSocket)

EVM Configuration

Show More Details

Attribute	Value
Description	EVM module settings including chain ID, tracer, and gas limits
File	`app.toml`
Section	`[evm]`
Type	Object containing multiple EVM configuration parameters
Default	Chain ID from config, no tracing, unlimited gas per tx
Adjustable	Per Node (requires restart); `evm-chain-id` is read-only
Source	`server/config/config.go:56-149`
Why Configure	Debug transactions, limit gas usage, control EVM behavior

Configuration
Parameter Details

[evm]
# EVM chain ID (set during init from config/config.go)
# Do not modify - change in source code before init
evm-chain-id = 262144

# Tracer type for debugging
tracer = ""

# Maximum gas limit for individual transactions
# 0 = unlimited
max-tx-gas-wanted = 0

# Cache preimages for historical queries
cache-preimage = false

# Minimum tip (priority fee) required
min-tip = 0

EVM Mempool Configuration

Show More Details

Attribute	Value
Description	Transaction pool behavior including price limits, queue sizes, and lifetime
File	`app.toml`
Section	`[evm.mempool]`
Type	Object containing mempool configuration parameters
Default	1 wei price limit, 5120 global slots, 3 hour lifetime
Adjustable	Per Node (requires restart)
Source	`server/config/config.go:158-187`
Why Configure	Optimize mempool capacity, prevent spam, manage transaction lifetime

New in v0.5.0: Mempool configuration is now fully exposed in app.toml and can be adjusted without code changes.

Standard Configuration
Parameter Details

[evm.mempool]
# Minimum gas price to accept into pool (in wei)
price-limit = 1

# Minimum price bump % to replace existing transaction
price-bump = 10

# Executable transaction slots guaranteed per account
account-slots = 16

# Maximum executable slots for all accounts
global-slots = 5120

# Non-executable slots per account
account-queue = 64

# Non-executable slots for all accounts
global-queue = 1024

# Maximum time non-executable transactions stay queued
lifetime = "3h0m0s"

Source: server/config/config.go:158-187

Advanced Mempool Configuration: For detailed information on integrating the EVM mempool, see the EVM Mempool Integration guide.

config.toml Configuration

Located at ~/.yourchain/config/config.toml, this file controls CometBFT (consensus layer) settings.

Persistent Peers

Show More Details

Attribute	Value
Description	List of nodes to maintain persistent connections to
File	`config.toml`
Section	`[p2p]`
Type	String (comma-separated list)
Format	`node_id@ip:port,node_id2@ip:port`
Default	`""` (empty - no persistent peers)
Default Port	`26656`
Adjustable	Per Node (requires restart)
Why Configure	Ensure validators stay connected to the network

Configuration
Getting Node IDs
Coordinator Sheet

Edit config.toml:

[p2p]
# Comma separated list of nodes to keep persistent connections to
persistent_peers = "node_id@ip:port,node_id2@ip:port"

Example:

persistent_peers = "7c90e16cca334eb7@192.168.1.100:26656,abc123def456@192.168.1.101:26656"

Verification:

# Check connected peers
curl localhost:26657/net_info | jq '.result.peers'

Default P2P Port: 26656

Consensus Timeouts

Show More Details

Attribute	Value
Description	Timing parameters for consensus protocol
File	`config.toml`
Section	`[consensus]`
Type	Duration strings
Default	`"5s"` commit timeout (determines block time)
Adjustable	Per Node (requires restart)
Why Configure	Adjust block time, optimize for network conditions

Production
Development Settings
Parameter Explanation

Default values:

[consensus]
timeout_propose = "3s"
timeout_propose_delta = "500ms"
timeout_prevote = "1s"
timeout_prevote_delta = "500ms"
timeout_precommit = "1s"
timeout_precommit_delta = "500ms"
timeout_commit = "5s"

Typically you do not need to adjust these.

Prometheus Metrics

Show More Details

Attribute	Value
Description	Enable metrics collection for monitoring
File	`config.toml`
Section	`[instrumentation]`
Type	Boolean + String (address)
Default	`false` (disabled), port `26660`
Adjustable	Per Node (requires restart)
Why Configure	Monitor node health, track performance metrics

[instrumentation]
# Enable Prometheus metrics
prometheus = true

# Prometheus listen address
prometheus_listen_addr = ":26660"

Access metrics:

curl http://localhost:26660/metrics

Enable for production to monitor node and overall network health.

client.toml Configuration

Located at ~/.yourchain/config/client.toml, this file configures client behavior.

Set Client Chain ID

Show More Details

Attribute	Value
Description	Chain ID for CLI client operations
File	`client.toml`
Section	Root level
Type	String
Default	`""` (empty - must be set manually)
Adjustable	Per Node (takes effect immediately)
Why Configure	Required for node startup - must match genesis chain ID

The node reads chain-id from client.toml at startup. If this doesn’t match genesis.json, the node will fail to start.

Configuration

yourchain config set client chain-id mychain-1 --home ~/.yourchain

Or edit client.toml directly:

chain-id = "mychain-1"

Other client settings:

# Keyring backend - This can be changed to "file", or "test" to create additional keys in different formats.
# "Test" creates an UNSAFE key that requires no password to submit txs for quicker iteration when testing.
keyring-backend = "os"

# Output format
output = "text"

# Node RPC address - This can be changed to a public endpoint to use the light client without syncing the full node.
node = "tcp://localhost:26657"

# Broadcast mode
broadcast-mode = "sync"

Network Launch

After all validators have configured their nodes, coordinate the network launch.

Pre-Launch Checklist

Show More Details

Finalize Genesis

All genesis parameters configured
Genesis validation passes
Genesis accounts and validators added
Genesis time set for future launch

Distribute Genesis

Share final genesis file with all validators
All validators verify genesis hash matches
No modifications allowed after distribution

Runtime Configuration

All validators configure app.toml
All validators configure config.toml
All validators set client.toml chain-id
Persistent peers exchanged

Pre-Launch Tests

Validators verify binary version
Validators test node starts without errors
Network connectivity verified
Monitoring systems ready

Distribute Genesis File

Show More Details

After finalizing your genesis file, distribute it to all validators.

GitHub Release
IPFS

Recommended for public networks:

# Coordinator creates release
gh release create v1.0.0-genesis \
  ~/.yourchain/config/genesis.json \
  --title "Genesis File" \
  --notes "Official genesis file for mychain-1"

# Validators download
wget https://github.com/yourorg/yourchain/releases/download/v1.0.0-genesis/genesis.json \
  -O ~/.yourchain/config/genesis.json

Verify Genesis Hash

Show More Details

Critical: All validators must verify they have the identical genesis file.

Generate Hash
Coordination

Each validator runs:

jq -S -c . ~/.yourchain/config/genesis.json | shasum -a 256

Example output:

a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6  -

Exchange Peer Information

Show More Details

Validators need each other’s peer information to connect.

Collect Information
Update Config
Verification

Each validator provides:

# Get node ID
yourchain comet show-node-id
# Output: 7c90e16cca334eb7259754f964918d879ca54996

# Share:
# - Node ID: 7c90e16cca334eb7259754f964918d879ca54996
# - Public IP: 192.168.1.100
# - P2P Port: 26656 (default)

Format for sharing:

7c90e16cca334eb7259754f964918d879ca54996@192.168.1.100:26656

Coordinate Launch Time

Show More Details

Set and coordinate the exact launch time across all validators.

Set Genesis Time
Launch Timeline
Validator Experience

Coordinator sets future genesis time:

jq '.genesis_time = "2024-12-01T00:00:00Z"' \
  ~/.yourchain/config/genesis.json > tmp && mv tmp ~/.yourchain/config/genesis.json

Timing recommendations:

Testnet: 1-2 hours ahead (allows validator setup)
Mainnet: 24-48 hours ahead (allows thorough preparation)
Local dev: Past time (starts immediately)

Start Validator Nodes

Show More Details

After configuration and coordination, start the nodes.

Start Command
Monitor Logs
Systemd Service

# Standard startup
yourchain start

# With log level
yourchain start --log_level info

# In background with systemd (recommended)
sudo systemctl start yourchain

# In background with nohup
nohup yourchain start > yourchain.log 2>&1 &

Verify Network Health

Show More Details

After launch, verify the network is operating correctly.

Block Production
Validator Participation
Network Connectivity
Health Check
RPC Endpoints

Check block height increasing:

# Via CometBFT RPC
curl localhost:26657/status | jq '.result.sync_info.latest_block_height'

# Via EVM RPC
curl http://localhost:8545 \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'

Should see: Block height increasing over time.

Post-Launch Operations

After successful launch, maintain healthy network operation.

Validator Operations

Show Validator Operations

Unjail Validator
Edit Validator
Monitor Performance

If validator gets jailed for downtime:

# Check if jailed
yourchain query staking validator $(yourchain keys show validator --bech val -a)

# Unjail
yourchain tx slashing unjail \
  --from validator \
  --chain-id mychain-1 \
  --fees 1000000000000000000atoken

Monitoring and Alerting

Show Monitoring and Alerting

Key Metrics
Common Issues

Monitor these metrics:

Block height - Should increase steadily
Peer count - Should maintain connections
Validator signing - Should sign every block
Memory/CPU usage - Should be stable
Disk space - Should have adequate free space

Prometheus metrics available at http://localhost:26660/metrics

Backup and Recovery

Show Backup and Recovery

Backup Critical Data
Disaster Recovery

What to backup:

# Validator private key
cp ~/.yourchain/config/priv_validator_key.json /secure/backup/

# Node key
cp ~/.yourchain/config/node_key.json /secure/backup/

# Genesis file
cp ~/.yourchain/config/genesis.json /secure/backup/

Store securely:

Encrypted storage
Multiple locations
Offline backups
Access controls

Next Steps

Your chain should now be launched and operational! If not, start the process over from the beginning, or contact us! Further resources:

Configuration Reference - Complete command reference and examples
VM Module Documentation - EVM configuration details
Cosmos SDK Documentation - General Cosmos SDK operations

Cosmos EVM

​Overview

​Runtime Configuration

​Configuration Files

​app.toml Configuration

​Minimum Gas Prices

​JSON-RPC Configuration

​EVM Configuration

​EVM Mempool Configuration

​config.toml Configuration

​Persistent Peers

​Consensus Timeouts

​Prometheus Metrics

​client.toml Configuration

​Set Client Chain ID

​Network Launch

​Pre-Launch Checklist

​Distribute Genesis File

​Verify Genesis Hash

​Exchange Peer Information

​Coordinate Launch Time

​Start Validator Nodes

​Verify Network Health

​Post-Launch Operations

​Validator Operations

​Monitoring and Alerting

​Backup and Recovery

​Next Steps

Overview

Runtime Configuration

Configuration Files

app.toml Configuration

Minimum Gas Prices

JSON-RPC Configuration

EVM Configuration

EVM Mempool Configuration

config.toml Configuration

Persistent Peers

Consensus Timeouts

Prometheus Metrics

client.toml Configuration

Set Client Chain ID

Network Launch

Pre-Launch Checklist

Distribute Genesis File

Verify Genesis Hash

Exchange Peer Information

Coordinate Launch Time

Start Validator Nodes

Verify Network Health

Post-Launch Operations

Validator Operations

Monitoring and Alerting

Backup and Recovery

Next Steps