|
1 | 1 | # slashveto.me |
2 | 2 |
|
3 | | -slashveto.me helps Aztec sequencer operators answer two questions: |
4 | | - |
5 | | -1. Is one of my sequencers beginning to move through the slashing process? |
6 | | -2. What does confirmed L1 state say about slashing risk across the network? |
7 | | - |
8 | | -An operator enters one or more sequencer addresses. For each address, |
9 | | -slashveto.me should show a single, linked Slashing Timeline rather than a collection |
10 | | -of unrelated events: |
| 3 | +slashveto.me tracks an Aztec sequencer from the first observed duty miss to an |
| 4 | +L1 slash and ejection: |
11 | 5 |
|
12 | 6 | ```text |
13 | | -duty miss → node offense → L1 mention → candidate → execution delay |
| 7 | +duty miss → node offense → L1 vote → quorum → execution delay |
14 | 8 | → executable → executed → stake removed → ejection |
15 | 9 | ``` |
16 | 10 |
|
17 | | -That path can stop at any step. Examples include “one inactive epoch observed; |
18 | | -the configured consecutive-epoch threshold has not been met” and “candidate |
19 | | -slash becomes executable in two days; this node observed inactivity in the |
20 | | -target epoch.” The second statement deliberately says **node evidence**: |
21 | | -onchain slash votes contain a validator, target epoch, and penalty unit, but no |
22 | | -offense reason. |
| 11 | +A path can stop at any step. The product keeps candidate amounts, executed |
| 12 | +rounds, and actual stake deductions separate. L1 votes do not encode an |
| 13 | +offense reason; a displayed reason is always labelled as evidence from the |
| 14 | +attached Aztec node. |
23 | 15 |
|
24 | | -## Two independent views |
| 16 | +## Surfaces |
25 | 17 |
|
26 | | -| Surface | Data source | Purpose | |
| 18 | +| Surface | Source | Purpose | |
27 | 19 | | --- | --- | --- | |
28 | | -| **Monitor** | Public Ethereum RPCs, queried by the browser | Backend-independent view of canonical contracts, rounds, votes, candidate actions, vetoes, execution, and actual slash logs. | |
29 | | -| **PINGME** | slashveto.me backend, one Aztec node, Ethereum RPCs | Earlier node and Sentinel warnings, linked per-sequencer history, realtime status, and Telegram or Web Push delivery. | |
30 | | - |
31 | | -The overlap is intentional. Monitor must remain useful when |
32 | | -`api.slashveto.me` or the attached Aztec node is unavailable. PINGME provides |
33 | | -continuity while a browser is closed and evidence that is not published to L1. |
34 | | -Neither view is an oracle: local evidence is an observer's report, while L1 |
35 | | -reveals voting and stake outcomes but not the underlying offense. |
36 | | - |
37 | | -Both views expose the same case feed and educational Slashing Timeline. |
38 | | -Watchlists can be shared as address-only URLs without exposing PINGME's private |
39 | | -management capability. Individual cases retain a compact copy-link action for |
40 | | -alerts and investigations. |
41 | | - |
42 | | -Watchlist rows collapse cases per sequencer and retain a compact stake and |
43 | | -pending-amount summary. The public feed collapses only cases that share an |
44 | | -exact payload address. |
45 | | - |
46 | | -## Read this first |
47 | | - |
48 | | -- [Aztec protocol model](docs/protocol.md) — slots, blocks, checkpoints, |
49 | | - committees, proposals, signals, and proofs |
50 | | -- [Slashing and ejection](docs/slashing.md) — all v5 offenses and the exact |
51 | | - warning-to-stake-removal lifecycle |
52 | | -- [Monitor architecture](docs/architecture.md) — trust boundaries, case |
53 | | - linking, and requirements for the refactor |
54 | | -- [V3 architecture record](docs/v3-plan.md) — the implemented case-first |
55 | | - clean break and its acceptance contract |
56 | | -- [Notification contract](docs/notifications.md) — what an alert may claim at |
57 | | - each stage |
58 | | -- [Privacy](docs/privacy.md) and [production runbook](docs/runbook.md) |
59 | | - |
60 | | -The protocol documentation was researched against the active Aztec mainnet |
61 | | -deployment and `aztec-packages` commit |
62 | | -[`def7152a`](https://github.com/AztecProtocol/aztec-packages/tree/def7152aa13dc0f880f24e45ce39442908170878) |
63 | | -on 2026-07-29. Parameters and canonical contracts are upgradeable. Runtime |
64 | | -views must resolve them from the Registry and read their current values rather |
65 | | -than treating the examples in these documents as constants. |
| 20 | +| **Monitor** | Ethereum RPC queried in the browser | Independent view of canonical contracts, votes, candidates, execution, and slash logs. | |
| 21 | +| **PINGME** | Backend using one Aztec node and Ethereum RPC | Earlier Sentinel/offense evidence, durable cases, and Telegram or Web Push alerts. | |
| 22 | + |
| 23 | +Monitor never calls the backend. PINGME keeps the last known state when one |
| 24 | +source fails and reports that source as stale. Neither surface is an oracle: |
| 25 | +node evidence is one observer's report, while L1 establishes contract state |
| 26 | +without revealing the reason behind a vote. |
| 27 | + |
| 28 | +The primary object is a slashing case: network, contract lineage, sequencer, |
| 29 | +and target epoch with its source observations and state transitions. Linking is |
| 30 | +exact and conservative. An actual slash joins through its execution transaction |
| 31 | +and action order, never by address and approximate time. |
| 32 | + |
| 33 | +## Repository |
| 34 | + |
| 35 | +- `shared/protocol/` contains the pure case projection, tallying, transitions, |
| 36 | + and notification wording shared by frontend and backend. |
| 37 | +- `src/` contains the React PWA and independent browser L1 collector. |
| 38 | +- `collector/` contains the Node backend, SQLite repository, three evidence |
| 39 | + collectors, API, durable outbox, Telegram, and Web Push. |
| 40 | +- `scripts/deploy-backend.sh` installs an immutable backend release under |
| 41 | + systemd. |
| 42 | + |
| 43 | +The backend API is rooted at `/api`. `/live` reports process liveness and |
| 44 | +`/health` reports whether the required evidence sources are current. |
| 45 | + |
| 46 | +| Method | Route | Purpose | |
| 47 | +| --- | --- | --- | |
| 48 | +| `GET` | `/api/config`, `/api/status`, `/api/network` | Capabilities, freshness, protocol state, and public cases | |
| 49 | +| `GET` | `/api/sequencers/:address`, `/api/cases/:id` | Public sequencer and exact-case views | |
| 50 | +| `POST` | `/api/watches` | Create a private watch and return its management token once | |
| 51 | +| `GET/PATCH/DELETE` | `/api/watches/:id` | Bearer-authenticated watch management | |
| 52 | +| `PUT/DELETE` | `/api/watches/:id/channels/web_push` | Web Push enrollment | |
| 53 | +| `POST` | `/api/watches/:id/channels/telegram-link` | One-time Telegram enrollment link | |
| 54 | +| `POST` | `/api/watches/:id/channels/test` | Queue a test alert | |
66 | 55 |
|
67 | 56 | ## Development |
68 | 57 |
|
69 | | -Use Node 24 and the pinned pnpm version: |
| 58 | +Node 24 and the pinned pnpm version are required: |
70 | 59 |
|
71 | 60 | ```bash |
72 | 61 | corepack enable |
73 | | -pnpm install |
| 62 | +pnpm install --frozen-lockfile |
74 | 63 | cp .env.example .env |
75 | 64 | cp collector/.env.example collector/.env |
76 | 65 | pnpm dev |
77 | 66 | pnpm dev:backend |
78 | 67 | ``` |
79 | 68 |
|
80 | | -Run `pnpm check` before deployment. All `VITE_*` values are public. RPC |
81 | | -credentials, Telegram tokens, VAPID private keys, and the Aztec admin endpoint |
82 | | -belong only in the backend environment. |
| 69 | +Run the release gate with: |
| 70 | + |
| 71 | +```bash |
| 72 | +pnpm check |
| 73 | +``` |
| 74 | + |
| 75 | +Every `VITE_*` value is public. RPC credentials, Aztec admin credentials, |
| 76 | +Telegram tokens, VAPID private keys, and the SQLite database belong only in the |
| 77 | +backend environment. The ignored `apiReference.md` and `onchainSources.md` are |
| 78 | +local research inputs, not runtime dependencies or published documentation. |
| 79 | + |
| 80 | +## Documentation |
| 81 | + |
| 82 | +- [Protocol and correctness model](docs/protocol.md) |
| 83 | +- [Notification contract](docs/notifications.md) |
| 84 | +- [Production runbook](docs/runbook.md) |
83 | 85 |
|
84 | | -The ignored `apiReference.md` and `onchainSources.md` files are research |
85 | | -snapshots, not runtime inputs or committed documentation. |
| 86 | +The protocol model was checked against the active Aztec mainnet deployment and |
| 87 | +[`aztec-packages` commit `def7152a`](https://github.com/AztecProtocol/aztec-packages/tree/def7152aa13dc0f880f24e45ce39442908170878) |
| 88 | +on 2026-07-29. Contracts and parameters are upgradeable; runtime code discovers |
| 89 | +the responsible lineage and reads its values. |
0 commit comments