add erc20 migration guide (#485)

Author: Cordtus

docs/migrations/v0.3.0_to_v0.4.0.md

@@ -7,6 +7,7 @@
 - [ ] Bump **`cosmos/evm` to v0.4.0** and align **Cosmos SDK / IBC / CometBFT** constraints.
 - [ ] Rewire **keepers** and **AppModule** (imports, constructors, `RegisterServices`).
 - [ ] Audit and migrate **EVM & FeeMarket params** (EIP-1559 knobs, denom/decimals).
+- [ ] Migrate existing **ERC20 dynamic/native precompiles** to new storage format (see Section 9).
 - [ ] Implement **store/params migrations** in your **UpgradeHandler**.
 
 ---
@@ -135,7 +136,7 @@ Add a public method to register a listener by `txHash`:
 
 ```go
 // from "github.com/ethereum/go-ethereum/common")) {
-func (app *MyApp) RegisterPendingTxListener(listener func(common.Hash 
+func (app *MyApp) RegisterPendingTxListener(listener func(common.Hash
     app.pendingTxListeners = append(app.pendingTxListeners, listener)
 }
 ```
@@ -174,25 +175,25 @@ func defaultOptionals() Optionals {
 		// from addresscodec "github.com/cosmos/cosmos-sdk/codec/address"(sdk.GetConfig()
 		// from sdk "github.com/cosmos/cosmos-sdk/types".GetBech32ValidatorAddrPrefix()),
         ValidatorAddrCodec: addresscodec.NewBech32Codec
-		// from addresscodec "github.com/cosmos/cosmos-sdk/codec/address"(sdk.GetConfig() 
+		// from addresscodec "github.com/cosmos/cosmos-sdk/codec/address"(sdk.GetConfig()
 		// from sdk "github.com/cosmos/cosmos-sdk/types".GetBech32ConsensusAddrPrefix()),
         ConsensusAddrCodec: addresscodec.NewBech32Codec
     }
 }
 
 type Option func(*Optionals)
 
-// from "cosmossdk.io/core/address") 
+// from "cosmossdk.io/core/address")
 // Option { return func(o *Optionals){ o.AddressCodec = c } }
-func WithAddressCodec(c address.Codec 
+func WithAddressCodec(c address.Codec
 
-// from "cosmossdk.io/core/address") 
+// from "cosmossdk.io/core/address")
 // Option { return func(o *Optionals){ o.ValidatorAddrCodec = c } }
-func WithValidatorAddrCodec(c address.Codec 
+func WithValidatorAddrCodec(c address.Codec
 
-// from "cosmossdk.io/core/address") 
+// from "cosmossdk.io/core/address")
 // Option { return func(o *Optionals){ o.ConsensusAddrCodec = c } }
-func WithConsensusAddrCodec(c address.Codec 
+func WithConsensusAddrCodec(c address.Codec
 ```
 
 ### 4.3 Update the precompile factory to accept options
@@ -232,9 +233,9 @@ func WithConsensusAddrCodec(c address.Codec
 *(app/keepers/precompiles.go)*
 
 ```diff
-- govPrecompile, err := govprecompile.NewPrecompile 
+- govPrecompile, err := govprecompile.NewPrecompile
 -     // from govprecompile "github.com/cosmos/evm/precompiles/gov"(govKeeper, cdc)
-+ govPrecompile, err := govprecompile.NewPrecompile 
++ govPrecompile, err := govprecompile.NewPrecompile
 +     // from govprecompile "github.com/cosmos/evm/precompiles/gov"(govKeeper, cdc, options.AddressCodec)
 ```
 
@@ -333,7 +334,41 @@ pcs := NewAvailableStaticPrecompiles(ctx, /* ... keepers ... */, opts...)
 
 ---
 
-## 9) Verify before tagging
+## 9) ERC20 Precompiles Migration
+
+**This is a breaking change for chains with existing ERC20 token pairs.**
+
+The storage mechanism for ERC20 precompiles has fundamentally changed in v0.4.0. Without proper migration, your ERC20 tokens will become inaccessible via EVM, showing zero balances and failing all operations.
+
+### Quick Impact Check
+
+Your chain needs this migration if you have:
+
+- IBC tokens converted to ERC20
+- Token factory tokens with ERC20 representations
+- Any existing `DynamicPrecompiles` or `NativePrecompiles` in storage
+
+### Migration
+
+For full details see: [ERC20 Precompiles Migration Guide](./v0.4.0_erc20_precompiles_migration.md)
+
+*Thanks to Mantra team for their work on this: [MANTRA-Chain Implementation](https://github.com/MANTRA-Chain/mantrachain/pull/409)*
+
+### Quick Verification
+
+Post-upgrade, verify your migration succeeded:
+
+```bash
+# Check ERC20 balance (should NOT be 0 if tokens existed before)
+cast call $TOKEN_ADDRESS "balanceOf(address)" $USER_ADDRESS --rpc-url http://localhost:8545
+
+# Verify precompiles in state
+evmd export | jq '.app_state.erc20.dynamic_precompiles'
+```
+
+---
+
+## 10) Verify before tagging
 
 - [ ] `go.mod` has **no `replace`** lines for `github.com/cosmos/evm`.
 - [ ] Node boots with expected **RPC namespaces**.