\
+ --moniker "Validator Name" \
+ --commission-rate 0.1 \
+ --commission-max-rate 0.2 \
+ --commission-max-change-rate 0.01 \
+ --min-self-delegation 1 \
+ --keyring-backend test
+
+# Collect gentxs
+yourchain genesis collect-gentxs
+
+# Validate genesis
+yourchain genesis validate
+```
+
+
+
+### Genesis File Manipulation
+
+
+```bash expandable
+# Set value in genesis
+jq '.path.to.param = "value"' genesis.json > tmp && mv tmp genesis.json
+
+# Examples
+jq '.chain_id = "mychain-1"' genesis.json > tmp && mv tmp genesis.json
+jq '.app_state.staking.params.bond_denom = "atoken"' genesis.json > tmp && mv tmp genesis.json
+jq '.app_state.evm.params.evm_denom = "atoken"' genesis.json > tmp && mv tmp genesis.json
+
+# Query value
+jq '.app_state.staking.params.bond_denom' genesis.json
+
+# Validate
+yourchain genesis validate
+```
+
+
+
+### Genesis Hash
+
+
+```bash expandable
+# Generate hash
+jq -S -c . ~/.yourchain/config/genesis.json | shasum -a 256
+
+# Save hash to file
+jq -S -c . ~/.yourchain/config/genesis.json | shasum -a 256 > genesis_hash.txt
+
+# Verify
+cat genesis_hash.txt
+```
+
+
+
+### Client Configuration
+
+
+```bash expandable
+# Set chain ID
+yourchain config set client chain-id mychain-1 --home ~/.yourchain
+
+# Set keyring backend
+yourchain config set client keyring-backend os --home ~/.yourchain
+
+# View current config
+yourchain config get client --home ~/.yourchain
+```
+
+
+
+### Node Operations
+
+
+```bash expandable
+# Start node
+yourchain start
+
+# Start with custom home
+yourchain start --home ~/.yourchain
+
+# Start with log level
+yourchain start --log_level info
+
+# Check status
+curl localhost:26657/status | jq
+
+# Check block height
+curl localhost:8545 \
+ -X POST \
+ -H "Content-Type: application/json" \
+ -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'
+```
+
+
+
+### Validator Operations
+
+
+```bash expandable
+# Unjail validator
+yourchain tx slashing unjail \
+ --from validator \
+ --chain-id mychain-1 \
+ --fees 1000000000000000000atoken
+
+# Edit validator
+yourchain tx staking edit-validator \
+ --moniker "New Moniker" \
+ --website "https://example.com" \
+ --from validator \
+ --chain-id mychain-1
+
+# Check validator info
+yourchain query staking validator $(yourchain keys show validator --bech val -a)
+
+# Check signing info
+yourchain query slashing signing-info $(yourchain comet show-validator)
+```
+
+
+
+## File Locations
+
+### Configuration Files
+
+| File | Location | Purpose |
+|---|---|---|
+| **Genesis** | `~/.yourchain/config/genesis.json` | Genesis state |
+| **App Config** | `~/.yourchain/config/app.toml` | Application settings |
+| **CometBFT Config** | `~/.yourchain/config/config.toml` | Consensus settings |
+| **Client Config** | `~/.yourchain/config/client.toml` | Client settings |
+| **Validator Key** | `~/.yourchain/config/priv_validator_key.json` | Validator private key |
+| **Node Key** | `~/.yourchain/config/node_key.json` | P2P node key |
+| **Gentx** | `~/.yourchain/config/gentx/` | Genesis transactions |
+
+
+
+### Source Code Files
+
+| File | Location | Purpose |
+|---|---|---|
+| **Bech32 Prefix** | `config/config.go:62` | Address prefix |
+| **BIP44 Coin Type** | `crypto/hd/hdpath.go:9` | HD wallet path |
+| **EVM Chain ID** | `config/config.go:78` | EIP-155 chain ID |
+| **Default Denoms** | `x/vm/types/params.go:21-25` | EVM module defaults |
+| **Constants** | `config/constants.go:5-8` | Example chain values |
+| **App Template** | `server/config/migration/v0.50-app.toml:11` | Config template |
+
+
+
+## Default Values
+
+### Pre-Genesis Defaults
+
+| Parameter | Default Value | File Location |
+|---|---|---|
+| Binary Name | `evmd` | Directory name |
+| Bech32 Prefix | `cosmos` | `config/config.go:62` |
+| BIP44 Coin Type | `60` (Ethereum) | `crypto/hd/hdpath.go:9` |
+| EVM Chain ID | `999888` | `config/config.go:78` |
+| Base Denom | `aatom` | `x/vm/types/params.go:21` |
+| Display Denom | `atom` | `x/vm/types/params.go:25` |
+
+
+
+### Genesis Defaults
+
+| Parameter | Default Value | Genesis Location |
+|---|---|---|
+| Cosmos Chain ID | (user-defined) | Root: `chain_id` |
+| Genesis Time | (auto-generated) | Root: `genesis_time` |
+| Base Fee | `1000000000` (1 gwei) | `app_state.feemarket.params.base_fee` |
+| Unbonding Time | `1814400s` (21 days) | `app_state.staking.params.unbonding_time` |
+| Max Validators | `100` | `app_state.staking.params.max_validators` |
+| Signed Blocks Window | `10000` | `app_state.slashing.params.signed_blocks_window` |
+| Min Signed | `0.500000000000000000` (50%) | `app_state.slashing.params.min_signed_per_window` |
+| Double-Sign Slash | `0.050000000000000000` (5%) | `app_state.slashing.params.slash_fraction_double_sign` |
+| Downtime Slash | `0.010000000000000000` (1%) | `app_state.slashing.params.slash_fraction_downtime` |
+| Voting Period | `172800s` (2 days) | `app_state.gov.params.voting_period` |
+| Quorum | `0.334` (33.4%) | `app_state.gov.params.quorum` |
+| Threshold | `0.5` (50%) | `app_state.gov.params.threshold` |
+
+
+
+### Runtime Defaults
+
+| Parameter | Default Value | File Location |
+|---|---|---|
+| Min Gas Prices | `0aatom` | `app.toml` |
+| JSON-RPC Address | `0.0.0.0:8545` | `app.toml: [json-rpc]` |
+| WebSocket Address | `0.0.0.0:8546` | `app.toml: [json-rpc]` |
+| P2P Port | `26656` | `config.toml: [p2p]` |
+| RPC Port | `26657` | `config.toml: [rpc]` |
+| Prometheus Port | `26660` | `config.toml: [instrumentation]` |
+| Mempool Price Limit | `1` wei | `app.toml: [evm.mempool]` |
+| Global Slots | `5120` | `app.toml: [evm.mempool]` |
+
+
+
+## Configuration Examples
+
+### Complete 18-Decimal Chain Setup
+
+
+```bash init-18-decimal.sh
+#!/bin/bash
+# Complete setup for 18-decimal EVM chain
+
+BINARY="yourchain"
+CHAIN_ID="mychain-1"
+DENOM="atoken"
+MONIKER="mynode"
+
+# Initialize
+$BINARY init $MONIKER --chain-id $CHAIN_ID
+
+GENESIS=~/.$BINARY/config/genesis.json
+
+# Configure denominations
+jq ".app_state.staking.params.bond_denom=\"$DENOM\"" $GENESIS > tmp && mv tmp $GENESIS
+jq ".app_state.mint.params.mint_denom=\"$DENOM\"" $GENESIS > tmp && mv tmp $GENESIS
+jq ".app_state.gov.params.min_deposit[0].denom=\"$DENOM\"" $GENESIS > tmp && mv tmp $GENESIS
+jq ".app_state.evm.params.evm_denom=\"$DENOM\"" $GENESIS > tmp && mv tmp $GENESIS
+
+# Bank metadata (18 decimals)
+jq ".app_state.bank.denom_metadata=[{
+ \"base\": \"$DENOM\",
+ \"display\": \"token\",
+ \"denom_units\": [
+ {\"denom\": \"$DENOM\", \"exponent\": 0},
+ {\"denom\": \"token\", \"exponent\": 18}
+ ],
+ \"name\": \"Token\",
+ \"symbol\": \"TKN\"
+}]" $GENESIS > tmp && mv tmp $GENESIS
+
+# Enable precompiles
+jq '.app_state.evm.params.active_static_precompiles=[
+ "0x0000000000000000000000000000000000000100",
+ "0x0000000000000000000000000000000000000400",
+ "0x0000000000000000000000000000000000000800",
+ "0x0000000000000000000000000000000000000804"
+]' $GENESIS > tmp && mv tmp $GENESIS
+
+# ERC20 native token
+jq '.app_state.erc20.native_precompiles=["0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE"]' $GENESIS > tmp && mv tmp $GENESIS
+jq '.app_state.erc20.token_pairs=[{
+ "erc20_address":"0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
+ "denom":"'$DENOM'",
+ "enabled":true,
+ "contract_owner":1
+}]' $GENESIS > tmp && mv tmp $GENESIS
+
+echo "Configuration complete!"
+$BINARY genesis validate
+```
+
+```toml app.toml
+# Minimum gas prices
+minimum-gas-prices = "1000000000atoken"
+
+[evm]
+evm-chain-id = 123456
+tracer = ""
+max-tx-gas-wanted = 0
+min-tip = 1000000000
+
+[evm.mempool]
+price-limit = 1
+price-bump = 10
+account-slots = 16
+global-slots = 5120
+account-queue = 64
+global-queue = 1024
+lifetime = "3h0m0s"
+
+[json-rpc]
+enable = true
+address = "0.0.0.0:8545"
+ws-address = "0.0.0.0:8546"
+api = ["eth", "net", "web3", "txpool"]
+gas-cap = 25000000
+allow-unprotected-txs = false
+```
+
+```toml config.toml
+[p2p]
+persistent_peers = "" # Add validator peers
+
+[consensus]
+timeout_commit = "5s"
+
+[instrumentation]
+prometheus = true
+prometheus_listen_addr = ":26660"
+```
+
+
+
+
+### Complete 6-Decimal Chain Setup
+
+
+```bash init-6-decimal.sh
+#!/bin/bash
+# Complete setup for 6-decimal Cosmos chain (requires PreciseBank)
+
+BINARY="yourchain"
+CHAIN_ID="mychain-1"
+BASE_DENOM="utoken"
+EXTENDED_DENOM="atoken"
+MONIKER="mynode"
+
+# Initialize
+$BINARY init $MONIKER --chain-id $CHAIN_ID
+
+GENESIS=~/.$BINARY/config/genesis.json
+
+# Configure denominations
+jq ".app_state.staking.params.bond_denom=\"$BASE_DENOM\"" $GENESIS > tmp && mv tmp $GENESIS
+jq ".app_state.mint.params.mint_denom=\"$BASE_DENOM\"" $GENESIS > tmp && mv tmp $GENESIS
+jq ".app_state.gov.params.min_deposit[0].denom=\"$BASE_DENOM\"" $GENESIS > tmp && mv tmp $GENESIS
+jq ".app_state.evm.params.evm_denom=\"$BASE_DENOM\"" $GENESIS > tmp && mv tmp $GENESIS
+
+# Bank metadata (6 decimals)
+jq ".app_state.bank.denom_metadata=[{
+ \"base\": \"$BASE_DENOM\",
+ \"display\": \"token\",
+ \"denom_units\": [
+ {\"denom\": \"$BASE_DENOM\", \"exponent\": 0},
+ {\"denom\": \"token\", \"exponent\": 6}
+ ],
+ \"name\": \"Token\",
+ \"symbol\": \"TKN\"
+}]" $GENESIS > tmp && mv tmp $GENESIS
+
+# Extended denom for EVM (REQUIRED for 6 decimals)
+jq ".app_state.evm.params.extended_denom_options={
+ \"extended_denom\": \"$EXTENDED_DENOM\"
+}" $GENESIS > tmp && mv tmp $GENESIS
+
+echo "Configuration complete!"
+echo "IMPORTANT: Add precisebank module to app.go before building"
+$BINARY genesis validate
+```
+
+```go app.go
+// Add PreciseBank module to app.go
+
+import (
+ precisebankkeeper "github.com/cosmos/evm/x/precisebank/keeper"
+ precisebanktypes "github.com/cosmos/evm/x/precisebank/types"
+)
+
+// In app struct
+type App struct {
+ // ...
+ PreciseBankKeeper precisebankkeeper.Keeper
+}
+
+// Initialize keeper
+app.PreciseBankKeeper = precisebankkeeper.NewKeeper(
+ appCodec,
+ keys[precisebanktypes.StoreKey],
+ app.BankKeeper,
+ app.AccountKeeper,
+)
+
+// Add to module manager
+app.ModuleManager = module.NewManager(
+ // ...
+ precisebank.NewAppModule(app.PreciseBankKeeper, app.AccountKeeper),
+ // ...
+)
+
+// Use in EVM keeper
+app.EVMKeeper = evmkeeper.NewKeeper(
+ // ...
+ app.PreciseBankKeeper, // Not app.BankKeeper!
+ // ...
+)
+```
+
+
+
+
+### Local Development Setup
+
+The `local_node.sh` script in the Cosmos EVM repository demonstrates a complete local development setup.
+
+The script automates complete chain setup for local development:
+
+**1. Binary Installation:**
+- Builds and installs `evmd` binary
+- Supports debug builds with `--remote-debugging`
+
+**2. Chain Initialization:**
+- Runs `evmd init` with test moniker
+- Generates default genesis and config files
+
+**3. Genesis Modifications:**
+```bash expandable
+# Token denomination
+jq '.app_state.staking.params.bond_denom="atest"' genesis.json
+jq '.app_state.evm.params.evm_denom="atest"' genesis.json
+
+# Bank metadata (18 decimals)
+jq '.app_state.bank.denom_metadata=[{...}]' genesis.json
+
+# Enable all precompiles
+jq '.app_state.evm.params.active_static_precompiles=[...]' genesis.json
+
+# ERC20 native token
+jq '.app_state.erc20.token_pairs=[...]' genesis.json
+
+# Fast governance (for testing)
+sed -i 's/"voting_period": "172800s"/"voting_period": "30s"/' genesis.json
+```
+
+**4. Runtime Configuration:**
+```bash expandable
+# Fast consensus (app.toml)
+sed -i 's/timeout_commit = "5s"/timeout_commit = "1s"/' config.toml
+
+# Enable all APIs (app.toml)
+sed -i 's/enable = false/enable = true/' app.toml
+
+# Enable Prometheus
+sed -i 's/prometheus = false/prometheus = true/' config.toml
+```
+
+**5. Test Accounts:**
+- Creates dev accounts with known mnemonics
+- Funds accounts in genesis
+- Supports `--additional-users` for extra accounts
+
+**View the script:**
+```bash expandable
+cat local_node.sh | less
+```
+
+**Basic usage:**
+```bash expandable
+# Fresh start (overwrites existing chain)
+./local_node.sh -y
+
+# Resume from previous state
+./local_node.sh -n
+
+# Skip binary rebuild
+./local_node.sh -y --no-install
+
+# Create additional test accounts
+./local_node.sh -y --additional-users 5
+```
+
+**What it provides:**
+- Running local node
+- Pre-funded dev accounts
+- Fast block times (1 second)
+- Fast governance (30 second voting)
+- All APIs enabled
+- Prometheus metrics enabled
+
+**Use for:**
+- Local development
+- Contract testing
+- Integration tests
+- Learning chain configuration
+
+To use `local_node.sh` as a template:
+
+**1. Copy the script:**
+```bash expandable
+cp local_node.sh my_chain_setup.sh
+```
+
+**2. Update binary name:**
+```bash expandable
+# Change all instances of "evmd" to "yourchain"
+sed -i 's/evmd/yourchain/g' my_chain_setup.sh
+```
+
+**3. Modify genesis values:**
+- Update chain ID
+- Change token denomination
+- Adjust precompile selection
+- Modify staking/gov parameters
+
+**4. Adjust config settings:**
+- Production consensus timeouts
+- Restricted API namespaces
+- Security settings
+
+**5. Remove dev-specific features:**
+- Fast governance
+- Test account mnemonics
+- Allow unprotected transactions
+
+**Source**: [local_node.sh](https://github.com/cosmos/evm/blob/main/local_node.sh)
+
+
+
+## Additional Resources
+
+### Module Documentation
+
+
+
+EVM execution and configuration
+
+
+
+Token pairs and STRv2
+
+
+
+EIP-1559 dynamic fees
+
+
+
+Fractional balance tracking
+
+
+
+Cosmos SDK integration
+
+
+
+Complete build guide
+
+
+
+
+
+### Concept Documentation
+
+
+
+STRv2 unified token model
+
+
+
+Dynamic fee pricing
+
+
+
+Decimal bridging
+
+
+
+
+
+### External Resources
+
+- [Cosmos SDK Documentation](https://docs.cosmos.network) - General Cosmos SDK operations
+- [CometBFT Documentation](https://docs.cometbft.com) - Consensus engine details
+- [Ethereum JSON-RPC Specification](https://ethereum.org/en/developers/docs/apis/json-rpc/) - RPC API reference
+- [Cosmos EVM GitHub](https://github.com/cosmos/evm) - Source code and issues
+
+
+
+## Quick Search
+
+**Configuration task:** Use Ctrl+F or Cmd+F to search for:
+- Parameter names (e.g., `evm_denom`, `bond_denom`)
+- File locations (e.g., `app.toml`, `genesis.json`)
+- Commands (e.g., `add-genesis-account`, `collect-gentxs`)
+- Error messages (paste the error to find solution)
+
+**Navigation:**
+- [Pre-Genesis & Genesis Setup](/docs/evm/next/documentation/getting-started/build-a-chain/pre-genesis-and-genesis-setup) - Comprehensive configuration guide
+- [Runtime Configuration & Launch](/docs/evm/next/documentation/getting-started/build-a-chain/runtime-and-launch) - Network launch procedures
+
+
+
+This reference provides quick access to commands and defaults. For detailed explanations and step-by-step procedures, see the comprehensive configuration guides.
\ No newline at end of file
diff --git a/docs/evm/next/documentation/getting-started/build-a-chain/overview.mdx b/docs/evm/next/documentation/getting-started/build-a-chain/overview.mdx
index 156aebe4..7c8791eb 100644
--- a/docs/evm/next/documentation/getting-started/build-a-chain/overview.mdx
+++ b/docs/evm/next/documentation/getting-started/build-a-chain/overview.mdx
@@ -3,30 +3,110 @@ title: "Introduction"
description: "Everything you need to build your own custom blockchain with full EVM compatibility."
---
-## Quick Start
-
-
-
- Detailed guide with code examples and best practices
-
-
- Step-by-step checklist for configuring and launching your chain
-
-
-
-## What You'll Learn
-
-1. **Pre-Genesis Configuration** - Set up chain identity, token economics, and module selection before initialization
-2. **Genesis Configuration** - Configure all module parameters, enable precompiles, and set up the validator set
-3. **Runtime Configuration** - Configure JSON-RPC, EVM settings, and node-specific parameters
-4. **Network Launch** - Coordinate validator launch and monitor network health
-5. **Post-Launch Operations** - Manage upgrades and parameter changes via governance
-6. **Advanced Customization** - Add custom modules, predeployed contracts, and other advanced features
\ No newline at end of file
+Building a production-ready blockchain with Cosmos EVM involves configuring parameters across three main phases: pre-genesis setup, genesis configuration, and runtime deployment. This guide provides a structured approach to each phase.
+
+## Where To Start
+
+The Cosmos EVM repository includes `evmd`, a fully functional blockchain that integrates the Cosmos SDK with the EVM module. Because `evmd` is developed and maintained alongside the module itself, it serves as the canonical reference implementation with production-ready defaults and best practices.
+
+Starting with `evmd` provides several advantages:
+- **Greater compatibility** - Direct alignment with the module's development ensures the configurations as described here work as intended
+- **Improved troubleshooting** - Greater similarity to the base project makes it simpler to diagnose issues and find solutions, if they arise
+- **Proven logic** - Take advantage of integration approaches used by the core development team are readily available on Github
+- **Peace of mind** - Fully audited (as of v0.4.x)
+- **Developer Community** - Besides the advantage of being EVM compatible, Cosmos-EVM already powers multiople projects. With many more planning to migrate in the naer future, there is no shortage of experience and knowledge to draw from (and contribute to!)!
+
+Rather than assembling components from scratch, fork `evmd` and customize it for your specific needs. This approach lets you focus on what makes your chain unique rather than debugging basic integration issues.
+
+## Main Configuration Guides
+
+
+
+Complete guide to parameters set before and during initialization
+
+
+
+Configure your chain's identity and core parameters. This includes both source code customization and genesis file preparation.
+
+Compiled into your binary and set before running `init`:
+
+- [Binary Name](/docs/evm/next/documentation/getting-started/build-a-chain/pre-genesis-and-genesis-setup#binary-name) - Your chain's executable name
+- [Bech32 Address Prefix](/docs/evm/next/documentation/getting-started/build-a-chain/pre-genesis-and-genesis-setup#bech32-address-prefix) - Unique address format for your chain
+- [BIP44 Coin Type](/docs/evm/next/documentation/getting-started/build-a-chain/pre-genesis-and-genesis-setup#bip44-coin-type) - HD wallet derivation path
+- [EVM Chain ID](/docs/evm/next/documentation/getting-started/build-a-chain/pre-genesis-and-genesis-setup#evm-chain-id) - Ethereum replay protection identifier
+- [Token Decimal Precision](/docs/evm/next/documentation/getting-started/build-a-chain/pre-genesis-and-genesis-setup#token-decimal-precision) - Choose between 18 or 6 decimals
+- [Default Denomination](/docs/evm/next/documentation/getting-started/build-a-chain/pre-genesis-and-genesis-setup#default-denomination-in-source) - Base token name in source code
+
+Configured in `genesis.json` after initialization:
+
+- [Cosmos Chain ID](/docs/evm/next/documentation/getting-started/build-a-chain/pre-genesis-and-genesis-setup#cosmos-chain-id) - String identifier for your chain
+- [Genesis Time](/docs/evm/next/documentation/getting-started/build-a-chain/pre-genesis-and-genesis-setup#genesis-time) - Network launch timestamp
+- [Bank Metadata](/docs/evm/next/documentation/getting-started/build-a-chain/pre-genesis-and-genesis-setup#bank-denomination-metadata) - Token display configuration
+- [VM Parameters](/docs/evm/next/documentation/getting-started/build-a-chain/pre-genesis-and-genesis-setup#vm-parameters) - EVM gas token and execution settings
+- [Active Precompiles](/docs/evm/next/documentation/getting-started/build-a-chain/pre-genesis-and-genesis-setup#active-precompiles) - Enable Cosmos SDK access from smart contracts
+- [ERC20 Module](/docs/evm/next/documentation/getting-started/build-a-chain/pre-genesis-and-genesis-setup#erc20-module) - Native token representation
+- [Fee Market](/docs/evm/next/documentation/getting-started/build-a-chain/pre-genesis-and-genesis-setup#fee-market-eip-1559) - EIP-1559 configuration
+- [Staking, Slashing, Governance](/docs/evm/next/documentation/getting-started/build-a-chain/pre-genesis-and-genesis-setup#staking-parameters) - Validator economics and governance
+- [Initial Accounts](/docs/evm/next/documentation/getting-started/build-a-chain/pre-genesis-and-genesis-setup#initial-accounts-and-validators) - Genesis funding and validator setup
+
+
+
+
+
+Node configuration, network launch, and post-launch operations
+
+
+
+Set up node-level settings and coordinate network deployment.
+
+- [app.toml](/docs/evm/next/documentation/getting-started/build-a-chain/runtime-and-launch#apptoml-configuration) - Minimum gas prices, JSON-RPC endpoints, mempool settings
+- [config.toml](/docs/evm/next/documentation/getting-started/build-a-chain/runtime-and-launch#configtoml-configuration) - P2P networking, consensus parameters, RPC settings
+- [client.toml](/docs/evm/next/documentation/getting-started/build-a-chain/runtime-and-launch#clienttoml-configuration) - CLI defaults and broadcast mode
+
+- [Validator Coordination](/docs/evm/next/documentation/getting-started/build-a-chain/runtime-and-launch#network-launch-coordination) - Collecting gentxs and distributing final genesis
+- [Starting Your Node](/docs/evm/next/documentation/getting-started/build-a-chain/runtime-and-launch#starting-your-node) - Launch procedures and verification
+- [Post-Launch Operations](/docs/evm/next/documentation/getting-started/build-a-chain/runtime-and-launch#post-launch-operations) - Monitoring, upgrades, and maintenance
+
+
+
+## Additional Resources
+
+
+
+Quick reference for commands, defaults, and examples
+
+
+
+Command cheatsheet with complete setup examples for different configurations.
+
+
+
+## Advanced Configuration
+
+For specialized customization beyond the core configuration:
+
+
+
+Configure the EVM mempool for nonce gap handling and transaction prioritization
+
+
+
+
+
+Deploy standard contracts at genesis for Create2, Multicall3, Permit2, and Safe
+
+
+
+
+
+## Local Development Testing
+
+The `cosmos/evm` repository includes `local_node.sh`, a development script that streamlines testing by launching a private local testnet with practical defaults:
+
+```bash expandable
+./local_node.sh -y # Fresh start with clean state
+```
+
+This script demonstrates the complete initialization sequence and provides a working chain at `http://localhost:8545` that you can connect to with MetaMask or other Ethereum wallets using chain ID `262144`.
+
+For a detailed explanation of what this script does and how to customize it, see the [Configuration Reference](/docs/evm/next/documentation/getting-started/build-a-chain/configuration-reference#understanding-local_nodesh).
diff --git a/docs/evm/next/documentation/getting-started/build-a-chain/pre-genesis-and-genesis-setup.mdx b/docs/evm/next/documentation/getting-started/build-a-chain/pre-genesis-and-genesis-setup.mdx
new file mode 100644
index 00000000..382f01e9
--- /dev/null
+++ b/docs/evm/next/documentation/getting-started/build-a-chain/pre-genesis-and-genesis-setup.mdx
@@ -0,0 +1,2071 @@
+---
+title: "Pre-Genesis & Genesis Setup"
+description: "Complete guide to configuring your chain before and during genesis - from binary customization to genesis file preparation."
+---
+
+This guide covers all configuration steps from initial binary setup through genesis file preparation. Complete these steps before launching your network.
+
+
+**Related Documentation:**
+- [Runtime Configuration & Launch](/docs/evm/next/documentation/getting-started/build-a-chain/runtime-and-launch) - Network launch procedures
+- [Configuration Reference](/docs/evm/next/documentation/getting-started/build-a-chain/configuration-reference) - Commands, examples, and quick reference
+
+
+## Overview
+
+Building a Cosmos EVM chain involves two main configuration phases:
+
+1. **Pre-Genesis Setup** - Configure binary and source code before initialization
+2. **Genesis Configuration** - Set genesis parameters and prepare for network launch
+
+
+Most pre-genesis parameters cannot easily be changed after launch. Plan carefully.
+
+
+
+
+## Planning Your Configuration
+
+Before you begin, decide on these parameters. Use the links to jump to detailed configuration instructions for each item.
+
+### Pre-Genesis Parameters (Set Before `init`)
+
+These parameters are compiled into your binary and must be set before running `yourchain init`:
+
+
+
+
+**Default**: `evmd`
+**Common Practice**: `yourchain` (unique name for your project)
+
+
+
+**Default**: `cosmos`
+**Common Practice**: Unique prefix for your chain (e.g., `evmos`, `osmosis`)
+
+
+
+**Default**: `60` (Ethereum)
+**Common Practice**: `60` for EVM chains, or register unique value
+
+
+
+**Default**: `262144`
+**Common Practice**: Register unique integer at [chainlist.org](https://chainlist.org)
+
+
+
+**Default**: 18 decimals (EVM standard)
+**Common Practice**: 18 decimals (simpler), 6 decimals (Cosmos standard, requires PreciseBank)
+
+
+
+**Default**: `aatom` / `atom`
+**Common Practice**: Update to your token name before `init`
+
+
+
+
+### Genesis Parameters (Set After `init`)
+
+These parameters are configured in `genesis.json` after initialization:
+
+
+
+
+**Format**: String (e.g., `mychain-1`)
+**Common Practice**: `{name}-{version}` format
+
+
+
+**Format**: RFC3339 UTC timestamp
+**Common Practice**: Coordinated launch time for validators
+
+
+
+**Required**: Base denom, display denom, decimals
+**Common Practice**: Must match your chosen precision
+
+
+
+**Includes**: `evm_denom`, `extended_denom_options`, gas settings
+**Common Practice**: Configure EVM gas token and options
+
+
+
+**Default**: All enabled
+**Common Practice**: Enable only what you need or leave all enabled
+
+
+
+**Required**: Native token pair configuration
+**Common Practice**: Configure STRv2 native token representation
+
+
+
+**Default**: Enabled with 1 gwei base fee
+**Common Practice**: Standard EIP-1559 for EVM chains
+
+
+
+**Default**: Permissionless
+**Common Practice**: Permissionless for public chains
+
+
+
+**Includes**: Bond denom, unbonding time, max validators
+**Common Practice**: 21-day unbonding, 100+ validators
+
+
+
+**Includes**: Downtime window, slash fractions
+**Common Practice**: Cosmos defaults (5% double-sign, 0.01% downtime)
+
+
+
+**Includes**: Voting period, quorum, threshold
+**Common Practice**: 2-7 day voting period
+
+
+
+**Required**: Genesis accounts and gentx collection
+**Common Practice**: Fund accounts and collect validator gentxs
+
+
+
+
+
+
+## Pre-Genesis Setup
+
+Confirm these parameters before running `yourchain init`. These parameters are compiled into your binary, and determine how the genesis file is generated.
+
+### Binary Name
+
+**Description**: The name of your compiled blockchain executable.
+
+**Default**: `evmd`
+
+**File Location**: Directory name and all Go imports
+
+**Why Change It**: Brand your chain and avoid confusion with the reference implementation.
+
+
+
+```bash expandable
+# 1. Navigate to evm repository
+cd /path/to/evm
+
+# 2. Rename binary directory
+mv evmd yourchain
+
+# 3. Update all Go imports
+find . -type f -name "*.go" -exec sed -i '' \
+ 's|github.com/cosmos/evm/evmd|github.com/your-org/your-chain/yourchain|g' {} \;
+
+# 4. Update go.mod module path
+# Edit go.mod manually to change:
+# From: module github.com/cosmos/evm
+# To: module github.com/your-org/your-chain
+
+# 5. Update Makefile
+sed -i '' 's/evmd/yourchain/g' Makefile
+
+# 6. Tidy and build
+go mod tidy
+make build
+
+# 7. Verify
+./build/yourchain version
+```
+
+
+
+**1. Rename the binary directory:**
+```bash expandable
+mv evmd yourchain
+```
+
+**2. Update Go imports in all `.go` files:**
+```bash expandable
+find . -type f -name "*.go" -exec sed -i '' \
+ 's|github.com/cosmos/evm/evmd|github.com/your-org/your-chain/yourchain|g' {} \;
+```
+
+**3. Update `go.mod` module declaration:**
+```go expandable
+// From:
+module github.com/cosmos/evm
+
+// To:
+module github.com/your-org/your-chain
+```
+
+**4. Update Makefile references:**
+```bash expandable
+sed -i '' 's/evmd/yourchain/g' Makefile
+```
+
+**5. Run go mod tidy:**
+```bash expandable
+go mod tidy
+```
+
+**6. Build and verify:**
+```bash expandable
+make build
+./build/yourchain version
+```
+
+
+
+The renaming process updates:
+
+**Directory Structure:**
+- `evmd/` → `yourchain/`
+- `evmd/cmd/evmd/` → `yourchain/cmd/yourchain/`
+
+**Go Import Paths:**
+```go expandable
+// Before
+import "github.com/cosmos/evm/evmd/cmd"
+
+// After
+import "github.com/your-org/your-chain/yourchain/cmd"
+```
+
+**Module Declaration:**
+```go expandable
+// go.mod before
+module github.com/cosmos/evm
+
+// go.mod after
+module github.com/your-org/your-chain
+```
+
+**Makefile:**
+```makefile
+# Before
+BINARY_NAME := evmd
+
+# After
+BINARY_NAME := yourchain
+```
+
+
+
+**Result**: Your binary will be named `yourchain` and all commands will use this name (e.g., `yourchain start`, `yourchain init`).
+
+
+
+### Bech32 Address Prefix
+
+**Description**: Your chain's address format (e.g., `cosmos1...`, `evmos1...`, `yourchain1...`).
+
+**Default**: `cosmos`
+
+**File Location**: [`config/config.go:62`](https://github.com/cosmos/evm/blob/main/config/config.go#L60-L74)
+
+**Why Change It**: Create unique, recognizable addresses for your chain.
+
+
+Must be changed **before** running `yourchain init`. Changing after genesis requires a hard fork.
+
+
+
+
+Edit `config/config.go` and change the `Bech32Prefix` constant:
+
+```go expandable
+const (
+ // Bech32Prefix defines the Bech32 prefix for your chain
+ Bech32Prefix = "yourchain" // Change this line
+ // Bech32PrefixAccAddr defines account addresses
+ Bech32PrefixAccAddr = Bech32Prefix
+ // Bech32PrefixAccPub defines account public keys
+ Bech32PrefixAccPub = Bech32Prefix + sdk.PrefixPublic
+ // Bech32PrefixValAddr defines validator operator addresses
+ Bech32PrefixValAddr = Bech32Prefix + sdk.PrefixValidator + sdk.PrefixOperator
+ // Bech32PrefixValPub defines validator operator public keys
+ Bech32PrefixValPub = Bech32Prefix + sdk.PrefixValidator + sdk.PrefixOperator + sdk.PrefixPublic
+ // Bech32PrefixConsAddr defines consensus node addresses
+ Bech32PrefixConsAddr = Bech32Prefix + sdk.PrefixValidator + sdk.PrefixConsensus
+ // Bech32PrefixConsPub defines consensus node public keys
+ Bech32PrefixConsPub = Bech32Prefix + sdk.PrefixValidator + sdk.PrefixConsensus + sdk.PrefixPublic
+)
+```
+
+**After changing, rebuild:**
+```bash expandable
+make build
+```
+
+
+
+Changing the prefix affects all address types:
+
+| Address Type | Prefix Pattern | Example |
+| --- | --- | --- |
+| **Account Address** | `yourchain` | `yourchain1abc123...` |
+| **Account PubKey** | `yourchainpub` | `yourchainpub1abc123...` |
+| **Validator Operator** | `yourchainvaloper` | `yourchainvaloper1abc123...` |
+| **Validator PubKey** | `yourchainvaloperpub` | `yourchainvaloperpub1abc123...` |
+| **Consensus Address** | `yourchainvalcons` | `yourchainvalcons1abc123...` |
+| **Consensus PubKey** | `yourchainvalconspub` | `yourchainvalconspub1abc123...` |
+
+All these are automatically derived from the base `Bech32Prefix`.
+
+
+
+After building with your new prefix, verify it works:
+
+```bash expandable
+# Initialize chain
+./build/yourchain init test --chain-id test-1
+
+# Create a test key
+./build/yourchain keys add testkey --keyring-backend test
+
+# Check address format
+./build/yourchain keys list --keyring-backend test
+```
+
+Expected output:
+```
+- address: yourchain1abc123...
+ name: testkey
+ pubkey: '{"@type":"/cosmos.crypto.secp256k1.PubKey",...}'
+ type: local
+```
+
+
+
+**Source**: [config/config.go:60-74](https://github.com/cosmos/evm/blob/main/config/config.go#L60-L74)
+
+
+
+### BIP44 Coin Type
+
+**Description**: The HD wallet derivation path for key generation according to [BIP-44](https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki).
+
+**Default**: `60` (Ethereum)
+
+**File Location**: [`crypto/hd/hdpath.go:9`](https://github.com/cosmos/evm/blob/main/crypto/hd/hdpath.go#L7-L13)
+
+**Why Change It**: For Cosmos SDK chains wanting non-Ethereum derivation paths, or to register a unique coin type.
+
+
+
+**For EVM-compatible chains, use the default:**
+
+```go expandable
+var (
+ // Bip44CoinType satisfies EIP84 for Ethereum compatibility
+ Bip44CoinType uint32 = 60
+)
+```
+
+**Benefits:**
+- Compatible with Ethereum wallets (MetaMask, Ledger, etc.)
+- Standard for EVM chains
+- No additional registration needed
+
+**Derivation Path:** `m/44'/60'/0'/0/0`
+
+**Recommendation:** Keep `60` for EVM chains unless you have specific requirements.
+
+
+
+**To register a unique coin type:**
+
+1. **Check [SLIP-0044 registry](https://github.com/satoshilabs/slips/blob/master/slip-0044.md)** for available numbers
+
+2. **Submit a PR** to register your chain's coin type
+
+3. **Update the code** in `crypto/hd/hdpath.go`:
+
+```go expandable
+var (
+ // Bip44CoinType for your chain
+ Bip44CoinType uint32 = 12345 // Your registered number
+
+ // BIP44HDPath with your coin type
+ BIP44HDPath = fmt.Sprintf("m/44'/%d'/0'/0/0", Bip44CoinType)
+)
+```
+
+4. **Rebuild the binary:**
+```bash expandable
+make build
+```
+
+**Note:** Custom coin types may not be supported by all wallets.
+
+
+
+| Coin Type | Chain | Purpose |
+| --- | --- | --- |
+| `60` | Ethereum | **EVM chains (recommended)** |
+| `118` | Cosmos Hub | Traditional Cosmos chains |
+| `330` | Terra | Terra ecosystem |
+| `529` | Secret Network | Secret Network |
+| `852` | Desmos | Desmos Network |
+
+**For new EVM chains:** Use `60` for maximum compatibility.
+
+**For new Cosmos chains:** Register a unique value via SLIP-0044.
+
+
+
+**Source**: [crypto/hd/hdpath.go:7-13](https://github.com/cosmos/evm/blob/main/crypto/hd/hdpath.go#L7-L13)
+
+
+
+### EVM Chain ID
+
+**Description**: The EIP-155 chain ID used for Ethereum transaction replay protection.
+
+**Default**: `262144`
+
+**File Location**: [`config/config.go:78`](https://github.com/cosmos/evm/blob/main/config/config.go#L78)
+
+**Why Change It**: Must be unique for your network to prevent transaction replay attacks.
+
+
+The EVM Chain ID must be set in source code **before building your binary**. It cannot be changed after your binary is built, as it's compiled into the chain configuration. Choose carefully before building.
+
+
+
+
+**1. Edit `config/config.go` and change the `EVMChainID` constant:**
+
+```go expandable
+const (
+ // ... other constants ...
+
+ // EVMChainID defines the EIP-155 replay-protection chain id for the current ethereum chain config.
+ EVMChainID = 123456 // Change from 262144 to your unique chain ID
+)
+```
+
+**2. Rebuild the binary:**
+```bash expandable
+make build
+```
+
+**3. Initialize your chain:**
+```bash expandable
+./build/yourchain init mynode --chain-id mychain-1
+```
+
+**4. Verify the chain ID was set correctly:**
+```bash expandable
+grep 'evm-chain-id' ~/.yourchain/config/app.toml
+# Should show: evm-chain-id = 123456
+```
+
+
+Do not edit `app.toml` to change the EVM chain ID after initialization. The chain ID must be set in source code before building. Editing app.toml will not properly configure the chain.
+
+
+
+
+**Requirements:**
+- Must be a unique integer
+- Not already registered on [chainlist.org](https://chainlist.org)
+- Cannot conflict with major networks
+
+**Reserved IDs (Do Not Use):**
+- `1` - Ethereum Mainnet
+- `137` - Polygon
+- `56` - BNB Chain
+- `43114` - Avalanche C-Chain
+- `10` - Optimism
+- `42161` - Arbitrum One
+
+**Recommended Approach:**
+1. Visit [chainlist.org](https://chainlist.org)
+2. Search for an unused ID
+3. For production mainnets, register your ID
+4. For testnets/devnets, use any high number (e.g., 900000+)
+
+**Common Ranges:**
+- `1-999`: Reserved for major networks
+- `1000-99999`: Public production chains
+- `100000+`: Private/test networks or application-specific chains
+
+
+
+The EVM Chain ID is used for:
+
+**Transaction Signing:**
+```javascript expandable
+// EIP-155 transaction signature includes chain ID
+const tx = {
+ chainId: 123456, // Your EVM Chain ID
+ nonce: 0,
+ gasPrice: 1000000000,
+ gasLimit: 21000,
+ to: '0x...',
+ value: 0,
+ data: '0x'
+}
+```
+
+**Wallet Configuration:**
+```javascript expandable
+// MetaMask network configuration
+{
+ chainId: '0x1E240', // 123456 in hex
+ chainName: 'My Chain',
+ rpcUrls: ['http://localhost:8545'],
+ nativeCurrency: {
+ name: 'Token',
+ symbol: 'TKN',
+ decimals: 18
+ }
+}
+```
+
+**Replay Protection:**
+- Transactions signed for chain `123456` cannot be replayed on other chains
+- Essential security feature of EIP-155
+
+
+
+**Source**: [config/config.go:78](https://github.com/cosmos/evm/blob/main/config/config.go#L78)
+
+
+
+### Token Decimal Precision
+
+**Description**: Determines whether your native token uses 18 decimals (like ETH) or another precision (like ATOM's 6 decimals).
+
+**Default**: 18 decimals
+
+**Why Choose**: Affects EVM compatibility and module requirements.
+
+
+This decision affects your entire architecture and cannot be changed after genesis. Choose based on your compatibility needs.
+
+
+
+
+**Direct EVM Compatibility - Simplest Setup**
+
+**Configuration:**
+- Base denom: `atoken` (atto-prefix, 10^-18)
+- Display denom: `token`
+- Exponent: 18
+- **No additional modules required**
+
+**Benefits:**
+- Native 1:1 EVM compatibility
+- Uses standard `x/bank` module
+- Simpler architecture
+- No precision conversion needed
+- Standard for EVM ecosystems
+
+**Example:**
+```
+1 token = 1,000,000,000,000,000,000 atoken
+ = 10^18 atoken
+```
+
+**In Genesis:**
+```json expandable
+{
+ "app_state": {
+ "bank": {
+ "denom_metadata": [{
+ "base": "atoken",
+ "display": "token",
+ "denom_units": [
+ {"denom": "atoken", "exponent": 0},
+ {"denom": "token", "exponent": 18}
+ ]
+ }]
+ },
+ "evm": {
+ "params": {
+ "evm_denom": "atoken"
+ // No extended_denom_options needed
+ }
+ }
+ }
+}
+```
+
+✅ **Recommended for new EVM chains**
+
+
+
+**Cosmos SDK Standard - Requires PreciseBank Module**
+
+**Configuration:**
+- Base denom: `utoken` (micro-prefix, 10^-6)
+- Display denom: `token`
+- Exponent: 6
+- **Requires `x/precisebank` module**
+- **Requires `extended_denom_options` in genesis**
+
+**Example:**
+```
+1 token = 1,000,000 utoken
+ = 10^6 utoken
+```
+
+**Additional Setup Required:**
+
+1. **Add PreciseBank to `app.go`:**
+```go expandable
+import (
+ precisebankkeeper "github.com/cosmos/evm/x/precisebank/keeper"
+ precisebanktypes "github.com/cosmos/evm/x/precisebank/types"
+)
+
+// Initialize keeper
+app.PreciseBankKeeper = precisebankkeeper.NewKeeper(
+ appCodec,
+ keys[precisebanktypes.StoreKey],
+ app.BankKeeper,
+ app.AccountKeeper,
+)
+
+// Add to module manager
+app.ModuleManager = module.NewManager(
+ // ...
+ precisebank.NewAppModule(app.PreciseBankKeeper, app.AccountKeeper),
+ // ...
+)
+```
+
+2. **Configure Extended Denom in Genesis:**
+```json expandable
+{
+ "app_state": {
+ "bank": {
+ "denom_metadata": [{
+ "base": "utoken",
+ "display": "token",
+ "denom_units": [
+ {"denom": "utoken", "exponent": 0},
+ {"denom": "token", "exponent": 6}
+ ]
+ }]
+ },
+ "evm": {
+ "params": {
+ "evm_denom": "utoken",
+ "extended_denom_options": {
+ "extended_denom": "atoken" // 18-decimal EVM representation
+ }
+ }
+ }
+ }
+}
+```
+
+**How It Works:**
+- Cosmos SDK sees: `utoken` (6 decimals)
+- EVM sees: `atoken` (18 decimals)
+- PreciseBank handles conversion: `1 utoken = 10^12 wei`
+
+⚠️ **More complex but maintains Cosmos compatibility**
+
+
+
+| Prefix | Decimals | Example Denom | Conversion | Used By |
+| --- | --- | --- | --- | --- |
+| `a` (atto) | 18 | `atoken` | 1 token = 10^18 atoken | **EVM chains** |
+| `u` (micro) | 6 | `uatom`, `ustake` | 1 token = 10^6 utoken | Cosmos Hub, most Cosmos chains |
+| `n` (nano) | 9 | `ntoken` | 1 token = 10^9 ntoken | Some chains |
+| `p` (pico) | 12 | `ptoken` | 1 token = 10^12 ptoken | Rare |
+| `m` (milli) | 3 | `mtoken` | 1 token = 10^3 mtoken | Rare |
+| Base | 0-8 | `sats` | 1 BTC = 10^8 sats | Bitcoin-style |
+
+**For new chains:**
+- EVM-focused → Use `a` prefix (18 decimals)
+- Cosmos-focused → Use `u` prefix (6 decimals) + PreciseBank
+
+
+
+**Further Reading:**
+- [Precision Handling Concepts](/docs/evm/next/documentation/concepts/precision-handling)
+- [PreciseBank Module Reference](/docs/evm/next/documentation/cosmos-sdk/modules/precisebank)
+
+
+
+### Default Denomination in Source
+
+**Description**: Default token denominations hardcoded in source files that are used when generating configuration files.
+
+**Default**: `aatom` / `atom`
+
+**Why Change It**: So that generated config files use your token name instead of the default.
+
+
+This step must be completed **before** running `yourchain init`. The defaults are compiled into the binary and written to generated files during initialization.
+
+
+
+
+**Three source files contain default denomination values:**
+
+**1. Server Configuration Template**
+**File**: [`server/config/migration/v0.50-app.toml:11`](https://github.com/cosmos/evm/blob/main/server/config/migration/v0.50-app.toml#L11)
+
+**Change:**
+```toml expandable
+# From:
+minimum-gas-prices = "0aatom"
+
+# To:
+minimum-gas-prices = "0atoken"
+```
+
+**2. EVM Module Defaults**
+**File**: [`x/vm/types/params.go:21-25`](https://github.com/cosmos/evm/blob/main/x/vm/types/params.go#L21-L25)
+
+**Change:**
+```go expandable
+// From:
+var (
+ DefaultEVMDenom = "uatom"
+ DefaultEVMExtendedDenom = "aatom"
+ DefaultEVMDisplayDenom = "atom"
+)
+
+// To:
+var (
+ DefaultEVMDenom = "atoken" // Your base denom
+ DefaultEVMExtendedDenom = "atoken" // Same if 18 decimals
+ DefaultEVMDisplayDenom = "token" // Display name
+)
+```
+
+**3. Example Chain Constants**
+**File**: [`config/constants.go:5-8`](https://github.com/cosmos/evm/blob/main/config/constants.go#L5-L8)
+
+**Change:**
+```go expandable
+// From:
+const (
+ ExampleChainDenom = "aatom"
+ ExampleDisplayDenom = "atom"
+)
+
+// To:
+const (
+ ExampleChainDenom = "atoken"
+ ExampleDisplayDenom = "token"
+)
+```
+
+
+
+**For 18-decimal tokens (recommended):**
+
+```bash expandable
+# 1. Update server config template
+sed -i '' 's/minimum-gas-prices = "0aatom"/minimum-gas-prices = "0atoken"/' \
+ server/config/migration/v0.50-app.toml
+
+# 2. Update EVM module defaults (requires manual edit)
+# Open x/vm/types/params.go and change lines 21-25:
+# DefaultEVMDenom = "atoken"
+# DefaultEVMExtendedDenom = "atoken"
+# DefaultEVMDisplayDenom = "token"
+
+# 3. Update example constants (requires manual edit)
+# Open config/constants.go and change lines 5-8:
+# ExampleChainDenom = "atoken"
+# ExampleDisplayDenom = "token"
+
+# 4. Rebuild binary
+make build
+
+# 5. Initialize and verify
+./build/yourchain init testnode --chain-id test-1
+grep "minimum-gas-prices" ~/.yourchain/config/app.toml
+# Should show: minimum-gas-prices = "0atoken"
+```
+
+**For 6-decimal tokens (Cosmos standard):**
+
+```bash expandable
+# Update the same files but use "utoken" instead:
+# DefaultEVMDenom = "utoken"
+# DefaultEVMExtendedDenom = "atoken" # Still needs extended for EVM
+# DefaultEVMDisplayDenom = "token"
+```
+
+
+
+After making changes and rebuilding:
+
+```bash expandable
+# 1. Initialize chain
+./build/yourchain init testnode --chain-id test-1 --home /tmp/test-home
+
+# 2. Verify app.toml
+grep "minimum-gas-prices" /tmp/test-home/config/app.toml
+# Expected: minimum-gas-prices = "0atoken"
+
+# 3. Verify genesis.json
+jq '.app_state.evm.params.evm_denom' /tmp/test-home/config/genesis.json
+# Expected: "atoken"
+
+# 4. Clean up test
+rm -rf /tmp/test-home
+```
+
+If verification succeeds, your defaults are correctly configured.
+
+
+
+**Token Denomination Guidelines:**
+
+**For 18-decimal tokens:**
+- Base denom: `atoken` (atto-token)
+- Display denom: `token`
+- Example: `1 token = 1,000,000,000,000,000,000 atoken`
+
+**For 6-decimal tokens:**
+- Base denom: `utoken` (micro-token)
+- Display denom: `token`
+- Extended denom: `atoken` (for EVM)
+- Example: `1 token = 1,000,000 utoken`
+
+**Source References:**
+- [server/config/migration/v0.50-app.toml:11](https://github.com/cosmos/evm/blob/main/server/config/migration/v0.50-app.toml#L11)
+- [x/vm/types/params.go:21-25](https://github.com/cosmos/evm/blob/main/x/vm/types/params.go#L21-L25)
+- [config/constants.go:5-8](https://github.com/cosmos/evm/blob/main/config/constants.go#L5-L8)
+
+
+
+## Genesis Configuration
+
+After completing Pre-Genesis Setup and running `yourchain init`, configure your genesis file. The genesis file is located at `~/.yourchain/config/genesis.json`.
+
+
+Genesis parameters can be modified until you distribute the genesis file to validators. After the network launches, most parameters can only be changed through governance proposals.
+
+
+### Initialize Your Chain
+
+First, initialize the chain to create the default genesis file:
+
+```bash expandable
+yourchain init --chain-id
+```
+
+Example:
+```bash expandable
+yourchain init mynode --chain-id mychain-1
+```
+
+This creates:
+- `~/.yourchain/config/genesis.json` - Genesis state file
+- `~/.yourchain/config/app.toml` - Application configuration
+- `~/.yourchain/config/config.toml` - CometBFT configuration
+- `~/.yourchain/config/client.toml` - Client configuration
+
+Now proceed with genesis configuration below.
+
+
+
+### Cosmos Chain ID
+
+**Description**: The unique string identifier for your blockchain in the Cosmos ecosystem.
+
+**Format**: Flexible string, commonly `{name}-{version}`
+
+**Genesis Location**: Root-level field `chain_id`
+
+**Why Important**: Used for IBC connections, CometBFT consensus, and client identification.
+
+
+
+The Cosmos Chain ID is typically set during initialization:
+
+```bash expandable
+yourchain init mynode --chain-id mychain-1
+```
+
+This writes the chain ID to `genesis.json`. You must also set it in `client.toml`:
+
+```bash expandable
+yourchain config set client chain-id mychain-1
+```
+
+
+
+To change the chain ID after initialization:
+
+```bash expandable
+# Update genesis.json
+jq '.chain_id = "mychain-1"' ~/.yourchain/config/genesis.json > tmp && \
+ mv tmp ~/.yourchain/config/genesis.json
+
+# Update client.toml
+yourchain config set client chain-id mychain-1 --home ~/.yourchain
+```
+
+**Verify:**
+```bash expandable
+jq '.chain_id' ~/.yourchain/config/genesis.json
+grep 'chain-id' ~/.yourchain/config/client.toml
+```
+
+
+
+**Recommended Formats:**
+
+**Mainnet:**
+```
+mychain-1 # Initial mainnet
+mychain-2 # After major upgrade/hard fork
+mychain-3 # After another major upgrade
+```
+
+**Testnet:**
+```
+mychain-testnet-1
+mychain-testnet-2
+mychain-devnet-1
+```
+
+**Local Development:**
+```
+mychain-local
+test-1
+dev-1
+```
+
+**IBC Considerations:**
+- IBC clients reference the chain ID
+- Incrementing the version number (e.g., `-1` to `-2`) is the canonical way to upgrade IBC clients
+- The chain ID is part of the IBC client identifier
+
+**Flexibility:**
+- Chain ID can be any string
+- No strict format requirements
+- `{name}-{number}` is convention but not required
+
+
+
+**Important Notes:**
+- All validators must use the exact same chain ID
+- Chain ID is included in all transactions and blocks
+- Cannot be changed after genesis without coordinated upgrade
+
+
+
+### Genesis Time
+
+**Description**: UTC timestamp when the chain starts producing blocks.
+
+**Format**: RFC3339 timestamp (e.g., `"2024-12-01T00:00:00Z"`)
+
+**Genesis Location**: Root-level field `genesis_time`
+
+**Why Important**: Coordinates synchronized network launch across all validators.
+
+
+
+Set the genesis time to a future UTC timestamp:
+
+```bash expandable
+jq '.genesis_time = "2024-12-01T00:00:00Z"' ~/.yourchain/config/genesis.json > tmp && \
+ mv tmp ~/.yourchain/config/genesis.json
+```
+
+**Verify:**
+```bash expandable
+jq '.genesis_time' ~/.yourchain/config/genesis.json
+```
+
+
+
+**Launch Sequence:**
+
+1. **Coordinator sets genesis_time** to a future timestamp
+2. **Genesis file distributed** to all validators
+3. **Validators start nodes** before the genesis time
+4. **Nodes wait** until genesis_time is reached
+5. **Consensus begins** automatically at genesis_time
+
+**Validator Experience:**
+```bash expandable
+# Start node before genesis time
+yourchain start
+
+# Output while waiting:
+# Genesis time is in the future. Waiting...
+# Time until genesis: 29m 45s
+
+# At genesis time:
+# Starting consensus...
+# Producing block height=1
+```
+
+
+
+**Timing Recommendations:**
+- **Testnet**: 1-2 hours ahead (allows validator setup)
+- **Mainnet**: 24-48 hours ahead (allows thorough preparation)
+- **Local Dev**: Use past time (starts immediately)
+
+**Coordination:**
+1. Choose time that works across all validator timezones
+2. Communicate clearly to all validators
+3. Ensure all validators have genesis file with same time
+4. Have validators start 30-60 minutes early
+5. Monitor validator status before launch
+
+**Example Timeline:**
+```
+T-48h: Announce genesis time
+T-24h: Distribute final genesis file
+T-2h: Validators verify genesis hash
+T-1h: Validators start nodes
+T-0: Genesis time - network starts
+T+10m: Verify all validators online
+```
+
+
+
+**Important**: All validators must have identical `genesis_time` in their genesis files.
+
+
+
+### Bank Denomination Metadata
+
+**Description**: Your token's base denomination, decimal precision, and display properties.
+
+**Genesis Location**: `app_state.bank.denom_metadata`
+
+**Why Important**: Controls how tokens are displayed and handled across the chain.
+
+
+**Decimal Precision Decision**: Your choice of 18 vs 6 decimals (configured in [Token Decimal Precision](#token-decimal-precision)) determines the values below. See that section for detailed explanation.
+
+
+
+
+**Configure denomination metadata for your chosen precision:**
+
+```bash expandable
+# For 18-decimal tokens (base denom: atoken)
+jq '.app_state.bank.denom_metadata=[{
+ "description": "The native staking and gas token",
+ "denom_units": [
+ {"denom": "atoken", "exponent": 0, "aliases": ["attotoken"]},
+ {"denom": "token", "exponent": 18, "aliases": []}
+ ],
+ "base": "atoken",
+ "display": "token",
+ "name": "My Token",
+ "symbol": "TKN",
+ "uri": "",
+ "uri_hash": ""
+}]' ~/.yourchain/config/genesis.json > tmp && mv tmp ~/.yourchain/config/genesis.json
+
+# For 6-decimal tokens (base denom: utoken)
+# Change "atoken" → "utoken" and exponent: 18 → 6
+```
+
+**Fields:**
+- `base`: Smallest unit stored on-chain (must match staking bond_denom)
+- `display`: Human-readable unit
+- `exponent`: Decimal places (18 or 6 based on your choice)
+- `name`: Full token name displayed in wallets
+- `symbol`: Ticker symbol (e.g., `TKN`, `ATOM`, `ETH`)
+
+
+
+After configuration, verify all denoms match across modules:
+
+```bash expandable
+GENESIS=~/.yourchain/config/genesis.json
+
+# Check bank metadata base
+jq '.app_state.bank.denom_metadata[0].base' $GENESIS
+
+# Check staking bond denom
+jq '.app_state.staking.params.bond_denom' $GENESIS
+
+# Check mint denom
+jq '.app_state.mint.params.mint_denom' $GENESIS
+
+# Check EVM denom
+jq '.app_state.evm.params.evm_denom' $GENESIS
+
+# Check governance min deposit
+jq '.app_state.gov.params.min_deposit[0].denom' $GENESIS
+```
+
+**All should return the same denom** (e.g., `"atoken"` or `"utoken"`).
+
+
+
+**Critical**: The following must all use the same base denomination:
+- `app_state.bank.denom_metadata[0].base`
+- `app_state.staking.params.bond_denom`
+- `app_state.mint.params.mint_denom`
+- `app_state.evm.params.evm_denom`
+- `app_state.gov.params.min_deposit[0].denom`
+
+
+
+### VM Parameters
+
+**Description**: Core EVM module configuration including gas token, extended denom options, and chain behavior.
+
+**Genesis Location**: `app_state.evm.params`
+
+**Why Important**: Defines how the EVM layer interacts with Cosmos SDK.
+
+
+
+**Sets which bank denomination is used for EVM gas:**
+
+```bash expandable
+jq '.app_state.evm.params.evm_denom = "atoken"' \
+ ~/.yourchain/config/genesis.json > tmp && mv tmp ~/.yourchain/config/genesis.json
+```
+
+**Must match** your bank metadata base denomination.
+
+**Source**: [x/vm/types/params.go:21](https://github.com/cosmos/evm/blob/main/x/vm/types/params.go#L21)
+
+
+
+**Only required for 6-decimal chains** (see [Token Decimal Precision](#token-decimal-precision)):
+
+```bash expandable
+# Only needed if using 6 decimals with PreciseBank
+jq '.app_state.evm.params.extended_denom_options = {
+ "extended_denom": "atoken"
+}' ~/.yourchain/config/genesis.json > tmp && mv tmp ~/.yourchain/config/genesis.json
+```
+
+**When to configure:**
+- ✅ 6-decimal chains: Set `extended_denom` to enable EVM compatibility via PreciseBank
+- ❌ 18-decimal chains: Leave empty or omit entirely
+
+**Example configuration:**
+```json expandable
+{
+ "evm_denom": "utoken",
+ "extended_denom_options": {
+ "extended_denom": "atoken"
+ }
+}
+```
+
+**Source**: [x/vm/types/params.go:76](https://github.com/cosmos/evm/blob/main/x/vm/types/params.go#L76)
+
+
+
+**Controls how far back historical state queries can go:**
+
+```bash expandable
+jq '.app_state.evm.params.history_serve_window = 8192' \
+ ~/.yourchain/config/genesis.json > tmp && mv tmp ~/.yourchain/config/genesis.json
+```
+
+**Default**: `8192` blocks (matches EIP-2935)
+
+**Values:**
+- `0` = Unlimited (keep all historical state)
+- `8192` = ~18 hours at 8s blocks (recommended)
+- `86400` = ~8 days at 8s blocks
+
+**Trade-offs:**
+- Higher = More disk space, older state queries supported
+- Lower = Less disk space, limited historical queries
+- `0` = Maximum compatibility, growing disk usage
+
+**Source**: [x/vm/types/params.go:50](https://github.com/cosmos/evm/blob/main/x/vm/types/params.go#L50)
+
+
+
+**Enable additional Ethereum Improvement Proposals:**
+
+```bash expandable
+jq '.app_state.evm.params.extra_eips = []' \
+ ~/.yourchain/config/genesis.json > tmp && mv tmp ~/.yourchain/config/genesis.json
+```
+
+**Default**: `[]` (empty - use standard EVM feature set)
+
+**When to use:**
+- Most chains should leave empty
+- Add specific EIP numbers if you need features not in default config
+- Example: `[1153, 3855]` to enable specific EIPs
+
+**Note**: EIPs must be activatable - invalid EIPs cause validation failure.
+
+**Source**: [x/vm/types/params.go:33](https://github.com/cosmos/evm/blob/main/x/vm/types/params.go#L33)
+
+
+
+
+
+### Active Precompiles
+
+**Description**: Enabled precompiled contracts that expose Cosmos SDK functionality to EVM smart contracts.
+
+**Genesis Location**: `app_state.evm.params.active_static_precompiles`
+
+**Default**: Empty array (no precompiles enabled)
+
+
+**Learn More**: [Precompiles Overview](/docs/evm/next/documentation/smart-contracts/precompiles/overview) - Complete documentation with Solidity interfaces
+
+
+
+
+| Address | Name | Purpose |
+| --- | --- | --- |
+| `0x0100` | **P256** | Cryptographic operations for Web3 auth |
+| `0x0400` | **Bech32** | Cosmos ↔ Ethereum address conversion |
+| `0x0800` | **Staking** | Validator staking operations |
+| `0x0801` | **Distribution** | Reward distribution and claiming |
+| `0x0802` | **ICS20** | IBC token transfers |
+| `0x0803` | **Vesting** | Token vesting operations |
+| `0x0804` | **Bank** | Bank module operations |
+| `0x0805` | **Governance** | Submit/vote on proposals |
+| `0x0806` | **Slashing** | Slashing queries |
+| `0x0807` | **Authz** | Authorization grants |
+
+
+
+**Enable all precompiles for maximum Cosmos SDK integration:**
+
+```bash expandable
+jq '.app_state.evm.params.active_static_precompiles = [
+ "0x0000000000000000000000000000000000000100",
+ "0x0000000000000000000000000000000000000400",
+ "0x0000000000000000000000000000000000000800",
+ "0x0000000000000000000000000000000000000801",
+ "0x0000000000000000000000000000000000000802",
+ "0x0000000000000000000000000000000000000803",
+ "0x0000000000000000000000000000000000000804",
+ "0x0000000000000000000000000000000000000805",
+ "0x0000000000000000000000000000000000000806",
+ "0x0000000000000000000000000000000000000807"
+]' ~/.yourchain/config/genesis.json > tmp && mv tmp ~/.yourchain/config/genesis.json
+```
+
+**Use case**: Full-featured chains with rich Cosmos SDK integration
+
+
+
+**Enable only specific precompiles:**
+
+```bash expandable
+jq '.app_state.evm.params.active_static_precompiles = [
+ "0x0000000000000000000000000000000000000100",
+ "0x0000000000000000000000000000000000000400",
+ "0x0000000000000000000000000000000000000800",
+ "0x0000000000000000000000000000000000000804"
+]' ~/.yourchain/config/genesis.json > tmp && mv tmp ~/.yourchain/config/genesis.json
+```
+
+This example enables:
+- P256 (cryptography)
+- Bech32 (address conversion)
+- Staking
+- Bank
+
+**Use case**: Minimal attack surface, enable only what you need
+
+
+
+**Pure EVM chain with no Cosmos SDK integration:**
+
+```bash expandable
+jq '.app_state.evm.params.active_static_precompiles = []' \
+ ~/.yourchain/config/genesis.json > tmp && mv tmp ~/.yourchain/config/genesis.json
+```
+
+**Use case**: Standard EVM chain without Cosmos features
+
+
+
+**Important**: The array must be sorted in ascending order for determinism.
+
+**Can be changed**: Precompiles can be enabled/disabled after genesis through governance proposals.
+
+**Source**: [x/vm/types/precompiles.go:22-32](https://github.com/cosmos/evm/blob/main/x/vm/types/precompiles.go#L22-L32)
+
+
+
+### ERC20 Module
+
+**Description**: Configured token pairs between Cosmos bank denoms and ERC20 representations, implementing Single Token Representation v2 (STRv2).
+
+**Genesis Location**: `app_state.erc20`
+
+**Why Important**: Allows native tokens to be used in EVM contracts as ERC20.
+
+
+**Learn More**:
+- [Single Token Representation Concepts](/docs/evm/next/documentation/concepts/single-token-representation)
+- [ERC20 Module Reference](/docs/evm/next/documentation/cosmos-sdk/modules/erc20)
+
+
+
+
+**Configure the native token's ERC20 representation:**
+
+```bash expandable
+# Set native precompile address
+jq '.app_state.erc20.native_precompiles = ["0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE"]' \
+ ~/.yourchain/config/genesis.json > tmp && mv tmp ~/.yourchain/config/genesis.json
+
+# Set token pair
+jq '.app_state.erc20.token_pairs = [{
+ "erc20_address": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
+ "denom": "atoken",
+ "enabled": true,
+ "contract_owner": 1
+}]' ~/.yourchain/config/genesis.json > tmp && mv tmp ~/.yourchain/config/genesis.json
+```
+
+**Fields:**
+- `erc20_address`: Special address `0xEeeee...EEeE` for native token
+- `denom`: Your base denomination (must match bank metadata)
+- `enabled`: Whether the pair is active
+- `contract_owner`: `1` = module-owned (standard for native token)
+
+
+
+**Control who can register new token pairs:**
+
+```bash expandable
+# Permissionless (anyone can register)
+jq '.app_state.erc20.params.permissionless_registration = true' \
+ ~/.yourchain/config/genesis.json > tmp && mv tmp ~/.yourchain/config/genesis.json
+
+# Permissioned (governance only)
+jq '.app_state.erc20.params.permissionless_registration = false' \
+ ~/.yourchain/config/genesis.json > tmp && mv tmp ~/.yourchain/config/genesis.json
+```
+
+**When to use each:**
+- `true`: Public chains, DeFi-focused ecosystems
+- `false`: Enterprise chains, controlled environments
+
+**Can be changed**: Via governance after genesis
+
+**Source**: [x/erc20/types/params.go:27](https://github.com/cosmos/evm/blob/main/x/erc20/types/params.go#L27)
+
+
+
+```json expandable
+{
+ "app_state": {
+ "erc20": {
+ "native_precompiles": [
+ "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE"
+ ],
+ "token_pairs": [
+ {
+ "erc20_address": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
+ "denom": "atoken",
+ "enabled": true,
+ "contract_owner": 1
+ }
+ ],
+ "params": {
+ "permissionless_registration": true
+ }
+ }
+ }
+}
+```
+
+**Result**: Native token becomes accessible as ERC20 from Solidity contracts using the special address `0xEeeee...EEeE`.
+
+
+
+
+
+### Fee Market (EIP-1559)
+
+**Description**: Dynamic fee pricing mechanism based on EIP-1559, controlling how transaction fees adjust based on network congestion.
+
+**Genesis Location**: `app_state.feemarket.params`
+
+**Default**: EIP-1559 enabled with 1 gwei base fee
+
+
+**Learn More**:
+- [EIP-1559 Fee Market Concepts](/docs/evm/next/documentation/concepts/eip-1559-feemarket)
+- [FeeMarket Module Reference](/docs/evm/next/documentation/cosmos-sdk/modules/feemarket)
+
+
+
+
+```bash expandable
+jq '.app_state.feemarket.params = {
+ "no_base_fee": false,
+ "base_fee": "1000000000",
+ "base_fee_change_denominator": 8,
+ "elasticity_multiplier": 2,
+ "min_gas_price": "0",
+ "min_gas_multiplier": "0.5",
+ "enable_height": 0
+}' ~/.yourchain/config/genesis.json > tmp && mv tmp ~/.yourchain/config/genesis.json
+```
+
+**Parameters:**
+- `no_base_fee`: `false` = EIP-1559 enabled
+- `base_fee`: `"1000000000"` = 1 gwei initial base fee
+- `base_fee_change_denominator`: `8` = ±12.5% max change per block
+- `elasticity_multiplier`: `2` = target is 50% of max gas
+- `min_gas_price`: `"0"` = no minimum floor
+- `min_gas_multiplier`: `"0.5"` = 50% of base fee minimum
+- `enable_height`: `0` = enabled from genesis
+
+**Use case**: Standard Ethereum-compatible chains
+
+
+
+```bash expandable
+jq '.app_state.feemarket.params = {
+ "no_base_fee": true,
+ "min_gas_price": "1000000000"
+}' ~/.yourchain/config/genesis.json > tmp && mv tmp ~/.yourchain/config/genesis.json
+```
+
+**Parameters:**
+- `no_base_fee`: `true` = Disable EIP-1559
+- `min_gas_price`: Fixed minimum gas price in wei
+
+**Use case**: Traditional Cosmos chains or simple testing
+
+
+
+**1. `base_fee`** (string, wei)
+- Initial base fee per gas
+- `"1000000000"` = 1 gwei (Ethereum standard)
+- `"100000000"` = 0.1 gwei (lower fee chains)
+- `"10000000000"` = 10 gwei (higher fee chains)
+
+**2. `base_fee_change_denominator`** (uint32)
+- Controls adjustment speed
+- `8` = ±12.5% max change per block (Ethereum standard)
+- `50` = ±2% max change (slower adjustment)
+- Lower = faster price adjustment
+
+**3. `elasticity_multiplier`** (uint32)
+- Determines gas target
+- `2` = target is 50% of max gas (standard)
+- Block above target → base fee increases
+- Block below target → base fee decreases
+
+**4. `min_gas_price`** (string, wei)
+- Network-wide minimum floor
+- `"0"` = no floor (standard)
+- `"500000000"` = 0.5 gwei minimum
+
+**5. `min_gas_multiplier`** (string, decimal)
+- Fraction of base fee for minimum
+- `"0.5"` = 50% of base fee (standard)
+- Must be between 0 and 1
+
+**6. `enable_height`** (int64)
+- Block height to activate EIP-1559
+- `0` = enabled from genesis
+- `> 0` = activate at specific height
+
+
+
+**Source**: [x/feemarket/types/params.go:13-21](https://github.com/cosmos/evm/blob/main/x/feemarket/types/params.go#L13-L21)
+
+
+
+### EVM Access Control
+
+**Description**: Permissions for deploying and calling smart contracts.
+
+**Genesis Location**: `app_state.evm.params.access_control`
+
+**Default**: Permissionless (anyone can deploy and call contracts)
+
+
+
+```bash expandable
+jq '.app_state.evm.params.access_control = {
+ "create": {
+ "access_type": 0,
+ "access_control_list": []
+ },
+ "call": {
+ "access_type": 0,
+ "access_control_list": []
+ }
+}' ~/.yourchain/config/genesis.json > tmp && mv tmp ~/.yourchain/config/genesis.json
+```
+
+**Access Type** `0` = PERMISSIONLESS
+
+**Use case**: Public chains, testnets, open ecosystems
+
+
+
+```bash expandable
+jq '.app_state.evm.params.access_control = {
+ "create": {
+ "access_type": 2,
+ "access_control_list": [
+ "0x1234567890123456789012345678901234567890",
+ "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd"
+ ]
+ },
+ "call": {
+ "access_type": 0,
+ "access_control_list": []
+ }
+}' ~/.yourchain/config/genesis.json > tmp && mv tmp ~/.yourchain/config/genesis.json
+```
+
+**Access Type** `2` = PERMISSIONED (allowlist)
+
+**Use case**: Enterprise chains, controlled deployment
+
+
+
+```bash expandable
+jq '.app_state.evm.params.access_control.create = {
+ "access_type": 1,
+ "access_control_list": [
+ "0xbadaddr1234567890123456789012345678901234"
+ ]
+}' ~/.yourchain/config/genesis.json > tmp && mv tmp ~/.yourchain/config/genesis.json
+```
+
+**Access Type** `1` = RESTRICTED (blocklist)
+
+**Use case**: Block known malicious addresses while keeping chain open
+
+
+
+| Type | Value | Behavior | List Usage |
+| --- | --- | --- | --- |
+| **Permissionless** | `0` | Anyone can perform action | Ignored |
+| **Restricted** | `1` | Block addresses in list | Blocklist |
+| **Permissioned** | `2` | Only addresses in list | Allowlist |
+
+**Separate controls:**
+- `create`: Who can deploy contracts
+- `call`: Who can call contracts
+
+**Can be changed**: Via governance proposals after genesis
+
+
+
+**Source**: [x/vm/types/params.go:160-165](https://github.com/cosmos/evm/blob/main/x/vm/types/params.go#L160-L165)
+
+
+
+### Staking Parameters
+
+**Description**: Staking module behavior, including bond denom, unbonding time, and validator set size.
+
+**Genesis Location**: `app_state.staking.params`
+
+
+
+```bash expandable
+# Set bond denomination
+jq '.app_state.staking.params.bond_denom = "atoken"' \
+ ~/.yourchain/config/genesis.json > tmp && mv tmp ~/.yourchain/config/genesis.json
+
+# Set unbonding time (21 days is Cosmos standard)
+jq '.app_state.staking.params.unbonding_time = "1814400s"' \
+ ~/.yourchain/config/genesis.json > tmp && mv tmp ~/.yourchain/config/genesis.json
+
+# Set max validators
+jq '.app_state.staking.params.max_validators = 100' \
+ ~/.yourchain/config/genesis.json > tmp && mv tmp ~/.yourchain/config/genesis.json
+```
+
+
+
+**1. `bond_denom`** (string)
+- Must match your base denomination from bank metadata
+- Example: `"atoken"`
+
+**2. `unbonding_time`** (duration string)
+- How long tokens remain locked after unstaking
+- During this period, tokens can still be slashed
+- **Format**: Go duration (e.g., `"1814400s"` = 21 days)
+
+**Common values:**
+- `"120s"` = 2 minutes (testing)
+- `"86400s"` = 1 day
+- `"604800s"` = 7 days
+- `"1814400s"` = 21 days (Cosmos standard)
+- `"2419200s"` = 28 days
+
+**Security vs Usability**: Longer = more secure but less flexible for users
+
+**3. `max_validators`** (uint32)
+- Maximum validators in active set
+- Only top N by voting power participate in consensus
+- Common values: 50, 100, 125, 150, 175
+- Higher = more decentralized but potentially slower
+
+**4. `max_entries`** (uint32)
+- Max concurrent unbonding/redelegation operations per pair
+- Default: `7`
+- Prevents spam on unbonding queue
+
+**5. `historical_entries`** (uint32)
+- Number of historical validator sets to keep
+- Used for IBC light client verification
+- Default: `10000`
+- Higher = more storage, better IBC compatibility
+
+**6. `min_commission_rate`** (decimal string)
+- Minimum commission validators must charge
+- Default: `"0.000000000000000000"` (0%)
+- Example: `"0.050000000000000000"` = 5% minimum
+
+
+
+```json expandable
+{
+ "app_state": {
+ "staking": {
+ "params": {
+ "bond_denom": "atoken",
+ "unbonding_time": "1814400s",
+ "max_validators": 100,
+ "max_entries": 7,
+ "historical_entries": 10000,
+ "min_commission_rate": "0.000000000000000000"
+ }
+ }
+ }
+}
+```
+
+
+
+
+
+### Slashing Parameters
+
+**Description**: Thresholds and penalties for validator downtime or misbehavior.
+
+**Genesis Location**: `app_state.slashing.params`
+
+
+
+```bash expandable
+jq '.app_state.slashing.params = {
+ "signed_blocks_window": "10000",
+ "min_signed_per_window": "0.500000000000000000",
+ "downtime_jail_duration": "600s",
+ "slash_fraction_double_sign": "0.050000000000000000",
+ "slash_fraction_downtime": "0.010000000000000000"
+}' ~/.yourchain/config/genesis.json > tmp && mv tmp ~/.yourchain/config/genesis.json
+```
+
+**Cosmos Defaults:**
+- **Signed blocks window**: 10,000 blocks (~22 hours at 8s blocks)
+- **Min signed**: 50% of blocks in window
+- **Downtime jail**: 10 minutes
+- **Double-sign slash**: 5% of stake
+- **Downtime slash**: 1% of stake
+
+
+
+**1. `signed_blocks_window`** (int64)
+- Number of blocks to track validator liveness
+- Validator must sign `min_signed_per_window` within this window
+
+**Common values:**
+- `100` = ~13 minutes at 8s blocks
+- `10000` = ~22 hours (Cosmos standard)
+- `20000` = ~44 hours
+
+**2. `min_signed_per_window`** (decimal string)
+- Minimum fraction of blocks validator must sign
+- `"0.500000000000000000"` = 50% (standard)
+- Example: With window=10000, must sign ≥5000 blocks
+
+**3. `downtime_jail_duration`** (duration string)
+- How long validator is jailed for downtime
+- Jailed validators earn no rewards, must manually unjail
+
+**Common values:**
+- `"60s"` = 1 minute
+- `"600s"` = 10 minutes (Cosmos standard)
+- `"3600s"` = 1 hour
+- `"86400s"` = 1 day
+
+**4. `slash_fraction_double_sign`** (decimal string)
+- Percentage of stake slashed for double-signing
+- Validator is also permanently tombstoned (cannot rejoin)
+
+**Common values:**
+- `"0.050000000000000000"` = 5% (Cosmos standard)
+- `"0.100000000000000000"` = 10%
+- `"0.200000000000000000"` = 20%
+
+**5. `slash_fraction_downtime`** (decimal string)
+- Percentage slashed for downtime (less severe)
+
+**Common values:**
+- `"0.000100000000000000"` = 0.01%
+- `"0.010000000000000000"` = 1% (Cosmos standard)
+- `"0.050000000000000000"` = 5%
+
+
+
+**Downtime Detection:**
+1. Chain tracks last `signed_blocks_window` blocks
+2. If validator signs < `min_signed_per_window` fraction → jailed
+3. Validator loses `slash_fraction_downtime` of stake
+4. Must wait `downtime_jail_duration` then manually unjail
+
+**Double-Sign Detection:**
+1. Validator signs two blocks at same height → slashed
+2. Loses `slash_fraction_double_sign` of stake
+3. Permanently tombstoned - cannot ever rejoin
+
+**Relationship with Unbonding:**
+- Tokens remain slashable during entire `unbonding_time`
+- Validators accountable for misbehavior that occurred while bonded
+- Historical slashing enforced even after unbonding starts
+
+
+
+
+
+### Governance Parameters
+
+**Description**: Settings for on-chain governance including voting periods, quorum, and deposit requirements.
+
+**Genesis Location**: `app_state.gov.params`
+
+
+
+```bash expandable
+jq '.app_state.gov.params = {
+ "min_deposit": [{
+ "denom": "atoken",
+ "amount": "10000000000000000000"
+ }],
+ "max_deposit_period": "172800s",
+ "voting_period": "172800s",
+ "expedited_voting_period": "86400s",
+ "quorum": "0.334",
+ "threshold": "0.5",
+ "veto_threshold": "0.334",
+ "min_initial_deposit_ratio": "0.0",
+ "expedited_threshold": "0.667",
+ "expedited_min_deposit": [{
+ "denom": "atoken",
+ "amount": "50000000000000000000"
+ }]
+}' ~/.yourchain/config/genesis.json > tmp && mv tmp ~/.yourchain/config/genesis.json
+```
+
+
+
+**1. `min_deposit`**
+- Minimum tokens required to submit proposal
+- Example: `10 tokens` = `10000000000000000000 atoken` (18 decimals)
+
+**2. `max_deposit_period`** (duration)
+- Time to reach minimum deposit
+- `"172800s"` = 2 days (Cosmos standard)
+
+**3. `voting_period`** (duration)
+- Length of voting period
+- Common values:
+ - `"172800s"` = 2 days (Cosmos standard)
+ - `"604800s"` = 7 days
+
+**4. `expedited_voting_period`** (duration)
+- Shorter period for expedited proposals
+- **Must be < `voting_period`**
+- `"86400s"` = 1 day (standard)
+
+**5. `quorum`** (decimal)
+- Minimum participation required
+- `"0.334"` = 33.4% (standard)
+
+**6. `threshold`** (decimal)
+- Minimum yes votes to pass
+- `"0.5"` = 50% (standard)
+
+**7. `veto_threshold`** (decimal)
+- NoWithVeto threshold to reject
+- `"0.334"` = 33.4% (standard)
+
+**8. `expedited_threshold`** (decimal)
+- Higher threshold for expedited proposals
+- `"0.667"` = 66.7% (standard)
+
+
+
+**Set minimum deposit denom:**
+```bash expandable
+jq '.app_state.gov.params.min_deposit[0].denom = "atoken"' \
+ ~/.yourchain/config/genesis.json > tmp && mv tmp ~/.yourchain/config/genesis.json
+```
+
+**Set voting periods:**
+```bash expandable
+# Standard voting period
+jq '.app_state.gov.params.voting_period = "172800s"' \
+ ~/.yourchain/config/genesis.json > tmp && mv tmp ~/.yourchain/config/genesis.json
+
+# Expedited period (must be < voting_period)
+jq '.app_state.gov.params.expedited_voting_period = "86400s"' \
+ ~/.yourchain/config/genesis.json > tmp && mv tmp ~/.yourchain/config/genesis.json
+```
+
+**Important**: `expedited_voting_period` must be strictly less than `voting_period`.
+
+
+
+
+
+### Mint Parameters
+
+**Description**: Token inflation and minting schedule.
+
+**Genesis Location**: `app_state.mint.params`
+
+
+
+```bash expandable
+jq '.app_state.mint.params = {
+ "mint_denom": "atoken",
+ "inflation_rate_change": "0.130000000000000000",
+ "inflation_max": "0.200000000000000000",
+ "inflation_min": "0.070000000000000000",
+ "goal_bonded": "0.670000000000000000",
+ "blocks_per_year": "6311520"
+}' ~/.yourchain/config/genesis.json > tmp && mv tmp ~/.yourchain/config/genesis.json
+```
+
+
+
+**1. `mint_denom`** (string)
+- Must match your base denomination
+- Example: `"atoken"`
+
+**2. `inflation_max`** (decimal)
+- Maximum annual inflation rate
+- `"0.200000000000000000"` = 20% (Cosmos standard)
+
+**3. `inflation_min`** (decimal)
+- Minimum annual inflation rate
+- `"0.070000000000000000"` = 7% (Cosmos standard)
+
+**4. `goal_bonded`** (decimal)
+- Target bonded token ratio
+- `"0.670000000000000000"` = 67% (Cosmos standard)
+
+**5. `blocks_per_year`** (string)
+- Expected blocks per year
+- `"6311520"` = ~5 second blocks (Cosmos standard)
+- Adjust based on your block time
+
+**How inflation works:**
+- If bonded ratio < goal → inflation increases (toward max)
+- If bonded ratio > goal → inflation decreases (toward min)
+- Incentivizes target staking ratio
+
+
+
+
+
+### Distribution Parameters
+
+**Description**: Token / reward distribution including community tax and proposer rewards.
+
+**Genesis Location**: `app_state.distribution.params`
+
+
+
+```bash expandable
+jq '.app_state.distribution.params = {
+ "community_tax": "0.020000000000000000",
+ "base_proposer_reward": "0.000000000000000000",
+ "bonus_proposer_reward": "0.000000000000000000",
+ "withdraw_addr_enabled": true
+}' ~/.yourchain/config/genesis.json > tmp && mv tmp ~/.yourchain/config/genesis.json
+```
+
+**Note**: Proposer rewards (`base_proposer_reward` and `bonus_proposer_reward`) are deprecated in recent Cosmos SDK versions and should be set to `"0.000000000000000000"`.
+
+
+
+**1. `community_tax`** (decimal)
+- Percentage of rewards going to community pool
+- `"0.020000000000000000"` = 2% (standard)
+
+**2. `base_proposer_reward`** (decimal)
+- **Deprecated** - set to `"0.000000000000000000"`
+
+**3. `bonus_proposer_reward`** (decimal)
+- **Deprecated** - set to `"0.000000000000000000"`
+
+**4. `withdraw_addr_enabled`** (bool)
+- Allow setting custom withdraw addresses
+- `true` (recommended)
+
+
+
+
+
+### Initial Accounts and Validators
+
+After configuring all genesis parameters, add initial accounts and collect validator gentxs.
+
+
+
+**Add accounts with initial balances:**
+
+```bash expandable
+# Add account by address
+yourchain genesis add-genesis-account \
+ cosmos1abc123... \
+ 1000000000000000000000atoken
+
+# Add account by key name from keyring
+yourchain genesis add-genesis-account \
+ validator1 \
+ 1000000000000000000000atoken \
+ --keyring-backend test
+
+# Add multiple accounts
+yourchain genesis add-genesis-account validator1 1000000000000000000000atoken
+yourchain genesis add-genesis-account validator2 1000000000000000000000atoken
+yourchain genesis add-genesis-account faucet 10000000000000000000000atoken
+```
+
+**Verify accounts:**
+```bash expandable
+jq '.app_state.bank.balances' ~/.yourchain/config/genesis.json
+```
+
+
+
+**Workflow:**
+
+**1. Each validator creates their gentx:**
+```bash expandable
+yourchain genesis gentx validator1 \
+ 1000000000000000000000atoken \
+ --chain-id mychain-1 \
+ --keyring-backend test \
+ --moniker "Validator 1" \
+ --commission-rate 0.1 \
+ --commission-max-rate 0.2 \
+ --commission-max-change-rate 0.01 \
+ --min-self-delegation 1
+```
+
+**Output**: Creates `~/.yourchain/config/gentx/gentx-.json`
+
+**2. Validator shares gentx file:**
+```bash expandable
+cat ~/.yourchain/config/gentx/gentx-*.json
+```
+
+**3. Coordinator collects all gentxs:**
+```bash expandable
+# Create gentx directory
+mkdir -p ~/.yourchain/config/gentx/
+
+# Copy all received gentx files to this directory
+# (one file per validator)
+
+# Collect into genesis
+yourchain genesis collect-gentxs
+```
+
+**4. Verify:**
+```bash expandable
+yourchain genesis validate
+jq '.app_state.genutil.gen_txs | length' ~/.yourchain/config/genesis.json
+```
+
+
+
+**Final validation before distribution:**
+
+```bash expandable
+# Validate structure and parameters
+yourchain genesis validate
+```
+
+**What it checks:**
+- JSON structure is valid
+- All module genesis states valid
+- No denomination mismatches
+- Token supply consistent
+- Parameters within valid ranges
+- Gentxs are valid
+
+**Verify denomination consistency:**
+```bash expandable
+GENESIS=~/.yourchain/config/genesis.json
+
+jq '[
+ .app_state.staking.params.bond_denom,
+ .app_state.mint.params.mint_denom,
+ .app_state.evm.params.evm_denom,
+ .app_state.gov.params.min_deposit[0].denom,
+ .app_state.bank.denom_metadata[0].base
+] | unique | length' $GENESIS
+```
+
+**Should output `1`** (all denoms match)
+
+**Check total supply:**
+```bash expandable
+jq '.app_state.bank.balances | map(.coins[0].amount | tonumber) | add' $GENESIS
+```
+
+**Check validator count:**
+```bash expandable
+jq '.app_state.genutil.gen_txs | length' $GENESIS
+```
+
+
+
+
+
+## Next Steps
+
+Your genesis file is now complete! Next:
+
+1. **Distribute Genesis File** to all validators
+2. **Configure Runtime Settings** (`app.toml`, `config.toml`)
+3. **Launch Network** with coordinated genesis time
+
+Continue to [Runtime Configuration & Network Launch](/docs/evm/next/documentation/getting-started/build-a-chain/runtime-and-launch) for the next phase.
+
+
+
+## Quick Reference
+
+**See**: [Configuration Reference](/docs/evm/next/documentation/getting-started/build-a-chain/configuration-reference) for:
+- Command cheatsheets
+- Configuration examples
+- Default values table
diff --git a/docs/evm/next/documentation/getting-started/build-a-chain/runtime-and-launch.mdx b/docs/evm/next/documentation/getting-started/build-a-chain/runtime-and-launch.mdx
new file mode 100644
index 00000000..931aee02
--- /dev/null
+++ b/docs/evm/next/documentation/getting-started/build-a-chain/runtime-and-launch.mdx
@@ -0,0 +1,1211 @@
+---
+title: "Runtime Configuration & Network Launch"
+description: "Configure runtime settings and launch your blockchain network - from app.toml configuration to coordinated genesis 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](/docs/evm/next/documentation/getting-started/build-a-chain/pre-genesis-and-genesis-setup) - Initial configuration and genesis preparation
+- [Configuration Reference](/docs/evm/next/documentation/getting-started/build-a-chain/configuration-reference) - Commands, examples, and quick reference
+
+
+## Overview
+
+After completing genesis configuration, you need to:
+
+1. **Configure Runtime Settings** - Set node-specific parameters in `app.toml` and `config.toml`
+2. **Distribute Genesis File** - Share the final genesis file with all validators
+3. **Launch Network** - Coordinate the chain start across all validators
+4. **Monitor and Maintain** - Ensure healthy network operation post-launch
+
+
+Ensure all validators have the exact same genesis file before launching. Even small differences will cause consensus failure.
+
+
+
+
+## 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
+
+| File | Purpose | Can Change After Start |
+|---|---|---|
+| `app.toml` | Application configuration (EVM, JSON-RPC, fees) | Yes (requires restart) |
+| `config.toml` | CometBFT configuration (P2P, consensus) | Yes (requires restart) |
+| `client.toml` | Client configuration (chain-id, keyring) | Yes |
+
+
+
+## app.toml Configuration
+
+Located at `~/.yourchain/config/app.toml`, this file controls application-level settings.
+
+### Minimum Gas Prices
+
+**What It Is**: Node-level minimum gas price to accept transactions into mempool.
+
+**Section**: Root level
+
+
+
+Edit `app.toml`:
+
+```toml expandable
+# Minimum gas prices for the node to accept transactions
+minimum-gas-prices = "1000000000atoken"
+```
+
+**Format**: ``
+
+**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`
+
+
+
+**For 18-decimal tokens:**
+```toml expandable
+minimum-gas-prices = "1000000000atoken" # 1 gwei
+```
+
+**For 6-decimal tokens:**
+```toml expandable
+minimum-gas-prices = "1000utoken" # 0.001 token
+```
+
+**Testing/Development:**
+```toml expandable
+minimum-gas-prices = "0atoken" # Accept all (not for production)
+```
+
+**Production:**
+- Set to at least expected minimum to prevent mempool spam
+- Can be higher than network minimum
+- Each validator can set their own value
+
+
+
+
+
+### JSON-RPC Configuration
+
+**What It Is**: Ethereum-compatible RPC endpoints for EVM interactions.
+
+**Section**: `[json-rpc]`
+
+
+
+```toml expandable
+[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
+```
+
+
+
+**Available Namespaces:**
+
+| Namespace | Purpose | Production Use |
+|---|---|---|
+| `eth` | Standard Ethereum RPC | ✅ Required |
+| `net` | Network information | ✅ Recommended |
+| `web3` | Web3 client version | ✅ Recommended |
+| `txpool` | Transaction pool inspection | ⚠️ Caution |
+| `debug` | Debug/trace endpoints | ❌ Dev only |
+
+**Production configuration:**
+```toml expandable
+api = ["eth", "net", "web3"]
+```
+
+**Development configuration:**
+```toml expandable
+api = ["eth", "net", "web3", "txpool", "debug"]
+```
+
+**Note**: The `debug` namespace can expose sensitive information and cause performance issues. Only enable for development.
+
+
+
+**For public RPC nodes:**
+
+```toml expandable
+# Bind to localhost only
+address = "127.0.0.1:8545"
+ws-address = "127.0.0.1:8546"
+
+# Disable unprotected transactions
+allow-unprotected-txs = false
+
+# Limit connections
+max-open-connections = 100
+
+# Disable debug APIs
+api = ["eth", "net", "web3"]
+
+# Set reasonable caps
+gas-cap = 25000000
+logs-cap = 10000
+block-range-cap = 10000
+```
+
+**Security recommendations:**
+1. Use reverse proxy (nginx, traefik) for public access
+2. Implement rate limiting at proxy level
+3. Enable TLS/HTTPS
+4. Monitor for abuse
+5. Consider DDoS protection
+
+
+
+**Default Port**: `8545` (HTTP), `8546` (WebSocket)
+
+
+
+### EVM Configuration
+
+**What It Is**: EVM module settings including chain ID, tracer, and gas limits.
+
+**Section**: `[evm]`
+
+
+
+```toml expandable
+[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
+```
+
+
+
+**1. `evm-chain-id`** (uint64) - **Read-only**
+- Automatically written during `yourchain init`
+- Value from `config/config.go:78`
+- Do not modify in app.toml
+- To change: Edit source code and rebuild before init
+
+**2. `tracer`** (string)
+- Options: `"json"`, `"markdown"`, `"struct"`, `""`
+- `"json"`: Detailed traces for debugging
+- `""`: No tracing (production recommended)
+
+**3. `max-tx-gas-wanted`** (uint64)
+- `0`: Unlimited (default)
+- `30000000`: Example limit per transaction
+- Protects against excessive gas usage
+
+**4. `min-tip`** (uint64)
+- Minimum priority fee in wei
+- `0`: Accept all transactions
+- `1000000000`: Require at least 1 gwei tip
+
+
+
+**Production:**
+```toml expandable
+[evm]
+evm-chain-id = 123456 # Your chain ID
+tracer = "" # No tracing
+max-tx-gas-wanted = 0 # Unlimited (or set limit)
+cache-preimage = false
+min-tip = 1000000000 # 1 gwei minimum
+```
+
+**Development:**
+```toml expandable
+[evm]
+evm-chain-id = 262144
+tracer = "json" # Enable debugging
+max-tx-gas-wanted = 0
+cache-preimage = false
+min-tip = 0 # No minimum
+```
+
+
+
+
+
+### EVM Mempool Configuration
+
+**What It Is**: Transaction pool behavior including price limits, queue sizes, and lifetime.
+
+**Section**: `[evm.mempool]`
+
+
+**New in v0.5.0**: Mempool configuration is now fully exposed in `app.toml` and can be adjusted without code changes.
+
+
+
+
+```toml expandable
+[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"
+```
+
+
+
+**1. `price-limit`** (uint64, wei)
+- Minimum gas price to accept into mempool
+- Default: `1` wei
+- Example: `1000000000` = reject txs below 1 gwei
+
+**2. `price-bump`** (uint64, percentage)
+- Minimum % increase to replace transaction with same nonce
+- Default: `10` (10%)
+- Example: `20` = require 20% higher gas price
+
+**3. `account-slots`** (uint64)
+- Guaranteed executable slots per account
+- Default: `16`
+- Higher = more pending txs per account
+
+**4. `global-slots`** (uint64)
+- Total executable slots across all accounts
+- Default: `5120`
+- Higher = larger mempool capacity
+
+**5. `account-queue`** (uint64)
+- Queued (non-executable) slots per account
+- Default: `64`
+- For transactions with gaps in nonce sequence
+
+**6. `global-queue`** (uint64)
+- Total queued slots across all accounts
+- Default: `1024`
+
+**7. `lifetime`** (duration)
+- Maximum time transaction stays in mempool
+- Default: `"3h0m0s"` (3 hours)
+- Format: Go duration (e.g., `"1h30m"`, `"24h0m0s"`)
+
+
+
+**High-throughput chain:**
+```toml expandable
+[evm.mempool]
+price-limit = 100000000 # 0.1 gwei minimum
+global-slots = 10240
+global-queue = 2048
+lifetime = "6h0m0s"
+```
+
+**Low-resource node:**
+```toml expandable
+[evm.mempool]
+price-limit = 1
+global-slots = 2048
+global-queue = 512
+account-slots = 8
+lifetime = "1h0m0s"
+```
+
+**Strict spam prevention:**
+```toml expandable
+[evm.mempool]
+price-limit = 1000000000 # 1 gwei minimum
+price-bump = 20 # 20% increase to replace
+lifetime = "30m0s" # 30 minute lifetime
+```
+
+
+
+**Source**: [server/config/config.go:158-187](https://github.com/cosmos/evm/blob/main/server/config/config.go#L158-L187)
+
+
+**Advanced Mempool Configuration**: For detailed information on integrating the full EVM mempool with nonce gap handling and custom transaction prioritization, see the [EVM Mempool Integration](/docs/evm/next/documentation/getting-started/build-a-chain/additional-configuration/mempool-integration) guide.
+
+
+
+
+## config.toml Configuration
+
+Located at `~/.yourchain/config/config.toml`, this file controls CometBFT (consensus layer) settings.
+
+### Persistent Peers
+
+**What It Is**: List of nodes to maintain persistent connections to.
+
+**Section**: `[p2p]`
+
+
+
+Edit `config.toml`:
+
+```toml expandable
+[p2p]
+# Comma separated list of nodes to keep persistent connections to
+persistent_peers = "node_id@ip:port,node_id2@ip:port"
+```
+
+**Example:**
+```toml expandable
+persistent_peers = "7c90e16cca334eb7@192.168.1.100:26656,abc123def456@192.168.1.101:26656"
+```
+
+
+
+**Each validator runs:**
+```bash expandable
+yourchain comet show-node-id
+```
+
+**Output**: `7c90e16cca334eb7259754f964918d879ca54996`
+
+**Share format:**
+- **Node ID**: `7c90e16cca334eb7259754f964918d879ca54996`
+- **Public IP**: `192.168.1.100`
+- **P2P Port**: `26656` (default)
+- **Connection string**: `7c90e16cca334eb7@192.168.1.100:26656`
+
+
+
+Create a coordination sheet for validators:
+
+| Validator | Node ID | IP Address | P2P Port | Connection String |
+|---|---|---|---|---|
+| Validator 1 | `7c90e16c...` | 192.168.1.100 | 26656 | `7c90e16c@192.168.1.100:26656` |
+| Validator 2 | `abc123de...` | 192.168.1.101 | 26656 | `abc123de@192.168.1.101:26656` |
+| Validator 3 | `def456ab...` | 192.168.1.102 | 26656 | `def456ab@192.168.1.102:26656` |
+
+**Each validator updates their `persistent_peers` with all other validators.**
+
+
+
+**Verification:**
+```bash expandable
+# Check connected peers
+curl localhost:26657/net_info | jq '.result.peers'
+```
+
+**Default P2P Port**: `26656`
+
+
+
+### Consensus Timeouts
+
+**What It Is**: Timing parameters for consensus protocol.
+
+**Section**: `[consensus]`
+
+
+
+**Standard Cosmos values** (recommended for production):
+
+```toml expandable
+[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"
+```
+
+These are the defaults and work well for most networks.
+
+
+
+**Faster block times** for local development:
+
+```toml expandable
+[consensus]
+timeout_propose = "2s"
+timeout_propose_delta = "200ms"
+timeout_prevote = "500ms"
+timeout_prevote_delta = "200ms"
+timeout_precommit = "500ms"
+timeout_precommit_delta = "200ms"
+timeout_commit = "1s"
+```
+
+**Note**: Used by `local_node.sh` for quick local testing.
+
+
+
+**Consensus Phases:**
+1. **Propose**: Block proposer broadcasts new block
+2. **Prevote**: Validators vote on proposed block
+3. **Precommit**: Validators commit to block
+4. **Commit**: Block is finalized
+
+**Timeout Parameters:**
+- `timeout_propose`: Time for proposer to broadcast block
+- `timeout_prevote`: Time to collect prevotes
+- `timeout_precommit`: Time to collect precommits
+- `timeout_commit`: Target block time
+- `*_delta`: Incremental increase per round
+
+**Trade-offs:**
+- Shorter timeouts = faster blocks, but higher chance of timeouts on slow networks
+- Longer timeouts = more robust on slow networks, but slower blocks
+
+
+
+
+
+### Prometheus Metrics
+
+**What It Is**: Enable metrics collection for monitoring.
+
+**Section**: `[instrumentation]`
+
+```toml expandable
+[instrumentation]
+# Enable Prometheus metrics
+prometheus = true
+
+# Prometheus listen address
+prometheus_listen_addr = ":26660"
+```
+
+**Access metrics:**
+```bash expandable
+curl http://localhost:26660/metrics
+```
+
+**Recommended**: Enable for production to monitor chain health.
+
+
+
+## client.toml Configuration
+
+Located at `~/.yourchain/config/client.toml`, this file configures client behavior.
+
+### Set Client Chain ID
+
+**What It Is**: Chain ID for CLI client operations.
+
+
+The node reads `chain-id` from `client.toml` at startup. If this doesn't match `genesis.json`, the node will fail to start with:
+```
+error during handshake: error on replay: invalid chain-id on InitChain
+```
+
+
+
+
+```bash expandable
+yourchain config set client chain-id mychain-1 --home ~/.yourchain
+```
+
+**Or edit `client.toml` directly:**
+```toml expandable
+chain-id = "mychain-1"
+```
+
+
+
+```bash expandable
+# Verify chain-id matches genesis
+jq '.chain_id' ~/.yourchain/config/genesis.json
+# Output: "mychain-1"
+
+# Verify chain-id in client.toml
+grep 'chain-id' ~/.yourchain/config/client.toml
+# Output: chain-id = "mychain-1"
+```
+
+Both must match for the node to start successfully.
+
+
+
+**Other client settings:**
+```toml expandable
+# Keyring backend
+keyring-backend = "os"
+
+# Output format
+output = "text"
+
+# Node RPC address
+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
+
+
+
+- All genesis parameters configured
+- Genesis validation passes
+- Genesis accounts and validators added
+- Genesis time set for future launch
+
+
+
+- Share final genesis file with all validators
+- All validators verify genesis hash matches
+- No modifications allowed after distribution
+
+
+
+- All validators configure `app.toml`
+- All validators configure `config.toml`
+- All validators set `client.toml` chain-id
+- Persistent peers exchanged
+
+
+
+- Validators verify binary version
+- Validators test node starts without errors
+- Network connectivity verified
+- Monitoring systems ready
+
+
+
+
+
+### Distribute Genesis File
+
+After finalizing your genesis file, distribute it to all validators.
+
+
+
+**Recommended for public networks:**
+
+```bash expandable
+# 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
+```
+
+
+
+**Recommended for decentralization:**
+
+```bash expandable
+# Coordinator uploads
+ipfs add ~/.yourchain/config/genesis.json
+# Returns: QmXyz123...
+
+# Validators download
+ipfs get QmXyz123... -o ~/.yourchain/config/genesis.json
+```
+
+
+
+**For private networks:**
+
+```bash expandable
+# Coordinator shares via secure channel
+# Validators receive and copy to ~/.yourchain/config/genesis.json
+```
+
+**Important**: Use secure, verified channels to prevent tampering.
+
+
+
+
+
+### Verify Genesis Hash
+
+**Critical**: All validators must verify they have the identical genesis file.
+
+
+
+**Each validator runs:**
+
+```bash expandable
+jq -S -c . ~/.yourchain/config/genesis.json | shasum -a 256
+```
+
+**Example output:**
+```
+a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6 -
+```
+
+
+
+**1. Coordinator publishes canonical hash:**
+```bash expandable
+# Generate and save hash
+jq -S -c . ~/.yourchain/config/genesis.json | shasum -a 256 > genesis_hash.txt
+
+# Publish hash via official channel
+cat genesis_hash.txt
+```
+
+**2. All validators verify:**
+```bash expandable
+# Each validator generates hash
+jq -S -c . ~/.yourchain/config/genesis.json | shasum -a 256
+
+# Compare with published hash
+# Must match exactly
+```
+
+**3. All validators confirm:**
+- Report matching hash on official communication channel
+- Proceed only when all validators confirm
+
+
+
+
+
+### Exchange Peer Information
+
+Validators need each other's peer information to connect.
+
+
+
+**Each validator provides:**
+
+```bash expandable
+# 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
+```
+
+
+
+**Each validator updates `config.toml`:**
+
+```bash expandable
+# Edit ~/.yourchain/config/config.toml
+# Add all other validators to persistent_peers
+
+[p2p]
+persistent_peers = "7c90e16c@192.168.1.100:26656,abc123de@192.168.1.101:26656,def456ab@192.168.1.102:26656"
+```
+
+**Remove your own node ID** from the list (nodes don't connect to themselves).
+
+
+
+**After starting nodes, verify connectivity:**
+
+```bash expandable
+# Check number of connected peers
+curl localhost:26657/net_info | jq '.result.n_peers'
+
+# List connected peers
+curl localhost:26657/net_info | jq '.result.peers[].node_info.moniker'
+
+# Check peer details
+curl localhost:26657/net_info | jq '.result.peers'
+```
+
+**Expected**: Each validator should connect to all other validators.
+
+
+
+
+
+### Coordinate Launch Time
+
+Set and coordinate the exact launch time across all validators.
+
+
+
+**Coordinator sets future genesis time:**
+
+```bash expandable
+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)
+
+
+
+**Example launch timeline:**
+
+```
+T-48h: Announce genesis time to all validators
+T-24h: Distribute final genesis file
+T-4h: Validators complete configuration
+T-2h: All validators verify genesis hash
+T-1h: Validators start nodes (wait for genesis time)
+T-30m: Monitor validator connections
+T-0: Genesis time - network starts automatically
+T+10m: Verify all validators online and signing
+T+1h: Monitor network health
+```
+
+
+
+**Validators start early:**
+
+```bash expandable
+# Start node before genesis time
+yourchain start
+
+# Node output while waiting:
+Genesis time is in the future. Waiting...
+Time until genesis: 29m 45s
+...
+
+# At genesis time:
+Starting consensus...
+INF finalizing commit of block hash=ABC123... height=1
+INF finalizing commit of block hash=DEF456... height=2
+```
+
+**Network automatically begins** when genesis time is reached.
+
+
+
+
+
+### Start Validator Nodes
+
+After configuration and coordination, start the nodes.
+
+
+
+```bash expandable
+# 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 &
+```
+
+
+
+```bash expandable
+# Follow logs
+yourchain start 2>&1 | grep "finalizing commit"
+
+# Expected output:
+INF finalizing commit of block hash=ABC123... height=1 module=consensus
+INF finalizing commit of block hash=DEF456... height=2 module=consensus
+INF finalizing commit of block hash=GHI789... height=3 module=consensus
+```
+
+**Healthy signs:**
+- Block height increasing
+- No error messages
+- Blocks finalizing every ~5-8 seconds
+
+
+
+**Create service file** at `/etc/systemd/system/yourchain.service`:
+
+```ini expandable
+[Unit]
+Description=Cosmos EVM Chain
+After=network-online.target
+
+[Service]
+User=yourchain
+ExecStart=/usr/local/bin/yourchain start --home /home/yourchain/.yourchain
+Restart=on-failure
+RestartSec=3
+LimitNOFILE=4096
+
+[Install]
+WantedBy=multi-user.target
+```
+
+**Enable and start:**
+```bash expandable
+sudo systemctl enable yourchain
+sudo systemctl start yourchain
+
+# Check status
+sudo systemctl status yourchain
+
+# View logs
+sudo journalctl -u yourchain -f
+```
+
+
+
+
+
+### Verify Network Health
+
+After launch, verify the network is operating correctly.
+
+
+
+**Check block height increasing:**
+
+```bash expandable
+# 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.
+
+
+
+**Check validator set:**
+
+```bash expandable
+# Number of validators
+curl localhost:26657/validators | jq '.result.validators | length'
+
+# List validators
+curl localhost:26657/validators | jq '.result.validators[].address'
+
+# Check voting power
+curl localhost:26657/validators | \
+ jq '[.result.validators[].voting_power | tonumber] | add'
+```
+
+**Should see:** All expected validators present and voting.
+
+
+
+**Check peers:**
+
+```bash expandable
+# Number of connected peers
+curl localhost:26657/net_info | jq '.result.n_peers'
+
+# List connected peers
+curl localhost:26657/net_info | jq '.result.peers[].node_info.moniker'
+```
+
+**Should see:** Connected to expected number of peers.
+
+
+
+**CometBFT health:**
+
+```bash expandable
+curl localhost:26657/health
+# Returns: {} (empty object = healthy)
+```
+
+**Node status:**
+```bash expandable
+curl localhost:26657/status | jq '.result'
+```
+
+**Shows:**
+- Node info
+- Sync status
+- Latest block info
+- Validator info
+
+
+
+**Test JSON-RPC:**
+
+```bash expandable
+# Check chain ID
+curl http://localhost:8545 \
+ -X POST \
+ -H "Content-Type: application/json" \
+ -d '{"jsonrpc":"2.0","method":"eth_chainId","params":[],"id":1}'
+
+# Get latest block
+curl http://localhost:8545 \
+ -X POST \
+ -H "Content-Type: application/json" \
+ -d '{"jsonrpc":"2.0","method":"eth_getBlockByNumber","params":["latest",false],"id":1}'
+
+# Check gas price
+curl http://localhost:8545 \
+ -X POST \
+ -H "Content-Type: application/json" \
+ -d '{"jsonrpc":"2.0","method":"eth_gasPrice","params":[],"id":1}'
+```
+
+**Should see:** Valid JSON responses with expected data.
+
+
+
+
+
+## Post-Launch Operations
+
+After successful launch, maintain healthy network operation.
+
+### Validator Operations
+
+
+
+**If validator gets jailed for downtime:**
+
+```bash expandable
+# 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
+```
+
+
+
+**Update validator information:**
+
+```bash expandable
+yourchain tx staking edit-validator \
+ --moniker "New Moniker" \
+ --website "https://example.com" \
+ --identity "keybase-id" \
+ --details "Description" \
+ --commission-rate 0.05 \
+ --from validator \
+ --chain-id mychain-1
+```
+
+
+
+**Track validator performance:**
+
+```bash expandable
+# Check signing info
+yourchain query slashing signing-info $(yourchain comet show-validator)
+
+# Check delegations
+yourchain query staking validator $(yourchain keys show validator --bech val -a)
+
+# Check rewards
+yourchain query distribution validator-outstanding-rewards \
+ $(yourchain keys show validator --bech val -a)
+```
+
+
+
+
+
+### Monitoring and Alerting
+
+
+
+**Monitor these metrics:**
+
+1. **Block height** - Should increase steadily
+2. **Peer count** - Should maintain connections
+3. **Validator signing** - Should sign every block
+4. **Memory/CPU usage** - Should be stable
+5. **Disk space** - Should have adequate free space
+
+**Prometheus metrics** available at `http://localhost:26660/metrics`
+
+
+
+**Chain not producing blocks:**
+- Check >= 2/3 voting power online
+- Verify network connectivity
+- Check validator logs for errors
+
+**Node out of sync:**
+- May need to resync from genesis
+- Or use state sync (if configured)
+- Check peer connections
+
+**High memory usage:**
+- Check mempool size
+- Monitor for transaction spam
+- May need to adjust `app.toml` settings
+
+**Validator missing blocks:**
+- Check node is running
+- Verify network connectivity
+- Check slashing params
+
+
+
+
+
+### Backup and Recovery
+
+
+
+**What to backup:**
+
+```bash expandable
+# 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
+
+
+
+**If validator node fails:**
+
+1. **Restore on new hardware:**
+```bash expandable
+# Install binary
+# Copy priv_validator_key.json
+# Copy node_key.json
+# Copy genesis.json
+# Sync blockchain data
+```
+
+2. **Sync options:**
+- Full sync from genesis (slow)
+- State sync from snapshot (fast)
+- Copy data directory from backup
+
+3. **Restart validator:**
+```bash expandable
+yourchain start
+```
+
+**Critical**: Never run two validators with same private key simultaneously (double-sign risk).
+
+
+
+
+
+## Next Steps
+
+Your chain is now launched and operational!
+
+**For ongoing operations:**
+- Monitor network health continuously
+- Maintain validator uptime
+- Coordinate upgrades via governance
+- Build community and ecosystem
+
+**Further resources:**
+- [Configuration Reference](/docs/evm/next/documentation/getting-started/build-a-chain/configuration-reference) - Complete command reference and examples
+- [VM Module Documentation](/docs/evm/next/documentation/cosmos-sdk/modules/vm) - EVM configuration details
+- [Cosmos SDK Documentation](https://docs.cosmos.network) - General Cosmos SDK operations
+
+
+
+## Summary
+
+This guide covered:
+- ✅ Runtime configuration (`app.toml`, `config.toml`, `client.toml`)
+- ✅ Network launch coordination
+- ✅ Genesis file distribution and verification
+- ✅ Node startup and monitoring
+- ✅ Post-launch operations and maintenance
+
+Your Cosmos EVM chain is now running and ready for use!
\ No newline at end of file
diff --git a/docs/evm/next/documentation/getting-started/build-a-chain/text b/docs/evm/next/documentation/getting-started/build-a-chain/text
new file mode 100644
index 00000000..9ea51cc5
--- /dev/null
+++ b/docs/evm/next/documentation/getting-started/build-a-chain/text
@@ -0,0 +1,21 @@
+# Combined ultra doc
+
+We now have three docs that all have significant overlap:
+
+1. `docs/evm/next/documentation/getting-started/build-a-chain/chain-configuration-reference.mdx` - Nice structure, with additional guidance or context for decisions. It is lacking some of the broader scope and details that can be found in doc 2 and/or 3. We should use this as the target format, with some adjustments and added content+context from the other two docs. Each section and sub-section should follow a consistent structure as much as possible.
+
+2. `docs/evm/next/documentation/getting-started/build-a-chain/chain-customization-checklist.mdx` - very comprehensive, but lacking in guidance and some details, not a very nice structure to follow in terms of readability. The final doc should cover the complete range of configs/parameters and the whole scope including post-launch and validator operations in the way this doc does. We also need to take example of how to condense the additional content within each section from this doc.
+
+3. `docs/evm/next/documentation/getting-started/build-a-chain/configuration-parameters.mdx` no guidance, strictly technical reference that should be used to add complete detail to each different item in the final doc.
+
+We need to combine the best qualities of these three, and also simplify the initial "planning" phase by clearly listing the parameters that can be changed within each section, (list them in their relevant groups, and in the order they are detailed in the document). We should note those of which can usually be left to defaults or are not commonly modified, and instruct the reader to make their own note/document for these before proceeding with the rest of the chain setup. This will reduce a large portion of text that does not really provide value by condensing the 'planning' to the top of the document, where it makes the most sense.
+
+Then we can move on to the actual configurations, which is already documented fairly well in each of docs 1 and 2.. However, the entire process as shown in doc 2 should be split into 2 pages -- one for pre-genesis and genesis configs, and one for the network launch, which should be preceeded bt the runtime configuration, as (an optional) continuiation of the first doc.
+The configuration sections within the document should also be listed in the correct sequence of operations, so that a reader who prefers that style of doc can still easily follow the procedure. (this is already pretty solid in both docs 1 and 2)
+We also want to have each "step" or section remain consistently structured like you can see in doc 1, but we should add the complete details for each relevant item that can be seen in doc 3. Finally, since we are adding significant amounts of detail from doc 3, we must condense some of the additional information that more experienced teams may not need by containing it in each section with the expandable or accordion components.
+Finally,we need to both double-check that none of this information is either conflicting (use doc 1 and 2 as the source of truth in the event of any direct conflicts), or redundant.
+
+Optionally, if it makes sense and there is significant content from the three original docs that does not fit into this "master" chain setup doc, we can make a "quick-reference" as a third page which contains the miscellaneous info like any command "cheat-sheets" and various code snippets and config examples etc.
+In this list, add a link to the relevant section of the document that describes each parameter and the relevant details for it. This will make navigating the document seamless.
+
+There is a quick draft of this page 'build-chain-final.mdx' but I don't like this one very much. It's too long (since it is not separeted like what I requested above) and each section is too condensed into accordions and does not contain enough of the context or guidance that I think it should have. Only the actual code/examples content should be condensed, and we should use some better components to organize each section into its own self contained "block" like the tabs or code groups components. Some good examples of this can be seen in doc 1.
diff --git a/docs/evm/next/documentation/getting-started/build-a-chain/token-configuration-guide.mdx b/docs/evm/next/documentation/getting-started/build-a-chain/token-configuration-guide.mdx
deleted file mode 100644
index dade4cac..00000000
--- a/docs/evm/next/documentation/getting-started/build-a-chain/token-configuration-guide.mdx
+++ /dev/null
@@ -1,197 +0,0 @@
----
-title: "Token Configuration"
-description: "Configuring the native token and decimal precision"
----
-
-## Overview
-
-Cosmos EVM handles token configuration through bank metadata and VM parameters, and the implications of different decimal precision choices.
-For most deployments, it is sugested to stick with the canonical EVM setup with an 18 decimal token for simplicity sake.
-
-It's also important to note that `eth` and `wei` are still valid identifiers for the native token, so your choices here will not affect any common EVM tooling or app compatibility.
-
-## How Token Configuration Works
-
-Cosmos EVM derives token configuration from two sources:
-
-1. **Bank Module Metadata**: Defines the token denominations and decimal precision
-2. **VM Module Parameters**: Specifies which bank denom to use as the native EVM token
-
-During initialization, the VM module's `SetGlobalConfigVariables` function:
-1. Reads bank metadata for the specified `evm_denom`
-2. Extracts decimal precision from the denom units
-3. Creates `EvmCoinInfo` with appropriate extended denom
-4. Stores this configuration in VM keeper state
-
-## Decimal Precision Choices
-
-### 18 Decimal Configuration (Recommended for Simplicity)
-
-**Genesis Configuration:**
-```json
-{
- "bank": {
- "denom_metadata": [
- {
- "description": "The native token with 18 decimals",
- "denom_units": [
- {
- "denom": "atoken", // Base denomination (18 decimals)
- "exponent": 0
- },
- {
- "denom": "token", // Display denomination
- "exponent": 18
- }
- ],
- "base": "atoken",
- "display": "token",
- "name": "Token",
- "symbol": "TKN"
- }
- ]
- },
- "vm": {
- "params": {
- "evm_denom": "atoken" // References bank metadata base denom
- // No extended_denom_options needed
- }
- }
-}
-```
-
-**Architecture Benefits:**
-- Direct 1:1 mapping with EVM (no conversion needed)
-- No precision loss or dust accumulation
-- Uses standard Cosmos SDK bank module by default
-- No additional modules required
-- Simplest implementation - this is the default configuration
-
-**Module Configuration (Default):**
-```go
-// No changes needed - the default configuration already uses standard bank:
-app.EVMKeeper = evmkeeper.NewKeeper(
- appCodec,
- keys[evmtypes.StoreKey],
- tkeys[evmtypes.TransientKey],
- keys,
- authtypes.NewModuleAddress(govtypes.ModuleName),
- app.AccountKeeper,
- app.BankKeeper, // Uses bank keeper directly by default
- app.StakingKeeper,
- // ...
-)
-```
-
-### 6 Decimal Configuration (Common in Cosmos)
-
-**Genesis Configuration:**
-```json
-{
- "bank": {
- "denom_metadata": [
- {
- "description": "The native token with 6 decimals",
- "denom_units": [
- {
- "denom": "utoken", // Base denomination (6 decimals)
- "exponent": 0
- },
- {
- "denom": "token", // Display denomination
- "exponent": 6
- }
- ],
- "base": "utoken",
- "display": "token",
- "name": "Token",
- "symbol": "TKN"
- }
- ]
- },
- "vm": {
- "params": {
- "evm_denom": "utoken", // References bank metadata base denom
- "extended_denom_options": {
- "extended_denom": "atoken" // Required: 18-decimal representation for EVM
- }
- }
- }
-}
-```
-
-**Architecture Requirements:**
-- Requires adding precisebank module to track fractional amounts
-- Conversion: 1 utoken = 10^12 wei in EVM
-- Precisebank wraps standard bank module
-- Handles dust from decimal conversion
-- See [Adding Precisebank Module](/docs/evm/next/documentation/getting-started/build-a-chain/building-your-chain-guide#adding-precisebank-module-for-non-18-decimal-chains) for implementation
-
-### Other Decimal Configurations
-
-Any decimal precision from 1-18 is supported, but requires careful consideration:
-
-- **2 decimals**: 1 base = 10^16 wei (requires precisebank)
-- **9 decimals**: 1 base = 10^9 wei (requires precisebank)
-- **12 decimals**: 1 base = 10^6 wei (requires precisebank)
-
-## Implementation Steps
-
-### For 18-Decimal Chains (Default)
-
-1. **No module changes required** - the default configuration already uses standard bank
-
-2. **Configure genesis with 18-decimal token** (see example above)
-
-3. **Verify bank keeper is used directly:**
-```go
-app.EVMKeeper = evmkeeper.NewKeeper(
- // ... other params
- app.BankKeeper, // Should use BankKeeper directly (default)
- // ... other params
-)
-```
-
-### For Non-18 Decimal Chains
-
-1. **Add precisebank module to your app.go:**
-```go
-// Add these imports:
-import "github.com/cosmos/evm/x/precisebank"
-import precisebankkeeper "github.com/cosmos/evm/x/precisebank/keeper"
-import precisebanktypes "github.com/cosmos/evm/x/precisebank/types"
-
-// Add to module list:
-precisebanktypes.ModuleName,
-```
-
-2. **Initialize PreciseBankKeeper and use it for EVM:**
-```go
-app.PreciseBankKeeper = precisebankkeeper.NewKeeper(
- appCodec,
- keys[precisebanktypes.StoreKey],
- app.BankKeeper,
- app.AccountKeeper,
-)
-
-app.EVMKeeper = evmkeeper.NewKeeper(
- // ... other params
- app.PreciseBankKeeper, // Use PreciseBankKeeper instead
- // ... other params
-)
-```
-
-3. **Configure extended denom** in VM params:
-```json
-"extended_denom_options": {
- "extended_denom": "atoken" // Your 18-decimal representation
-}
-```
-
-
-## Double-check
-
-1. **Forgetting extended_denom_options**: Non-18 decimal chains MUST specify extended denom
-2. **Module mismatch**: Adding precisebank to 18 decimals adds unnecessary complexity
-3. **Incorrect denom references**: VM params must reference actual bank metadata base denom
-4. **Missing bank metadata**: Bank metadata must be set in genesis
diff --git a/docs/evm/next/documentation/getting-started/index.mdx b/docs/evm/next/documentation/getting-started/index.mdx
index 66f27a18..5135e478 100644
--- a/docs/evm/next/documentation/getting-started/index.mdx
+++ b/docs/evm/next/documentation/getting-started/index.mdx
@@ -10,7 +10,7 @@ Set up your development environment and deploy your first application:
Configure your IDE and install essential development tools for optimal productivity.
- Setup Environment →
+ Setup Environment →
diff --git a/docs/evm/next/documentation/getting-started/local-node-setup.mdx b/docs/evm/next/documentation/getting-started/local-node-setup.mdx
index 982fb7ca..f7fe4f63 100644
--- a/docs/evm/next/documentation/getting-started/local-node-setup.mdx
+++ b/docs/evm/next/documentation/getting-started/local-node-setup.mdx
@@ -112,7 +112,7 @@ The script sets up a chain with these default values:
| Parameter | Value | Purpose |
|-----------|-------|---------|
-| Chain ID | `9001` | Can be overridden with `CHAIN_ID` env var |
+| Cosmos Chain ID | `9001` | Can be overridden with `CHAIN_ID` env var |
| Moniker | `localtestnet` | Node identifier |
| Home Directory | `~/.evmd` | All chain data location |
| Keyring | `test` | **WARNING: Not secure for production** |
@@ -356,7 +356,7 @@ Edit at the top of `local_node.sh`:
| Variable | Line | Default | Purpose |
|----------|------|---------|---------|
-| `CHAINID` | 3 | `9001` | EVM chain ID (overridable via `CHAIN_ID` env var) |
+| `CHAINID` | 3 | `9001` | Cosmos chain ID (overridable via `CHAIN_ID` env var) |
| `MONIKER` | 4 | `localtestnet` | Node identifier |
| `LOGLEVEL` | 11 | `info` | Log verbosity: `debug`, `info`, `warn`, `error` |
| `BASEFEE` | 15 | `10000000` | Initial EIP-1559 base fee |
@@ -930,7 +930,7 @@ Configure your tools to use this endpoint:
```javascript MetaMask
Network Name: Local EVM
RPC URL: http://localhost:8545
-Chain ID: 9001
+Chain ID: 999111
Currency Symbol: TEST
```
@@ -972,22 +972,6 @@ http://localhost:1317
ws://localhost:8546
```
-## Security Considerations
-
-
-The local node setup is **NOT SECURE** and should **NEVER** be used in production or on public networks.
-
-
-Key security concerns:
-- Test keyring backend stores keys unencrypted
-- Well-known development mnemonics are public
-- All APIs are enabled without authentication
-- Zero gas prices accepted
-- Fast consensus timeouts compromise security
-- No pruning means disk usage grows quickly
-
-For production deployments, see the [Chain Deployment Guide](/docs/evm/next/documentation/getting-started/build-a-chain/building-your-chain-guide).
-
## Next Steps
diff --git a/docs/evm/next/documentation/getting-started/reference-network.mdx b/docs/evm/next/documentation/getting-started/reference-network.mdx
deleted file mode 100644
index 1c1f52bc..00000000
--- a/docs/evm/next/documentation/getting-started/reference-network.mdx
+++ /dev/null
@@ -1,76 +0,0 @@
----
-title: "Reference Network (evmd)"
-description: "Reference network used throughout this documentation"
----
-
-## Overview
-
-Throughout this documentation, you'll notice consistent references to:
-- **Binary name**: `evmd`
-- **Token denominations**: `test` (whole token) and `atest` (18 decimals)
-
-The intention is to provide direct examples for hands-on testing, rather than abstract placeholders wherever possible.
-
-## The evmd Reference Network
-
-**evmd** is the official Cosmos EVM reference implementation available in the [cosmos/evm](https://github.com/cosmos/evm) repository. It serves as:
-
-**Living Documentation**: Most examples in these docs can be run verbatim using `evmd`
-**Testing Environment**: Quickly spin up a local network using the `local-node.sh` script in the `cosmos/evm` repo
-**Integration Reference**: See exactly how the EVM module integrates with Cosmos SDK
-
-Code and CLI examples are immediately executable:
-
-```bash
-evmd query bank balances cosmos1... --denom test
-evmd start --chain-id local-1
-evmd keys add alice
-```
-
-No placeholders or generic commands - every example works directly with the evmd reference implementation.
-
-## Token Denomination System
-
-The evmd network uses the EVM standard 18-decimal format for the native/staking token.
-| **Token** | **Decimals** | **Usage** | **Example Amount** |
-|-----------|--------------|-----------|-------------------|
-| `test` | 0 | Native Cosmos operations | 1 `TEST` = `1000000000000000000atest` |
-| `atest` | 18 | EVM operations and gas | `1000000000000000000atest` = 1 `TEST` |
-
-## Quick Start with evmd
-
-### 1. Get the Binary
-
-```bash
-git clone https://github.com/cosmos/evm.git
-cd evm
-make install
-```
-
-### 2. Initialize Local Network
-
-```bash
-evmd init mynode --chain-id local-1 --default-denom atest
-```
-
-### 3. Create Test Account
-
-```bash
-evmd keys add alice
-evmd genesis add-genesis-account alice 1000000000000atest
-```
-
-### 4. Start the Network
-
-```bash
-evmd start --json-rpc.enable --json-rpc.api eth,web3,net
-```
-
-Now you can follow along with / test documentation examples verbatim.
-
-
-## Next Steps
-
-- **Try it out**: [Set up your local evmd network](/docs/evm/next/documentation/getting-started/local-node-setup)
-- **Configure**: [Node configuration options](/docs/evm/next/documentation/getting-started/node-configuration)
-- **Integrate**: [Add EVM compatibility to your chain](/docs/evm/next/documentation/getting-started/build-a-chain/overview.mdx)
diff --git a/docs/evm/next/documentation/getting-started/development-environment.mdx b/docs/evm/next/documentation/getting-started/tooling-and-resources/development-environment.mdx
similarity index 100%
rename from docs/evm/next/documentation/getting-started/development-environment.mdx
rename to docs/evm/next/documentation/getting-started/tooling-and-resources/development-environment.mdx
diff --git a/docs/evm/next/documentation/overview.mdx b/docs/evm/next/documentation/overview.mdx
index d95b119e..478bc2b5 100644
--- a/docs/evm/next/documentation/overview.mdx
+++ b/docs/evm/next/documentation/overview.mdx
@@ -6,6 +6,12 @@ mode: "wide"
import { EthereumOutlineIcon, CosmosOutlineIcon } from '/snippets/icons.mdx'
+
+**About the examples in this documentation**
+
+Code and CLI examples use `evmd`, the reference implementation from [cosmos/evm](https://github.com/cosmos/evm). Examples can be run directly without modification using the native token denominations `test` (display) and `atest` (base, 18 decimals). To get started quickly, see [Local Node Setup](/docs/evm/next/documentation/getting-started/local-node-setup).
+
+
Bootstrapping and customizing your own blockchain with full EVM compatibility, from start to finish.
diff --git a/snippets/icons.mdx b/snippets/icons.mdx
index 1aa6b0fc..481df7bf 100644
--- a/snippets/icons.mdx
+++ b/snippets/icons.mdx
@@ -87,6 +87,267 @@ export const APIIcon = ({ size = 24, color = "currentColor", className = "" }) =
)
+// Configuration Icons for Chain Setup
+
+export const BinaryIcon = ({ size = 24, className = "" }) => (
+
+)
+
+export const AddressPrefixIcon = ({ size = 24, className = "" }) => (
+
+)
+
+export const CoinTypeIcon = ({ size = 24, className = "" }) => (
+
+)
+
+export const ChainLinkIcon = ({ size = 24, className = "" }) => (
+
+)
+
+export const DecimalIcon = ({ size = 24, className = "" }) => (
+
+)
+
+export const SourceCodeIcon = ({ size = 24, className = "" }) => (
+
+)
+
+export const ChainIdIcon = ({ size = 24, className = "" }) => (
+
+)
+
+export const ClockIcon = ({ size = 24, className = "" }) => (
+
+)
+
+export const MetadataIcon = ({ size = 24, className = "" }) => (
+
+)
+
+export const ChipIcon = ({ size = 24, className = "" }) => (
+
+)
+
+export const PuzzleIcon = ({ size = 24, className = "" }) => (
+
+)
+
+export const ExchangeIcon = ({ size = 24, className = "" }) => (
+
+)
+
+export const TrendingIcon = ({ size = 24, className = "" }) => (
+
+)
+
+export const ShieldIcon = ({ size = 24, className = "" }) => (
+
+)
+
+export const LayersIcon = ({ size = 24, className = "" }) => (
+
+)
+
+export const GavelIcon = ({ size = 24, className = "" }) => (
+
+)
+
+export const VoteIcon = ({ size = 24, className = "" }) => (
+
+)
+
+export const UsersIcon = ({ size = 24, className = "" }) => (
+
+)
+
export const IconWrapper = ({
children,
color = "#4B47CA",