notifs

Author: sekuba

collector/src/channels.mjs

@@ -336,7 +336,7 @@ export class TelegramChannel {
     const icon = event.severity === 'critical' ? '🚨' : event.severity === 'warning' ? '⚠️' : '🛰️';
     const url = new URL(notificationPath(event), this.publicUrl).toString();
     const references = [
-      `slashveto.me case: ${url}`,
+      `Case: ${url}`,
       ...dashtecReferenceLines(event),
       ...etherscanReferenceLines(event),
     ];

collector/src/notification-content.mjs

@@ -5,7 +5,7 @@ export function formatNotificationBody(transition) {
   const body = typeof transition?.body === 'string' ? transition.body.trim() : '';
   const sequencer = transitionSequencer(transition);
   return sequencer
-    ? `Sequencer: ${shortAddress(sequencer)}${body ? `\n${body}` : ''}`
+    ? `Sequencer: ${sequencer}${body ? `\n${body}` : ''}`
     : body;
 }
 
@@ -25,23 +25,14 @@ export function etherscanReferenceLines(transition) {
     : 'https://etherscan.io';
   const lines = [];
   if (HASH.test(String(data.transactionHash ?? ''))) {
-    lines.push(`Etherscan transaction: ${origin}/tx/${data.transactionHash}`);
-  }
-  if (/^\d+$/.test(String(data.blockNumber ?? ''))) {
-    lines.push(`Etherscan block: ${origin}/block/${data.blockNumber}`);
-  }
-  if (ADDRESS.test(String(data.payloadAddress ?? ''))) {
-    lines.push(`Etherscan candidate payload: ${origin}/address/${data.payloadAddress}`);
+    lines.push(`Transaction: ${origin}/tx/${data.transactionHash}`);
   }
   return lines;
 }
 
 function transitionSequencer(transition) {
-  const value = transition?.data?.sequencer ?? transition?.targets?.[0];
+  const targets = Array.isArray(transition?.targets) ? transition.targets : [];
+  const value = transition?.data?.sequencer ?? (targets.length === 1 ? targets[0] : null);
   const normalized = String(value ?? '').toLowerCase();
   return ADDRESS.test(normalized) ? normalized : null;
 }
-
-function shortAddress(value) {
-  return `${value.slice(0, 6)}…${value.slice(-4)}`;
-}

collector/test/case-repository.test.mjs

@@ -75,6 +75,49 @@ test('CaseRepository projects transitions and queues only matching watched seque
   repository.close();
 });
 
+test('L1 ballots queue only the first vote and quorum', () => {
+  const repository = createRepository();
+  repository.createWatch({
+    id: 'aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa',
+    managementTokenHash: 'hash',
+    network: 'mainnet',
+    addresses: [SEQUENCER],
+    now: 1_700_000_000_000,
+  });
+  repository.upsertEndpoint({
+    watchId: 'aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa',
+    kind: 'telegram',
+    destination: '1234',
+    now: 1_700_000_000_000,
+  });
+
+  const firstVote = repository.recordObservations([
+    l1Vote('vote-1', '2023-11-14T22:15:20.000Z', 1),
+  ], { protocol: protocol() });
+  assert.equal(firstVote.transitions, 1);
+  assert.equal(firstVote.queued, 1);
+
+  const secondVote = repository.recordObservations([
+    l1Vote('vote-2', '2023-11-14T22:16:20.000Z', 2),
+  ]);
+  assert.equal(secondVote.transitions, 0);
+  assert.equal(secondVote.queued, 0);
+
+  const quorum = repository.recordObservations([
+    l1Vote('quorum', '2023-11-14T22:17:20.000Z', 2, '100'),
+  ]);
+  assert.equal(quorum.transitions, 1);
+  assert.equal(quorum.queued, 1);
+
+  const item = repository.getCase(repository.listCases({ network: 'mainnet' })[0].id);
+  assert.equal(item.state.stage, 'candidate');
+  assert.deepEqual(item.transitions.map((transition) => transition.toStage), [
+    'l1_support',
+    'candidate',
+  ]);
+  repository.close();
+});
+
 test('L1 snapshots preserve a repeated sequencer as two exact target-epoch cases', () => {
   const repository = createRepository();
   repository.recordSuccessfulL1Snapshot('mainnet', {
@@ -456,3 +499,34 @@ function observation(id, kind, data) {
     data,
   };
 }
+
+function l1Vote(id, observedAt, support, amount = null) {
+  return {
+    id,
+    network: 'mainnet',
+    source: 'ethereum_l1',
+    kind: 'l1_round',
+    sequencer: SEQUENCER,
+    lineageId: PROPOSER,
+    targetEpoch: '8',
+    round: '10',
+    provenance: {
+      observedAt,
+      blockNumber: '100',
+      blockHash: BLOCK_HASH,
+      canonical: true,
+    },
+    data: {
+      round: '10',
+      status: amount ? 'quorum-reached' : 'below-quorum',
+      support,
+      quorum: 2,
+      amount,
+      payloadAddress: amount ? PAYLOAD : null,
+      isExecuted: false,
+      isVetoed: false,
+      stable: false,
+      escaped: false,
+    },
+  };
+}

collector/test/channels.test.mjs

@@ -24,6 +24,7 @@ const EVENT = {
     chainId: 1,
     blockNumber: '25587802',
     payloadAddress: '0x2222222222222222222222222222222222222222',
+    transactionHash: `0x${'34'.repeat(32)}`,
   },
 };
 
@@ -55,10 +56,12 @@ test('WebPushChannel builds a scoped high-urgency payload and returns the provid
   assert.equal(payload.title, EVENT.title);
   assert.equal(
     payload.body,
-    'Sequencer: 0x1111…1111\nA confirmed payload targets 0x1111…1111.',
+    'Sequencer: 0x1111111111111111111111111111111111111111\n' +
+      'A confirmed payload targets 0x1111…1111.',
   );
   assert.equal(payload.data.caseId, EVENT.data.caseId);
   assert.equal(payload.data.url, notificationPath(EVENT));
+  assert.doesNotMatch(payload.body, /https?:\/\//);
   assert.equal(
     payload.data.url,
     '?view=pingme&network=mainnet&case=case%3Amainnet%3Alineage%3A0x1111111111111111111111111111111111111111%3A24',
@@ -290,11 +293,12 @@ test('TelegramClient long polling and TelegramChannel preserve routing semantics
   assert.equal(message.chatId, '-100123');
   assert.deepEqual(message.options, { priority: 'alert' });
   assert.match(message.text, /^🚨 Sequencer targeted/);
-  assert.match(message.text, /Sequencer: 0x1111…1111/);
-  assert.match(message.text, /slashveto\.me case: https:\/\/slashveto\.example\/base\/\?view=pingme&network=mainnet&case=case%3Amainnet%3Alineage%3A0x1111111111111111111111111111111111111111%3A24/);
+  assert.match(message.text, /Sequencer: 0x1111111111111111111111111111111111111111/);
+  assert.match(message.text, /Case: https:\/\/slashveto\.example\/base\/\?view=pingme&network=mainnet&case=case%3Amainnet%3Alineage%3A0x1111111111111111111111111111111111111111%3A24/);
   assert.match(message.text, /Dashtec: https:\/\/dashtec\.xyz\/sequencers\/0x1111111111111111111111111111111111111111/);
-  assert.match(message.text, /Etherscan block: https:\/\/etherscan\.io\/block\/25587802/);
-  assert.match(message.text, /Etherscan candidate payload: https:\/\/etherscan\.io\/address\/0x2222222222222222222222222222222222222222$/);
+  assert.match(message.text, /Transaction: https:\/\/etherscan\.io\/tx\/0x3434343434343434343434343434343434343434343434343434343434343434/);
+  assert.doesNotMatch(message.text, /Etherscan block/);
+  assert.doesNotMatch(message.text, /candidate payload/);
 });
 
 test('TelegramChannel keeps queued alerts retryable until the bot identity is validated', async () => {

collector/test/notification-content.test.mjs

@@ -9,16 +9,16 @@ import {
 
 const SEQUENCER = '0x1111111111111111111111111111111111111111';
 
-test('case transition content identifies one sequencer and preserves educational copy', () => {
+test('case transition content identifies the full sequencer without repeating the heading', () => {
   const transition = {
     network: 'mainnet',
-    body: 'Candidate. Target epoch 24. L1 does not encode an offense reason.',
+    body: 'Event: Quorum reached for a 2,000 AZTEC slash\nEpoch: 24',
     targets: [SEQUENCER],
     data: { sequencer: SEQUENCER },
   };
   assert.equal(
     formatNotificationBody(transition),
-    'Sequencer: 0x1111…1111\n' + transition.body,
+    `Sequencer: ${SEQUENCER}\n${transition.body}`,
   );
   assert.deepEqual(dashtecReferenceLines(transition), [
     `Dashtec: https://dashtec.xyz/sequencers/${SEQUENCER}`,
@@ -36,8 +36,6 @@ test('case transition references use only its exact L1 facts', () => {
       payloadAddress,
     },
   }), [
-    `Etherscan transaction: https://sepolia.etherscan.io/tx/${transactionHash}`,
-    'Etherscan block: https://sepolia.etherscan.io/block/42',
-    `Etherscan candidate payload: https://sepolia.etherscan.io/address/${payloadAddress}`,
+    `Transaction: https://sepolia.etherscan.io/tx/${transactionHash}`,
   ]);
 });

docs/notifications.md

@@ -12,6 +12,10 @@ should be able to answer, without decoding contract data:
 An alert links to the exact case whose transition triggered it, not just the
 PINGME landing page.
 
+The heading keeps the compact `sequencer · case status` form. The body states
+the event, full sequencer address, relevant slot, epoch or round, UTC
+observation time, and reason provenance without repeating explanatory prose.
+
 ## Claims allowed at each stage
 
 | Stage | What the alert may claim |
@@ -35,29 +39,32 @@ action” and “predicted payload address.”
 L1 votes contain no offense type. Alerts may attach a reason only as separately
 labelled node evidence matched by address and exact target epoch or slot:
 
-> Candidate 2,000 AZTEC slash becomes executable in 2d 4h. This node observed
-> inactivity in target epoch 123.
+> Event: Quorum reached for a 2,000 AZTEC slash
+>
+> Epoch: 123
+>
+> Reason: Inactivity (node evidence)
 
 They must not say:
 
 > L1 confirmed a 2,000 AZTEC inactivity slash.
 
 If several local offenses match the same L1 action, list them rather than
-choosing one. If no evidence matches, say “reason unknown on L1.” An approximate
-timestamp match is insufficient.
+choosing one. If no evidence matches, say `Reason: Not encoded on L1`. An
+approximate timestamp match is insufficient.
 
 ## Required context
 
 Every alert includes:
 
 - watched sequencer address;
-- case stage and previous stage;
-- exact slot, epoch, target epoch, or slashing round as applicable;
-- source (`this Aztec node`, `Sentinel`, or `Ethereum L1`);
-- source observation time; current freshness is shown when the case opens;
+- current case status in the heading;
+- exact slot, epoch, or slashing round as applicable;
+- UTC observation time;
+- reason and its node-evidence provenance, or that no reason is encoded on L1;
 - actual AZTEC amount or candidate AZTEC amount, explicitly distinguished;
 - the next transition and countdown, when deterministic; and
-- the exact slashveto.me case URL.
+- for Telegram, the exact slashveto.me case URL.
 
 Stage-specific evidence is:
 
@@ -70,9 +77,9 @@ Stage-specific evidence is:
 | Execution / slash | transaction, round, deployed payload, requested action, canonical `Slashed` amount, and post-slash/ejection state when known |
 | Reorg / correction | orphaned block or transaction and the case state that replaced it |
 
-Telegram may add Dashtec links for affected sequencers and Etherscan links for
-the exact network transaction, block, or predicted/deployed address. Web Push
-opens the same exact case.
+Telegram includes the exact case link, a Dashtec sequencer link, and an
+Etherscan transaction link when a transaction hash exists. Web Push contains no
+links in its copy and opens the exact case when selected.
 
 ## Alert transitions and noise control
 
@@ -81,7 +88,8 @@ Alert on meaningful path changes, not every poll:
 - first missed duty in an epoch;
 - newly qualifying inactive epoch or changed streak progress;
 - offense registration or safe withdrawal;
-- first L1 mention and relevant vote/penalty threshold crossings;
+- first L1 vote and slash quorum; intermediate ballot counts update the case
+  without sending alerts;
 - candidate addition, removal, amount change, or address change;
 - round close, execution start, veto, materially changed pause protection, or
   expiry;

shared/protocol/cases.test.ts

@@ -231,6 +231,121 @@ describe('case projection', () => {
             severity: 'warning',
         });
     });
+
+    it('notifies on the first L1 vote and quorum, not each ballot increment', () => {
+        const offense = {
+            ...observation('offense', 'node_offense', {
+                status: 'active',
+                offenseTypeName: 'inactivity',
+                amount: '2000000000000000000000',
+                expectedRound: '12',
+            }),
+            provenance: {
+                observedAt: '2026-07-29T11:00:00.000Z',
+                canonical: true,
+            },
+        };
+        const firstVote = projectCases([
+            offense,
+            observation('vote-1', 'l1_round', {
+                round: '12',
+                status: 'below-quorum',
+                support: 1,
+                quorum: 65,
+                amount: null,
+            }, 'ethereum_l1'),
+        ], protocol())[0];
+        const secondVote = projectCases([
+            offense,
+            observation('vote-2', 'l1_round', {
+                round: '12',
+                status: 'below-quorum',
+                support: 2,
+                quorum: 65,
+                amount: null,
+            }, 'ethereum_l1'),
+        ], protocol())[0];
+        const quorum = projectCases([
+            offense,
+            observation('quorum', 'l1_round', {
+                round: '12',
+                status: 'quorum-reached',
+                support: 65,
+                quorum: 65,
+                amount: '2000000000000000000000',
+                payloadAddress: '0x3333333333333333333333333333333333333333',
+            }, 'ethereum_l1'),
+        ], protocol())[0];
+
+        expect(transitionFor(null, firstVote)).toMatchObject({
+            title: '0x1111…1111 · L1 mention',
+            body: [
+                'Event: First L1 slash vote recorded',
+                'Epoch: 10',
+                'Round: 12',
+                'Time: 2026-07-29 12:00:06 UTC',
+                'Reason: Inactivity (node evidence)',
+            ].join('\n'),
+        });
+        expect(transitionFor(firstVote, secondVote)).toBeNull();
+        expect(transitionFor(firstVote, quorum)).toMatchObject({
+            title: '0x1111…1111 · Candidate',
+            body: [
+                'Event: Quorum reached for a 2,000 AZTEC slash',
+                'Epoch: 10',
+                'Round: 12',
+                'Time: 2026-07-29 12:00:06 UTC',
+                'Reason: Inactivity (node evidence)',
+                'Next: Voting closes',
+            ].join('\n'),
+        });
+    });
+
+    it('includes the relevant slot, epoch, and observation time', () => {
+        const duty = projectCases([{
+            ...observation('duty', 'duty_miss', {
+                epoch: 10,
+                slot: '9001',
+                status: 'attestation-missed',
+            }),
+            slot: '9001',
+        }], protocol())[0];
+
+        expect(transitionFor(null, duty)).toMatchObject({
+            title: '0x1111…1111 · Duty miss',
+            body: [
+                'Event: Duty missed',
+                'Epoch: 10',
+                'Slot: 9001',
+                'Time: 2026-07-29 12:00:04 UTC',
+                'Reason: Inactivity (node evidence)',
+            ].join('\n'),
+        });
+    });
+
+    it('names other offense types without repeating them', () => {
+        const offense = projectCases([{
+            ...observation('duplicate', 'node_offense', {
+                status: 'active',
+                offenseTypeName: 'duplicate_proposal',
+                amount: '5000000000000000000000',
+                expectedRound: '12',
+            }),
+            slot: '9001',
+        }], protocol())[0];
+
+        expect(transitionFor(null, offense)).toMatchObject({
+            title: '0x1111…1111 · Awaiting L1 round',
+            body: [
+                'Event: Offense recorded by this node',
+                'Epoch: 10',
+                'Slot: 9001',
+                'Round: 12',
+                'Time: 2026-07-29 12:00:09 UTC',
+                'Reason: Duplicate Proposal (node evidence)',
+            ].join('\n'),
+        });
+    });
 });
 
 function observation(