diff --git a/docs.json b/docs.json index 9471d318..e3eabc74 100644 --- a/docs.json +++ b/docs.json @@ -200,9 +200,7 @@ { "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/chain-customization-checklist", - "docs/evm/next/documentation/getting-started/build-a-chain/building-your-chain-guide", + "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/configuration-parameters", "docs/evm/next/documentation/getting-started/build-a-chain/token-configuration-guide", { diff --git a/docs/evm/next/documentation/concepts/chain-id.mdx b/docs/evm/next/documentation/concepts/chain-id.mdx index c72991ad..82193a08 100644 --- a/docs/evm/next/documentation/concepts/chain-id.mdx +++ b/docs/evm/next/documentation/concepts/chain-id.mdx @@ -10,7 +10,7 @@ icon: "fingerprint" ## Dual Chain ID System -Cosmos EVM requires **two separate chain IDs** to maintain full compatibility with both the Cosmos SDK and Ethereum ecosystems: +Cosmos EVM requires **two completely independent chain IDs** to maintain full compatibility with both the Cosmos SDK and Ethereum ecosystems. ### 1. Cosmos Chain ID (String) @@ -20,13 +20,13 @@ The **Cosmos Chain ID** is a string identifier used by: - Native Cosmos SDK transactions - Chain upgrades and governance -**Format**: String with flexible naming (e.g., `"cosmosevm-1"`, `"mychain-testnet-2"`) +**Format**: Any string (recommended format: `"mychain-1"`, `"testnet-2"`) **Example**: ```json // In genesis.json { - "chain_id": "cosmosevm-1" + "chain_id": "mychain-1" } ``` @@ -38,12 +38,13 @@ The **EVM Chain ID** is an integer used by: - Smart contract deployments - EVM tooling (Hardhat, Foundry, etc.) -**Format**: Positive integer (e.g., `9000`, `9001`) +**Format**: Any unique positive integer (check [chainlist.org](https://chainlist.org)) **Example**: -```go -// In app/app.go -const EVMChainID = 9000 +```toml +# In app.toml +[evm] +chain-id = 262144 ``` ## Configuration @@ -78,23 +79,12 @@ evmtypes.DefaultChainConfig(9000) // Your EVM Chain ID ## Important Considerations -### Chain ID Selection - - -The two chain IDs serve different purposes and **must not be confused**: -- Use the **Cosmos Chain ID** (string) for IBC connections, governance proposals, and Cosmos SDK operations -- Use the **EVM Chain ID** (integer) for MetaMask configuration, smart contract deployments, and EIP-155 transaction signing - - ### EVM Chain ID Guidelines When selecting your EVM Chain ID: 1. **Check availability**: Verify your chosen ID is not already in use on [chainlist.org](https://chainlist.org/) 2. **Avoid conflicts**: Don't use well-known chain IDs (1 for Ethereum mainnet, 137 for Polygon, etc.) -3. **Consider ranges**: - - Production networks often use lower numbers - - Testnets commonly use higher ranges (9000+) - - Local development can use very high numbers (31337+) +3. **Choose any available integer**: There are no required ranges or formats - simply pick any integer not in use ### Chain Upgrades @@ -104,17 +94,6 @@ Unlike traditional Cosmos chains that change their chain ID during upgrades (e.g Only the Cosmos Chain ID may change during chain upgrades if needed for consensus-breaking changes. The EVM Chain ID should never change once set. -## Examples - -Here are some example configurations: - -| Network Type | Cosmos Chain ID | EVM Chain ID | Notes | -|-------------|-----------------|--------------|-------| -| Mainnet | `"cosmosevm-1"` | `9000` | Production network | -| Testnet | `"cosmosevm-testnet-1"` | `9001` | Public testnet | -| Devnet | `"cosmosevm-dev-1"` | `9002` | Development network | -| Local | `"cosmosevm-local-1"` | `31337` | Local development | - ## Troubleshooting ### Common Issues diff --git a/docs/evm/next/documentation/custom-improvement-proposals.mdx b/docs/evm/next/documentation/custom-improvement-proposals.mdx index 6d723daa..9def6b78 100644 --- a/docs/evm/next/documentation/custom-improvement-proposals.mdx +++ b/docs/evm/next/documentation/custom-improvement-proposals.mdx @@ -1,6 +1,6 @@ --- title: "Custom Improvement Proposals" -description: "With the release a new feature called custom improvement proposals has been introduced in the Cosmos EVM framework. Custom improvement proposals allow protocol developers to modify the behavior of the EVM opcodes to tailor their functionalities to the specific needs." +description: "Cosmos EVM allows protocol developers to register custom EIP activators that modify EVM behavior. This advanced feature enables chains to enable additional Ethereum Improvement Proposals or create chain-specific EVM modifications when needed." --- ## Operations[​](#operations "Direct link to Operations") 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 index c13b45f9..d3f22698 100644 --- 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 @@ -92,13 +92,12 @@ The example chain (`evmd`) comes with the following default configuration: | Option | Value | Description | |---------------------|------------------------|-------------| | **Binary** | `evmd` | The compiled chain binary name | -| **Chain ID** | `cosmos_262144-1` | Default Cosmos chain ID (format: `name_evmChainID-version`) | -| **EVM Chain ID** | `262144` | EVM chain ID for transaction replay protection | -| **Custom Opcodes** | - | No custom opcodes by default | +| **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 nine static precompiles are enabled by default | +| **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. 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 34a9a817..00498d49 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 @@ -16,13 +16,12 @@ The reference implementation (`evmd`) comes with these defaults: | Configuration | Default Value | Customizable | |---------------|---------------|--------------| | **Binary Name** | `evmd` | ✓ Yes (rename) | -| **Cosmos Chain ID** | `cosmos_262144-1` | ✓ Yes (genesis) | -| **EVM Chain ID** | `262144` | ✓ Yes (genesis) | -| **Custom Opcodes** | None | ✓ Yes (advanced) | +| **Cosmos Chain ID** | User-defined (string) | ✓ Yes (genesis) | +| **EVM Chain ID** | `262144` | ✓ Yes (app.toml) | | **Token Pairs** | 1 (native token) | ✓ Yes (genesis) | | **Denomination** | `atest` (18 decimals) | ✓ Yes (genesis) | | **EVM Permissioning** | Permissionless | ✓ Yes (genesis) | -| **Enabled Precompiles** | All 9 precompiles | ✓ Yes (genesis) | +| **Enabled Precompiles** | All precompiles | ✓ Yes (genesis) | Let's configure each of these for your custom chain. @@ -89,156 +88,139 @@ After renaming, your binary will be `yourchain` instead of `evmd`. All CLI comma ## 2. Cosmos Chain ID -**What It Is**: The unique identifier for your blockchain in the Cosmos ecosystem. Used for IBC connections and governance. +**What It Is**: The unique string identifier for your blockchain in the Cosmos ecosystem. Used for CometBFT consensus, IBC connections, and governance. -**Default**: `cosmos_262144-1` - -**Format**: `{name}_{evmChainID}-{version}` +**Format**: String with flexible naming (e.g., `"cosmosevm-1"`, `"mychain-testnet-2"`) ### How to Change Set during chain initialization: ```bash -yourchain init mynode --chain-id yourchain_262144-1 +yourchain init mynode --chain-id mychain-1 ``` **Recommended Formats**: -- Testnet: `yourchain_262144-1` -- Mainnet: `yourchain-1` (after registering a unique EVM chain ID) +- Mainnet: `mychain-1` (increment version for major upgrades) +- Testnet: `mychain-testnet-1` +- Local: Any unique string - -The Cosmos chain ID is separate from the EVM chain ID. The format `name_evmChainID-version` helps maintain consistency between both IDs, but it's not required. - +**Important**: The Cosmos chain ID can be **any string**. While the format `{name}-{number}` is canonical for IBC client upgrades, you have full flexibility in choosing your identifier. ### Changing After Genesis -While technically possible through a coordinated upgrade, changing the Cosmos chain ID requires all nodes to update and restart simultaneously. Plan your chain ID carefully before launch. +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 -**What It Is**: The EIP-155 chain ID used for Ethereum transaction replay protection. +**What It Is**: The EIP-155 integer used for Ethereum transaction replay protection. This is what Ethereum wallets (MetaMask, etc.) use to identify your network. **Default**: `262144` -**Where Configured**: Retrieved from app options in `app.go` - ### How to Change -The EVM chain ID **cannot** be changed after genesis without breaking transaction replay protection. Choose carefully before launch. +The EVM chain ID **cannot** be changed after genesis without breaking transaction replay protection and wallet compatibility. Choose carefully before launch. -The EVM chain ID is retrieved from app options in `app.go`: - -```go -// evmd/app.go line ~216 -evmChainID := cast.ToUint64(appOpts.Get(srvflags.EVMChainID)) +Configure it in `app.toml`: +```toml +[evm] +chain-id = 262144 ``` -You can set it via CLI flag when starting the chain: +Or via CLI flag when starting the chain: ```bash yourchain start --evm.chain-id 262144 ``` -Or configure it in `app.toml`: -```toml -[evm] -chain-id = 262144 -``` - ### Choosing an EVM Chain ID +**Choose any integer that isn't already taken on [chainlist.org](https://chainlist.org)** + -**Avoid these ranges**: +**Avoid these**: - `1` - Ethereum Mainnet -- `2-10` - Ethereum testnets -- `1-999` - Generally reserved by Ethereum Foundation - `137` - Polygon -- Common production chains - Check [chainlist.org](https://chainlist.org) +- `56` - BNB Chain +- Check [chainlist.org](https://chainlist.org) for all registered chains **For local development and testnets**: - Use `262144` (evmd default) -- Or any high number unlikely to conflict +- Or any unique high number - No registration needed **For mainnet launches**: -- Choose a unique ID > 1,000,000 +- Choose a unique integer not in use - Register at [chainlist.org](https://chainlist.org) -- Verify no conflicts with existing chains -- Document your choice publicly +- Verify no conflicts +- Document publicly --- -## 4. Custom Opcodes - -**What It Is**: Custom EVM operations beyond standard Ethereum opcodes. +## 4. EIP Integration -**Default**: None +**What It Is**: Enable additional Ethereum Improvement Proposals (EIPs) that aren't activated by default in the EVM configuration. - -Custom opcodes are an advanced feature. Most chains should use standard Ethereum opcodes with the optional `extra_eips` parameter instead. - +**Default**: Empty list (no extra EIPs enabled) -### Adding Extra EIPs +### How to Configure -Instead of custom opcodes, enable additional Ethereum Improvement Proposals: +Enable additional EIPs in genesis: ```json { "app_state": { "vm": { "params": { - "extra_eips": [2200, 2929, 3198] + "extra_eips": [] } } } } ``` -**Common EIPs**: -- `2200` - Net gas metering -- `2929` - Gas cost increases for state access -- `3198` - BASEFEE opcode -- `3529` - Reduction in refunds - - -For teams that need custom EVM functionality: + +The `extra_eips` parameter allows enabling standard Ethereum EIPs that aren't included in the default chain configuration. Most chains can leave this empty and use the standard EVM feature set. + -1. Create activator functions in your chain's `eips/` directory -2. Register in the activators map -3. Add to `extra_eips` in genesis +### When to Use Extra EIPs -```go -// yourchain/eips/custom.go -func ActivateMyCustomOpcode(jt *vm.JumpTable) { - // Define custom opcode behavior -} + + +**Most chains should use the default empty configuration**: -// Register in activators -var CustomActivators = map[int]func(*vm.JumpTable){ - 9999: ActivateMyCustomOpcode, +```json +{ + "extra_eips": [] } ``` -Then in genesis: +The default EVM configuration includes all commonly-used Ethereum features up through the Cancun upgrade. + + + +**Enable specific EIPs if your chain requires them**: + +For example, to enable additional EIP-1153 (transient storage): ```json { - "extra_eips": [9999] + "extra_eips": [1153] } ``` -This is rarely needed - consider if standard EVM functionality meets your needs first. - +Only add EIPs if you have a specific technical requirement for functionality not in the default configuration. + + --- @@ -684,7 +666,7 @@ Most Ethereum-compatible chains should keep EIP-1559 enabled (default) for bette **What It Is**: Native Cosmos SDK functionality exposed as EVM smart contracts. -**Default**: All 9 static precompiles enabled +**Default**: All static precompiles enabled ### Available Precompiles @@ -779,10 +761,6 @@ func NewDefaultVMGenesisState() *vmtypes.GenesisState { - -**Security Consideration**: Only enable precompiles your chain actually needs. Each enabled precompile increases the attack surface and testing complexity. - - ### Modifying After Genesis Precompiles can be enabled or disabled through governance: @@ -894,10 +872,10 @@ The `local_node.sh` script performs all the configuration steps automatically. H The script modifies `genesis.json` to configure: -- **Chain ID**: Sets to `cosmos_262144-1` +- **Cosmos Chain ID**: Sets a development chain ID - **Token denomination**: Configures `atest` (18 decimals) across all modules - **Bank metadata**: Sets up denom metadata with proper exponents -- **Precompiles**: Enables all 9 static precompiles by default +- **Precompiles**: Enables all static precompiles by default - **Validator configuration**: Creates genesis validator with initial stake - **Genesis accounts**: Funds test accounts for development 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 2b93d829..97fb4cc8 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 @@ -5,14 +5,7 @@ description: "Everything you need to build your own custom blockchain with full ## Quick Start - - - Step-by-step checklist covering all phases from pre-genesis to post-launch - +