AI explanation of Timelock and Safe tx

[spalen0]

Plugin AI to explain transactions queued to Timelocks and Safes. Explanation message should be sent to Telegram.

[spalen0]

Suggestions for AI Explanation of Timelock & Safe Transactions

After reviewing the codebase, here are multiple approaches — from lightweight to full-featured.

---

Solution 1: LLM API with Decoded Calldata (Recommended Starting Point)

Leverage the existing calldata_decoder.py output and pass it to an LLM (Claude or OpenAI) for natural-language explanation.

Flow:

1. Timelock/Safe monitoring detects a new queued tx (existing logic)
2. Decode calldata via existing decode_calldata() → get DecodedCall (function name, params)
3. Enrich with on-chain context: target contract name (ENS/labels), token symbols for addresses, ETH value
4. Build a structured prompt: "Explain this governance transaction in plain English: function setCollateralFactor(address 0x..., uint256 850000000000000000) on contract Comptroller (Compound)"
5. LLM returns a 1-3 sentence explanation
6. Append explanation to the existing Telegram alert message

Pros: Simple integration, reuses existing decoder, handles edge cases gracefully.
Cons: API cost per alert, latency, potential hallucination on obscure functions.

Sketch:

# utils/ai.py
import anthropic

def explain_transaction(decoded_calls: list[DecodedCall], target: str, value: int, context: str = "") -> str:
    client = anthropic.Anthropic()
    prompt = f"""Explain this DeFi governance transaction in 1-3 sentences for a risk monitoring team.
Target: {target}
Value: {value} wei
Calls: {format_calls(decoded_calls)}
{context}
Be specific about the impact. No fluff."""
    
    response = client.messages.create(
        model="claude-haiku-4-5-20251001",  # fast + cheap for this use case
        max_tokens=200,
        messages=[{"role": "user", "content": prompt}]
    )
    return response.content[0].text

---

Solution 2: Template Engine + LLM Fallback (Cost-Efficient)

Build a rule-based template system for common governance actions (which are repetitive), and only call the LLM for unknown/complex transactions.

Flow:

1. Maintain a mapping of function_selector → explanation_template
2. For known selectors (e.g., grantRole, _setCollateralFactor, upgradeTo), fill in a template
3. For unknown selectors or scheduleBatch with complex nested calls, fall back to the LLM

Example templates:

TEMPLATES = {
    "grantRole": "Grants the **{role_name}** role to `{account}` on {target}.",
    "_setCollateralFactor": "Sets collateral factor for **{asset}** to **{factor}%** on {target}.",
    "upgradeTo": "⚠️ Upgrades proxy `{target}` to new implementation `{new_impl}`.",
    "transfer": "Transfers **{amount} {token}** to `{recipient}`.",
    "updateDelay": "Changes timelock delay to **{delay}** seconds ({human_readable}).",
}

Pros: Zero API cost for 80% of alerts, predictable output, instant.
Cons: Maintenance burden for templates, won't cover novel governance actions.

---

Solution 3: Transaction Simulation + LLM Narrative

Use Tenderly or Alchemy simulation APIs to simulate the transaction before execution, then feed the state diff to an LLM.

Flow:

1. Detect queued tx
2. Simulate via Tenderly Simulation API → get state changes, token transfers, events emitted
3. Pass simulation results + decoded calldata to LLM
4. LLM generates a risk-aware explanation: "This transaction will move 500K USDC from the treasury to address X, and update the oracle price feed for ETH/USD to use Chainlink aggregator Y"

Pros: Most accurate — explains what actually happens, not just what was called. Catches hidden side effects (e.g., callback hooks, proxy delegatecalls).
Cons: Requires Tenderly API key, added complexity, simulation may fail for some edge cases.

Sketch:

def simulate_and_explain(target: str, calldata: str, chain_id: int, value: int = 0) -> str:
    # Step 1: Simulate
    sim_result = tenderly_simulate(target, calldata, chain_id, value)
    state_changes = sim_result["state_changes"]
    token_transfers = sim_result["token_transfers"]
    
    # Step 2: Explain
    return explain_with_llm(
        calldata_decoded=decode_calldata(calldata),
        state_changes=state_changes,
        token_transfers=token_transfers,
    )

---

Solution 4: Contract Source + LLM Deep Analysis

Fetch the verified contract source from Etherscan/Sourcify, extract the relevant function, and ask the LLM to explain it in context.

Flow:

1. Detect queued tx, decode calldata
2. Fetch verified source of target contract from Etherscan API
3. Extract the specific function being called
4. Prompt: "Here is the Solidity function being called in a governance timelock. Explain what it does and the risk implications: [source code + parameters]"

Pros: Deepest understanding — LLM reads the actual implementation. Can catch subtle risks (reentrancy, privilege escalation).
Cons: Not all contracts are verified, source can be large (token limits), slower.

---

Solution 5: Hybrid Multi-Tier System (Production-Grade)

Combine the above into a tiered approach:

Tier	Condition	Method	Latency	Cost
1	Known selector in template map	Template engine	~0ms	Free
2	Unknown selector, decodable	LLM with decoded calldata (Haiku)	~1s	~$0.001
3	Complex batch/delegatecall	Simulation + LLM (Sonnet)	~5s	~$0.01
4	High-value or proxy upgrade	Source analysis + LLM (Opus)	~10s	~$0.05

This keeps costs minimal while providing deep analysis where it matters most.

---

Implementation Considerations

• Where to add it: New utils/ai.py for the LLM client, and integrate into both timelock/timelock_alerts.py (in format_alert()) and safe/main.py (in message construction)
• Caching: Cache explanations by (target, calldata_hash) to avoid re-explaining identical txs
• Telegram formatting: Add a 🤖 AI Summary: section below the existing alert content
• Error handling: If AI explanation fails, send the alert without it (non-blocking)
• Model choice: Claude Haiku for speed/cost on simple explanations, Sonnet for batch analysis
• Rate limiting: Governance txs are infrequent (few per day), so API costs should be negligible

Happy to pick one of these and implement it. My recommendation: start with Solution 1 (simplest, covers all cases), then evolve toward Solution 5 once we see what patterns emerge.