GETTING STARTED
Investigate the change, not just the event.
Watchtower is a read-only historical investigation system for three configured Base contract profiles. It turns one approved proxy upgrade event into a bounded evidence path: verify the trigger, run exact-block checks, let a tightly constrained agent choose approved follow-ups on configured live scans, derive the result deterministically, and issue a receipt.
The public MVP does not accept arbitrary addresses, event signatures, calls, RPC URLs, or block ranges outside the registered profile. A replay is always labeled as a replay.
Verify the configured event and historical trigger evidence.
Select the immutable registered investigation plan.
Run initial deterministic historical checks.
Let the bounded agent request only approved follow-up check IDs.
Derive severity and disposition with deterministic rules.
Issue and browser-verify the canonical receipt.
QUICK START
Follow one evidence path.
The current app is a focused demo of registered historical investigations. It is designed to be inspected without a wallet.
- 01
Choose a registered profile
Select Aave V3 Base Pool, Compound III Base USDC Comet, or ether.fi Base weETH OFT.
- 02
Replay or scan
Replay one committed fixture immediately. The configured Aave V3 Base Pool, Compound III Base USDC Comet, and ether.fi profiles can run bounded live scans when the archive RPC is available. All three profiles also have verified fixture replays.
- 03
Read the trace
Inspect the observed event, selected plan, exact block checks, evidence status, and final disposition.
- 04
Verify the receipt
Download the receipt or recompute its canonical SHA-256 ID in the browser.
etherfi-base-weeth-oftThe browser intentionally has no address input. There is no wallet connection, private-key request, or transaction submission.
CORE CONCEPTS
Monitoring is deliberately narrow.
Watchtower’s current registry watches one high-signal event on each configured proxy, then checks the state that gives that event context.
| Signal | What Watchtower looks for | Why it matters |
|---|---|---|
| Configured proxy upgrade | Upgraded(address) from the profile’s primary proxy at its approved block. | Creates a precise implementation-change trigger for investigation. |
| Historical implementation state | EIP-1967 implementation storage at block N−1 and block N. | Shows whether the proxy state agrees with the decoded implementation. |
| Implementation bytecode | Deployed code presence and configured byte length at the upgrade block. | Confirms that code exists at the implementation address being checked. |
| Protocol identity | Fixed profile calls such as Aave `getPool()`, Compound `governor()`, or ether.fi `endpoint()`. | Checks that the configured protocol identity still matches its approved assertion. |
Ownership changes, pause events, transfers, treasury activity, liquidity changes, wallet movements, and dynamic project discovery are outside this MVP.
INCIDENTS
An incident is a verified signal with context.
Watchtower does not turn every transaction into an alert. A current incident is created when the configured proxy emits the approved upgrade event. The alert carries a factual title and summary, severity rule, observation time, evidence status, source links, and the associated investigation.
Configured ether.fi weETH OFT proxy implementation updated
The decoded implementation matches the profile’s approved implementation at the configured upgrade block.
- Network
- Base mainnet
- Block
- 23487559
- Evidence
- Complete
- Result
- Corroborated
INVESTIGATIONS
Every alert follows a fixed trace.
After a candidate log is found, the scanner validates its block, transaction, and receipt, strictly decodes the event, selects a registered versioned plan, and executes only the checks authorized for that profile. On a configured live Aave, Compound, or ether.fi scan, the agent can choose which remaining registered check to inspect next.
- 01Observe
Confirm the configured emitter, topic, block, transaction, receipt, and decoded implementation.
- 02Plan
Choose the approved, escalation, or incomplete plan from the closed registry.
- 03Check
Read implementation state at N−1 and N and verify bytecode at N.
- 04Investigate
The bounded agent may select remaining check IDs; deterministic code supplies and executes their fixed parameters.
- 05Decide
Deterministic rules derive the disposition after every required plan check has run.
- 06Verify
Bind the trigger, plan, checks, limitations, links, and disposition into canonical JSON.
The model can choose only the order of approved follow-up check IDs. It cannot supply RPC parameters, change severity or disposition, or modify receipt v1. Missing credentials and provider failures are visible while deterministic checks continue.
RISK LEVELS
Severity names the rule that fired.
The current policy classifies the decoded implementation address against the profile’s approved address list. It is an assessment of that comparison, not a claim about intent.
Zero address target
The decoded implementation is the zero address.
target-is-zero-addressUnapproved target
The decoded implementation is nonzero but not in the approved target list.
target-is-not-approvedApproved target
The decoded implementation matches the configured approved target.
target-is-approvedThe current policy does not emit critical, medium, low, or financial-risk scores.
RECEIPTS
Every result comes with receipts.
A Watchtower receipt is the canonical record of one configured historical upgrade investigation. It preserves the trigger, selected plan, checks, errors, limitations, final disposition, and explorer links so another reader can inspect the same evidence path.
receipt_af9ac18199f550c4d6ccf64a16334dd03afbbe3a3bf06c705347e16684bd64b5
- Block
- 23487559
- Trigger
Upgraded(address)- Plan
- corroborate-approved-upgrade · 1.0.0
- Checks
- 6 / 6 passed
- Result
- corroborated
- Network
- Base mainnet · 8453
- Reproducibility through canonical JSON
- Independent SHA-256 verification in the browser
- Explorer links for the recorded transaction, block, and addresses
Committed fixtures can be replayed in the browser. Live alerts and receipts are held in process memory and clear when the server restarts.
GET /api/scans/:scanId/integrity compares the configured profile, network, exact block, transaction, event, registered plan, executed checks, severity, disposition, receipt hash, and live or fixture provenance. It returns matched and failed paths, expected and observed values, and a refusal code when the record cannot be corroborated. Receipt verification is application-level tamper evidence, not blockchain anchoring, publisher authentication, or proof that every packet field is hash-bound.
REVIEW PACKETS
Share the evidence in two useful formats.
Watchtower review packets are for exchange and infrastructure teams reviewing integrations, protocol teams reviewing upgrades, and crypto-agent companies that need deterministic protocol evidence.
Markdown supports human review and annotation. JSON supports machine consumption, archiving, and retention in an external audit trail.
bounded historical investigation → deterministic evidence → explicit disposition → verifiable receipt
Select the JSON packet in the Watchtower app to check its format and schema, confirm that a canonical receipt is present, compare the packet and receipt identifiers, and independently recompute the receipt’s SHA-256 ID inside the packet with Web Crypto. The verifier ignores saved verification metadata, including the browserVerification value, so every selection performs a fresh check. No file is uploaded and verification makes no fetch, RPC, or scan request.
- Browser verification covers the canonical receipt inside the packet and its identifier only.
- Additional packet context, display metadata, saved verification metadata, agent narrative, links, and other fields outside that payload are not all hash-bound.
- Watchtower does not pause deposits, approve integrations, declare upgrades safe, generate LLM risk scores, or monitor arbitrary contracts.
Review packets do not authenticate their publisher, prevent exploits, or replace a smart-contract audit.
SYSTEM
From Base evidence to a readable result.
Provides the historical block, transaction, receipt, and log data.
The ChainReader boundary validates the shape and identity of RPC responses.
The scanner filters one configured proxy and one approved event topic.
On configured live Aave, Compound, or ether.fi scans, OpenRouter returns strictly validated decisions selecting only registered check IDs.
Assertions, limitations, links, and disposition are normalized into records.
The static workspace renders the archive, trace, failures, and verification actions.
ARCHITECTURE
A small system with explicit boundaries.
Frontend
Vanilla HTML, CSS, and browser JavaScript served from public/. It renders the profile archive and investigation workspace.
Express API
Express exposes health, configuration, bounded scans, in-memory alerts, and validated receipt downloads.
Base RPC reader
viem provides read-only JSON-RPC access. The RPC URL stays server-side.
Rules and bounded agent
TypeScript selects a registered plan and executes fixed checks. An optional server-side OpenRouter adapter can choose follow-up check order but cannot control RPC parameters or outcomes.
Storage
Scan results, alerts, evidence, and live receipts are held in process memory. Committed fixture data powers the public archive.
External links
Recorded explorer links point to BaseScan. There is no notification service, worker, database, authentication layer, or wallet integration.
ALERTS
Alerts currently live in the Watchtower workspace.
The web UI and JSON API expose alerts created by a bounded scan. An alert includes the configured incident class, severity and rule, factual title and summary, observation time, evidence status, source links, and an associated investigation when trigger evidence is complete.
Upgraded(address) · complete evidence · corroborated
Telegram and Discord are not implemented alert-delivery channels in this repository. The public Telegram link is a project contact link only.
LIMITATIONS
Know what the evidence does not say.
Watchtower monitors configured deployed systems for observable upgrade evidence. It is not a smart-contract audit and does not guarantee that a contract is safe.
- Scope. Only three Base profiles and the configured
Upgraded(address)event are supported. - Historical access. Exact-block checks need an archive-capable provider. RPC outages, timeouts, rate limits, or pruned history can produce incomplete evidence.
- Agent availability. Live agent decisions require server-side OpenRouter credentials. Missing credentials or provider failure is shown explicitly and does not stop required deterministic checks.
- Live coverage. The live API scans one registered live-enabled profile and one approved historical range per request. Aave, Compound, and ether.fi are live-enabled, and all three also have verified fixture replays.
- Receipt distinction. The committed Aave fixture keeps its original receipt without a bytecode hash. A live Aave scan may include a reproducible implementation hash and therefore produce a different receipt ID.
- Persistence. Live alerts and receipts are in memory and disappear when the process restarts.
- Interpretation. Receipts do not establish identity, intent, causality, governance legitimacy, implementation safety, or remote cross-chain safety.
- Out of scope. There is no continuous monitoring, notification delivery, authentication, wallet access, transaction submission, database, multi-chain support, dynamic proxy discovery, or arbitrary RPC execution.
REFERENCE
Frequently asked questions.
Can Watchtower prevent an exploit?
No. It reports observable evidence after a configured event and does not prevent transactions or replace a smart-contract audit.
What are receipts?
Canonical JSON records whose SHA-256 IDs can be recomputed in the browser. They include the trigger, plan, checks, errors, limitations, disposition, and sources.
How quickly are changes detected?
There is no continuous monitoring or latency promise. The current live path is a bounded scan initiated by the user.
Can I monitor multiple contracts?
The registry contains three predefined profiles. The current MVP does not accept arbitrary contracts or open-ended project graphs.
Where can I inspect the source?
Use View source ↗ to open the public repository.