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.
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
Argument | Type | Description | Default |
---|---|---|---|
[file] | string | Path to genesis file to validate | Uses default location |
If no file is specified, the command validates the genesis file at the default location: $HOME/.babylond/config/genesis.json
Flags
Flag | Type | Description | Default |
---|---|---|---|
-h, --help | boolean | Show help information | false |
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
- 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
- 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
Flag | Type | Description | Default |
---|---|---|---|
--home | string | Directory for config and data | "/Users/dariaagadzhanova/.babylond" |
--log_format | string | Logging format (json |plain ) | "plain" |
--log_level | string | Logging level or pattern | "info" |
--log_no_color | boolean | Disable colored logs | false |
--trace | boolean | Print full stack trace on errors | false |