publicize dn

Author: sekuba

README.md

@@ -62,5 +62,5 @@ 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.
 
-The destructive one-time backend switch is documented in the runbook and runs
-as `scripts/switch-backend.sh --fresh`.
+Production backend deployments use `scripts/deploy-backend.sh`: `--fresh`
+resets all state, while `--upgrade` preserves and backs up the current database.

collector/README.md

@@ -91,12 +91,13 @@ requests require it as `Authorization: Bearer …`. A PATCH replaces the address
 list; deleting a subscription removes the watch and its channels.
 
 `GET /live` reports process liveness. `GET /health` reports operational source
-and delivery health. Public events include node-local and L1 observations but never
-watch/address associations, provider endpoints, or delivery metadata. For an L1
-round, `data.nodeEvidence` contains every earlier node offense or completed
-inactive epoch matching both the target address and one of the round's target
-epochs. This is explicitly correlated node evidence: L1 votes and payloads do
-not encode an offense type.
+and delivery health. Public events include node-local, Sentinel, and L1
+observations but never watch/address associations, provider endpoints, or
+delivery metadata. Catch-up and notification-test events remain
+endpoint-scoped. For an L1 round, `data.nodeEvidence` contains every earlier
+node offense or completed inactive epoch matching both the target address and
+one of the round's target epochs. This is explicitly correlated node evidence:
+L1 votes and payloads do not encode an offense type.
 
 ## Storage and delivery
 

collector/src/api-server.mjs

@@ -17,6 +17,7 @@ import {
 
 const WATCHLIST_ID_PATTERN = /^[0-9a-f-]{36}$/i;
 const MAX_SEQUENCER_FILTERS = 100;
+const PUBLIC_EVENT_SOURCES = ['aztec_node', 'aztec_sentinel', 'ethereum_l1'];
 
 export class CollectorApiServer {
   constructor({
@@ -190,7 +191,7 @@ export class CollectorApiServer {
       const query = parseEventQuery(url.searchParams, this.network);
       const page = this.repository.listEvents({
         ...query,
-        sources: ['aztec_node', 'ethereum_l1'],
+        sources: PUBLIC_EVENT_SOURCES,
       });
       return writeJson(response, 200, {
         schemaVersion: 2,
@@ -206,7 +207,7 @@ export class CollectorApiServer {
       }
       const network = normalizeNetwork(url.searchParams.get('network') ?? this.network, this.network);
       const event = this.repository.getEvent(id);
-      if (!event || event.network !== network || !['aztec_node', 'ethereum_l1'].includes(event.source)) {
+      if (!event || event.network !== network || !PUBLIC_EVENT_SOURCES.includes(event.source)) {
         throw new HttpError(404, 'event_not_found', 'Event not found');
       }
       return writeJson(response, 200, {

collector/test/api-server.test.mjs

@@ -595,6 +595,45 @@ test('anonymous reads and watch-list creation have tighter independent limits',
   assert.equal(secondCreate.body.error.code, 'subscription_rate_limited');
 });
 
+test('public journal exposes Sentinel precursor feed and detail', async (t) => {
+  const repository = healthyRepository();
+  repository.recordEvent({
+    id: 'sentinel-first-miss',
+    network: 'mainnet',
+    source: 'aztec_sentinel',
+    type: 'inactivity_first_miss',
+    severity: 'warning',
+    title: 'First missed duty observed',
+    body: 'Precursor evidence, not a registered slash offense.',
+    data: {
+      certainty: 'pending',
+      sequencer: SEQUENCER_A,
+      epoch: '42',
+      slot: '1344',
+    },
+    observedAt: NOW,
+  }, [SEQUENCER_A]);
+  const { baseUrl } = await startApi(t, repository);
+
+  const feedResponse = await fetch(
+    `${baseUrl}/api/v2/events?network=mainnet&address=${SEQUENCER_A}`,
+  );
+  assert.equal(feedResponse.status, 200);
+  const feed = await feedResponse.json();
+  assert.deepEqual(
+    feed.data
+      .filter((event) => event.id === 'sentinel-first-miss')
+      .map(({ source, type, certainty }) => ({ source, type, certainty })),
+    [{ source: 'aztec_sentinel', type: 'inactivity_first_miss', certainty: 'pending' }],
+  );
+
+  const detailResponse = await fetch(
+    `${baseUrl}/api/v2/events/sentinel-first-miss?network=mainnet`,
+  );
+  assert.equal(detailResponse.status, 200);
+  assert.equal((await detailResponse.json()).data.type, 'inactivity_first_miss');
+});
+
 function healthyRepository() {
   const repository = new OffenseRepository(':memory:');
   const [offense] = parseOffenseSnapshot([OFFENSE_A]);

docs/architecture.md

@@ -40,6 +40,10 @@ There are three event sources:
 - `ethereum_l1` events come from coherently pinned canonical contract reads or
   confirmed `Slashed` logs. They are `confirmed`.
 
+All three observation sources are present in the public journal. Authenticated
+watch-list event reads are address-scoped views of the same journal, while
+catch-up and notification-test artifacts remain endpoint-scoped.
+
 The backend checks node chain, Registry, and Rollup identity before trusting
 admin results. It retains prior state when a source fails. An offense can
 disappear only after a ready, fresh, non-regressing node cursor advances past

docs/privacy.md

@@ -17,9 +17,11 @@ Slashmon never needs validator keys, seed phrases, wallet signatures, or an
 Aztec keystore. Protect the database and backups as secrets. The systemd unit
 uses a private state directory and `UMask=0077`.
 
-Public API responses expose source health and public-address observations. They
-do not expose watch membership, channel endpoints, tokens, or delivery state.
-Catch-up and notification-test events remain endpoint-scoped.
+Public API responses expose source health and all public-address observation
+events from the Aztec node, Sentinel, and Ethereum L1. They do not expose watch
+membership, channel endpoints, tokens, or delivery state. Catch-up and
+notification-test events remain endpoint-scoped because they describe a
+recipient's delivery lifecycle rather than a public network observation.
 
 ## Provider exposure
 

docs/runbook.md

@@ -4,21 +4,6 @@ The supported production deployment is one Node 24 backend under systemd, one
 SQLite database, and an HTTPS reverse proxy. Never run two backend instances for
 the same installation.
 
-## Switch from an older backend
-
-From a clean checkout of the commit to deploy, run:
-
-```bash
-scripts/switch-backend.sh --fresh
-```
-
-The script keeps supported credentials and endpoints from
-`/etc/slashmon-backend.env`, installs the current commit, removes the old service
-unit, and starts `slashmon-backend.service`. It permanently removes the old and
-new Slashmon state directories plus `/var/backups/slashmon`; it creates no
-database backup and provides no automatic rollback. Run it only when losing all
-existing watches, events, delivery state, and checkpoints is intended.
-
 ## Prepare
 
 Install Node 24 at `/usr/local/bin/node`, enable Corepack, and create the
@@ -53,7 +38,7 @@ Override `AZTEC_SENTINEL_POLL_INTERVAL_MS`,
 `AZTEC_SENTINEL_EPOCH_END_BUFFER_SLOTS`,
 `AZTEC_SENTINEL_VALIDATOR_CONCURRENCY`, or
 `AZTEC_SENTINEL_VALIDATOR_MAX_RESPONSE_BYTES` only for an observed node or RPC
-constraint. The fresh-switch script preserves these settings.
+constraint. The deployment script preserves these settings.
 
 Telegram and Web Push are independently optional. Create one Telegram bot or
 generate a stable VAPID keypair:
@@ -64,26 +49,27 @@ pnpm --filter @slashmon/backend exec web-push generate-vapid-keys
 
 Changing VAPID keys requires browsers to subscribe again.
 
-## Install
+## Deploy
 
-Create an immutable release and install production dependencies:
+Run one mode from a clean checkout of the commit to deploy:
 
 ```bash
-revision="$(git rev-parse --short=12 HEAD)"
-release="/opt/slashmon/releases/$revision"
-sudo install -d -m 0755 "$release"
-git archive HEAD | sudo tar -x -C "$release"
-sudo corepack pnpm --dir "$release" install --prod --frozen-lockfile
-sudo ln -sfn "$release" /opt/slashmon/current
-sudo install -m 0644 collector/deploy/slashmon-backend.service /etc/systemd/system/
-sudo systemctl daemon-reload
-sudo systemctl enable --now slashmon-backend.service
+scripts/deploy-backend.sh --fresh
+scripts/deploy-backend.sh --upgrade
 ```
 
-The unit creates `/var/lib/slashmon` and stores
-`/var/lib/slashmon/slashmon.sqlite`. Startup accepts an empty database or the
-current schema only. Archive any database from an older Slashmon implementation
-and start clean; there is intentionally no migration path.
+Use `--fresh` for the first deployment or an intentionally incompatible reset.
+It permanently removes all Slashmon state and `/var/backups/slashmon`; it
+creates no backup. Use `--upgrade` for a compatible release. It stops the only
+writer, checkpoints and checks SQLite, saves a timestamped database under
+`/var/backups/slashmon`, switches the immutable release, and restarts the
+service without deleting state. Keep the previous release and backup until
+source polls and test deliveries succeed. Neither mode provides automatic
+rollback.
+
+The unit stores the database at `/var/lib/slashmon/slashmon.sqlite`. Startup
+accepts an empty database or the current schema only; there is no migration
+path.
 
 To self-host the PWA, install all dependencies and run `pnpm build` in the
 release. Serve `dist/` as static files. Frontend RPC URLs must be public HTTPS
@@ -137,23 +123,5 @@ Repeatedly restarting does not repair a stale node or RPC. Web Push 404/410 is
 endpoint-specific; shared authentication failures keep urgent work retryable
 and degrade channel health.
 
-## Backup and upgrade
-
-Stop the only writer, checkpoint and check SQLite, then copy the database:
-
-```bash
-sudo systemctl stop slashmon-backend.service
-database=/var/lib/slashmon/slashmon.sqlite
-sudo sqlite3 "$database" 'PRAGMA wal_checkpoint(TRUNCATE);'
-test "$(sudo sqlite3 "$database" 'PRAGMA quick_check;')" = ok
-sudo install -d -m 0700 /var/backups/slashmon
-sudo cp --preserve=mode,ownership,timestamps "$database" /var/backups/slashmon/
-sudo systemctl start slashmon-backend.service
-```
-
-For an upgrade, install a new immutable release, take this backup, switch the
-`/opt/slashmon/current` symlink while stopped, and start the service. Keep the
-previous release and backup until source polls and test deliveries succeed.
-
 Delivery is at-least-once. A crash after provider acceptance but before the
 success commit can duplicate an alert; stable event IDs are the comparison key.