Merge pull request #23 from sekuba/v33

V33

Author: sekuba

.env.example

@@ -1,4 +1,4 @@
-# Slashmon frontend build configuration.
+# slashveto.me frontend build configuration.
 # Every VITE_* value is shipped to every browser. Secrets do not belong here.
 
 # Production Pages builds use https://api.slashveto.me. Empty means same-origin
@@ -15,13 +15,12 @@ VITE_API_BASE_URL=
 # Pages monitor, but private notification watches are disabled on *.github.io.
 VITE_BASE_PATH=/
 
-# Public Ethereum RPCs used by the browser's independent L1 view.
-# Comma-separated URLs enable failover. A missing value fails visibly instead
-# of probing the browser user's localhost.
+# One public Ethereum RPC per network for the independent browser view. A
+# missing value fails visibly instead of probing the browser user's localhost.
 VITE_L1_RPC_URL=https://1rpc.io/eth
 VITE_REGISTRY_ADDRESS=0x35b22e09Ee0390539439E24f06Da43D83f90e298
 VITE_TESTNET_L1_RPC_URL=https://0xrpc.io/sep
 VITE_TESTNET_REGISTRY_ADDRESS=0xA0BFb1B494FB49041e5c6e8c2C1BE09cD171c6Ba
 
 # The Web Push public key is deliberately not a VITE_* variable. The frontend
-# fetches it from GET /api/v2/config; its private half stays on the backend.
+# fetches it from GET /api/config; its private half stays on the backend.

.github/workflows/deploy.yml

@@ -48,39 +48,28 @@ jobs:
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
 
-      - name: Require reachable HTTPS endpoints for the PWA
+      - name: Require HTTPS endpoints for the PWA
         env:
           PUBLIC_API_ORIGIN: https://api.slashveto.me
-          MAINNET_L1_RPC_URLS: ${{ vars.VITE_L1_RPC_URL }}
-          TESTNET_L1_RPC_URLS: ${{ vars.VITE_TESTNET_L1_RPC_URL }}
+          MAINNET_L1_RPC_URL: ${{ vars.VITE_L1_RPC_URL }}
+          TESTNET_L1_RPC_URL: ${{ vars.VITE_TESTNET_L1_RPC_URL }}
         run: |
-          require_https_list() {
+          require_https_url() {
             local name="$1"
             local value="$2"
 
-            if [[ -z "$value" ]]; then
+            if [[ -z "$value" || "$value" != https://* || "$value" == *,* ]]; then
               echo "Set the $name repository variable; Pages must never ship a localhost fallback."
               return 1
             fi
-
-            local endpoints
-            IFS=',' read -ra endpoints <<< "$value"
-            for endpoint in "${endpoints[@]}"; do
-              endpoint="${endpoint#"${endpoint%%[![:space:]]*}"}"
-              endpoint="${endpoint%"${endpoint##*[![:space:]]}"}"
-              if [[ "$endpoint" != https://* ]]; then
-                echo "$name must contain only HTTPS URLs."
-                return 1
-              fi
-            done
           }
 
           if [[ -z "$PUBLIC_API_ORIGIN" || "$PUBLIC_API_ORIGIN" != https://* || "$PUBLIC_API_ORIGIN" == *,* ]]; then
             echo "VITE_API_BASE_URL must be one public HTTPS API origin."
             exit 1
           fi
-          require_https_list VITE_L1_RPC_URL "$MAINNET_L1_RPC_URLS"
-          require_https_list VITE_TESTNET_L1_RPC_URL "$TESTNET_L1_RPC_URLS"
+          require_https_url VITE_L1_RPC_URL "$MAINNET_L1_RPC_URL"
+          require_https_url VITE_TESTNET_L1_RPC_URL "$TESTNET_L1_RPC_URL"
 
       - name: Lint, test, syntax-check, and build
         run: pnpm check

README.md

@@ -1,68 +1,89 @@
-# Slashmon
+# slashveto.me
 
-Slashmon watches Aztec slashing and has two deliberately separate parts:
+slashveto.me tracks an Aztec sequencer from the first observed duty miss to an
+L1 slash and ejection:
 
-- **Monitor** is a browser-only view of public Ethereum state. It resolves the
-  canonical Aztec contracts and checks slashing rounds directly through public
-  L1 RPCs. Its on-page details panel can select a browser-local RPC and inspect
-  the resolved deployment metadata.
-- **PINGME** is the backend UI. It can search the complete journal for one
-  sequencer, manage address watches, and send matched alerts through Telegram
-  or Web Push. The backend records per-duty inactivity precursors and
-  registered offenses from one Aztec node, then verifies L1 slashing state.
+```text
+duty miss → node offense → L1 vote → quorum → execution delay
+          → executable → executed → stake removed → ejection
+```
 
-Node-local offenses are early warnings, not consensus. Slashmon labels them
-`pending`. Ethereum observations are labelled `confirmed`. The backend never
-turns one node's opinion into L1 truth.
+A path can stop at any step. The product keeps candidate amounts, executed
+rounds, and actual stake deductions separate. L1 votes do not encode an
+offense reason; a displayed reason is always labelled as evidence from the
+attached Aztec node.
 
-## Repository
+## Surfaces
+
+| Surface | Source | Purpose |
+| --- | --- | --- |
+| **Monitor** | Ethereum RPC queried in the browser | Independent view of canonical contracts, votes, candidates, execution, and slash logs. |
+| **PINGME** | Backend using one Aztec node and Ethereum RPC | Earlier Sentinel/offense evidence, durable cases, and Telegram or Web Push alerts. |
 
-- `src/` — React/Vite PWA containing Monitor and PINGME
-- `collector/` — Node backend, SQLite journal, and notification delivery
-- [`docs/architecture.md`](docs/architecture.md) — data flow and trust boundaries
-- [`docs/notifications.md`](docs/notifications.md) — notification stages, required context, and links
-- [`docs/runbook.md`](docs/runbook.md) — production deployment and operations
-- [`docs/privacy.md`](docs/privacy.md) — stored data and provider exposure
+Monitor never calls the backend. PINGME keeps the last known state when one
+source fails and reports that source as stale. Neither surface is an oracle:
+node evidence is one observer's report, while L1 establishes contract state
+without revealing the reason behind a vote.
+
+The primary object is a slashing case: network, contract lineage, sequencer,
+and target epoch with its source observations and state transitions. Linking is
+exact and conservative. An actual slash joins through its execution transaction
+and action order, never by address and approximate time.
+
+## Repository
 
-The ignored `apiReference.md` and `onchainSources.md` files are research
-material. Runtime behavior must live in committed code, ABIs, and tests.
+- `shared/protocol/` contains the pure case projection, tallying, transitions,
+  and notification wording shared by frontend and backend.
+- `src/` contains the React PWA and independent browser L1 collector.
+- `collector/` contains the Node backend, SQLite repository, three evidence
+  collectors, API, durable outbox, Telegram, and Web Push.
+- `scripts/deploy-backend.sh` installs an immutable backend release under
+  systemd.
+
+The backend API is rooted at `/api`. `/live` reports process liveness and
+`/health` reports whether the required evidence sources are current.
+
+| Method | Route | Purpose |
+| --- | --- | --- |
+| `GET` | `/api/config`, `/api/status`, `/api/network` | Capabilities, freshness, protocol state, and public cases |
+| `GET` | `/api/sequencers/:address`, `/api/cases/:id` | Public sequencer and exact-case views |
+| `POST` | `/api/watches` | Create a private watch and return its management token once |
+| `GET/PATCH/DELETE` | `/api/watches/:id` | Bearer-authenticated watch management |
+| `PUT/DELETE` | `/api/watches/:id/channels/web_push` | Web Push enrollment |
+| `POST` | `/api/watches/:id/channels/telegram-link` | One-time Telegram enrollment link |
+| `POST` | `/api/watches/:id/channels/test` | Queue a test alert |
 
 ## Development
 
-Use Node 24 and the pinned pnpm release:
+Node 24 and the pinned pnpm version are required:
 
 ```bash
 corepack enable
-pnpm install
+pnpm install --frozen-lockfile
 cp .env.example .env
 cp collector/.env.example collector/.env
-```
-
-Run the two processes in separate terminals:
-
-```bash
 pnpm dev
 pnpm dev:backend
 ```
 
-For local cross-origin development, set
-`VITE_API_BASE_URL=http://127.0.0.1:8790`; the backend example already allows
-`http://localhost:5173`. Alternatively leave `VITE_API_BASE_URL` empty and set
-`SLASHMON_DEV_API_PROXY_TARGET` for Vite's same-origin development proxy.
-
-Run the complete quality gate with:
+Run the release gate with:
 
 ```bash
 pnpm check
 ```
 
-All `VITE_*` values are public browser configuration. Backend RPC credentials,
-Telegram tokens, and VAPID private keys belong only in `collector/.env` or the
-production environment file.
+Every `VITE_*` value is public. RPC credentials, Aztec admin credentials,
+Telegram tokens, VAPID private keys, and the SQLite database belong only in the
+backend environment. The ignored `apiReference.md` and `onchainSources.md` are
+local research inputs, not runtime dependencies or published documentation.
+
+## Documentation
 
-Notification watches use a bearer capability stored by browser origin. Host a
-production PINGME installation on a dedicated origin and do not add third-party
-scripts. A shared GitHub Pages origin is suitable only for the public Monitor.
+- [Protocol and correctness model](docs/protocol.md)
+- [Notification contract](docs/notifications.md)
+- [Production runbook](docs/runbook.md)
 
-Production backend deployments use `scripts/deploy-backend.sh`: `--fresh`
-resets all state, while `--upgrade` preserves and backs up the current database.
+The protocol model was checked against the active Aztec mainnet deployment and
+[`aztec-packages` commit `def7152a`](https://github.com/AztecProtocol/aztec-packages/tree/def7152aa13dc0f880f24e45ce39442908170878)
+on 2026-07-29. Contracts and parameters are upgradeable; runtime code discovers
+the responsible lineage and reads its values.

collector/.env.example

@@ -1,58 +1,22 @@
-# Backend identity and browser origin.
-SLASHMON_NETWORK=mainnet
+# Local backend. These URLs are the built-in defaults and are shown here so
+# the three required upstreams are explicit.
 SLASHMON_PUBLIC_URL=http://localhost:5173
 BACKEND_CORS_ORIGIN=http://localhost:5173
-
-# Public node RPC and private admin RPC for the same Aztec node.
 AZTEC_NODE_URL=http://127.0.0.1:8080
-AZTEC_NODE_API_KEY=
 AZTEC_ADMIN_URL=http://127.0.0.1:8880
-AZTEC_ADMIN_API_KEY=
-AZTEC_SENTINEL_POLL_INTERVAL_MS=60000
-AZTEC_SENTINEL_LOOKBACK_EPOCHS=3
-AZTEC_SENTINEL_EPOCH_END_BUFFER_SLOTS=2
-AZTEC_SENTINEL_VALIDATOR_CONCURRENCY=8
-AZTEC_SENTINEL_VALIDATOR_MAX_RESPONSE_BYTES=2097152
-
-# Comma-separated Ethereum RPCs. The network selects the chain and Registry.
 L1_RPC_URL=http://127.0.0.1:8545
-# L1_REGISTRY_ADDRESS=
-L1_SLASH_LOG_LOOKBACK_BLOCKS=600
-
-# Enable Telegram only when both values are set.
-TELEGRAM_BOT_TOKEN=
-TELEGRAM_BOT_USERNAME=
-
-# Enable Web Push only when all three values are set.
-VAPID_SUBJECT=
-VAPID_PUBLIC_KEY=
-VAPID_PRIVATE_KEY=
 
-BACKEND_DATABASE_PATH=./data/slashmon.sqlite
-BACKEND_BIND_HOST=127.0.0.1
-BACKEND_PORT=8790
-BACKEND_TRUST_PROXY=false
+# Add only when required by the endpoints above.
+# AZTEC_NODE_API_KEY=
+# AZTEC_ADMIN_API_KEY=
 
-# Abuse controls. Defaults suit a small public deployment; raise deliberately
-# if normal traffic grows. Per-IP limits require a trusted loopback proxy to
-# overwrite X-Real-IP or X-Forwarded-For.
-BACKEND_READ_RATE_LIMIT_MAX_PER_MINUTE=180
-BACKEND_READ_RATE_LIMIT_MAX_PER_MINUTE_GLOBAL=600
-BACKEND_MUTATION_RATE_LIMIT_MAX_PER_MINUTE=20
-BACKEND_WATCHLIST_MUTATION_RATE_LIMIT_MAX_PER_MINUTE=20
-BACKEND_SUBSCRIPTION_CREATE_MAX_PER_HOUR_PER_IP=3
-BACKEND_SUBSCRIPTION_CREATE_MAX_PER_DAY_PER_IP=10
-BACKEND_SUBSCRIPTION_CREATE_MAX_PER_HOUR_GLOBAL=10
-BACKEND_SUBSCRIPTION_CREATE_MAX_PER_DAY_GLOBAL=50
-BACKEND_NOTIFICATION_TEST_COOLDOWN_MS=300000
-BACKEND_NOTIFICATION_TEST_MAX_PER_HOUR_GLOBAL=30
-BACKEND_NOTIFICATION_TEST_MAX_PER_DAY_GLOBAL=100
-BACKEND_WEB_PUSH_ENROLLMENT_MAX_PER_HOUR_PER_WATCHLIST=3
-BACKEND_WEB_PUSH_ENROLLMENT_MAX_PER_DAY_PER_WATCHLIST=10
-BACKEND_WEB_PUSH_ENROLLMENT_MAX_PER_HOUR_GLOBAL=20
-BACKEND_WEB_PUSH_ENROLLMENT_MAX_PER_DAY_GLOBAL=100
-TELEGRAM_SEND_MAX_PER_SECOND=20
-TELEGRAM_LOW_PRIORITY_SEND_MAX_PER_SECOND=5
-TELEGRAM_CHAT_SEND_INTERVAL_MS=1000
+# Uncomment for an exact mainnet backfill from the first current-stack Rollup
+# block. Historical observations are indexed without sending notifications.
+# L1_SLASH_LOG_START_BLOCK=25533241
 
-BACKEND_LOG_LEVEL=info
+# Optional channels. Each group must be complete.
+# TELEGRAM_BOT_TOKEN=
+# TELEGRAM_BOT_USERNAME=
+# VAPID_SUBJECT=mailto:operator@example.com
+# VAPID_PUBLIC_KEY=
+# VAPID_PRIVATE_KEY=