From 03185a2555b17cab4d949b6e701be22850906be5 Mon Sep 17 00:00:00 2001 From: Cordt Date: Wed, 15 Oct 2025 14:32:37 -0600 Subject: [PATCH 1/6] finalize build chain docs --- docs.json | 22 +- .../mempool-integration.mdx | 19 +- .../predeployed-contracts.mdx | 21 +- .../build-a-chain/build-chain-final.mdx | 2985 +++++++++++++++++ .../building-your-chain-guide.mdx | 225 -- .../build-a-chain/configuration-reference.mdx | 659 ++++ .../build-a-chain/overview.mdx | 140 +- .../pre-genesis-and-genesis-setup.mdx | 2104 ++++++++++++ .../build-a-chain/runtime-and-launch.mdx | 1313 ++++++++ .../getting-started/build-a-chain/text | 21 + .../token-configuration-guide.mdx | 197 -- snippets/icons.mdx | 261 ++ 12 files changed, 7493 insertions(+), 474 deletions(-) create mode 100644 docs/evm/next/documentation/getting-started/build-a-chain/build-chain-final.mdx delete mode 100644 docs/evm/next/documentation/getting-started/build-a-chain/building-your-chain-guide.mdx create mode 100644 docs/evm/next/documentation/getting-started/build-a-chain/configuration-reference.mdx create mode 100644 docs/evm/next/documentation/getting-started/build-a-chain/pre-genesis-and-genesis-setup.mdx create mode 100644 docs/evm/next/documentation/getting-started/build-a-chain/runtime-and-launch.mdx create mode 100644 docs/evm/next/documentation/getting-started/build-a-chain/text delete mode 100644 docs/evm/next/documentation/getting-started/build-a-chain/token-configuration-guide.mdx diff --git a/docs.json b/docs.json index e18409a1..70f14b57 100644 --- a/docs.json +++ b/docs.json @@ -200,18 +200,18 @@ { "group": "Build Your Own Chain", "pages": [ - "docs/evm/next/documentation/getting-started/build-a-chain/overview", "docs/evm/next/documentation/getting-started/build-a-chain/building-your-chain-guide", - "docs/evm/next/documentation/getting-started/build-a-chain/chain-customization-checklist", - "docs/evm/next/documentation/getting-started/build-a-chain/configuration-parameters", - "docs/evm/next/documentation/getting-started/build-a-chain/parameter-reference", - "docs/evm/next/documentation/getting-started/build-a-chain/token-configuration-guide", + "docs/evm/next/documentation/getting-started/build-a-chain/overview", + "docs/evm/next/documentation/getting-started/build-a-chain/pre-genesis-and-genesis-setup", + "docs/evm/next/documentation/getting-started/build-a-chain/runtime-and-launch", { - "group": "Additional Configuration", - "pages": [ - "docs/evm/next/documentation/getting-started/build-a-chain/additional-configuration/mempool-integration", - "docs/evm/next/documentation/getting-started/build-a-chain/additional-configuration/predeployed-contracts" - ] - }] + "group": "Additional Configuration", + "pages": [ + "docs/evm/next/documentation/getting-started/build-a-chain/additional-configuration/mempool-integration", + "docs/evm/next/documentation/getting-started/build-a-chain/additional-configuration/predeployed-contracts" + ] + }, + "docs/evm/next/documentation/getting-started/build-a-chain/configuration-reference" + ] }, "docs/evm/next/documentation/getting-started/local-node-setup", "docs/evm/next/documentation/getting-started/index", diff --git a/docs/evm/next/documentation/getting-started/build-a-chain/additional-configuration/mempool-integration.mdx b/docs/evm/next/documentation/getting-started/build-a-chain/additional-configuration/mempool-integration.mdx index a23e3ffe..fefcd4e7 100644 --- a/docs/evm/next/documentation/getting-started/build-a-chain/additional-configuration/mempool-integration.mdx +++ b/docs/evm/next/documentation/getting-started/build-a-chain/additional-configuration/mempool-integration.mdx @@ -9,9 +9,9 @@ This guide provides step-by-step instructions for integrating the EVM mempool in ### Step 1: Add EVM Mempool to App Struct -Update your `app/app.go` to include the EVM mempool: - + ```go +// Update your app/app.go to include the EVM mempool type App struct { *baseapp.BaseApp // ... other keepers @@ -22,6 +22,7 @@ type App struct { EVMMempool *evmmempool.ExperimentalEVMMempool } ``` + ### Step 2: Configure Mempool in NewApp Constructor @@ -31,7 +32,7 @@ The mempool must be initialized **after** the antehandler has been set in the ap Add the following configuration in your `NewApp` constructor: - + ```go // Set the EVM priority nonce mempool if evmtypes.GetChainConfig() != nil { @@ -68,7 +69,7 @@ if evmtypes.GetChainConfig() != nil { app.SetPrepareProposal(abciProposalHandler.PrepareProposalHandler()) } ``` - + **Breaking Change from v0.4.x:** The global mempool registry (`SetGlobalEVMMempool`) has been removed. Mempool is now passed directly to the JSON-RPC server during initialization. @@ -78,8 +79,8 @@ if evmtypes.GetChainConfig() != nil { The `EVMMempoolConfig` struct provides several configuration options for customizing the mempool behavior: -### Minimal Configuration - + + For most use cases, the minimal configuration is sufficient: ```go @@ -88,9 +89,9 @@ mempoolConfig := &evmmempool.EVMMempoolConfig{ BlockGasLimit: 100_000_000, // or 0 to use default } ``` + -### Full Configuration Options - + ```go type EVMMempoolConfig struct { // Required: AnteHandler for transaction validation @@ -112,6 +113,8 @@ type EVMMempoolConfig struct { MinTip *uint256.Int } ``` + + #### Defaults and Fallbacks diff --git a/docs/evm/next/documentation/getting-started/build-a-chain/additional-configuration/predeployed-contracts.mdx b/docs/evm/next/documentation/getting-started/build-a-chain/additional-configuration/predeployed-contracts.mdx index b817345c..f34ba4b8 100644 --- a/docs/evm/next/documentation/getting-started/build-a-chain/additional-configuration/predeployed-contracts.mdx +++ b/docs/evm/next/documentation/getting-started/build-a-chain/additional-configuration/predeployed-contracts.mdx @@ -24,10 +24,11 @@ There are several methods to deploy preinstalled contracts on a Cosmos EVM chain The most straightforward method for new chains or testnets. Contracts are deployed when the chain is first initialized. -#### Default Configuration - -If uaing the reference `evmd` application, your chain automatically includes default preinstalls, however they will not be active by defaut. + + +If using the reference `evmd` application, your chain automatically includes default preinstalls, however they will not be active by default. + ```go // Source: evmd/genesis.go:28-34 func NewEVMGenesisState() *evmtypes.GenesisState { @@ -37,13 +38,14 @@ func NewEVMGenesisState() *evmtypes.GenesisState { return evmGenState } ``` + + -#### Custom Genesis Configuration - + To customize which contracts are deployed: + ```json -// genesis.json { "app_state": { "evm": { @@ -63,6 +65,9 @@ To customize which contracts are deployed: } } ``` + + + #### Local Development @@ -122,6 +127,7 @@ evmd tx gov vote 1 yes --from mykey Include predeployed contracts as part of a coordinated chain upgrade: + ```go func CreateUpgradeHandler( mm *module.Manager, @@ -138,6 +144,7 @@ func CreateUpgradeHandler( } } ``` + ## Implementation Details @@ -164,6 +171,7 @@ All preinstall deployments undergo strict validation: Predeployed contracts are stored in the chain state like regular contracts: + ```go // Actual deployment process from x/vm/keeper/preinstalls.go func (k *Keeper) AddPreinstalls(ctx sdk.Context, preinstalls []types.Preinstall) error { @@ -205,6 +213,7 @@ func (k *Keeper) AddPreinstalls(ctx sdk.Context, preinstalls []types.Preinstall) return nil } ``` + ## Verification and Testing diff --git a/docs/evm/next/documentation/getting-started/build-a-chain/build-chain-final.mdx b/docs/evm/next/documentation/getting-started/build-a-chain/build-chain-final.mdx new file mode 100644 index 00000000..d0ef5664 --- /dev/null +++ b/docs/evm/next/documentation/getting-started/build-a-chain/build-chain-final.mdx @@ -0,0 +1,2985 @@ +# Chain Configuration: Complete Guide + +**From planning to launch - comprehensive configuration documentation for Cosmos EVM chains** + +This guide provides complete documentation for configuring and launching a Cosmos EVM chain. It covers pre-genesis setup, genesis configuration, runtime settings, network coordination, and post-launch operations. + +Use this as both a planning tool (understanding your options) and an execution manual (step-by-step instructions with verification). + +--- + +## 1. Overview & Quick Start + +### What You'll Configure + +When building your custom Cosmos EVM chain, you'll configure parameters across multiple areas: + +| Configuration Area | When to Configure | Changeable After Genesis | Difficulty | +|-------------------|-------------------|-------------------------|------------| +| **Binary Name** | Before any setup | No (requires new binary) | Easy | +| **Bech32 Prefix** | Before `init` | No (hard fork required) | Easy | +| **BIP44 Coin Type** | Before `init` | No (breaks wallets) | Easy | +| **EVM Chain ID** | Before `init` | No (breaks signatures) | Easy | +| **Token Decimals** | Genesis | No (architectural) | Medium | +| **Bank Metadata** | Genesis | Limited (via governance) | Medium | +| **Precompiles** | Genesis | Yes (via governance) | Medium | +| **Access Control** | Genesis | Yes (via governance) | Easy | +| **Fee Market** | Genesis | Yes (via governance) | Medium | +| **Runtime Config** | Before start | Yes (node-level) | Easy | +| **Network Peers** | Before start | Yes (config file) | Easy | + +### Prerequisites + +Before starting this guide, ensure you have: + +- Go 1.21 or later installed +- Forked or cloned the [cosmos/evm](https://github.com/cosmos/evm) repository +- Basic understanding of Cosmos SDK and EVM concepts +- Decided on your chain's identity (name, token symbol) + +**Estimated Time**: 2-4 hours for initial configuration, additional time for multi-validator coordination + +--- + +## 2. Planning Your Configuration + +Before modifying any code or files, create a planning document with these key decisions. Each parameter links to its detailed configuration section later in this guide. + +### Configuration Planning Worksheet + +Create your own document with these values before starting: + +#### Chain Identity & Branding +- **Binary Name**: `_________________` → [Configure in Section 3.1](#31-fork-repository-and-rename-binary) +- **Cosmos Chain ID**: `_________________-1` → [Configure in Section 4.1](#41-set-cosmos-chain-id) +- **EVM Chain ID**: `_________________` → [Configure in Section 3.4](#34-set-evm-chain-id) +- **Bech32 Prefix**: `_________________` → [Configure in Section 3.2](#32-set-bech32-address-prefix) +- **BIP44 Coin Type**: `60` (recommended) → [Configure in Section 3.3](#33-set-bip44-coin-type) + +#### Token Economics +- **Token Name**: `_________________` → [Configure in Section 4.2](#42-configure-bank-metadata) +- **Token Symbol**: `_________________` → [Configure in Section 4.2](#42-configure-bank-metadata) +- **Decimals**: `18` (recommended) / `6` / Other → [Configure in Section 3.5](#35-choose-token-decimal-precision) +- **Base Denom**: `_________________` → [Configure in Sections 3.6 & 4.2](#36-configure-default-token-denomination-in-source-code) +- **Display Denom**: `_________________` → [Configure in Section 4.2](#42-configure-bank-metadata) +- **Genesis Supply**: `_________________` → [Configure in Section 4.13](#413-add-genesis-accounts-with-initial-balances) +- **Inflation Enabled**: Yes / No → [Configure in Section 4.11](#411-configure-mint-parameters) + +#### EVM & Smart Contracts +- **Precompiles to Enable**: → [Configure in Section 4.6](#46-enable-required-precompiles) + - `[ ]` 0x0100 - P256 + - `[ ]` 0x0400 - Bech32 + - `[ ]` 0x0800 - Staking + - `[ ]` 0x0801 - Distribution + - `[ ]` 0x0802 - ICS20 + - `[ ]` 0x0803 - Vesting + - `[ ]` 0x0804 - Bank + - `[ ]` 0x0805 - Governance + - `[ ]` 0x0806 - Slashing + - `[ ]` 0x0807 - Authz +- **Deployment Permissions**: Permissionless / Permissioned / Restricted → [Configure in Section 4.8](#48-configure-evm-access-control) +- **Fee Market**: EIP-1559 (recommended) / Fixed → [Configure in Section 4.9](#49-configure-eip-1559-fee-market) + +#### Governance & Validators +- **Unbonding Time**: `_______` days → [Configure in Section 4.10](#410-configure-staking-parameters) +- **Max Validators**: `_______` → [Configure in Section 4.10](#410-configure-staking-parameters) +- **Voting Period**: `_______` (30s testnet / 2d mainnet) → [Configure in Section 4.12](#412-configure-governance-parameters) +- **Min Deposit**: `_______` → [Configure in Section 4.12](#412-configure-governance-parameters) + +#### Network Configuration +- **Network Type**: Local / Testnet / Mainnet +- **Genesis Validators**: `_______` +- **Public RPC Nodes**: `_______` +- **Genesis Time**: `_______` → [Configure in Section 4.1](#41-set-genesis-time) + + +Save this planning document for reference throughout the configuration process. You'll use these values in multiple sections. + + +--- + +## 3. Pre-Genesis Setup + + +**CRITICAL TIMING SECTION** + +Everything in this section MUST be completed BEFORE running `yourchain init`. + +These settings CANNOT be changed after genesis without a hard fork. + +Do not proceed to genesis configuration until all items in this section are complete and verified. + + + +**Why This Section Exists** + +These parameters are compiled into your binary or written to configuration files during initialization. Changing them later requires: +- Rebuilding the binary +- Re-initializing all nodes +- Coordinating a network restart +- In some cases, a hard fork + +This section ensures you set everything correctly the first time. + + +--- + +### 3.1. Fork Repository and Rename Binary + +**What This Does**: Renames your blockchain binary from `evmd` to your chosen name and updates all Go import paths to match your project. + + + + + + + + +```bash +cd /path/to/cosmos-evm +mv evmd yourchain +``` + + + +```bash +# macOS +find . -type f -name "*.go" -exec sed -i '' \ + 's|github.com/cosmos/evm/evmd|github.com/your-org/your-chain/yourchain|g' {} \; + +# Linux +find . -type f -name "*.go" -exec sed -i \ + 's|github.com/cosmos/evm/evmd|github.com/your-org/your-chain/yourchain|g' {} \; +``` + + + +Edit `go.mod` manually: + +```go +// Change this: +module github.com/cosmos/evm + +// To this: +module github.com/your-org/your-chain +``` + + + +```bash +sed -i '' 's/evmd/yourchain/g' Makefile +``` + + + +```bash +go mod tidy +``` + + + +```bash +make build +./build/yourchain version +``` + + + + + + + + +```bash +# 1. Binary exists with new name +ls -la ./build/yourchain + +# 2. Version command works +./build/yourchain version + +# 3. No references to old name +grep -r "github.com/cosmos/evm/evmd" . --include="*.go" | wc -l +# Should output: 0 +``` + + + + + +**Files Modified**: +- `evmd/` → `yourchain/` (directory rename) +- All `*.go` files (import paths) +- `go.mod` (module declaration) +- `Makefile` (binary references) + + + + + +--- + +### 3.2. Set Bech32 Address Prefix + +**What This Does**: Defines your chain's address format (e.g., `cosmos1...`, `evmos1...`, `yourchain1...`). + +**File**: `config/config.go:62` + +**Default**: `cosmos` + + + + + +Edit `config/config.go`: + +```go +const ( + // Bech32Prefix defines the Bech32 prefix for your chain + Bech32Prefix = "yourchain" + + // 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 +) +``` + +Rebuild binary: +```bash +make build +``` + + + + + +After initialization (in later steps): + +```bash +# Create a test key +yourchain keys add test --keyring-backend test + +# Check address format starts with your prefix +yourchain keys show test --keyring-backend test +# Expected: yourchain1abc123... +``` + + + + + +Your Bech32 prefix determines all address formats: +- **Account addresses**: `yourchain1abc123...` +- **Validator operator**: `yourchainvaloper1abc123...` +- **Consensus addresses**: `yourchainvalcons1abc123...` +- **Account public keys**: `yourchainpub1abc123...` + + + + + +**Source**: [config/config.go:60-74](https://github.com/cosmos/evm/blob/main/config/config.go#L60-L74) + +--- + +### 3.3. Set BIP44 Coin Type + +**What This Does**: Sets the HD wallet derivation path for key generation following BIP-44 standard. + +**File**: `crypto/hd/hdpath.go:9` + +**Default**: `60` (Ethereum compatibility) + + + + + + + + + +**Use coin type `60`** - No changes needed (this is the default) + +```go +var ( + // Bip44CoinType satisfies EIP84 + Bip44CoinType uint32 = 60 // Ethereum compatibility + + // BIP44HDPath is the default BIP44 HD path + BIP44HDPath = ethaccounts.DefaultBaseDerivationPath.String() +) +``` + +**Derivation Path**: `m/44'/60'/0'/0/0` + +**Benefits**: +- Works with MetaMask and Ethereum wallets +- Standard for EVM-compatible chains +- No wallet configuration needed + + + + + +**Register and use a unique value** + +1. Register at [SLIP-0044](https://github.com/satoshilabs/slips/blob/master/slip-0044.md) +2. Update code: + +```go +var ( + // Bip44CoinType for your unique chain + Bip44CoinType uint32 = 12345 // Your registered value + + BIP44HDPath = ethaccounts.DefaultBaseDerivationPath.String() +) +``` + +**Use When**: Need distinct identity from Ethereum ecosystem + + + + + +Rebuild binary: +```bash +make build +``` + + + + + +After initialization: + +```bash +# Create a test key +yourchain keys add test --keyring-backend test + +# Key uses configured derivation path +# With coin type 60: m/44'/60'/0'/0/0 +``` + + + + + +**Source**: [crypto/hd/hdpath.go:7-13](https://github.com/cosmos/evm/blob/main/crypto/hd/hdpath.go#L7-L13) + +--- + +### 3.4. Set EVM Chain ID + +**What This Does**: Sets the EIP-155 chain ID for Ethereum transaction replay protection. This is what wallets like MetaMask use to identify your network. + +**File**: `config/config.go:78` + +**Type**: Number (uint64) + +**Default**: `262144` + + +**CRITICAL**: Choose carefully - cannot be changed after genesis without breaking all transaction signatures and wallet configurations. + + + + + + +Edit `config/config.go`: + +```go +const ( + // EVMChainID defines the EIP-155 replay-protection chain id + EVMChainID = 123456 // Your unique chain ID +) +``` + +Rebuild binary: +```bash +make build +``` + + + + + +**For Testing**: +- Use `262144` (evmd default) +- Or any high number > 100,000 +- No registration needed + +**For Production**: +1. Choose unique integer +2. Check [chainlist.org](https://chainlist.org) for conflicts +3. Register your chain ID +4. Document publicly + +**Avoid**: `1`, `56`, `137`, `10`, `42161` (see chainlist.org for full list) + + + + + +After initialization: + +```bash +# Check chain ID was written to app.toml +grep 'evm-chain-id' ~/.yourchain/config/app.toml +# Expected: evm-chain-id = 123456 +``` + + + + + +**During `init`**: Value from `config/config.go:78` → written to `app.toml` as `evm-chain-id` + +**During startup**: Node reads `evm-chain-id` from `app.toml` + +**In wallets**: MetaMask uses this ID to identify your network + + + + + +**Source**: [config/config.go:77-78](https://github.com/cosmos/evm/blob/main/config/config.go#L77-L78) + +--- + +### 3.5. Choose Token Decimal Precision + +**What This Does**: Determines whether your native token uses 18 decimals (like ETH) or 6 decimals (like ATOM). + +**Recommendation**: Use 18 decimals for simplicity and native EVM compatibility + + +This decision affects: +- Which modules you need (`x/bank` only vs. `x/precisebank`) +- EVM precision handling +- User experience with decimal places +- Cannot change after genesis without hard fork + + + + + + +**Native EVM Compatibility - No Extra Modules Required** + +**Configuration**: +- Base denom: `atoken` (atto-token, 10^-18) +- Display denom: `token` +- 1 token = 1,000,000,000,000,000,000 atoken + +**Advantages**: +- ✅ Direct 1:1 mapping with EVM +- ✅ No PreciseBank module needed +- ✅ Simpler architecture +- ✅ Standard for EVM chains + +**Setup**: +- Use standard `x/bank` module only +- No code changes needed beyond setting denomination names +- Skip extended_denom_options + + + + + +**Traditional Cosmos Precision - Requires Additional Module** + +**Configuration**: +- Base denom: `utoken` (micro-token, 10^-6) +- Display denom: `token` +- 1 token = 1,000,000 utoken + +**Requirements**: +- ✅ Must add `x/precisebank` module to `app.go` +- ✅ Must configure `extended_denom_options` in genesis +- ✅ Use `PreciseBankKeeper` in EVMKeeper + +**PreciseBank Integration** (in `app.go`): + +```go +import ( + precisebankkeeper "github.com/cosmos/evm/x/precisebank/keeper" + precisebanktypes "github.com/cosmos/evm/x/precisebank/types" + precisebank "github.com/cosmos/evm/x/precisebank" +) + +// Add to store keys +keys := storetypes.NewKVStoreKeys( + // ... other keys + precisebanktypes.StoreKey, +) + +// Initialize PreciseBankKeeper +app.PreciseBankKeeper = precisebankkeeper.NewKeeper( + appCodec, + keys[precisebanktypes.StoreKey], + app.BankKeeper, + app.AccountKeeper, +) + +// CRITICAL: Use PreciseBankKeeper in EVMKeeper +app.EVMKeeper = evmkeeper.NewKeeper( + appCodec, + keys[evmtypes.StoreKey], + app.GetSubspace(evmtypes.ModuleName), + app.AccountKeeper, + app.PreciseBankKeeper, // Not BankKeeper! + app.StakingKeeper, + app.FeeMarketKeeper, + authtypes.NewModuleAddress(govtypes.ModuleName).String(), +) + +// Add to module manager +app.ModuleManager = module.NewManager( + // ... other modules + precisebank.NewAppModule(app.PreciseBankKeeper, app.AccountKeeper), +) + +// Add to genesis order (after bank, before evm) +genesisModuleOrder := []string{ + // ... + banktypes.ModuleName, + precisebanktypes.ModuleName, + evmtypes.ModuleName, + // ... +} +``` + + +Failure to add PreciseBank will result in incorrect balances and transaction failures. + + + + + + +| Prefix | Decimals | Example | Used For | +|--------|----------|---------|----------| +| `a` (atto) | 18 | `atoken` | EVM chains (recommended) | +| `u` (micro) | 6 | `utoken` | Cosmos chains | +| `n` (nano) | 9 | `ntoken` | Some L2s | + + + + + + +**Learn More:** +- [Precision Handling Concepts](/docs/evm/next/documentation/concepts/precision-handling) +- [PreciseBank Module Reference](/docs/evm/next/documentation/cosmos-sdk/modules/precisebank) + + +--- + +### 3.6. Configure Default Token Denomination in Source Code + +**What This Does**: Changes hardcoded defaults so generated configs use your token instead of "aatom"/"atom". + + +Must be done BEFORE `yourchain init` and BEFORE building the binary. + + + + + + + + + + +**File**: `server/config/migration/v0.50-app.toml:11` + +```bash +# Change from: +minimum-gas-prices = "0aatom" + +# To (example): +minimum-gas-prices = "0atoken" +``` + +Using sed: +```bash +sed -i '' 's/minimum-gas-prices = "0aatom"/minimum-gas-prices = "0atoken"/' \ + server/config/migration/v0.50-app.toml +``` + + + + + +**File**: `x/vm/types/params.go:21-25` + +For **18 decimals**: +```go +var ( + DefaultEVMDenom = "atoken" + DefaultEVMExtendedDenom = "atoken" + DefaultEVMDisplayDenom = "token" +) +``` + +For **6 decimals**: +```go +var ( + DefaultEVMDenom = "utoken" + DefaultEVMExtendedDenom = "atoken" + DefaultEVMDisplayDenom = "token" +) +``` + + + + + +**File**: `config/constants.go:5-8` + +```go +const ( + ExampleChainDenom = "atoken" // Your base denom + ExampleDisplayDenom = "token" // Your display denom +) +``` + + + + + +```bash +make build +``` + + + + + + + + + +After initialization: + +```bash +# Check generated app.toml uses your denomination +grep "minimum-gas-prices" ~/.yourchain/config/app.toml +# Expected: minimum-gas-prices = "0atoken" +``` + + + + + +**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) + +--- + +### Pre-Genesis Completion Checklist + +Before proceeding to Section 4, verify all pre-genesis setup is complete: + +```bash +# 1. Binary renamed and built +./build/yourchain version +# ✓ Should show your chain name, not "evmd" + +# 2. Bech32 prefix set in code +grep "Bech32Prefix = " config/config.go +# ✓ Should show your prefix + +# 3. BIP44 coin type set in code +grep "Bip44CoinType uint32 = " crypto/hd/hdpath.go +# ✓ Should show your coin type (typically 60) + +# 4. EVM chain ID set in code +grep "EVMChainID = " config/config.go +# ✓ Should show your EVM chain ID + +# 5. Token decimals decided +# ✓ 18 decimals → No PreciseBank needed +# ✓ 6 decimals → PreciseBank integrated in app.go + +# 6. Default denominations updated in source +grep "DefaultEVMDenom = " x/vm/types/params.go +grep "minimum-gas-prices" server/config/migration/v0.50-app.toml +# ✓ Should show your denomination +``` + + +**DO NOT PROCEED** until all items are verified. These settings cannot be changed after `yourchain init` without starting over. + + +--- + +## 4. Genesis Configuration + +Now that your binary is configured, initialize your chain and configure genesis parameters. + +### Initialize Your Chain + +```bash +yourchain init --chain-id +``` + +**Example**: +```bash +yourchain init mynode --chain-id mychain-1 +``` + +This creates `~/.yourchain/` with: +- `config/genesis.json` - You'll edit this +- `config/app.toml` - Runtime configuration +- `config/config.toml` - CometBFT configuration +- `data/` - Blockchain data + + +Set environment variable for easier commands: + +```bash +export GENESIS=~/.yourchain/config/genesis.json +``` + + +--- + +### 4.1. Set Genesis Time + +**What This Does**: Sets UTC timestamp when chain starts producing blocks. + +**Genesis Location**: Root level `genesis_time` + + + + + +```bash +jq '.genesis_time = "2024-12-01T00:00:00Z"' $GENESIS > tmp && mv tmp $GENESIS +``` + +**For local testing**: Use current time or leave default (immediate start) + +**For coordinated launch**: Set 24-48 hours in future to allow validator preparation + + + + + +- All validators must have identical genesis_time +- Chain auto-starts at this time when 2/3+ validators online +- Validators start nodes before genesis_time +- If genesis_time is past, chain starts immediately + + + + + +```bash +jq '.genesis_time' $GENESIS +# Output: "2024-12-01T00:00:00Z" +``` + + + + + +--- + +### 4.2. Configure Bank Metadata + +**What This Does**: Defines token denomination, decimal precision, and display properties. + +**Genesis Location**: `app_state.bank.denom_metadata` + + +The `base` denomination MUST match: +- `app_state.evm.params.evm_denom` +- `app_state.staking.params.bond_denom` +- `app_state.mint.params.mint_denom` +- `app_state.gov.params.min_deposit[0].denom` + + + + + + +```bash +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" +}]' $GENESIS > tmp && mv tmp $GENESIS +``` + + + + + +```bash +jq '.app_state.bank.denom_metadata=[{ + "description": "The native staking and gas token", + "denom_units": [ + { + "denom": "utoken", + "exponent": 0, + "aliases": ["microtoken"] + }, + { + "denom": "token", + "exponent": 6, + "aliases": [] + } + ], + "base": "utoken", + "display": "token", + "name": "My Token", + "symbol": "TKN" +}]' $GENESIS > tmp && mv tmp $GENESIS +``` + + +Also requires `extended_denom_options` (see Section 4.4) + + + + + + +| Field | Description | Example | +|-------|-------------|---------| +| `base` | Smallest unit (on-chain) | `atoken`, `utoken` | +| `display` | Human-readable unit | `token` | +| `exponent` | Decimal places | `18` or `6` | +| `name` | Full token name | `"My Token"` | +| `symbol` | Ticker symbol | `"TKN"` | + + + + + +```bash +jq '.app_state.bank.denom_metadata' $GENESIS +``` + + + + + +--- + +### 4.3. Set EVM Denom + +**What This Does**: Specifies which bank denomination is the native EVM gas token. + +**Genesis Location**: `app_state.evm.params.evm_denom` + + + + + +```bash +# For 18-decimal token +jq '.app_state.evm.params.evm_denom = "atoken"' $GENESIS > tmp && mv tmp $GENESIS + +# For 6-decimal token +jq '.app_state.evm.params.evm_denom = "utoken"' $GENESIS > tmp && mv tmp $GENESIS +``` + + + + + +```bash +jq '.app_state.evm.params.evm_denom' $GENESIS +# Must match bank metadata base denom +``` + + + + + +**Source**: [x/vm/types/params.go:21](https://github.com/cosmos/evm/blob/main/x/vm/types/params.go#L21) + +--- + +### 4.4. Configure Extended Denom Options + +**What This Does**: Provides 18-decimal representation for EVM when using non-18 decimal native token. + +**Genesis Location**: `app_state.evm.params.extended_denom_options` + +**Required For**: 6-decimal chains or other non-18 decimal configurations + + + + + +```bash +jq '.app_state.evm.params.extended_denom_options = { + "extended_denom": "atoken" +}' $GENESIS > tmp && mv tmp $GENESIS +``` + +**Example Genesis**: +```json +{ + "app_state": { + "evm": { + "params": { + "evm_denom": "utoken", + "extended_denom_options": { + "extended_denom": "atoken" + } + } + } + } +} +``` + + +Must also have PreciseBank module integrated in app.go (see Section 3.5) + + + + + + +- Base denom: `utoken` (6 decimals) +- EVM sees: `atoken` (18 decimals) +- PreciseBank converts: 1 utoken = 10^12 wei + + + + + +Not needed for 18-decimal tokens. Leave this section empty. + + + + + +**Source**: [x/vm/types/params.go:76](https://github.com/cosmos/evm/blob/main/x/vm/types/params.go#L76) + +--- + +### 4.5. Configure ERC20 Token Pairs + +**What This Does**: Creates ERC20 representation of your native token for EVM compatibility. + +**Genesis Location**: `app_state.erc20.token_pairs` and `app_state.erc20.native_precompiles` + +**Special Address**: `0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE` (native token) + + + + + +```bash +# Set token pair +jq '.app_state.erc20.token_pairs = [{ + "erc20_address": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE", + "denom": "atoken", + "enabled": true, + "contract_owner": 1 +}]' $GENESIS > tmp && mv tmp $GENESIS + +# Set native precompile +jq '.app_state.erc20.native_precompiles = ["0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE"]' $GENESIS > tmp && mv tmp $GENESIS +``` + +**Note**: Replace `"atoken"` with your base denomination + + + + + +| Field | Value | Description | +|-------|-------|-------------| +| `erc20_address` | Special address | Native token ERC20 address | +| `denom` | Your base denom | Must match bank metadata | +| `enabled` | `true` | Token pair is active | +| `contract_owner` | `1` | Module-owned | + + + + + +```bash +jq '.app_state.erc20.token_pairs' $GENESIS +jq '.app_state.erc20.native_precompiles' $GENESIS +``` + + + + + + +**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) + + +--- + +### 4.6. Enable Required Precompiles + +**What This Does**: Enables precompiled contracts that provide Cosmos SDK functionality to EVM. + +**Genesis Location**: `app_state.evm.params.active_static_precompiles` + + + + + +| Address | Name | Purpose | +|---------|------|---------| +| `0x0100` | P256 | Web3 auth, passkeys | +| `0x0400` | Bech32 | Address conversion | +| `0x0800` | Staking | Validator operations | +| `0x0801` | Distribution | Reward claiming | +| `0x0802` | ICS20 | IBC transfers | +| `0x0803` | Vesting | Token vesting | +| `0x0804` | Bank | Native transfers | +| `0x0805` | Governance | On-chain voting | +| `0x0806` | Slashing | Validator info | +| `0x0807` | Authz | Permissions | + + + + + +```bash +jq '.app_state.evm.params.active_static_precompiles = [ + "0x0000000000000000000000000000000000000100", + "0x0000000000000000000000000000000000000400", + "0x0000000000000000000000000000000000000800", + "0x0000000000000000000000000000000000000801", + "0x0000000000000000000000000000000000000802", + "0x0000000000000000000000000000000000000803", + "0x0000000000000000000000000000000000000804", + "0x0000000000000000000000000000000000000805", + "0x0000000000000000000000000000000000000806", + "0x0000000000000000000000000000000000000807" +]' $GENESIS > tmp && mv tmp $GENESIS +``` + + + + + +Example for DeFi-focused chain: + +```bash +jq '.app_state.evm.params.active_static_precompiles = [ + "0x0000000000000000000000000000000000000100", # P256 + "0x0000000000000000000000000000000000000400", # Bech32 + "0x0000000000000000000000000000000000000800", # Staking + "0x0000000000000000000000000000000000000804" # Bank +]' $GENESIS > tmp && mv tmp $GENESIS +``` + + + + + +```bash +jq '.app_state.evm.params.active_static_precompiles' $GENESIS +``` + + + + + + +**Learn More**: [Precompiles Overview](/docs/evm/next/documentation/smart-contracts/precompiles/overview) + + +**Source**: [x/vm/types/precompiles.go:22-32](https://github.com/cosmos/evm/blob/main/x/vm/types/precompiles.go#L22-L32) + +--- + +### 4.7. Configure Predeployed Contracts + +**What This Does**: Deploys essential smart contracts at genesis to standard addresses. + +**Genesis Location**: `app_state.evm.preinstalls` + + + + + +Automatically deployed during init: + +1. **CREATE2 Deployer** (`0x4e59b44847b379578588920cA78FbF26c0B4956C`) + - Deterministic contract deployment + +2. **Multicall3** (`0xcA11bde05977b3631167028862bE2a173976CA11`) + - Batch multiple read calls + +3. **Permit2** (`0x000000000022D473030F116dDEE9F6B43aC78BA3`) + - Uniswap's token approval system + +4. **Safe Factory** (`0x4e1DCf7AD4e460CfD30791CCC4F9c8a4f820ec67`) + - Gnosis Safe multisig deployment + + + + + +```bash +jq '.app_state.evm.preinstalls' $GENESIS +``` + + +These contracts are hardcoded and automatically included. No manual configuration needed. + + + + + + +--- + +### 4.8. Configure EVM Access Control + +**What This Does**: Sets permissions for deploying and calling smart contracts. + +**Genesis Location**: `app_state.evm.params.access_control` + + + + + +| Type | Value | Behavior | +|------|-------|----------| +| Permissionless | `0` | Anyone can perform action | +| Restricted | `1` | Block addresses in list | +| Permissioned | `2` | Only addresses in list | + + + + + +```bash +jq '.app_state.evm.params.access_control = { + "create": { + "access_type": 0, + "access_control_list": [] + }, + "call": { + "access_type": 0, + "access_control_list": [] + } +}' $GENESIS > tmp && mv tmp $GENESIS +``` + +**Use For**: Public chains, testnets, open ecosystems + + + + + +```bash +jq '.app_state.evm.params.access_control = { + "create": { + "access_type": 2, + "access_control_list": [ + "0x1234567890123456789012345678901234567890", + "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd" + ] + }, + "call": { + "access_type": 0, + "access_control_list": [] + } +}' $GENESIS > tmp && mv tmp $GENESIS +``` + +**Use For**: Enterprise chains, controlled deployment + + + + + +```bash +jq '.app_state.evm.params.access_control.create = { + "access_type": 1, + "access_control_list": [ + "0xBADADDRESS1234567890123456789012345678" + ] +}' $GENESIS > tmp && mv tmp $GENESIS +``` + +**Use For**: Blocking known malicious addresses + + + + + +```bash +jq '.app_state.evm.params.access_control' $GENESIS +``` + + + + + +**Source**: [x/vm/types/params.go:160-165](https://github.com/cosmos/evm/blob/main/x/vm/types/params.go#L160-L165) + +--- + +### 4.9. Configure EIP-1559 Fee Market + +**What This Does**: Configures Ethereum's EIP-1559 dynamic fee market for automatic fee adjustment. + +**Genesis Location**: `app_state.feemarket.params` + + + + + +```bash +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 +}' $GENESIS > tmp && mv tmp $GENESIS +``` + +**Use For**: Standard Ethereum-compatible chains + + + + + +| Parameter | Default | Description | +|-----------|---------|-------------| +| `no_base_fee` | `false` | Enable EIP-1559 | +| `base_fee` | `"1000000000"` | 1 gwei initial | +| `base_fee_change_denominator` | `8` | ±12.5% max change | +| `elasticity_multiplier` | `2` | Target = 50% max gas | +| `min_gas_price` | `"0"` | Network minimum | +| `min_gas_multiplier` | `"0.5"` | 50% of base fee | +| `enable_height` | `0` | Enabled from genesis | + + + + + +```bash +jq '.app_state.feemarket.params = { + "no_base_fee": true, + "min_gas_price": "1000000000" +}' $GENESIS > tmp && mv tmp $GENESIS +``` + +**Use For**: Traditional Cosmos chains or testing + + + + + +```bash +jq '.app_state.feemarket.params' $GENESIS +``` + + + + + + +**Learn More**: [EIP-1559 Fee Market Concepts](/docs/evm/next/documentation/concepts/eip-1559-feemarket) + + +**Source**: [x/feemarket/types/params.go:13-21](https://github.com/cosmos/evm/blob/main/x/feemarket/types/params.go#L13-L21) + +--- + +### 4.10. Configure Staking Parameters + +**What This Does**: Configures validator staking, unbonding periods, and related parameters. + +**Genesis Location**: `app_state.staking.params` + + + + + +```bash +# Set bond denomination +jq '.app_state.staking.params.bond_denom = "atoken"' $GENESIS > tmp && mv tmp $GENESIS + +# Set unbonding time +jq '.app_state.staking.params.unbonding_time = "1814400s"' $GENESIS > tmp && mv tmp $GENESIS + +# Set max validators +jq '.app_state.staking.params.max_validators = 100' $GENESIS > tmp && mv tmp $GENESIS +``` + + + + + +| Parameter | Default | Description | +|-----------|---------|-------------| +| `bond_denom` | - | Must match your base denom | +| `unbonding_time` | `"1814400s"` | 21 days | +| `max_validators` | `100` | Maximum active validators | +| `max_entries` | `7` | Max concurrent operations | +| `historical_entries` | `10000` | For IBC light clients | + +**Unbonding Time Examples**: +- `"120s"` = 2 minutes (testing) +- `"604800s"` = 7 days +- `"1814400s"` = 21 days (Cosmos standard) +- `"2419200s"` = 28 days + + + + + +```bash +jq '.app_state.staking.params' $GENESIS +``` + + + + + +--- + +### 4.11. Configure Mint Parameters + +**What This Does**: Configures token inflation and minting schedule. + +**Genesis Location**: `app_state.mint.params` + + + + + +```bash +jq '.app_state.mint.params.mint_denom = "atoken"' $GENESIS > tmp && mv tmp $GENESIS +``` + +**Complete Parameters**: +```json +{ + "mint_denom": "atoken", + "inflation_rate_change": "0.130000000000000000", + "inflation_max": "0.200000000000000000", + "inflation_min": "0.070000000000000000", + "goal_bonded": "0.670000000000000000", + "blocks_per_year": "6311520" +} +``` + + + + + +| Parameter | Default | Description | +|-----------|---------|-------------| +| `mint_denom` | - | Must match base denom | +| `inflation_max` | `0.20` | 20% max annual | +| `inflation_min` | `0.07` | 7% min annual | +| `goal_bonded` | `0.67` | 67% target staked | + + + + + +```bash +jq '.app_state.mint.params' $GENESIS +``` + + + + + +--- + +### 4.12. Configure Governance Parameters + +**What This Does**: Configures on-chain governance including voting periods and requirements. + +**Genesis Location**: `app_state.gov.params` + + + + + +```bash +# Set deposit denomination +jq '.app_state.gov.params.min_deposit[0].denom = "atoken"' $GENESIS > tmp && mv tmp $GENESIS + +# Set voting period +jq '.app_state.gov.params.voting_period = "172800s"' $GENESIS > tmp && mv tmp $GENESIS + +# For testnet (fast testing) +jq '.app_state.gov.params.voting_period = "30s"' $GENESIS > tmp && mv tmp $GENESIS +``` + + + + + +| Parameter | Default | Description | +|-----------|---------|-------------| +| `min_deposit` | - | Minimum to submit proposal | +| `voting_period` | `"172800s"` | 2 days (mainnet) | +| `quorum` | `"0.334"` | 33.4% participation | +| `threshold` | `"0.5"` | 50% yes votes | +| `veto_threshold` | `"0.334"` | 33.4% veto | + +**Voting Period**: +- Testnet: `"30s"` +- Mainnet: `"172800s"` (2 days) or `"604800s"` (7 days) + + + + + +```bash +jq '.app_state.gov.params' $GENESIS +``` + + + + + +--- + +### 4.13. Add Genesis Accounts with Initial Balances + +**What This Does**: Creates accounts with initial token balances at genesis. + + + + + +```bash +# Using address +yourchain genesis add-genesis-account \ + cosmos1abc123... \ + 1000000000000000000000atoken + +# Using key name from keyring +yourchain genesis add-genesis-account \ + validator1 \ + 1000000000000000000000atoken \ + --keyring-backend test +``` + + + + + +```bash +yourchain genesis add-genesis-account validator1 1000000000000000000000atoken +yourchain genesis add-genesis-account validator2 1000000000000000000000atoken +yourchain genesis add-genesis-account faucet 10000000000000000000000atoken +``` + + + + + +```bash +# Create accounts file +cat > accounts.json < + + + +```bash +jq '.app_state.bank.balances' $GENESIS +``` + + + + + +--- + +### 4.14. Collect Validator Genesis Transactions + +**What This Does**: Gathers validator self-delegation transactions for genesis. + + + + + +```bash +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**: `~/.yourchain/config/gentx/gentx-.json` + + + + + +```bash +# Receive all gentx files from validators +mkdir -p ~/.yourchain/config/gentx/ +# Copy received gentx files to this directory + +# Collect into genesis +yourchain genesis collect-gentxs +``` + + + + + +```bash +yourchain genesis validate +jq '.app_state.genutil.gen_txs' $GENESIS +``` + + + + + +--- + +### 4.15. Validate Final Genesis File + +**What This Does**: Validates genesis file for correctness before network launch. + + + + + +```bash +yourchain genesis validate +``` + + + + + +- JSON structure is valid +- All module genesis states are valid +- No denomination mismatches +- Token supply is consistent +- All parameters within valid ranges +- Gentxs are valid + + + + + +```bash +# 1. Validate structure +yourchain genesis validate + +# 2. Check all denoms match +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 identical) + +# 3. Verify total supply +jq '.app_state.bank.balances | map(.coins[0].amount | tonumber) | add' $GENESIS + +# 4. Check validator count +jq '.app_state.genutil.gen_txs | length' $GENESIS +``` + + + + + +**Denomination Mismatch**: +``` +Error: bond_denom (utoken) does not match evm_denom (atoken) +``` +Fix: Ensure all denoms match across modules + +**Invalid Supply**: +``` +Error: total supply does not match balances +``` +Fix: Check genesis accounts and recalculate + +**Invalid Parameter**: +``` +Error: min_gas_multiplier must be between 0 and 1 +``` +Fix: Correct parameter value + + + + + +--- + +## 5. Runtime Configuration + +Configure `~/.yourchain/config/app.toml` for runtime settings. + +### 5.1. Configure JSON-RPC + +**What This Does**: Configures Ethereum JSON-RPC server for wallet/dApp access. + +**File**: `~/.yourchain/config/app.toml` + +**Section**: `[json-rpc]` + + + + + +```toml +[json-rpc] +# Enable JSON-RPC server +enable = true + +# HTTP server address +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 + +# Allow unprotected transactions (dev only!) +allow-unprotected-txs = false + +# Enable transaction indexer +enable-indexer = true +``` + + + + + +| Namespace | Description | Recommended For | +|-----------|-------------|-----------------| +| `eth` | Standard Ethereum RPC | All nodes (required) | +| `net` | Network information | All nodes | +| `web3` | Web3 client version | All nodes | +| `txpool` | Transaction pool | Dev/monitoring | +| `debug` | Debug/trace endpoints | Dev only (not prod) | + + + + + +**For Production**: +- Use `address = "127.0.0.1:8545"` + reverse proxy +- Enable rate limiting +- Set `allow-unprotected-txs = false` +- Remove `debug` from API namespaces + +**For Development**: +- Use `address = "0.0.0.0:8545"` for network access +- Enable all APIs including `debug` +- Set `allow-unprotected-txs = true` for convenience + + + + + +--- + +### 5.2. Configure EVM Settings + +**What This Does**: EVM execution configuration including tracer and gas limits. + +**File**: `~/.yourchain/config/app.toml` + +**Section**: `[evm]` + + + + + +```toml +[evm] +# EVM chain ID (read-only, set during init) +evm-chain-id = 262144 + +# Tracer type for debugging +tracer = "" + +# Maximum gas limit per transaction (0 = unlimited) +max-tx-gas-wanted = 0 + +# Cache preimages for historical queries +cache-preimage = false + +# Minimum tip (priority fee) in wei +min-tip = 1000000000 + +# Geth metrics server address +geth-metrics-address = "127.0.0.1:8100" +``` + + + + + +| Parameter | Default | Description | +|-----------|---------|-------------| +| `evm-chain-id` | From init | Read-only, don't modify | +| `tracer` | `""` | `"json"` for debug, `""` for prod | +| `max-tx-gas-wanted` | `0` | Transaction gas limit | +| `min-tip` | `0` | Minimum priority fee (wei) | + + + + + + +`evm-chain-id` is written during init and should NOT be manually edited. + +To change it: +1. Modify `config/config.go:78` +2. Rebuild binary +3. Re-run init + + + + + + +--- + +### 5.3. Configure EVM Mempool + +**What This Does**: Controls transaction pool behavior including price limits and queue sizes. + +**File**: `~/.yourchain/config/app.toml` + +**Section**: `[evm.mempool]` + + +**New in v0.5.0**: Mempool configuration now fully exposed in `app.toml` + + + + + + +```toml +[evm.mempool] +# Minimum gas price to accept (wei) +price-limit = 1000000000 + +# Minimum % price increase to replace transaction +price-bump = 10 + +# Executable transaction slots per account +account-slots = 16 + +# Total executable slots for all accounts +global-slots = 5120 + +# Queued transaction slots per account +account-queue = 64 + +# Total queued slots for all accounts +global-queue = 1024 + +# Maximum time transactions stay in queue +lifetime = "3h0m0s" +``` + + + + + +| Parameter | Default | Description | +|-----------|---------|-------------| +| `price-limit` | `1` | Min gas price (wei) | +| `price-bump` | `10` | Min % increase to replace (10%) | +| `account-slots` | `16` | Guaranteed slots per account | +| `global-slots` | `5120` | Total executable slots | +| `account-queue` | `64` | Queued slots per account | +| `global-queue` | `1024` | Total queued slots | +| `lifetime` | `"3h0m0s"` | Max time in mempool | + + + + + +**High-Throughput Chain**: +```toml +global-slots = 10240 +global-queue = 2048 +price-limit = 100000000 +lifetime = "6h0m0s" +``` + +**Low-Resource Node**: +```toml +global-slots = 2048 +global-queue = 512 +lifetime = "1h0m0s" +account-slots = 8 +``` + + + + + +**Source**: [server/config/config.go:158-187](https://github.com/cosmos/evm/blob/main/server/config/config.go#L158-L187) + +--- + +### 5.4. Set Minimum Gas Prices + +**What This Does**: Node-level minimum gas price that rejects lower-priced transactions. + +**File**: `~/.yourchain/config/app.toml` + +**Format**: `` + + + + + +```toml +minimum-gas-prices = "1000000000atoken" +``` + +**Examples**: +- `"1000000000atoken"` = 1 gwei +- `"500000000atoken"` = 0.5 gwei +- `"0atoken"` = accept all (not recommended) + + + + + +- Node rejects transactions below this price +- Protects against spam +- Should align with genesis fee market config +- Each node can set independently + + + + + +--- + +### 5.5. Configure Network Peers + +**What This Does**: Sets persistent peer connections for network participation. + +**File**: `~/.yourchain/config/config.toml` + + + + + +Each node runs: +```bash +yourchain comet show-node-id +``` + +Output: `7c90e16cca334eb7259754f964918d879ca54996` + +**Share**: `@:` + +Example: `7c90e16cca334eb7259754f964918d879ca54996@192.168.1.100:26656` + + + + + +Edit `~/.yourchain/config/config.toml`: + +```toml +# Comma-separated list of persistent peers +persistent_peers = "7c90e16c@192.168.1.100:26656,abc123de@192.168.1.101:26656,def456ab@192.168.1.102:26656" +``` + + + + + +```bash +curl localhost:26657/net_info | jq '.result.peers' +``` + + + + + +--- + +### 5.6. Set Client Chain ID + +**What This Does**: Sets chain-id in client configuration for CLI operations and node startup validation. + +**File**: `~/.yourchain/config/client.toml` + + + + + +```bash +yourchain config set client chain-id mychain-1 --home ~/.yourchain +``` + +Or edit `~/.yourchain/config/client.toml` manually: +```toml +chain-id = "mychain-1" +``` + + + + + +The node reads chain-id from `client.toml` at startup. If it doesn't match `genesis.json`, the node will fail with: +``` +error during handshake: error on replay: invalid chain-id on InitChain +``` + + + + + +```bash +# Check matches genesis.json +jq '.chain_id' $GENESIS +# Output: "mychain-1" + +# Check set in client.toml +grep 'chain-id' ~/.yourchain/config/client.toml +# Output: chain-id = "mychain-1" +``` + + + + + +--- + +## 6. Network Launch + +Coordinate launch with all validators. + +### 6.1. Distribute Final Genesis File + +**What This Does**: Shares genesis file with all validators. + + + + + + + + + +```bash +# Coordinator uploads +ipfs add ~/.yourchain/config/genesis.json +# Returns: QmXyz123... + +# Validators download +ipfs get QmXyz123... -o ~/.yourchain/config/genesis.json +``` + + + + + +```bash +# Coordinator creates release +gh release create v1.0.0 ~/.yourchain/config/genesis.json + +# Validators download +wget https://github.com/yourorg/yourchain/releases/download/v1.0.0/genesis.json \ + -O ~/.yourchain/config/genesis.json +``` + + + + + + + + + +--- + +### 6.2. Verify Genesis Hash + +**What This Does**: Ensures all validators have identical genesis files. + + + + + + + + +```bash +jq -S -c . $GENESIS | shasum -a 256 +``` + +Output: `a1b2c3d4e5f6...` + +Publish this hash publicly + + + +```bash +jq -S -c . $GENESIS | shasum -a 256 +``` + +Compare with published hash - must match exactly + + + +All validators report matching hash before proceeding + + + + + + + + + +Even one character difference means different genesis state. + +Do NOT proceed unless ALL validators confirm identical hashes. + + + + + + +--- + +### 6.3. Exchange Peer Information + +**What This Does**: Validators share node IDs and connection info. + + + + + +Each validator provides: +```bash +# Get node ID +yourchain comet show-node-id +# Output: 7c90e16cca334eb7259754f964918d879ca54996 + +# Share format: @: +# Example: 7c90e16cca334eb7259754f964918d879ca54996@192.168.1.100:26656 +``` + +**Create coordination sheet**: + +| Validator | Node ID | IP Address | Connection String | +|-----------|---------|------------|-------------------| +| Validator 1 | 7c90e16c... | 192.168.1.100 | 7c90e16c@192.168.1.100:26656 | +| Validator 2 | abc123de... | 192.168.1.101 | abc123de@192.168.1.101:26656 | +| Validator 3 | def456ab... | 192.168.1.102 | def456ab@192.168.1.102:26656 | + + + + + +Each validator updates `~/.yourchain/config/config.toml`: +```toml +persistent_peers = "7c90e16c@192.168.1.100:26656,abc123de@192.168.1.101:26656,def456ab@192.168.1.102:26656" +``` + + + + + +### 6.4. Start Validator Nodes + +**What This Does**: Starts nodes and coordinates chain launch at genesis time. + + + + + + + + +All validators check: +```bash +jq '.genesis_time' $GENESIS +``` + +Ensure same value for all validators + + + +Start 15-30 minutes before genesis_time: + +```bash +yourchain start +``` + +Expected output: +``` +Genesis time is in the future. Waiting... +Time until genesis: 29m 45s +``` + + + +At genesis_time, chain begins automatically when 2/3+ voting power online + +Monitor logs: +```bash +yourchain start 2>&1 | grep "finalizing commit" +``` + +Expected: +``` +INF finalizing commit of block hash=ABC123... height=1 +INF finalizing commit of block hash=DEF456... height=2 +``` + + + + + + + + +**Check block height**: +```bash +curl localhost:26657/status | jq '.result.sync_info.latest_block_height' +``` + +**Check validator count**: +```bash +curl localhost:26657/validators | jq '.result.validators | length' +``` + +**Check voting power**: +```bash +curl localhost:26657/validators | \ + jq '[.result.validators[].voting_power | tonumber] | add' +``` + +**Test RPC**: +```bash +curl http://localhost:8545 \ + -X POST \ + -H "Content-Type: application/json" \ + -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' +``` + + + + + +**Chain Not Starting**: +- Check genesis_time hasn't passed +- Verify 2/3+ validators online +- Check logs for errors +- Verify persistent_peers configured + +**Not Producing Blocks**: +- Verify >= 2/3 voting power online +- Check validator gentxs in genesis +- Confirm no consensus errors + +**Peer Connection Issues**: +- Verify persistent_peers configured correctly +- Check firewall rules (port 26656) +- Confirm IP addresses are reachable + + + + + +--- + +## 7. Post-Launch Operations + +### 7.1. Monitoring & Alerting + +**What This Does**: Sets up monitoring infrastructure for chain health. + + + + + +Edit `~/.yourchain/config/config.toml`: + +```toml +[instrumentation] +prometheus = true +prometheus_listen_addr = ":26660" +``` + +Restart node to apply. + + + + + +**Critical Metrics**: +- Block production rate (~6-8s per block) +- Validator uptime and participation +- Missed blocks (slashing risk) +- Peer connections (network health) +- Disk usage (state growth) +- Memory usage +- Transaction throughput + +**EVM-Specific Metrics** (on port 8100): +- Gas usage per block +- Transaction pool size +- EVM execution time +- Base fee changes (EIP-1559) + + + + + +**Critical Alerts**: +- Validator jailed +- Missed blocks > 5 +- RPC downtime +- Node out of sync (> 10 blocks behind) + +**Warning Alerts**: +- Disk > 80% full +- Memory > 85% used +- Peer connections < expected +- High transaction rejection rate + + + + + +**Prometheus + Grafana**: Metrics and dashboards + +**Tenderduty**: Validator-specific monitoring +```bash +git clone https://github.com/blockpane/tenderduty +cd tenderduty +go install +``` + +**Custom Dashboards**: Import Cosmos SDK and EVM dashboards for Grafana + + + + + +--- + +### 7.2. Governance Parameter Updates + +**What This Does**: Changes chain parameters after launch through on-chain governance. + + + + + +**Via Governance**: +- `active_static_precompiles` (VM) +- `access_control` (VM) +- Fee market parameters +- Staking parameters (unbonding_time, max_validators) +- Governance parameters (voting_period, quorum) +- Distribution parameters (community_tax) +- Mint parameters (inflation) + +**Cannot Change**: +- EVM chain ID +- Bech32 prefix +- BIP44 coin type +- Token decimals + + + + + +```bash +# Create proposal JSON +cat > proposal.json < + + + +```bash +yourchain tx gov vote 1 yes \ + --from validator1 \ + --chain-id mychain-1 +``` + +**Vote Options**: `yes`, `no`, `abstain`, `no_with_veto` + + + + + +--- + +### 7.3. Software Upgrades + +**What This Does**: Plans and executes coordinated software upgrades. + + + + + + + + +- Watch [cosmos/evm releases](https://github.com/cosmos/evm/releases) +- Review changelogs for breaking changes +- Check for security patches + + + +- Deploy upgrade to testnet first +- Verify all features work +- Measure upgrade duration +- Test rollback if needed + + + + +```bash +cat > upgrade-proposal.json < + + + +Create `app/upgrades/v0_5_0/upgrades.go`: + +```go +package v0_5_0 + +import ( + sdk "github.com/cosmos/cosmos-sdk/types" + "github.com/cosmos/cosmos-sdk/types/module" + upgradetypes "github.com/cosmos/cosmos-sdk/x/upgrade/types" +) + +func CreateUpgradeHandler( + mm *module.Manager, + configurator module.Configurator, +) upgradetypes.UpgradeHandler { + return func(ctx sdk.Context, plan upgradetypes.Plan, vm module.VersionMap) (module.VersionMap, error) { + // Custom upgrade logic here + return mm.RunMigrations(ctx, configurator, vm) + } +} +``` + +Register in `app/app.go`: +```go +import v0_5_0 "github.com/your-org/your-chain/app/upgrades/v0_5_0" + +app.UpgradeKeeper.SetUpgradeHandler( + "v0.5.0", + v0_5_0.CreateUpgradeHandler(app.mm, app.configurator), +) +``` + + + + + +1. Proposal passes via governance +2. Chain halts at upgrade height +3. Validators swap binaries: + +```bash +# Stop old binary (automatic halt) +# Replace binary +cp yourchain-v0.5.0 $GOPATH/bin/yourchain +# Restart +yourchain start +``` + +4. Chain resumes with new version + + + + + + + + + +- **Test thoroughly** on testnet first +- **Coordinate timing** with validators +- **Prepare rollback plan** if needed +- **Communicate clearly** with community +- **Monitor closely** during upgrade +- **Have backup nodes** ready + + + + + + +**Learn More**: [Upgrade Handlers Guide](/docs/evm/next/documentation/migrations/upgrade-handlers) + + +--- + +## 8. Complete Examples + +### 8.1. Example: 18-Decimal Chain Setup + +Complete working example for an 18-decimal EVM-compatible chain. + + + + + +```bash +#!/bin/bash +# Complete setup script for 18-decimal chain + +BINARY="yourchain" +CHAIN_ID="yourchain-1" +DENOM="atoken" +GENESIS=~/.yourchain/config/genesis.json + +# Initialize +$BINARY init mynode --chain-id $CHAIN_ID + +# 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 + +# Set bank metadata (18 decimals) +jq ".app_state.bank.denom_metadata=[{ + \"description\": \"The native staking token\", + \"denom_units\": [ + {\"denom\": \"$DENOM\", \"exponent\": 0, \"aliases\": [\"attotoken\"]}, + {\"denom\": \"token\", \"exponent\": 18, \"aliases\": []} + ], + \"base\": \"$DENOM\", + \"display\": \"token\", + \"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 + +# Configure ERC20 token pair +jq '.app_state.erc20.token_pairs=[{ + "erc20_address": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE", + "denom": "atoken", + "enabled": true, + "contract_owner": 1 +}]' $GENESIS > tmp && mv tmp $GENESIS + +jq '.app_state.erc20.native_precompiles=["0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE"]' $GENESIS > tmp && mv tmp $GENESIS + +echo "Genesis configuration complete!" +``` + + + + + +```toml +[evm] +evm-chain-id = 262144 +tracer = "" +max-tx-gas-wanted = 0 +min-tip = 1000000000 # 1 gwei + +[evm.mempool] +price-limit = 1000000000 +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 +enable-indexer = true + +minimum-gas-prices = "1000000000atoken" +``` + + + + + +--- + +### 8.2. Example: 6-Decimal Chain with PreciseBank + +Complete working example for a 6-decimal chain with PreciseBank integration. + + + + + +```bash +#!/bin/bash +# Complete setup script for 6-decimal chain + +BINARY="yourchain" +CHAIN_ID="yourchain-1" +BASE_DENOM="utoken" +EXTENDED_DENOM="atoken" +GENESIS=~/.yourchain/config/genesis.json + +# Initialize +$BINARY init mynode --chain-id $CHAIN_ID + +# 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 + +# Set bank metadata (6 decimals) +jq ".app_state.bank.denom_metadata=[{ + \"description\": \"The native staking token\", + \"denom_units\": [ + {\"denom\": \"$BASE_DENOM\", \"exponent\": 0}, + {\"denom\": \"token\", \"exponent\": 6} + ], + \"base\": \"$BASE_DENOM\", + \"display\": \"token\", + \"name\": \"Token\", + \"symbol\": \"TKN\" +}]" $GENESIS > tmp && mv tmp $GENESIS + +# Set extended denom options (REQUIRED for 6 decimals) +jq ".app_state.evm.params.extended_denom_options={ + \"extended_denom\": \"$EXTENDED_DENOM\" +}" $GENESIS > tmp && mv tmp $GENESIS + +# Enable precompiles +jq '.app_state.evm.params.active_static_precompiles=[ + "0x0000000000000000000000000000000000000100", + "0x0000000000000000000000000000000000000400", + "0x0000000000000000000000000000000000000800" +]' $GENESIS > tmp && mv tmp $GENESIS + +echo "Genesis configuration complete!" +echo "IMPORTANT: Ensure PreciseBank module is integrated in app.go" +``` + + + + + +```go +// In app.go - REQUIRED for 6-decimal chains + +import ( + precisebankkeeper "github.com/cosmos/evm/x/precisebank/keeper" + precisebanktypes "github.com/cosmos/evm/x/precisebank/types" + precisebank "github.com/cosmos/evm/x/precisebank" +) + +// Add to store keys +keys := storetypes.NewKVStoreKeys( + // ... other keys + precisebanktypes.StoreKey, +) + +// Initialize PreciseBankKeeper +app.PreciseBankKeeper = precisebankkeeper.NewKeeper( + appCodec, + keys[precisebanktypes.StoreKey], + app.BankKeeper, + app.AccountKeeper, +) + +// CRITICAL: Use PreciseBankKeeper in EVMKeeper +app.EVMKeeper = evmkeeper.NewKeeper( + appCodec, + keys[evmtypes.StoreKey], + app.GetSubspace(evmtypes.ModuleName), + app.AccountKeeper, + app.PreciseBankKeeper, // Not BankKeeper! + app.StakingKeeper, + app.FeeMarketKeeper, + authtypes.NewModuleAddress(govtypes.ModuleName).String(), +) + +// Add to module manager +app.ModuleManager = module.NewManager( + // ... other modules + precisebank.NewAppModule(app.PreciseBankKeeper, app.AccountKeeper), + // ... +) + +// Add to genesis order (after bank, before evm) +genesisModuleOrder := []string{ + // ... + banktypes.ModuleName, + precisebanktypes.ModuleName, + evmtypes.ModuleName, + // ... +} +``` + + + + + +--- + +### 8.3. Using local_node.sh as Template + +The `local_node.sh` script in the cosmos/evm repository demonstrates complete chain configuration for local development. + + + + + +The script performs all configuration steps automatically: + +**Genesis Modifications**: +- Sets development chain ID +- Configures `atest` denomination (18 decimals) +- Sets up bank metadata +- Enables all static precompiles +- Creates genesis validator +- Funds test accounts + +**app.toml Configuration**: +- Sets EVM chain ID to 262144 +- Enables JSON-RPC on 0.0.0.0:8545 +- Enables all APIs including debug +- Allows unprotected transactions (dev only) +- Enables transaction indexer + + + + + +```bash +# Fresh start (overwrites previous database) +./local_node.sh -y + +# Resume from previous state +./local_node.sh -n + +# Skip binary rebuild +./local_node.sh --no-install + +# Build with debug symbols +./local_node.sh --remote-debugging +``` + + + + + +To adapt for your chain: + +1. **Copy the script**: `cp local_node.sh my_chain_setup.sh` +2. **Update chain name**: Change `evmd` to your binary +3. **Modify genesis values**: Update denom, chain ID, precompiles +4. **Adjust app.toml settings**: Configure for your use case +5. **Add custom logic**: Include chain-specific setup + + + + + + +**Development vs Production**: + +The `local_node.sh` configuration is optimized for local development. For production: + +- Disable debug APIs in JSON-RPC +- Require transaction signatures (`allow-unprotected-txs = false`) +- Set appropriate `min-tip` value +- Use secure key management (not test keys) +- Configure proper peer discovery +- Enable appropriate monitoring + + + + + + +--- + +## 9. Quick Reference + +### Commands Summary + +```bash +# Build +make build + +# Initialize +yourchain init --chain-id + +# Genesis accounts +yourchain genesis add-genesis-account
+ +# Create validator gentx +yourchain genesis gentx --chain-id + +# Collect gentxs +yourchain genesis collect-gentxs + +# Validate genesis +yourchain genesis validate + +# Hash genesis +jq -S -c . genesis.json | shasum -a 256 + +# Show node ID +yourchain comet show-node-id + +# Start node +yourchain start + +# Check status +curl localhost:26657/status + +# Check block height (Cosmos) +curl localhost:26657/status | jq '.result.sync_info.latest_block_height' + +# Check block height (Ethereum) +curl http://localhost:8545 -X POST -H "Content-Type: application/json" \ + -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' +``` + +--- + +### File Locations + +| File | Location | +|------|----------| +| Genesis | `~/.yourchain/config/genesis.json` | +| App Config | `~/.yourchain/config/app.toml` | +| CometBFT Config | `~/.yourchain/config/config.toml` | +| Client Config | `~/.yourchain/config/client.toml` | +| Gentx Directory | `~/.yourchain/config/gentx/` | +| Bech32 Prefix | `config/config.go:62` | +| BIP44 Coin Type | `crypto/hd/hdpath.go:9` | +| EVM Chain ID | `config/config.go:78` | +| Default Denoms | `x/vm/types/params.go:21-25` | + +--- + +### Default Values Reference + +| Parameter | Default | Source | +|-----------|---------|--------| +| **Pre-Genesis** | | | +| Bech32 Prefix | `cosmos` | config/config.go:62 | +| BIP44 Coin Type | `60` | crypto/hd/hdpath.go:9 | +| EVM Chain ID | `262144` | config/config.go:78 | +| **EVM Module** | | | +| Base Fee | `1000000000` (1 gwei) | x/feemarket/types/params.go:13 | +| History Serve Window | `8192` blocks | x/vm/types/params.go:50 | +| **Mempool** | | | +| Price Limit | `1` wei | server/config/config.go:179 | +| Price Bump | `10%` | server/config/config.go:180 | +| Account Slots | `16` | server/config/config.go:181 | +| Global Slots | `5120` | server/config/config.go:182 | +| Account Queue | `64` | server/config/config.go:183 | +| Global Queue | `1024` | server/config/config.go:184 | +| Lifetime | `3h0m0s` | server/config/config.go:185 | +| **Staking** | | | +| Unbonding Time | `1814400s` (21 days) | Staking default | +| Max Validators | `100` | Staking default | +| **Governance** | | | +| Voting Period | `172800s` (2 days) | Gov default | +| Quorum | `0.334` (33.4%) | Gov default | + +--- + +### Navigation Index + +**Planning**: [Section 2](#2-planning-your-configuration) + +**Pre-Genesis Setup** (Must do before init): +- [Binary Name](#31-fork-repository-and-rename-binary) +- [Bech32 Prefix](#32-set-bech32-address-prefix) +- [BIP44 Coin Type](#33-set-bip44-coin-type) +- [EVM Chain ID](#34-set-evm-chain-id) +- [Token Decimals](#35-choose-token-decimal-precision) +- [Default Denominations](#36-configure-default-token-denomination-in-source-code) + +**Genesis Configuration**: +- [Genesis Time](#41-set-genesis-time) +- [Bank Metadata](#42-configure-bank-metadata) +- [EVM Denom](#43-set-evm-denom) +- [Extended Denom](#44-configure-extended-denom-options) +- [ERC20 Token Pairs](#45-configure-erc20-token-pairs) +- [Precompiles](#46-enable-required-precompiles) +- [Predeployed Contracts](#47-configure-predeployed-contracts) +- [Access Control](#48-configure-evm-access-control) +- [Fee Market](#49-configure-eip-1559-fee-market) +- [Staking](#410-configure-staking-parameters) +- [Mint](#411-configure-mint-parameters) +- [Governance](#412-configure-governance-parameters) +- [Genesis Accounts](#413-add-genesis-accounts-with-initial-balances) +- [Validator Gentxs](#414-collect-validator-genesis-transactions) +- [Validation](#415-validate-final-genesis-file) + +**Runtime Configuration**: +- [JSON-RPC](#51-configure-json-rpc) +- [EVM Settings](#52-configure-evm-settings) +- [Mempool](#53-configure-evm-mempool) +- [Gas Prices](#54-set-minimum-gas-prices) +- [Network Peers](#55-configure-network-peers) +- [Client Chain ID](#56-set-client-chain-id) + +**Network Launch**: +- [Distribute Genesis](#61-distribute-final-genesis-file) +- [Verify Hash](#62-verify-genesis-hash) +- [Exchange Peers](#63-exchange-peer-information) +- [Start Nodes](#64-start-validator-nodes) + +**Post-Launch**: +- [Monitoring](#71-monitoring--alerting) +- [Governance](#72-governance-parameter-updates) +- [Upgrades](#73-software-upgrades) + +--- + +**Generated from**: [cosmos/evm](https://github.com/cosmos/evm) codebase +**Version**: v0.5.0-rc.1 (Cosmos SDK v0.53.4, IBC-Go v10, CometBFT v0.38.18) \ No newline at end of file diff --git a/docs/evm/next/documentation/getting-started/build-a-chain/building-your-chain-guide.mdx b/docs/evm/next/documentation/getting-started/build-a-chain/building-your-chain-guide.mdx deleted file mode 100644 index 38d8596b..00000000 --- a/docs/evm/next/documentation/getting-started/build-a-chain/building-your-chain-guide.mdx +++ /dev/null @@ -1,225 +0,0 @@ ---- -title: "Build A Custom Chain" -description: "Create your own blockchain by forking and customizing the Cosmos EVM reference chain (evmd). This guide covers the example chain configuration, running the chain locally, and understanding the foundation for building your custom blockchain." ---- - -# Example Cosmos EVM Chain - -The `evmd` directory in the Cosmos EVM repository contains an example chain that demonstrates the integration of Cosmos EVM modules. This reference implementation is based on the simapp implementation from the Cosmos SDK repository, which provides a simplified yet complete blockchain foundation. - - -This chain implementation serves two primary purposes: -1. **Demonstration**: Shows how to integrate Cosmos EVM modules into a blockchain -2. **Testing Foundation**: Provides a working chain for development and testing - -You can use evmd as the starting point for building your own custom chain. - - -## Building Your Custom Chain - -The `evmd` implementation serves as the foundation for building your own custom blockchain. To create your chain: - - - -Start by forking the Cosmos EVM repository: - -```bash -git clone https://github.com/YOUR-ORG/YOUR-CHAIN.git -cd YOUR-CHAIN -``` - - - -Rename the `evmd` directory and update all references: - -```bash -# Rename directory -mv evmd yourchain - -# Update imports and binary name -find . -type f -name "*.go" -exec sed -i 's/evmd/yourchain/g' {} \; -``` - -Update `go.mod` to reflect your repository path. - - - -Modify the default configuration in your chain: - -- **Chain IDs**: Update Cosmos chain ID and EVM chain ID -- **Bech32 Prefix**: Set your address prefix in `config/config.go` -- **Token Denomination**: Configure in genesis -- **Precompiles**: Enable only the precompiles you need -- **Modules**: Add or remove modules based on requirements - - -For detailed configuration guidance, see the comprehensive [Configuration Parameters](/docs/evm/next/documentation/getting-started/build-a-chain/configuration-parameters) documentation. - - - - -Use the local node script to test your changes: - -```bash -./local_node.sh -y -``` - -Verify that: -- The chain starts successfully -- JSON-RPC is accessible -- Wallets can connect -- Transactions work as expected - - - -Once testing is complete, prepare for testnet deployment: - -- Set up validator infrastructure -- Configure persistent peers -- Coordinate genesis with validators -- Launch the network - - -For production deployment guidance, see the [Node Configuration](/docs/evm/next/documentation/getting-started/node-configuration) documentation. - - - - -## Default Configuration - -The example chain (`evmd`) comes with the following default configuration: - -| Option | Value | Description | -|---------------------|------------------------|-------------| -| **Binary** | `evmd` | The compiled chain binary name | -| **Cosmos Chain ID** | User-defined | Cosmos chain ID (string) - set during `init` | -| **EVM Chain ID** | `262144` | EVM chain ID (integer) for transaction replay protection | -| **Token Pairs** | 1 (native token) | Default ERC20 token pair for the native denomination | -| **Denomination** | `atest` | Native token denomination (18 decimals, atto-prefix) | -| **EVM Permissioning** | Permissionless | Anyone can deploy and call contracts | -| **Enabled Precompiles** | All | All static precompiles are enabled by default | - - -The default configuration uses an 18-decimal token (`atest`) which provides direct EVM compatibility without requiring the precisebank module. This is the recommended setup for new chains. - - -## Running The Chain - -To run the example chain locally, use the provided local node script from the repository root: - -```bash -./local_node.sh [FLAGS] -``` - -### Available Flags - -- `-y`: Overwrite previous database (fresh start) -- `-n`: Do **not** overwrite previous database (resume from previous state) -- `--no-install`: Skip installation of the binary (use existing binary) -- `--remote-debugging`: Build a binary suitable for remote debugging - - -The `local_node.sh` script handles all the setup including: -- Building the `evmd` binary -- Initializing the chain configuration -- Setting up genesis parameters -- Starting the chain with JSON-RPC enabled - - -### Example Usage - - -```bash Fresh Start -# Start with a clean slate -./local_node.sh -y -``` - -```bash Resume Previous State -# Continue from where you left off -./local_node.sh -n -``` - -```bash Development Mode -# Skip rebuild if binary already exists -./local_node.sh --no-install -``` - -```bash Debug Mode -# Build with debugging symbols -./local_node.sh --remote-debugging -``` - - -## Connect to Wallet - -Once the chain is running, you can connect using any Ethereum-compatible wallet. The example below uses MetaMask: - -### MetaMask Setup - - - -Use the following seed phrase when adding a new wallet in MetaMask: - -``` -abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about -``` - - - - -1. Click the **Network** button on the top left of MetaMask -2. Click **Add custom network** at the bottom of the modal -3. Configure the network with these settings: - -| Setting | Value | -|---------|-------| -| **Network Name** | Cosmos EVM Local | -| **RPC URL** | `http://localhost:8545` | -| **Chain ID** | `262144` | -| **Currency Symbol** | `TEST` | -| **Block Explorer URL** | (leave empty for local) | - - -Make sure your local chain is running before adding the network. The RPC URL must be accessible from your browser. - - - - -After adding the network: -- Switch to the "Cosmos EVM Local" network in MetaMask -- You should see your account balance (if the test account was funded in genesis) -- You can now interact with the chain through MetaMask - - - -### Recommended Reading - - - -Complete reference for all chain configuration options - - - -Production deployment and validator setup - - - -EVM execution, precompiles, and access control - - - -Token pairs and ERC20 wrapper configuration - - - -EIP-1559 dynamic fee market configuration - - - -Available precompiled contracts and integration - - - ---- - -For additional support and community resources, visit the [Cosmos EVM GitHub repository](https://github.com/cosmos/evm) or join the Cosmos developer community. \ No newline at end of file diff --git a/docs/evm/next/documentation/getting-started/build-a-chain/configuration-reference.mdx b/docs/evm/next/documentation/getting-started/build-a-chain/configuration-reference.mdx new file mode 100644 index 00000000..4384e35f --- /dev/null +++ b/docs/evm/next/documentation/getting-started/build-a-chain/configuration-reference.mdx @@ -0,0 +1,659 @@ +--- +title: "Configuration Reference" +description: "Quick reference for Cosmos EVM chain configuration - commands, file locations, defaults, and examples." +--- + +This reference provides quick access to common commands, configuration examples, and default values for building Cosmos EVM chains. + + +**Related Documentation:** +- [Pre-Genesis & Genesis Setup](/docs/evm/next/documentation/getting-started/build-a-chain/pre-genesis-and-genesis-setup) - Complete configuration guide +- [Runtime Configuration & Launch](/docs/evm/next/documentation/getting-started/build-a-chain/runtime-and-launch) - Network launch procedures + + +--- + +## Commands Summary + +### Chain Initialization + + +```bash +# Initialize chain +yourchain init --chain-id + +# Example +yourchain init mynode --chain-id mychain-1 + +# Show node ID +yourchain comet show-node-id + +# Show validator info +yourchain comet show-validator +``` + + +--- + +### Genesis Account Management + + +```bash +# Add genesis account +yourchain genesis add-genesis-account
+ +# Add from keyring +yourchain genesis add-genesis-account \ + validator1 \ + 1000000000000000000000atoken \ + --keyring-backend test + +# Example amounts (18 decimals) +yourchain genesis add-genesis-account validator1 1000000000000000000000atoken # 1000 tokens +yourchain genesis add-genesis-account faucet 10000000000000000000000atoken # 10000 tokens +``` + + +--- + +### Validator Genesis Transactions + + +```bash +# Create gentx +yourchain genesis gentx \ + --chain-id \ + --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 +# 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 +# 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 +# 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 +# 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 +# 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 +# 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 +# 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 +cat local_node.sh | less +``` + + + +**Basic usage:** +```bash +# 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 +cp local_node.sh my_chain_setup.sh +``` + +**2. Update binary name:** +```bash +# 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..adf9f46e 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,116 @@ 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** - Real working examples of integration approaches used by the core development team are readily available on Github + +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 +./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..a274bb1f --- /dev/null +++ b/docs/evm/next/documentation/getting-started/build-a-chain/pre-genesis-and-genesis-setup.mdx @@ -0,0 +1,2104 @@ +--- +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 +# 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 +mv evmd yourchain +``` + +**2. Update Go imports in all `.go` files:** +```bash +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 +// FROM: +module github.com/cosmos/evm + +// TO: +module github.com/your-org/your-chain +``` + +**4. Update Makefile references:** +```bash +sed -i '' 's/evmd/yourchain/g' Makefile +``` + +**5. Run go mod tidy:** +```bash +go mod tidy +``` + +**6. Build and verify:** +```bash +make build +./build/yourchain version +``` + + + +The renaming process updates: + +**Directory Structure:** +- `evmd/` → `yourchain/` +- `evmd/cmd/evmd/` → `yourchain/cmd/yourchain/` + +**Go Import Paths:** +```go +// Before +import "github.com/cosmos/evm/evmd/cmd" + +// After +import "github.com/your-org/your-chain/yourchain/cmd" +``` + +**Module Declaration:** +```go +// 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 +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 +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 +# 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 +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 +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 +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` (in older code) or `999888` (in current config/config.go) + +**File Location**: [`config/config.go:78`](https://github.com/cosmos/evm/blob/main/config/config.go#L77-L78) + +**Why Change It**: Must be unique for your network to prevent transaction replay attacks. + + +The EVM Chain ID **cannot** be changed after genesis without breaking all transaction signatures and wallet compatibility. Choose carefully before launch. + + + + +Edit `config/config.go` and change the `EVMChainID` constant: + +```go +const ( + // EVMChainID defines the EIP-155 replay-protection chain id + EVMChainID = 123456 // Change to your unique chain ID +) +``` + +**This value is used during `yourchain init`** to populate the `evm-chain-id` field in `app.toml`. + +**After changing, rebuild:** +```bash +make build +``` + +**Then initialize (the chain ID will be embedded):** +```bash +./build/yourchain init mynode --chain-id mychain-1 +``` + +**Verify it was set correctly:** +```bash +grep 'evm-chain-id' ~/.yourchain/config/app.toml +# Should show: evm-chain-id = "123456" +``` + + + +**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 +// 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 +// 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:77-78](https://github.com/cosmos/evm/blob/main/config/config.go#L77-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 +{ + "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 +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 +{ + "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 +# 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 +// 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 +// FROM: +const ( + ExampleChainDenom = "aatom" + ExampleDisplayDenom = "atom" +) + +// TO: +const ( + ExampleChainDenom = "atoken" + ExampleDisplayDenom = "token" +) +``` + + + +**For 18-decimal tokens (recommended):** + +```bash +# 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 +# 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 +# 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 +yourchain init --chain-id +``` + +Example: +```bash +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 +yourchain init mynode --chain-id mychain-1 +``` + +This writes the chain ID to both `genesis.json` and `client.toml`. + + + +To change the chain ID after initialization: + +```bash +# 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 +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 +jq '.genesis_time = "2024-12-01T00:00:00Z"' ~/.yourchain/config/genesis.json > tmp && \ + mv tmp ~/.yourchain/config/genesis.json +``` + +**Verify:** +```bash +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 +# 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. + + + +**For EVM-compatible chains using 18 decimals:** + +```bash +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 +``` + +**Fields Explained:** +- `base`: Smallest unit stored on-chain (`atoken`) +- `display`: Human-readable unit (`token`) +- `exponent`: Decimal places (18 for EVM compatibility) +- `name`: Full token name displayed in wallets +- `symbol`: Ticker symbol (e.g., `TKN`, `ATOM`, `ETH`) + + + +**For Cosmos-standard chains using 6 decimals:** + +```bash +jq '.app_state.bank.denom_metadata=[{ + "description": "The native staking and gas token", + "denom_units": [ + { + "denom": "utoken", + "exponent": 0, + "aliases": ["microtoken"] + }, + { + "denom": "token", + "exponent": 6, + "aliases": [] + } + ], + "base": "utoken", + "display": "token", + "name": "My Token", + "symbol": "TKN" +}]' ~/.yourchain/config/genesis.json > tmp && mv tmp ~/.yourchain/config/genesis.json +``` + +**Note**: When using 6 decimals, you must also: +- Add PreciseBank module to `app.go` +- Configure `extended_denom_options` in VM params (see next section) + + + +After configuration, verify all denoms match across modules: + +```bash +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 +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 non-18 decimal chains:** + +When using 6 decimals (or other non-18 decimals), configure extended denom: + +```bash +jq '.app_state.evm.params.extended_denom_options = { + "extended_denom": "atoken" +}' ~/.yourchain/config/genesis.json > tmp && mv tmp ~/.yourchain/config/genesis.json +``` + +**Example for 6-decimal chain:** +```json +{ + "app_state": { + "evm": { + "params": { + "evm_denom": "utoken", + "extended_denom_options": { + "extended_denom": "atoken" + } + } + } + } +} +``` + +**How it works:** +- Cosmos SDK uses: `utoken` (6 decimals) +- EVM sees: `atoken` (18 decimals) +- PreciseBank handles conversion: `1 utoken = 10^12 wei` + +**Not needed for 18-decimal chains** - leave empty or omit. + +**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 +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 +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 +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 +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 +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 +# 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 +# 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 +{ + "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 +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 +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 +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 +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 +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 +# 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 +{ + "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 +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 +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 +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 +# 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 +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 +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 +# 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 +jq '.app_state.bank.balances' ~/.yourchain/config/genesis.json +``` + + + +**Workflow:** + +**1. Each validator creates their gentx:** +```bash +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 +cat ~/.yourchain/config/gentx/gentx-*.json +``` + +**3. Coordinator collects all gentxs:** +```bash +# 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 +yourchain genesis validate +jq '.app_state.genutil.gen_txs | length' ~/.yourchain/config/genesis.json +``` + + + +**Final validation before distribution:** + +```bash +# 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 +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 +jq '.app_state.bank.balances | map(.coins[0].amount | tonumber) | add' $GENESIS +``` + +**Check validator count:** +```bash +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 +- Troubleshooting guide 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..d9c3f56c --- /dev/null +++ b/docs/evm/next/documentation/getting-started/build-a-chain/runtime-and-launch.mdx @@ -0,0 +1,1313 @@ +--- +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 +# 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 +minimum-gas-prices = "1000000000atoken" # 1 gwei +``` + +**For 6-decimal tokens:** +```toml +minimum-gas-prices = "1000utoken" # 0.001 token +``` + +**Testing/Development:** +```toml +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 +[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 DEV) +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 +api = ["eth", "net", "web3"] +``` + +**Development configuration:** +```toml +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 +# 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 +[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 +[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 +[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 +[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 +[evm.mempool] +price-limit = 100000000 # 0.1 gwei minimum +global-slots = 10240 +global-queue = 2048 +lifetime = "6h0m0s" +``` + +**Low-resource node:** +```toml +[evm.mempool] +price-limit = 1 +global-slots = 2048 +global-queue = 512 +account-slots = 8 +lifetime = "1h0m0s" +``` + +**Strict spam prevention:** +```toml +[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 +[p2p] +# Comma separated list of nodes to keep persistent connections to +persistent_peers = "node_id@ip:port,node_id2@ip:port" +``` + +**Example:** +```toml +persistent_peers = "7c90e16cca334eb7@192.168.1.100:26656,abc123def456@192.168.1.101:26656" +``` + + + +**Each validator runs:** +```bash +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 +# 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 +[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 +[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 +[instrumentation] +# Enable Prometheus metrics +prometheus = true + +# Prometheus listen address +prometheus_listen_addr = ":26660" +``` + +**Access metrics:** +```bash +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 +yourchain config set client chain-id mychain-1 --home ~/.yourchain +``` + +**Or edit `client.toml` directly:** +```toml +chain-id = "mychain-1" +``` + + + +```bash +# 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 +# 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 +# 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 +# Coordinator uploads +ipfs add ~/.yourchain/config/genesis.json +# Returns: QmXyz123... + +# Validators download +ipfs get QmXyz123... -o ~/.yourchain/config/genesis.json +``` + + + +**For private networks:** + +```bash +# 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 +jq -S -c . ~/.yourchain/config/genesis.json | shasum -a 256 +``` + +**Example output:** +``` +a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6 - +``` + + + +**1. Coordinator publishes canonical hash:** +```bash +# 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 +# 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 + + + +**If hashes don't match:** + +1. **Check whitespace**: Use `jq -S -c` to normalize +2. **Re-download**: Get genesis file again +3. **Verify source**: Ensure downloading from official source +4. **Check corruption**: File may be corrupted in transfer + +**Even one character difference = different genesis state** + +All validators must have byte-for-byte identical files. + + + +--- + +### Exchange Peer Information + +Validators need each other's peer information to connect. + + + +**Each validator provides:** + +```bash +# 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 +# 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 +# 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 +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 +# 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 +# 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 +# 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 +[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 +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 +# 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 +# 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 +# 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 +curl localhost:26657/health +# Returns: {} (empty object = healthy) +``` + +**Node status:** +```bash +curl localhost:26657/status | jq '.result' +``` + +**Shows:** +- Node info +- Sync status +- Latest block info +- Validator info + + + +**Test JSON-RPC:** + +```bash +# 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 +# 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 +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 +# 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 +# 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 +# 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 +yourchain start +``` + +**Critical**: Never run two validators with same private key simultaneously (double-sign risk). + + + +--- + +## Troubleshooting + +### Common Launch Issues + + + +**Error: `invalid chain-id on InitChain`** + +**Solution:** +```bash +# Verify chain IDs match +jq '.chain_id' ~/.yourchain/config/genesis.json +grep 'chain-id' ~/.yourchain/config/client.toml + +# Set if missing +yourchain config set client chain-id mychain-1 +``` + +**Error: `genesis.json file not found`** + +**Solution:** +```bash +# Verify file exists +ls ~/.yourchain/config/genesis.json + +# Re-download if missing +``` + + + +**Check P2P configuration:** + +```bash +# Verify persistent_peers in config.toml +grep 'persistent_peers' ~/.yourchain/config/config.toml + +# Check node ID is correct +yourchain comet show-node-id + +# Test network connectivity +nc -zv 26656 +``` + +**Check firewall:** +```bash +# Port 26656 must be open for P2P +sudo ufw status +sudo ufw allow 26656 +``` + + + +**If validators have different genesis files:** + +1. **Stop all nodes** +2. **Coordinator distributes canonical genesis** +3. **All validators re-verify hash** +4. **Restart launch process** + +**Prevention:** +- Use checksums +- Distribute via secure channel +- Verify before launch + + + +**Check validator participation:** + +```bash +# Check number of online validators +curl localhost:26657/validators | jq '.result.validators | length' + +# Check total voting power +curl localhost:26657/validators | \ + jq '[.result.validators[].voting_power | tonumber] | add' +``` + +**Need >=2/3 voting power online for consensus.** + +**If insufficient:** +- Wait for more validators to come online +- Verify genesis file distributed +- Check validator connectivity + + + +--- + +## 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 +- ✅ Troubleshooting common issues + +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/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 = "" }) => ( + + + 18 + + +) + +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", From 024566bdc174634c6cfdf57dc12855b12a6a3a0a Mon Sep 17 00:00:00 2001 From: Cordt Date: Wed, 15 Oct 2025 14:46:01 -0600 Subject: [PATCH 2/6] remove syntax breaking --- from all files --- .../predeployed-contracts.mdx | 4 +- .../build-a-chain/build-chain-final.mdx | 2985 ----------------- .../chain-configuration-reference.mdx | 111 +- .../chain-customization-checklist.mdx | 14 +- .../configuration-parameters.mdx | 36 +- .../build-a-chain/configuration-reference.mdx | 52 +- .../build-a-chain/overview.mdx | 8 +- .../pre-genesis-and-genesis-setup.mdx | 10 +- .../build-a-chain/runtime-and-launch.mdx | 50 +- 9 files changed, 140 insertions(+), 3130 deletions(-) delete mode 100644 docs/evm/next/documentation/getting-started/build-a-chain/build-chain-final.mdx diff --git a/docs/evm/next/documentation/getting-started/build-a-chain/additional-configuration/predeployed-contracts.mdx b/docs/evm/next/documentation/getting-started/build-a-chain/additional-configuration/predeployed-contracts.mdx index f34ba4b8..b6088c6a 100644 --- a/docs/evm/next/documentation/getting-started/build-a-chain/additional-configuration/predeployed-contracts.mdx +++ b/docs/evm/next/documentation/getting-started/build-a-chain/additional-configuration/predeployed-contracts.mdx @@ -317,7 +317,7 @@ preinstalls := append(evmtypes.DefaultPreinstalls, customPreinstall) ### Common Issues | Issue | Cause | Solution | -|-------|-------|----------| +|-|-|-| | "preinstall already has an account in account keeper" | Address collision | Choose different address | | "preinstall has empty code hash" | Invalid or empty bytecode | Verify bytecode hex string is valid | | "preinstall address is not a valid hex address" | Malformed address | Ensure 0x prefix and 40 hex chars | @@ -337,7 +337,7 @@ preinstalls := append(evmtypes.DefaultPreinstalls, customPreinstall) ### Default Preinstalls | Contract | Address | Bytecode Field | Status | -|----------|---------|---------------|--------| +|-|||--| | Create2 | `0x4e59b44847b379578588920ca78fbf26c0b4956c` | `preinstall.Code` | ✓ Verified | | Multicall3 | `0xcA11bde05977b3631167028862bE2a173976CA11` | `preinstall.Code` | ✓ Verified | | Permit2 | `0x000000000022D473030F116dDEE9F6B43aC78BA3` | `preinstall.Code` | ✓ Verified | diff --git a/docs/evm/next/documentation/getting-started/build-a-chain/build-chain-final.mdx b/docs/evm/next/documentation/getting-started/build-a-chain/build-chain-final.mdx deleted file mode 100644 index d0ef5664..00000000 --- a/docs/evm/next/documentation/getting-started/build-a-chain/build-chain-final.mdx +++ /dev/null @@ -1,2985 +0,0 @@ -# Chain Configuration: Complete Guide - -**From planning to launch - comprehensive configuration documentation for Cosmos EVM chains** - -This guide provides complete documentation for configuring and launching a Cosmos EVM chain. It covers pre-genesis setup, genesis configuration, runtime settings, network coordination, and post-launch operations. - -Use this as both a planning tool (understanding your options) and an execution manual (step-by-step instructions with verification). - ---- - -## 1. Overview & Quick Start - -### What You'll Configure - -When building your custom Cosmos EVM chain, you'll configure parameters across multiple areas: - -| Configuration Area | When to Configure | Changeable After Genesis | Difficulty | -|-------------------|-------------------|-------------------------|------------| -| **Binary Name** | Before any setup | No (requires new binary) | Easy | -| **Bech32 Prefix** | Before `init` | No (hard fork required) | Easy | -| **BIP44 Coin Type** | Before `init` | No (breaks wallets) | Easy | -| **EVM Chain ID** | Before `init` | No (breaks signatures) | Easy | -| **Token Decimals** | Genesis | No (architectural) | Medium | -| **Bank Metadata** | Genesis | Limited (via governance) | Medium | -| **Precompiles** | Genesis | Yes (via governance) | Medium | -| **Access Control** | Genesis | Yes (via governance) | Easy | -| **Fee Market** | Genesis | Yes (via governance) | Medium | -| **Runtime Config** | Before start | Yes (node-level) | Easy | -| **Network Peers** | Before start | Yes (config file) | Easy | - -### Prerequisites - -Before starting this guide, ensure you have: - -- Go 1.21 or later installed -- Forked or cloned the [cosmos/evm](https://github.com/cosmos/evm) repository -- Basic understanding of Cosmos SDK and EVM concepts -- Decided on your chain's identity (name, token symbol) - -**Estimated Time**: 2-4 hours for initial configuration, additional time for multi-validator coordination - ---- - -## 2. Planning Your Configuration - -Before modifying any code or files, create a planning document with these key decisions. Each parameter links to its detailed configuration section later in this guide. - -### Configuration Planning Worksheet - -Create your own document with these values before starting: - -#### Chain Identity & Branding -- **Binary Name**: `_________________` → [Configure in Section 3.1](#31-fork-repository-and-rename-binary) -- **Cosmos Chain ID**: `_________________-1` → [Configure in Section 4.1](#41-set-cosmos-chain-id) -- **EVM Chain ID**: `_________________` → [Configure in Section 3.4](#34-set-evm-chain-id) -- **Bech32 Prefix**: `_________________` → [Configure in Section 3.2](#32-set-bech32-address-prefix) -- **BIP44 Coin Type**: `60` (recommended) → [Configure in Section 3.3](#33-set-bip44-coin-type) - -#### Token Economics -- **Token Name**: `_________________` → [Configure in Section 4.2](#42-configure-bank-metadata) -- **Token Symbol**: `_________________` → [Configure in Section 4.2](#42-configure-bank-metadata) -- **Decimals**: `18` (recommended) / `6` / Other → [Configure in Section 3.5](#35-choose-token-decimal-precision) -- **Base Denom**: `_________________` → [Configure in Sections 3.6 & 4.2](#36-configure-default-token-denomination-in-source-code) -- **Display Denom**: `_________________` → [Configure in Section 4.2](#42-configure-bank-metadata) -- **Genesis Supply**: `_________________` → [Configure in Section 4.13](#413-add-genesis-accounts-with-initial-balances) -- **Inflation Enabled**: Yes / No → [Configure in Section 4.11](#411-configure-mint-parameters) - -#### EVM & Smart Contracts -- **Precompiles to Enable**: → [Configure in Section 4.6](#46-enable-required-precompiles) - - `[ ]` 0x0100 - P256 - - `[ ]` 0x0400 - Bech32 - - `[ ]` 0x0800 - Staking - - `[ ]` 0x0801 - Distribution - - `[ ]` 0x0802 - ICS20 - - `[ ]` 0x0803 - Vesting - - `[ ]` 0x0804 - Bank - - `[ ]` 0x0805 - Governance - - `[ ]` 0x0806 - Slashing - - `[ ]` 0x0807 - Authz -- **Deployment Permissions**: Permissionless / Permissioned / Restricted → [Configure in Section 4.8](#48-configure-evm-access-control) -- **Fee Market**: EIP-1559 (recommended) / Fixed → [Configure in Section 4.9](#49-configure-eip-1559-fee-market) - -#### Governance & Validators -- **Unbonding Time**: `_______` days → [Configure in Section 4.10](#410-configure-staking-parameters) -- **Max Validators**: `_______` → [Configure in Section 4.10](#410-configure-staking-parameters) -- **Voting Period**: `_______` (30s testnet / 2d mainnet) → [Configure in Section 4.12](#412-configure-governance-parameters) -- **Min Deposit**: `_______` → [Configure in Section 4.12](#412-configure-governance-parameters) - -#### Network Configuration -- **Network Type**: Local / Testnet / Mainnet -- **Genesis Validators**: `_______` -- **Public RPC Nodes**: `_______` -- **Genesis Time**: `_______` → [Configure in Section 4.1](#41-set-genesis-time) - - -Save this planning document for reference throughout the configuration process. You'll use these values in multiple sections. - - ---- - -## 3. Pre-Genesis Setup - - -**CRITICAL TIMING SECTION** - -Everything in this section MUST be completed BEFORE running `yourchain init`. - -These settings CANNOT be changed after genesis without a hard fork. - -Do not proceed to genesis configuration until all items in this section are complete and verified. - - - -**Why This Section Exists** - -These parameters are compiled into your binary or written to configuration files during initialization. Changing them later requires: -- Rebuilding the binary -- Re-initializing all nodes -- Coordinating a network restart -- In some cases, a hard fork - -This section ensures you set everything correctly the first time. - - ---- - -### 3.1. Fork Repository and Rename Binary - -**What This Does**: Renames your blockchain binary from `evmd` to your chosen name and updates all Go import paths to match your project. - - - - - - - - -```bash -cd /path/to/cosmos-evm -mv evmd yourchain -``` - - - -```bash -# macOS -find . -type f -name "*.go" -exec sed -i '' \ - 's|github.com/cosmos/evm/evmd|github.com/your-org/your-chain/yourchain|g' {} \; - -# Linux -find . -type f -name "*.go" -exec sed -i \ - 's|github.com/cosmos/evm/evmd|github.com/your-org/your-chain/yourchain|g' {} \; -``` - - - -Edit `go.mod` manually: - -```go -// Change this: -module github.com/cosmos/evm - -// To this: -module github.com/your-org/your-chain -``` - - - -```bash -sed -i '' 's/evmd/yourchain/g' Makefile -``` - - - -```bash -go mod tidy -``` - - - -```bash -make build -./build/yourchain version -``` - - - - - - - - -```bash -# 1. Binary exists with new name -ls -la ./build/yourchain - -# 2. Version command works -./build/yourchain version - -# 3. No references to old name -grep -r "github.com/cosmos/evm/evmd" . --include="*.go" | wc -l -# Should output: 0 -``` - - - - - -**Files Modified**: -- `evmd/` → `yourchain/` (directory rename) -- All `*.go` files (import paths) -- `go.mod` (module declaration) -- `Makefile` (binary references) - - - - - ---- - -### 3.2. Set Bech32 Address Prefix - -**What This Does**: Defines your chain's address format (e.g., `cosmos1...`, `evmos1...`, `yourchain1...`). - -**File**: `config/config.go:62` - -**Default**: `cosmos` - - - - - -Edit `config/config.go`: - -```go -const ( - // Bech32Prefix defines the Bech32 prefix for your chain - Bech32Prefix = "yourchain" - - // 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 -) -``` - -Rebuild binary: -```bash -make build -``` - - - - - -After initialization (in later steps): - -```bash -# Create a test key -yourchain keys add test --keyring-backend test - -# Check address format starts with your prefix -yourchain keys show test --keyring-backend test -# Expected: yourchain1abc123... -``` - - - - - -Your Bech32 prefix determines all address formats: -- **Account addresses**: `yourchain1abc123...` -- **Validator operator**: `yourchainvaloper1abc123...` -- **Consensus addresses**: `yourchainvalcons1abc123...` -- **Account public keys**: `yourchainpub1abc123...` - - - - - -**Source**: [config/config.go:60-74](https://github.com/cosmos/evm/blob/main/config/config.go#L60-L74) - ---- - -### 3.3. Set BIP44 Coin Type - -**What This Does**: Sets the HD wallet derivation path for key generation following BIP-44 standard. - -**File**: `crypto/hd/hdpath.go:9` - -**Default**: `60` (Ethereum compatibility) - - - - - - - - - -**Use coin type `60`** - No changes needed (this is the default) - -```go -var ( - // Bip44CoinType satisfies EIP84 - Bip44CoinType uint32 = 60 // Ethereum compatibility - - // BIP44HDPath is the default BIP44 HD path - BIP44HDPath = ethaccounts.DefaultBaseDerivationPath.String() -) -``` - -**Derivation Path**: `m/44'/60'/0'/0/0` - -**Benefits**: -- Works with MetaMask and Ethereum wallets -- Standard for EVM-compatible chains -- No wallet configuration needed - - - - - -**Register and use a unique value** - -1. Register at [SLIP-0044](https://github.com/satoshilabs/slips/blob/master/slip-0044.md) -2. Update code: - -```go -var ( - // Bip44CoinType for your unique chain - Bip44CoinType uint32 = 12345 // Your registered value - - BIP44HDPath = ethaccounts.DefaultBaseDerivationPath.String() -) -``` - -**Use When**: Need distinct identity from Ethereum ecosystem - - - - - -Rebuild binary: -```bash -make build -``` - - - - - -After initialization: - -```bash -# Create a test key -yourchain keys add test --keyring-backend test - -# Key uses configured derivation path -# With coin type 60: m/44'/60'/0'/0/0 -``` - - - - - -**Source**: [crypto/hd/hdpath.go:7-13](https://github.com/cosmos/evm/blob/main/crypto/hd/hdpath.go#L7-L13) - ---- - -### 3.4. Set EVM Chain ID - -**What This Does**: Sets the EIP-155 chain ID for Ethereum transaction replay protection. This is what wallets like MetaMask use to identify your network. - -**File**: `config/config.go:78` - -**Type**: Number (uint64) - -**Default**: `262144` - - -**CRITICAL**: Choose carefully - cannot be changed after genesis without breaking all transaction signatures and wallet configurations. - - - - - - -Edit `config/config.go`: - -```go -const ( - // EVMChainID defines the EIP-155 replay-protection chain id - EVMChainID = 123456 // Your unique chain ID -) -``` - -Rebuild binary: -```bash -make build -``` - - - - - -**For Testing**: -- Use `262144` (evmd default) -- Or any high number > 100,000 -- No registration needed - -**For Production**: -1. Choose unique integer -2. Check [chainlist.org](https://chainlist.org) for conflicts -3. Register your chain ID -4. Document publicly - -**Avoid**: `1`, `56`, `137`, `10`, `42161` (see chainlist.org for full list) - - - - - -After initialization: - -```bash -# Check chain ID was written to app.toml -grep 'evm-chain-id' ~/.yourchain/config/app.toml -# Expected: evm-chain-id = 123456 -``` - - - - - -**During `init`**: Value from `config/config.go:78` → written to `app.toml` as `evm-chain-id` - -**During startup**: Node reads `evm-chain-id` from `app.toml` - -**In wallets**: MetaMask uses this ID to identify your network - - - - - -**Source**: [config/config.go:77-78](https://github.com/cosmos/evm/blob/main/config/config.go#L77-L78) - ---- - -### 3.5. Choose Token Decimal Precision - -**What This Does**: Determines whether your native token uses 18 decimals (like ETH) or 6 decimals (like ATOM). - -**Recommendation**: Use 18 decimals for simplicity and native EVM compatibility - - -This decision affects: -- Which modules you need (`x/bank` only vs. `x/precisebank`) -- EVM precision handling -- User experience with decimal places -- Cannot change after genesis without hard fork - - - - - - -**Native EVM Compatibility - No Extra Modules Required** - -**Configuration**: -- Base denom: `atoken` (atto-token, 10^-18) -- Display denom: `token` -- 1 token = 1,000,000,000,000,000,000 atoken - -**Advantages**: -- ✅ Direct 1:1 mapping with EVM -- ✅ No PreciseBank module needed -- ✅ Simpler architecture -- ✅ Standard for EVM chains - -**Setup**: -- Use standard `x/bank` module only -- No code changes needed beyond setting denomination names -- Skip extended_denom_options - - - - - -**Traditional Cosmos Precision - Requires Additional Module** - -**Configuration**: -- Base denom: `utoken` (micro-token, 10^-6) -- Display denom: `token` -- 1 token = 1,000,000 utoken - -**Requirements**: -- ✅ Must add `x/precisebank` module to `app.go` -- ✅ Must configure `extended_denom_options` in genesis -- ✅ Use `PreciseBankKeeper` in EVMKeeper - -**PreciseBank Integration** (in `app.go`): - -```go -import ( - precisebankkeeper "github.com/cosmos/evm/x/precisebank/keeper" - precisebanktypes "github.com/cosmos/evm/x/precisebank/types" - precisebank "github.com/cosmos/evm/x/precisebank" -) - -// Add to store keys -keys := storetypes.NewKVStoreKeys( - // ... other keys - precisebanktypes.StoreKey, -) - -// Initialize PreciseBankKeeper -app.PreciseBankKeeper = precisebankkeeper.NewKeeper( - appCodec, - keys[precisebanktypes.StoreKey], - app.BankKeeper, - app.AccountKeeper, -) - -// CRITICAL: Use PreciseBankKeeper in EVMKeeper -app.EVMKeeper = evmkeeper.NewKeeper( - appCodec, - keys[evmtypes.StoreKey], - app.GetSubspace(evmtypes.ModuleName), - app.AccountKeeper, - app.PreciseBankKeeper, // Not BankKeeper! - app.StakingKeeper, - app.FeeMarketKeeper, - authtypes.NewModuleAddress(govtypes.ModuleName).String(), -) - -// Add to module manager -app.ModuleManager = module.NewManager( - // ... other modules - precisebank.NewAppModule(app.PreciseBankKeeper, app.AccountKeeper), -) - -// Add to genesis order (after bank, before evm) -genesisModuleOrder := []string{ - // ... - banktypes.ModuleName, - precisebanktypes.ModuleName, - evmtypes.ModuleName, - // ... -} -``` - - -Failure to add PreciseBank will result in incorrect balances and transaction failures. - - - - - - -| Prefix | Decimals | Example | Used For | -|--------|----------|---------|----------| -| `a` (atto) | 18 | `atoken` | EVM chains (recommended) | -| `u` (micro) | 6 | `utoken` | Cosmos chains | -| `n` (nano) | 9 | `ntoken` | Some L2s | - - - - - - -**Learn More:** -- [Precision Handling Concepts](/docs/evm/next/documentation/concepts/precision-handling) -- [PreciseBank Module Reference](/docs/evm/next/documentation/cosmos-sdk/modules/precisebank) - - ---- - -### 3.6. Configure Default Token Denomination in Source Code - -**What This Does**: Changes hardcoded defaults so generated configs use your token instead of "aatom"/"atom". - - -Must be done BEFORE `yourchain init` and BEFORE building the binary. - - - - - - - - - - -**File**: `server/config/migration/v0.50-app.toml:11` - -```bash -# Change from: -minimum-gas-prices = "0aatom" - -# To (example): -minimum-gas-prices = "0atoken" -``` - -Using sed: -```bash -sed -i '' 's/minimum-gas-prices = "0aatom"/minimum-gas-prices = "0atoken"/' \ - server/config/migration/v0.50-app.toml -``` - - - - - -**File**: `x/vm/types/params.go:21-25` - -For **18 decimals**: -```go -var ( - DefaultEVMDenom = "atoken" - DefaultEVMExtendedDenom = "atoken" - DefaultEVMDisplayDenom = "token" -) -``` - -For **6 decimals**: -```go -var ( - DefaultEVMDenom = "utoken" - DefaultEVMExtendedDenom = "atoken" - DefaultEVMDisplayDenom = "token" -) -``` - - - - - -**File**: `config/constants.go:5-8` - -```go -const ( - ExampleChainDenom = "atoken" // Your base denom - ExampleDisplayDenom = "token" // Your display denom -) -``` - - - - - -```bash -make build -``` - - - - - - - - - -After initialization: - -```bash -# Check generated app.toml uses your denomination -grep "minimum-gas-prices" ~/.yourchain/config/app.toml -# Expected: minimum-gas-prices = "0atoken" -``` - - - - - -**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) - ---- - -### Pre-Genesis Completion Checklist - -Before proceeding to Section 4, verify all pre-genesis setup is complete: - -```bash -# 1. Binary renamed and built -./build/yourchain version -# ✓ Should show your chain name, not "evmd" - -# 2. Bech32 prefix set in code -grep "Bech32Prefix = " config/config.go -# ✓ Should show your prefix - -# 3. BIP44 coin type set in code -grep "Bip44CoinType uint32 = " crypto/hd/hdpath.go -# ✓ Should show your coin type (typically 60) - -# 4. EVM chain ID set in code -grep "EVMChainID = " config/config.go -# ✓ Should show your EVM chain ID - -# 5. Token decimals decided -# ✓ 18 decimals → No PreciseBank needed -# ✓ 6 decimals → PreciseBank integrated in app.go - -# 6. Default denominations updated in source -grep "DefaultEVMDenom = " x/vm/types/params.go -grep "minimum-gas-prices" server/config/migration/v0.50-app.toml -# ✓ Should show your denomination -``` - - -**DO NOT PROCEED** until all items are verified. These settings cannot be changed after `yourchain init` without starting over. - - ---- - -## 4. Genesis Configuration - -Now that your binary is configured, initialize your chain and configure genesis parameters. - -### Initialize Your Chain - -```bash -yourchain init --chain-id -``` - -**Example**: -```bash -yourchain init mynode --chain-id mychain-1 -``` - -This creates `~/.yourchain/` with: -- `config/genesis.json` - You'll edit this -- `config/app.toml` - Runtime configuration -- `config/config.toml` - CometBFT configuration -- `data/` - Blockchain data - - -Set environment variable for easier commands: - -```bash -export GENESIS=~/.yourchain/config/genesis.json -``` - - ---- - -### 4.1. Set Genesis Time - -**What This Does**: Sets UTC timestamp when chain starts producing blocks. - -**Genesis Location**: Root level `genesis_time` - - - - - -```bash -jq '.genesis_time = "2024-12-01T00:00:00Z"' $GENESIS > tmp && mv tmp $GENESIS -``` - -**For local testing**: Use current time or leave default (immediate start) - -**For coordinated launch**: Set 24-48 hours in future to allow validator preparation - - - - - -- All validators must have identical genesis_time -- Chain auto-starts at this time when 2/3+ validators online -- Validators start nodes before genesis_time -- If genesis_time is past, chain starts immediately - - - - - -```bash -jq '.genesis_time' $GENESIS -# Output: "2024-12-01T00:00:00Z" -``` - - - - - ---- - -### 4.2. Configure Bank Metadata - -**What This Does**: Defines token denomination, decimal precision, and display properties. - -**Genesis Location**: `app_state.bank.denom_metadata` - - -The `base` denomination MUST match: -- `app_state.evm.params.evm_denom` -- `app_state.staking.params.bond_denom` -- `app_state.mint.params.mint_denom` -- `app_state.gov.params.min_deposit[0].denom` - - - - - - -```bash -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" -}]' $GENESIS > tmp && mv tmp $GENESIS -``` - - - - - -```bash -jq '.app_state.bank.denom_metadata=[{ - "description": "The native staking and gas token", - "denom_units": [ - { - "denom": "utoken", - "exponent": 0, - "aliases": ["microtoken"] - }, - { - "denom": "token", - "exponent": 6, - "aliases": [] - } - ], - "base": "utoken", - "display": "token", - "name": "My Token", - "symbol": "TKN" -}]' $GENESIS > tmp && mv tmp $GENESIS -``` - - -Also requires `extended_denom_options` (see Section 4.4) - - - - - - -| Field | Description | Example | -|-------|-------------|---------| -| `base` | Smallest unit (on-chain) | `atoken`, `utoken` | -| `display` | Human-readable unit | `token` | -| `exponent` | Decimal places | `18` or `6` | -| `name` | Full token name | `"My Token"` | -| `symbol` | Ticker symbol | `"TKN"` | - - - - - -```bash -jq '.app_state.bank.denom_metadata' $GENESIS -``` - - - - - ---- - -### 4.3. Set EVM Denom - -**What This Does**: Specifies which bank denomination is the native EVM gas token. - -**Genesis Location**: `app_state.evm.params.evm_denom` - - - - - -```bash -# For 18-decimal token -jq '.app_state.evm.params.evm_denom = "atoken"' $GENESIS > tmp && mv tmp $GENESIS - -# For 6-decimal token -jq '.app_state.evm.params.evm_denom = "utoken"' $GENESIS > tmp && mv tmp $GENESIS -``` - - - - - -```bash -jq '.app_state.evm.params.evm_denom' $GENESIS -# Must match bank metadata base denom -``` - - - - - -**Source**: [x/vm/types/params.go:21](https://github.com/cosmos/evm/blob/main/x/vm/types/params.go#L21) - ---- - -### 4.4. Configure Extended Denom Options - -**What This Does**: Provides 18-decimal representation for EVM when using non-18 decimal native token. - -**Genesis Location**: `app_state.evm.params.extended_denom_options` - -**Required For**: 6-decimal chains or other non-18 decimal configurations - - - - - -```bash -jq '.app_state.evm.params.extended_denom_options = { - "extended_denom": "atoken" -}' $GENESIS > tmp && mv tmp $GENESIS -``` - -**Example Genesis**: -```json -{ - "app_state": { - "evm": { - "params": { - "evm_denom": "utoken", - "extended_denom_options": { - "extended_denom": "atoken" - } - } - } - } -} -``` - - -Must also have PreciseBank module integrated in app.go (see Section 3.5) - - - - - - -- Base denom: `utoken` (6 decimals) -- EVM sees: `atoken` (18 decimals) -- PreciseBank converts: 1 utoken = 10^12 wei - - - - - -Not needed for 18-decimal tokens. Leave this section empty. - - - - - -**Source**: [x/vm/types/params.go:76](https://github.com/cosmos/evm/blob/main/x/vm/types/params.go#L76) - ---- - -### 4.5. Configure ERC20 Token Pairs - -**What This Does**: Creates ERC20 representation of your native token for EVM compatibility. - -**Genesis Location**: `app_state.erc20.token_pairs` and `app_state.erc20.native_precompiles` - -**Special Address**: `0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE` (native token) - - - - - -```bash -# Set token pair -jq '.app_state.erc20.token_pairs = [{ - "erc20_address": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE", - "denom": "atoken", - "enabled": true, - "contract_owner": 1 -}]' $GENESIS > tmp && mv tmp $GENESIS - -# Set native precompile -jq '.app_state.erc20.native_precompiles = ["0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE"]' $GENESIS > tmp && mv tmp $GENESIS -``` - -**Note**: Replace `"atoken"` with your base denomination - - - - - -| Field | Value | Description | -|-------|-------|-------------| -| `erc20_address` | Special address | Native token ERC20 address | -| `denom` | Your base denom | Must match bank metadata | -| `enabled` | `true` | Token pair is active | -| `contract_owner` | `1` | Module-owned | - - - - - -```bash -jq '.app_state.erc20.token_pairs' $GENESIS -jq '.app_state.erc20.native_precompiles' $GENESIS -``` - - - - - - -**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) - - ---- - -### 4.6. Enable Required Precompiles - -**What This Does**: Enables precompiled contracts that provide Cosmos SDK functionality to EVM. - -**Genesis Location**: `app_state.evm.params.active_static_precompiles` - - - - - -| Address | Name | Purpose | -|---------|------|---------| -| `0x0100` | P256 | Web3 auth, passkeys | -| `0x0400` | Bech32 | Address conversion | -| `0x0800` | Staking | Validator operations | -| `0x0801` | Distribution | Reward claiming | -| `0x0802` | ICS20 | IBC transfers | -| `0x0803` | Vesting | Token vesting | -| `0x0804` | Bank | Native transfers | -| `0x0805` | Governance | On-chain voting | -| `0x0806` | Slashing | Validator info | -| `0x0807` | Authz | Permissions | - - - - - -```bash -jq '.app_state.evm.params.active_static_precompiles = [ - "0x0000000000000000000000000000000000000100", - "0x0000000000000000000000000000000000000400", - "0x0000000000000000000000000000000000000800", - "0x0000000000000000000000000000000000000801", - "0x0000000000000000000000000000000000000802", - "0x0000000000000000000000000000000000000803", - "0x0000000000000000000000000000000000000804", - "0x0000000000000000000000000000000000000805", - "0x0000000000000000000000000000000000000806", - "0x0000000000000000000000000000000000000807" -]' $GENESIS > tmp && mv tmp $GENESIS -``` - - - - - -Example for DeFi-focused chain: - -```bash -jq '.app_state.evm.params.active_static_precompiles = [ - "0x0000000000000000000000000000000000000100", # P256 - "0x0000000000000000000000000000000000000400", # Bech32 - "0x0000000000000000000000000000000000000800", # Staking - "0x0000000000000000000000000000000000000804" # Bank -]' $GENESIS > tmp && mv tmp $GENESIS -``` - - - - - -```bash -jq '.app_state.evm.params.active_static_precompiles' $GENESIS -``` - - - - - - -**Learn More**: [Precompiles Overview](/docs/evm/next/documentation/smart-contracts/precompiles/overview) - - -**Source**: [x/vm/types/precompiles.go:22-32](https://github.com/cosmos/evm/blob/main/x/vm/types/precompiles.go#L22-L32) - ---- - -### 4.7. Configure Predeployed Contracts - -**What This Does**: Deploys essential smart contracts at genesis to standard addresses. - -**Genesis Location**: `app_state.evm.preinstalls` - - - - - -Automatically deployed during init: - -1. **CREATE2 Deployer** (`0x4e59b44847b379578588920cA78FbF26c0B4956C`) - - Deterministic contract deployment - -2. **Multicall3** (`0xcA11bde05977b3631167028862bE2a173976CA11`) - - Batch multiple read calls - -3. **Permit2** (`0x000000000022D473030F116dDEE9F6B43aC78BA3`) - - Uniswap's token approval system - -4. **Safe Factory** (`0x4e1DCf7AD4e460CfD30791CCC4F9c8a4f820ec67`) - - Gnosis Safe multisig deployment - - - - - -```bash -jq '.app_state.evm.preinstalls' $GENESIS -``` - - -These contracts are hardcoded and automatically included. No manual configuration needed. - - - - - - ---- - -### 4.8. Configure EVM Access Control - -**What This Does**: Sets permissions for deploying and calling smart contracts. - -**Genesis Location**: `app_state.evm.params.access_control` - - - - - -| Type | Value | Behavior | -|------|-------|----------| -| Permissionless | `0` | Anyone can perform action | -| Restricted | `1` | Block addresses in list | -| Permissioned | `2` | Only addresses in list | - - - - - -```bash -jq '.app_state.evm.params.access_control = { - "create": { - "access_type": 0, - "access_control_list": [] - }, - "call": { - "access_type": 0, - "access_control_list": [] - } -}' $GENESIS > tmp && mv tmp $GENESIS -``` - -**Use For**: Public chains, testnets, open ecosystems - - - - - -```bash -jq '.app_state.evm.params.access_control = { - "create": { - "access_type": 2, - "access_control_list": [ - "0x1234567890123456789012345678901234567890", - "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd" - ] - }, - "call": { - "access_type": 0, - "access_control_list": [] - } -}' $GENESIS > tmp && mv tmp $GENESIS -``` - -**Use For**: Enterprise chains, controlled deployment - - - - - -```bash -jq '.app_state.evm.params.access_control.create = { - "access_type": 1, - "access_control_list": [ - "0xBADADDRESS1234567890123456789012345678" - ] -}' $GENESIS > tmp && mv tmp $GENESIS -``` - -**Use For**: Blocking known malicious addresses - - - - - -```bash -jq '.app_state.evm.params.access_control' $GENESIS -``` - - - - - -**Source**: [x/vm/types/params.go:160-165](https://github.com/cosmos/evm/blob/main/x/vm/types/params.go#L160-L165) - ---- - -### 4.9. Configure EIP-1559 Fee Market - -**What This Does**: Configures Ethereum's EIP-1559 dynamic fee market for automatic fee adjustment. - -**Genesis Location**: `app_state.feemarket.params` - - - - - -```bash -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 -}' $GENESIS > tmp && mv tmp $GENESIS -``` - -**Use For**: Standard Ethereum-compatible chains - - - - - -| Parameter | Default | Description | -|-----------|---------|-------------| -| `no_base_fee` | `false` | Enable EIP-1559 | -| `base_fee` | `"1000000000"` | 1 gwei initial | -| `base_fee_change_denominator` | `8` | ±12.5% max change | -| `elasticity_multiplier` | `2` | Target = 50% max gas | -| `min_gas_price` | `"0"` | Network minimum | -| `min_gas_multiplier` | `"0.5"` | 50% of base fee | -| `enable_height` | `0` | Enabled from genesis | - - - - - -```bash -jq '.app_state.feemarket.params = { - "no_base_fee": true, - "min_gas_price": "1000000000" -}' $GENESIS > tmp && mv tmp $GENESIS -``` - -**Use For**: Traditional Cosmos chains or testing - - - - - -```bash -jq '.app_state.feemarket.params' $GENESIS -``` - - - - - - -**Learn More**: [EIP-1559 Fee Market Concepts](/docs/evm/next/documentation/concepts/eip-1559-feemarket) - - -**Source**: [x/feemarket/types/params.go:13-21](https://github.com/cosmos/evm/blob/main/x/feemarket/types/params.go#L13-L21) - ---- - -### 4.10. Configure Staking Parameters - -**What This Does**: Configures validator staking, unbonding periods, and related parameters. - -**Genesis Location**: `app_state.staking.params` - - - - - -```bash -# Set bond denomination -jq '.app_state.staking.params.bond_denom = "atoken"' $GENESIS > tmp && mv tmp $GENESIS - -# Set unbonding time -jq '.app_state.staking.params.unbonding_time = "1814400s"' $GENESIS > tmp && mv tmp $GENESIS - -# Set max validators -jq '.app_state.staking.params.max_validators = 100' $GENESIS > tmp && mv tmp $GENESIS -``` - - - - - -| Parameter | Default | Description | -|-----------|---------|-------------| -| `bond_denom` | - | Must match your base denom | -| `unbonding_time` | `"1814400s"` | 21 days | -| `max_validators` | `100` | Maximum active validators | -| `max_entries` | `7` | Max concurrent operations | -| `historical_entries` | `10000` | For IBC light clients | - -**Unbonding Time Examples**: -- `"120s"` = 2 minutes (testing) -- `"604800s"` = 7 days -- `"1814400s"` = 21 days (Cosmos standard) -- `"2419200s"` = 28 days - - - - - -```bash -jq '.app_state.staking.params' $GENESIS -``` - - - - - ---- - -### 4.11. Configure Mint Parameters - -**What This Does**: Configures token inflation and minting schedule. - -**Genesis Location**: `app_state.mint.params` - - - - - -```bash -jq '.app_state.mint.params.mint_denom = "atoken"' $GENESIS > tmp && mv tmp $GENESIS -``` - -**Complete Parameters**: -```json -{ - "mint_denom": "atoken", - "inflation_rate_change": "0.130000000000000000", - "inflation_max": "0.200000000000000000", - "inflation_min": "0.070000000000000000", - "goal_bonded": "0.670000000000000000", - "blocks_per_year": "6311520" -} -``` - - - - - -| Parameter | Default | Description | -|-----------|---------|-------------| -| `mint_denom` | - | Must match base denom | -| `inflation_max` | `0.20` | 20% max annual | -| `inflation_min` | `0.07` | 7% min annual | -| `goal_bonded` | `0.67` | 67% target staked | - - - - - -```bash -jq '.app_state.mint.params' $GENESIS -``` - - - - - ---- - -### 4.12. Configure Governance Parameters - -**What This Does**: Configures on-chain governance including voting periods and requirements. - -**Genesis Location**: `app_state.gov.params` - - - - - -```bash -# Set deposit denomination -jq '.app_state.gov.params.min_deposit[0].denom = "atoken"' $GENESIS > tmp && mv tmp $GENESIS - -# Set voting period -jq '.app_state.gov.params.voting_period = "172800s"' $GENESIS > tmp && mv tmp $GENESIS - -# For testnet (fast testing) -jq '.app_state.gov.params.voting_period = "30s"' $GENESIS > tmp && mv tmp $GENESIS -``` - - - - - -| Parameter | Default | Description | -|-----------|---------|-------------| -| `min_deposit` | - | Minimum to submit proposal | -| `voting_period` | `"172800s"` | 2 days (mainnet) | -| `quorum` | `"0.334"` | 33.4% participation | -| `threshold` | `"0.5"` | 50% yes votes | -| `veto_threshold` | `"0.334"` | 33.4% veto | - -**Voting Period**: -- Testnet: `"30s"` -- Mainnet: `"172800s"` (2 days) or `"604800s"` (7 days) - - - - - -```bash -jq '.app_state.gov.params' $GENESIS -``` - - - - - ---- - -### 4.13. Add Genesis Accounts with Initial Balances - -**What This Does**: Creates accounts with initial token balances at genesis. - - - - - -```bash -# Using address -yourchain genesis add-genesis-account \ - cosmos1abc123... \ - 1000000000000000000000atoken - -# Using key name from keyring -yourchain genesis add-genesis-account \ - validator1 \ - 1000000000000000000000atoken \ - --keyring-backend test -``` - - - - - -```bash -yourchain genesis add-genesis-account validator1 1000000000000000000000atoken -yourchain genesis add-genesis-account validator2 1000000000000000000000atoken -yourchain genesis add-genesis-account faucet 10000000000000000000000atoken -``` - - - - - -```bash -# Create accounts file -cat > accounts.json < - - - -```bash -jq '.app_state.bank.balances' $GENESIS -``` - - - - - ---- - -### 4.14. Collect Validator Genesis Transactions - -**What This Does**: Gathers validator self-delegation transactions for genesis. - - - - - -```bash -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**: `~/.yourchain/config/gentx/gentx-.json` - - - - - -```bash -# Receive all gentx files from validators -mkdir -p ~/.yourchain/config/gentx/ -# Copy received gentx files to this directory - -# Collect into genesis -yourchain genesis collect-gentxs -``` - - - - - -```bash -yourchain genesis validate -jq '.app_state.genutil.gen_txs' $GENESIS -``` - - - - - ---- - -### 4.15. Validate Final Genesis File - -**What This Does**: Validates genesis file for correctness before network launch. - - - - - -```bash -yourchain genesis validate -``` - - - - - -- JSON structure is valid -- All module genesis states are valid -- No denomination mismatches -- Token supply is consistent -- All parameters within valid ranges -- Gentxs are valid - - - - - -```bash -# 1. Validate structure -yourchain genesis validate - -# 2. Check all denoms match -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 identical) - -# 3. Verify total supply -jq '.app_state.bank.balances | map(.coins[0].amount | tonumber) | add' $GENESIS - -# 4. Check validator count -jq '.app_state.genutil.gen_txs | length' $GENESIS -``` - - - - - -**Denomination Mismatch**: -``` -Error: bond_denom (utoken) does not match evm_denom (atoken) -``` -Fix: Ensure all denoms match across modules - -**Invalid Supply**: -``` -Error: total supply does not match balances -``` -Fix: Check genesis accounts and recalculate - -**Invalid Parameter**: -``` -Error: min_gas_multiplier must be between 0 and 1 -``` -Fix: Correct parameter value - - - - - ---- - -## 5. Runtime Configuration - -Configure `~/.yourchain/config/app.toml` for runtime settings. - -### 5.1. Configure JSON-RPC - -**What This Does**: Configures Ethereum JSON-RPC server for wallet/dApp access. - -**File**: `~/.yourchain/config/app.toml` - -**Section**: `[json-rpc]` - - - - - -```toml -[json-rpc] -# Enable JSON-RPC server -enable = true - -# HTTP server address -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 - -# Allow unprotected transactions (dev only!) -allow-unprotected-txs = false - -# Enable transaction indexer -enable-indexer = true -``` - - - - - -| Namespace | Description | Recommended For | -|-----------|-------------|-----------------| -| `eth` | Standard Ethereum RPC | All nodes (required) | -| `net` | Network information | All nodes | -| `web3` | Web3 client version | All nodes | -| `txpool` | Transaction pool | Dev/monitoring | -| `debug` | Debug/trace endpoints | Dev only (not prod) | - - - - - -**For Production**: -- Use `address = "127.0.0.1:8545"` + reverse proxy -- Enable rate limiting -- Set `allow-unprotected-txs = false` -- Remove `debug` from API namespaces - -**For Development**: -- Use `address = "0.0.0.0:8545"` for network access -- Enable all APIs including `debug` -- Set `allow-unprotected-txs = true` for convenience - - - - - ---- - -### 5.2. Configure EVM Settings - -**What This Does**: EVM execution configuration including tracer and gas limits. - -**File**: `~/.yourchain/config/app.toml` - -**Section**: `[evm]` - - - - - -```toml -[evm] -# EVM chain ID (read-only, set during init) -evm-chain-id = 262144 - -# Tracer type for debugging -tracer = "" - -# Maximum gas limit per transaction (0 = unlimited) -max-tx-gas-wanted = 0 - -# Cache preimages for historical queries -cache-preimage = false - -# Minimum tip (priority fee) in wei -min-tip = 1000000000 - -# Geth metrics server address -geth-metrics-address = "127.0.0.1:8100" -``` - - - - - -| Parameter | Default | Description | -|-----------|---------|-------------| -| `evm-chain-id` | From init | Read-only, don't modify | -| `tracer` | `""` | `"json"` for debug, `""` for prod | -| `max-tx-gas-wanted` | `0` | Transaction gas limit | -| `min-tip` | `0` | Minimum priority fee (wei) | - - - - - - -`evm-chain-id` is written during init and should NOT be manually edited. - -To change it: -1. Modify `config/config.go:78` -2. Rebuild binary -3. Re-run init - - - - - - ---- - -### 5.3. Configure EVM Mempool - -**What This Does**: Controls transaction pool behavior including price limits and queue sizes. - -**File**: `~/.yourchain/config/app.toml` - -**Section**: `[evm.mempool]` - - -**New in v0.5.0**: Mempool configuration now fully exposed in `app.toml` - - - - - - -```toml -[evm.mempool] -# Minimum gas price to accept (wei) -price-limit = 1000000000 - -# Minimum % price increase to replace transaction -price-bump = 10 - -# Executable transaction slots per account -account-slots = 16 - -# Total executable slots for all accounts -global-slots = 5120 - -# Queued transaction slots per account -account-queue = 64 - -# Total queued slots for all accounts -global-queue = 1024 - -# Maximum time transactions stay in queue -lifetime = "3h0m0s" -``` - - - - - -| Parameter | Default | Description | -|-----------|---------|-------------| -| `price-limit` | `1` | Min gas price (wei) | -| `price-bump` | `10` | Min % increase to replace (10%) | -| `account-slots` | `16` | Guaranteed slots per account | -| `global-slots` | `5120` | Total executable slots | -| `account-queue` | `64` | Queued slots per account | -| `global-queue` | `1024` | Total queued slots | -| `lifetime` | `"3h0m0s"` | Max time in mempool | - - - - - -**High-Throughput Chain**: -```toml -global-slots = 10240 -global-queue = 2048 -price-limit = 100000000 -lifetime = "6h0m0s" -``` - -**Low-Resource Node**: -```toml -global-slots = 2048 -global-queue = 512 -lifetime = "1h0m0s" -account-slots = 8 -``` - - - - - -**Source**: [server/config/config.go:158-187](https://github.com/cosmos/evm/blob/main/server/config/config.go#L158-L187) - ---- - -### 5.4. Set Minimum Gas Prices - -**What This Does**: Node-level minimum gas price that rejects lower-priced transactions. - -**File**: `~/.yourchain/config/app.toml` - -**Format**: `` - - - - - -```toml -minimum-gas-prices = "1000000000atoken" -``` - -**Examples**: -- `"1000000000atoken"` = 1 gwei -- `"500000000atoken"` = 0.5 gwei -- `"0atoken"` = accept all (not recommended) - - - - - -- Node rejects transactions below this price -- Protects against spam -- Should align with genesis fee market config -- Each node can set independently - - - - - ---- - -### 5.5. Configure Network Peers - -**What This Does**: Sets persistent peer connections for network participation. - -**File**: `~/.yourchain/config/config.toml` - - - - - -Each node runs: -```bash -yourchain comet show-node-id -``` - -Output: `7c90e16cca334eb7259754f964918d879ca54996` - -**Share**: `@:` - -Example: `7c90e16cca334eb7259754f964918d879ca54996@192.168.1.100:26656` - - - - - -Edit `~/.yourchain/config/config.toml`: - -```toml -# Comma-separated list of persistent peers -persistent_peers = "7c90e16c@192.168.1.100:26656,abc123de@192.168.1.101:26656,def456ab@192.168.1.102:26656" -``` - - - - - -```bash -curl localhost:26657/net_info | jq '.result.peers' -``` - - - - - ---- - -### 5.6. Set Client Chain ID - -**What This Does**: Sets chain-id in client configuration for CLI operations and node startup validation. - -**File**: `~/.yourchain/config/client.toml` - - - - - -```bash -yourchain config set client chain-id mychain-1 --home ~/.yourchain -``` - -Or edit `~/.yourchain/config/client.toml` manually: -```toml -chain-id = "mychain-1" -``` - - - - - -The node reads chain-id from `client.toml` at startup. If it doesn't match `genesis.json`, the node will fail with: -``` -error during handshake: error on replay: invalid chain-id on InitChain -``` - - - - - -```bash -# Check matches genesis.json -jq '.chain_id' $GENESIS -# Output: "mychain-1" - -# Check set in client.toml -grep 'chain-id' ~/.yourchain/config/client.toml -# Output: chain-id = "mychain-1" -``` - - - - - ---- - -## 6. Network Launch - -Coordinate launch with all validators. - -### 6.1. Distribute Final Genesis File - -**What This Does**: Shares genesis file with all validators. - - - - - - - - - -```bash -# Coordinator uploads -ipfs add ~/.yourchain/config/genesis.json -# Returns: QmXyz123... - -# Validators download -ipfs get QmXyz123... -o ~/.yourchain/config/genesis.json -``` - - - - - -```bash -# Coordinator creates release -gh release create v1.0.0 ~/.yourchain/config/genesis.json - -# Validators download -wget https://github.com/yourorg/yourchain/releases/download/v1.0.0/genesis.json \ - -O ~/.yourchain/config/genesis.json -``` - - - - - - - - - ---- - -### 6.2. Verify Genesis Hash - -**What This Does**: Ensures all validators have identical genesis files. - - - - - - - - -```bash -jq -S -c . $GENESIS | shasum -a 256 -``` - -Output: `a1b2c3d4e5f6...` - -Publish this hash publicly - - - -```bash -jq -S -c . $GENESIS | shasum -a 256 -``` - -Compare with published hash - must match exactly - - - -All validators report matching hash before proceeding - - - - - - - - - -Even one character difference means different genesis state. - -Do NOT proceed unless ALL validators confirm identical hashes. - - - - - - ---- - -### 6.3. Exchange Peer Information - -**What This Does**: Validators share node IDs and connection info. - - - - - -Each validator provides: -```bash -# Get node ID -yourchain comet show-node-id -# Output: 7c90e16cca334eb7259754f964918d879ca54996 - -# Share format: @: -# Example: 7c90e16cca334eb7259754f964918d879ca54996@192.168.1.100:26656 -``` - -**Create coordination sheet**: - -| Validator | Node ID | IP Address | Connection String | -|-----------|---------|------------|-------------------| -| Validator 1 | 7c90e16c... | 192.168.1.100 | 7c90e16c@192.168.1.100:26656 | -| Validator 2 | abc123de... | 192.168.1.101 | abc123de@192.168.1.101:26656 | -| Validator 3 | def456ab... | 192.168.1.102 | def456ab@192.168.1.102:26656 | - - - - - -Each validator updates `~/.yourchain/config/config.toml`: -```toml -persistent_peers = "7c90e16c@192.168.1.100:26656,abc123de@192.168.1.101:26656,def456ab@192.168.1.102:26656" -``` - - - - - -### 6.4. Start Validator Nodes - -**What This Does**: Starts nodes and coordinates chain launch at genesis time. - - - - - - - - -All validators check: -```bash -jq '.genesis_time' $GENESIS -``` - -Ensure same value for all validators - - - -Start 15-30 minutes before genesis_time: - -```bash -yourchain start -``` - -Expected output: -``` -Genesis time is in the future. Waiting... -Time until genesis: 29m 45s -``` - - - -At genesis_time, chain begins automatically when 2/3+ voting power online - -Monitor logs: -```bash -yourchain start 2>&1 | grep "finalizing commit" -``` - -Expected: -``` -INF finalizing commit of block hash=ABC123... height=1 -INF finalizing commit of block hash=DEF456... height=2 -``` - - - - - - - - -**Check block height**: -```bash -curl localhost:26657/status | jq '.result.sync_info.latest_block_height' -``` - -**Check validator count**: -```bash -curl localhost:26657/validators | jq '.result.validators | length' -``` - -**Check voting power**: -```bash -curl localhost:26657/validators | \ - jq '[.result.validators[].voting_power | tonumber] | add' -``` - -**Test RPC**: -```bash -curl http://localhost:8545 \ - -X POST \ - -H "Content-Type: application/json" \ - -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' -``` - - - - - -**Chain Not Starting**: -- Check genesis_time hasn't passed -- Verify 2/3+ validators online -- Check logs for errors -- Verify persistent_peers configured - -**Not Producing Blocks**: -- Verify >= 2/3 voting power online -- Check validator gentxs in genesis -- Confirm no consensus errors - -**Peer Connection Issues**: -- Verify persistent_peers configured correctly -- Check firewall rules (port 26656) -- Confirm IP addresses are reachable - - - - - ---- - -## 7. Post-Launch Operations - -### 7.1. Monitoring & Alerting - -**What This Does**: Sets up monitoring infrastructure for chain health. - - - - - -Edit `~/.yourchain/config/config.toml`: - -```toml -[instrumentation] -prometheus = true -prometheus_listen_addr = ":26660" -``` - -Restart node to apply. - - - - - -**Critical Metrics**: -- Block production rate (~6-8s per block) -- Validator uptime and participation -- Missed blocks (slashing risk) -- Peer connections (network health) -- Disk usage (state growth) -- Memory usage -- Transaction throughput - -**EVM-Specific Metrics** (on port 8100): -- Gas usage per block -- Transaction pool size -- EVM execution time -- Base fee changes (EIP-1559) - - - - - -**Critical Alerts**: -- Validator jailed -- Missed blocks > 5 -- RPC downtime -- Node out of sync (> 10 blocks behind) - -**Warning Alerts**: -- Disk > 80% full -- Memory > 85% used -- Peer connections < expected -- High transaction rejection rate - - - - - -**Prometheus + Grafana**: Metrics and dashboards - -**Tenderduty**: Validator-specific monitoring -```bash -git clone https://github.com/blockpane/tenderduty -cd tenderduty -go install -``` - -**Custom Dashboards**: Import Cosmos SDK and EVM dashboards for Grafana - - - - - ---- - -### 7.2. Governance Parameter Updates - -**What This Does**: Changes chain parameters after launch through on-chain governance. - - - - - -**Via Governance**: -- `active_static_precompiles` (VM) -- `access_control` (VM) -- Fee market parameters -- Staking parameters (unbonding_time, max_validators) -- Governance parameters (voting_period, quorum) -- Distribution parameters (community_tax) -- Mint parameters (inflation) - -**Cannot Change**: -- EVM chain ID -- Bech32 prefix -- BIP44 coin type -- Token decimals - - - - - -```bash -# Create proposal JSON -cat > proposal.json < - - - -```bash -yourchain tx gov vote 1 yes \ - --from validator1 \ - --chain-id mychain-1 -``` - -**Vote Options**: `yes`, `no`, `abstain`, `no_with_veto` - - - - - ---- - -### 7.3. Software Upgrades - -**What This Does**: Plans and executes coordinated software upgrades. - - - - - - - - -- Watch [cosmos/evm releases](https://github.com/cosmos/evm/releases) -- Review changelogs for breaking changes -- Check for security patches - - - -- Deploy upgrade to testnet first -- Verify all features work -- Measure upgrade duration -- Test rollback if needed - - - - -```bash -cat > upgrade-proposal.json < - - - -Create `app/upgrades/v0_5_0/upgrades.go`: - -```go -package v0_5_0 - -import ( - sdk "github.com/cosmos/cosmos-sdk/types" - "github.com/cosmos/cosmos-sdk/types/module" - upgradetypes "github.com/cosmos/cosmos-sdk/x/upgrade/types" -) - -func CreateUpgradeHandler( - mm *module.Manager, - configurator module.Configurator, -) upgradetypes.UpgradeHandler { - return func(ctx sdk.Context, plan upgradetypes.Plan, vm module.VersionMap) (module.VersionMap, error) { - // Custom upgrade logic here - return mm.RunMigrations(ctx, configurator, vm) - } -} -``` - -Register in `app/app.go`: -```go -import v0_5_0 "github.com/your-org/your-chain/app/upgrades/v0_5_0" - -app.UpgradeKeeper.SetUpgradeHandler( - "v0.5.0", - v0_5_0.CreateUpgradeHandler(app.mm, app.configurator), -) -``` - - - - - -1. Proposal passes via governance -2. Chain halts at upgrade height -3. Validators swap binaries: - -```bash -# Stop old binary (automatic halt) -# Replace binary -cp yourchain-v0.5.0 $GOPATH/bin/yourchain -# Restart -yourchain start -``` - -4. Chain resumes with new version - - - - - - - - - -- **Test thoroughly** on testnet first -- **Coordinate timing** with validators -- **Prepare rollback plan** if needed -- **Communicate clearly** with community -- **Monitor closely** during upgrade -- **Have backup nodes** ready - - - - - - -**Learn More**: [Upgrade Handlers Guide](/docs/evm/next/documentation/migrations/upgrade-handlers) - - ---- - -## 8. Complete Examples - -### 8.1. Example: 18-Decimal Chain Setup - -Complete working example for an 18-decimal EVM-compatible chain. - - - - - -```bash -#!/bin/bash -# Complete setup script for 18-decimal chain - -BINARY="yourchain" -CHAIN_ID="yourchain-1" -DENOM="atoken" -GENESIS=~/.yourchain/config/genesis.json - -# Initialize -$BINARY init mynode --chain-id $CHAIN_ID - -# 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 - -# Set bank metadata (18 decimals) -jq ".app_state.bank.denom_metadata=[{ - \"description\": \"The native staking token\", - \"denom_units\": [ - {\"denom\": \"$DENOM\", \"exponent\": 0, \"aliases\": [\"attotoken\"]}, - {\"denom\": \"token\", \"exponent\": 18, \"aliases\": []} - ], - \"base\": \"$DENOM\", - \"display\": \"token\", - \"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 - -# Configure ERC20 token pair -jq '.app_state.erc20.token_pairs=[{ - "erc20_address": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE", - "denom": "atoken", - "enabled": true, - "contract_owner": 1 -}]' $GENESIS > tmp && mv tmp $GENESIS - -jq '.app_state.erc20.native_precompiles=["0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE"]' $GENESIS > tmp && mv tmp $GENESIS - -echo "Genesis configuration complete!" -``` - - - - - -```toml -[evm] -evm-chain-id = 262144 -tracer = "" -max-tx-gas-wanted = 0 -min-tip = 1000000000 # 1 gwei - -[evm.mempool] -price-limit = 1000000000 -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 -enable-indexer = true - -minimum-gas-prices = "1000000000atoken" -``` - - - - - ---- - -### 8.2. Example: 6-Decimal Chain with PreciseBank - -Complete working example for a 6-decimal chain with PreciseBank integration. - - - - - -```bash -#!/bin/bash -# Complete setup script for 6-decimal chain - -BINARY="yourchain" -CHAIN_ID="yourchain-1" -BASE_DENOM="utoken" -EXTENDED_DENOM="atoken" -GENESIS=~/.yourchain/config/genesis.json - -# Initialize -$BINARY init mynode --chain-id $CHAIN_ID - -# 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 - -# Set bank metadata (6 decimals) -jq ".app_state.bank.denom_metadata=[{ - \"description\": \"The native staking token\", - \"denom_units\": [ - {\"denom\": \"$BASE_DENOM\", \"exponent\": 0}, - {\"denom\": \"token\", \"exponent\": 6} - ], - \"base\": \"$BASE_DENOM\", - \"display\": \"token\", - \"name\": \"Token\", - \"symbol\": \"TKN\" -}]" $GENESIS > tmp && mv tmp $GENESIS - -# Set extended denom options (REQUIRED for 6 decimals) -jq ".app_state.evm.params.extended_denom_options={ - \"extended_denom\": \"$EXTENDED_DENOM\" -}" $GENESIS > tmp && mv tmp $GENESIS - -# Enable precompiles -jq '.app_state.evm.params.active_static_precompiles=[ - "0x0000000000000000000000000000000000000100", - "0x0000000000000000000000000000000000000400", - "0x0000000000000000000000000000000000000800" -]' $GENESIS > tmp && mv tmp $GENESIS - -echo "Genesis configuration complete!" -echo "IMPORTANT: Ensure PreciseBank module is integrated in app.go" -``` - - - - - -```go -// In app.go - REQUIRED for 6-decimal chains - -import ( - precisebankkeeper "github.com/cosmos/evm/x/precisebank/keeper" - precisebanktypes "github.com/cosmos/evm/x/precisebank/types" - precisebank "github.com/cosmos/evm/x/precisebank" -) - -// Add to store keys -keys := storetypes.NewKVStoreKeys( - // ... other keys - precisebanktypes.StoreKey, -) - -// Initialize PreciseBankKeeper -app.PreciseBankKeeper = precisebankkeeper.NewKeeper( - appCodec, - keys[precisebanktypes.StoreKey], - app.BankKeeper, - app.AccountKeeper, -) - -// CRITICAL: Use PreciseBankKeeper in EVMKeeper -app.EVMKeeper = evmkeeper.NewKeeper( - appCodec, - keys[evmtypes.StoreKey], - app.GetSubspace(evmtypes.ModuleName), - app.AccountKeeper, - app.PreciseBankKeeper, // Not BankKeeper! - app.StakingKeeper, - app.FeeMarketKeeper, - authtypes.NewModuleAddress(govtypes.ModuleName).String(), -) - -// Add to module manager -app.ModuleManager = module.NewManager( - // ... other modules - precisebank.NewAppModule(app.PreciseBankKeeper, app.AccountKeeper), - // ... -) - -// Add to genesis order (after bank, before evm) -genesisModuleOrder := []string{ - // ... - banktypes.ModuleName, - precisebanktypes.ModuleName, - evmtypes.ModuleName, - // ... -} -``` - - - - - ---- - -### 8.3. Using local_node.sh as Template - -The `local_node.sh` script in the cosmos/evm repository demonstrates complete chain configuration for local development. - - - - - -The script performs all configuration steps automatically: - -**Genesis Modifications**: -- Sets development chain ID -- Configures `atest` denomination (18 decimals) -- Sets up bank metadata -- Enables all static precompiles -- Creates genesis validator -- Funds test accounts - -**app.toml Configuration**: -- Sets EVM chain ID to 262144 -- Enables JSON-RPC on 0.0.0.0:8545 -- Enables all APIs including debug -- Allows unprotected transactions (dev only) -- Enables transaction indexer - - - - - -```bash -# Fresh start (overwrites previous database) -./local_node.sh -y - -# Resume from previous state -./local_node.sh -n - -# Skip binary rebuild -./local_node.sh --no-install - -# Build with debug symbols -./local_node.sh --remote-debugging -``` - - - - - -To adapt for your chain: - -1. **Copy the script**: `cp local_node.sh my_chain_setup.sh` -2. **Update chain name**: Change `evmd` to your binary -3. **Modify genesis values**: Update denom, chain ID, precompiles -4. **Adjust app.toml settings**: Configure for your use case -5. **Add custom logic**: Include chain-specific setup - - - - - - -**Development vs Production**: - -The `local_node.sh` configuration is optimized for local development. For production: - -- Disable debug APIs in JSON-RPC -- Require transaction signatures (`allow-unprotected-txs = false`) -- Set appropriate `min-tip` value -- Use secure key management (not test keys) -- Configure proper peer discovery -- Enable appropriate monitoring - - - - - - ---- - -## 9. Quick Reference - -### Commands Summary - -```bash -# Build -make build - -# Initialize -yourchain init --chain-id - -# Genesis accounts -yourchain genesis add-genesis-account
- -# Create validator gentx -yourchain genesis gentx --chain-id - -# Collect gentxs -yourchain genesis collect-gentxs - -# Validate genesis -yourchain genesis validate - -# Hash genesis -jq -S -c . genesis.json | shasum -a 256 - -# Show node ID -yourchain comet show-node-id - -# Start node -yourchain start - -# Check status -curl localhost:26657/status - -# Check block height (Cosmos) -curl localhost:26657/status | jq '.result.sync_info.latest_block_height' - -# Check block height (Ethereum) -curl http://localhost:8545 -X POST -H "Content-Type: application/json" \ - -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' -``` - ---- - -### File Locations - -| File | Location | -|------|----------| -| Genesis | `~/.yourchain/config/genesis.json` | -| App Config | `~/.yourchain/config/app.toml` | -| CometBFT Config | `~/.yourchain/config/config.toml` | -| Client Config | `~/.yourchain/config/client.toml` | -| Gentx Directory | `~/.yourchain/config/gentx/` | -| Bech32 Prefix | `config/config.go:62` | -| BIP44 Coin Type | `crypto/hd/hdpath.go:9` | -| EVM Chain ID | `config/config.go:78` | -| Default Denoms | `x/vm/types/params.go:21-25` | - ---- - -### Default Values Reference - -| Parameter | Default | Source | -|-----------|---------|--------| -| **Pre-Genesis** | | | -| Bech32 Prefix | `cosmos` | config/config.go:62 | -| BIP44 Coin Type | `60` | crypto/hd/hdpath.go:9 | -| EVM Chain ID | `262144` | config/config.go:78 | -| **EVM Module** | | | -| Base Fee | `1000000000` (1 gwei) | x/feemarket/types/params.go:13 | -| History Serve Window | `8192` blocks | x/vm/types/params.go:50 | -| **Mempool** | | | -| Price Limit | `1` wei | server/config/config.go:179 | -| Price Bump | `10%` | server/config/config.go:180 | -| Account Slots | `16` | server/config/config.go:181 | -| Global Slots | `5120` | server/config/config.go:182 | -| Account Queue | `64` | server/config/config.go:183 | -| Global Queue | `1024` | server/config/config.go:184 | -| Lifetime | `3h0m0s` | server/config/config.go:185 | -| **Staking** | | | -| Unbonding Time | `1814400s` (21 days) | Staking default | -| Max Validators | `100` | Staking default | -| **Governance** | | | -| Voting Period | `172800s` (2 days) | Gov default | -| Quorum | `0.334` (33.4%) | Gov default | - ---- - -### Navigation Index - -**Planning**: [Section 2](#2-planning-your-configuration) - -**Pre-Genesis Setup** (Must do before init): -- [Binary Name](#31-fork-repository-and-rename-binary) -- [Bech32 Prefix](#32-set-bech32-address-prefix) -- [BIP44 Coin Type](#33-set-bip44-coin-type) -- [EVM Chain ID](#34-set-evm-chain-id) -- [Token Decimals](#35-choose-token-decimal-precision) -- [Default Denominations](#36-configure-default-token-denomination-in-source-code) - -**Genesis Configuration**: -- [Genesis Time](#41-set-genesis-time) -- [Bank Metadata](#42-configure-bank-metadata) -- [EVM Denom](#43-set-evm-denom) -- [Extended Denom](#44-configure-extended-denom-options) -- [ERC20 Token Pairs](#45-configure-erc20-token-pairs) -- [Precompiles](#46-enable-required-precompiles) -- [Predeployed Contracts](#47-configure-predeployed-contracts) -- [Access Control](#48-configure-evm-access-control) -- [Fee Market](#49-configure-eip-1559-fee-market) -- [Staking](#410-configure-staking-parameters) -- [Mint](#411-configure-mint-parameters) -- [Governance](#412-configure-governance-parameters) -- [Genesis Accounts](#413-add-genesis-accounts-with-initial-balances) -- [Validator Gentxs](#414-collect-validator-genesis-transactions) -- [Validation](#415-validate-final-genesis-file) - -**Runtime Configuration**: -- [JSON-RPC](#51-configure-json-rpc) -- [EVM Settings](#52-configure-evm-settings) -- [Mempool](#53-configure-evm-mempool) -- [Gas Prices](#54-set-minimum-gas-prices) -- [Network Peers](#55-configure-network-peers) -- [Client Chain ID](#56-set-client-chain-id) - -**Network Launch**: -- [Distribute Genesis](#61-distribute-final-genesis-file) -- [Verify Hash](#62-verify-genesis-hash) -- [Exchange Peers](#63-exchange-peer-information) -- [Start Nodes](#64-start-validator-nodes) - -**Post-Launch**: -- [Monitoring](#71-monitoring--alerting) -- [Governance](#72-governance-parameter-updates) -- [Upgrades](#73-software-upgrades) - ---- - -**Generated from**: [cosmos/evm](https://github.com/cosmos/evm) codebase -**Version**: v0.5.0-rc.1 (Cosmos SDK v0.53.4, IBC-Go v10, CometBFT v0.38.18) \ No newline at end of file diff --git a/docs/evm/next/documentation/getting-started/build-a-chain/chain-configuration-reference.mdx b/docs/evm/next/documentation/getting-started/build-a-chain/chain-configuration-reference.mdx index 625c489c..4f62ed18 100644 --- a/docs/evm/next/documentation/getting-started/build-a-chain/chain-configuration-reference.mdx +++ b/docs/evm/next/documentation/getting-started/build-a-chain/chain-configuration-reference.mdx @@ -5,16 +5,13 @@ description: "Comprehensive reference for configuring your Cosmos EVM chain. Com This reference provides complete inline documentation for every configuration parameter when building a Cosmos EVM chain. Each section includes code examples, file locations, and detailed explanations organized by configuration area. - -This guide focuses on comprehensive parameter documentation. For a step-by-step workflow, see the [Building Your Chain Guide](/docs/evm/next/documentation/getting-started/build-a-chain/building-your-chain-guide). - ## Configuration Overview When building your custom chain, you'll configure parameters across multiple areas: | Configuration Area | When to Configure | Changeable After Genesis | -|-------------------|-------------------|-------------------------| +|-|-|-| | **Binary Name** | Before any setup | No (requires new binary) | | **Bech32 Prefix** | Before `init` | No (hard fork required) | | **BIP44 Coin Type** | Before `init` | No (breaks wallets) | @@ -26,7 +23,7 @@ When building your custom chain, you'll configure parameters across multiple are | **Fee Market** | Genesis | Yes (via governance) | | **Runtime Config** | Before start | Yes (node-level) | ---- + ## Binary Name @@ -82,7 +79,7 @@ make build After renaming, all CLI commands use your new binary name: `yourchain start`, `yourchain init`, etc. ---- + ## Bech32 Address Prefix @@ -129,7 +126,7 @@ const ( **Source**: [config/config.go:60-74](https://github.com/cosmos/evm/blob/main/config/config.go#L60-L74) ---- + ## BIP44 Coin Type @@ -194,7 +191,7 @@ var ( **Source**: [crypto/hd/hdpath.go:7-13](https://github.com/cosmos/evm/blob/main/crypto/hd/hdpath.go#L7-L13) ---- + ## EVM Chain ID @@ -276,7 +273,7 @@ grep 'evm-chain-id' ~/.yourchain/config/app.toml **Source**: [config/config.go:77-78](https://github.com/cosmos/evm/blob/main/config/config.go#L77-L78) ---- + ## Token Decimal Precision @@ -370,7 +367,7 @@ For chains using other decimal precisions (e.g., 8 decimals for Bitcoin compatib - [PreciseBank Module Reference](/docs/evm/next/documentation/cosmos-sdk/modules/precisebank) - Integration guide ---- + ## Bank Metadata @@ -449,7 +446,7 @@ jq '.app_state.bank.denom_metadata=[{ ### Field Descriptions | Field | Description | Example | -|-------|-------------|---------| +|-|-|| | `base` | Smallest unit stored on-chain | `atoken`, `utoken` | | `display` | Human-readable unit | `token` | | `exponent` | Decimal places | `18` or `6` | @@ -469,7 +466,7 @@ jq '.app_state.bank.denom_metadata=[{ Mismatched denominations will cause genesis validation to fail. ---- + ## EVM Denom @@ -506,7 +503,7 @@ jq '.app_state.evm.params.evm_denom = "atoken"' genesis.json > tmp && mv tmp gen **Source**: [x/vm/types/params.go:21](https://github.com/cosmos/evm/blob/main/x/vm/types/params.go#L21) ---- + ## Extended Denom Options @@ -555,7 +552,7 @@ jq '.app_state.evm.params.extended_denom_options = { **Source**: [x/vm/types/params.go:76](https://github.com/cosmos/evm/blob/main/x/vm/types/params.go#L76) ---- + ## ERC20 Token Pairs @@ -603,7 +600,7 @@ jq '.app_state.erc20.token_pairs = [{ ### Field Descriptions | Field | Description | Value | -|-------|-------------|-------| +|-|-|-| | `erc20_address` | ERC20 contract address | Special address for native token | | `denom` | Cosmos base denomination | Must match your token's base denom | | `enabled` | Whether the pair is active | `true` | @@ -611,7 +608,7 @@ jq '.app_state.erc20.token_pairs = [{ **Result**: Your native token becomes accessible as an ERC20 token from Solidity contracts. ---- + ## Native Precompile Address @@ -640,7 +637,7 @@ jq '.app_state.erc20.native_precompiles = ["0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeee **Must Match**: The address must be identical to the `erc20_address` in `token_pairs` configuration. ---- + ## ERC20 Registration Permissions @@ -678,7 +675,7 @@ jq '.app_state.erc20.params.permissionless_registration = false' genesis.json > **Source**: [x/erc20/types/params.go:27](https://github.com/cosmos/evm/blob/main/x/erc20/types/params.go#L27) ---- + ## Active Precompiles @@ -698,7 +695,7 @@ For complete precompile documentation including Solidity interfaces and usage ex ### Available Precompiles | Address | Name | Purpose | Typical Use Case | -|---------|------|---------|------------------| +||||| | `0x0100` | **P256** | Cryptographic operations for Web3 auth | Passkey authentication, secure signing | | `0x0400` | **Bech32** | Cosmos ↔ Ethereum address conversion | Cross-chain operations, IBC | | `0x0800` | **Staking** | Validator staking operations | Liquid staking protocols, auto-compounding | @@ -771,7 +768,7 @@ yourchain tx gov submit-proposal param-change proposal.json \ **Source**: [x/vm/types/precompiles.go:22-32](https://github.com/cosmos/evm/blob/main/x/vm/types/precompiles.go#L22-L32) ---- + ## Predeployed Contracts @@ -814,7 +811,7 @@ No manual configuration needed unless you want to disable specific contracts. jq '.app_state.evm.preinstalls' ~/.yourchain/config/genesis.json ``` ---- + ## EVM Access Control @@ -827,7 +824,7 @@ jq '.app_state.evm.preinstalls' ~/.yourchain/config/genesis.json ### Access Control Types | Type | Value | Behavior | access_control_list Usage | -|------|-------|----------|--------------------------| +||-|-|--| | **Permissionless** | `0` | Anyone can perform action | Ignored (can be empty) | | **Restricted** | `1` | Block addresses in list | Blocklist | | **Permissioned** | `2` | Only addresses in list | Allowlist | @@ -931,7 +928,7 @@ Access control can be changed through governance proposals. **Source**: [x/vm/types/params.go:160-165](https://github.com/cosmos/evm/blob/main/x/vm/types/params.go#L160-L165) ---- + ## Extra EIPs @@ -978,7 +975,7 @@ EIPs must be activatable in the EVM implementation. Invalid EIP numbers will cau **Source**: [x/vm/types/params.go:33](https://github.com/cosmos/evm/blob/main/x/vm/types/params.go#L33) ---- + ## History Serve Window @@ -999,7 +996,7 @@ jq '.app_state.evm.params.history_serve_window = 8192' genesis.json > tmp && mv ### Values and Trade-offs | Value | Retention Period | Disk Usage | Query Capability | -|-------|-----------------|------------|------------------| +|-|--||| | `0` | Unlimited (forever) | Grows continuously | Full historical queries | | `8192` | ~18 hours (at 8s blocks) | Moderate | Recent state only | | `86400` | ~8 days | Higher | Week of history | @@ -1015,7 +1012,7 @@ jq '.app_state.evm.params.history_serve_window = 8192' genesis.json > tmp && mv **Source**: [x/vm/types/params.go:50](https://github.com/cosmos/evm/blob/main/x/vm/types/params.go#L50) ---- + ## EIP-1559 Fee Market @@ -1136,7 +1133,7 @@ Most Ethereum-compatible chains should keep EIP-1559 enabled (default) for bette **Source**: [x/feemarket/types/params.go:13-21](https://github.com/cosmos/evm/blob/main/x/feemarket/types/params.go#L13-L21) ---- + ## Minimum Gas Prices @@ -1174,7 +1171,7 @@ minimum-gas-prices = "1000000000atoken" **Recommendation**: Set to at least the expected minimum to prevent mempool spam. For production, use a value that covers the cost of transaction processing. ---- + ## EVM Mempool Settings @@ -1300,7 +1297,7 @@ account-slots = 4 **Source**: [server/config/config.go:158-187](https://github.com/cosmos/evm/blob/v0.5.0-rc.1/server/config/config.go#L158-L187) ---- + ## Staking Parameters @@ -1335,7 +1332,7 @@ jq '.app_state.staking.params.bond_denom = "atoken"' genesis.json > tmp && mv tm ### Parameters | Parameter | Default | Description | -|-----------|---------|-------------| +|--||-| | `bond_denom` | - | Must match your base denomination | | `unbonding_time` | `"1814400s"` | 21 days - time to wait for unstaking | | `max_validators` | `100` | Maximum active validators | @@ -1346,7 +1343,7 @@ jq '.app_state.staking.params.bond_denom = "atoken"' genesis.json > tmp && mv tm **CRITICAL**: `bond_denom` must match your bank metadata base denomination and evm_denom. ---- + ## Governance Parameters @@ -1392,7 +1389,7 @@ jq '.app_state.gov.params.voting_period = "30s"' genesis.json > tmp && mv tmp ge ### Parameters | Parameter | Default | Description | -|-----------|---------|-------------| +|--||-| | `min_deposit` | - | Minimum deposit to submit proposal | | `max_deposit_period` | `"172800s"` | 2 days to reach min deposit | | `voting_period` | `"172800s"` | 2 days voting (use `"30s"` for testing) | @@ -1404,7 +1401,7 @@ jq '.app_state.gov.params.voting_period = "30s"' genesis.json > tmp && mv tmp ge For testnets, set `voting_period` to `"30s"` for faster testing. For mainnets, use `"172800s"` (2 days) or longer. ---- + ## Mint Parameters @@ -1440,7 +1437,7 @@ jq '.app_state.mint.params.mint_denom = "atoken"' genesis.json > tmp && mv tmp g ### Parameters | Parameter | Default | Description | -|-----------|---------|-------------| +|--||-| | `mint_denom` | - | Must match your base denomination | | `inflation_max` | `0.20` | Maximum annual inflation (20%) | | `inflation_min` | `0.07` | Minimum annual inflation (7%) | @@ -1450,7 +1447,7 @@ jq '.app_state.mint.params.mint_denom = "atoken"' genesis.json > tmp && mv tmp g **How It Works**: Inflation adjusts automatically based on bonded ratio to incentivize staking toward the goal. ---- + ## Distribution Parameters @@ -1478,13 +1475,13 @@ jq '.app_state.mint.params.mint_denom = "atoken"' genesis.json > tmp && mv tmp g ### Parameters | Parameter | Default | Description | -|-----------|---------|-------------| +|--||-| | `community_tax` | `0.02` | 2% of rewards to community pool | | `base_proposer_reward` | `0.01` | 1% base reward for block proposer | | `bonus_proposer_reward` | `0.04` | 4% bonus reward for block proposer | | `withdraw_addr_enabled` | `true` | Allow setting custom withdraw address | ---- + ## JSON-RPC Configuration @@ -1554,7 +1551,7 @@ batch-response-max-size = 0 ### API Namespaces | Namespace | Description | Recommended For | -|-----------|-------------|-----------------| +|--|-|--| | `eth` | Standard Ethereum RPC | All RPC nodes (required) | | `net` | Network information | All RPC nodes | | `web3` | Web3 client version | All RPC nodes | @@ -1575,7 +1572,7 @@ batch-response-max-size = 0 - Enable all APIs including `debug` - Set `allow-unprotected-txs = true` for testing convenience ---- + ## EVM Runtime Settings @@ -1647,7 +1644,7 @@ To change the EVM chain ID, you must modify the code constant in `config/config. **New in v0.5.0**: Go-ethereum metrics are now emitted on a separate server. This separates EVM-specific metrics from Cosmos SDK metrics for better observability. ---- + ## TLS Configuration @@ -1714,7 +1711,7 @@ curl https://localhost:8545 \ **Production Recommendation**: Use a reverse proxy (nginx, Caddy) for TLS instead of direct TLS in the node. This provides better flexibility and security. ---- + ## Network Peers @@ -1756,7 +1753,7 @@ persistent_peers = "7c90e16cca334eb7259754f964918d879ca54996@192.168.1.100:26656 curl localhost:26657/net_info | jq '.result.peers' ``` ---- + ## Chain Identity @@ -1814,7 +1811,7 @@ jq '.genesis_time = "2024-12-01T00:00:00Z"' genesis.json > tmp && mv tmp genesis 3. Ensure all validators use identical genesis file 4. Validators start nodes and wait for genesis time ---- + ## Genesis Accounts @@ -1872,7 +1869,7 @@ yourchain genesis bulk-add-genesis-account accounts.json jq '.app_state.bank.balances' ~/.yourchain/config/genesis.json ``` ---- + ## Validator Genesis Transactions @@ -1926,7 +1923,7 @@ jq '.app_state.genutil.gen_txs' ~/.yourchain/config/genesis.json **Result**: Genesis file now contains all validator self-delegations. ---- + ## Genesis Validation @@ -2003,7 +2000,7 @@ jq '.app_state.bank.balances | map(.coins[0].amount | tonumber) | add' genesis.j jq '.app_state.genutil.gen_txs | length' genesis.json ``` ---- + ## Genesis Distribution @@ -2054,7 +2051,7 @@ wget https://github.com/yourorg/yourchain/releases/download/v1.0.0/genesis.json **Security**: Use secure, verified channels to prevent tampering. Always verify genesis hash after distribution. ---- + ## Genesis Hash Verification @@ -2101,7 +2098,7 @@ jq -S -c . ~/.yourchain/config/genesis.json | shasum -a 256 **CRITICAL**: Even one character difference means different genesis state. All validators must have IDENTICAL files. Do not proceed unless all hashes match. ---- + ## Coordinated Launch @@ -2252,7 +2249,7 @@ curl http://localhost:8545 \ ---- + ## Monitoring and Alerting @@ -2315,7 +2312,7 @@ go install description: "Validator has missed {{ $value }} blocks" ``` ---- + ## Governance Parameter Updates @@ -2381,7 +2378,7 @@ yourchain tx gov vote 1 yes \ **Vote Options**: `yes`, `no`, `abstain`, `no_with_veto` ---- + ## Software Upgrades @@ -2489,7 +2486,7 @@ yourchain start - [Migration Guides](/docs/evm/next/documentation/migrations/migration-v0.4-to-v0.5) ---- + ## Configuration Workflow @@ -2618,7 +2615,7 @@ For production: ---- + ## Complete Examples @@ -2814,7 +2811,7 @@ genesisModuleOrder := []string{ ``` ---- + ## Quick Reference @@ -2862,7 +2859,7 @@ curl http://localhost:8545 -X POST -H "Content-Type: application/json" \ ### File Locations | File | Location | -|------|----------| +||-| | Genesis | `~/.yourchain/config/genesis.json` | | App Config | `~/.yourchain/config/app.toml` | | CometBFT Config | `~/.yourchain/config/config.toml` | @@ -2874,7 +2871,7 @@ curl http://localhost:8545 -X POST -H "Content-Type: application/json" \ ### Default Values | Parameter | Default | Source | -|-----------|---------|--------| +|--||--| | Bech32 Prefix | `cosmos` | config/config.go:62 | | BIP44 Coin Type | `60` | crypto/hd/hdpath.go:9 | | EVM Chain ID | `262144` | config/config.go:78 | @@ -2892,7 +2889,7 @@ curl http://localhost:8545 -X POST -H "Content-Type: application/json" \ | Unbonding Time | `1814400s` (21 days) | Staking params default | | Voting Period | `172800s` (2 days) | Gov params default | ---- + **Generated from**: [cosmos/evm](https://github.com/cosmos/evm) codebase **Version**: v0.5.0-rc.1 (Cosmos SDK v0.53.4, IBC-Go v10, CometBFT v0.38.18) diff --git a/docs/evm/next/documentation/getting-started/build-a-chain/chain-customization-checklist.mdx b/docs/evm/next/documentation/getting-started/build-a-chain/chain-customization-checklist.mdx index 1dd9d054..9c7f7dde 100644 --- a/docs/evm/next/documentation/getting-started/build-a-chain/chain-customization-checklist.mdx +++ b/docs/evm/next/documentation/getting-started/build-a-chain/chain-customization-checklist.mdx @@ -3,8 +3,6 @@ title: "Guided Setup: Config to Launch" description: "Configure your chain step by step - complete with code references, examples and explanations." --- -This checklist provides **complete inline documentation** for every step of building and launching your Cosmos EVM chain. Each item includes code examples, file locations, and detailed explanations without requiring navigation to other pages. - ## Pre-Genesis Setup @@ -607,7 +605,7 @@ jq '.app_state.evm.params.extended_denom_options = { **Available Precompiles**: | Address | Name | Purpose | -|---------|------|---------| +|||| | `0x0100` | P256 | Cryptographic operations for Web3 auth | | `0x0400` | Bech32 | Cosmos ↔ Ethereum address conversion | | `0x0800` | Staking | Validator staking operations | @@ -1991,7 +1989,7 @@ persistent_peers = "7c90e16c@192.168.1.100:26656,abc123de@192.168.1.101:26656,de **Coordination Sheet** (example): | Validator | Node ID | IP Address | P2P Connection String | -|-----------|---------|------------|----------------------| +|--|||-| | Validator 1 | 7c90e16c... | 192.168.1.100 | 7c90e16c@192.168.1.100:26656 | | Validator 2 | abc123de... | 192.168.1.101 | abc123de@192.168.1.101:26656 | | Validator 3 | def456ab... | 192.168.1.102 | def456ab@192.168.1.102:26656 | @@ -2124,7 +2122,7 @@ curl http://localhost:8545 \ ---- + **Your chain is now running!** Validators can begin processing transactions and the network is operational. @@ -2171,7 +2169,7 @@ curl http://localhost:8545 -X POST -H "Content-Type: application/json" \ ### File Locations | File | Location | -|------|----------| +||-| | Genesis | `~/.yourchain/config/genesis.json` | | App Config | `~/.yourchain/config/app.toml` | | CometBFT Config | `~/.yourchain/config/config.toml` | @@ -2182,7 +2180,7 @@ curl http://localhost:8545 -X POST -H "Content-Type: application/json" \ ### Default Values | Parameter | Default | Source | -|-----------|---------|--------| +|--||--| | Bech32 Prefix | `cosmos` | config/config.go:62 | | BIP44 Coin Type | `60` | crypto/hd/hdpath.go:9 | | EVM Chain ID | `262144` | config/config.go:78 | @@ -2190,7 +2188,7 @@ curl http://localhost:8545 -X POST -H "Content-Type: application/json" \ | Mempool Price Limit | `1` wei | mempool/txpool/legacypool/legacypool.go:161 | | History Serve Window | `8192` blocks | x/vm/types/params.go:50 | ---- + **Generated from**: [cosmos/evm](https://github.com/cosmos/evm) codebase **Version**: Cosmos SDK v0.53.4, IBC-Go v10, CometBFT v0.38.18 diff --git a/docs/evm/next/documentation/getting-started/build-a-chain/configuration-parameters.mdx b/docs/evm/next/documentation/getting-started/build-a-chain/configuration-parameters.mdx index 00498d49..9c8071bc 100644 --- a/docs/evm/next/documentation/getting-started/build-a-chain/configuration-parameters.mdx +++ b/docs/evm/next/documentation/getting-started/build-a-chain/configuration-parameters.mdx @@ -14,7 +14,7 @@ This guide focuses on the practical configuration steps. For comprehensive param The reference implementation (`evmd`) comes with these defaults: | Configuration | Default Value | Customizable | -|---------------|---------------|--------------| +|||--| | **Binary Name** | `evmd` | ✓ Yes (rename) | | **Cosmos Chain ID** | User-defined (string) | ✓ Yes (genesis) | | **EVM Chain ID** | `262144` | ✓ Yes (app.toml) | @@ -25,7 +25,7 @@ The reference implementation (`evmd`) comes with these defaults: Let's configure each of these for your custom chain. ---- + ## 1. Binary Name @@ -84,7 +84,7 @@ go build -o yourchain ./yourchain/cmd/yourchain After renaming, your binary will be `yourchain` instead of `evmd`. All CLI commands will use this new name (e.g., `yourchain start` instead of `evmd start`). ---- + ## 2. Cosmos Chain ID @@ -111,7 +111,7 @@ yourchain init mynode --chain-id mychain-1 The Cosmos chain ID can be changed during coordinated chain upgrades. The version number (e.g., `-1`, `-2`) is typically incremented when consensus-breaking changes occur. ---- + ## 3. EVM Chain ID @@ -165,7 +165,7 @@ yourchain start --evm.chain-id 262144 ---- + ## 4. EIP Integration @@ -222,7 +222,7 @@ Only add EIPs if you have a specific technical requirement for functionality not ---- + ## 5. Token Pairs (ERC20 Module) @@ -271,7 +271,7 @@ The evmd example uses a special ERC20 address for the native token: **Default Setup**: Most chains start with just the native token pair. Additional pairs can be registered after launch through governance or permissionless registration (if enabled). ---- + ## 6. Token Denomination @@ -413,7 +413,7 @@ Requires precisebank module with custom conversion factor. ### Common Denomination Prefixes | Prefix | Decimals | Example | Used For | -|--------|----------|---------|----------| +|--|-||-| | `a` (atto) | 18 | `atoken` | **EVM-compatible chains (recommended)** | | `u` (micro) | 6 | `uatom`, `ustake` | Traditional Cosmos chains | | Base | 0-8 | `sats` | Bitcoin-style | @@ -463,7 +463,7 @@ jq '.app_state["bank"]["denom_metadata"]=[{ - `bank.denom_metadata[0].base` ---- + ## 7. EVM Permissioning @@ -567,7 +567,7 @@ EVM permissions are set in genesis under `vm.params.access_control`: ### Access Control Types | Type | Value | Behavior | access_control_list | -|------|-------|----------|---------------------| +||-|-|| | **Permissionless** | `0` | Anyone can perform action | Ignored | | **Restricted** | `1` | Block addresses in list | Blocklist | | **Permissioned** | `2` | Only addresses in list | Allowlist | @@ -587,7 +587,7 @@ yourchain tx gov submit-proposal param-change proposal.json \ --chain-id yourchain-1 ``` ---- + ## 8. Fee Market & Gas Configuration @@ -660,7 +660,7 @@ The fee market module implements EIP-1559 dynamic pricing: Most Ethereum-compatible chains should keep EIP-1559 enabled (default) for better user experience and fee predictability. ---- + ## 9. Enabled Precompiles @@ -675,7 +675,7 @@ For complete precompile documentation including Solidity interfaces and usage ex | Address | Name | Description | Typical Use Case | -|---------|------|-------------|------------------| +|||-|| | `0x0100` | **P256** | P256 cryptographic operations | Web3 auth, secure signing | | `0x0400` | **Bech32** | Cosmos ↔ Ethereum address conversion | Cross-chain operations | | `0x0800` | **Staking** | Validator staking operations | Liquid staking, auto-compounding | @@ -771,7 +771,7 @@ yourchain tx gov submit-proposal param-change proposal.json \ --from validator ``` ---- + ## Configuration Workflow @@ -856,7 +856,7 @@ For production: ---- + ## Configuration Examples @@ -945,7 +945,7 @@ The script serves as a complete example of the configuration workflow described - Configure proper peer discovery and networking ---- + ### Complete 18-Decimal Chain @@ -1100,7 +1100,7 @@ genesisModuleOrder := []string{ ``` ---- + ## Next Steps @@ -1158,6 +1158,6 @@ Understanding decimal bridging between Cosmos and EVM ---- + For additional support, visit the [Cosmos EVM GitHub repository](https://github.com/cosmos/evm) or join the Cosmos developer community. diff --git a/docs/evm/next/documentation/getting-started/build-a-chain/configuration-reference.mdx b/docs/evm/next/documentation/getting-started/build-a-chain/configuration-reference.mdx index 4384e35f..e0e6c6d5 100644 --- a/docs/evm/next/documentation/getting-started/build-a-chain/configuration-reference.mdx +++ b/docs/evm/next/documentation/getting-started/build-a-chain/configuration-reference.mdx @@ -11,7 +11,7 @@ This reference provides quick access to common commands, configuration examples, - [Runtime Configuration & Launch](/docs/evm/next/documentation/getting-started/build-a-chain/runtime-and-launch) - Network launch procedures ---- + ## Commands Summary @@ -33,7 +33,7 @@ yourchain comet show-validator ``` ---- + ### Genesis Account Management @@ -54,7 +54,7 @@ yourchain genesis add-genesis-account faucet 10000000000000000000000atoken # ``` ---- + ### Validator Genesis Transactions @@ -78,7 +78,7 @@ yourchain genesis validate ``` ---- + ### Genesis File Manipulation @@ -100,7 +100,7 @@ yourchain genesis validate ``` ---- + ### Genesis Hash @@ -117,7 +117,7 @@ cat genesis_hash.txt ``` ---- + ### Client Configuration @@ -134,7 +134,7 @@ yourchain config get client --home ~/.yourchain ``` ---- + ### Node Operations @@ -160,7 +160,7 @@ curl localhost:8545 \ ``` ---- + ### Validator Operations @@ -187,14 +187,14 @@ 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 | @@ -203,12 +203,12 @@ yourchain query slashing signing-info $(yourchain comet show-validator) | **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 | @@ -216,14 +216,14 @@ yourchain query slashing signing-info $(yourchain comet show-validator) | **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` | @@ -231,12 +231,12 @@ yourchain query slashing signing-info $(yourchain comet show-validator) | 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` | @@ -250,12 +250,12 @@ yourchain query slashing signing-info $(yourchain comet show-validator) | 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]` | @@ -265,7 +265,7 @@ yourchain query slashing signing-info $(yourchain comet show-validator) | Mempool Price Limit | `1` wei | `app.toml: [evm.mempool]` | | Global Slots | `5120` | `app.toml: [evm.mempool]` | ---- + ## Configuration Examples @@ -368,7 +368,7 @@ prometheus_listen_addr = ":26660" ---- + ### Complete 6-Decimal Chain Setup @@ -456,7 +456,7 @@ app.EVMKeeper = evmkeeper.NewKeeper( ---- + ### Local Development Setup @@ -581,7 +581,7 @@ sed -i 's/evmd/yourchain/g' my_chain_setup.sh **Source**: [local_node.sh](https://github.com/cosmos/evm/blob/main/local_node.sh) ---- + ## Additional Resources @@ -613,7 +613,7 @@ Complete build guide ---- + ### Concept Documentation @@ -631,7 +631,7 @@ Decimal bridging ---- + ### External Resources @@ -640,7 +640,7 @@ Decimal bridging - [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 @@ -654,6 +654,6 @@ Decimal bridging - [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 adf9f46e..ed40300e 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 @@ -51,7 +51,7 @@ Configured in `genesis.json` after initialization: - [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 ---- +
@@ -73,7 +73,7 @@ Set up node-level settings and coordinate network deployment. - [Post-Launch Operations](/docs/evm/next/documentation/getting-started/build-a-chain/runtime-and-launch#post-launch-operations) - Monitoring, upgrades, and maintenance ---- + ## Additional Resources @@ -85,7 +85,7 @@ Quick reference for commands, defaults, and examples Command cheatsheet with complete setup examples for different configurations. ---- + ## Advanced Configuration @@ -103,7 +103,7 @@ Deploy standard contracts at genesis for Create2, Multicall3, Permit2, and Safe
---- + ## Local Development Testing 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 index a274bb1f..0f3725ac 100644 --- 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 @@ -305,7 +305,7 @@ 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...` | @@ -404,7 +404,7 @@ make build | Coin Type | Chain | Purpose | -|---|---|---| +|||| | `60` | Ethereum | **EVM chains (recommended)** | | `118` | Cosmos Hub | Traditional Cosmos chains | | `330` | Terra | Terra ecosystem | @@ -672,7 +672,7 @@ app.ModuleManager = module.NewManager( | 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 | @@ -1261,7 +1261,7 @@ jq '.app_state.evm.params.extra_eips = []' \ | Address | Name | Purpose | -|---------|------|---------| +|||| | `0x0100` | **P256** | Cryptographic operations for Web3 auth | | `0x0400` | **Bech32** | Cosmos ↔ Ethereum address conversion | | `0x0800` | **Staking** | Validator staking operations | @@ -1589,7 +1589,7 @@ jq '.app_state.evm.params.access_control.create = { | 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 | 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 index d9c3f56c..fbc5e2dd 100644 --- 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 @@ -24,7 +24,7 @@ After completing genesis configuration, you need to: Ensure all validators have the exact same genesis file before launching. Even small differences will cause consensus failure. ---- + ## Runtime Configuration @@ -33,12 +33,12 @@ Runtime configuration is set in config files located at `~/.yourchain/config/`. ### 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 @@ -95,7 +95,7 @@ minimum-gas-prices = "0atoken" # Accept all (not for production) ---- + ### JSON-RPC Configuration @@ -156,7 +156,7 @@ enable-indexer = false **Available Namespaces:** | Namespace | Purpose | Production Use | -|-----------|---------|----------------| +|--||-| | `eth` | Standard Ethereum RPC | ✅ Required | | `net` | Network information | ✅ Recommended | | `web3` | Web3 client version | ✅ Recommended | @@ -210,7 +210,7 @@ block-range-cap = 10000 **Default Port**: `8545` (HTTP), `8546` (WebSocket) ---- + ### EVM Configuration @@ -287,7 +287,7 @@ min-tip = 0 # No minimum ---- + ### EVM Mempool Configuration @@ -398,7 +398,7 @@ lifetime = "30m0s" # 30 minute lifetime **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 @@ -445,7 +445,7 @@ yourchain comet show-node-id 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` | @@ -462,7 +462,7 @@ curl localhost:26657/net_info | jq '.result.peers' **Default P2P Port**: `26656` ---- + ### Consensus Timeouts @@ -525,7 +525,7 @@ timeout_commit = "1s" ---- + ### Prometheus Metrics @@ -549,7 +549,7 @@ curl http://localhost:26660/metrics **Recommended**: Enable for production to monitor chain health. ---- + ## client.toml Configuration @@ -608,7 +608,7 @@ node = "tcp://localhost:26657" broadcast-mode = "sync" ``` ---- + ## Network Launch @@ -645,7 +645,7 @@ After all validators have configured their nodes, coordinate the network launch. ---- + ### Distribute Genesis File @@ -693,7 +693,7 @@ ipfs get QmXyz123... -o ~/.yourchain/config/genesis.json ---- + ### Verify Genesis Hash @@ -751,7 +751,7 @@ All validators must have byte-for-byte identical files. ---- + ### Exchange Peer Information @@ -810,7 +810,7 @@ curl localhost:26657/net_info | jq '.result.peers' ---- + ### Coordinate Launch Time @@ -869,7 +869,7 @@ INF finalizing commit of block hash=DEF456... height=2 ---- + ### Start Validator Nodes @@ -942,7 +942,7 @@ sudo journalctl -u yourchain -f ---- + ### Verify Network Health @@ -1045,7 +1045,7 @@ curl http://localhost:8545 \ ---- + ## Post-Launch Operations @@ -1101,7 +1101,7 @@ yourchain query distribution validator-outstanding-rewards \ ---- + ### Monitoring and Alerting @@ -1141,7 +1141,7 @@ yourchain query distribution validator-outstanding-rewards \ ---- + ### Backup and Recovery @@ -1193,7 +1193,7 @@ yourchain start ---- + ## Troubleshooting @@ -1281,7 +1281,7 @@ curl localhost:26657/validators | \ ---- + ## Next Steps @@ -1298,7 +1298,7 @@ Your chain is now launched and operational! - [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 From 04dbffff44d1e207f493b602d31e1008ffb20663 Mon Sep 17 00:00:00 2001 From: Cordt Date: Wed, 15 Oct 2025 15:55:56 -0600 Subject: [PATCH 3/6] make all codeblocks expandable, and various cleanup --- .../pre-genesis-and-genesis-setup.mdx | 252 ++++++++---------- 1 file changed, 106 insertions(+), 146 deletions(-) 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 index 0f3725ac..f0e1731e 100644 --- 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 @@ -152,7 +152,7 @@ Confirm these parameters before running `yourchain init`. These parameters are c -```bash +```bash expandable # 1. Navigate to evm repository cd /path/to/evm @@ -182,18 +182,18 @@ make build **1. Rename the binary directory:** -```bash +```bash expandable mv evmd yourchain ``` **2. Update Go imports in all `.go` files:** -```bash +```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 +```go expandable // FROM: module github.com/cosmos/evm @@ -202,17 +202,17 @@ module github.com/your-org/your-chain ``` **4. Update Makefile references:** -```bash +```bash expandable sed -i '' 's/evmd/yourchain/g' Makefile ``` **5. Run go mod tidy:** -```bash +```bash expandable go mod tidy ``` **6. Build and verify:** -```bash +```bash expandable make build ./build/yourchain version ``` @@ -226,7 +226,7 @@ The renaming process updates: - `evmd/cmd/evmd/` → `yourchain/cmd/yourchain/` **Go Import Paths:** -```go +```go expandable // Before import "github.com/cosmos/evm/evmd/cmd" @@ -235,7 +235,7 @@ import "github.com/your-org/your-chain/yourchain/cmd" ``` **Module Declaration:** -```go +```go expandable // go.mod before module github.com/cosmos/evm @@ -276,7 +276,7 @@ Must be changed **before** running `yourchain init`. Changing after genesis requ Edit `config/config.go` and change the `Bech32Prefix` constant: -```go +```go expandable const ( // Bech32Prefix defines the Bech32 prefix for your chain Bech32Prefix = "yourchain" // Change this line @@ -296,7 +296,7 @@ const ( ``` **After changing, rebuild:** -```bash +```bash expandable make build ``` @@ -305,7 +305,7 @@ 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...` | @@ -319,7 +319,7 @@ All these are automatically derived from the base `Bech32Prefix`. After building with your new prefix, verify it works: -```bash +```bash expandable # Initialize chain ./build/yourchain init test --chain-id test-1 @@ -358,7 +358,7 @@ Expected output: **For EVM-compatible chains, use the default:** -```go +```go expandable var ( // Bip44CoinType satisfies EIP84 for Ethereum compatibility Bip44CoinType uint32 = 60 @@ -384,7 +384,7 @@ var ( 3. **Update the code** in `crypto/hd/hdpath.go`: -```go +```go expandable var ( // Bip44CoinType for your chain Bip44CoinType uint32 = 12345 // Your registered number @@ -395,7 +395,7 @@ var ( ``` 4. **Rebuild the binary:** -```bash +```bash expandable make build ``` @@ -404,7 +404,7 @@ make build | Coin Type | Chain | Purpose | -|||| +| --- | --- | --- | | `60` | Ethereum | **EVM chains (recommended)** | | `118` | Cosmos Hub | Traditional Cosmos chains | | `330` | Terra | Terra ecosystem | @@ -439,7 +439,7 @@ The EVM Chain ID **cannot** be changed after genesis without breaking all transa Edit `config/config.go` and change the `EVMChainID` constant: -```go +```go expandable const ( // EVMChainID defines the EIP-155 replay-protection chain id EVMChainID = 123456 // Change to your unique chain ID @@ -449,17 +449,17 @@ const ( **This value is used during `yourchain init`** to populate the `evm-chain-id` field in `app.toml`. **After changing, rebuild:** -```bash +```bash expandable make build ``` **Then initialize (the chain ID will be embedded):** -```bash +```bash expandable ./build/yourchain init mynode --chain-id mychain-1 ``` **Verify it was set correctly:** -```bash +```bash expandable grep 'evm-chain-id' ~/.yourchain/config/app.toml # Should show: evm-chain-id = "123456" ``` @@ -495,7 +495,7 @@ grep 'evm-chain-id' ~/.yourchain/config/app.toml The EVM Chain ID is used for: **Transaction Signing:** -```javascript +```javascript expandable // EIP-155 transaction signature includes chain ID const tx = { chainId: 123456, // Your EVM Chain ID @@ -509,7 +509,7 @@ const tx = { ``` **Wallet Configuration:** -```javascript +```javascript expandable // MetaMask network configuration { chainId: '0x1E240', // 123456 in hex @@ -569,7 +569,7 @@ This decision affects your entire architecture and cannot be changed after genes ``` **In Genesis:** -```json +```json expandable { "app_state": { "bank": { @@ -614,7 +614,7 @@ This decision affects your entire architecture and cannot be changed after genes **Additional Setup Required:** 1. **Add PreciseBank to `app.go`:** -```go +```go expandable import ( precisebankkeeper "github.com/cosmos/evm/x/precisebank/keeper" precisebanktypes "github.com/cosmos/evm/x/precisebank/types" @@ -637,7 +637,7 @@ app.ModuleManager = module.NewManager( ``` 2. **Configure Extended Denom in Genesis:** -```json +```json expandable { "app_state": { "bank": { @@ -670,9 +670,9 @@ app.ModuleManager = module.NewManager( ⚠️ **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 | @@ -712,7 +712,7 @@ This step must be completed **before** running `yourchain init`. The defaults ar **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 +```toml expandable # FROM: minimum-gas-prices = "0aatom" @@ -724,7 +724,7 @@ minimum-gas-prices = "0atoken" **File**: [`x/vm/types/params.go:21-25`](https://github.com/cosmos/evm/blob/main/x/vm/types/params.go#L21-L25) **Change:** -```go +```go expandable // FROM: var ( DefaultEVMDenom = "uatom" @@ -744,7 +744,7 @@ var ( **File**: [`config/constants.go:5-8`](https://github.com/cosmos/evm/blob/main/config/constants.go#L5-L8) **Change:** -```go +```go expandable // FROM: const ( ExampleChainDenom = "aatom" @@ -762,7 +762,7 @@ const ( **For 18-decimal tokens (recommended):** -```bash +```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 @@ -789,7 +789,7 @@ grep "minimum-gas-prices" ~/.yourchain/config/app.toml **For 6-decimal tokens (Cosmos standard):** -```bash +```bash expandable # Update the same files but use "utoken" instead: # DefaultEVMDenom = "utoken" # DefaultEVMExtendedDenom = "atoken" # Still needs extended for EVM @@ -800,7 +800,7 @@ grep "minimum-gas-prices" ~/.yourchain/config/app.toml After making changes and rebuilding: -```bash +```bash expandable # 1. Initialize chain ./build/yourchain init testnode --chain-id test-1 --home /tmp/test-home @@ -852,12 +852,12 @@ Genesis parameters can be modified until you distribute the genesis file to vali First, initialize the chain to create the default genesis file: -```bash +```bash expandable yourchain init --chain-id ``` Example: -```bash +```bash expandable yourchain init mynode --chain-id mychain-1 ``` @@ -885,7 +885,7 @@ Now proceed with genesis configuration below. The Cosmos Chain ID is typically set during initialization: -```bash +```bash expandable yourchain init mynode --chain-id mychain-1 ``` @@ -895,7 +895,7 @@ This writes the chain ID to both `genesis.json` and `client.toml`. To change the chain ID after initialization: -```bash +```bash expandable # Update genesis.json jq '.chain_id = "mychain-1"' ~/.yourchain/config/genesis.json > tmp && \ mv tmp ~/.yourchain/config/genesis.json @@ -905,7 +905,7 @@ yourchain config set client chain-id mychain-1 --home ~/.yourchain ``` **Verify:** -```bash +```bash expandable jq '.chain_id' ~/.yourchain/config/genesis.json grep 'chain-id' ~/.yourchain/config/client.toml ``` @@ -968,13 +968,13 @@ dev-1 Set the genesis time to a future UTC timestamp: -```bash +```bash expandable jq '.genesis_time = "2024-12-01T00:00:00Z"' ~/.yourchain/config/genesis.json > tmp && \ mv tmp ~/.yourchain/config/genesis.json ``` **Verify:** -```bash +```bash expandable jq '.genesis_time' ~/.yourchain/config/genesis.json ``` @@ -989,7 +989,7 @@ jq '.genesis_time' ~/.yourchain/config/genesis.json 5. **Consensus begins** automatically at genesis_time **Validator Experience:** -```bash +```bash expandable # Start node before genesis time yourchain start @@ -1040,24 +1040,21 @@ T+10m: Verify all validators online **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. + + - -**For EVM-compatible chains using 18 decimals:** + +**Configure denomination metadata for your chosen precision:** -```bash +```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": [] - } + {"denom": "atoken", "exponent": 0, "aliases": ["attotoken"]}, + {"denom": "token", "exponent": 18, "aliases": []} ], "base": "atoken", "display": "token", @@ -1066,50 +1063,23 @@ jq '.app_state.bank.denom_metadata=[{ "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 Explained:** -- `base`: Smallest unit stored on-chain (`atoken`) -- `display`: Human-readable unit (`token`) -- `exponent`: Decimal places (18 for EVM compatibility) +**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`) - -**For Cosmos-standard chains using 6 decimals:** - -```bash -jq '.app_state.bank.denom_metadata=[{ - "description": "The native staking and gas token", - "denom_units": [ - { - "denom": "utoken", - "exponent": 0, - "aliases": ["microtoken"] - }, - { - "denom": "token", - "exponent": 6, - "aliases": [] - } - ], - "base": "utoken", - "display": "token", - "name": "My Token", - "symbol": "TKN" -}]' ~/.yourchain/config/genesis.json > tmp && mv tmp ~/.yourchain/config/genesis.json -``` - -**Note**: When using 6 decimals, you must also: -- Add PreciseBank module to `app.go` -- Configure `extended_denom_options` in VM params (see next section) - - After configuration, verify all denoms match across modules: -```bash +```bash expandable GENESIS=~/.yourchain/config/genesis.json # Check bank metadata base @@ -1153,7 +1123,7 @@ jq '.app_state.gov.params.min_deposit[0].denom' $GENESIS **Sets which bank denomination is used for EVM gas:** -```bash +```bash expandable jq '.app_state.evm.params.evm_denom = "atoken"' \ ~/.yourchain/config/genesis.json > tmp && mv tmp ~/.yourchain/config/genesis.json ``` @@ -1164,46 +1134,36 @@ jq '.app_state.evm.params.evm_denom = "atoken"' \ -**Only required for non-18 decimal chains:** - -When using 6 decimals (or other non-18 decimals), configure extended denom: +**Only required for 6-decimal chains** (see [Token Decimal Precision](#token-decimal-precision)): -```bash +```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 ``` -**Example for 6-decimal chain:** -```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 { - "app_state": { - "evm": { - "params": { - "evm_denom": "utoken", - "extended_denom_options": { - "extended_denom": "atoken" - } - } - } + "evm_denom": "utoken", + "extended_denom_options": { + "extended_denom": "atoken" } } ``` -**How it works:** -- Cosmos SDK uses: `utoken` (6 decimals) -- EVM sees: `atoken` (18 decimals) -- PreciseBank handles conversion: `1 utoken = 10^12 wei` - -**Not needed for 18-decimal chains** - leave empty or omit. - **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 +```bash expandable jq '.app_state.evm.params.history_serve_window = 8192' \ ~/.yourchain/config/genesis.json > tmp && mv tmp ~/.yourchain/config/genesis.json ``` @@ -1226,7 +1186,7 @@ jq '.app_state.evm.params.history_serve_window = 8192' \ **Enable additional Ethereum Improvement Proposals:** -```bash +```bash expandable jq '.app_state.evm.params.extra_eips = []' \ ~/.yourchain/config/genesis.json > tmp && mv tmp ~/.yourchain/config/genesis.json ``` @@ -1261,7 +1221,7 @@ jq '.app_state.evm.params.extra_eips = []' \ | Address | Name | Purpose | -|||| +| --- | --- | --- | | `0x0100` | **P256** | Cryptographic operations for Web3 auth | | `0x0400` | **Bech32** | Cosmos ↔ Ethereum address conversion | | `0x0800` | **Staking** | Validator staking operations | @@ -1277,7 +1237,7 @@ jq '.app_state.evm.params.extra_eips = []' \ **Enable all precompiles for maximum Cosmos SDK integration:** -```bash +```bash expandable jq '.app_state.evm.params.active_static_precompiles = [ "0x0000000000000000000000000000000000000100", "0x0000000000000000000000000000000000000400", @@ -1298,7 +1258,7 @@ jq '.app_state.evm.params.active_static_precompiles = [ **Enable only specific precompiles:** -```bash +```bash expandable jq '.app_state.evm.params.active_static_precompiles = [ "0x0000000000000000000000000000000000000100", "0x0000000000000000000000000000000000000400", @@ -1319,7 +1279,7 @@ This example enables: **Pure EVM chain with no Cosmos SDK integration:** -```bash +```bash expandable jq '.app_state.evm.params.active_static_precompiles = []' \ ~/.yourchain/config/genesis.json > tmp && mv tmp ~/.yourchain/config/genesis.json ``` @@ -1354,7 +1314,7 @@ jq '.app_state.evm.params.active_static_precompiles = []' \ **Configure the native token's ERC20 representation:** -```bash +```bash expandable # Set native precompile address jq '.app_state.erc20.native_precompiles = ["0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE"]' \ ~/.yourchain/config/genesis.json > tmp && mv tmp ~/.yourchain/config/genesis.json @@ -1378,7 +1338,7 @@ jq '.app_state.erc20.token_pairs = [{ **Control who can register new token pairs:** -```bash +```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 @@ -1398,7 +1358,7 @@ jq '.app_state.erc20.params.permissionless_registration = false' \ -```json +```json expandable { "app_state": { "erc20": { @@ -1443,7 +1403,7 @@ jq '.app_state.erc20.params.permissionless_registration = false' \ -```bash +```bash expandable jq '.app_state.feemarket.params = { "no_base_fee": false, "base_fee": "1000000000", @@ -1468,7 +1428,7 @@ jq '.app_state.feemarket.params = { -```bash +```bash expandable jq '.app_state.feemarket.params = { "no_base_fee": true, "min_gas_price": "1000000000" @@ -1532,7 +1492,7 @@ jq '.app_state.feemarket.params = { -```bash +```bash expandable jq '.app_state.evm.params.access_control = { "create": { "access_type": 0, @@ -1551,7 +1511,7 @@ jq '.app_state.evm.params.access_control = { -```bash +```bash expandable jq '.app_state.evm.params.access_control = { "create": { "access_type": 2, @@ -1573,7 +1533,7 @@ jq '.app_state.evm.params.access_control = { -```bash +```bash expandable jq '.app_state.evm.params.access_control.create = { "access_type": 1, "access_control_list": [ @@ -1589,7 +1549,7 @@ jq '.app_state.evm.params.access_control.create = { | 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 | @@ -1614,7 +1574,7 @@ jq '.app_state.evm.params.access_control.create = { -```bash +```bash expandable # Set bond denomination jq '.app_state.staking.params.bond_denom = "atoken"' \ ~/.yourchain/config/genesis.json > tmp && mv tmp ~/.yourchain/config/genesis.json @@ -1672,7 +1632,7 @@ jq '.app_state.staking.params.max_validators = 100' \ -```json +```json expandable { "app_state": { "staking": { @@ -1701,7 +1661,7 @@ jq '.app_state.staking.params.max_validators = 100' \ -```bash +```bash expandable jq '.app_state.slashing.params = { "signed_blocks_window": "10000", "min_signed_per_window": "0.500000000000000000", @@ -1791,7 +1751,7 @@ jq '.app_state.slashing.params = { -```bash +```bash expandable jq '.app_state.gov.params = { "min_deposit": [{ "denom": "atoken", @@ -1852,13 +1812,13 @@ jq '.app_state.gov.params = { **Set minimum deposit denom:** -```bash +```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 +```bash expandable # Standard voting period jq '.app_state.gov.params.voting_period = "172800s"' \ ~/.yourchain/config/genesis.json > tmp && mv tmp ~/.yourchain/config/genesis.json @@ -1882,7 +1842,7 @@ jq '.app_state.gov.params.expedited_voting_period = "86400s"' \ -```bash +```bash expandable jq '.app_state.mint.params = { "mint_denom": "atoken", "inflation_rate_change": "0.130000000000000000", @@ -1933,7 +1893,7 @@ jq '.app_state.mint.params = { -```bash +```bash expandable jq '.app_state.distribution.params = { "community_tax": "0.020000000000000000", "base_proposer_reward": "0.000000000000000000", @@ -1972,7 +1932,7 @@ After configuring all genesis parameters, add initial accounts and collect valid **Add accounts with initial balances:** -```bash +```bash expandable # Add account by address yourchain genesis add-genesis-account \ cosmos1abc123... \ @@ -1991,7 +1951,7 @@ yourchain genesis add-genesis-account faucet 10000000000000000000000atoken ``` **Verify accounts:** -```bash +```bash expandable jq '.app_state.bank.balances' ~/.yourchain/config/genesis.json ``` @@ -2000,7 +1960,7 @@ jq '.app_state.bank.balances' ~/.yourchain/config/genesis.json **Workflow:** **1. Each validator creates their gentx:** -```bash +```bash expandable yourchain genesis gentx validator1 \ 1000000000000000000000atoken \ --chain-id mychain-1 \ @@ -2015,12 +1975,12 @@ yourchain genesis gentx validator1 \ **Output**: Creates `~/.yourchain/config/gentx/gentx-.json` **2. Validator shares gentx file:** -```bash +```bash expandable cat ~/.yourchain/config/gentx/gentx-*.json ``` **3. Coordinator collects all gentxs:** -```bash +```bash expandable # Create gentx directory mkdir -p ~/.yourchain/config/gentx/ @@ -2032,7 +1992,7 @@ yourchain genesis collect-gentxs ``` **4. Verify:** -```bash +```bash expandable yourchain genesis validate jq '.app_state.genutil.gen_txs | length' ~/.yourchain/config/genesis.json ``` @@ -2041,7 +2001,7 @@ jq '.app_state.genutil.gen_txs | length' ~/.yourchain/config/genesis.json **Final validation before distribution:** -```bash +```bash expandable # Validate structure and parameters yourchain genesis validate ``` @@ -2055,7 +2015,7 @@ yourchain genesis validate - Gentxs are valid **Verify denomination consistency:** -```bash +```bash expandable GENESIS=~/.yourchain/config/genesis.json jq '[ @@ -2070,12 +2030,12 @@ jq '[ **Should output `1`** (all denoms match) **Check total supply:** -```bash +```bash expandable jq '.app_state.bank.balances | map(.coins[0].amount | tonumber) | add' $GENESIS ``` **Check validator count:** -```bash +```bash expandable jq '.app_state.genutil.gen_txs | length' $GENESIS ``` From 1f1c138a7aa85df35277e1872fb92f9c09fb9412 Mon Sep 17 00:00:00 2001 From: Cordt Date: Wed, 15 Oct 2025 16:34:29 -0600 Subject: [PATCH 4/6] first pass major cleanup to build docs --- .../mempool-integration.mdx | 40 ++- .../predeployed-contracts.mdx | 32 +- .../chain-configuration-reference.mdx | 252 +++++++-------- .../chain-customization-checklist.mdx | 288 ++++++------------ .../configuration-parameters.mdx | 86 +++--- .../build-a-chain/configuration-reference.mdx | 74 ++--- .../build-a-chain/overview.mdx | 14 +- .../build-a-chain/runtime-and-launch.mdx | 124 ++++---- 8 files changed, 368 insertions(+), 542 deletions(-) diff --git a/docs/evm/next/documentation/getting-started/build-a-chain/additional-configuration/mempool-integration.mdx b/docs/evm/next/documentation/getting-started/build-a-chain/additional-configuration/mempool-integration.mdx index fefcd4e7..66b7baf4 100644 --- a/docs/evm/next/documentation/getting-started/build-a-chain/additional-configuration/mempool-integration.mdx +++ b/docs/evm/next/documentation/getting-started/build-a-chain/additional-configuration/mempool-integration.mdx @@ -9,8 +9,7 @@ This guide provides step-by-step instructions for integrating the EVM mempool in ### Step 1: Add EVM Mempool to App Struct - -```go +```go expandable // Update your app/app.go to include the EVM mempool type App struct { *baseapp.BaseApp @@ -22,7 +21,6 @@ type App struct { EVMMempool *evmmempool.ExperimentalEVMMempool } ``` - ### Step 2: Configure Mempool in NewApp Constructor @@ -32,8 +30,7 @@ The mempool must be initialized **after** the antehandler has been set in the ap Add the following configuration in your `NewApp` constructor: - -```go +```go expandable // Set the EVM priority nonce mempool if evmtypes.GetChainConfig() != nil { mempoolConfig := &evmmempool.EVMMempoolConfig{ @@ -69,7 +66,6 @@ if evmtypes.GetChainConfig() != nil { app.SetPrepareProposal(abciProposalHandler.PrepareProposalHandler()) } ``` - **Breaking Change from v0.4.x:** The global mempool registry (`SetGlobalEVMMempool`) has been removed. Mempool is now passed directly to the JSON-RPC server during initialization. @@ -83,7 +79,7 @@ The `EVMMempoolConfig` struct provides several configuration options for customi For most use cases, the minimal configuration is sufficient: -```go +```go expandable mempoolConfig := &evmmempool.EVMMempoolConfig{ AnteHandler: app.GetAnteHandler(), BlockGasLimit: 100_000_000, // or 0 to use default @@ -92,7 +88,7 @@ mempoolConfig := &evmmempool.EVMMempoolConfig{ -```go +```go expandable type EVMMempoolConfig struct { // Required: AnteHandler for transaction validation AnteHandler sdk.AnteHandler @@ -140,7 +136,7 @@ PR [#496](https://github.com/cosmos/evm/pull/496) replaced pre-built pools with If you use the default mempool wiring (no custom pools), your existing code continues to work: -```go +```go expandable mempoolConfig := &evmmempool.EVMMempoolConfig{ AnteHandler: app.GetAnteHandler(), BlockGasLimit: 100_000_000, // or 0 to use default @@ -156,7 +152,7 @@ evmMempool := evmmempool.NewExperimentalEVMMempool( If you built custom pools yourself, replace them with configuration objects: **Before (v0.4.x):** -```go +```go expandable mempoolConfig := &evmmempool.EVMMempoolConfig{ TxPool: customTxPool, // ← REMOVED CosmosPool: customCosmosPool, // ← REMOVED @@ -166,7 +162,7 @@ mempoolConfig := &evmmempool.EVMMempoolConfig{ ``` **After (v0.5.0):** -```go +```go expandable mempoolConfig := &evmmempool.EVMMempoolConfig{ LegacyPoolConfig: &legacyCfg, // ← NEW (or nil for defaults) CosmosPoolConfig: &cosmosCfg, // ← NEW (or nil for defaults) @@ -179,7 +175,7 @@ mempoolConfig := &evmmempool.EVMMempoolConfig{ Customize EVM transaction pool parameters: -```go +```go expandable // EVM legacy txpool tuning legacyCfg := legacypool.DefaultConfig legacyCfg.PriceLimit = 2 // Minimum gas price (wei) @@ -197,7 +193,7 @@ mempoolConfig.LegacyPoolConfig = &legacyCfg The mempool uses a `PriorityNonceMempool` for Cosmos transactions by default. You can customize the priority calculation: -```go +```go expandable // Define custom priority calculation for Cosmos transactions cosmosCfg := sdkmempool.PriorityNonceMempoolConfig[math.Int]{} cosmosCfg.TxPriority = sdkmempool.TxPriority[math.Int]{ @@ -232,7 +228,7 @@ mempoolConfig.CosmosPoolConfig = &cosmosCfg Override the default broadcast behavior for promoted EVM transactions: -```go +```go expandable // Custom EVM broadcast (optional) mempoolConfig.BroadcastTxFn = func(txs []*ethtypes.Transaction) error { // Custom logic for broadcasting promoted transactions @@ -244,7 +240,7 @@ mempoolConfig.BroadcastTxFn = func(txs []*ethtypes.Transaction) error { Different chains may require different gas limits based on their capacity: -```go +```go expandable // Example: 50M gas limit for lower capacity chains mempoolConfig := &evmmempool.EVMMempoolConfig{ AnteHandler: app.GetAnteHandler(), @@ -256,7 +252,7 @@ mempoolConfig := &evmmempool.EVMMempoolConfig{ For best results, connect the mempool to CometBFT's EventBus so it can react to finalized blocks: -```go +```go expandable // After starting the CometBFT node if m, ok := app.GetMempool().(*evmmempool.ExperimentalEVMMempool); ok { m.SetEventBus(bftNode.EventBus()) @@ -283,7 +279,7 @@ The main coordinator implementing Cosmos SDK's `ExtMempool` interface (`mempool/ Custom transaction validation that handles nonce gaps specially (`mempool/check_tx.go`). **Special Handling**: On `ErrNonceGap` for EVM transactions: -```go +```go expandable if errors.Is(err, ErrNonceGap) { // Route to local queue instead of rejecting err := mempool.InsertInvalidNonce(request.Tx) @@ -306,7 +302,7 @@ Direct port of Ethereum's transaction pool managing both pending and queued tran Standard Cosmos SDK mempool for non-EVM transactions with fee-based prioritization. **Default Priority Calculation**: -```go +```go expandable // Calculate effective gas price priority = (fee_amount / gas_limit) - base_fee ``` @@ -330,7 +326,7 @@ The mempool handles different transaction types appropriately: During block building, both transaction types compete fairly based on their effective tips: -```go +```go expandable // Simplified selection logic func SelectTransactions() Iterator { evmTxs := GetPendingEVMTransactions() // From local TxPool @@ -351,7 +347,7 @@ func SelectTransactions() Iterator { Test that transactions with nonce gaps are properly queued: -```javascript +```javascript expandable // Send transactions out of order await wallet.sendTransaction({nonce: 100, ...}); // OK: Immediate execution await wallet.sendTransaction({nonce: 102, ...}); // OK: Queued locally (gap) @@ -362,7 +358,7 @@ await wallet.sendTransaction({nonce: 101, ...}); // OK: Fills gap, both execute Verify that higher-fee transactions replace lower-fee ones: -```javascript +```javascript expandable // Send initial transaction const tx1 = await wallet.sendTransaction({ nonce: 100, @@ -381,7 +377,7 @@ const tx2 = await wallet.sendTransaction({ Test typical deployment scripts (like Uniswap) that send many transactions at once: -```javascript +```javascript expandable // Deploy multiple contracts in quick succession const factory = await Factory.deploy(); const router = await Router.deploy(factory.address); diff --git a/docs/evm/next/documentation/getting-started/build-a-chain/additional-configuration/predeployed-contracts.mdx b/docs/evm/next/documentation/getting-started/build-a-chain/additional-configuration/predeployed-contracts.mdx index b6088c6a..8cd94f79 100644 --- a/docs/evm/next/documentation/getting-started/build-a-chain/additional-configuration/predeployed-contracts.mdx +++ b/docs/evm/next/documentation/getting-started/build-a-chain/additional-configuration/predeployed-contracts.mdx @@ -28,8 +28,7 @@ The most straightforward method for new chains or testnets. Contracts are deploy If using the reference `evmd` application, your chain automatically includes default preinstalls, however they will not be active by default. - -```go +```go expandable // Source: evmd/genesis.go:28-34 func NewEVMGenesisState() *evmtypes.GenesisState { evmGenState := evmtypes.DefaultGenesisState() @@ -38,14 +37,12 @@ func NewEVMGenesisState() *evmtypes.GenesisState { return evmGenState } ``` - To customize which contracts are deployed: - -```json +```json expandable { "app_state": { "evm": { @@ -65,7 +62,6 @@ To customize which contracts are deployed: } } ``` - @@ -73,7 +69,7 @@ To customize which contracts are deployed: The `local_node.sh` script automatically configures default preinstalls: -```bash +```bash expandable ./local_node.sh # Automatically deploys all default preinstalls ``` @@ -88,7 +84,7 @@ For chains already in production, use the `MsgRegisterPreinstalls` governance pr The `authority` field must be set to the governance module account address, which is typically derived from the gov module name. This is usually something like `cosmos10d07y265gmmuvt4z0w9aw880jnsr700j6zn9kn` for the standard gov module. -```json +```json expandable { "messages": [ { @@ -112,7 +108,7 @@ The `authority` field must be set to the governance module account address, whic #### Submission Process -```bash +```bash expandable # Submit proposal evmd tx gov submit-proposal proposal.json \ --from mykey \ @@ -127,8 +123,7 @@ evmd tx gov vote 1 yes --from mykey Include predeployed contracts as part of a coordinated chain upgrade: - -```go +```go expandable func CreateUpgradeHandler( mm *module.Manager, configurator module.Configurator, @@ -144,7 +139,6 @@ func CreateUpgradeHandler( } } ``` - ## Implementation Details @@ -171,8 +165,7 @@ All preinstall deployments undergo strict validation: Predeployed contracts are stored in the chain state like regular contracts: - -```go +```go expandable // Actual deployment process from x/vm/keeper/preinstalls.go func (k *Keeper) AddPreinstalls(ctx sdk.Context, preinstalls []types.Preinstall) error { for _, preinstall := range preinstalls { @@ -213,7 +206,6 @@ func (k *Keeper) AddPreinstalls(ctx sdk.Context, preinstalls []types.Preinstall) return nil } ``` - ## Verification and Testing @@ -221,7 +213,7 @@ func (k *Keeper) AddPreinstalls(ctx sdk.Context, preinstalls []types.Preinstall) After deployment, verify contracts are properly installed: -```bash +```bash expandable # Query contract code via CLI evmd query evm code 0x4e59b44847b379578588920ca78fbf26c0b4956c @@ -229,7 +221,7 @@ evmd query evm code 0x4e59b44847b379578588920ca78fbf26c0b4956c evmd query evm account 0x4e59b44847b379578588920ca78fbf26c0b4956c ``` -```javascript +```javascript expandable // Verify via Web3 const code = await provider.getCode("0x4e59b44847b379578588920ca78fbf26c0b4956c"); console.log("Deployed:", code !== "0x"); @@ -274,7 +266,7 @@ console.log("Deployed:", code !== "0x"); The Safe Singleton Factory bytecode in `DefaultPreinstalls` ([`x/vm/types/preinstall.go:30-32`](https://github.com/cosmos/evm/blob/main/x/vm/types/preinstall.go#L30-L32)) is **identical to the Create2 factory bytecode**, which is incorrect and will not function for deploying Safe wallets. **Verification**: -```bash +```bash expandable # Create2 bytecode 0x7fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffe03601600081602082378035828234f58015156039578182fd5b8082525050506014600cf3 @@ -295,7 +287,7 @@ The Safe Singleton Factory bytecode in `DefaultPreinstalls` ([`x/vm/types/preins To add custom contracts beyond the defaults: -```go +```go expandable // Define custom preinstall customPreinstall := types.Preinstall{ Name: "MyCustomContract", @@ -348,7 +340,7 @@ preinstalls := append(evmtypes.DefaultPreinstalls, customPreinstall) ### Genesis Configuration Paths -```json +```json expandable { "app_state": { "vm": { diff --git a/docs/evm/next/documentation/getting-started/build-a-chain/chain-configuration-reference.mdx b/docs/evm/next/documentation/getting-started/build-a-chain/chain-configuration-reference.mdx index 4f62ed18..e74de2a6 100644 --- a/docs/evm/next/documentation/getting-started/build-a-chain/chain-configuration-reference.mdx +++ b/docs/evm/next/documentation/getting-started/build-a-chain/chain-configuration-reference.mdx @@ -35,14 +35,14 @@ When building your custom chain, you'll configure parameters across multiple are -```bash +```bash expandable cd /path/to/cosmos-evm mv evmd yourchain ``` -```bash +```bash expandable # Update all references in Go files find . -type f -name "*.go" -exec sed -i '' \ 's|github.com/cosmos/evm/evmd|github.com/your-org/your-chain/yourchain|g' {} \; @@ -51,7 +51,7 @@ find . -type f -name "*.go" -exec sed -i '' \ Edit the module declaration: -```go +```go expandable module github.com/your-org/your-chain // Update all import paths that reference evmd @@ -59,13 +59,13 @@ module github.com/your-org/your-chain -```bash +```bash expandable sed -i '' 's/evmd/yourchain/g' Makefile ``` -```bash +```bash expandable go mod tidy make build @@ -96,14 +96,14 @@ Must be changed **before** running `yourchain init`. Changing after genesis requ **Default Code**: -```go +```go expandable const ( Bech32Prefix = "cosmos" ) ``` **Update to Your Prefix**: -```go +```go expandable const ( // Bech32Prefix defines the Bech32 prefix for your chain Bech32Prefix = "yourchain" @@ -138,7 +138,7 @@ const ( ### Default Configuration -```go +```go expandable var ( // Bip44CoinType satisfies EIP84 Bip44CoinType uint32 = 60 // Ethereum compatibility @@ -151,7 +151,7 @@ var ( **Use `60` for EVM chains**: -```go +```go expandable var ( // Bip44CoinType for Ethereum compatibility Bip44CoinType uint32 = 60 @@ -176,7 +176,7 @@ var ( 1. Register at [SLIP-0044](https://github.com/satoshilabs/slips/blob/master/slip-0044.md) 2. Update code: -```go +```go expandable var ( // Bip44CoinType for your chain Bip44CoinType uint32 = 12345 // Your registered value @@ -210,7 +210,7 @@ var ( **Default Code**: -```go +```go expandable const ( // EVMChainID defines the EIP-155 replay-protection chain id EVMChainID = 262144 @@ -218,7 +218,7 @@ const ( ``` **Update to Your Chain ID**: -```go +```go expandable const ( // EVMChainID defines the EIP-155 replay-protection chain id EVMChainID = 123456 // Your unique chain ID @@ -227,8 +227,6 @@ const ( ### Choosing an EVM Chain ID - - **Do not use**: - `1` - Ethereum Mainnet - `137` - Polygon @@ -236,18 +234,14 @@ const ( - `42161` - Arbitrum One - `10` - Optimism - Check [chainlist.org](https://chainlist.org) for all registered chains - - **Local development and testnets**: - Use `262144` (evmd default) - Or any unique high number (e.g., `999001`) - No registration needed **Testing Range**: Typically use numbers > 100,000 - - **Mainnet launches**: 1. Choose a unique integer not in use 2. Check [chainlist.org](https://chainlist.org) for conflicts @@ -257,8 +251,6 @@ const ( **Recommended Ranges**: - 1,000 - 99,999: Public chains - 100,000+: Private/test networks - - ### How It Works @@ -267,7 +259,7 @@ const ( **During node startup**: Read from `app.toml` to initialize EVM encoding **Verification After Init**: -```bash +```bash expandable grep 'evm-chain-id' ~/.yourchain/config/app.toml ``` @@ -379,7 +371,7 @@ For chains using other decimal precisions (e.g., 8 decimals for Bitcoin compatib -```bash +```bash expandable jq '.app_state.bank.denom_metadata=[{ "description": "The native staking and gas token", "denom_units": [ @@ -410,7 +402,7 @@ jq '.app_state.bank.denom_metadata=[{ -```bash +```bash expandable jq '.app_state.bank.denom_metadata=[{ "description": "The native staking and gas token", "denom_units": [ @@ -480,12 +472,12 @@ Mismatched denominations will cause genesis validation to fail. ### How to Configure -```bash +```bash expandable jq '.app_state.evm.params.evm_denom = "atoken"' genesis.json > tmp && mv tmp genesis.json ``` **Example Genesis**: -```json +```json expandable { "app_state": { "evm": { @@ -515,14 +507,14 @@ jq '.app_state.evm.params.evm_denom = "atoken"' genesis.json > tmp && mv tmp gen ### Configuration for 6-Decimal Chains -```bash +```bash expandable jq '.app_state.evm.params.extended_denom_options = { "extended_denom": "atoken" }' genesis.json > tmp && mv tmp genesis.json ``` **Example Genesis**: -```json +```json expandable { "app_state": { "evm": { @@ -570,7 +562,7 @@ jq '.app_state.evm.params.extended_denom_options = { ### Native Token Pair Configuration -```bash +```bash expandable jq '.app_state.erc20.token_pairs = [{ "erc20_address": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE", "denom": "atoken", @@ -580,7 +572,7 @@ jq '.app_state.erc20.token_pairs = [{ ``` **Example Genesis**: -```json +```json expandable { "app_state": { "erc20": { @@ -618,12 +610,12 @@ jq '.app_state.erc20.token_pairs = [{ ### Configuration -```bash +```bash expandable jq '.app_state.erc20.native_precompiles = ["0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE"]' genesis.json > tmp && mv tmp genesis.json ``` **Example Genesis**: -```json +```json expandable { "app_state": { "erc20": { @@ -653,7 +645,7 @@ jq '.app_state.erc20.native_precompiles = ["0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeee -```bash +```bash expandable jq '.app_state.erc20.params.permissionless_registration = true' genesis.json > tmp && mv tmp genesis.json ``` @@ -663,7 +655,7 @@ jq '.app_state.erc20.params.permissionless_registration = true' genesis.json > t -```bash +```bash expandable jq '.app_state.erc20.params.permissionless_registration = false' genesis.json > tmp && mv tmp genesis.json ``` @@ -711,7 +703,7 @@ For complete precompile documentation including Solidity interfaces and usage ex -```bash +```bash expandable jq '.app_state.evm.params.active_static_precompiles = [ "0x0000000000000000000000000000000000000100", "0x0000000000000000000000000000000000000400", @@ -730,7 +722,7 @@ jq '.app_state.evm.params.active_static_precompiles = [ -```bash +```bash expandable jq '.app_state.evm.params.active_static_precompiles = [ "0x0000000000000000000000000000000000000100", "0x0000000000000000000000000000000000000400", @@ -744,7 +736,7 @@ jq '.app_state.evm.params.active_static_precompiles = [ -```bash +```bash expandable jq '.app_state.evm.params.active_static_precompiles = []' genesis.json > tmp && mv tmp genesis.json ``` @@ -760,7 +752,7 @@ jq '.app_state.evm.params.active_static_precompiles = []' genesis.json > tmp && Precompiles can be enabled or disabled through governance proposals: -```bash +```bash expandable yourchain tx gov submit-proposal param-change proposal.json \ --from validator \ --chain-id yourchain-1 @@ -807,7 +799,7 @@ No manual configuration needed unless you want to disable specific contracts. **Verification After Init**: -```bash +```bash expandable jq '.app_state.evm.preinstalls' ~/.yourchain/config/genesis.json ``` @@ -833,7 +825,7 @@ jq '.app_state.evm.preinstalls' ~/.yourchain/config/genesis.json -```json +```json expandable { "app_state": { "evm": { @@ -860,7 +852,7 @@ jq '.app_state.evm.preinstalls' ~/.yourchain/config/genesis.json -```bash +```bash expandable jq '.app_state.evm.params.access_control = { "create": { "access_type": 2, @@ -882,7 +874,7 @@ jq '.app_state.evm.params.access_control = { -```bash +```bash expandable jq '.app_state.evm.params.access_control.create = { "access_type": 1, "access_control_list": [ @@ -897,7 +889,7 @@ jq '.app_state.evm.params.access_control.create = { -```json +```json expandable { "access_control": { "create": { @@ -950,12 +942,12 @@ The default EVM configuration includes all commonly-used Ethereum features throu ### Configuration -```bash +```bash expandable jq '.app_state.evm.params.extra_eips = [1153, 3855]' genesis.json > tmp && mv tmp genesis.json ``` **Example Genesis**: -```json +```json expandable { "app_state": { "evm": { @@ -989,7 +981,7 @@ EIPs must be activatable in the EVM implementation. Invalid EIP numbers will cau ### Configuration -```bash +```bash expandable jq '.app_state.evm.params.history_serve_window = 8192' genesis.json > tmp && mv tmp genesis.json ``` @@ -1030,7 +1022,7 @@ jq '.app_state.evm.params.history_serve_window = 8192' genesis.json > tmp && mv ### Complete Configuration -```bash +```bash expandable jq '.app_state.feemarket.params = { "no_base_fee": false, "base_fee": "1000000000", @@ -1086,7 +1078,7 @@ jq '.app_state.feemarket.params = { -```json +```json expandable { "no_base_fee": false, "base_fee": "1000000000", @@ -1102,7 +1094,7 @@ jq '.app_state.feemarket.params = { -```json +```json expandable { "no_base_fee": true, "min_gas_price": "1000000000" @@ -1113,7 +1105,7 @@ jq '.app_state.feemarket.params = { -```json +```json expandable { "no_base_fee": false, "base_fee": "100000000", @@ -1145,7 +1137,7 @@ Most Ethereum-compatible chains should keep EIP-1559 enabled (default) for bette ### Configuration -```toml +```toml expandable minimum-gas-prices = "1000000000atoken" ``` @@ -1187,7 +1179,7 @@ minimum-gas-prices = "1000000000atoken" ### Full Configuration -```toml +```toml expandable [evm.mempool] # PriceLimit is the minimum gas price to enforce for acceptance into the pool (in wei) price-limit = 1 @@ -1260,9 +1252,7 @@ Invalid values will cause the node to fail validation on startup. ### Tuning Recommendations - - -```toml +```toml expandable global-slots = 10240 global-queue = 2048 price-limit = 100000000 # 0.1 gwei minimum @@ -1270,10 +1260,8 @@ lifetime = "6h0m0s" ``` **Use Case**: High-volume chains, DeFi platforms, DEXs - - -```toml +```toml expandable global-slots = 2048 global-queue = 512 lifetime = "1h0m0s" @@ -1281,10 +1269,8 @@ account-slots = 8 ``` **Use Case**: Nodes with limited memory, validator nodes - - -```toml +```toml expandable price-limit = 1000000000 # 1 gwei minimum price-bump = 25 # 25% replacement cost lifetime = "30m0s" @@ -1292,8 +1278,6 @@ account-slots = 4 ``` **Use Case**: Preventing spam, maintaining high transaction quality - - **Source**: [server/config/config.go:158-187](https://github.com/cosmos/evm/blob/v0.5.0-rc.1/server/config/config.go#L158-L187) @@ -1308,12 +1292,12 @@ account-slots = 4 ### Configuration **Set Bond Denom**: -```bash +```bash expandable jq '.app_state.staking.params.bond_denom = "atoken"' genesis.json > tmp && mv tmp genesis.json ``` **Complete Configuration**: -```json +```json expandable { "app_state": { "staking": { @@ -1354,17 +1338,17 @@ jq '.app_state.staking.params.bond_denom = "atoken"' genesis.json > tmp && mv tm ### Configuration **Set Min Deposit Denom**: -```bash +```bash expandable jq '.app_state.gov.params.min_deposit[0].denom = "atoken"' genesis.json > tmp && mv tmp genesis.json ``` **Set Voting Period (for testnet)**: -```bash +```bash expandable jq '.app_state.gov.params.voting_period = "30s"' genesis.json > tmp && mv tmp genesis.json ``` **Complete Configuration**: -```json +```json expandable { "app_state": { "gov": { @@ -1412,12 +1396,12 @@ For testnets, set `voting_period` to `"30s"` for faster testing. For mainnets, u ### Configuration **Set Mint Denom**: -```bash +```bash expandable jq '.app_state.mint.params.mint_denom = "atoken"' genesis.json > tmp && mv tmp genesis.json ``` **Complete Configuration**: -```json +```json expandable { "app_state": { "mint": { @@ -1457,7 +1441,7 @@ jq '.app_state.mint.params.mint_denom = "atoken"' genesis.json > tmp && mv tmp g ### Configuration -```json +```json expandable { "app_state": { "distribution": { @@ -1497,7 +1481,7 @@ jq '.app_state.mint.params.mint_denom = "atoken"' genesis.json > tmp && mv tmp g ### Full Configuration -```toml +```toml expandable [json-rpc] # Enable JSON-RPC server enable = true @@ -1584,7 +1568,7 @@ batch-response-max-size = 0 ### Configuration -```toml +```toml expandable [evm] # EVM chain ID (set during init from config/config.go - DO NOT MODIFY) evm-chain-id = 262144 @@ -1662,7 +1646,7 @@ To change the EVM chain ID, you must modify the code constant in `config/config. ### Configuration -```toml +```toml expandable [tls] # Path to TLS certificate certificate-path = "/path/to/cert.pem" @@ -1676,7 +1660,7 @@ key-path = "/path/to/key.pem" **For testing (self-signed)**: -```bash +```bash expandable openssl req -x509 -newkey rsa:4096 \ -keyout key.pem \ -out cert.pem \ @@ -1689,7 +1673,7 @@ openssl req -x509 -newkey rsa:4096 \ -```toml +```toml expandable [tls] certificate-path = "/home/user/.yourchain/config/cert.pem" key-path = "/home/user/.yourchain/config/key.pem" @@ -1697,7 +1681,7 @@ key-path = "/home/user/.yourchain/config/key.pem" -```bash +```bash expandable curl https://localhost:8545 \ -X POST \ -H "Content-Type: application/json" \ @@ -1721,7 +1705,7 @@ curl https://localhost:8545 \ ### Configuration -```toml +```toml expandable # Comma separated list of nodes to keep persistent connections to persistent_peers = "node_id@ip:port,node_id2@ip:port" ``` @@ -1729,7 +1713,7 @@ persistent_peers = "node_id@ip:port,node_id2@ip:port" ### Getting Node Information **Each node gets their Node ID**: -```bash +```bash expandable yourchain comet show-node-id ``` @@ -1742,13 +1726,13 @@ Output: `7c90e16cca334eb7259754f964918d879ca54996` ### Configuration Example -```toml +```toml expandable persistent_peers = "7c90e16cca334eb7259754f964918d879ca54996@192.168.1.100:26656,abc123def456@192.168.1.101:26656,def456abc789@192.168.1.102:26656" ``` ### Verification -```bash +```bash expandable # Check connected peers curl localhost:26657/net_info | jq '.result.peers' ``` @@ -1766,12 +1750,12 @@ curl localhost:26657/net_info | jq '.result.peers' **Format**: `{name}-{version}` (e.g., `mychain-1`, `testnet-3`) **Set During Init**: -```bash +```bash expandable yourchain init mynode --chain-id mychain-1 ``` **Or Modify After Init**: -```bash +```bash expandable jq '.chain_id = "mychain-1"' ~/.yourchain/config/genesis.json > tmp && mv tmp genesis.json ``` @@ -1795,7 +1779,7 @@ Can be any string, but `{name}-{number}` format is canonical for IBC client upgr **Genesis Location**: Root level field `genesis_time` **Configuration**: -```bash +```bash expandable jq '.genesis_time = "2024-12-01T00:00:00Z"' genesis.json > tmp && mv tmp genesis.json ``` @@ -1819,13 +1803,13 @@ jq '.genesis_time = "2024-12-01T00:00:00Z"' genesis.json > tmp && mv tmp genesis ### Adding Single Account -```bash +```bash expandable yourchain genesis add-genesis-account ``` **Examples**: -```bash +```bash expandable # Using address yourchain genesis add-genesis-account \ cosmos1abc123... \ @@ -1845,7 +1829,7 @@ yourchain genesis add-genesis-account faucet 10000000000000000000000atoken ### Bulk Add Accounts -```bash +```bash expandable # Create accounts file cat > accounts.json < -```bash +```bash expandable # On validator node yourchain genesis gentx validator1 \ 1000000000000000000000atoken \ @@ -1896,14 +1880,14 @@ yourchain genesis gentx validator1 \ -```bash +```bash expandable # Validator sends this file to coordinator cat ~/.yourchain/config/gentx/gentx-*.json ``` -```bash +```bash expandable # Coordinator receives all gentx files mkdir -p ~/.yourchain/config/gentx/ # Copy all received gentx files to this directory @@ -1914,7 +1898,7 @@ yourchain genesis collect-gentxs -```bash +```bash expandable yourchain genesis validate jq '.app_state.genutil.gen_txs' ~/.yourchain/config/genesis.json ``` @@ -1931,7 +1915,7 @@ jq '.app_state.genutil.gen_txs' ~/.yourchain/config/genesis.json ### Validation Command -```bash +```bash expandable yourchain genesis validate ``` @@ -1946,8 +1930,6 @@ yourchain genesis validate ### Common Validation Errors - - ``` Error: bond_denom (utoken) does not match evm_denom (atoken) ``` @@ -1958,28 +1940,22 @@ Error: bond_denom (utoken) does not match evm_denom (atoken) - `evm.params.evm_denom` - `gov.params.min_deposit[0].denom` - `bank.denom_metadata[0].base` - - ``` Error: total supply does not match balances ``` **Fix**: Check genesis accounts and token allocations. Recalculate total supply. - - ``` Error: min_gas_multiplier must be between 0 and 1 ``` **Fix**: Correct the parameter value to be within valid range. - - ### Full Verification Checklist -```bash +```bash expandable # 1. Validate structure yourchain genesis validate @@ -2012,7 +1988,7 @@ jq '.app_state.genutil.gen_txs | length' genesis.json **Best for large networks**: -```bash +```bash expandable # Coordinator uploads ipfs add ~/.yourchain/config/genesis.json # Returns: QmXyz123... @@ -2025,7 +2001,7 @@ ipfs get QmXyz123... -o ~/.yourchain/config/genesis.json -```bash +```bash expandable # Coordinator creates release with genesis.json gh release create v1.0.0 ~/.yourchain/config/genesis.json @@ -2061,7 +2037,7 @@ wget https://github.com/yourorg/yourchain/releases/download/v1.0.0/genesis.json -```bash +```bash expandable jq -S -c . ~/.yourchain/config/genesis.json | shasum -a 256 > genesis_hash.txt cat genesis_hash.txt ``` @@ -2079,7 +2055,7 @@ a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6 - -```bash +```bash expandable # Generate local hash jq -S -c . ~/.yourchain/config/genesis.json | shasum -a 256 @@ -2109,7 +2085,7 @@ jq -S -c . ~/.yourchain/config/genesis.json | shasum -a 256 **Each Validator Shares**: **1. Get Node ID**: -```bash +```bash expandable yourchain comet show-node-id ``` Output: `7c90e16cca334eb7259754f964918d879ca54996` @@ -2123,7 +2099,7 @@ Output: `7c90e16cca334eb7259754f964918d879ca54996` **3. Update persistent_peers**: Each validator edits `~/.yourchain/config/config.toml`: -```toml +```toml expandable persistent_peers = "7c90e16c@192.168.1.100:26656,abc123de@192.168.1.101:26656,def456ab@192.168.1.102:26656" ``` @@ -2132,7 +2108,7 @@ persistent_peers = "7c90e16c@192.168.1.100:26656,abc123de@192.168.1.101:26656,de All validators check: -```bash +```bash expandable jq '.genesis_time' ~/.yourchain/config/genesis.json ``` @@ -2142,7 +2118,7 @@ Ensure all validators have the same genesis_time set in their genesis files. Each validator starts their node 15-30 minutes before genesis_time: -```bash +```bash expandable yourchain start ``` @@ -2157,7 +2133,7 @@ Time until genesis: 29m 45s At genesis_time, the chain will automatically start producing blocks when 2/3+ of voting power is online. **Monitor logs**: -```bash +```bash expandable yourchain start 2>&1 | grep "finalizing commit" ``` @@ -2173,29 +2149,29 @@ INF finalizing commit of block hash=GHI789... height=3 ### Monitoring Block Production **1. Check Block Height Increasing**: -```bash +```bash expandable curl localhost:26657/status | jq '.result.sync_info.latest_block_height' ``` **2. Check Validator Participation**: -```bash +```bash expandable curl localhost:26657/validators | jq '.result.validators | length' ``` **3. Confirm 2/3+ Voting Power**: -```bash +```bash expandable curl localhost:26657/validators | \ jq '[.result.validators[].voting_power | tonumber] | add' ``` **4. Check Network Health**: -```bash +```bash expandable curl localhost:26657/health # Should return: {} ``` **5. Test RPC Access**: -```bash +```bash expandable curl http://localhost:8545 \ -X POST \ -H "Content-Type: application/json" \ @@ -2204,8 +2180,6 @@ curl http://localhost:8545 \ ### Common Launch Issues - - **Symptoms**: Nodes waiting indefinitely, no blocks produced **Checks**: @@ -2218,9 +2192,7 @@ curl http://localhost:8545 \ - Ensure enough validators are online - Check network connectivity between nodes - Verify genesis files match (hash verification) - - **Symptoms**: Nodes connected but no block production **Checks**: @@ -2232,9 +2204,7 @@ curl http://localhost:8545 \ - Wait for more validators to come online - Verify validator keys are correct - Check for network partitions - - **Symptoms**: Nodes can't find peers **Checks**: @@ -2246,8 +2216,6 @@ curl http://localhost:8545 \ - Update persistent_peers with correct addresses - Open P2P port in firewall - Check network connectivity - - @@ -2260,7 +2228,7 @@ curl http://localhost:8545 \ **1. Prometheus + Grafana** Enable metrics in `config.toml`: -```toml +```toml expandable [instrumentation] prometheus = true prometheus_listen_addr = ":26660" @@ -2269,7 +2237,7 @@ prometheus_listen_addr = ":26660" **2. Tenderduty** (Validator monitoring) Install: -```bash +```bash expandable git clone https://github.com/blockpane/tenderduty cd tenderduty go install @@ -2303,7 +2271,7 @@ go install - High transaction rejection rate **Example Alert** (Prometheus): -```yaml +```yaml expandable - alert: ValidatorMissedBlocks expr: missed_blocks > 5 for: 5m @@ -2341,7 +2309,7 @@ go install ### Submitting a Parameter Change Proposal -```bash +```bash expandable # Create proposal JSON cat > proposal.json < -```bash +```bash expandable cat > upgrade-proposal.json < Create `app/upgrades/v0_5_0/upgrades.go`: -```go +```go expandable package v0_5_0 import ( @@ -2453,7 +2421,7 @@ func CreateUpgradeHandler( ``` Register in `app/app.go`: -```go +```go expandable import v0_5_0 "github.com/your-org/your-chain/app/upgrades/v0_5_0" app.UpgradeKeeper.SetUpgradeHandler( @@ -2470,7 +2438,7 @@ app.UpgradeKeeper.SetUpgradeHandler( 4. Chain resumes with new version **Binary Swap**: -```bash +```bash expandable # Stop old binary (automatic at upgrade height) # Replace binary cp yourchain-v0.5.0 $GOPATH/bin/yourchain @@ -2506,7 +2474,7 @@ Decide on: Before any initialization: -```bash +```bash expandable # 1. Rename binary mv evmd yourchain find . -type f -name "*.go" -exec sed -i '' 's/evmd/yourchain/g' {} \; @@ -2522,7 +2490,7 @@ make build -```bash +```bash expandable yourchain init mynode --chain-id yourchain-1 ``` @@ -2530,7 +2498,7 @@ yourchain init mynode --chain-id yourchain-1 Edit `~/.yourchain/config/genesis.json`: -```bash +```bash expandable GENESIS=~/.yourchain/config/genesis.json # Set denominations across all modules @@ -2549,7 +2517,7 @@ jq '.app_state.evm.params.evm_denom="atoken"' $GENESIS > tmp && mv tmp $GENESIS Edit `~/.yourchain/config/app.toml`: -```toml +```toml expandable [evm] chain-id = 262144 # Verify matches your code setting min-tip = 1000000000 @@ -2564,14 +2532,14 @@ minimum-gas-prices = "1000000000atoken" -```bash +```bash expandable yourchain genesis add-genesis-account validator1 1000000000000000000000atoken yourchain genesis add-genesis-account faucet 10000000000000000000000atoken ``` -```bash +```bash expandable yourchain genesis gentx validator1 \ 1000000000000000000000atoken \ --chain-id yourchain-1 \ @@ -2581,20 +2549,20 @@ yourchain genesis gentx validator1 \ If multi-validator network: -```bash +```bash expandable # Collect all gentx files yourchain genesis collect-gentxs ``` -```bash +```bash expandable yourchain genesis validate ``` -```bash +```bash expandable yourchain start ``` @@ -2817,7 +2785,7 @@ genesisModuleOrder := []string{ ### Commands Summary -```bash +```bash expandable # Build make build diff --git a/docs/evm/next/documentation/getting-started/build-a-chain/chain-customization-checklist.mdx b/docs/evm/next/documentation/getting-started/build-a-chain/chain-customization-checklist.mdx index 9c7f7dde..789ceafe 100644 --- a/docs/evm/next/documentation/getting-started/build-a-chain/chain-customization-checklist.mdx +++ b/docs/evm/next/documentation/getting-started/build-a-chain/chain-customization-checklist.mdx @@ -9,9 +9,7 @@ description: "Configure your chain step by step - complete with code references, These parameters must be set **before** running `evmd init`. They cannot be changed after genesis without a hard fork. - - **What This Does**: Renames your blockchain binary and updates all Go import paths to match your project. @@ -23,7 +21,7 @@ These parameters must be set **before** running `evmd init`. They cannot be chan **Commands**: -```bash +```bash expandable # 1. Rename directory mv evmd yourchain @@ -48,20 +46,18 @@ make build ``` **Verification**: -```bash +```bash expandable ./build/yourchain version ``` - - **What This Does**: Defines your chain's address format (e.g., `cosmos1...`, `evmos1...`, `yourchain1...`) **File**: `config/config.go:62` **Default**: -```go +```go expandable const ( Bech32Prefix = "cosmos" ) @@ -69,7 +65,7 @@ const ( **How to Change**: -```go +```go expandable const ( // Bech32Prefix defines the Bech32 prefix for your chain Bech32Prefix = "yourchain" @@ -92,16 +88,14 @@ const ( **Source**: [config/config.go:60-74](https://github.com/cosmos/evm/blob/main/config/config.go#L60-L74) - - **What This Does**: Sets the HD wallet derivation path for key generation **File**: `crypto/hd/hdpath.go:9` **Default**: -```go +```go expandable var ( // Bip44CoinType satisfies EIP84 Bip44CoinType uint32 = 60 // Ethereum compatibility @@ -114,7 +108,7 @@ var ( **How to Change**: -```go +```go expandable var ( // Bip44CoinType for your chain Bip44CoinType uint32 = 60 // or your registered coin type @@ -128,9 +122,7 @@ var ( **Source**: [crypto/hd/hdpath.go:7-13](https://github.com/cosmos/evm/blob/main/crypto/hd/hdpath.go#L7-L13) - - **What This Does**: Determines whether your native token uses 18 decimals (like ETH) or 6 decimals (like ATOM) @@ -182,7 +174,7 @@ Only required if using 6 decimals or other non-18 decimal precision **1. Update app.go** to include PreciseBank module **2. Configure extended_denom_options** in genesis: -```json +```json expandable { "app_state": { "evm": { @@ -197,9 +189,7 @@ Only required if using 6 decimals or other non-18 decimal precision } ``` - - **What This Does**: Sets the EIP-155 chain ID for Ethereum transaction replay protection @@ -210,7 +200,7 @@ Only required if using 6 decimals or other non-18 decimal precision **File**: `config/config.go:78` **Default Code**: -```go +```go expandable const ( // EVMChainID defines the EIP-155 replay-protection chain id EVMChainID = 262144 @@ -219,7 +209,7 @@ const ( **How to Change**: -```go +```go expandable const ( // EVMChainID defines the EIP-155 replay-protection chain id EVMChainID = 123456 // Your unique chain ID @@ -245,15 +235,13 @@ const ( - Must rebuild binary after changing **Verification After Init**: -```bash +```bash expandable grep 'evm-chain-id' ~/.yourchain/config/app.toml ``` **Source**: [config/config.go:77-78](https://github.com/cosmos/evm/blob/main/config/config.go#L77-L78) - - **What This Does**: Changes hardcoded default token denominations in the source code so that generated configuration files use your chosen token denomination instead of "aatom"/"atom". @@ -270,19 +258,19 @@ Three source files contain default denomination values that are used when genera **1. Configuration Template** (`/server/config/migration/v0.50-app.toml:11`) **Default**: -```toml +```toml expandable minimum-gas-prices = "0aatom" ``` **Change to** (example using "atoken"): -```toml +```toml expandable minimum-gas-prices = "0atoken" ``` **2. EVM Module Defaults** (`/x/vm/types/params.go:21-25`) **Default**: -```go +```go expandable var ( DefaultEVMDenom = "uatom" DefaultEVMExtendedDenom = "aatom" @@ -291,7 +279,7 @@ var ( ``` **Change to**: -```go +```go expandable var ( DefaultEVMDenom = "atoken" // Base EVM denomination DefaultEVMExtendedDenom = "atoken" // Extended denomination (if using PreciseBank) @@ -302,7 +290,7 @@ var ( **3. Example Chain Constants** (`/config/constants.go:5-8`) **Default**: -```go +```go expandable const ( ExampleChainDenom = "aatom" ExampleDisplayDenom = "atom" @@ -310,7 +298,7 @@ const ( ``` **Change to**: -```go +```go expandable const ( ExampleChainDenom = "atoken" // Your base denomination ExampleDisplayDenom = "token" // Your display denomination @@ -319,7 +307,7 @@ const ( **Quick Setup Commands**: -```bash +```bash expandable # 1. Edit configuration template sed -i '' 's/minimum-gas-prices = "0aatom"/minimum-gas-prices = "0atoken"/' \ server/config/migration/v0.50-app.toml @@ -341,7 +329,7 @@ make build **Verification After Build and Init**: -```bash +```bash expandable # Initialize node ./build/yourchain init testnode --chain-id mychain-1 --home /tmp/test-home @@ -371,31 +359,27 @@ For **6-decimal tokens** (Cosmos SDK standard): - [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 Run `evmd init --chain-id ` then edit `~/.evmd/config/genesis.json`: - ### Chain Identity - **What This Does**: Sets the unique string identifier for your blockchain in the Cosmos ecosystem **Format**: `{name}-{version}` (e.g., `mychain-1`, `testnet-3`) **Set During Init**: -```bash +```bash expandable yourchain init mynode --chain-id mychain-1 ``` **Or Modify After Init**: -```bash +```bash expandable jq '.chain_id = "mychain-1"' ~/.yourchain/config/genesis.json > tmp && mv tmp genesis.json ``` @@ -408,9 +392,7 @@ jq '.chain_id = "mychain-1"' ~/.yourchain/config/genesis.json > tmp && mv tmp ge **Notes**: Can be any string, but `{name}-{number}` format is canonical for IBC client upgrades - - **What This Does**: UTC timestamp when chain starts producing blocks @@ -419,7 +401,7 @@ jq '.chain_id = "mychain-1"' ~/.yourchain/config/genesis.json > tmp && mv tmp ge **Genesis Location**: Root level field `genesis_time` **Manual Configuration**: -```bash +```bash expandable jq '.genesis_time = "2024-12-01T00:00:00Z"' genesis.json > tmp && mv tmp genesis.json ``` @@ -435,11 +417,9 @@ jq '.genesis_time = "2024-12-01T00:00:00Z"' genesis.json > tmp && mv tmp genesis 3. Ensure all validators use identical genesis file 4. Validators start nodes and wait for genesis time - ### Token Configuration - **What This Does**: Defines your token's base denomination, decimal precision, and display properties @@ -447,7 +427,7 @@ jq '.genesis_time = "2024-12-01T00:00:00Z"' genesis.json > tmp && mv tmp genesis **For 18-Decimal Token** (Recommended): -```bash +```bash expandable jq '.app_state.bank.denom_metadata=[{ "description": "The native staking and gas token", "denom_units": [ @@ -473,7 +453,7 @@ jq '.app_state.bank.denom_metadata=[{ **For 6-Decimal Token**: -```bash +```bash expandable jq '.app_state.bank.denom_metadata=[{ "description": "The native staking and gas token", "denom_units": [ @@ -508,9 +488,7 @@ jq '.app_state.bank.denom_metadata=[{ - `app_state.mint.params.mint_denom` - `app_state.gov.params.min_deposit[0].denom` - - **What This Does**: Specifies which bank denomination is the native EVM gas token @@ -522,12 +500,12 @@ jq '.app_state.bank.denom_metadata=[{ **Configuration**: -```bash +```bash expandable jq '.app_state.evm.params.evm_denom = "atoken"' genesis.json > tmp && mv tmp genesis.json ``` **Example Genesis**: -```json +```json expandable { "app_state": { "evm": { @@ -543,9 +521,7 @@ jq '.app_state.evm.params.evm_denom = "atoken"' genesis.json > tmp && mv tmp gen **Source**: [x/vm/types/params.go:21](https://github.com/cosmos/evm/blob/main/x/vm/types/params.go#L21) - - **When Required**: Only for 6-decimal or other non-18-decimal chains @@ -555,14 +531,14 @@ jq '.app_state.evm.params.evm_denom = "atoken"' genesis.json > tmp && mv tmp gen **Configuration for 6-Decimal Chain**: -```bash +```bash expandable jq '.app_state.evm.params.extended_denom_options = { "extended_denom": "atoken" }' genesis.json > tmp && mv tmp genesis.json ``` **Example Genesis**: -```json +```json expandable { "app_state": { "evm": { @@ -588,11 +564,9 @@ jq '.app_state.evm.params.extended_denom_options = { **Source**: [x/vm/types/params.go:76](https://github.com/cosmos/evm/blob/main/x/vm/types/params.go#L76) - ### VM Module - **What This Does**: Enables precompiled contracts that provide access to Cosmos modules from EVM @@ -619,7 +593,7 @@ jq '.app_state.evm.params.extended_denom_options = { **Enable All Precompiles**: -```bash +```bash expandable jq '.app_state.evm.params.active_static_precompiles = [ "0x0000000000000000000000000000000000000100", "0x0000000000000000000000000000000000000400", @@ -636,7 +610,7 @@ jq '.app_state.evm.params.active_static_precompiles = [ **Enable Selective Precompiles** (example): -```bash +```bash expandable jq '.app_state.evm.params.active_static_precompiles = [ "0x0000000000000000000000000000000000000100", # P256 "0x0000000000000000000000000000000000000400", # Bech32 @@ -648,9 +622,7 @@ jq '.app_state.evm.params.active_static_precompiles = [ **Source**: [x/vm/types/precompiles.go:22-32](https://github.com/cosmos/evm/blob/main/x/vm/types/precompiles.go#L22-L32) - - **What This Does**: Deploys essential smart contracts at genesis to standard addresses @@ -681,13 +653,11 @@ Genesis is automatically populated during `evmd init`. These contracts are hardc **No manual configuration needed** unless you want to disable specific contracts. **Verification After Init**: -```bash +```bash expandable jq '.app_state.evm.preinstalls' ~/.yourchain/config/genesis.json ``` - - **What This Does**: Sets permissions for deploying and calling smart contracts @@ -702,7 +672,7 @@ jq '.app_state.evm.preinstalls' ~/.yourchain/config/genesis.json **Default: Fully Permissionless** -```json +```json expandable { "access_control": { "create": { @@ -719,7 +689,7 @@ jq '.app_state.evm.preinstalls' ~/.yourchain/config/genesis.json **Example: Permissioned Deployment** (only specific addresses can deploy): -```bash +```bash expandable jq '.app_state.evm.params.access_control = { "create": { "access_type": 2, @@ -737,7 +707,7 @@ jq '.app_state.evm.params.access_control = { **Example: Restricted Deployment** (block specific addresses): -```bash +```bash expandable jq '.app_state.evm.params.access_control.create = { "access_type": 1, "access_control_list": [ @@ -753,9 +723,7 @@ jq '.app_state.evm.params.access_control.create = { **Source**: [x/vm/types/params.go:160-165](https://github.com/cosmos/evm/blob/main/x/vm/types/params.go#L160-L165) - - **What This Does**: Enables additional Ethereum Improvement Proposals not in default config @@ -769,12 +737,12 @@ jq '.app_state.evm.params.access_control.create = { **Example**: -```bash +```bash expandable jq '.app_state.evm.params.extra_eips = [1153, 3855]' genesis.json > tmp && mv tmp genesis.json ``` **Example Genesis**: -```json +```json expandable { "app_state": { "evm": { @@ -792,9 +760,7 @@ jq '.app_state.evm.params.extra_eips = [1153, 3855]' genesis.json > tmp && mv tm **Source**: [x/vm/types/params.go:33](https://github.com/cosmos/evm/blob/main/x/vm/types/params.go#L33) - - **What This Does**: Controls how far back historical state queries can go @@ -806,7 +772,7 @@ jq '.app_state.evm.params.extra_eips = [1153, 3855]' genesis.json > tmp && mv tm **Configuration**: -```bash +```bash expandable jq '.app_state.evm.params.history_serve_window = 8192' genesis.json > tmp && mv tmp genesis.json ``` @@ -824,11 +790,9 @@ jq '.app_state.evm.params.history_serve_window = 8192' genesis.json > tmp && mv **Source**: [x/vm/types/params.go:50](https://github.com/cosmos/evm/blob/main/x/vm/types/params.go#L50) - ### ERC20 Module - **What This Does**: Creates ERC20 representation of your native token for EVM compatibility @@ -838,7 +802,7 @@ jq '.app_state.evm.params.history_serve_window = 8192' genesis.json > tmp && mv **Configuration**: -```bash +```bash expandable jq '.app_state.erc20.token_pairs = [{ "erc20_address": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE", "denom": "atoken", @@ -848,7 +812,7 @@ jq '.app_state.erc20.token_pairs = [{ ``` **Example Genesis**: -```json +```json expandable { "app_state": { "erc20": { @@ -873,9 +837,7 @@ jq '.app_state.erc20.token_pairs = [{ **Result**: Your native token becomes accessible as ERC20 from Solidity contracts - - **What This Does**: Registers the native token's precompile address @@ -883,12 +845,12 @@ jq '.app_state.erc20.token_pairs = [{ **Configuration**: -```bash +```bash expandable jq '.app_state.erc20.native_precompiles = ["0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE"]' genesis.json > tmp && mv tmp genesis.json ``` **Example Genesis**: -```json +```json expandable { "app_state": { "erc20": { @@ -900,9 +862,7 @@ jq '.app_state.erc20.native_precompiles = ["0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeee **Notes**: Must match the `erc20_address` in `token_pairs` - - **What This Does**: Controls whether anyone can register new token pairs or only governance @@ -914,13 +874,13 @@ jq '.app_state.erc20.native_precompiles = ["0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeee **Permissionless (Default)**: -```bash +```bash expandable jq '.app_state.erc20.params.permissionless_registration = true' genesis.json > tmp && mv tmp genesis.json ``` **Permissioned (Governance Only)**: -```bash +```bash expandable jq '.app_state.erc20.params.permissionless_registration = false' genesis.json > tmp && mv tmp genesis.json ``` @@ -930,11 +890,9 @@ jq '.app_state.erc20.params.permissionless_registration = false' genesis.json > **Source**: [x/erc20/types/params.go:27](https://github.com/cosmos/evm/blob/main/x/erc20/types/params.go#L27) - ### Fee Market Module - **What This Does**: Configures Ethereum's EIP-1559 dynamic fee market mechanism @@ -942,7 +900,7 @@ jq '.app_state.erc20.params.permissionless_registration = false' genesis.json > **Complete Configuration**: -```bash +```bash expandable jq '.app_state.feemarket.params = { "no_base_fee": false, "base_fee": "1000000000", @@ -997,7 +955,7 @@ jq '.app_state.feemarket.params = { **Configuration Examples**: **Standard EIP-1559 (Recommended)**: -```json +```json expandable { "no_base_fee": false, "base_fee": "1000000000", @@ -1009,7 +967,7 @@ jq '.app_state.feemarket.params = { ``` **Fixed Fee (Disabled EIP-1559)**: -```json +```json expandable { "no_base_fee": true, "min_gas_price": "1000000000" @@ -1017,7 +975,7 @@ jq '.app_state.feemarket.params = { ``` **Low-Fee L2**: -```json +```json expandable { "no_base_fee": false, "base_fee": "100000000", @@ -1027,17 +985,15 @@ jq '.app_state.feemarket.params = { **Source**: [x/feemarket/types/params.go:13-21](https://github.com/cosmos/evm/blob/main/x/feemarket/types/params.go#L13-L21) - ### Standard Cosmos Modules - **Genesis Path**: `app_state.staking.params` **Set Bond Denom**: -```bash +```bash expandable jq '.app_state.staking.params.bond_denom = "atoken"' genesis.json > tmp && mv tmp genesis.json ``` @@ -1046,7 +1002,7 @@ jq '.app_state.staking.params.bond_denom = "atoken"' genesis.json > tmp && mv tm The unbonding period is how long tokens remain locked after a user initiates unstaking. During this time, validators remain accountable and can be slashed for misbehavior that occurred while bonded. **Set Custom Unbonding Time**: -```bash +```bash expandable jq '.app_state.staking.params.unbonding_time = "1814400s"' genesis.json > tmp && mv tmp genesis.json ``` @@ -1059,13 +1015,13 @@ jq '.app_state.staking.params.unbonding_time = "1814400s"' genesis.json > tmp && **Set Max Validators**: -```bash +```bash expandable jq '.app_state.staking.params.max_validators = 100' genesis.json > tmp && mv tmp genesis.json ``` **Complete Configuration**: -```json +```json expandable { "app_state": { "staking": { @@ -1116,9 +1072,7 @@ jq '.app_state.staking.params.max_validators = 100' genesis.json > tmp && mv tmp - Default: `"0.000000000000000000"` (0%) - Example: `"0.050000000000000000"` = 5% minimum commission - - **What This Does**: Configures penalties for validator misbehavior including downtime and double-signing @@ -1126,7 +1080,7 @@ jq '.app_state.staking.params.max_validators = 100' genesis.json > tmp && mv tmp **Complete Configuration**: -```json +```json expandable { "app_state": { "slashing": { @@ -1144,7 +1098,7 @@ jq '.app_state.staking.params.max_validators = 100' genesis.json > tmp && mv tmp **Set Slashing Parameters**: -```bash +```bash expandable # Downtime detection window jq '.app_state.slashing.params.signed_blocks_window = "10000"' genesis.json > tmp && mv tmp genesis.json @@ -1221,15 +1175,13 @@ jq '.app_state.slashing.params.slash_fraction_downtime = "0.010000000000000000"' - Tokens remain slashable during entire `unbonding_time` period - Validators remain accountable for misbehavior that occurred while bonded - - **Genesis Path**: `app_state.gov.params` **Set Min Deposit Denom**: -```bash +```bash expandable jq '.app_state.gov.params.min_deposit[0].denom = "atoken"' genesis.json > tmp && mv tmp genesis.json ``` @@ -1239,7 +1191,7 @@ jq '.app_state.gov.params.min_deposit[0].denom = "atoken"' genesis.json > tmp && The `expedited_voting_period` must be strictly less than `voting_period`. If you change `voting_period`, also adjust `expedited_voting_period` accordingly. -```bash +```bash expandable # Set voting period jq '.app_state.gov.params.voting_period = "172800s"' genesis.json > tmp && mv tmp genesis.json @@ -1258,7 +1210,7 @@ jq '.app_state.gov.params.expedited_voting_period = "86400s"' genesis.json > tmp **Complete Configuration**: -```json +```json expandable { "app_state": { "gov": { @@ -1290,21 +1242,19 @@ jq '.app_state.gov.params.expedited_voting_period = "86400s"' genesis.json > tmp - `threshold`: Minimum yes votes (`"0.5"` = 50%) - `veto_threshold`: Veto threshold (`"0.334"` = 33.4%) - - **Genesis Path**: `app_state.mint.params` **Set Mint Denom**: -```bash +```bash expandable jq '.app_state.mint.params.mint_denom = "atoken"' genesis.json > tmp && mv tmp genesis.json ``` **Complete Configuration**: -```json +```json expandable { "app_state": { "mint": { @@ -1328,15 +1278,13 @@ jq '.app_state.mint.params.mint_denom = "atoken"' genesis.json > tmp && mv tmp g - `goal_bonded`: Target bonded token ratio (67%) - `blocks_per_year`: Expected blocks per year - - **Genesis Path**: `app_state.distribution.params` **Configuration**: -```json +```json expandable { "app_state": { "distribution": { @@ -1357,23 +1305,21 @@ jq '.app_state.mint.params.mint_denom = "atoken"' genesis.json > tmp && mv tmp g - `bonus_proposer_reward`: Bonus reward for block proposer (4%) - `withdraw_addr_enabled`: Allow setting custom withdraw address - ### Initial State - **What This Does**: Creates accounts with initial token balances at genesis **Command**: -```bash +```bash expandable yourchain genesis add-genesis-account ``` **Examples**: -```bash +```bash expandable # Using address yourchain genesis add-genesis-account \ cosmos1abc123... \ @@ -1393,7 +1339,7 @@ yourchain genesis add-genesis-account faucet 10000000000000000000000atoken **Bulk Add** (using bulk command): -```bash +```bash expandable # Create accounts file cat > accounts.json < - **What This Does**: Gathers validator self-delegation transactions to include in genesis @@ -1427,7 +1371,7 @@ jq '.app_state.bank.balances' ~/.yourchain/config/genesis.json **1. Each Validator Creates Their Gentx**: -```bash +```bash expandable # On validator node yourchain genesis gentx validator1 \ 1000000000000000000000atoken \ @@ -1444,14 +1388,14 @@ yourchain genesis gentx validator1 \ **2. Validator Shares Gentx File**: -```bash +```bash expandable # Validator sends this file to coordinator cat ~/.yourchain/config/gentx/gentx-*.json ``` **3. Coordinator Collects All Gentxs**: -```bash +```bash expandable # Coordinator receives all gentx files mkdir -p ~/.yourchain/config/gentx/ # Copy all received gentx files to this directory @@ -1462,20 +1406,18 @@ yourchain genesis collect-gentxs **4. Verify Genesis**: -```bash +```bash expandable yourchain genesis validate jq '.app_state.genutil.gen_txs' ~/.yourchain/config/genesis.json ``` **Result**: Genesis file now contains all validator self-delegations - - **Command**: -```bash +```bash expandable yourchain genesis validate ``` @@ -1509,7 +1451,7 @@ Fix: Correct the parameter value **Full Verification Checklist**: -```bash +```bash expandable # 1. Validate structure yourchain genesis validate @@ -1530,23 +1472,19 @@ jq '.app_state.bank.balances | map(.coins[0].amount | tonumber) | add' genesis.j jq '.app_state.genutil.gen_txs | length' genesis.json ``` - - ## Runtime Configuration Edit `~/.yourchain/config/app.toml`: - - **Section**: `[json-rpc]` **Full Configuration**: -```toml +```toml expandable [json-rpc] # Enable JSON-RPC server enable = true @@ -1610,15 +1548,13 @@ batch-response-max-size = 0 - Enable rate limiting - Use `allow-unprotected-txs = false` in production - - **Section**: `[evm]` **Configuration**: -```toml +```toml expandable [evm] # EVM chain ID (set during init from config/config.go - DO NOT MODIFY) evm-chain-id = 262144 @@ -1661,9 +1597,7 @@ min-tip = 0 **Notes**: The `evm-chain-id` value in app.toml is for reference only. It was set during `evmd init` from your code. To change it, you must modify `config/config.go:78` and rebuild the binary before running init. - - **What This Does**: Controls transaction pool behavior including price limits, queue sizes, and lifetime. @@ -1675,7 +1609,7 @@ min-tip = 0 **Full Configuration**: -```toml +```toml expandable [evm.mempool] # PriceLimit is the minimum gas price to enforce for acceptance into the pool (in wei) price-limit = 1 @@ -1740,7 +1674,7 @@ lifetime = "3h0m0s" **Tuning Recommendations**: **High-throughput chain**: -```toml +```toml expandable global-slots = 10240 global-queue = 2048 price-limit = 100000000 @@ -1748,7 +1682,7 @@ lifetime = "6h0m0s" ``` **Low-resource node**: -```toml +```toml expandable global-slots = 2048 global-queue = 512 lifetime = "1h0m0s" @@ -1757,13 +1691,11 @@ account-slots = 8 **Source**: [server/config/config.go:158-187](https://github.com/cosmos/evm/blob/v0.5.0-rc.1/server/config/config.go#L158-L187) - - **Configuration**: -```toml +```toml expandable minimum-gas-prices = "1000000000atoken" ``` @@ -1785,15 +1717,13 @@ minimum-gas-prices = "1000000000atoken" **Recommendation**: Set to at least the expected minimum to prevent mempool spam - - **File**: `~/.yourchain/config/config.toml` **Configuration**: -```toml +```toml expandable # Comma separated list of nodes to keep persistent connections to persistent_peers = "node_id@ip:port,node_id2@ip:port" ``` @@ -1802,7 +1732,7 @@ persistent_peers = "node_id@ip:port,node_id2@ip:port" **1. Get Node ID** from each validator: -```bash +```bash expandable yourchain comet show-node-id ``` @@ -1815,27 +1745,25 @@ Output: `7c90e16cca334eb7259754f964918d879ca54996` **3. Update config.toml**: -```bash +```bash expandable # Edit ~/.yourchain/config/config.toml persistent_peers = "7c90e16cca334eb7259754f964918d879ca54996@192.168.1.100:26656,abc123def456...@192.168.1.101:26656" ``` **Example with Multiple Peers**: -```toml +```toml expandable persistent_peers = "7c90e16c@192.168.1.100:26656,abc123de@192.168.1.101:26656,def456ab@192.168.1.102:26656" ``` **Verification**: -```bash +```bash expandable # Check connected peers curl localhost:26657/net_info | jq '.result.peers' ``` - - **What This Does**: Sets the chain-id in client configuration for CLI operations and node startup validation. @@ -1843,12 +1771,12 @@ curl localhost:26657/net_info | jq '.result.peers' **Command**: -```bash +```bash expandable yourchain config set client chain-id --home ``` **Example**: -```bash +```bash expandable evmd config set client chain-id mychain-1 --home ~/.evmd ``` @@ -1862,7 +1790,7 @@ error during handshake: error on replay: invalid chain-id on InitChain **Verification**: -```bash +```bash expandable # Verify chain-id matches genesis.json jq '.chain_id' ~/.yourchain/config/genesis.json # Output: "mychain-1" @@ -1872,21 +1800,17 @@ grep 'chain-id' ~/.yourchain/config/client.toml # Output: chain-id = "mychain-1" ``` - - ## Network Launch - - **Methods**: **1. IPFS** (Recommended for large networks): -```bash +```bash expandable # Coordinator uploads ipfs add ~/.yourchain/config/genesis.json # Returns: QmXyz123... @@ -1897,7 +1821,7 @@ ipfs get QmXyz123... -o ~/.yourchain/config/genesis.json **2. GitHub Release**: -```bash +```bash expandable # Coordinator creates release with genesis.json gh release create v1.0.0 ~/.yourchain/config/genesis.json @@ -1913,13 +1837,11 @@ wget https://github.com/yourorg/yourchain/releases/download/v1.0.0/genesis.json **Security**: Use secure, verified channels to prevent tampering - - **Command** (each validator runs): -```bash +```bash expandable jq -S -c . ~/.yourchain/config/genesis.json | shasum -a 256 ``` @@ -1932,7 +1854,7 @@ a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6 - **1. Coordinator Generates Canonical Hash**: -```bash +```bash expandable jq -S -c . ~/.yourchain/config/genesis.json | shasum -a 256 > genesis_hash.txt cat genesis_hash.txt ``` @@ -1944,7 +1866,7 @@ cat genesis_hash.txt **3. Each Validator Verifies**: -```bash +```bash expandable # Generate local hash jq -S -c . ~/.yourchain/config/genesis.json | shasum -a 256 @@ -1958,15 +1880,13 @@ jq -S -c . ~/.yourchain/config/genesis.json | shasum -a 256 **Notes**: Even one character difference means different genesis state. All validators must have identical files. - - **Each Validator Shares**: **1. Get Node ID**: -```bash +```bash expandable yourchain comet show-node-id ``` @@ -1982,7 +1902,7 @@ Output: `7c90e16cca334eb7259754f964918d879ca54996` Each validator edits `~/.yourchain/config/config.toml`: -```toml +```toml expandable persistent_peers = "7c90e16c@192.168.1.100:26656,abc123de@192.168.1.101:26656,def456ab@192.168.1.102:26656" ``` @@ -1994,9 +1914,7 @@ persistent_peers = "7c90e16c@192.168.1.100:26656,abc123de@192.168.1.101:26656,de | Validator 2 | abc123de... | 192.168.1.101 | abc123de@192.168.1.101:26656 | | Validator 3 | def456ab... | 192.168.1.102 | def456ab@192.168.1.102:26656 | - - **What This Does**: Sets the exact moment when the chain starts producing blocks @@ -2006,7 +1924,7 @@ persistent_peers = "7c90e16c@192.168.1.100:26656,abc123de@192.168.1.101:26656,de **1. Choose Future Time** (give validators time to prepare): -```bash +```bash expandable # Example: Launch in 24 hours # If now is: 2024-10-14T12:00:00Z # Set genesis_time to: 2024-10-15T12:00:00Z @@ -2014,7 +1932,7 @@ persistent_peers = "7c90e16c@192.168.1.100:26656,abc123de@192.168.1.101:26656,de **2. Update Genesis** (coordinator): -```bash +```bash expandable jq '.genesis_time = "2024-10-15T12:00:00Z"' genesis.json > tmp && mv tmp genesis.json ``` @@ -2022,13 +1940,13 @@ jq '.genesis_time = "2024-10-15T12:00:00Z"' genesis.json > tmp && mv tmp genesis **4. All Validators Verify**: -```bash +```bash expandable jq '.genesis_time' ~/.yourchain/config/genesis.json ``` **5. Validators Start Nodes Before Genesis Time**: -```bash +```bash expandable # Start 30 minutes before genesis_time yourchain start ``` @@ -2046,19 +1964,17 @@ Time until genesis: 29m 45s - Start nodes before genesis_time - Chain waits until genesis_time to begin - - **Start Command**: -```bash +```bash expandable yourchain start ``` **Monitor Logs**: -```bash +```bash expandable yourchain start 2>&1 | grep "finalizing commit" ``` @@ -2073,33 +1989,33 @@ INF finalizing commit of block hash=GHI789... height=3 **1. Check Block Height Increasing**: -```bash +```bash expandable curl localhost:26657/status | jq '.result.sync_info.latest_block_height' ``` **2. Check Validator Participation**: -```bash +```bash expandable curl localhost:26657/validators | jq '.result.validators | length' ``` **3. Confirm 2/3+ Voting Power**: -```bash +```bash expandable curl localhost:26657/validators | \ jq '[.result.validators[].voting_power | tonumber] | add' ``` **4. Check Network Health**: -```bash +```bash expandable curl localhost:26657/health # Should return: {} ``` **5. Test RPC Access**: -```bash +```bash expandable curl http://localhost:8545 \ -X POST \ -H "Content-Type: application/json" \ @@ -2118,9 +2034,7 @@ curl http://localhost:8545 \ - Check network connectivity - Ensure >= 2/3 voting power online - - @@ -2130,7 +2044,7 @@ curl http://localhost:8545 \ ### Commands Summary -```bash +```bash expandable # Build make build diff --git a/docs/evm/next/documentation/getting-started/build-a-chain/configuration-parameters.mdx b/docs/evm/next/documentation/getting-started/build-a-chain/configuration-parameters.mdx index 9c8071bc..3a646c7a 100644 --- a/docs/evm/next/documentation/getting-started/build-a-chain/configuration-parameters.mdx +++ b/docs/evm/next/documentation/getting-started/build-a-chain/configuration-parameters.mdx @@ -37,14 +37,14 @@ Let's configure each of these for your custom chain. -```bash +```bash expandable cd /path/to/cosmos-evm mv evmd yourchain ``` -```bash +```bash expandable # Update all references in Go files find . -type f -name "*.go" -exec sed -i 's/evmd/yourchain/g' {} \; ``` @@ -52,7 +52,7 @@ find . -type f -name "*.go" -exec sed -i 's/evmd/yourchain/g' {} \; Edit the module path in `go.mod`: -```go +```go expandable module github.com/your-org/your-chain // Update import paths that reference evmd @@ -70,7 +70,7 @@ install: -```bash +```bash expandable go mod tidy make install @@ -96,7 +96,7 @@ After renaming, your binary will be `yourchain` instead of `evmd`. All CLI comma Set during chain initialization: -```bash +```bash expandable yourchain init mynode --chain-id mychain-1 ``` @@ -126,13 +126,13 @@ The EVM chain ID **cannot** be changed after genesis without breaking transactio Configure it in `app.toml`: -```toml +```toml expandable [evm] chain-id = 262144 ``` Or via CLI flag when starting the chain: -```bash +```bash expandable yourchain start --evm.chain-id 262144 ``` @@ -140,30 +140,22 @@ yourchain start --evm.chain-id 262144 **Choose any integer that isn't already taken on [chainlist.org](https://chainlist.org)** - - **Avoid these**: - `1` - Ethereum Mainnet - `137` - Polygon - `56` - BNB Chain - Check [chainlist.org](https://chainlist.org) for all registered chains - - **For local development and testnets**: - Use `262144` (evmd default) - Or any unique high number - No registration needed - - **For mainnet launches**: - Choose a unique integer not in use - Register at [chainlist.org](https://chainlist.org) - Verify no conflicts - Document publicly - - @@ -177,7 +169,7 @@ yourchain start --evm.chain-id 262144 Enable additional EIPs in genesis: -```json +```json expandable { "app_state": { "vm": { @@ -199,7 +191,7 @@ The `extra_eips` parameter allows enabling standard Ethereum EIPs that aren't in **Most chains should use the default empty configuration**: -```json +```json expandable { "extra_eips": [] } @@ -212,7 +204,7 @@ The default EVM configuration includes all commonly-used Ethereum features up th **Enable specific EIPs if your chain requires them**: For example, to enable additional EIP-1153 (transient storage): -```json +```json expandable { "extra_eips": [1153] } @@ -240,7 +232,7 @@ Only add EIPs if you have a specific technical requirement for functionality not Token pairs are configured in genesis under the `erc20` module: -```json +```json expandable { "app_state": { "erc20": { @@ -291,7 +283,7 @@ Token configuration involves three components: **Direct EVM Compatibility - No Extra Modules Needed** -```json +```json expandable { "app_state": { "bank": { @@ -336,7 +328,7 @@ Token configuration involves three components: **Requires PreciseBank Module** -```json +```json expandable { "app_state": { "bank": { @@ -384,7 +376,7 @@ When using non-18 decimal tokens, you **must** add the precisebank module and co For chains using other decimal precisions (e.g., 8 decimals for Bitcoin compatibility): -```json +```json expandable { "bank": { "denom_metadata": [{ @@ -430,7 +422,7 @@ Requires precisebank module with custom conversion factor. The denomination is set in multiple places that must be consistent: -```bash +```bash expandable # After initializing your chain GENESIS=~/.yourchain/config/genesis.json @@ -477,7 +469,7 @@ EVM permissions are set in genesis under `vm.params.access_control`: -```json +```json expandable { "app_state": { "vm": { @@ -502,7 +494,7 @@ EVM permissions are set in genesis under `vm.params.access_control`: -```json +```json expandable { "access_control": { "create": { @@ -524,7 +516,7 @@ EVM permissions are set in genesis under `vm.params.access_control`: -```json +```json expandable { "access_control": { "create": { @@ -545,7 +537,7 @@ EVM permissions are set in genesis under `vm.params.access_control`: -```json +```json expandable { "access_control": { "create": { @@ -580,7 +572,7 @@ EVM permissions are set in genesis under `vm.params.access_control`: Access control can be changed through governance proposals: -```bash +```bash expandable # Example: Enable permissionless deployment via governance yourchain tx gov submit-proposal param-change proposal.json \ --from validator \ @@ -614,7 +606,7 @@ The fee market module implements EIP-1559 dynamic pricing: -```json +```json expandable { "app_state": { "feemarket": { @@ -635,7 +627,7 @@ The fee market module implements EIP-1559 dynamic pricing: -```json +```json expandable { "feemarket": { "params": { @@ -690,7 +682,7 @@ For complete precompile documentation including Solidity interfaces and usage ex -```json +```json expandable { "app_state": { "vm": { @@ -716,7 +708,7 @@ For complete precompile documentation including Solidity interfaces and usage ex -```json +```json expandable { "active_static_precompiles": [ "0x0000000000000000000000000000000000000100", // P256 @@ -731,7 +723,7 @@ For complete precompile documentation including Solidity interfaces and usage ex -```json +```json expandable { "active_static_precompiles": [] } @@ -743,7 +735,7 @@ For complete precompile documentation including Solidity interfaces and usage ex Set defaults in your chain's genesis configuration: -```go +```go expandable // yourchain/genesis.go func NewDefaultVMGenesisState() *vmtypes.GenesisState { evmGenState := vmtypes.DefaultGenesisState() @@ -765,7 +757,7 @@ func NewDefaultVMGenesisState() *vmtypes.GenesisState { Precompiles can be enabled or disabled through governance: -```bash +```bash expandable # Propose adding a precompile yourchain tx gov submit-proposal param-change proposal.json \ --from validator @@ -788,7 +780,7 @@ Decide on: -```bash +```bash expandable # Rename binary mv evmd yourchain @@ -801,7 +793,7 @@ find . -type f -name "*.go" -exec sed -i 's/evmd/yourchain/g' {} \; -```bash +```bash expandable yourchain init mynode --chain-id yourchain-1 ``` @@ -809,7 +801,7 @@ yourchain init mynode --chain-id yourchain-1 Edit `~/.yourchain/config/genesis.json`: -```bash +```bash expandable GENESIS=~/.yourchain/config/genesis.json # Set denominations @@ -825,7 +817,7 @@ jq '.app_state.vm.params.evm_denom="atoken"' $GENESIS > tmp && mv tmp $GENESIS Edit `~/.yourchain/config/app.toml`: -```toml +```toml expandable [evm] chain-id = 262144 # Set EVM chain ID min-tip = 1000000000 @@ -837,7 +829,7 @@ address = "0.0.0.0:8545" -```bash +```bash expandable yourchain start ``` @@ -868,8 +860,6 @@ For production: The `local_node.sh` script performs all the configuration steps automatically. Here's what it does: - - The script modifies `genesis.json` to configure: - **Cosmos Chain ID**: Sets a development chain ID @@ -882,12 +872,10 @@ The script modifies `genesis.json` to configure: View the genesis configuration logic in `local_node.sh` to see exactly how evmd modifies genesis parameters for local development. - - The script configures `app.toml` with development-friendly settings: -```toml +```toml expandable [evm] chain-id = 262144 tracer = "json" # Enable EVM tracing for debugging @@ -903,9 +891,7 @@ enable-indexer = true # Enable transaction indexing ``` These settings are optimized for local development and should be adjusted for production. - - The `local_node.sh` script accepts flags that control configuration: - **`-y`**: Overwrites previous database (fresh genesis) @@ -914,16 +900,14 @@ The `local_node.sh` script accepts flags that control configuration: - **`--remote-debugging`**: Builds with debug symbols Example usage: -```bash +```bash expandable # Fresh start with all default configurations ./local_node.sh -y # Resume from previous state ./local_node.sh -n ``` - - To use `local_node.sh` as a template for your chain: 1. **Copy the script**: `cp local_node.sh my_chain_setup.sh` @@ -933,8 +917,6 @@ To use `local_node.sh` as a template for your chain: 5. **Add custom logic**: Include any chain-specific setup The script serves as a complete example of the configuration workflow described in this guide. - - **Production Considerations**: The `local_node.sh` configuration is optimized for local development. For testnets and mainnets: diff --git a/docs/evm/next/documentation/getting-started/build-a-chain/configuration-reference.mdx b/docs/evm/next/documentation/getting-started/build-a-chain/configuration-reference.mdx index e0e6c6d5..41583ab6 100644 --- a/docs/evm/next/documentation/getting-started/build-a-chain/configuration-reference.mdx +++ b/docs/evm/next/documentation/getting-started/build-a-chain/configuration-reference.mdx @@ -17,8 +17,8 @@ This reference provides quick access to common commands, configuration examples, ### Chain Initialization - -```bash + +```bash expandable # Initialize chain yourchain init --chain-id @@ -31,14 +31,13 @@ yourchain comet show-node-id # Show validator info yourchain comet show-validator ``` - ### Genesis Account Management - -```bash + +```bash expandable # Add genesis account yourchain genesis add-genesis-account
@@ -52,14 +51,13 @@ yourchain genesis add-genesis-account \ yourchain genesis add-genesis-account validator1 1000000000000000000000atoken # 1000 tokens yourchain genesis add-genesis-account faucet 10000000000000000000000atoken # 10000 tokens ``` - ### Validator Genesis Transactions - -```bash + +```bash expandable # Create gentx yourchain genesis gentx \ --chain-id \ @@ -76,14 +74,13 @@ yourchain genesis collect-gentxs # Validate genesis yourchain genesis validate ``` - ### Genesis File Manipulation - -```bash + +```bash expandable # Set value in genesis jq '.path.to.param = "value"' genesis.json > tmp && mv tmp genesis.json @@ -98,14 +95,13 @@ jq '.app_state.staking.params.bond_denom' genesis.json # Validate yourchain genesis validate ``` - ### Genesis Hash - -```bash + +```bash expandable # Generate hash jq -S -c . ~/.yourchain/config/genesis.json | shasum -a 256 @@ -115,14 +111,13 @@ jq -S -c . ~/.yourchain/config/genesis.json | shasum -a 256 > genesis_hash.txt # Verify cat genesis_hash.txt ``` - ### Client Configuration - -```bash + +```bash expandable # Set chain ID yourchain config set client chain-id mychain-1 --home ~/.yourchain @@ -132,14 +127,13 @@ yourchain config set client keyring-backend os --home ~/.yourchain # View current config yourchain config get client --home ~/.yourchain ``` - ### Node Operations - -```bash + +```bash expandable # Start node yourchain start @@ -158,14 +152,13 @@ curl localhost:8545 \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' ``` - ### Validator Operations - -```bash + +```bash expandable # Unjail validator yourchain tx slashing unjail \ --from validator \ @@ -185,7 +178,6 @@ yourchain query staking validator $(yourchain keys show validator --bech val -a) # Check signing info yourchain query slashing signing-info $(yourchain comet show-validator) ``` - @@ -194,7 +186,7 @@ yourchain query slashing signing-info $(yourchain comet show-validator) ### 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 | @@ -208,7 +200,7 @@ yourchain query slashing signing-info $(yourchain comet show-validator) ### 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 | @@ -223,7 +215,7 @@ yourchain query slashing signing-info $(yourchain comet show-validator) ### 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` | @@ -236,7 +228,7 @@ yourchain query slashing signing-info $(yourchain comet show-validator) ### 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` | @@ -255,7 +247,7 @@ yourchain query slashing signing-info $(yourchain comet show-validator) ### 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]` | @@ -271,7 +263,6 @@ yourchain query slashing signing-info $(yourchain comet show-validator) ### Complete 18-Decimal Chain Setup - ```bash init-18-decimal.sh #!/bin/bash @@ -366,13 +357,11 @@ prometheus = true prometheus_listen_addr = ":26660" ``` - ### Complete 6-Decimal Chain Setup - ```bash init-6-decimal.sh #!/bin/bash @@ -454,7 +443,6 @@ app.EVMKeeper = evmkeeper.NewKeeper( ) ``` - @@ -462,8 +450,6 @@ app.EVMKeeper = evmkeeper.NewKeeper( 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:** @@ -475,7 +461,7 @@ The script automates complete chain setup for local development: - Generates default genesis and config files **3. Genesis Modifications:** -```bash +```bash expandable # Token denomination jq '.app_state.staking.params.bond_denom="atest"' genesis.json jq '.app_state.evm.params.evm_denom="atest"' genesis.json @@ -494,7 +480,7 @@ sed -i 's/"voting_period": "172800s"/"voting_period": "30s"/' genesis.json ``` **4. Runtime Configuration:** -```bash +```bash expandable # Fast consensus (app.toml) sed -i 's/timeout_commit = "5s"/timeout_commit = "1s"/' config.toml @@ -511,14 +497,12 @@ sed -i 's/prometheus = false/prometheus = true/' config.toml - Supports `--additional-users` for extra accounts **View the script:** -```bash +```bash expandable cat local_node.sh | less ``` - - **Basic usage:** -```bash +```bash expandable # Fresh start (overwrites existing chain) ./local_node.sh -y @@ -545,18 +529,16 @@ cat local_node.sh | less - Contract testing - Integration tests - Learning chain configuration - - To use `local_node.sh` as a template: **1. Copy the script:** -```bash +```bash expandable cp local_node.sh my_chain_setup.sh ``` **2. Update binary name:** -```bash +```bash expandable # Change all instances of "evmd" to "yourchain" sed -i 's/evmd/yourchain/g' my_chain_setup.sh ``` @@ -576,8 +558,6 @@ sed -i 's/evmd/yourchain/g' my_chain_setup.sh - Fast governance - Test account mnemonics - Allow unprotected transactions - - **Source**: [local_node.sh](https://github.com/cosmos/evm/blob/main/local_node.sh) 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 ed40300e..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 @@ -12,7 +12,9 @@ The Cosmos EVM repository includes `evmd`, a fully functional blockchain that in 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** - Real working examples of integration approaches used by the core development team are readily available on Github +- **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. @@ -26,7 +28,6 @@ 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 @@ -35,9 +36,7 @@ Compiled into your binary and set before running `init`: - [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 @@ -49,7 +48,6 @@ Configured in `genesis.json` after initialization: - [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 - @@ -61,17 +59,13 @@ 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 - @@ -109,7 +103,7 @@ Deploy standard contracts at genesis for Create2, Multicall3, Permit2, and Safe The `cosmos/evm` repository includes `local_node.sh`, a development script that streamlines testing by launching a private local testnet with practical defaults: -```bash +```bash expandable ./local_node.sh -y # Fresh start with clean state ``` 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 index fbc5e2dd..3c030e5d 100644 --- 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 @@ -33,7 +33,7 @@ Runtime configuration is set in config files located at `~/.yourchain/config/`. ### 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 | @@ -54,7 +54,7 @@ Located at `~/.yourchain/config/app.toml`, this file controls application-level Edit `app.toml`: -```toml +```toml expandable # Minimum gas prices for the node to accept transactions minimum-gas-prices = "1000000000atoken" ``` @@ -74,17 +74,17 @@ minimum-gas-prices = "1000000000atoken" **For 18-decimal tokens:** -```toml +```toml expandable minimum-gas-prices = "1000000000atoken" # 1 gwei ``` **For 6-decimal tokens:** -```toml +```toml expandable minimum-gas-prices = "1000utoken" # 0.001 token ``` **Testing/Development:** -```toml +```toml expandable minimum-gas-prices = "0atoken" # Accept all (not for production) ``` @@ -105,7 +105,7 @@ minimum-gas-prices = "0atoken" # Accept all (not for production) -```toml +```toml expandable [json-rpc] # Enable JSON-RPC server enable = true @@ -156,7 +156,7 @@ enable-indexer = false **Available Namespaces:** | Namespace | Purpose | Production Use | -|--||-| +|---|---|---| | `eth` | Standard Ethereum RPC | ✅ Required | | `net` | Network information | ✅ Recommended | | `web3` | Web3 client version | ✅ Recommended | @@ -164,12 +164,12 @@ enable-indexer = false | `debug` | Debug/trace endpoints | ❌ Dev only | **Production configuration:** -```toml +```toml expandable api = ["eth", "net", "web3"] ``` **Development configuration:** -```toml +```toml expandable api = ["eth", "net", "web3", "txpool", "debug"] ``` @@ -179,7 +179,7 @@ api = ["eth", "net", "web3", "txpool", "debug"] **For public RPC nodes:** -```toml +```toml expandable # Bind to localhost only address = "127.0.0.1:8545" ws-address = "127.0.0.1:8546" @@ -220,7 +220,7 @@ block-range-cap = 10000 -```toml +```toml expandable [evm] # EVM chain ID (set during init from config/config.go) # DO NOT MODIFY - change in source code before init @@ -266,7 +266,7 @@ min-tip = 0 **Production:** -```toml +```toml expandable [evm] evm-chain-id = 123456 # Your chain ID tracer = "" # No tracing @@ -276,7 +276,7 @@ min-tip = 1000000000 # 1 gwei minimum ``` **Development:** -```toml +```toml expandable [evm] evm-chain-id = 262144 tracer = "json" # Enable debugging @@ -301,7 +301,7 @@ min-tip = 0 # No minimum -```toml +```toml expandable [evm.mempool] # Minimum gas price to accept into pool (in wei) price-limit = 1 @@ -364,7 +364,7 @@ lifetime = "3h0m0s" **High-throughput chain:** -```toml +```toml expandable [evm.mempool] price-limit = 100000000 # 0.1 gwei minimum global-slots = 10240 @@ -373,7 +373,7 @@ lifetime = "6h0m0s" ``` **Low-resource node:** -```toml +```toml expandable [evm.mempool] price-limit = 1 global-slots = 2048 @@ -383,7 +383,7 @@ lifetime = "1h0m0s" ``` **Strict spam prevention:** -```toml +```toml expandable [evm.mempool] price-limit = 1000000000 # 1 gwei minimum price-bump = 20 # 20% increase to replace @@ -414,21 +414,21 @@ Located at `~/.yourchain/config/config.toml`, this file controls CometBFT (conse Edit `config.toml`: -```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 +```toml expandable persistent_peers = "7c90e16cca334eb7@192.168.1.100:26656,abc123def456@192.168.1.101:26656" ``` **Each validator runs:** -```bash +```bash expandable yourchain comet show-node-id ``` @@ -445,7 +445,7 @@ yourchain comet show-node-id 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` | @@ -455,7 +455,7 @@ Create a coordination sheet for validators: **Verification:** -```bash +```bash expandable # Check connected peers curl localhost:26657/net_info | jq '.result.peers' ``` @@ -474,7 +474,7 @@ curl localhost:26657/net_info | jq '.result.peers' **Standard Cosmos values** (recommended for production): -```toml +```toml expandable [consensus] timeout_propose = "3s" timeout_propose_delta = "500ms" @@ -491,7 +491,7 @@ These are the defaults and work well for most networks. **Faster block times** for local development: -```toml +```toml expandable [consensus] timeout_propose = "2s" timeout_propose_delta = "200ms" @@ -533,7 +533,7 @@ timeout_commit = "1s" **Section**: `[instrumentation]` -```toml +```toml expandable [instrumentation] # Enable Prometheus metrics prometheus = true @@ -543,7 +543,7 @@ prometheus_listen_addr = ":26660" ``` **Access metrics:** -```bash +```bash expandable curl http://localhost:26660/metrics ``` @@ -568,18 +568,18 @@ error during handshake: error on replay: invalid chain-id on InitChain -```bash +```bash expandable yourchain config set client chain-id mychain-1 --home ~/.yourchain ``` **Or edit `client.toml` directly:** -```toml +```toml expandable chain-id = "mychain-1" ``` -```bash +```bash expandable # Verify chain-id matches genesis jq '.chain_id' ~/.yourchain/config/genesis.json # Output: "mychain-1" @@ -594,7 +594,7 @@ Both must match for the node to start successfully. **Other client settings:** -```toml +```toml expandable # Keyring backend keyring-backend = "os" @@ -655,7 +655,7 @@ After finalizing your genesis file, distribute it to all validators. **Recommended for public networks:** -```bash +```bash expandable # Coordinator creates release gh release create v1.0.0-genesis \ ~/.yourchain/config/genesis.json \ @@ -671,7 +671,7 @@ wget https://github.com/yourorg/yourchain/releases/download/v1.0.0-genesis/genes **Recommended for decentralization:** -```bash +```bash expandable # Coordinator uploads ipfs add ~/.yourchain/config/genesis.json # Returns: QmXyz123... @@ -684,7 +684,7 @@ ipfs get QmXyz123... -o ~/.yourchain/config/genesis.json **For private networks:** -```bash +```bash expandable # Coordinator shares via secure channel # Validators receive and copy to ~/.yourchain/config/genesis.json ``` @@ -703,7 +703,7 @@ ipfs get QmXyz123... -o ~/.yourchain/config/genesis.json **Each validator runs:** -```bash +```bash expandable jq -S -c . ~/.yourchain/config/genesis.json | shasum -a 256 ``` @@ -715,7 +715,7 @@ a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6 - **1. Coordinator publishes canonical hash:** -```bash +```bash expandable # Generate and save hash jq -S -c . ~/.yourchain/config/genesis.json | shasum -a 256 > genesis_hash.txt @@ -724,7 +724,7 @@ cat genesis_hash.txt ``` **2. All validators verify:** -```bash +```bash expandable # Each validator generates hash jq -S -c . ~/.yourchain/config/genesis.json | shasum -a 256 @@ -761,7 +761,7 @@ Validators need each other's peer information to connect. **Each validator provides:** -```bash +```bash expandable # Get node ID yourchain comet show-node-id # Output: 7c90e16cca334eb7259754f964918d879ca54996 @@ -781,7 +781,7 @@ yourchain comet show-node-id **Each validator updates `config.toml`:** -```bash +```bash expandable # Edit ~/.yourchain/config/config.toml # Add all other validators to persistent_peers @@ -795,7 +795,7 @@ persistent_peers = "7c90e16c@192.168.1.100:26656,abc123de@192.168.1.101:26656,de **After starting nodes, verify connectivity:** -```bash +```bash expandable # Check number of connected peers curl localhost:26657/net_info | jq '.result.n_peers' @@ -820,7 +820,7 @@ Set and coordinate the exact launch time across all validators. **Coordinator sets future genesis time:** -```bash +```bash expandable jq '.genesis_time = "2024-12-01T00:00:00Z"' \ ~/.yourchain/config/genesis.json > tmp && mv tmp ~/.yourchain/config/genesis.json ``` @@ -850,7 +850,7 @@ T+1h: Monitor network health **Validators start early:** -```bash +```bash expandable # Start node before genesis time yourchain start @@ -877,7 +877,7 @@ After configuration and coordination, start the nodes. -```bash +```bash expandable # Standard startup yourchain start @@ -893,7 +893,7 @@ nohup yourchain start > yourchain.log 2>&1 & -```bash +```bash expandable # Follow logs yourchain start 2>&1 | grep "finalizing commit" @@ -912,7 +912,7 @@ INF finalizing commit of block hash=GHI789... height=3 module=consensus **Create service file** at `/etc/systemd/system/yourchain.service`: -```ini +```ini expandable [Unit] Description=Cosmos EVM Chain After=network-online.target @@ -929,7 +929,7 @@ WantedBy=multi-user.target ``` **Enable and start:** -```bash +```bash expandable sudo systemctl enable yourchain sudo systemctl start yourchain @@ -952,7 +952,7 @@ After launch, verify the network is operating correctly. **Check block height increasing:** -```bash +```bash expandable # Via CometBFT RPC curl localhost:26657/status | jq '.result.sync_info.latest_block_height' @@ -969,7 +969,7 @@ curl http://localhost:8545 \ **Check validator set:** -```bash +```bash expandable # Number of validators curl localhost:26657/validators | jq '.result.validators | length' @@ -987,7 +987,7 @@ curl localhost:26657/validators | \ **Check peers:** -```bash +```bash expandable # Number of connected peers curl localhost:26657/net_info | jq '.result.n_peers' @@ -1001,13 +1001,13 @@ curl localhost:26657/net_info | jq '.result.peers[].node_info.moniker' **CometBFT health:** -```bash +```bash expandable curl localhost:26657/health # Returns: {} (empty object = healthy) ``` **Node status:** -```bash +```bash expandable curl localhost:26657/status | jq '.result' ``` @@ -1021,7 +1021,7 @@ curl localhost:26657/status | jq '.result' **Test JSON-RPC:** -```bash +```bash expandable # Check chain ID curl http://localhost:8545 \ -X POST \ @@ -1057,7 +1057,7 @@ After successful launch, maintain healthy network operation. **If validator gets jailed for downtime:** -```bash +```bash expandable # Check if jailed yourchain query staking validator $(yourchain keys show validator --bech val -a) @@ -1072,7 +1072,7 @@ yourchain tx slashing unjail \ **Update validator information:** -```bash +```bash expandable yourchain tx staking edit-validator \ --moniker "New Moniker" \ --website "https://example.com" \ @@ -1087,7 +1087,7 @@ yourchain tx staking edit-validator \ **Track validator performance:** -```bash +```bash expandable # Check signing info yourchain query slashing signing-info $(yourchain comet show-validator) @@ -1149,7 +1149,7 @@ yourchain query distribution validator-outstanding-rewards \ **What to backup:** -```bash +```bash expandable # Validator private key cp ~/.yourchain/config/priv_validator_key.json /secure/backup/ @@ -1171,7 +1171,7 @@ cp ~/.yourchain/config/genesis.json /secure/backup/ **If validator node fails:** 1. **Restore on new hardware:** -```bash +```bash expandable # Install binary # Copy priv_validator_key.json # Copy node_key.json @@ -1185,7 +1185,7 @@ cp ~/.yourchain/config/genesis.json /secure/backup/ - Copy data directory from backup 3. **Restart validator:** -```bash +```bash expandable yourchain start ``` @@ -1204,7 +1204,7 @@ yourchain start **Error: `invalid chain-id on InitChain`** **Solution:** -```bash +```bash expandable # Verify chain IDs match jq '.chain_id' ~/.yourchain/config/genesis.json grep 'chain-id' ~/.yourchain/config/client.toml @@ -1216,7 +1216,7 @@ yourchain config set client chain-id mychain-1 **Error: `genesis.json file not found`** **Solution:** -```bash +```bash expandable # Verify file exists ls ~/.yourchain/config/genesis.json @@ -1227,7 +1227,7 @@ ls ~/.yourchain/config/genesis.json **Check P2P configuration:** -```bash +```bash expandable # Verify persistent_peers in config.toml grep 'persistent_peers' ~/.yourchain/config/config.toml @@ -1239,7 +1239,7 @@ nc -zv 26656 ``` **Check firewall:** -```bash +```bash expandable # Port 26656 must be open for P2P sudo ufw status sudo ufw allow 26656 @@ -1263,7 +1263,7 @@ sudo ufw allow 26656 **Check validator participation:** -```bash +```bash expandable # Check number of online validators curl localhost:26657/validators | jq '.result.validators | length' From e53e367c47c5e551239bbfc15fafa4568519bc0e Mon Sep 17 00:00:00 2001 From: Cordt Date: Wed, 15 Oct 2025 22:45:31 -0600 Subject: [PATCH 5/6] fix some slop --- V0.5_COMMIT_ANALYSIS.md | 911 ----------- V0.5_INTEGRATION_PREP_FINDINGS.md | 1341 ----------------- .../pre-genesis-and-genesis-setup.mdx | 46 +- 3 files changed, 33 insertions(+), 2265 deletions(-) delete mode 100644 V0.5_COMMIT_ANALYSIS.md delete mode 100644 V0.5_INTEGRATION_PREP_FINDINGS.md diff --git a/V0.5_COMMIT_ANALYSIS.md b/V0.5_COMMIT_ANALYSIS.md deleted file mode 100644 index 932a1cb9..00000000 --- a/V0.5_COMMIT_ANALYSIS.md +++ /dev/null @@ -1,911 +0,0 @@ -# Cosmos EVM v0.5.0 - Detailed Commit Analysis - -**Version Range:** v0.4.1 → v0.5.0-rc.0 -**Total Commits:** 33 commits -**Date Range:** August 2025 -**Focus:** Major features, breaking changes, and significant implementations - ---- - -## Executive Summary - -v0.5.0 introduces significant architectural improvements focused on: - -- **Performance Optimization** - EVM instance removal in ante handlers -- **Developer Experience** - Simplified mempool configuration, decoupled precompile interfaces -- **EIP Support** - EIP-2935 (block hash storage), EIP-7212 support via eth_createAccessList -- **Security** - Re-use go-ethereum tx validation rules, improved tx processing hooks -- **Clean Architecture** - Global singleton removal, interface-based design - ---- - -## Major Features & Implementations - -### 1. EVM Instance Deletion in AnteHandler (#352) - -**Commit:** `befde4fa` -**Author:** LEE JUNSEO (bharvest) -**Impact:** 🔴 CRITICAL - Performance optimization - -#### What Changed - -- Removed stateDB allocation in ante handler -- Optimized `CanTransfer` ante handler by eliminating unnecessary EVM instance creation -- Reduced memory overhead per transaction - -#### Why It Matters - -**Before:** Every transaction created a full EVM instance during ante handling, even for non-EVM transactions. This was expensive and unnecessary. - -**After:** Ante handler validates transactions without creating EVM instance. EVM is only instantiated when actually executing contract calls. - -**Performance Impact:** - -- Reduces memory allocation per tx -- Faster ante handler execution -- Lower CPU usage on high-throughput chains - -#### Migration Impact - -- No API breaking changes -- Transparent performance improvement -- Internal optimization only - -**Files Modified:** - -```sh -ante/evm/07_can_transfer.go | 14 +------------- -``` - ---- - -### 2. Mempool Configuration Refactor (#496) - -**Commit:** `e01cc507` -**Author:** Vlad J -**Impact:** 🔴 BREAKING - API change - -#### What Changed - -Replaced pre-built pool injection with configuration-based approach: - -**Before (v0.4.x):** - -```go -type EVMMempoolConfig struct { - TxPool *txpool.TxPool // Pre-built pool - CosmosPool sdkmempool.ExtMempool // Pre-built pool - // ... -} -``` - -**After (v0.5.0):** - -```go -type EVMMempoolConfig struct { - LegacyPoolConfig *legacypool.Config // Config object - CosmosPoolConfig *sdkmempool.PriorityNonceMempoolConfig[math.Int] // Config object - // ... -} -``` - -#### Why It Matters - -**Problem:** Pre-built pools forced users to construct complex objects before passing to mempool. This was: - -- Hard to customize -- Required deep knowledge of internal structures -- Coupling between app and mempool internals - -**Solution:** Configuration objects allow: - -- Simple parameter tuning -- Internal pool construction by mempool -- Better separation of concerns -- Easier testing and mocking - -#### Migration Required - -✅ **Action Items:** - -1. Remove manual pool construction -2. Pass config objects instead -3. Update initialization code - -**Example Migration:** - -```diff -- legacyPool := legacypool.New(config, blockchain) -- cosmosPool := sdkmempool.NewPriorityMempool(...) - - mempoolConfig := &evmmempool.EVMMempoolConfig{ -- TxPool: txPool, -- CosmosPool: cosmosPool, -+ LegacyPoolConfig: &legacypool.Config{ -+ AccountSlots: 16, -+ GlobalSlots: 5120, -+ }, - AnteHandler: app.GetAnteHandler(), - } -``` - -**Files Modified:** - -``` -mempool/mempool.go | 66 +++++++++++++++++++++++++++++------------------------- -``` - ---- - -### 3. Global Mempool Registry Removal (#467) - -**Commit:** `aa9a8342` -**Author:** mmsqe -**Impact:** 🔴 BREAKING - Architecture change - -#### What Changed - -- Removed `SetGlobalEVMMempool()` function -- Removed global singleton pattern -- Mempool now passed directly to JSON-RPC server on initialization - -**Removed Files:** - -``` -mempool/registry_production.go | 33 ------ -mempool/registry_testing.go | 28 ------ -``` - -#### Why It Matters - -**Problem with Singleton:** - -- Global state is hard to test -- Race conditions on concurrent initialization -- Tight coupling between components -- Makes unit testing difficult - -**Benefits of Direct Injection:** - -- Explicit dependencies -- Easier to test (can inject mock mempool) -- No hidden global state -- Thread-safe by design - -#### Migration Required - -✅ **Action Items:** - -1. Remove `SetGlobalEVMMempool()` call from app.go -2. Pass mempool to RPC server explicitly during initialization - -**Before:** - -```go -evmMempool := evmmempool.NewExperimentalEVMMempool(...) -if err := evmmempool.SetGlobalEVMMempool(evmMempool); err != nil { - panic(err) -} -``` - -**After:** - -```go -evmMempool := evmmempool.NewExperimentalEVMMempool(...) -// Pass to RPC server in server initialization -rpcServer := NewJSONRPCServer(evmMempool, ...) -``` - -**Files Modified:** - -``` -evmd/app.go | 4 --- -rpc/apis.go | 24 ++++++++++------ -rpc/backend/backend.go | 4 +++ -rpc/backend/tx_pool.go | 9 +++--- -server/json_rpc.go | 4 ++- -server/start.go | 5 +++- -``` - ---- - -### 4. Precompile Interface Decoupling (#477) - -**Commit:** `8903f9d7` -**Author:** yoosah -**Impact:** 🟡 BREAKING - Better architecture - -#### What Changed - -- Defined keeper interfaces in `precompiles/common/interfaces.go` -- Precompiles now depend on interfaces instead of concrete keepers -- Constructor signatures changed to accept `MsgServer` and `Querier` interfaces - -**New Interfaces:** - -```go -// precompiles/common/interfaces.go -type BankKeeper interface { - GetBalance(ctx context.Context, addr sdk.AccAddress, denom string) sdk.Coin - SendCoins(ctx context.Context, from, to sdk.AccAddress, amt sdk.Coins) error - // ... only methods actually used by precompiles -} - -type StakingMsgServer interface { - Delegate(context.Context, *stakingtypes.MsgDelegate) (*stakingtypes.MsgDelegateResponse, error) - // ... only required methods -} -``` - -#### Why It Matters - -**Benefits:** - -1. **Loose Coupling** - Precompiles don't depend on entire keeper implementations -2. **Easy Testing** - Can mock interfaces with minimal effort -3. **Clear Contracts** - Interfaces document exactly what precompiles need -4. **Future-Proof** - Keeper internals can change without affecting precompiles - -#### Migration Required - -✅ **Action Items:** -Update precompile initialization to pass msg servers and query servers: - -**Before:** - -```go -govPrecompile, err := govprecompile.NewPrecompile( - govKeeper, - cdc, -) -``` - -**After:** - -```go -govPrecompile, err := govprecompile.NewPrecompile( - govkeeper.NewMsgServerImpl(&govKeeper), // Msg server interface - govkeeper.NewQueryServer(&govKeeper), // Query server interface - bankKeeper, - codec, - options.AddressCodec, -) -``` - -**Files Modified:** - -``` -evmd/precompiles.go | 27 +++++++++++-- -precompiles/common/interfaces.go (NEW) | 45 ++++++++++++++++++++++ -precompiles/distribution/distribution.go | 25 +++++++----- -precompiles/gov/gov.go | 19 +++++---- -precompiles/staking/staking.go | 18 ++++++--- -precompiles/slashing/slashing.go | 19 +++++---- -precompiles/ics20/ics20.go | 20 +++------- -``` - ---- - -### 5. EIP-2935 Implementation - Block Hash Storage (#407) - -**Commit:** `f164197b` -**Author:** yihuang (Crypto.org) -**Impact:** 🟢 NEW FEATURE - EIP support - -#### What Changed - -- Implemented EIP-2935: Historical block hash storage in state -- Added `history_serve_window` parameter (default: 8192 blocks) -- Modified `BLOCKHASH` opcode to query contract storage -- Adapted implementation from go-ethereum - -#### What is EIP-2935? - -**Problem:** Smart contracts can only access the last 256 block hashes via `BLOCKHASH` opcode. This limitation prevents: - -- Long-term oracle verification -- Historical proof verification -- Complex time-based logic - -**Solution:** Store block hashes in state for configurable window (default 8192 blocks = ~24 hours on 10s block time). - -#### Implementation Details - -```go -// Stores block hash in predefined contract storage -// Contract address: 0x0000...25 (EIP-2935 spec) -stateDB.SetState(blockHashContract, slot, blockHash) -``` - -**Storage Format:** - -- Ring buffer in contract storage -- Slot = block_number % HISTORY_SERVE_WINDOW -- Efficient overwriting of old hashes - -#### Migration Required - -✅ **Action Items:** - -1. Add `history_serve_window` parameter to genesis -2. Remove `allow_unprotected_txs` (cleaned up in same PR) - -**Genesis Update:** - -```diff -{ - "vm": { - "params": { -- "allow_unprotected_txs": false, -+ "history_serve_window": 8192 - } - } -} -``` - -**Files Modified:** - -``` -proto/cosmos/evm/vm/v1/evm.proto | 1 + -x/vm/keeper/keeper.go | 37 +- -x/vm/keeper/state_transition.go | 20 +- -x/vm/types/params.go | 3 + -x/vm/types/preinstall.go (NEW) | 6 + -``` - -**Performance Impact:** - -- Minimal: One storage write per block -- Ring buffer prevents unbounded growth - ---- - -### 6. Remove allow-unprotected-txs Parameter (#415) - -**Commit:** `1d8b9e1e` -**Author:** Sujong Lee -**Impact:** 🔴 BREAKING - Parameter removal - -#### What Changed - -- Removed `allow_unprotected_txs` from VM module parameters -- Non-EIP-155 transaction handling moved to node-level config - -#### Why It Matters - -**Context:** EIP-155 added chain ID to transaction signatures to prevent replay attacks across chains. - -**Problem with Global Parameter:** - -- Should be node-level decision (operator's choice) -- Shouldn't be consensus parameter -- Different nodes may want different policies - -**Solution:** - -- Removed from state/consensus -- Operators configure per-node if needed -- Reduces attack surface at consensus layer - -#### Migration Required - -✅ **Action Items:** - -1. Remove parameter from genesis -2. Remove code referencing `AllowUnprotectedTxs` -3. If needed, configure at node level (outside consensus) - -**Files Modified:** - -``` -ante/evm/05_signature_verification.go | 20 +- -proto/cosmos/evm/vm/v1/evm.proto | 6 +- -x/vm/types/params.go | 17 - -x/vm/types/params_legacy.go | 12 +- -``` - ---- - -### 7. eth_createAccessList RPC Method (#346) - -**Commit:** `4d93f2d0` -**Author:** Abdul Malek -**Impact:** 🟢 NEW FEATURE - RPC method - -#### What Changed - -- Added `eth_createAccessList` JSON-RPC method -- Supports EIP-2930 access list transactions -- Provides gas optimization for complex transactions - -#### What is eth_createAccessList? - -**Purpose:** Analyzes transaction execution and returns optimal access list. - -**Access Lists (EIP-2930):** - -- Pre-declare storage slots accessed during execution -- Reduces gas cost for those accesses -- Particularly useful for: - - Complex contract interactions - - Multi-contract calls - - Heavy storage operations - -**Example Usage:** - -```javascript -// RPC call -eth.createAccessList({ - from: "0x...", - to: "0x...", - data: "0x..." -}) - -// Returns -{ - accessList: [ - { - address: "0xContract1...", - storageKeys: ["0xkey1", "0xkey2"] - } - ], - gasUsed: "0x1234" -} -``` - -#### Benefits - -- **Gas Optimization** - Can save 5-20% gas on complex txs -- **Tool Compatibility** - Required by many Ethereum dev tools -- **User Experience** - Wallets can optimize gas automatically - -**Files Modified:** - -- Extensive changes across RPC layer -- Access list generation logic -- Gas estimation improvements - ---- - -### 8. PostTxProcessing Hook Improvements (#479) - -**Commit:** `2cf6593f` -**Author:** Facundo Medica (Informal Systems) -**Impact:** 🟡 ENHANCEMENT - Hook behavior - -#### What Changed - -- `PostTxProcessing` hooks now run even on transaction failures -- Hook data is persisted regardless of tx success/failure -- More reliable event emission and state tracking - -#### Why It Matters - -**Before:** Hooks only ran on successful transactions, causing: - -- Missed events for failed txs -- Incomplete metrics/analytics -- Lost tracking data - -**After:** Hooks always run, enabling: - -- Complete transaction lifecycle tracking -- Failed transaction analytics -- Comprehensive event logging -- Better monitoring and debugging - -**Use Cases:** - -- IBC callbacks need to know about failures -- Metrics systems track all attempts -- Debugging failed transactions -- Audit logs must be complete - -#### Migration Impact - -- No breaking changes -- Enhanced functionality -- Hooks should handle failure cases - -**Files Modified:** - -``` -x/vm/keeper/keeper.go | 5 + -x/vm/keeper/state_transition.go | 85 ++++++++---- -``` - ---- - -### 9. Re-use go-ethereum TX Validation Rules (#286) - -**Commit:** `6492ef5b` -**Author:** yihuang (Crypto.org) -**Impact:** 🟢 ENHANCEMENT - Better compatibility - -#### What Changed - -- Delegated transaction validation to go-ethereum's validation logic -- Ensures 100% compatibility with Ethereum transaction rules -- Reduces custom validation code - -#### Why It Matters - -**Benefits:** - -1. **Compatibility** - Matches Ethereum behavior exactly -2. **Maintenance** - Automatic updates when go-ethereum updates -3. **Security** - Leverages battle-tested validation -4. **Consistency** - Same rules as mainnet Ethereum - -**Validation Rules Inherited:** - -- Gas limit validation -- Gas price validation -- Nonce validation -- Signature validation -- Transaction type checks - -#### Migration Impact - -- No breaking changes -- More restrictive validation in some edge cases -- Better error messages matching Ethereum - -**Files Modified:** - -``` -ante/evm/05_signature_verification.go | 4 ++-- -ante/evm/mono_decorator.go | 26 ++++++++++++++++++++++ -x/vm/keeper/state_transition.go | 12 +++++++++- -``` - ---- - -## Medium Priority Changes - -### 10. Mempool New Block Notification Fix (#471) - -**Commit:** `642c8e98` -**Author:** Community -**Impact:** 🟡 FIX - Race condition - -**Problem:** Mempool wasn't notified of new blocks in time, causing "insufficient funds" errors when funding and sending tx in same block. - -**Solution:** Improved timing of mempool block notifications. - ---- - -### 11. IsStorageEmpty Implementation (#490) - -**Commit:** `1f22f197` -**Author:** Community -**Impact:** 🟡 FIX - Missing method - -**Problem:** `IsStorageEmpty` method not implemented in state DB. - -**Solution:** Added proper implementation for contract storage emptiness checks. - ---- - -### 12. Decimals Query Fix for IBC Tokens (#397) - -**Commit:** `810e9ef0` -**Author:** Community -**Impact:** 🟡 FIX - IBC compatibility - -**Problem:** Decimals query reverted when Display doesn't match DenomUnit for IBC tokens. - -**Solution:** Improved metadata handling for IBC token decimals. - ---- - -### 13. PreciseBank & WERC20 Precompile Fixes (#457) - -**Commit:** `29c1fac8` -**Author:** Community -**Impact:** 🟡 FIX + FEATURE - -**Added:** - -- `FractionalBalanceChange` event for tracking sub-unit balance changes -- Improved WERC20 precompile precision handling - ---- - -### 14. Token-Pairs Query Pagination (#468) - -**Commit:** `7dc893df` -**Author:** Community -**Impact:** 🟡 FIX - Query improvement - -**Added:** Pagination flags to token-pairs query for better API usability. - ---- - -### 15. BalanceChangeEntry Cleanup (#506) - -**Commit:** `750d77d9` -**Author:** mmsqe -**Impact:** 🟢 CLEANUP - -**Removed:** Deprecated `BalanceChangeEntry` tracing code, aligned with go-ethereum v1.16.2 balance change tracking. - ---- - -## Documentation & Testing - -### 16. ERC20 Migration Guide (#485) - -**Commit:** `a9cb4011` -**Author:** Documentation team -**Impact:** 📚 DOCS - -Added comprehensive guide for ERC20 precompile storage migration. - ---- - -### 17. SetClientCtx Migration Instructions (#481) - -**Commit:** `909c8e2b` -**Author:** Documentation team -**Impact:** 📚 DOCS - -Added instructions for implementing `SetClientCtx` method during migration. - ---- - -### 18. Upgrade Test (v0.4.1 → main) (#498) - -**Commit:** `48e3c833` -**Author:** Tyler -**Impact:** ✅ TEST - -Added comprehensive upgrade test suite for v0.4.1 → v0.5.0 migration. - ---- - -### 19. JSON-RPC Compatibility Tests (#419) - -**Commit:** `ab1cd0cf` -**Author:** Testing team -**Impact:** ✅ TEST - -Added JSON-RPC compatibility test suite to ensure Ethereum tooling works correctly. - ---- - -### 20. EVM Tools Compatibility Tests (#287) - -**Commit:** `204ff4ea` -**Author:** Testing team -**Impact:** ✅ TEST - -Added tests for Hardhat, Foundry, and other popular Ethereum development tools. - ---- - -### 21. Revert Error E2E Tests (#476) - -**Commit:** `3991c2c4` -**Author:** Testing team -**Impact:** ✅ TEST - -Added end-to-end tests for revert errors in both contract and precompile calls. - ---- - -## Minor Changes & Fixes - -### 22. Duplicate Switch Case Fix (#492) - -**Commit:** `03083a8b` -**Impact:** 🟢 FIX - Code quality -Fixed duplicate case in switch statement to avoid empty execution blocks. - ---- - -### 23. Deprecated Allowance Functions Cleanup (#472) - -**Commit:** `1bdd7d2a` -**Impact:** 🟢 CLEANUP -Removed deprecated `increaseAllowance` and `decreaseAllowance` functions. - ---- - -### 24. Local Node Upgrade Scripts (#470) - -**Commit:** `39ddca42` -**Impact:** 🔧 TOOLING -Improved `local_node.sh` script with upgrade testing support. - ---- - -### 25. Contracts Compile Script Update (#475) - -**Commit:** `b9bdbe6a` -**Impact:** 🔧 TOOLING -Updated contract compilation scripts for better developer experience. - ---- - -### 26. RPC Accessibility Fix (#469) - -**Commit:** `a2599769` -**Impact:** 🟡 FIX -Fixed RPC endpoint accessibility issues. - ---- - -### 27. CI Workflow Improvement (#499) - -**Commit:** `2d3df2ba` -**Impact:** 🔧 CI -Workflow now fails when feat/fix/refactor PRs don't have CHANGELOG entry. - ---- - -### 28. Version Retraction (#464, #465) - -**Commits:** `384ea4a2`, `dd448d29` -**Impact:** 🔧 VERSION -Retracted problematic intermediate versions. - ---- - -### 29. Mergify Config Update (#463) - -**Commit:** `dd448d29` -**Impact:** 🔧 CI -Updated Mergify configuration for better PR automation. - ---- - -## Breaking Changes Summary - -### API Breaking Changes - -| Change | Impact | Migration Required | -| ----------------------- | ------ | ------------------------ | -| Mempool config refactor | HIGH | Update config struct | -| Global mempool removal | HIGH | Pass mempool to RPC | -| Precompile interfaces | MEDIUM | Update constructor calls | -| VM params removal | MEDIUM | Update genesis | -| Hook behavior | LOW | Handle failure cases | - -### Required Migrations - -1. **Update `EVMMempoolConfig`** - - - Remove `TxPool` and `CosmosPool` fields - - Add `LegacyPoolConfig` and `CosmosPoolConfig` - -2. **Remove Global Mempool** - - - Delete `SetGlobalEVMMempool()` call - - Pass mempool to RPC server explicitly - -3. **Update Precompile Initialization** - - - Pass msg/query servers instead of keepers - - Add bank keeper to ICS-20 precompile - - Add address codec to Gov precompile - -4. **Update Genesis** - - - Remove `allow_unprotected_txs` - - Add `history_serve_window: 8192` - -5. **Implement App `Close()` Method** - - Add proper cleanup logic - - Handle mempool shutdown - ---- - -## New Features Summary - -| Feature | Benefit | Use Case | -| --------------------------- | ------------------------------ | --------------------------- | -| EIP-2935 | Historical block hash access | Oracle verification, proofs | -| eth_createAccessList | Gas optimization | Complex transactions | -| Interface-based precompiles | Better testing, loose coupling | Development, maintenance | -| PostTx hooks on failure | Complete lifecycle tracking | Monitoring, debugging | -| Go-ethereum validation | Perfect Ethereum compatibility | Tool support | - ---- - -## Performance Improvements - -1. **EVM Instance Removal** - Reduced memory allocation per transaction -2. **Optimized Ante Handler** - Faster tx validation -3. **Access List Support** - 5-20% gas savings on complex txs -4. **Better Memory Management** - Reduced heap pressure - ---- - -## Developer Experience Improvements - -1. **Simpler Configuration** - Config objects vs pre-built pools -2. **Better Testing** - Interface-based design -3. **Improved Documentation** - Migration guides and examples -4. **Better Error Messages** - Matching Ethereum exactly -5. **Comprehensive Test Suite** - JSON-RPC, tool compatibility - ---- - -## Security Enhancements - -1. **Go-ethereum Validation** - Battle-tested rules -2. **Removed Global State** - Thread-safe design -3. **Parameter Cleanup** - Reduced attack surface -4. **Better Hook Handling** - Consistent state management - ---- - -## Compatibility Matrix - -| Tool/Framework | v0.4.x | v0.5.0 | Notes | -| -------------- | ------ | ------ | ------------- | -| Hardhat | ✅ | ✅ | Full support | -| Foundry | ✅ | ✅ | Full support | -| Remix | ✅ | ✅ | Full support | -| MetaMask | ✅ | ✅ | Full support | -| Ethers.js | ✅ | ✅ | Full support | -| Web3.js | ✅ | ✅ | Full support | -| Access Lists | ❌ | ✅ | NEW in v0.5.0 | -| EIP-2935 | ❌ | ✅ | NEW in v0.5.0 | - ---- - -## Upgrade Checklist - -### Pre-Upgrade - -- [ ] Review all breaking changes -- [ ] Test upgrade on devnet -- [ ] Update genesis file (remove allow_unprotected_txs, add history_serve_window) -- [ ] Update app.go for mempool changes -- [ ] Update precompile initialization - -### During Upgrade - -- [ ] Run upgrade handler -- [ ] Monitor for errors -- [ ] Check mempool operation -- [ ] Verify RPC endpoints - -### Post-Upgrade - -- [ ] Test eth_createAccessList -- [ ] Verify EIP-2935 block hash storage -- [ ] Check gas estimation accuracy -- [ ] Monitor performance metrics - ---- - -## Resources - -- **Upgrade Handler:** See `evmd/upgrades.go` -- **Mempool README:** See `mempool/README.md` -- **Migration Guide:** See `docs/migrations/v0.3.0_to_v0.4.0.md` (template for v0.5) -- **Test Suite:** See `tests/integration/` - ---- - -## Contributors - -Major contributions from: - -- **Vlad J** (Cosmos/EVM team) - Mempool refactor, architecture -- **mmsqe** (Crypto.org) - Global mempool removal, cleanup -- **yihuang** (Crypto.org) - EIP-2935, go-ethereum validation -- **yoosah** - Precompile interface decoupling -- **LEE JUNSEO** (bharvest) - Performance optimizations -- **Abdul Malek** - eth_createAccessList implementation -- **Facundo Medica** (Informal Systems) - Hook improvements -- **Tyler** - Testing and CI improvements - ---- - -**Document Version:** 1.0 -**Last Updated:** 2025-10-10 -**Status:** Draft for documentation team review diff --git a/V0.5_INTEGRATION_PREP_FINDINGS.md b/V0.5_INTEGRATION_PREP_FINDINGS.md deleted file mode 100644 index 7dfbd6a0..00000000 --- a/V0.5_INTEGRATION_PREP_FINDINGS.md +++ /dev/null @@ -1,1341 +0,0 @@ -# Cosmos EVM v0.5.0 Integration Documentation - Preparation Findings - -**Date:** 2025-10-10 -**Purpose:** Bulk data collection and organizational prep for v0.5 integration documentation rewrite -**Scope:** Fresh integrations, v0.4.x→v0.5.0 migrations, and mempool integration updates - ---- - -## Executive Summary - -This document contains all the raw findings, API changes, and structural analysis needed to rewrite three critical integration documents for Cosmos EVM v0.5.0: - -1. **Fresh Integration Guide** (no EVM → EVM v0.5.0) -2. **Migration Guide** (v0.4.x → v0.5.0) -3. **Mempool Integration Doc** (updated for v0.5.0 APIs) - -### Key Insights - -- **v0.5.0 simplifies integration** by removing several config options and introducing cleaner APIs -- **Mempool is now configuration-based** instead of pre-built pool injection -- **Global mempool registry removed** - mempool now passed directly to JSON-RPC server -- **Keeper initialization ordering is critical** - PreciseBank must come before VM -- **Several components are optional** but current docs don't clearly denote which - ---- - -## Section 1: API-Breaking Changes (v0.4.1 → v0.5.0-rc.0) - -### Modified Files in evmd/ - -Based on `git diff v0.4.1..v0.5.0-rc.0 evmd/`: - -``` -M evmd/ante/evm_handler.go -M evmd/app.go -M evmd/cmd/evmd/cmd/testnet.go -M evmd/cmd/evmd/config/evmd_config.go -M evmd/precompiles.go -M evmd/tests/ibc/ics20_precompile_transfer_test.go -M evmd/tests/ibc/v2_ics20_precompile_transfer_test.go -M evmd/tests/network/util.go -M evmd/upgrades.go -``` - -**Statistics:** 9 files changed, 88 insertions(+), 20 deletions(-) - ---- - -### 1.1 Mempool Architecture Changes (app.go) - -#### REMOVED: Global Mempool Registry - -**Before (v0.4.1):** - -```go -// Set the global mempool for RPC access -if err := evmmempool.SetGlobalEVMMempool(evmMempool); err != nil { - panic(err) -} -app.SetMempool(evmMempool) -``` - -**After (v0.5.0):** - -```go -// Global registry removed - mempool passed directly to RPC server -app.SetMempool(evmMempool) -``` - -**Impact:** Chains must update JSON-RPC server initialization to pass mempool directly instead of relying on singleton pattern. - ---- - -#### ADDED: App Close Method - -**New in v0.5.0:** - -```go -// Close unsubscribes from the CometBFT event bus (if set) and closes the underlying BaseApp. -func (app *EVMD) Close() error { - var err error - if m, ok := app.GetMempool().(*evmmempool.ExperimentalEVMMempool); ok { - err = m.Close() - } - err = errors.Join(err, app.BaseApp.Close()) - msg := "Application gracefully shutdown" - if err == nil { - app.Logger().Info(msg) - } else { - app.Logger().Error(msg, "error", err) - } - return err -} -``` - -**Purpose:** Proper cleanup of mempool resources and event bus subscriptions. -**Required:** Apps must implement this method to prevent resource leaks. - ---- - -#### CHANGED: Import Statement - -**New import in v0.5.0:** - -```go -import ( - "encoding/json" - "errors" // ← NEW - "fmt" - "io" - // ... -) -``` - -**Purpose:** Used in new `Close()` method with `errors.Join()`. - ---- - -### 1.2 Mempool Config Structure Changes - -#### REMOVED: Pre-built Pool Injection - -**Before (v0.4.1):** - -```go -type EVMMempoolConfig struct { - TxPool *txpool.TxPool // ← REMOVED - CosmosPool sdkmempool.ExtMempool // ← REMOVED - AnteHandler sdk.AnteHandler - BroadCastTxFn func(txs []*ethtypes.Transaction) error - BlockGasLimit uint64 -} -``` - -**After (v0.5.0):** - -```go -type EVMMempoolConfig struct { - LegacyPoolConfig *legacypool.Config // ← NEW - CosmosPoolConfig *sdkmempool.PriorityNonceMempoolConfig[math.Int] // ← NEW - AnteHandler sdk.AnteHandler - BroadCastTxFn func(txs []*ethtypes.Transaction) error - BlockGasLimit uint64 -} -``` - -**Rationale:** - -- Configuration-based approach is more flexible -- Pools are now created internally by `NewExperimentalEVMMempool()` -- Simplifies integration - no need to pre-construct pools -- Better separation of concerns - ---- - -### 1.3 Precompile Constructor Signature Changes (precompiles.go) - -#### CHANGED: ICS-20 Transfer Precompile - -**Before (v0.4.1):** - -```go -ibcTransferPrecompile, err := ics20precompile.NewPrecompile( - stakingKeeper, - transferKeeper, - channelKeeper, -) -``` - -**After (v0.5.0):** - -```go -ibcTransferPrecompile, err := ics20precompile.NewPrecompile( - bankKeeper, // ← NEW - added as first parameter - stakingKeeper, - transferKeeper, - channelKeeper, -) -``` - -**Reason:** ICS-20 precompile now needs bank keeper for additional token operations. - ---- - -#### CHANGED: Gov Precompile - -**Before (v0.4.1):** - -```go -govPrecompile, err := govprecompile.NewPrecompile( - govKeeper, - cdc, -) -``` - -**After (v0.5.0):** - -```go -govPrecompile, err := govprecompile.NewPrecompile( - govkeeper.NewMsgServerImpl(&govKeeper), // ← CHANGED to msg server - govkeeper.NewQueryServer(&govKeeper), // ← CHANGED to query server - bankKeeper, // ← NEW - codec, // ← renamed from cdc - options.AddressCodec, // ← NEW -) -``` - -**Reason:** Decoupling from keeper - uses interfaces instead for better modularity. - ---- - -#### NO CHANGE: Optional Params Pattern - -The `Optionals` struct and functional options pattern remain unchanged from v0.4.x: - -```go -type Optionals struct { - AddressCodec address.Codec // used by gov/staking - ValidatorAddrCodec address.Codec // used by slashing - ConsensusAddrCodec address.Codec // used by slashing -} - -func defaultOptionals() Optionals { - return Optionals{ - AddressCodec: addresscodec.NewBech32Codec(sdk.GetConfig().GetBech32AccountAddrPrefix()), - ValidatorAddrCodec: addresscodec.NewBech32Codec(sdk.GetConfig().GetBech32ValidatorAddrPrefix()), - ConsensusAddrCodec: addresscodec.NewBech32Codec(sdk.GetConfig().GetBech32ConsensusAddrPrefix()), - } -} -``` - ---- - -### 1.4 Ante Handler Changes (ante/evm_handler.go) - -**File appears to be simplified but no major API breaking changes in the public interface.** - -The ante handler setup in app.go remains conceptually the same: - -- Still uses `ante.NewAnteHandler(options)` -- Options struct likely has internal changes but external API is stable - ---- - -### 1.5 Upgrade Handler (upgrades.go) - -**New file added in v0.5.0 with reference upgrade handler:** - -```go -const UpgradeName = "v0.4.0-to-v0.5.0" - -func (app EVMD) RegisterUpgradeHandlers() { - app.UpgradeKeeper.SetUpgradeHandler( - UpgradeName, - func(ctx context.Context, _ upgradetypes.Plan, fromVM module.VersionMap) (module.VersionMap, error) { - sdk.UnwrapSDKContext(ctx).Logger().Debug("this is a debug level message to test that verbose logging mode has properly been enabled during a chain upgrade") - return app.ModuleManager.RunMigrations(ctx, app.Configurator(), fromVM) - }, - ) - - upgradeInfo, err := app.UpgradeKeeper.ReadUpgradeInfoFromDisk() - if err != nil { - panic(err) - } - - if upgradeInfo.Name == UpgradeName && !app.UpgradeKeeper.IsSkipHeight(upgradeInfo.Height) { - storeUpgrades := storetypes.StoreUpgrades{ - Added: []string{}, // No new stores added in v0.5.0 - } - app.SetStoreLoader(upgradetypes.UpgradeStoreLoader(upgradeInfo.Height, &storeUpgrades)) - } -} -``` - -**Key Points:** - -- No store migrations required for v0.5.0 upgrade -- Standard module migrations handled by `RunMigrations()` -- Example shows proper verbose logging during upgrades - ---- - -## Section 2: Component-Based API Change Categorization - -Instead of organizing by file, here are the changes grouped by logical component: - -### 2.1 Mempool Component - -**Changes:** - -1. **Config struct refactor** - Pre-built pools → Configuration objects -2. **Global registry removal** - Singleton pattern → Direct injection -3. **Cleanup lifecycle** - New `Close()` method for proper shutdown -4. **Event bus integration** - Mempool now subscribes to CometBFT events - -**Migration Steps:** - -1. Remove `SetGlobalEVMMempool()` call from app constructor -2. Update `EVMMempoolConfig` to use `LegacyPoolConfig` and `CosmosPoolConfig` -3. Add `Close()` method to app -4. Pass mempool to RPC server initialization explicitly - -**Optional vs Required:** - -- **REQUIRED:** Basic mempool setup with `AnteHandler` and `BlockGasLimit` -- **OPTIONAL:** Custom `LegacyPoolConfig` (defaults provided) -- **OPTIONAL:** Custom `CosmosPoolConfig` (defaults provided) -- **OPTIONAL:** Custom `BroadcastTxFn` (default uses `clientCtx`) - ---- - -### 2.2 Precompiles Component - -**Changes:** - -1. **ICS-20 constructor** - Added `bankKeeper` as first parameter -2. **Gov constructor** - Changed from keeper to msg/query servers + bank keeper + address codec -3. **Staking/Distribution constructors** - Changed to use msg/query server pattern (if similar to gov) - -**Migration Steps:** - -1. Update ICS-20 precompile call to include `bankKeeper` -2. Update Gov precompile to use msg server, query server, bank keeper, and address codec -3. Verify all precompile constructors match new signatures - -**Optional vs Required:** - -- **REQUIRED:** Staking, Distribution, Bank precompiles (core functionality) -- **OPTIONAL:** Gov precompile (governance features) -- **OPTIONAL:** Slashing precompile (validator slashing) -- **OPTIONAL:** ICS-20 precompile (IBC transfers via EVM) - ---- - -### 2.3 Ante Handler Component - -**Changes:** - -- Internal optimizations -- No major public API changes identified - -**Migration Steps:** - -- No changes required to existing ante handler setup - ---- - -### 2.4 App Lifecycle Component - -**Changes:** - -1. **Close method** - New required method for cleanup -2. **clientCtx handling** - Existing `SetClientCtx()` method remains required - -**Migration Steps:** - -1. Implement `Close()` method in app -2. Ensure `SetClientCtx()` is implemented (should already exist from v0.4.x) - -**Required:** - -- **REQUIRED:** `Close()` method -- **REQUIRED:** `SetClientCtx()` method -- **REQUIRED:** `clientCtx client.Context` field in app struct - ---- - -### 2.5 VM Parameters Component - -**Changes:** - -1. **REMOVED:** `allow_unprotected_txs` parameter -2. **ADDED:** `history_serve_window` parameter (default: 8192) - -**Migration Steps:** - -1. Remove `allow_unprotected_txs` from genesis files -2. Add `history_serve_window: 8192` to genesis files -3. Remove any code referencing `AllowUnprotectedTxs` - -**Purpose:** - -- `history_serve_window` supports EIP-2935 (block hash storage) - ---- - -## Section 3: Keeper Initialization Ordering Requirements - -Based on analysis of evmd/app.go from v0.5.0: - -### Critical Ordering Requirements - -``` -1. Standard Cosmos SDK Keepers (order matters for some): - AccountKeeper - BankKeeper - StakingKeeper - ... other SDK keepers - -2. FeeMarket Keeper - ↓ (must come before PreciseBank and VM) - -3. PreciseBank Keeper ⚠️ CRITICAL - ↓ (MUST be initialized BEFORE VM keeper) - -4. VM Keeper - ↓ (needs PreciseBank, FeeMarket) - -5. ERC20 Keeper - ↓ (needs VM keeper) - -6. Transfer Keeper (IBC) - ↓ (can reference ERC20 keeper) - -7. Precompiles Registration - ↓ (needs all keepers ready) - -8. EVM Mempool - ↓ (needs VM keeper, FeeMarket keeper, and ante handler set) -``` - -### Dependency Graph - -``` -AccountKeeper → PreciseBank ───┐ -BankKeeper ─────────────────────┤ -FeeMarketKeeper ────────────────┼→ VM Keeper → ERC20 Keeper -ConsensusParamsKeeper ──────────┤ ↓ -StakingKeeper ──────────────────┘ Transfer Keeper - ↓ - Precompiles - ↓ - EVM Mempool -``` - -### Why Ordering Matters - -1. **PreciseBank before VM:** - - - VM keeper depends on PreciseBank for 18-decimal precision token operations - - Compilation will succeed but runtime panics occur if order is wrong - -2. **FeeMarket before VM:** - - - VM needs FeeMarket for gas pricing - -3. **ERC20 after VM:** - - - ERC20 module interacts with EVM state - -4. **Transfer after ERC20:** - - - IBC transfer needs ERC20 keeper for token conversions - -5. **Mempool after all keepers:** - - Mempool needs VM, FeeMarket, and ante handler (which depends on many keepers) - ---- - -## Section 4: Optional vs Required Components - -### Required Components ✓ - -These components are **essential** for basic EVM functionality: - -1. **VM Module** (`x/vm`) - - - Core EVM execution engine - - Cannot run EVM without this - -2. **FeeMarket Module** (`x/feemarket`) - - - EIP-1559 dynamic fee support - - Required for gas pricing - -3. **PreciseBank Module** (`x/precisebank`) - - - 18-decimal precision for EVM tokens - - Required for proper ERC20 token handling - -4. **ERC20 Module** (`x/erc20`) - - - ERC20 token bridge between Cosmos and EVM - - Required for token interoperability - -5. **Core Precompiles** - - - Bank precompile - token operations - - Bech32 precompile - address conversion - - P256 precompile - EIP-7212 signature verification - -6. **EVM Mempool** - - - Required for proper EVM transaction handling - - Supports nonce gap queuing - -7. **Ante Handlers** - - - EVM ante handler for EVM tx validation - - Required for security - -8. **App Lifecycle Methods** - - `SetClientCtx()` - - `Close()` - - `RegisterPendingTxListener()` - - `onPendingTx()` - ---- - -### Optional Components (Can be excluded) - -1. **Staking Precompile** - - - Use case: EVM contracts calling staking operations - - Can omit if not needed - -2. **Distribution Precompile** - - - Use case: EVM contracts claiming rewards - - Can omit if not needed - -3. **Gov Precompile** - - - Use case: EVM contracts submitting proposals - - Can omit if not needed - -4. **Slashing Precompile** - - - Use case: EVM contracts unjailing validators - - Can omit if not needed - -5. **ICS-20 Transfer Precompile** - - - Use case: EVM contracts initiating IBC transfers - - Can omit if IBC not used or not needed from EVM - -6. **Custom Mempool Configs** - - - Use case: Fine-tuning mempool behavior - - Defaults are sufficient for most chains - -7. **IBC Transfer Override** - - Use case: IBC transfers of ERC20 tokens - - Can use standard IBC transfer if not needed - ---- - -## Section 5: Fresh Integration Step-by-Step Outline - -Based on evmd reference implementation in v0.5.0: - -### High-Level Component Flow - -``` -1. Dependencies & Imports -2. App Struct Definition -3. Store Keys Registration -4. Keeper Initialization (order matters!) -5. Module Wiring -6. Precompiles Registration -7. Ante Handler Setup -8. Mempool Configuration -9. Module Manager & Begin/EndBlockers -10. Init Genesis & Export -``` - ---- - -### Detailed Steps (Component-Based) - -#### Component: Dependencies - -1. Add `github.com/cosmos/evm v0.5.0` to go.mod -2. Add replace directive for go-ethereum fork -3. Run `go mod tidy` - -**Ordering:** N/A (first step) - ---- - -#### Component: Store Keys - -1. Add EVM store keys to `keys` map: - - - `evmtypes.StoreKey` - - `feemarkettypes.StoreKey` - - `erc20types.StoreKey` - - `precisebanktypes.StoreKey` - -2. Add EVM transient keys to `tkeys` map: - - `evmtypes.TransientKey` - - `feemarkettypes.TransientKey` - -**Ordering:** Before keeper initialization - ---- - -#### Component: PreciseBank Keeper - -1. Initialize PreciseBank keeper: - -```go -app.PreciseBankKeeper = precisebankkeeper.NewKeeper( - appCodec, - runtime.NewKVStoreService(keys[precisebanktypes.StoreKey]), - app.AccountKeeper, - app.BankKeeper, - authtypes.NewModuleAddress(govtypes.ModuleName), - logger, -) -``` - -**Ordering:** MUST come before VM keeper -**Dependencies:** AccountKeeper, BankKeeper, govtypes (for authority address) -**Optional:** NO - Required for proper EVM token handling - ---- - -#### Component: FeeMarket Keeper - -1. Initialize FeeMarket keeper: - -```go -app.FeeMarketKeeper = feemarketkeeper.NewKeeper( - appCodec, - authtypes.NewModuleAddress(govtypes.ModuleName), - runtime.NewKVStoreService(keys[feemarkettypes.StoreKey]), - runtime.NewTransientStoreService(tkeys[feemarkettypes.TransientKey]), - app.GetSubspace(feemarkettypes.ModuleName), -) -``` - -**Ordering:** MUST come before VM keeper -**Dependencies:** govtypes (for authority address) -**Optional:** NO - Required for EIP-1559 gas pricing - ---- - -#### Component: VM Keeper - -1. Initialize VM keeper: - -```go -app.EVMKeeper = evmkeeper.NewKeeper( - appCodec, - keys[evmtypes.StoreKey], - tkeys[evmtypes.TransientKey], - authtypes.NewModuleAddress(govtypes.ModuleName), - app.AccountKeeper, - app.PreciseBankKeeper, // ⚠️ Must be initialized before this - app.StakingKeeper, - app.FeeMarketKeeper, // ⚠️ Must be initialized before this - &app.ConsensusParamsKeeper, - &app.Erc20Keeper, // Note: circular reference handled via pointer - tracer, -) -``` - -**Ordering:** After PreciseBank and FeeMarket, before ERC20 -**Dependencies:** PreciseBank, FeeMarket, Account, Staking, ConsensusParams -**Optional:** NO - Core EVM execution engine - ---- - -#### Component: ERC20 Keeper - -1. Initialize ERC20 keeper: - -```go -app.Erc20Keeper = erc20keeper.NewKeeper( - keys[erc20types.StoreKey], - appCodec, - authtypes.NewModuleAddress(govtypes.ModuleName), - app.AccountKeeper, - app.PreciseBankKeeper, - app.EVMKeeper, // ⚠️ Must be initialized before this - app.StakingKeeper, - &app.TransferKeeper, // Note: circular reference via pointer -) -``` - -**Ordering:** After VM keeper, before Transfer keeper -**Dependencies:** VM, PreciseBank, Account, Staking -**Optional:** NO - Required for ERC20 token bridge - ---- - -#### Component: IBC Transfer Keeper (EVM-enhanced) - -1. Initialize Transfer keeper with EVM override: - -```go -app.TransferKeeper = transferkeeper.NewKeeper( - appCodec, - runtime.NewKVStoreService(keys[ibctransfertypes.StoreKey]), - app.GetSubspace(ibctransfertypes.ModuleName), - app.IBCKeeper.ChannelKeeper, - app.IBCKeeper.ChannelKeeper, - app.MsgServiceRouter(), - app.AccountKeeper, - app.BankKeeper, - app.Erc20Keeper, // ⚠️ ERC20 keeper for token conversions - authAddr, -) -``` - -**Ordering:** After ERC20 keeper -**Dependencies:** IBC, ERC20, Account, Bank -**Optional:** If not using IBC, can use standard transfer keeper - ---- - -#### Component: Precompiles - -1. Register static precompiles on VM keeper: - -```go -app.EVMKeeper.WithStaticPrecompiles( - NewAvailableStaticPrecompiles( - *app.StakingKeeper, - app.DistrKeeper, - app.PreciseBankKeeper, - app.Erc20Keeper, - app.TransferKeeper, - app.IBCKeeper.ChannelKeeper, - app.EVMKeeper, - app.GovKeeper, - app.SlashingKeeper, - app.AppCodec(), - ), -) -``` - -**Ordering:** After all keepers initialized -**Dependencies:** All keepers used by precompiles -**Optional:** Can customize which precompiles to include (see Section 4) - ---- - -#### Component: Ante Handler - -1. Set up ante handler with EVM options: - -```go -app.setAnteHandler(app.txConfig, maxGasWanted) -``` - -Where `setAnteHandler` creates options: - -```go -options := ante.HandlerOptions{ - AccountKeeper: app.AccountKeeper, - BankKeeper: app.BankKeeper, - ExtensionOptionChecker: cosmosevmtypes.HasDynamicFeeExtensionOption, - EvmKeeper: app.EVMKeeper, - FeegrantKeeper: app.FeeGrantKeeper, - IBCKeeper: app.IBCKeeper, - FeeMarketKeeper: app.FeeMarketKeeper, - SignModeHandler: txConfig.SignModeHandler(), - SigGasConsumer: evmante.SigVerificationGasConsumer, - MaxTxGasWanted: maxGasWanted, - TxFeeChecker: cosmosevmante.NewDynamicFeeChecker(app.FeeMarketKeeper), - PendingTxListener: app.onPendingTx, // ⚠️ For mempool integration -} -``` - -**Ordering:** After all keepers, before mempool -**Dependencies:** All keepers, txConfig -**Optional:** NO - Required for transaction validation - ---- - -#### Component: EVM Mempool - -1. Configure and initialize mempool: - -```go -if evmtypes.GetChainConfig() != nil { - mempoolConfig := &evmmempool.EVMMempoolConfig{ - AnteHandler: app.GetAnteHandler(), // ⚠️ Must be set first - BlockGasLimit: 100_000_000, - } - - evmMempool := evmmempool.NewExperimentalEVMMempool( - app.CreateQueryContext, - logger, - app.EVMKeeper, - app.FeeMarketKeeper, - app.txConfig, - app.clientCtx, // ⚠️ Must be set via SetClientCtx() - mempoolConfig, - ) - app.EVMMempool = evmMempool - - app.SetMempool(evmMempool) - checkTxHandler := evmmempool.NewCheckTxHandler(evmMempool) - app.SetCheckTxHandler(checkTxHandler) - - abciProposalHandler := baseapp.NewDefaultProposalHandler(evmMempool, app) - abciProposalHandler.SetSignerExtractionAdapter( - evmmempool.NewEthSignerExtractionAdapter( - sdkmempool.NewDefaultSignerExtractionAdapter(), - ), - ) - app.SetPrepareProposal(abciProposalHandler.PrepareProposalHandler()) -} -``` - -**Ordering:** After ante handler set -**Dependencies:** VM keeper, FeeMarket keeper, txConfig, clientCtx, ante handler -**Optional:** NO - Required for proper EVM transaction handling - ---- - -#### Component: Module Manager - -1. Register EVM modules: - -```go -app.ModuleManager = module.NewManager( - // ... standard SDK modules - vm.NewAppModule(appCodec, app.EVMKeeper, app.AccountKeeper), - feemarket.NewAppModule(app.FeeMarketKeeper), - erc20.NewAppModule(app.Erc20Keeper, app.AccountKeeper, app.BankKeeper), - precisebank.NewAppModule(app.PreciseBankKeeper, app.AccountKeeper, app.BankKeeper), - transfer.NewAppModule(app.TransferKeeper), // EVM-enhanced version -) -``` - -2. Set Begin/EndBlocker order: - -```go -app.ModuleManager.SetOrderBeginBlockers( - // ... - feemarkettypes.ModuleName, // Update base fee - erc20types.ModuleName, - evmtypes.ModuleName, // Must come after FeeMarket - // ... -) - -app.ModuleManager.SetOrderEndBlockers( - // ... - evmtypes.ModuleName, - erc20types.ModuleName, - feemarkettypes.ModuleName, // Must come last to get full block gas - // ... -) -``` - -**Ordering:** After all keepers and mempool -**Optional:** NO - Required for module lifecycle - ---- - -#### Component: App Lifecycle Methods - -1. Implement required interface methods: - -```go -func (app *App) SetClientCtx(clientCtx client.Context) { - app.clientCtx = clientCtx -} - -func (app *App) RegisterPendingTxListener(listener func(common.Hash)) { - app.pendingTxListeners = append(app.pendingTxListeners, listener) -} - -func (app *App) onPendingTx(hash common.Hash) { - for _, listener := range app.pendingTxListeners { - listener(hash) - } -} - -func (app *App) Close() error { - var err error - if m, ok := app.GetMempool().(*evmmempool.ExperimentalEVMMempool); ok { - err = m.Close() - } - err = errors.Join(err, app.BaseApp.Close()) - msg := "Application gracefully shutdown" - if err == nil { - app.Logger().Info(msg) - } else { - app.Logger().Error(msg, "error", err) - } - return err -} -``` - -**Ordering:** N/A (helper methods) -**Optional:** NO - Required by interfaces - ---- - -## Section 6: Migration Path (v0.4.x → v0.5.0) - -### Component-by-Component Migration - -#### A. Mempool Migration - -**Required Actions:** - -1. Remove `SetGlobalEVMMempool()` call -2. Update `EVMMempoolConfig` structure: - - Remove: `TxPool` field - - Remove: `CosmosPool` field - - Add: `LegacyPoolConfig` (optional) - - Add: `CosmosPoolConfig` (optional) -3. Add `Close()` method to app -4. Update RPC server initialization to pass mempool directly - -**Example Diff:** - -```diff - mempoolConfig := &evmmempool.EVMMempoolConfig{ -- TxPool: customTxPool, -- CosmosPool: customCosmosPool, -+ LegacyPoolConfig: &legacypool.Config{...}, // optional -+ CosmosPoolConfig: &sdkmempool.PriorityNonceMempoolConfig[math.Int]{...}, // optional - AnteHandler: app.GetAnteHandler(), - BlockGasLimit: 100_000_000, - } - - evmMempool := evmmempool.NewExperimentalEVMMempool(...) - app.EVMMempool = evmMempool - -- if err := evmmempool.SetGlobalEVMMempool(evmMempool); err != nil { -- panic(err) -- } - app.SetMempool(evmMempool) -``` - ---- - -#### B. Precompiles Migration - -**Required Actions:** - -1. Update ICS-20 precompile constructor to include `bankKeeper` -2. Update Gov precompile constructor to use msg/query servers + bank + codec -3. Verify address codec options are passed correctly - -**Example Diff:** - -```diff - // ICS-20 Precompile - ibcTransferPrecompile, err := ics20precompile.NewPrecompile( -+ bankKeeper, - stakingKeeper, - transferKeeper, - channelKeeper, - ) - - // Gov Precompile -- govPrecompile, err := govprecompile.NewPrecompile(govKeeper, cdc) -+ govPrecompile, err := govprecompile.NewPrecompile( -+ govkeeper.NewMsgServerImpl(&govKeeper), -+ govkeeper.NewQueryServer(&govKeeper), -+ bankKeeper, -+ codec, -+ options.AddressCodec, -+ ) -``` - ---- - -#### C. VM Parameters Migration - -**Required Actions:** - -1. Remove `allow_unprotected_txs` from genesis -2. Add `history_serve_window` to genesis -3. Remove code referencing `AllowUnprotectedTxs` - -**Genesis Diff:** - -```diff - { - "app_state": { - "vm": { - "params": { - "evm_denom": "atest", - "extra_eips": [], -- "allow_unprotected_txs": false, - "evm_channels": [], - "access_control": {...}, - "active_static_precompiles": [...], -+ "history_serve_window": 8192 - } - } - } - } -``` - ---- - -#### D. App Lifecycle Migration - -**Required Actions:** - -1. Add `Close()` method to app (if not already present from v0.4.x) -2. Add `errors` import - -**Example:** - -```diff -+ import ( -+ "errors" -+ // ... -+ ) - -+ func (app *App) Close() error { -+ var err error -+ if m, ok := app.GetMempool().(*evmmempool.ExperimentalEVMMempool); ok { -+ err = m.Close() -+ } -+ err = errors.Join(err, app.BaseApp.Close()) -+ msg := "Application gracefully shutdown" -+ if err == nil { -+ app.Logger().Info(msg) -+ } else { -+ app.Logger().Error(msg, "error", err) -+ } -+ return err -+ } -``` - ---- - -## Section 7: Mempool Integration Updates - -### Key Changes for Mempool Integration Doc - -1. **Remove Section:** Global mempool registry (`SetGlobalEVMMempool`) - - - This is no longer used in v0.5.0 - - Update docs to show mempool passed to RPC server - -2. **Update Section:** Configuration structure - - - Show new `LegacyPoolConfig` and `CosmosPoolConfig` fields - - Explain that pools are no longer pre-built - -3. **Add Section:** App cleanup - - - Document the `Close()` method requirement - - Explain event bus cleanup - -4. **Update Section:** RPC server initialization - - Show how to pass mempool to RPC server directly - - Remove references to global singleton - -### Updated Configuration Example - -**Current Doc (v0.4.x style):** - -```go -mempoolConfig := &evmmempool.EVMMempoolConfig{ - TxPool: customTxPool, // Build pool yourself - CosmosPool: customCosmosPool, // Build pool yourself - AnteHandler: app.GetAnteHandler(), - BlockGasLimit: 100_000_000, -} -``` - -**Should Be (v0.5.0 style):** - -```go -mempoolConfig := &evmmempool.EVMMempoolConfig{ - // Optional: Customize pool behavior via config - LegacyPoolConfig: &legacypool.Config{ - AccountSlots: 16, - GlobalSlots: 5120, - PriceLimit: 1, - }, - - // Optional: Customize Cosmos mempool - CosmosPoolConfig: &sdkmempool.PriorityNonceMempoolConfig[math.Int]{ - TxPriority: customPriorityConfig, - }, - - // Required - AnteHandler: app.GetAnteHandler(), - BlockGasLimit: 100_000_000, -} -``` - ---- - -## Section 8: Summary of Documentation Changes Needed - -### Fresh Integration Guide - -**Sections to Add:** - -1. Component dependency graph visual -2. Keeper initialization ordering rules -3. Optional vs required components table -4. Step-by-step with ordering annotations - -**Sections to Update:** - -1. Mempool setup (remove global registry) -2. Precompile constructors (updated signatures) -3. App lifecycle methods (add `Close()`) - ---- - -### Migration Guide (v0.4.x → v0.5.0) - -**Sections to Add:** - -1. Mempool refactor section (config-based vs pre-built) -2. VM parameters migration -3. App cleanup lifecycle - -**Sections to Update:** - -1. Precompile migration (ICS-20 + Gov changes) -2. Breaking changes summary (categorize by component) - ---- - -### Mempool Integration Doc - -**Sections to Remove:** - -1. Global mempool registry setup -2. Pre-built pool construction examples - -**Sections to Add:** - -1. Configuration-based approach -2. App `Close()` method -3. RPC server mempool injection - -**Sections to Update:** - -1. Configuration struct documentation -2. Default behaviors -3. Custom configuration examples - ---- - -## Section 9: Key Documentation Principles - -Based on user requirements, the rewritten docs should follow these principles: - -### 1. Component-Based Organization - -**DON'T:** - -``` -- "Change app.go line X" -- "Update app.go here" -- "Modify app.go again" -``` - -**DO:** - -``` -- "Mempool Component: Configure in app.go" -- "Precompiles Component: Register after keepers" -- "Ante Handler Component: Set before mempool" -``` - ---- - -### 2. Ordering Clarity - -**Always Specify:** - -- "Must be initialized BEFORE X" -- "Must come AFTER Y" -- "Order with other modules: [list]" - -**Example:** - -> **PreciseBank Keeper Initialization** -> -> ⚠️ **CRITICAL:** Must be initialized BEFORE the VM keeper. -> -> **Ordering:** -> -> - After: AccountKeeper, BankKeeper -> - Before: VM Keeper -> -> **Why:** VM keeper depends on PreciseBank for 18-decimal token operations. - ---- - -### 3. Optional vs Required Tags - -**Every Component Should Have:** - -``` -✅ REQUIRED - Core EVM functionality -❌ OPTIONAL - Enhanced features -``` - -**Example:** - -> **ICS-20 Transfer Precompile** -> -> ❌ **OPTIONAL** -> -> **Use Case:** Enable IBC token transfers from EVM contracts -> -> **Can Skip If:** Chain doesn't need IBC integration from EVM side - ---- - -### 4. Clear Dependencies - -**Every Component Should List:** - -- **Depends On:** What must exist first -- **Required By:** What needs this component -- **Circular References:** How they're handled - -**Example:** - -> **ERC20 Keeper** -> -> **Depends On:** -> -> - VM Keeper -> - PreciseBank Keeper -> - Account Keeper -> -> **Required By:** -> -> - IBC Transfer Keeper (for token conversions) -> - Bank Precompile (for balance queries) -> -> **Note:** VM keeper has pointer to ERC20 keeper (circular dependency handled via pointer) - ---- - -## Section 10: Next Steps - -### For Integration Guide Rewrite - -1. ✅ Use findings from this document -2. ✅ Create component-based flow diagram -3. ✅ Write component sections with ordering + dependencies -4. ✅ Add optional vs required tables -5. ✅ Include troubleshooting for common ordering mistakes - -### For Migration Guide Rewrite - -1. ✅ Use API changes from Section 1 -2. ✅ Organize by component (Section 2 categorization) -3. ✅ Add before/after code examples -4. ✅ Include upgrade handler reference -5. ✅ Add migration checklist - -### For Mempool Doc Update - -1. ✅ Use mempool changes from Section 1.1, 1.2 -2. ✅ Update configuration structure docs -3. ✅ Remove global registry references -4. ✅ Add `Close()` method docs -5. ✅ Update RPC server initialization - ---- - -## Appendix A: Reference Files - -### evmd v0.5.0-rc.0 Reference Locations - -- **app.go:** `/Users/cordt/repos/evm/evmd/app.go` -- **precompiles.go:** `/Users/cordt/repos/evm/evmd/precompiles.go` -- **ante/evm_handler.go:** `/Users/cordt/repos/evm/evmd/ante/evm_handler.go` -- **upgrades.go:** `/Users/cordt/repos/evm/evmd/upgrades.go` -- **mempool/README.md:** `/Users/cordt/repos/evm/mempool/README.md` -- **mempool/mempool.go:** `/Users/cordt/repos/evm/mempool/mempool.go` - -### Existing Documentation Locations - -- **Fresh Integration Guide:** `/Users/cordt/repos/docs/docs/evm/next/documentation/integration/fresh-v0.5-integration.mdx` -- **Migration Guide:** `/Users/cordt/repos/docs/docs/evm/next/documentation/integration/migration-v0.4-to-v0.5.mdx` -- **Mempool Integration:** `/Users/cordt/repos/docs/docs/evm/next/documentation/getting-started/build-a-chain/additional-configuration/mempool-integration.mdx.mdx` - ---- - -## Appendix B: Quick Reference Tables - -### Keeper Initialization Order - -| Order | Keeper | Must Come After | Must Come Before | -| ----- | ----------------- | --------------------------- | ---------------- | -| 1 | AccountKeeper | - | PreciseBank | -| 2 | BankKeeper | - | PreciseBank | -| 3 | StakingKeeper | AccountKeeper | VM | -| 4 | FeeMarketKeeper | - | VM | -| 5 | PreciseBankKeeper | Account, Bank | VM | -| 6 | VMKeeper | PreciseBank, FeeMarket | ERC20 | -| 7 | Erc20Keeper | VM | Transfer | -| 8 | TransferKeeper | ERC20 | Precompiles | -| 9 | Precompiles | All keepers | Mempool | -| 10 | EVMMempool | Ante handler, VM, FeeMarket | - | - ---- - -### Optional Components Quick Reference - -| Component | Required? | Reason if Optional | -| ----------------------- | --------- | ----------------------------- | -| VM Module | ✅ YES | Core EVM execution | -| FeeMarket Module | ✅ YES | Gas pricing | -| PreciseBank Module | ✅ YES | 18-decimal precision | -| ERC20 Module | ✅ YES | Token interoperability | -| Staking Precompile | ❌ NO | Only if EVM needs staking ops | -| Distribution Precompile | ❌ NO | Only if EVM needs rewards | -| Gov Precompile | ❌ NO | Only if EVM needs governance | -| Slashing Precompile | ❌ NO | Only if EVM needs slashing | -| ICS-20 Precompile | ❌ NO | Only if EVM needs IBC | -| Custom Mempool Config | ❌ NO | Defaults sufficient for most | -| IBC Transfer Override | ❌ NO | Only for ERC20 IBC transfers | - ---- - -### API Breaking Changes Quick Reference - -| Component | Change Type | v0.4.1 | v0.5.0 | -| ----------------- | ------------------ | ---------------------------------- | ------------------------------------------------------------------- | -| Mempool Config | Field Removal | `TxPool *txpool.TxPool` | Removed | -| Mempool Config | Field Removal | `CosmosPool sdkmempool.ExtMempool` | Removed | -| Mempool Config | Field Addition | - | `LegacyPoolConfig *legacypool.Config` | -| Mempool Config | Field Addition | - | `CosmosPoolConfig *sdkmempool.PriorityNonceMempoolConfig[math.Int]` | -| Mempool | Function Removal | `SetGlobalEVMMempool()` | Removed | -| App | Method Addition | - | `Close() error` | -| ICS-20 Precompile | Constructor Change | 3 params | 4 params (added `bankKeeper`) | -| Gov Precompile | Constructor Change | 2 params | 5 params (msg/query servers + bank + codec) | -| VM Params | Parameter Removal | `allow_unprotected_txs` | Removed | -| VM Params | Parameter Addition | - | `history_serve_window` | - ---- - -**End of Findings Document** 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 index f0e1731e..7a5bcb9e 100644 --- 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 @@ -425,9 +425,9 @@ make build **Description**: The EIP-155 chain ID used for Ethereum transaction replay protection. -**Default**: `262144` (in older code) or `999888` (in current config/config.go) +**Default**: `262144` -**File Location**: [`config/config.go:78`](https://github.com/cosmos/evm/blob/main/config/config.go#L77-L78) +**File Location**: [`server/config/config.go:65`](https://github.com/cosmos/evm/blob/main/server/config/config.go#L64-L65) **Why Change It**: Must be unique for your network to prevent transaction replay attacks. @@ -436,24 +436,20 @@ The EVM Chain ID **cannot** be changed after genesis without breaking all transa - -Edit `config/config.go` and change the `EVMChainID` constant: + +Edit `server/config/config.go` and change the `DefaultEVMChainID` value: ```go expandable -const ( - // EVMChainID defines the EIP-155 replay-protection chain id - EVMChainID = 123456 // Change to your unique chain ID -) +// DefaultEVMChainID is the default EVM Chain ID if one is not provided +DefaultEVMChainID = 123456 // Change to your unique chain ID ``` -**This value is used during `yourchain init`** to populate the `evm-chain-id` field in `app.toml`. - **After changing, rebuild:** ```bash expandable make build ``` -**Then initialize (the chain ID will be embedded):** +**Then initialize (your custom chain ID will be written to app.toml):** ```bash expandable ./build/yourchain init mynode --chain-id mychain-1 ``` @@ -461,10 +457,30 @@ make build **Verify it was set correctly:** ```bash expandable grep 'evm-chain-id' ~/.yourchain/config/app.toml -# Should show: evm-chain-id = "123456" +# Should show: evm-chain-id = 123456 ``` + +Alternatively, just edit `app.toml` directly after running init: + +```bash expandable +# Initialize with default +yourchain init mynode --chain-id mychain-1 + +# Then edit app.toml +# Change evm-chain-id = 262144 to your desired chain ID +``` + +**Edit `~/.yourchain/config/app.toml`:** +```toml expandable +[evm] +evm-chain-id = 123456 # Your unique chain ID +``` + +**This approach is simpler if you're only changing the chain ID without other source code modifications.** + + **Requirements:** - Must be a unique integer @@ -889,7 +905,11 @@ The Cosmos Chain ID is typically set during initialization: yourchain init mynode --chain-id mychain-1 ``` -This writes the chain ID to both `genesis.json` and `client.toml`. +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 +``` From bb7b69d5206a582fffb08d45d7ed14fcbf889efa Mon Sep 17 00:00:00 2001 From: Cordt Date: Wed, 15 Oct 2025 23:23:15 -0600 Subject: [PATCH 6/6] misc. cleanup and reorg of older content --- docs.json | 6 +- .../documentation/cosmos-sdk/modules/ibc.mdx | 3 +- .../pre-genesis-and-genesis-setup.mdx | 67 +++++------ .../build-a-chain/runtime-and-launch.mdx | 110 +----------------- .../documentation/getting-started/index.mdx | 2 +- .../getting-started/local-node-setup.mdx | 22 +--- .../getting-started/reference-network.mdx | 76 ------------ .../development-environment.mdx | 0 docs/evm/next/documentation/overview.mdx | 6 + 9 files changed, 45 insertions(+), 247 deletions(-) delete mode 100644 docs/evm/next/documentation/getting-started/reference-network.mdx rename docs/evm/next/documentation/getting-started/{ => tooling-and-resources}/development-environment.mdx (100%) diff --git a/docs.json b/docs.json index 70f14b57..7f56dfd4 100644 --- a/docs.json +++ b/docs.json @@ -215,14 +215,14 @@ }, "docs/evm/next/documentation/getting-started/local-node-setup", "docs/evm/next/documentation/getting-started/index", - "docs/evm/next/documentation/getting-started/reference-network", - "docs/evm/next/documentation/getting-started/faq", - "docs/evm/next/documentation/getting-started/development-environment" ] + "docs/evm/next/documentation/getting-started/faq" + ] }, { "group": "Tooling and Resources", "pages": [ "docs/evm/next/documentation/getting-started/tooling-and-resources/overview", + "docs/evm/next/documentation/getting-started/tooling-and-resources/development-environment", "docs/evm/next/documentation/getting-started/tooling-and-resources/block-explorers", "docs/evm/next/documentation/getting-started/tooling-and-resources/foundry", "docs/evm/next/documentation/getting-started/tooling-and-resources/hardhat", diff --git a/docs/evm/next/documentation/cosmos-sdk/modules/ibc.mdx b/docs/evm/next/documentation/cosmos-sdk/modules/ibc.mdx index 1e6fec70..b15423cb 100644 --- a/docs/evm/next/documentation/cosmos-sdk/modules/ibc.mdx +++ b/docs/evm/next/documentation/cosmos-sdk/modules/ibc.mdx @@ -1,7 +1,6 @@ --- title: "IBC" description: "Inter-Blockchain Communication protocol implementation with EVM callbacks" -icon: "chevrons-left-right-ellipsis" --- The `x/ibc` module from [cosmos/evm](https://github.com/cosmos/evm) implements Inter-Blockchain Communication (IBC) protocol support with specialized EVM callback functionality for cross-chain smart contract interactions. @@ -68,7 +67,7 @@ EVM callbacks use the `memo` field in ICS-20 transfers with specific JSON struct { "dest_callback": { "address": "0x...", - "gas_limit": "1000000", + "gas_limit": "1000000", "calldata": "0x..." } } 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 index 7a5bcb9e..382f01e9 100644 --- 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 @@ -165,8 +165,8 @@ find . -type f -name "*.go" -exec sed -i '' \ # 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 +# From: module github.com/cosmos/evm +# To: module github.com/your-org/your-chain # 5. Update Makefile sed -i '' 's/evmd/yourchain/g' Makefile @@ -194,10 +194,10 @@ find . -type f -name "*.go" -exec sed -i '' \ **3. Update `go.mod` module declaration:** ```go expandable -// FROM: +// From: module github.com/cosmos/evm -// TO: +// To: module github.com/your-org/your-chain ``` @@ -427,58 +427,46 @@ make build **Default**: `262144` -**File Location**: [`server/config/config.go:65`](https://github.com/cosmos/evm/blob/main/server/config/config.go#L64-L65) +**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 **cannot** be changed after genesis without breaking all transaction signatures and wallet compatibility. Choose carefully before launch. +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. - -Edit `server/config/config.go` and change the `DefaultEVMChainID` value: + +**1. Edit `config/config.go` and change the `EVMChainID` constant:** ```go expandable -// DefaultEVMChainID is the default EVM Chain ID if one is not provided -DefaultEVMChainID = 123456 // Change to your unique chain ID +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 +) ``` -**After changing, rebuild:** +**2. Rebuild the binary:** ```bash expandable make build ``` -**Then initialize (your custom chain ID will be written to app.toml):** +**3. Initialize your chain:** ```bash expandable ./build/yourchain init mynode --chain-id mychain-1 ``` -**Verify it was set correctly:** +**4. Verify the chain ID was set correctly:** ```bash expandable grep 'evm-chain-id' ~/.yourchain/config/app.toml # Should show: evm-chain-id = 123456 ``` - - - -Alternatively, just edit `app.toml` directly after running init: - -```bash expandable -# Initialize with default -yourchain init mynode --chain-id mychain-1 - -# Then edit app.toml -# Change evm-chain-id = 262144 to your desired chain ID -``` - -**Edit `~/.yourchain/config/app.toml`:** -```toml expandable -[evm] -evm-chain-id = 123456 # Your unique chain ID -``` -**This approach is simpler if you're only changing the chain ID without other source code modifications.** + +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. + @@ -545,7 +533,7 @@ const tx = { -**Source**: [config/config.go:77-78](https://github.com/cosmos/evm/blob/main/config/config.go#L77-L78) +**Source**: [config/config.go:78](https://github.com/cosmos/evm/blob/main/config/config.go#L78) @@ -729,10 +717,10 @@ This step must be completed **before** running `yourchain init`. The defaults ar **Change:** ```toml expandable -# FROM: +# From: minimum-gas-prices = "0aatom" -# TO: +# To: minimum-gas-prices = "0atoken" ``` @@ -741,14 +729,14 @@ minimum-gas-prices = "0atoken" **Change:** ```go expandable -// FROM: +// From: var ( DefaultEVMDenom = "uatom" DefaultEVMExtendedDenom = "aatom" DefaultEVMDisplayDenom = "atom" ) -// TO: +// To: var ( DefaultEVMDenom = "atoken" // Your base denom DefaultEVMExtendedDenom = "atoken" // Same if 18 decimals @@ -761,13 +749,13 @@ var ( **Change:** ```go expandable -// FROM: +// From: const ( ExampleChainDenom = "aatom" ExampleDisplayDenom = "atom" ) -// TO: +// To: const ( ExampleChainDenom = "atoken" ExampleDisplayDenom = "token" @@ -2081,4 +2069,3 @@ Continue to [Runtime Configuration & Network Launch](/docs/evm/next/documentatio - Command cheatsheets - Configuration examples - Default values table -- Troubleshooting guide 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 index 3c030e5d..931aee02 100644 --- 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 @@ -141,7 +141,7 @@ http-timeout = "30s" # HTTP idle timeout http-idle-timeout = "2m0s" -# Allow unprotected transactions (ONLY FOR DEV) +# Allow unprotected transactions (only for development) allow-unprotected-txs = false # Maximum open connections (0 = unlimited) @@ -223,7 +223,7 @@ block-range-cap = 10000 ```toml expandable [evm] # EVM chain ID (set during init from config/config.go) -# DO NOT MODIFY - change in source code before init +# Do not modify - change in source code before init evm-chain-id = 262144 # Tracer type for debugging @@ -242,10 +242,10 @@ min-tip = 0 -**1. `evm-chain-id`** (uint64) - **READ-ONLY** +**1. `evm-chain-id`** (uint64) - **Read-only** - Automatically written during `yourchain init` - Value from `config/config.go:78` -- **DO NOT MODIFY** in app.toml +- Do not modify in app.toml - To change: Edit source code and rebuild before init **2. `tracer`** (string) @@ -736,19 +736,6 @@ jq -S -c . ~/.yourchain/config/genesis.json | shasum -a 256 - Report matching hash on official communication channel - Proceed only when all validators confirm - - -**If hashes don't match:** - -1. **Check whitespace**: Use `jq -S -c` to normalize -2. **Re-download**: Get genesis file again -3. **Verify source**: Ensure downloading from official source -4. **Check corruption**: File may be corrupted in transfer - -**Even one character difference = different genesis state** - -All validators must have byte-for-byte identical files. - @@ -1195,94 +1182,6 @@ yourchain start -## Troubleshooting - -### Common Launch Issues - - - -**Error: `invalid chain-id on InitChain`** - -**Solution:** -```bash expandable -# Verify chain IDs match -jq '.chain_id' ~/.yourchain/config/genesis.json -grep 'chain-id' ~/.yourchain/config/client.toml - -# Set if missing -yourchain config set client chain-id mychain-1 -``` - -**Error: `genesis.json file not found`** - -**Solution:** -```bash expandable -# Verify file exists -ls ~/.yourchain/config/genesis.json - -# Re-download if missing -``` - - - -**Check P2P configuration:** - -```bash expandable -# Verify persistent_peers in config.toml -grep 'persistent_peers' ~/.yourchain/config/config.toml - -# Check node ID is correct -yourchain comet show-node-id - -# Test network connectivity -nc -zv 26656 -``` - -**Check firewall:** -```bash expandable -# Port 26656 must be open for P2P -sudo ufw status -sudo ufw allow 26656 -``` - - - -**If validators have different genesis files:** - -1. **Stop all nodes** -2. **Coordinator distributes canonical genesis** -3. **All validators re-verify hash** -4. **Restart launch process** - -**Prevention:** -- Use checksums -- Distribute via secure channel -- Verify before launch - - - -**Check validator participation:** - -```bash expandable -# Check number of online validators -curl localhost:26657/validators | jq '.result.validators | length' - -# Check total voting power -curl localhost:26657/validators | \ - jq '[.result.validators[].voting_power | tonumber] | add' -``` - -**Need >=2/3 voting power online for consensus.** - -**If insufficient:** -- Wait for more validators to come online -- Verify genesis file distributed -- Check validator connectivity - - - - - ## Next Steps Your chain is now launched and operational! @@ -1308,6 +1207,5 @@ This guide covered: - ✅ Genesis file distribution and verification - ✅ Node startup and monitoring - ✅ Post-launch operations and maintenance -- ✅ Troubleshooting common issues 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/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.