refactor(network): split dkgGossipMsgId into raw + libp2p adapter (Codex PR #501 round 5)

Codex review feedback flagged that the round-4 signature accepted a
libp2p `Message` directly, which made the "cross-backend dedup" framing
aspirational rather than concrete. A future iroh-gossip backend would
need to either duplicate the framing logic or shoehorn its messages
through the libp2p shape.

Split:
- `dkgGossipMsgIdRaw({ topic, data, publisherIdBytes, sequenceNumber })`
  is the backend-agnostic primitive; framing + sha256 lives here once.
- `dkgGossipMsgId(msg: libp2p.Message)` is now a thin adapter that
  unwraps libp2p shape into raw inputs and enforces signed-only.

Tests:
- Adds a FIXED VECTOR test that pins the exact 32-byte sha256 output
  for a known input, addressing Codex feedback that the existing
  `expected()` helper mirrors production logic and would mask
  encoding drift if both were mutated together.
- Adds direct tests for `dkgGossipMsgIdRaw` (length-framing,
  seqno-in-hash, 32-byte digest).
- Adds an adapter↔raw equivalence test proving the libp2p adapter
  delegates to the primitive on every signed message.

Marks the public API `@experimental` in JSDoc — the function is
intentionally unwired in v1 (see RFC 07 §5.4 + Phase 5 deferred
cutover) and downstream consumers shouldn't rely on the in-process
mesh routing through it yet.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: 2 people

packages/core/src/index.ts

@@ -22,6 +22,8 @@ export {
   type ResolveOpts,
   PeerResolver,
   dkgGossipMsgId,
+  dkgGossipMsgIdRaw,
+  type DkgGossipMsgIdInput,
   DkgGossipUnsignedMessageError,
 } from './network/index.js';
 export {

packages/core/src/network/gossip-msg-id.ts

@@ -6,12 +6,12 @@
  * libp2p-gossipsub without protocol-level cooperation. The exact
  * encoding (after Codex review feedback on PR #501):
  *
- *     msgId(topic, payload, fromIdentityId, seqno) :=
+ *     msgId(topic, payload, publisherId, sequenceNumber) :=
  *         sha256(
  *           u32_be(len(topic))           ‖ topic
  *           ‖ u32_be(len(payload))        ‖ payload
- *           ‖ u32_be(len(fromIdentityId)) ‖ fromIdentityId
- *           ‖ u64_be(seqno)
+ *           ‖ u32_be(len(publisherId))    ‖ publisherId
+ *           ‖ u64_be(sequenceNumber)
  *         )
  *
  * Why length framing
@@ -23,8 +23,8 @@
  * the encoding injective — distinct tuples always hash to distinct
  * inputs.
  *
- * Why include seqno
- * -----------------
+ * Why include sequenceNumber
+ * --------------------------
  * The whole point of gossipsub's msgId is dedup-with-retries: a peer
  * publishing the same payload twice (e.g. resending after a network
  * blip) must produce TWO distinct msgIds, otherwise the second
@@ -33,36 +33,53 @@
  * sequence number in the hash preserves that semantic without
  * forfeiting cross-backend determinism: every backend with a notion
  * of per-publisher monotonic ordering (gossipsub seqno, iroh-gossip
- * sequence, etc.) maps the same (topic, payload, from, seq) tuple
- * to the same hash.
+ * sequence, etc.) maps the same (topic, payload, publisher, seq)
+ * tuple to the same hash.
  *
  * Why throw on unsigned
  * ---------------------
- * Codex review feedback on PR #501 round 4: with `type: 'unsigned'`
- * the message has no publisher identity (no `from`) and no seqno.
- * The earlier draft fell back to `fromBytes = []` and `seqno = 0n`,
- * which means two different publishers sending the same payload on
- * the same topic produce the SAME msgId — one publish gets falsely
- * deduplicated. (The upstream default for unsigned —
- * `sha256(data)` — has the same property, but a public function
- * shouldn't replicate that pitfall in a freshly-shipped contract.)
+ * Codex review feedback on PR #501 round 4: with no `from` and no
+ * seqno, two different publishers sending the same payload would
+ * produce the SAME msgId — false dedup. The upstream default for
+ * unsigned (`sha256(data)`) has the same property, but a freshly-
+ * shipped public function shouldn't replicate that pitfall. V10
+ * configures gossipsub StrictSign by default so unsigned messages
+ * don't appear in the wild today; throwing makes the unsupported
+ * case loud and catches accidental misuse via the public re-export.
  *
- * V10 configures gossipsub with the StrictSign default, so unsigned
- * messages don't appear in the wild today. Throwing here makes the
- * "unsigned not supported in this msgId scheme" stance explicit:
+ * Why split into raw + adapter
+ * ----------------------------
+ * Codex review feedback on PR #501 round 5: the round-4 signature
+ * accepted a libp2p `Message` directly, which made the "cross-
+ * backend dedup" framing aspirational rather than concrete. A
+ * future iroh-gossip backend would have its own message type with
+ * its own ways of representing publisher and sequence — at which
+ * point either we'd duplicate the framing logic (drift risk) or
+ * have to refactor every consumer to convert through the libp2p
+ * shape.
  *
- *   - any code path that tries to publish an unsigned message
- *     fails loudly (easy to debug),
- *   - external consumers of the exported function can't accidentally
- *     hit the false-dedup case,
- *   - a future PR that wants to support unsigned has to deliberately
- *     extend the scheme with a per-message identity (nonce / hash
- *     prefix / etc.), pinned by tests.
+ * Round-5 split:
+ *   - `dkgGossipMsgIdRaw({ topic, data, publisherIdBytes,
+ *     sequenceNumber })` — backend-agnostic primitive over canonical
+ *     value types. Every backend's adapter normalises into this and
+ *     the framing/hash lives here once.
+ *   - `dkgGossipMsgId(msg: libp2p.Message)` — thin libp2p adapter:
+ *     unwraps `from.toMultihash().bytes` and `sequenceNumber`,
+ *     enforces signed-only (because libp2p's unsigned variant has
+ *     no publisher identity to feed in).
+ * A future `dkgGossipMsgIdIroh(msg: iroh.GossipMessage)` adapter
+ * goes alongside; the framing lives once in `dkgGossipMsgIdRaw`.
  *
- * v1 ships only `LibP2PGossipBackend`, so this function only changes
- * which sha256 inputs gossipsub feeds itself; nothing observable on
- * the wire. Locking the constant in NOW (rather than after a second
- * backend ships) avoids a future synchronised mid-flight upgrade.
+ * Wiring
+ * ------
+ * v1 ships only the function and tests. The actual `msgIdFn` wiring
+ * in `node.ts` is intentionally deferred — see RFC 07 §5.4 + Phase 5
+ * for the rolling-upgrade rationale and the coordinated-cutover plan.
+ *
+ * @experimental Public API but intentionally unwired. The encoding
+ * is pinned by `gossip-msg-id.test.ts`; downstream consumers may
+ * import for inspection / future-backend adapters but should not
+ * rely on the in-process libp2p mesh routing through it yet.
  */
 import { sha256 } from '@noble/hashes/sha2.js';
 import type { Message } from '@libp2p/gossipsub';
@@ -92,15 +109,38 @@ export class DkgGossipUnsignedMessageError extends Error {
   }
 }
 
-export function dkgGossipMsgId(msg: Message): Uint8Array {
-  if (msg.type !== 'signed') {
-    throw new DkgGossipUnsignedMessageError();
-  }
+/**
+ * Inputs for the backend-agnostic msgId primitive.
+ *
+ * - `topic` — gossip topic string (UTF-8 encoded inside the function).
+ * - `data` — raw payload bytes.
+ * - `publisherIdBytes` — canonical bytes identifying the publisher.
+ *   For libp2p, this is `peerId.toMultihash().bytes`. For other
+ *   backends, the equivalent canonical identity bytes.
+ * - `sequenceNumber` — per-publisher monotonic sequence (gossipsub
+ *   seqno, iroh sequence, etc.).
+ *
+ * @experimental
+ */
+export interface DkgGossipMsgIdInput {
+  topic: string;
+  data: Uint8Array;
+  publisherIdBytes: Uint8Array;
+  sequenceNumber: bigint;
+}
 
-  const topicBytes = new TextEncoder().encode(msg.topic);
-  const data = msg.data;
-  const fromBytes = msg.from.toMultihash().bytes;
-  const seqno = msg.sequenceNumber;
+/**
+ * Backend-agnostic msgId primitive. Every gossip backend adapter
+ * normalises into `DkgGossipMsgIdInput` and the framing + hash
+ * lives here once.
+ *
+ * @experimental
+ */
+export function dkgGossipMsgIdRaw(input: DkgGossipMsgIdInput): Uint8Array {
+  const topicBytes = new TextEncoder().encode(input.topic);
+  const data = input.data;
+  const fromBytes = input.publisherIdBytes;
+  const seqno = input.sequenceNumber;
 
   const total =
     4 + topicBytes.length +
@@ -123,3 +163,24 @@ export function dkgGossipMsgId(msg: Message): Uint8Array {
 
   return sha256(buf);
 }
+
+/**
+ * libp2p-gossipsub adapter. Suitable as the `msgIdFn` parameter of
+ * `gossipsub({ ... })` when (eventually) wired in `node.ts`.
+ *
+ * Throws `DkgGossipUnsignedMessageError` if `msg.type !== 'signed'`.
+ *
+ * @experimental Public but intentionally unwired in v1; see file
+ * doc-comment + RFC 07 §5.4 for the rollout plan.
+ */
+export function dkgGossipMsgId(msg: Message): Uint8Array {
+  if (msg.type !== 'signed') {
+    throw new DkgGossipUnsignedMessageError();
+  }
+  return dkgGossipMsgIdRaw({
+    topic: msg.topic,
+    data: msg.data,
+    publisherIdBytes: msg.from.toMultihash().bytes,
+    sequenceNumber: msg.sequenceNumber,
+  });
+}

packages/core/src/network/index.ts

@@ -19,4 +19,9 @@ export type {
 } from './peer-resolver.js';
 export { PeerResolver } from './peer-resolver.js';
 
-export { dkgGossipMsgId, DkgGossipUnsignedMessageError } from './gossip-msg-id.js';
+export type { DkgGossipMsgIdInput } from './gossip-msg-id.js';
+export {
+  dkgGossipMsgId,
+  dkgGossipMsgIdRaw,
+  DkgGossipUnsignedMessageError,
+} from './gossip-msg-id.js';

packages/core/test/gossip-msg-id.test.ts

@@ -2,6 +2,7 @@ import { describe, it, expect } from 'vitest';
 import { sha256 } from '@noble/hashes/sha2.js';
 import {
   dkgGossipMsgId,
+  dkgGossipMsgIdRaw,
   DkgGossipUnsignedMessageError,
 } from '../src/network/gossip-msg-id.js';
 
@@ -173,4 +174,117 @@ describe('dkgGossipMsgId (RFC 07 §5.4)', () => {
     });
     expect(a).toEqual(b);
   });
+
+  // Codex review feedback on PR #501 round 5: the encoding can drift if
+  // both production and test are mutated together via `expected()`. This
+  // pins the exact 32-byte SHA256 output for a known input so any
+  // change to the framing/hash bytes is caught even if the helper is
+  // wrong in the same way the prod code is.
+  //
+  // Vector:
+  //   topic = 'dkg/test/1.0.0'
+  //   data  = [0x01, 0x02, 0x03, 0x04]
+  //   from  = [0x12, 0x34, 0x56]
+  //   seq   = 7n
+  // Pre-hash:
+  //   0000000e 646b672f746573742f312e302e30 00000004 01020304
+  //                                                      00000003 123456 0000000000000007
+  // SHA256:
+  //   17dc679d5ac2b669fc946ead91f08728a2dc33f8799f3b3bf3df04384959caa8
+  it('FIXED VECTOR: pinned 32-byte SHA256 for a known input (libp2p adapter)', () => {
+    const knownFrom = {
+      toMultihash: () => ({ bytes: new Uint8Array([0x12, 0x34, 0x56]) }),
+    } as unknown as Parameters<typeof dkgGossipMsgId>[0] extends infer M
+      ? M extends { from: infer P } ? P : never : never;
+    const id = dkgGossipMsgId({
+      type: 'signed',
+      topic: 'dkg/test/1.0.0',
+      data: new Uint8Array([0x01, 0x02, 0x03, 0x04]),
+      from: knownFrom,
+      sequenceNumber: 7n,
+      signature: new Uint8Array(),
+      key: {} as never,
+    });
+    const hex = Array.from(id, (b) => b.toString(16).padStart(2, '0')).join('');
+    expect(hex).toBe(
+      '17dc679d5ac2b669fc946ead91f08728a2dc33f8799f3b3bf3df04384959caa8',
+    );
+  });
+});
+
+// Codex review feedback on PR #501 round 5: the libp2p-shaped function
+// alone makes the "cross-backend dedup" framing aspirational. Pinning
+// the backend-agnostic primitive separately, plus asserting the libp2p
+// adapter delegates to it, locks in the contract: any future backend
+// adapter (iroh-gossip, etc.) just needs to feed canonical bytes into
+// `dkgGossipMsgIdRaw` and gets the same dedup behaviour.
+describe('dkgGossipMsgIdRaw (RFC 07 §5.4 — backend-agnostic primitive)', () => {
+  it('FIXED VECTOR: pinned 32-byte SHA256 (matches libp2p adapter vector)', () => {
+    const id = dkgGossipMsgIdRaw({
+      topic: 'dkg/test/1.0.0',
+      data: new Uint8Array([0x01, 0x02, 0x03, 0x04]),
+      publisherIdBytes: new Uint8Array([0x12, 0x34, 0x56]),
+      sequenceNumber: 7n,
+    });
+    const hex = Array.from(id, (b) => b.toString(16).padStart(2, '0')).join('');
+    expect(hex).toBe(
+      '17dc679d5ac2b669fc946ead91f08728a2dc33f8799f3b3bf3df04384959caa8',
+    );
+  });
+
+  it('libp2p adapter agrees with raw primitive on every signed message', () => {
+    const fromBytes = new Uint8Array([0xAA, 0xBB, 0xCC]);
+    const peerId = {
+      toMultihash: () => ({ bytes: fromBytes }),
+    } as unknown as Parameters<typeof dkgGossipMsgId>[0] extends infer M
+      ? M extends { from: infer P } ? P : never : never;
+    const adapterId = dkgGossipMsgId({
+      type: 'signed',
+      topic: 'cg/topic-x/1.0.0',
+      data: new Uint8Array([9, 9, 9]),
+      from: peerId,
+      sequenceNumber: 1234n,
+      signature: new Uint8Array(),
+      key: {} as never,
+    });
+    const rawId = dkgGossipMsgIdRaw({
+      topic: 'cg/topic-x/1.0.0',
+      data: new Uint8Array([9, 9, 9]),
+      publisherIdBytes: fromBytes,
+      sequenceNumber: 1234n,
+    });
+    expect(adapterId).toEqual(rawId);
+  });
+
+  it('length-framing collision check applies at the raw level too', () => {
+    const a = dkgGossipMsgIdRaw({
+      topic: 'ab', data: new TextEncoder().encode('c'),
+      publisherIdBytes: new Uint8Array([1]), sequenceNumber: 0n,
+    });
+    const b = dkgGossipMsgIdRaw({
+      topic: 'a', data: new TextEncoder().encode('bc'),
+      publisherIdBytes: new Uint8Array([1]), sequenceNumber: 0n,
+    });
+    expect(a).not.toEqual(b);
+  });
+
+  it('seqno enters the hash at the raw level too', () => {
+    const a = dkgGossipMsgIdRaw({
+      topic: 't', data: new Uint8Array([1]),
+      publisherIdBytes: new Uint8Array([2]), sequenceNumber: 1n,
+    });
+    const b = dkgGossipMsgIdRaw({
+      topic: 't', data: new Uint8Array([1]),
+      publisherIdBytes: new Uint8Array([2]), sequenceNumber: 2n,
+    });
+    expect(a).not.toEqual(b);
+  });
+
+  it('returns a 32-byte SHA256 digest', () => {
+    const id = dkgGossipMsgIdRaw({
+      topic: 't', data: new Uint8Array(),
+      publisherIdBytes: new Uint8Array(), sequenceNumber: 0n,
+    });
+    expect(id.length).toBe(32);
+  });
 });