KeeperHub / KeeperHub/keeperhub
feat(mcp): semantic EVM revert decoding & actionable agent remediation
- Dominant language
- TypeScript
- Stars
- 24
- Forks
- 93
- Avg merge
- 1d 4h
- Merged PRs (30d)
- 253
Description
## Reason
When an AI agent or caller invokes MCP simulation tools (`execute_contract_call`, `execute_token_transfer`, `simulate_transaction`) and an EVM revert occurs, the error is returned as a raw HTTP 400 with embedded JSON or unclassified revert bytes. The agent lacks structured diagnostics and actionable remediation instructions (e.g., distinguishing an ERC-20 allowance shortfall from an insufficient balance or a paused contract). Consequently, autonomous agents cannot self-heal or execute preflight resolution (such as issuing an ERC-20 `approve()` call) without human intervention.
## Scope
- **Covers:**
- Standardized EVM error decoding in `lib/web3/decode-revert-error.ts` for:
- Built-in `Error(string)` and Solidity `Panic(uint256)` codes.
- Common ERC-20 custom errors (e.g., `ERC20InsufficientAllowance`, `ERC20InsufficientBalance`).
- Gnosis Safe GS error codes (e.g., `GS013` signature validation).
- OpenZeppelin Pausable and AccessControl errors.
- Actionable agent remediation generation (`getRemediationForRevert`) providing machine-readable reason codes and clear instructions.
- MCP tool error augmentation in `lib/mcp/tools.ts` to format simulation failures for agent consumption.
- Safe deployment panic error formatting in `lib/safe/deploy-errors.ts`.
- **Explicitly does not cover:**
- Modifying transaction broadcasting, signing logic, or executor gas estimation.
- Altering on-chain state or private key management.
## Plan
1. Implement semantic revert decoding in `lib/web3/decode-revert-error.ts`, inspecting built-in `Error(string)` and `Panic(uint256)` selectors before checking contract-specific ABIs to avoid ethers.js interface masking.
2. Provide typed reason codes and actionable remediation guidance for agent dry-runs.
3. Augment MCP simulation error reporting with structured remediation advice.
4. Add comprehensive unit test suites covering built-ins, Safe GS codes, custom contract errors, and MCP diagnostics.
Contributor guide
Research direction
Start with lib/web3/decode-revert-error.ts and trace how MCP simulation failures flow through lib/mcp/tools.ts and lib/safe/deploy-errors.ts. Review the existing error and ABI handling before defining coverage for built-in, ERC-20, Safe, Pausable, and AccessControl reverts; done means structured reason codes, remediation guidance, augmented MCP diagnostics, and comprehensive unit tests.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- api, blockchain
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100