KeeperHub / KeeperHub/keeperhub

feat(mcp): semantic EVM revert decoding & actionable agent remediation

Open
#2,546 0 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.