Skip to content

Restructuring: "Build Your Own Chain" content #101

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
Oct 16, 2025
Merged

Restructuring: "Build Your Own Chain" content #101

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
03185a2
finalize build chain docs
Cordtus Oct 15, 2025
024566b
remove syntax breaking --- from all files
Cordtus Oct 15, 2025
04dbfff
make all codeblocks expandable, and various cleanup
Cordtus Oct 15, 2025
1f1c138
first pass major cleanup to build docs
Cordtus Oct 15, 2025
e53e367
fix some slop
Cordtus Oct 16, 2025
bb7b69d
misc. cleanup and reorg of older content
Cordtus Oct 16, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
911 changes: 0 additions & 911 deletions V0.5_COMMIT_ANALYSIS.md
View file
Open in desktop

This file was deleted.

1,341 changes: 0 additions & 1,341 deletions V0.5_INTEGRATION_PREP_FINDINGS.md
View file
Open in desktop

This file was deleted.

28 changes: 14 additions & 14 deletions docs.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -200,29 +200,29 @@
{
"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",
"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",
Expand Down
3 changes: 1 addition & 2 deletions docs/evm/next/documentation/cosmos-sdk/modules/ibc.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
Expand Down Expand Up @@ -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..."
}
}
Expand Down
51 changes: 25 additions & 26 deletions .../getting-started/build-a-chain/additional-configuration/mempool-integration.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,9 +9,8 @@ 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
```go expandable
// Update your app/app.go to include the EVM mempool
type App struct {
*baseapp.BaseApp
// ... other keepers
Expand All @@ -31,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:

<Expandable title="View EVM mempool initialization code">
```go
```go expandable
// Set the EVM priority nonce mempool
if evmtypes.GetChainConfig() != nil {
mempoolConfig := &evmmempool.EVMMempoolConfig{
Expand Down Expand Up @@ -68,7 +66,6 @@ if evmtypes.GetChainConfig() != nil {
app.SetPrepareProposal(abciProposalHandler.PrepareProposalHandler())
}
```
</Expandable>

<Warning>
**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.
Expand All @@ -78,20 +75,20 @@ if evmtypes.GetChainConfig() != nil {

The `EVMMempoolConfig` struct provides several configuration options for customizing the mempool behavior:

### Minimal Configuration

<Tabs>
<Tab title="Minimal Configuration">
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
}
```
</Tab>

### Full Configuration Options

```go
<Tab title="Full Configuration Options">
```go expandable
type EVMMempoolConfig struct {
// Required: AnteHandler for transaction validation
AnteHandler sdk.AnteHandler
Expand All @@ -112,6 +109,8 @@ type EVMMempoolConfig struct {
MinTip *uint256.Int
}
```
</Tab>
</Tabs>

#### Defaults and Fallbacks

Expand All @@ -137,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
Expand All @@ -153,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
Expand All @@ -163,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)
Expand All @@ -176,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)
Expand All @@ -194,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]{
Expand Down Expand Up @@ -229,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
Expand All @@ -241,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(),
Expand All @@ -253,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())
Expand All @@ -280,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)
Expand All @@ -303,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
```
Expand All @@ -327,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
Expand All @@ -348,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)
Expand All @@ -359,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,
Expand All @@ -378,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);
Expand Down
Loading