docs: update MIGRATION_GUIDE.md with status and troubleshooting

- Added migration status table for all 10 precompiles
- Updated decode examples to show recommended approach (direct Decode)
- Added troubleshooting section with common issues and solutions:
  * s.precompile.Methods undefined
  * s.precompile.ABI undefined
  * Too many arguments in calls
  * Factory calls with CallArgs
- Added references to Bech32 and Slashing migrations
- Updated examples to be more comprehensive

Co-Authored-By: Claude <[email protected]>
Co-Authored-By: Happy <[email protected]>

Author: 3 people

MIGRATION_GUIDE.md

@@ -8,6 +8,21 @@ This guide explains how to migrate precompile integration tests from the old go-
 
 The precompiles have been refactored to use a custom `go-abi` library instead of the standard `go-ethereum/accounts/abi` package. This change requires updates to the test code to work with the new API.
 
+## Migration Status
+
+| Precompile | Status | Notes |
+|------------|--------|-------|
+| **Bank** | ✅ Complete | Fully migrated, all tests working |
+| **Bech32** | ✅ Complete | Fully migrated, all tests working |
+| **Slashing** | 🟡 Partial | Query tests migrated, integration/tx tests need work |
+| **P256** | ✅ Complete | Already working, no changes needed |
+| **Distribution** | ❌ Pending | Complex test suite, needs migration |
+| **ERC20** | ❌ Pending | Many test files, needs migration |
+| **Gov** | ❌ Pending | Test files exist, needs migration |
+| **ICS20** | ❌ Pending | Complex IBC tests, needs migration |
+| **Staking** | ❌ Pending | Large test suite, needs migration |
+| **WERC20** | ❌ Pending | Event handling issues, needs migration |
+
 ## Key Differences
 
 ### Old API (go-ethereum/accounts/abi)
@@ -126,7 +141,15 @@ err = is.precompile.UnpackIntoInterface(&balances, bank2.BalancesMethod, ethRes.
 Expect(err).ToNot(HaveOccurred(), "failed to unpack balances")
 ```
 
-**After:**
+**After (Recommended):**
+```go
+var ret bank.BalancesReturn
+_, err = ret.Decode(ethRes.Ret)
+Expect(err).ToNot(HaveOccurred(), "failed to unpack balances")
+Expect(ret.Balances).To(Equal(expectedBalances))
+```
+
+**After (With Helper):**
 ```go
 balances, err := decodeBalancesResult(ethRes.Ret)
 Expect(err).ToNot(HaveOccurred(), "failed to unpack balances")
@@ -141,7 +164,15 @@ Expect(err).ToNot(HaveOccurred(), "failed to unpack balances")
 Expect(out[0].(*big.Int).String()).To(Equal(expectedValue.String()))
 ```
 
-**After:**
+**After (Recommended):**
+```go
+var ret bank.SupplyOfReturn
+_, err = ret.Decode(ethRes.Ret)
+Expect(err).ToNot(HaveOccurred(), "failed to unpack balances")
+Expect(ret.TotalSupply.String()).To(Equal(expectedValue.String()))
+```
+
+**After (With Helper):**
 ```go
 supply, err := decodeSupplyOfResult(ethRes.Ret)
 Expect(err).ToNot(HaveOccurred(), "failed to unpack balances")
@@ -204,8 +235,76 @@ After migration, verify the tests build successfully:
 go build -tags=tests ./tests/integration/precompiles/{precompile_name}/...
 ```
 
+## Common Issues and Solutions
+
+### Issue 1: `s.precompile.Methods` undefined
+**Error:** `s.precompile.Methods undefined (type *"github.com/cosmos/evm/precompiles/xxx".Precompile has no field or method Methods)`
+
+**Solution:** The `Methods` field no longer exists. Use typed call structs directly:
+```go
+// Old:
+method := s.precompile.Methods[xxx.SomeMethod]
+result, err := s.precompile.SomeMethod(ctx, &method, args)
+
+// New:
+var call xxx.SomeCall
+result, err := s.precompile.SomeMethod(ctx, &call)
+```
+
+### Issue 2: `s.precompile.ABI` undefined
+**Error:** `s.precompile.ABI undefined (type *"github.com/cosmos/evm/precompiles/xxx".Precompile has no field or method ABI)`
+
+**Solution:** The `ABI` field no longer exists. For direct precompile calls, encode with `EncodeWithSelector()`:
+```go
+// Old:
+input, err := s.precompile.Pack(xxx.SomeMethod, args...)
+s.precompile.UnpackIntoInterface(&out, xxx.SomeMethod, data)
+
+// New:
+var call xxx.SomeCall{CreateArgs: args}
+input, _ := call.EncodeWithSelector()
+var ret xxx.SomeReturn
+_, err := ret.Decode(data)
+```
+
+### Issue 3: Too many arguments in call
+**Error:** `too many arguments in call to s.precompile.SomeMethod`
+
+**Solution:** The new API uses typed structs instead of variadic `[]interface{}`:
+```go
+// Old:
+result, err := s.precompile.SomeMethod(ctx, contract, stateDB, []interface{}{arg1, arg2})
+
+// New:
+var call xxx.SomeCall{Arg1: value1, Arg2: value2}
+result, err := s.precompile.SomeMethod(ctx, call, stateDB, contract)
+```
+
+### Issue 4: Factory calls with CallArgs
+**Error:** `cannot use callArgs as "github.com/yihuang/go-abi".Method value`
+
+**Solution:** When calling through factory functions, set the `Method` field in `CallArgs`:
+```go
+// Old:
+callArgs := testutiltypes.CallArgs{
+    ContractABI: contract.ABI,
+    MethodName:  "someMethod",
+    Args:        []interface{}{arg1, arg2},
+}
+
+// New:
+callArgs := testutiltypes.CallArgs{
+    ContractABI: contract.ABI,
+    MethodName:  "someMethod",
+    Args:        []interface{}{arg1, arg2},
+    Method:      &SomeCall{Arg1: arg1, Arg2: arg2}, // Add this
+}
+```
+
 ## References
 
 - Bank precompile migration: `tests/integration/precompiles/bank/`
+- Bech32 precompile migration: `tests/integration/precompiles/bech32/`
+- Slashing precompile migration: `tests/integration/precompiles/slashing/test_query.go`
 - go-abi library: github.com/yihuang/go-abi
 - Generated types example: `precompiles/bank/bank.abi.go`