Skip to main content

babylond validate-genesis

Validate the genesis file for correctness and consistency.

Overview

The babylond validate-genesis command validates a genesis file to ensure it contains valid configuration and state data for initializing a Babylon blockchain. This command performs comprehensive checks on the genesis file structure, module parameters, initial state, and cross-module consistency.

Why Genesis Validation?

Genesis validation is crucial because:

  • Ensures the blockchain can start successfully
  • Prevents runtime errors during network initialization
  • Validates all module parameters are within acceptable ranges
  • Confirms initial state consistency across modules
  • Detects configuration errors before network deployment

Usage

babylond validate-genesis [file] [flags]

Arguments

ArgumentTypeDescriptionDefault
[file]stringPath to genesis file to validateUses default location

If no file is specified, the command validates the genesis file at the default location: $HOME/.babylond/config/genesis.json

Flags

FlagTypeDescriptionDefault
-h, --helpbooleanShow help informationfalse

Examples

Validate Default Genesis File

babylond validate-genesis

Validate Specific Genesis File

babylond validate-genesis ./my-genesis.json

Validate Genesis During Testnet Setup

# After creating testnet
babylond testnet --v 4 --output-dir ./testnet

# Validate generated genesis
babylond validate-genesis ./testnet/node0/babylond/config/genesis.json

Validate Before Network Launch

# Validate mainnet genesis before launch
babylond validate-genesis ./mainnet-genesis.json

Pipeline Integration

#!/bin/bash
# validate-network.sh

GENESIS_FILE="./config/genesis.json"

echo "Validating genesis file..."
if babylond validate-genesis "$GENESIS_FILE"; then
echo "✅ Genesis validation passed"
exit 0
else
echo "❌ Genesis validation failed"
exit 1
fi

What Genesis Validation Checks

Basic Structure

  • JSON Format: Valid JSON syntax and structure
  • Required Fields: All mandatory genesis fields are present
  • Field Types: Correct data types for all fields
  • Encoding: Proper base64/hex encoding where required

Chain Configuration

  • Chain ID: Valid chain identifier format
  • Genesis Time: Proper timestamp format
  • Initial Height: Valid starting block height
  • Consensus Parameters: Valid consensus configuration

Module Parameters

The validation checks parameters for all Babylon modules:

Core Modules

  • Auth: Account parameters and configuration
  • Bank: Token denominations and supply
  • Distribution: Reward distribution parameters
  • Staking: Validator and delegation parameters
  • Slashing: Penalty and jail configurations
  • Gov: Governance voting and proposal parameters

Babylon-Specific Modules

  • Bitcoin Staking: BTC staking parameters and covenant configuration
  • Epoching: Epoch configuration and validator limits
  • BTC Light Client: Bitcoin header configuration
  • Finality: Finality provider parameters
  • Checkpointing: Checkpoint submission settings
  • Zone Concierge: Inter-zone communication settings

State Consistency

  • Account Balances: Total supply matches account balances
  • Validator Set: Proper validator configuration and voting power
  • Cross-Module References: Valid references between modules
  • Economic Parameters: Consistent economic configuration

Common Validation Errors

JSON Syntax Errors

Error: invalid character '}' looking for beginning of object key string

Solution: Fix JSON syntax, often missing commas or quotes

Missing Required Fields

Error: missing field 'chain_id' in genesis

Solution: Add the missing required field to genesis

Invalid Parameters

Error: invalid parameter: max_validators must be positive

Solution: Correct the invalid parameter value

Supply Mismatch

Error: total supply does not match sum of account balances

Solution: Ensure total supply equals the sum of all account balances

Invalid Addresses

Error: invalid address format in genesis accounts

Solution: Verify all addresses use correct bech32 format

Troubleshooting

Validation Failures

Check JSON syntax:

# Use jq to validate JSON syntax
jq . genesis.json > /dev/null && echo "Valid JSON" || echo "Invalid JSON"

Verify required fields:

# Check for required top-level fields
jq 'has("chain_id") and has("genesis_time") and has("app_state")' genesis.json

Validate addresses:

# Extract and validate addresses
jq -r '.app_state.auth.accounts[].address' genesis.json | while read addr; do
babylond keys parse "$addr" 2>/dev/null || echo "Invalid address: $addr"
done

Module-Specific Issues

Bank module errors:

# Check token supplies
jq '.app_state.bank.supply' genesis.json

# Verify account balances sum
jq '.app_state.bank.balances' genesis.json

Staking module errors:

# Check validator configuration
jq '.app_state.staking.validators' genesis.json

# Verify delegation consistency
jq '.app_state.staking.delegations' genesis.json

Bitcoin staking errors:

# Check BTC staking parameters
jq '.app_state.btcstaking.params' genesis.json

# Verify covenant configuration
jq '.app_state.btcstaking.params.covenant_pks' genesis.json

Genesis Validation in Development

Local Development

# Initialize node
babylond init mynode

# Customize genesis
jq '.app_state.bank.supply[0].amount = "1000000000000"' \
~/.babylond/config/genesis.json > genesis-temp.json
mv genesis-temp.json ~/.babylond/config/genesis.json

# Validate changes
babylond validate-genesis

Testnet Deployment

# Create testnet
babylond testnet --v 4 --output-dir ./testnet

# Validate all node genesis files
for i in {0..3}; do
echo "Validating node$i genesis..."
babylond validate-genesis "./testnet/node$i/babylond/config/genesis.json"
done

Continuous Integration

# .github/workflows/validate-genesis.yml
name: Validate Genesis
on: [push, pull_request]

jobs:
validate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Setup Babylon
run: make install
- name: Validate Genesis
run: babylond validate-genesis ./networks/mainnet/genesis.json

Best Practices

Pre-Launch Validation

  • Always validate genesis files before network launch
  • Test genesis validation in CI/CD pipelines
  • Validate after any manual genesis modifications
  • Cross-verify with multiple team members

Development Workflow

# Development validation script
#!/bin/bash
set -e

echo "Creating development genesis..."
babylond init dev-node

echo "Customizing genesis parameters..."
# Add custom configuration here

echo "Validating genesis..."
babylond validate-genesis

echo "Starting node with validated genesis..."
babylond start

Network Upgrades

# Validate upgraded genesis
babylond export > exported-state.json
babylond validate-genesis exported-state.json

Integration with Other Commands

After Testnet Creation

babylond testnet --v 4 --output-dir ./testnet
babylond validate-genesis ./testnet/node0/babylond/config/genesis.json

Before Node Start

babylond validate-genesis
babylond start

With Genesis Export

# Export current state
babylond export --height 1000 > exported-genesis.json

# Validate exported state
babylond validate-genesis exported-genesis.json

Output Examples

Successful Validation

File at ./genesis.json is a valid genesis file

Failed Validation

Error: genesis doc is invalid
invalid genesis file: validator set is empty

Verbose Output

# Enable debug logging for detailed validation info
babylond validate-genesis --log_level debug

Automation Examples

Genesis Validation Script

#!/bin/bash
# validate-all-genesis.sh

GENESIS_FILES=(
"./mainnet-genesis.json"
"./testnet-genesis.json"
"./devnet-genesis.json"
)

for genesis in "${GENESIS_FILES[@]}"; do
echo "Validating $genesis..."
if babylond validate-genesis "$genesis"; then
echo "✅ $genesis is valid"
else
echo "❌ $genesis validation failed"
exit 1
fi
echo
done

echo "All genesis files validated successfully!"

Docker Validation

FROM babylonlabs/babylond:latest

COPY genesis.json /tmp/genesis.json

RUN babylond validate-genesis /tmp/genesis.json

CMD ["babylond", "start"]

Makefile Integration

validate-genesis:
@echo "Validating genesis file..."
@babylond validate-genesis ./config/genesis.json

start-node: validate-genesis
@babylond start

.PHONY: validate-genesis start-node
Pro Tips
  • Always validate genesis files before network deployment
  • Include genesis validation in your CI/CD pipelines
  • Validate after any manual modifications to genesis files
  • Use version control to track genesis file changes
  • Test genesis validation with different scenarios during development
Important Notes
  • Genesis validation does not guarantee successful network startup
  • Some runtime issues may only appear during actual blockchain execution
  • Always backup original genesis files before modifications
  • Coordinate genesis validation with all network participants
  • Different Babylon versions may have different validation rules

Global Flags

FlagTypeDescriptionDefault
--homestringDirectory for config and data"/Users/dariaagadzhanova/.babylond"
--log_formatstringLogging format (json|plain)"plain"
--log_levelstringLogging level or pattern"info"
--log_no_colorbooleanDisable colored logsfalse
--tracebooleanPrint full stack trace on errorsfalse