docs(migration): boilerplate v0.5.0 migration docs with mempool migra… (cosmos#540)

* docs(migration): boilerplate v0.5.0 migration docs with mempool migration

* shorten line

* Update docs/migrations/v0.4.0_to_v0.5.0_UNRELEASED.md

---------

Co-authored-by: Alex | Interchain Labs <[email protected]>

Author: vladjdk

docs/migrations/v0.4.0_to_v0.5.0_UNRELEASED.md

@@ -0,0 +1,94 @@
+# Cosmos EVM v0.4.0 → v0.5.0 Migration (UNRELEASED)
+
+## 0) Prep
+
+- Create a branch: `git switch -c upgrade/evm-v0.5`.
+- Ensure a clean build + tests green pre-upgrade.
+- Snapshot your current params/genesis for comparison later.
+
+---
+
+## 1) Dependency bumps (go.mod)
+
+- Bump `github.com/cosmos/evm` to v0.5.0 and run:
+
+```bash
+go mod tidy
+```
+
+---
+
+## 2) App wiring in `app.go`
+
+### Mempool
+
+#### Minimal setups: nothing to change
+
+If you use the default mempool wiring (no custom pools), your existing code continues to work. If `BlockGasLimit` is 0, it defaults to `100_000_000`. If `BroadCastTxFn` is not set, it's also set to a default value.
+
+```go
+mempoolConfig := &evmmempool.EVMMempoolConfig{
+    AnteHandler:   app.GetAnteHandler(),
+    BlockGasLimit: 100_000_000, // or 0 to use default
+}
+evmMempool := evmmempool.NewExperimentalEVMMempool(
+    app.CreateQueryContext, logger, app.EVMKeeper, app.FeeMarketKeeper, app.txConfig, app.clientCtx, mempoolConfig
+)
+```
+
+#### Advanced setups: migrate your customizations
+
+PR [#496](https://github.com/cosmos/evm/pull/496) replaced pre-built pools with configs in `EVMMempoolConfig`:
+
+- Replace pools with configs
+  - Removed: `TxPool *txpool.TxPool`, `CosmosPool sdkmempool.ExtMempool`
+  - Added: `LegacyPoolConfig *legacypool.Config`, `CosmosPoolConfig *sdkmempool.PriorityNonceMempoolConfig[math.Int]`
+
+If you built custom pools yourself:
+
+```diff
+ mempoolConfig := &evmmempool.EVMMempoolConfig{
+-   TxPool:     customTxPool,
+-   CosmosPool: customCosmosPool,
++   LegacyPoolConfig: &legacyCfg,  // or nil for defaults
++   CosmosPoolConfig: &cosmosCfg,  // or nil for defaults
+   AnteHandler:      app.GetAnteHandler(),
+   BroadCastTxFn:    myBroadcast, // optional
+ }
+```
+
+Example custom configs:
+
+```go
+// EVM legacy txpool tuning
+legacyCfg := legacypool.DefaultConfig
+legacyCfg.PriceLimit = 2
+mempoolConfig.LegacyPoolConfig = &legacyCfg
+
+// Cosmos priority mempool tuning
+cosmosCfg := sdkmempool.PriorityNonceMempoolConfig[math.Int]{}
+cosmosCfg.TxPriority = sdkmempool.TxPriority[math.Int]{
+    GetTxPriority: func(goCtx context.Context, tx sdk.Tx) math.Int {
+        // Custom priority function
+    },
+    Compare:  func(a, b math.Int) int { return a.BigInt().Cmp(b.BigInt()) },
+    MinValue: math.ZeroInt(),
+}
+mempoolConfig.CosmosPoolConfig = &cosmosCfg
+
+// Custom EVM broadcast (optional)
+mempoolConfig.BroadCastTxFn = func(txs []*ethtypes.Transaction) error { return nil }
+```
+
+---
+
+## 3) Build & quick tests
+
+```bash
+go build ./...
+```
+
+Smoke test on a single node:
+- Send a few EVM txs; confirm promotion/broadcast (or your `BroadCastTxFn`).
+- Send Cosmos txs; confirm ordering reflects your `CosmosPoolConfig` (if customized).
+