ownerwatch 0.7.2__py3-none-any.whl

ownerwatch/__init__.py

@@ -0,0 +1,3 @@
+"""ownerwatch: alert when the admin surface of an EVM contract changes."""
+
+__version__ = "0.7.2"

ownerwatch/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+main()

ownerwatch/alerts.py

@@ -0,0 +1,120 @@
+from __future__ import annotations
+
+import json
+import logging
+import sys
+from dataclasses import asdict, dataclass
+
+import requests
+
+from .config import Alerts
+from .events import severity_rank
+
+log = logging.getLogger("ownerwatch")
+
+
+@dataclass
+class Alert:
+    severity: str
+    chain: str
+    contract: str
+    label: str
+    event: str
+    source: str
+    message: str
+    block: int
+    tx_hash: str
+
+    def text(self) -> str:
+        return (f"[{self.severity.upper()}] {self.label} ({self.contract}) on {self.chain}\n"
+                f"{self.source}.{self.event}: {self.message}\n"
+                f"block {self.block} tx {self.tx_hash}")
+
+
+class Dispatcher:
+    """Fan an Alert out to every configured sink. Never raises: a dead
+    webhook must not stop the poller."""
+
+    def __init__(self, cfg: Alerts, sinks: list | None = None):
+        self.cfg = cfg
+        self.min_rank = severity_rank(cfg.min_severity)
+        self.extra_sinks = sinks or []  # callables, used by tests
+        self.counts: dict[str, int] = {}   # severity -> alerts sent today
+        self.digest_day: str | None = None
+
+    def send(self, alert: Alert) -> None:
+        print(alert.text(), file=sys.stdout, flush=True)
+        self.counts[alert.severity] = self.counts.get(alert.severity, 0) + 1
+        if severity_rank(alert.severity) < self.min_rank:
+            return
+        for fn in self.extra_sinks:
+            fn(alert)
+        text = alert.text()
+        for name, fn in (("discord", self._discord), ("slack", self._slack), ("telegram", self._telegram), ("webhook", self._webhook)):
+            try:
+                fn(alert, text)
+            except Exception as e:  # noqa: BLE001
+                log.warning("%s delivery failed: %s", name, e)
+
+    def maybe_digest(self, chain: str, head: int, today: str | None = None) -> bool:
+        """At the first poll of each UTC day, post yesterday's summary. Returns True when sent."""
+        import datetime as _dt
+        today = today or _dt.datetime.now(_dt.timezone.utc).strftime("%Y-%m-%d")
+        if not self.cfg.daily_digest:
+            return False
+        if self.digest_day is None:
+            self.digest_day = today
+            return False
+        if today == self.digest_day:
+            return False
+        summary = ", ".join(f"{k}: {self.counts.get(k, 0)}" for k in ("critical", "high", "medium", "info"))
+        self.send(Alert("info", chain, "-", "ownerwatch", "DailyDigest", "ownerwatch",
+                        f"digest for {self.digest_day}: {summary}; watcher alive, head block {head}", head, "-"))
+        self.counts = {}
+        self.digest_day = today
+        return True
+
+    def heartbeat(self) -> None:
+        """Ping the dead-man's-switch URL. Silence there means the watcher is down."""
+        if not self.cfg.heartbeat_url:
+            return
+        try:
+            requests.get(self.cfg.heartbeat_url, timeout=10)
+        except Exception as e:  # noqa: BLE001
+            log.warning("heartbeat failed: %s", e)
+
+    @staticmethod
+    def _clip(text: str, limit: int) -> str:
+        return text if len(text) <= limit else text[: limit - 1] + "…"
+
+    COLORS = {"info": 0x95A5A6, "medium": 0xF1C40F, "high": 0xE67E22, "critical": 0xE74C3C}
+
+    def _discord(self, alert: Alert, text: str) -> None:
+        if self.cfg.discord_webhook:
+            embed = {
+                "title": self._clip(f"[{alert.severity.upper()}] {alert.label}: {alert.source}.{alert.event}", 256),
+                "description": self._clip(alert.message, 4096),
+                "color": self.COLORS.get(alert.severity, 0x95A5A6),
+                "fields": [
+                    {"name": "Contract", "value": f"`{alert.contract}`", "inline": True},
+                    {"name": "Chain", "value": alert.chain, "inline": True},
+                    {"name": "Block", "value": str(alert.block), "inline": True},
+                    {"name": "Tx", "value": self._clip(alert.tx_hash, 1024), "inline": False},
+                ],
+            }
+            requests.post(self.cfg.discord_webhook, json={"embeds": [embed]}, timeout=10).raise_for_status()
+
+    def _slack(self, alert: Alert, text: str) -> None:
+        if self.cfg.slack_webhook:
+            requests.post(self.cfg.slack_webhook, json={"text": self._clip(text, 3000)}, timeout=10).raise_for_status()
+
+    def _telegram(self, alert: Alert, text: str) -> None:
+        if self.cfg.telegram_bot_token and self.cfg.telegram_chat_id:
+            requests.post(f"https://api.telegram.org/bot{self.cfg.telegram_bot_token}/sendMessage",
+                          json={"chat_id": self.cfg.telegram_chat_id, "text": self._clip(text, 4096),
+                                "disable_web_page_preview": True}, timeout=10).raise_for_status()
+
+    def _webhook(self, alert: Alert, text: str) -> None:
+        if self.cfg.webhook_url:
+            requests.post(self.cfg.webhook_url, data=json.dumps(asdict(alert)),
+                          headers={"content-type": "application/json"}, timeout=10).raise_for_status()

ownerwatch/cli.py

@@ -0,0 +1,173 @@
+from __future__ import annotations
+
+import argparse
+import logging
+import sys
+
+from . import __version__
+from .alerts import Dispatcher
+from .config import load_all
+from .events import CATALOG
+from .watcher import Watcher
+
+
+def main(argv: list[str] | None = None) -> int:
+    p = argparse.ArgumentParser(prog="ownerwatch", description="Alert when an EVM contract's admin surface changes.")
+    p.add_argument("--version", action="version", version=__version__)
+    sub = p.add_subparsers(dest="cmd", required=True)
+    r = sub.add_parser("run", help="poll forever and alert")
+    r.add_argument("--config", default="config.yaml")
+    r.add_argument("--once", action="store_true", help="scan once and exit (for cron)")
+    b = sub.add_parser("backfill", help="scan a historical block range and print alerts")
+    b.add_argument("--config", default="config.yaml")
+    b.add_argument("--from-block", type=int, required=True)
+    b.add_argument("--to-block", type=int, required=True)
+    b.add_argument("--chain", default=None, help="chain_name to backfill when the config has several chains")
+    sub.add_parser("events", help="list the events in the catalog")
+    va = sub.add_parser("validate", help="check a config file and print what it would watch")
+    va.add_argument("--config", default="config.yaml")
+    ta = sub.add_parser("test-alert", help="send a test alert through every configured sink")
+    ta.add_argument("--config", default="config.yaml")
+    h = sub.add_parser("hosted", help="run watchers for every address with an active on-chain subscription")
+    h.add_argument("--rpc", required=True, help="RPC of the chain the Subscriptions contract lives on")
+    h.add_argument("--subscriptions", required=True, help="Subscriptions contract address")
+    h.add_argument("--configs", default="configs", help="directory of <customer-address>.yaml files")
+    h.add_argument("--check-interval", type=int, default=60)
+    pr = sub.add_parser("probe", help="inspect the admin surface of addresses and suggest a config")
+    pr.add_argument("addresses", nargs="*")
+    pr.add_argument("--rpc", default=None)
+    pr.add_argument("--config", default=None, help="probe every contract and Safe listed in this config (per chain)")
+    pr.add_argument("--chain-name", default="ethereum")
+    pr.add_argument("--safe-chain", default=None, help="Safe Tx Service key (eth, base, arb1, oeth, ...) to add safes: entries")
+    pr.add_argument("--label", default="Protocol")
+    pr.add_argument("--yaml", action="store_true", help="print only the suggested config")
+    pr.add_argument("--markdown", action="store_true", help="print a short admin-surface report in markdown")
+    pr.add_argument("--json", action="store_true", help="print the probed nodes as JSON")
+    pr.add_argument("--roles-from-logs", action="store_true",
+                    help="replay RoleGranted/RoleRevoked logs to list every current role holder (needs an RPC with log history)")
+    pr.add_argument("--from-block", type=int, default=None,
+                    help="with --roles-from-logs: first block to scan (default: creation block from Sourcify or a code search)")
+    pr.add_argument("--logs-rpc", default=None,
+                    help="with --roles-from-logs: RPC used only for eth_getLogs, e.g. https://rpc.flashbots.net (100k blocks per call)")
+    a = p.parse_args(argv)
+
+    logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(message)s", stream=sys.stderr)
+
+    if a.cmd == "events":
+        for s in CATALOG:
+            print(f"{s.severity:8} {s.source:18} {s.signature}")
+        return 0
+
+    if a.cmd == "hosted":
+        from .hosted import HostedRunner
+        HostedRunner(a.rpc, a.subscriptions, a.configs, a.check_interval).run_forever()
+        return 0
+
+    if a.cmd == "probe":
+        from web3 import Web3
+        from .probe import Prober, describe, markdown_report, suggest_config
+        if a.config:
+            # one report per chain, addresses taken from the config
+            for cfg in load_all(a.config):
+                prober = Prober(Web3(Web3.HTTPProvider(cfg.rpc_url, request_kwargs={"timeout": 30})))
+                addrs = [c.address for c in cfg.contracts] + [s_.address for s_ in cfg.safes]
+                roots = [prober.probe(x) for x in dict.fromkeys(addrs)]
+                prober.check_roles(list(prober.seen.keys()))
+                if a.markdown:
+                    print(markdown_report(prober, a.label, cfg.chain_name, roots))
+                elif a.json:
+                    import dataclasses, json as _json
+                    print(_json.dumps({"chain": cfg.chain_name, "nodes": [dataclasses.asdict(n) for n in prober.seen.values()]}, indent=2))
+                else:
+                    print(f"# {cfg.chain_name}")
+                    for n in prober.seen.values():
+                        print(describe(n))
+            return 0
+        if not a.rpc or not a.addresses:
+            p.error("probe needs --rpc and at least one address, or --config")
+        prober = Prober(Web3(Web3.HTTPProvider(a.rpc, request_kwargs={"timeout": 30})))
+        roots = [prober.probe(x) for x in a.addresses]
+        prober.check_roles(list(prober.seen.keys()))
+        if a.roles_from_logs:
+            logs_w3 = Web3(Web3.HTTPProvider(a.logs_rpc, request_kwargs={"timeout": 60})) if a.logs_rpc else None
+            for x in a.addresses:
+                try:
+                    prober.role_history(x, a.from_block, logs_w3, log=lambda m: print(m, file=sys.stderr))
+                except Exception as e:  # noqa: BLE001
+                    print(f"# role history for {x} failed: {e}", file=sys.stderr)
+        if a.markdown:
+            print(markdown_report(prober, a.label, a.chain_name, roots))
+            return 0
+        if a.json:
+            import dataclasses, json as _json
+            print(_json.dumps({"chain": a.chain_name, "nodes": [dataclasses.asdict(n) for n in prober.seen.values()]}, indent=2))
+            return 0
+        if not a.yaml:
+            for n in prober.seen.values():
+                print(describe(n))
+            print("\n# suggested config\n")
+        print(suggest_config(prober, a.rpc, a.chain_name, a.safe_chain, a.label))
+        return 0
+
+    try:
+        cfgs = load_all(a.config)
+    except Exception as e:  # noqa: BLE001
+        print(f"config error: {e}", file=sys.stderr)
+        return 2
+    if a.cmd == "validate":
+        from web3 import Web3
+        for cfg in cfgs:
+            sinks = [k for k in ("discord_webhook", "slack_webhook", "telegram_bot_token", "webhook_url") if getattr(cfg.alerts, k)]
+            print(f"{cfg.chain_name}: {len(cfg.contracts)} contracts, {len(cfg.treasuries)} treasuries, {len(cfg.safes)} safes, sinks: {', '.join(sinks) or 'stdout only'}")
+            try:
+                w3 = Web3(Web3.HTTPProvider(cfg.rpc_url, request_kwargs={"timeout": 15}))
+                print(f"  rpc ok, chain id {w3.eth.chain_id}, head {w3.eth.block_number}")
+                for c in cfg.contracts:
+                    if len(w3.eth.get_code(c.address)) == 0:
+                        print(f"  WARNING {c.label} {c.address} has no code on this chain")
+            except Exception as e:  # noqa: BLE001
+                print(f"  rpc FAILED: {e}")
+        return 0
+    if a.cmd == "test-alert":
+        from .alerts import Alert
+        for cfg in cfgs:
+            Dispatcher(cfg.alerts).send(Alert("info", cfg.chain_name, "0x" + "00" * 20, "ownerwatch", "TestAlert", "ownerwatch",
+                                              "test alert: your sinks are wired up", 0, "-"))
+        return 0
+    if a.cmd == "backfill":
+        if len(cfgs) > 1 and not a.chain:
+            p.error("--chain is required for a multi-chain config")
+        if a.chain:
+            matches = [c for c in cfgs if c.chain_name == a.chain]
+            if not matches:
+                p.error(f"no chain named {a.chain!r} in config (have: {', '.join(c.chain_name for c in cfgs)})")
+            cfg = matches[0]
+        else:
+            cfg = cfgs[0]
+        w = Watcher(cfg, Dispatcher(cfg.alerts))
+        n, start = 0, a.from_block
+        while start <= a.to_block:
+            end = min(start + cfg.max_block_range - 1, a.to_block)
+            n += w._scan(start, end)
+            start = end + 1
+        print(f"{n} alerts in blocks {a.from_block}-{a.to_block}", file=sys.stderr)
+        return 0
+    watchers = [Watcher(c, Dispatcher(c.alerts)) for c in cfgs]
+    if a.once:
+        for w in watchers:
+            w.poll_once()
+        return 0
+    if len(watchers) == 1:
+        watchers[0].run_forever()
+        return 0
+    import threading
+    threads = [threading.Thread(target=w.run_forever, name=w.cfg.chain_name, daemon=True) for w in watchers]
+    for t in threads:
+        t.start()
+    for t in threads:
+        t.join()
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

ownerwatch/config.py

@@ -0,0 +1,141 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import yaml
+from web3 import Web3
+
+
+@dataclass
+class Token:
+    address: str
+    symbol: str
+    decimals: int
+    min_amount: float
+
+
+@dataclass
+class Collection:
+    address: str
+    label: str
+
+
+@dataclass
+class Treasury:
+    address: str
+    label: str
+    tokens: list[Token]
+    nfts: list[Collection] = field(default_factory=list)
+    min_native_drop: float | None = None   # alert if native balance falls by >= this many ETH between polls
+
+
+@dataclass
+class Contract:
+    address: str
+    label: str
+
+
+@dataclass
+class Safe:
+    address: str
+    label: str
+    chain: str = "eth"
+
+
+@dataclass
+class Alerts:
+    discord_webhook: str = ""
+    slack_webhook: str = ""
+    telegram_bot_token: str = ""
+    telegram_chat_id: str = ""
+    webhook_url: str = ""
+    heartbeat_url: str = ""        # GET after every successful poll (healthchecks.io, Better Uptime, cron monitors)
+    daily_digest: bool = False     # once a day (UTC) post a one-line summary: alerts by severity, head block, uptime
+    min_severity: str = "info"
+
+
+@dataclass
+class Config:
+    rpc_url: str
+    chain_name: str = "ethereum"
+    explorer_url: str = ""          # e.g. https://etherscan.io; alerts then carry a clickable tx link
+    poll_interval_seconds: int = 15
+    confirmations: int = 2
+    max_block_range: int = 2000
+    start_block: int | str = "latest"
+    state_file: str = "state/cursor.json"
+    contracts: list[Contract] = field(default_factory=list)
+    treasuries: list[Treasury] = field(default_factory=list)
+    safes: list[Safe] = field(default_factory=list)
+    safe_api_key: str = ""
+    alerts: Alerts = field(default_factory=Alerts)
+
+    def labels(self) -> dict[str, str]:
+        out = {c.address: c.label for c in self.contracts}
+        out.update({t.address: t.label for t in self.treasuries})
+        out.update({s.address: s.label for s in self.safes})
+        return out
+
+
+def _addr(a: str) -> str:
+    return Web3.to_checksum_address(a)
+
+
+SHARED_KEYS = ("explorer_url", "poll_interval_seconds", "confirmations", "max_block_range", "start_block", "alerts", "safe_api_key")
+
+
+def load_all(path: str | Path) -> list[Config]:
+    """One Config per chain. A file with a top-level `chains:` list yields one
+    Config per entry; keys in SHARED_KEYS are inherited from the top level."""
+    raw = yaml.safe_load(Path(path).read_text()) or {}
+    if "chains" not in raw:
+        return [_build(raw)]
+    out = []
+    for entry in raw["chains"] or []:
+        merged = {k: raw[k] for k in SHARED_KEYS if k in raw}
+        merged.update(entry)
+        merged.setdefault("state_file", f"state/{merged.get('chain_name', 'chain')}.json")
+        out.append(_build(merged))
+    if not out:
+        raise ValueError("chains: is empty")
+    return out
+
+
+def load(path: str | Path) -> Config:
+    cfgs = load_all(path)
+    if len(cfgs) > 1:
+        raise ValueError("multi-chain config: use load_all()")
+    return cfgs[0]
+
+
+def _build(raw: dict) -> Config:
+    contracts = [Contract(_addr(c["address"]), c.get("label", c["address"])) for c in raw.get("contracts", []) or []]
+    treasuries = []
+    for t in raw.get("treasuries", []) or []:
+        tokens = [Token(_addr(k["address"]), k.get("symbol", "?"), int(k.get("decimals", 18)), float(k.get("min_amount", 0)))
+                  for k in t.get("tokens", []) or []]
+        nfts = [Collection(_addr(n["address"]), n.get("label", n["address"])) for n in t.get("nfts", []) or []]
+        drop = t.get("min_native_drop")
+        treasuries.append(Treasury(_addr(t["address"]), t.get("label", t["address"]), tokens, nfts,
+                                   float(drop) if drop is not None else None))
+    safes = [Safe(_addr(x["address"]), x.get("label", x["address"]), x.get("chain", "eth")) for x in raw.get("safes", []) or []]
+    alerts = Alerts(**{k: v for k, v in (raw.get("alerts") or {}).items() if k in Alerts.__dataclass_fields__})
+    cfg = Config(
+        rpc_url=raw["rpc_url"],
+        chain_name=raw.get("chain_name", "ethereum"),
+        explorer_url=str(raw.get("explorer_url", "") or ""),
+        poll_interval_seconds=int(raw.get("poll_interval_seconds", 15)),
+        confirmations=int(raw.get("confirmations", 2)),
+        max_block_range=int(raw.get("max_block_range", 2000)),
+        start_block=raw.get("start_block", "latest"),
+        state_file=raw.get("state_file", "state/cursor.json"),
+        contracts=contracts,
+        treasuries=treasuries,
+        safes=safes,
+        safe_api_key=str(raw.get("safe_api_key", "") or ""),
+        alerts=alerts,
+    )
+    if not cfg.contracts and not cfg.treasuries and not cfg.safes:
+        raise ValueError("config has nothing to watch: add contracts or treasuries")
+    return cfg

ownerwatch/decode.py

@@ -0,0 +1,160 @@
+"""Best-effort decoding of calldata in timelock and Safe alerts.
+
+Order of attempts:
+1. Sourcify (verified ABI for the target on this chain): full function + args.
+2. openchain.xyz, then 4byte.directory: function signature only.
+3. Raw selector.
+Every lookup is cached in memory and fully optional; offline you still get
+the selector.
+"""
+from __future__ import annotations
+
+import logging
+
+import requests
+
+log = logging.getLogger("ownerwatch")
+_sel_cache: dict[str, str | None] = {}
+_abi_cache: dict[tuple[int, str], list | None] = {}
+
+
+def _raw(data: bytes | str) -> bytes:
+    return bytes.fromhex(data[2:]) if isinstance(data, str) else bytes(data)
+
+
+def selector_name(data: bytes | str) -> str | None:
+    raw = _raw(data)
+    if len(raw) < 4:
+        return None
+    sel = "0x" + raw[:4].hex()
+    if sel in _sel_cache:
+        return _sel_cache[sel]
+    name = None
+    try:
+        r = requests.get("https://api.openchain.xyz/signature-database/v1/lookup",
+                         params={"function": sel, "filter": "true"}, timeout=5)
+        hits = (r.json().get("result", {}).get("function", {}) or {}).get(sel) or []
+        if hits:
+            name = hits[0]["name"]
+    except Exception as e:  # noqa: BLE001
+        log.debug("openchain lookup failed: %s", e)
+    if name is None:
+        try:
+            r = requests.get("https://www.4byte.directory/api/v1/signatures/",
+                             params={"hex_signature": sel, "ordering": "created_at"}, timeout=5)
+            res = r.json().get("results") or []
+            if res:
+                name = res[0]["text_signature"]
+        except Exception as e:  # noqa: BLE001
+            log.debug("4byte lookup failed: %s", e)
+    _sel_cache[sel] = name
+    return name
+
+
+def verified_abi(chain_id: int, address: str) -> list | None:
+    key = (chain_id, address.lower())
+    if key in _abi_cache:
+        return _abi_cache[key]
+    abi = None
+    try:
+        r = requests.get(f"https://sourcify.dev/server/v2/contract/{chain_id}/{address}", params={"fields": "abi"}, timeout=8)
+        if r.status_code == 200:
+            abi = r.json().get("abi") or None
+    except Exception as e:  # noqa: BLE001
+        log.debug("sourcify lookup failed: %s", e)
+    _abi_cache[key] = abi
+    return abi
+
+
+MAX_ARG = 80      # characters per argument before clipping
+MAX_LIST = 4      # list items shown before "... n more"
+
+
+def _fmt(v) -> str:
+    if isinstance(v, (bytes, bytearray)):
+        return _clip("0x" + bytes(v).hex())
+    if isinstance(v, dict):   # decoded struct
+        return "{" + ", ".join(f"{k}={_fmt(x)}" for k, x in v.items()) + "}"
+    if isinstance(v, (list, tuple)):
+        items = [_fmt(x) for x in v[:MAX_LIST]]
+        if len(v) > MAX_LIST:
+            items.append(f"... {len(v) - MAX_LIST} more")
+        return "[" + ", ".join(items) + "]"
+    return _clip(str(v))
+
+
+def _clip(s: str) -> str:
+    return s if len(s) <= MAX_ARG else s[:MAX_ARG - 1] + "…"
+
+
+IMPL_SLOT = int("0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc", 16)
+
+
+def implementation_of(w3, address: str) -> str | None:
+    """ERC-1967 implementation, else slot 0 if it holds an address (Safe proxies keep the singleton there)."""
+    try:
+        for slot in (IMPL_SLOT, 0):
+            v = bytes(w3.eth.get_storage_at(address, slot))
+            if int.from_bytes(v[:12], "big") == 0 and int.from_bytes(v[12:], "big") != 0:
+                from web3 import Web3
+                cand = Web3.to_checksum_address("0x" + v[12:].hex())
+                if len(w3.eth.get_code(cand)) > 0:
+                    return cand
+    except Exception as e:  # noqa: BLE001
+        log.debug("implementation lookup failed for %s: %s", address, e)
+    return None
+
+
+def _try_abi_decode(abi: list, raw: bytes, sel: str, note: str) -> str | None:
+    try:
+        from web3 import Web3
+        fn, args = Web3().eth.contract(abi=abi).decode_function_input(raw)
+        inner = ", ".join(f"{k}={_fmt(v)}" for k, v in args.items())
+        return f"{fn.fn_name}({inner}) [{sel}, {note}]"
+    except Exception as e:  # noqa: BLE001
+        log.debug("abi decode failed: %s", e)
+        return None
+
+
+def describe_call(data: bytes | str, chain_id: int | None = None, target: str | None = None, w3=None) -> str:
+    raw = _raw(data)
+    if not raw:
+        return "empty calldata"
+    sel = "0x" + raw[:4].hex()
+    if chain_id is not None and target:
+        abi = verified_abi(chain_id, target)
+        if abi:
+            out = _try_abi_decode(abi, raw, sel, "verified")
+            if out:
+                return out
+        if w3 is not None:
+            impl = implementation_of(w3, target)
+            if impl:
+                abi = verified_abi(chain_id, impl)
+                if abi:
+                    out = _try_abi_decode(abi, raw, sel, "verified via implementation")
+                    if out:
+                        return out
+    name = selector_name(raw)
+    return f"{name} [{sel}]" if name else f"selector {sel}"
+
+
+def describe_signature_call(signature: str, data: bytes | str) -> str:
+    """GovernorBravo/legacy Timelock style: explicit 'fn(type,type)' plus args-only calldata."""
+    raw = _raw(data)
+    try:
+        from eth_abi import decode as abi_decode
+        types_str = signature[signature.index("(") + 1: signature.rindex(")")]
+        types = [t.strip() for t in types_str.split(",") if t.strip()]
+        if not types:
+            return signature
+        try:
+            values = abi_decode(types, raw)
+        except Exception:  # noqa: BLE001
+            if len(raw) % 32 != 4:
+                raise
+            values = abi_decode(types, raw[4:])   # proposer included the selector as well as the signature
+        return f"{signature[:signature.index('(')]}({', '.join(_fmt(v) for v in values)})"
+    except Exception as e:  # noqa: BLE001
+        log.debug("signature decode failed for %s: %s", signature, e)
+        return signature