ownerwatch 0.7.2__tar.gz

ownerwatch-0.7.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 imal1ice
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ownerwatch-0.7.2/PKG-INFO

@@ -0,0 +1,136 @@
+Metadata-Version: 2.4
+Name: ownerwatch
+Version: 0.7.2
+Summary: Self-hosted monitor that alerts when admin keys, roles, proxies, pausers or treasuries of EVM contracts change.
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: web3>=7
+Requires-Dist: pyyaml>=6
+Requires-Dist: requests>=2.31
+Dynamic: license-file
+
+# ownerwatch
+
+[![ci](https://github.com/imal1ice/ownerwatch/actions/workflows/ci.yml/badge.svg)](https://github.com/imal1ice/ownerwatch/actions/workflows/ci.yml) [![release](https://img.shields.io/github/v/release/imal1ice/ownerwatch)](https://github.com/imal1ice/ownerwatch/releases) ![license](https://img.shields.io/github/license/imal1ice/ownerwatch)
+
+Self-hosted monitor that alerts you the moment the **admin surface** of your EVM contracts changes.
+
+Most protocol losses in 2025-2026 started with a key, a role or a proxy changing hands, not with a clever exploit. ownerwatch watches the events that mean "someone just gained control" and pushes them to Discord, Slack, Telegram or any webhook within seconds. No account, no SaaS, no third party holding your contract list. One YAML file and a Docker container.
+
+## What it watches
+
+Every address in your config gets the full catalog:
+
+| Standard | Events | Severity |
+|---|---|---|
+| Ownable / Ownable2Step | OwnershipTransferred, OwnershipTransferStarted | critical / high |
+| AccessControl | RoleGranted, RoleRevoked, RoleAdminChanged | high / critical |
+| ERC-1967 proxies | Upgraded, AdminChanged, BeaconUpgraded | critical |
+| Pausable | Paused, Unpaused | medium |
+| TimelockController | CallScheduled, CallExecuted, Cancelled, MinDelayChange | high / critical |
+| Legacy Timelock (Compound, Uniswap and forks) | NewAdmin, NewPendingAdmin, NewDelay, QueueTransaction, ExecuteTransaction, CancelTransaction | medium to critical |
+| Governor (OpenZeppelin and GovernorBravo) | ProposalCreated, ProposalQueued, ProposalExecuted, ProposalCanceled, VotingDelaySet, VotingPeriodSet, ProposalThresholdSet, QuorumNumeratorUpdated, TimelockChange, NewImplementation | medium to critical |
+| Aragon OS (Lido and others) | SetApp, SetPermission, ChangePermissionManager, StartVote, ExecuteVote | medium to critical |
+| Safe | AddedOwner, RemovedOwner, ChangedThreshold, EnabledModule, DisabledModule, ChangedGuard, ChangedFallbackHandler, ExecutionFromModuleSuccess, ExecutionSuccess, ExecutionFailure | info to critical |
+| ERC-20 treasuries | Transfer out above a threshold you set | high |
+| NFT treasuries | Any ERC-721 or ERC-1155 transfer out | high |
+| Native balance | ETH balance of a treasury falls by more than a threshold between polls | high |
+
+**Safe queues.** Add a Safe under `safes:` and ownerwatch polls the Safe Transaction Service: you get an alert when a transaction is proposed, and a critical one when it has collected enough signatures to execute. That is the moment to act; the on-chain events above are the record of what already happened.
+
+Timelock and Safe-queue alerts show the call being made: full function and arguments when the target is verified on Sourcify, otherwise the signature from the openchain and 4byte databases, otherwise the raw selector. Set `explorer_url` and every alert carries a clickable transaction link.
+
+Run `ownerwatch events` to print the catalog.
+
+## Quick start
+
+```bash
+pip install git+https://github.com/imal1ice/ownerwatch
+cp config.example.yaml config.yaml   # add your contracts and a Discord/Telegram target
+ownerwatch run --config config.yaml
+```
+
+Or with Docker:
+
+```bash
+docker compose up -d        # uses ./config.yaml, keeps state in a named volume
+```
+
+A hardened systemd unit is in `deploy/ownerwatch.service`.
+
+Several chains in one process: put shared settings at the top level and a `chains:` list underneath, see `examples/multichain.yaml`.
+
+**Don't know what to watch?** Point `probe` at your main contract and it walks the owner/admin/proxy chain, tells you who can upgrade or pause it, flags EOAs and 1-of-N Safes, and prints a config:
+
+```bash
+ownerwatch probe --rpc https://eth.drpc.org --safe-chain eth --label Acme 0xYourProxy 0xYourSafe
+ownerwatch probe --rpc https://eth.drpc.org --roles-from-logs 0xAccessControlContract   # every current role holder, replayed from logs since deployment
+ownerwatch probe --config config.yaml --markdown --label Acme > admin-surface.md   # monthly report of everything you watch
+```
+
+`--roles-from-logs` finds the creation block on Sourcify and reads the history from a free public log gateway on Ethereum, Optimism, Arbitrum, Gnosis and Polygon; on Base (and for any chain without one) pass `--logs-rpc` with an RPC that serves wide `eth_getLogs` ranges, or `--from-block` to bound the scan.
+
+Want that check in CI? `examples/github-action-drift.yml` re-probes weekly and fails when a signer, delay or proxy admin changes from the committed report.
+
+```bash
+```
+
+Other commands:
+
+```bash
+ownerwatch validate                         # check the config, the RPC and that every address has code
+ownerwatch test-alert                       # push a test message through your sinks
+ownerwatch run --once                       # single scan, for cron
+ownerwatch backfill --from-block N --to-block M   # replay history, prints what you would have seen
+ownerwatch events                           # list the catalog
+```
+
+See [docs/what-to-watch.md](docs/what-to-watch.md) for the control-graph model behind the catalog, and [docs/sample-alerts.md](docs/sample-alerts.md) for real alerts replayed from mainnet history.
+
+## Examples
+
+`examples/` has verified configs for Uniswap, Compound, Arbitrum, Aave and the Optimism Foundation Safe on mainnet. Backfill one to see what alerts look like on real history:
+
+```bash
+ownerwatch backfill --config examples/aave-mainnet.yaml --from-block 22000000 --to-block 22050000
+```
+
+## How it works
+
+- Polls `eth_getLogs` for the catalog's topic hashes on your addresses, in chunks that fit public RPCs.
+- Waits `confirmations` blocks behind the head so small reorgs don't produce ghost alerts.
+- Persists a block cursor to `state/`, so a restart resumes where it left off with no duplicates.
+- Alert delivery never stops the poller: a dead webhook is logged and skipped.
+- Set `heartbeat_url` to a dead-man's-switch (healthchecks.io or similar) and you get paged when ownerwatch itself stops polling. Quiet and dead must not look the same.
+- Works on any EVM chain, one process can watch several.
+
+## Hosted tier
+
+Don't want to run it? I run it for you, per chain, paid in USDC on-chain through `contracts/src/Subscriptions.sol`: approve, call `subscribe(periods, chains, maxCost, configRef)`, send me the config. No invoices, no accounts, no KYC either way. Details in [docs/hosted.md](docs/hosted.md). Deployment address will be listed here once live; until then open an issue. The operator side is `ownerwatch hosted --rpc ... --subscriptions 0x... --configs configs/`: it starts a watcher for every address with an active subscription and stops it when the subscription lapses.
+
+```bash
+cd contracts && forge install foundry-rs/forge-std --no-git && forge test
+```
+
+## Roadmap
+
+- Native balance and NFT alerts for Safe queues (currently on-chain only)
+
+## Support the project
+
+ownerwatch is free and MIT licensed. If it saves you a 3am incident, fund the work:
+
+- Drips: https://www.drips.network/app/projects/github/imal1ice/ownerwatch
+- Giveth: https://giveth.io/project/ownerwatch
+- Direct: `0x874D018623EeBb398B898AC7AB0c97506244141B` (Ethereum and all major L2s)
+
+Need it deployed, extended or integrated with your alerting stack? Open an issue or reach out on GitHub.
+
+## Development
+
+```bash
+python3 -m venv .venv && .venv/bin/pip install -e . pytest
+.venv/bin/pytest        # end-to-end test against a local anvil node; needs foundry
+```

ownerwatch-0.7.2/README.md

@@ -0,0 +1,123 @@
+# ownerwatch
+
+[![ci](https://github.com/imal1ice/ownerwatch/actions/workflows/ci.yml/badge.svg)](https://github.com/imal1ice/ownerwatch/actions/workflows/ci.yml) [![release](https://img.shields.io/github/v/release/imal1ice/ownerwatch)](https://github.com/imal1ice/ownerwatch/releases) ![license](https://img.shields.io/github/license/imal1ice/ownerwatch)
+
+Self-hosted monitor that alerts you the moment the **admin surface** of your EVM contracts changes.
+
+Most protocol losses in 2025-2026 started with a key, a role or a proxy changing hands, not with a clever exploit. ownerwatch watches the events that mean "someone just gained control" and pushes them to Discord, Slack, Telegram or any webhook within seconds. No account, no SaaS, no third party holding your contract list. One YAML file and a Docker container.
+
+## What it watches
+
+Every address in your config gets the full catalog:
+
+| Standard | Events | Severity |
+|---|---|---|
+| Ownable / Ownable2Step | OwnershipTransferred, OwnershipTransferStarted | critical / high |
+| AccessControl | RoleGranted, RoleRevoked, RoleAdminChanged | high / critical |
+| ERC-1967 proxies | Upgraded, AdminChanged, BeaconUpgraded | critical |
+| Pausable | Paused, Unpaused | medium |
+| TimelockController | CallScheduled, CallExecuted, Cancelled, MinDelayChange | high / critical |
+| Legacy Timelock (Compound, Uniswap and forks) | NewAdmin, NewPendingAdmin, NewDelay, QueueTransaction, ExecuteTransaction, CancelTransaction | medium to critical |
+| Governor (OpenZeppelin and GovernorBravo) | ProposalCreated, ProposalQueued, ProposalExecuted, ProposalCanceled, VotingDelaySet, VotingPeriodSet, ProposalThresholdSet, QuorumNumeratorUpdated, TimelockChange, NewImplementation | medium to critical |
+| Aragon OS (Lido and others) | SetApp, SetPermission, ChangePermissionManager, StartVote, ExecuteVote | medium to critical |
+| Safe | AddedOwner, RemovedOwner, ChangedThreshold, EnabledModule, DisabledModule, ChangedGuard, ChangedFallbackHandler, ExecutionFromModuleSuccess, ExecutionSuccess, ExecutionFailure | info to critical |
+| ERC-20 treasuries | Transfer out above a threshold you set | high |
+| NFT treasuries | Any ERC-721 or ERC-1155 transfer out | high |
+| Native balance | ETH balance of a treasury falls by more than a threshold between polls | high |
+
+**Safe queues.** Add a Safe under `safes:` and ownerwatch polls the Safe Transaction Service: you get an alert when a transaction is proposed, and a critical one when it has collected enough signatures to execute. That is the moment to act; the on-chain events above are the record of what already happened.
+
+Timelock and Safe-queue alerts show the call being made: full function and arguments when the target is verified on Sourcify, otherwise the signature from the openchain and 4byte databases, otherwise the raw selector. Set `explorer_url` and every alert carries a clickable transaction link.
+
+Run `ownerwatch events` to print the catalog.
+
+## Quick start
+
+```bash
+pip install git+https://github.com/imal1ice/ownerwatch
+cp config.example.yaml config.yaml   # add your contracts and a Discord/Telegram target
+ownerwatch run --config config.yaml
+```
+
+Or with Docker:
+
+```bash
+docker compose up -d        # uses ./config.yaml, keeps state in a named volume
+```
+
+A hardened systemd unit is in `deploy/ownerwatch.service`.
+
+Several chains in one process: put shared settings at the top level and a `chains:` list underneath, see `examples/multichain.yaml`.
+
+**Don't know what to watch?** Point `probe` at your main contract and it walks the owner/admin/proxy chain, tells you who can upgrade or pause it, flags EOAs and 1-of-N Safes, and prints a config:
+
+```bash
+ownerwatch probe --rpc https://eth.drpc.org --safe-chain eth --label Acme 0xYourProxy 0xYourSafe
+ownerwatch probe --rpc https://eth.drpc.org --roles-from-logs 0xAccessControlContract   # every current role holder, replayed from logs since deployment
+ownerwatch probe --config config.yaml --markdown --label Acme > admin-surface.md   # monthly report of everything you watch
+```
+
+`--roles-from-logs` finds the creation block on Sourcify and reads the history from a free public log gateway on Ethereum, Optimism, Arbitrum, Gnosis and Polygon; on Base (and for any chain without one) pass `--logs-rpc` with an RPC that serves wide `eth_getLogs` ranges, or `--from-block` to bound the scan.
+
+Want that check in CI? `examples/github-action-drift.yml` re-probes weekly and fails when a signer, delay or proxy admin changes from the committed report.
+
+```bash
+```
+
+Other commands:
+
+```bash
+ownerwatch validate                         # check the config, the RPC and that every address has code
+ownerwatch test-alert                       # push a test message through your sinks
+ownerwatch run --once                       # single scan, for cron
+ownerwatch backfill --from-block N --to-block M   # replay history, prints what you would have seen
+ownerwatch events                           # list the catalog
+```
+
+See [docs/what-to-watch.md](docs/what-to-watch.md) for the control-graph model behind the catalog, and [docs/sample-alerts.md](docs/sample-alerts.md) for real alerts replayed from mainnet history.
+
+## Examples
+
+`examples/` has verified configs for Uniswap, Compound, Arbitrum, Aave and the Optimism Foundation Safe on mainnet. Backfill one to see what alerts look like on real history:
+
+```bash
+ownerwatch backfill --config examples/aave-mainnet.yaml --from-block 22000000 --to-block 22050000
+```
+
+## How it works
+
+- Polls `eth_getLogs` for the catalog's topic hashes on your addresses, in chunks that fit public RPCs.
+- Waits `confirmations` blocks behind the head so small reorgs don't produce ghost alerts.
+- Persists a block cursor to `state/`, so a restart resumes where it left off with no duplicates.
+- Alert delivery never stops the poller: a dead webhook is logged and skipped.
+- Set `heartbeat_url` to a dead-man's-switch (healthchecks.io or similar) and you get paged when ownerwatch itself stops polling. Quiet and dead must not look the same.
+- Works on any EVM chain, one process can watch several.
+
+## Hosted tier
+
+Don't want to run it? I run it for you, per chain, paid in USDC on-chain through `contracts/src/Subscriptions.sol`: approve, call `subscribe(periods, chains, maxCost, configRef)`, send me the config. No invoices, no accounts, no KYC either way. Details in [docs/hosted.md](docs/hosted.md). Deployment address will be listed here once live; until then open an issue. The operator side is `ownerwatch hosted --rpc ... --subscriptions 0x... --configs configs/`: it starts a watcher for every address with an active subscription and stops it when the subscription lapses.
+
+```bash
+cd contracts && forge install foundry-rs/forge-std --no-git && forge test
+```
+
+## Roadmap
+
+- Native balance and NFT alerts for Safe queues (currently on-chain only)
+
+## Support the project
+
+ownerwatch is free and MIT licensed. If it saves you a 3am incident, fund the work:
+
+- Drips: https://www.drips.network/app/projects/github/imal1ice/ownerwatch
+- Giveth: https://giveth.io/project/ownerwatch
+- Direct: `0x874D018623EeBb398B898AC7AB0c97506244141B` (Ethereum and all major L2s)
+
+Need it deployed, extended or integrated with your alerting stack? Open an issue or reach out on GitHub.
+
+## Development
+
+```bash
+python3 -m venv .venv && .venv/bin/pip install -e . pytest
+.venv/bin/pytest        # end-to-end test against a local anvil node; needs foundry
+```

ownerwatch-0.7.2/ownerwatch/__init__.py

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

ownerwatch-0.7.2/ownerwatch/__main__.py

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

ownerwatch-0.7.2/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-0.7.2/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())