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