Research: generic tx-handling tool vs. per-protocol prepare_* tools for DeFi coverage

[szhygulin]

Problem

DeFi protocol coverage is currently O(N) in implementation effort: every new protocol (Compound, Aave, Curve, Morpho, Kamino, MarginFi, Lido, Rocket Pool, EigenLayer, Marinade, Jito, …) requires bespoke prepare_* tools per action. Phase 2/3 added ~30 tools across 10+ protocols, each with its own ABI handling, parameter validation, slippage logic, and pre-sign annotations. The cost compounds:

• Every new protocol = N new tools (supply / withdraw / borrow / repay / claim …).
• Every new tool needs invariant coverage (Add CI workflow: typecheck + tests on Node 20/22 #1 abi-decode, Broaden .gitignore to catch all .env variants #2 hash, v0.2.3: document approval→wait→main-tx pattern to all agents #11 unlimited).
• The catalog grows past what the agent can reasonably load (token cost — see #).

Alternative to research

Expose a generic transaction-handling tool — call it prepare_arbitrary_call or extend prepare_custom_call — and let the user's cooperating agent write a small script per protocol on demand. The MCP would supply:

• ABI fetching (get_contract_abi exists).
• Read helpers (read_contract exists).
• A signing-grade prepare_arbitrary_call(to, data, value, chainId, gasParams?) that runs the same pre-sign invariants the per-protocol tools run.
• Optional templates / library code the agent can adapt.

The agent then composes the protocol-specific tx itself — fetch the pool address, encode the calldata, hand the unsigned tx to the MCP for invariant-checked signing.

Questions to research

1. Security model: does the existing prepare_custom_call already meet this need, or is its current refusal surface too narrow / too wide? What gates would need to relax / tighten? (Curve allowlist saga from feat(pre-sign): approve-allowlist as security recommendation (closes #617) #618 / fix(curve-swap): destination-allowlist ack on swap leg (closes #626) #628 is relevant — generic-call is harder to apply pool-specific allowlists to.)
2. Invariant coverage: how do Add CI workflow: typecheck + tests on Node 20/22 #1 (abi-decode + bold-codeblock surfacing) and v0.2.3: document approval→wait→main-tx pattern to all agents #11 (unlimited / long-lived) work when the MCP doesn't know the protocol? Decode-by-ABI + heuristics vs. agent-supplied annotations vs. refuse the bold-codeblock surfacing entirely?
3. UX: per-protocol tools give the user a clear name in the audit log (prepare_aave_supply). Generic-call shows opaque calldata. Does that meaningfully erode the trust UI?
4. Comparable systems: how does Safe app, Rabby, MetaMask Snaps, or Phantom's signing flow handle the long tail? Anyone using a generic-call + agent-script pattern in production?
5. Hybrid: most-used protocols stay native (Aave / Uniswap / Lido — top-5 TVL); long-tail goes generic-call. Where's the cutoff?
6. Threat model delta: an agent-authored script is in-context — a rogue agent already gets to choose the calldata in either model. The trust boundary stays at Ledger clear-sign + MCP invariants. Confirm or refute.

Deliverable

A short design note (not code): recommend (a) status quo, (b) full generic-call pivot, (c) hybrid with a clear cutoff rule. Cite which existing MCP scaffolding already covers the generic path.

Scope

Research only. Do not implement until the design is decided.

[szhygulin]

Research delivered. Recommendation: (c) hybrid — keep per-protocol prepare_* for flows that encode prepare-time invariants, route the long tail through the existing prepare_custom_call. No new entry point. No pivot.

Key findings:

• A prepare_arbitrary_call would be prepare_custom_call (feat(custom-call): add prepare_custom_call escape-hatch tool #494 / feat(security): add get_contract_abi — standalone Etherscan-V2 ABI fetch (closes #495) #497 / fix(custom-call): honor acknowledgeNonProtocolTarget at preview/send time #498) renamed — same code, same acknowledgeNonProtocolTarget gate, same approve-routing refusal (MCP: prepare_custom_call lacks intent-layer refusal for unlimited approval to burn/dead addresses #556), same verified-or-inline-ABI requirement.
• Per-protocol prepare_* tools concentrate prepare-time invariants the generic path cannot enforce: slippage / MEV math, protocol-pause / cap / threshold preconditions, approve+action bundling with burn-address + unlimited-approval gates, durable-binding to a verified candidate (Inv Add TRON Phase 1: read-only balances + portfolio integration #15), non-standard token semantics. assertTransactionSafe blocks 4 (catch-all unknown destination) and 5 (per-destination ABI-selector check) are bypassed for ack-stamped txs — the per-protocol path is where multiple independent server-side cross-checks fire.
• The catalog-growth lever is conditional tool-surface gating (VAULTPILOT_PROTOCOLS / VAULTPILOT_CHAIN_FAMILIES, already shipped via feat(scope): conditional tool-surface gating via VAULTPILOT_CHAIN_FAMILIES + VAULTPILOT_PROTOCOLS #492), not a generic-call pivot.
• Production wallets converge on the same shape: per-protocol clear-sign for top-N + generic raw for the long tail (Safe Apps, Rabby, MetaMask Snaps, Phantom). None ship "agent writes a script per protocol" as the default.

The actionable parts are tracked as follow-ups:

• Codify per-protocol vs. prepare_custom_call cutoff rule in CLAUDE.md #651 — codify the structural cutoff rule (5 criteria) in project CLAUDE.md.
• Selector classifier for prepare_custom_call (defense-in-depth on the escape hatch) #652 — selector classifier for prepare_custom_call defense-in-depth, promoted from claude-work/archive/plan-custom-call-selector-classifier.md.

Original research note lived at #645 (closed unmerged — doc was a planning artifact, doesn't need to ship in main).