@bitsocial/pubsub-voting 0.0.6

package/dist/transport/helia.d.ts

@@ -0,0 +1,55 @@
+import type { CID } from "multiformats/cid";
+import type { PeerId } from "@libp2p/interface";
+import type { BlockstoreLike, FetchServiceLike, HeliaInstance, PubsubService } from "./types.js";
+/**
+ * The host's raw blockstore surface. `get` may return EITHER a `Promise<Uint8Array>` (a plain
+ * `interface-blockstore`) OR an async generator yielding the block's bytes — Helia's real
+ * `BlockStorage` implements the streaming `Blocks` interface and yields the block (one chunk in
+ * practice), not a bare promise. The library works against the simpler {@link BlockstoreLike}
+ * contract, so {@link adaptBlockstore} normalises either shape at this one boundary.
+ */
+interface RawBlockstore {
+    get(cid: CID, options?: {
+        signal?: AbortSignal;
+    }): AsyncIterable<Uint8Array> | Promise<Uint8Array>;
+    put(cid: CID, block: Uint8Array, options?: {
+        signal?: AbortSignal;
+    }): Promise<CID>;
+    has(cid: CID, options?: {
+        signal?: AbortSignal;
+    }): Promise<boolean>;
+    /** Helia's `Blocks.createSession` (a provider-scoped session blockstore); plain blockstores lack it. */
+    createSession?(root: CID, options?: {
+        providers?: PeerId[];
+        maxProviders?: number;
+    }): RawBlockSession;
+}
+/** The raw session surface (Helia's `SessionBlockstore`); `get` streams like the parent store's. */
+interface RawBlockSession {
+    get(cid: CID, options?: {
+        signal?: AbortSignal;
+    }): AsyncIterable<Uint8Array> | Promise<Uint8Array>;
+    addPeer(peer: PeerId): Promise<void> | void;
+    close(): void;
+}
+/**
+ * Adapt a raw blockstore to the library's {@link BlockstoreLike} contract: normalise `get` to a
+ * single `Uint8Array`. Helia's `BlockStorage.get` yields the block over an async generator (a
+ * single chunk for the sub-1 MiB blocks this library stores; chunks are concatenated defensively),
+ * while a plain blockstore returns a promise — both are handled. `put`/`has` already return
+ * promises, so they pass through. Exported so the transport (and the integration harness) adapt the
+ * injected node the same way.
+ */
+export declare function adaptBlockstore(raw: RawBlockstore): BlockstoreLike;
+/**
+ * Resolve and validate the gossipsub service, blockstore, and fetch service on an injected
+ * Helia node, throwing {@link MissingPubsubError} / {@link MissingBlockstoreError} /
+ * {@link MissingFetchError} if any is absent or malformed. Returns the narrowed handles so
+ * callers do not re-check.
+ */
+export declare function requireHeliaServices(helia: HeliaInstance): {
+    pubsub: PubsubService;
+    blockstore: BlockstoreLike;
+    fetch: FetchServiceLike;
+};
+export {};

package/dist/transport/helia.js

@@ -0,0 +1,114 @@
+import { MissingBlockstoreError, MissingFetchError, MissingPubsubError } from "../errors.js";
+/**
+ * The helia/libp2p-touching glue. Like the rest of `transport/`, this is the only place
+ * that reaches into the host node; the core never imports it.
+ *
+ * `requireHeliaServices` is the one piece live today: the host injects its running Helia
+ * node directly (no adapter), and we cannot trust the type — `libp2p.services.pubsub` is
+ * `unknown`, a plain Helia node has none, and a malformed object may lack a blockstore —
+ * so we validate both at construction and fail fast (`MissingPubsubError` /
+ * `MissingBlockstoreError`) instead of letting a later publish/subscribe/fetch throw
+ * obscurely.
+ *
+ * Note "bitswap" is not separately checkable: it is a block broker wired *beneath*
+ * `blockstore`, not a property of the Helia node, so validating the blockstore (the
+ * surface bitswap retrieves through) is the closest honest guarantee.
+ */
+/** Does `value` look like a pubsub service we can drive (the methods we depend on)? */
+function isPubsubService(value) {
+    if (value === null || typeof value !== "object")
+        return false;
+    const candidate = value;
+    return (typeof candidate.publish === "function" &&
+        typeof candidate.subscribe === "function" &&
+        typeof candidate.unsubscribe === "function");
+}
+/** Does `value` look like a blockstore we can fetch/store blocks through? */
+function isRawBlockstore(value) {
+    if (value === null || typeof value !== "object")
+        return false;
+    const candidate = value;
+    return (typeof candidate.get === "function" &&
+        typeof candidate.put === "function" &&
+        typeof candidate.has === "function");
+}
+function isAsyncIterable(value) {
+    return value !== null && typeof value === "object" && Symbol.asyncIterator in value;
+}
+/**
+ * Adapt a raw blockstore to the library's {@link BlockstoreLike} contract: normalise `get` to a
+ * single `Uint8Array`. Helia's `BlockStorage.get` yields the block over an async generator (a
+ * single chunk for the sub-1 MiB blocks this library stores; chunks are concatenated defensively),
+ * while a plain blockstore returns a promise — both are handled. `put`/`has` already return
+ * promises, so they pass through. Exported so the transport (and the integration harness) adapt the
+ * injected node the same way.
+ */
+export function adaptBlockstore(raw) {
+    const adapted = {
+        get: (cid, options) => readBlock(raw.get(cid, options), cid),
+        put: (cid, block) => raw.put(cid, block),
+        has: (cid) => raw.has(cid)
+    };
+    // Feature-detected, not assumed: only Helia's `Blocks` makes sessions; the unit tests' plain
+    // blockstores don't, and their absence here is what tells the chase to broadcast instead.
+    // Dispatched dynamically (like `get`/`put`/`has` above) so a wrapper installed on the raw
+    // store after adaptation — e.g. the benchmark's timing instrumentation — is still honoured.
+    if (typeof raw.createSession === "function") {
+        adapted.createSession = (root, options) => {
+            const session = raw.createSession(root, options);
+            return {
+                get: (cid, opts) => readBlock(session.get(cid, opts), cid),
+                addPeer: (peer) => session.addPeer(peer),
+                close: () => session.close()
+            };
+        };
+    }
+    return adapted;
+}
+/** Normalise one raw `get` result (promise or stream — see {@link RawBlockstore}) to the block's bytes. */
+async function readBlock(result, cid) {
+    if (!isAsyncIterable(result))
+        return result; // a plain Promise<Uint8Array> blockstore
+    const chunks = [];
+    for await (const chunk of result)
+        chunks.push(chunk);
+    if (chunks.length === 1)
+        return chunks[0];
+    if (chunks.length === 0)
+        throw new Error(`block ${cid.toString()} yielded no bytes`);
+    const total = chunks.reduce((sum, chunk) => sum + chunk.length, 0);
+    const out = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        out.set(chunk, offset);
+        offset += chunk.length;
+    }
+    return out;
+}
+/** Does `value` look like a libp2p fetch service (the request + responder registration)? */
+function isFetchService(value) {
+    if (value === null || typeof value !== "object")
+        return false;
+    const candidate = value;
+    return (typeof candidate.fetch === "function" &&
+        typeof candidate.registerLookupFunction === "function" &&
+        typeof candidate.unregisterLookupFunction === "function");
+}
+/**
+ * Resolve and validate the gossipsub service, blockstore, and fetch service on an injected
+ * Helia node, throwing {@link MissingPubsubError} / {@link MissingBlockstoreError} /
+ * {@link MissingFetchError} if any is absent or malformed. Returns the narrowed handles so
+ * callers do not re-check.
+ */
+export function requireHeliaServices(helia) {
+    const pubsub = helia.libp2p?.services?.pubsub;
+    if (!isPubsubService(pubsub))
+        throw new MissingPubsubError();
+    const blockstore = helia.blockstore;
+    if (!isRawBlockstore(blockstore))
+        throw new MissingBlockstoreError();
+    const fetch = helia.libp2p?.services?.fetch;
+    if (!isFetchService(fetch))
+        throw new MissingFetchError();
+    return { pubsub, blockstore: adaptBlockstore(blockstore), fetch };
+}

package/dist/transport/integration/harness.d.ts

@@ -0,0 +1,65 @@
+import { type Libp2p } from "libp2p";
+import { type Helia } from "helia";
+import type { VotesBundle } from "../../schema/votes.js";
+import type { BundleVerdict } from "../../verify/types.js";
+import type { VoteCrdt } from "../../crdt/types.js";
+import { type VerdictCache } from "../../verify/cache.js";
+import { type RootChaser } from "../chase.js";
+import type { PubsubService, VoteTransport } from "../types.js";
+import { type RootRecord } from "../messages.js";
+/** The gossipsub peer-score methods used for assertions — on the concrete class, not the interface. */
+interface ScoreOps {
+    getScore(peer: string): number;
+    getMeshPeers(topic: string): string[];
+}
+export interface VoteNodeOptions {
+    /** Per-message validation deadline (ms). Small values let a test force the deadline path. */
+    timeoutMs?: number;
+}
+export interface VoteNode {
+    readonly helia: Helia;
+    readonly libp2p: Libp2p;
+    /** The gossipsub service, plus the score/mesh introspection the assertions read. */
+    readonly pubsub: PubsubService & ScoreOps;
+    readonly peerId: string;
+    readonly topic: string;
+    readonly crdt: VoteCrdt;
+    readonly cache: VerdictCache;
+    readonly chaser: RootChaser;
+    readonly transport: VoteTransport;
+    /** Bundle-kind messages this node ACCEPTED (delivered post-validation ⇒ it would forward them). */
+    readonly acceptedBundles: Uint8Array[];
+    /** Root records this node heard through the gate. */
+    readonly heardRoots: RootRecord[];
+    /** Chase sessions this node opened: which root, seeded with which advertisers (peer id strings). */
+    readonly openedSessions: Array<{
+        root: string;
+        providers: string[];
+    }>;
+    /** True once a heard root matched this node's own current root (heartbeat suppression signal). */
+    heardMatchingRoot(): boolean;
+    /** Replace the injected verifier (e.g. a rejecter, or a slow one, for a specific assertion). */
+    setVerifier(verify: (bundle: VotesBundle) => Promise<BundleVerdict>): void;
+    /** Encode this node's current winner-set to a checkpoint (blocks written to its blockstore). */
+    checkpointRootRecord(): Promise<RootRecord>;
+    /** Publish this node's own root record on the topic (a heartbeat). */
+    publishOwnRoot(): Promise<void>;
+    /** Seed a bundle straight into this node's state (store block + CRDT merge), no network. */
+    admitBundle(bundle: VotesBundle): Promise<void>;
+    stop(): Promise<void>;
+}
+/** Build one real node with the full forward-gate wired to real gossipsub. */
+export declare function makeVoteNode(topic: string, options?: VoteNodeOptions): Promise<VoteNode>;
+/**
+ * Dial `b` from `a` and wait until gossipsub has grafted them into each other's mesh for
+ * `topic` — after which a publish is reliably delivered (so negative assertions like "not
+ * forwarded" are meaningful, not just races against an unformed mesh).
+ */
+export declare function connectNodes(a: VoteNode, b: VoteNode): Promise<void>;
+/** Poll `predicate` until it is truthy or `timeoutMs` elapses (then throw with `description`). */
+export declare function waitFor(predicate: () => boolean | Promise<boolean>, timeoutMs?: number, description?: string): Promise<void>;
+/** Resolve after `ms`; used only to space out polls, never as an observation substitute. */
+export declare function delay(ms: number): Promise<void>;
+/** A well-formed one-vote bundle. The signature is a well-formed 65 bytes; validity is the verifier's job. */
+export declare function sampleBundle(address: string, publicKey: string, blockNumber?: number): VotesBundle;
+export {};

package/dist/transport/integration/harness.js

@@ -0,0 +1,278 @@
+import pLimit from "p-limit";
+import { createLibp2p } from "libp2p";
+import { tcp } from "@libp2p/tcp";
+import { noise } from "@chainsafe/libp2p-noise";
+import { yamux } from "@chainsafe/libp2p-yamux";
+import { identify } from "@libp2p/identify";
+import { gossipsub } from "@libp2p/gossipsub";
+import { fetch as fetchService } from "@libp2p/fetch";
+import { createHelia } from "helia";
+import { makeBlockstoreBundleStore } from "../bundle-store.js";
+import { adaptBlockstore } from "../helia.js";
+import { makeVoteCrdt } from "../../crdt/crdt.js";
+import { makeBucketMath } from "../../chain/bucket.js";
+import { makeVerdictCache } from "../../verify/cache.js";
+import { encodeBundle, decodeBundle, bundleCidForBytes } from "../../crdt/codec.js";
+import { encodeCheckpoint } from "../../checkpoint/codec.js";
+import { makeGossipGate } from "../gossip-validator.js";
+import { makeRootChaser, toChaseSession } from "../chase.js";
+import { makeVoteTransport } from "../transport.js";
+import { decodeVoteMessage, maxBundleMessageBytes, MAX_ROOT_MESSAGE_BYTES, ROOT_RECORD_VERSION } from "../messages.js";
+/**
+ * Test harness for the two-node gossipsub integration test. It stands up ONE real libp2p +
+ * Helia node carrying `@libp2p/gossipsub` (>= 15.0.23, the CVE-2026-46679 floor) and
+ * `@libp2p/fetch`, and wires the SAME forward-gate / chaser / transport the production client
+ * assembles in `src/client/voter.ts` `start()` — the only differences are test seams: an
+ * injectable verifier (so a test can force a reject or a slow verify) and a small `timeoutMs`.
+ * No production `src/` code is modified; this reuses `makeGossipGate` / `makeRootChaser` /
+ * `makeVoteTransport` verbatim.
+ *
+ * What only a real node can prove (and a fake pubsub cannot): gossipsub actually forwards an
+ * accepted message and drops a rejected one, peer scores move on a `reject`, a validation past
+ * the deadline yields `ignore` with no penalty, a converged pair stays quiet, and a divergent
+ * root pulls the checkpoint blocks over real bitswap.
+ */
+/** Every bundle in the test is dated to a small block; reads use bucket 0 (never expired). */
+const CURRENT_BUCKET = 0;
+const BLOCKS_PER_BUCKET = 43_200;
+const VOTE_EXPIRY_BUCKETS = 30;
+/** A permissive default verifier; individual tests swap it via {@link VoteNode.setVerifier}. */
+const okVerifier = () => ({ valid: true, ruleScore: 1n, resolvedNames: {} });
+/** Build one real node with the full forward-gate wired to real gossipsub. */
+export async function makeVoteNode(topic, options = {}) {
+    const timeoutMs = options.timeoutMs ?? 10_000;
+    const libp2p = await createLibp2p({
+        addresses: { listen: ["/ip4/127.0.0.1/tcp/0"] },
+        transports: [tcp()],
+        connectionEncrypters: [noise()],
+        streamMuxers: [yamux()],
+        services: {
+            identify: identify(),
+            fetch: fetchService(),
+            pubsub: gossipsub({
+                allowPublishToZeroTopicPeers: true,
+                heartbeatInterval: 300,
+                // Isolate the invalid-message penalty (P₄) as the only score signal so a reject is
+                // crisply observable and an `ignore` provably moves nothing. Positive/mesh weights
+                // are zeroed; IP-colocation is disabled because both nodes share 127.0.0.1.
+                scoreParams: {
+                    IPColocationFactorWeight: 0,
+                    appSpecificScore: () => 0,
+                    topics: {
+                        [topic]: {
+                            topicWeight: 1,
+                            timeInMeshWeight: 0,
+                            timeInMeshQuantum: 1_000,
+                            timeInMeshCap: 1,
+                            firstMessageDeliveriesWeight: 0,
+                            firstMessageDeliveriesDecay: 0.5,
+                            firstMessageDeliveriesCap: 100,
+                            meshMessageDeliveriesWeight: 0,
+                            meshMessageDeliveriesDecay: 0.5,
+                            meshMessageDeliveriesCap: 100,
+                            meshMessageDeliveriesThreshold: 1,
+                            meshMessageDeliveriesWindow: 10,
+                            meshMessageDeliveriesActivation: 5_000,
+                            meshFailurePenaltyWeight: 0,
+                            meshFailurePenaltyDecay: 0.5,
+                            // One invalid delivery ⇒ score −50: clearly negative, below the publish
+                            // threshold, but above the −80 graylist so the peer is not disconnected
+                            // mid-assertion.
+                            invalidMessageDeliveriesWeight: -50,
+                            invalidMessageDeliveriesDecay: 0.9
+                        }
+                    }
+                }
+            })
+        }
+    });
+    const helia = await createHelia({ libp2p });
+    const pubsub = libp2p.services.pubsub;
+    // Adapt Helia's async-generator `get` to the library's Promise-returning BlockstoreLike, the
+    // same bridge `requireHeliaServices` applies to an injected host node.
+    const blockstore = adaptBlockstore(helia.blockstore);
+    const store = makeBlockstoreBundleStore(blockstore);
+    const crdt = makeVoteCrdt({
+        store,
+        bucketMath: makeBucketMath(BLOCKS_PER_BUCKET),
+        voteExpiryBuckets: VOTE_EXPIRY_BUCKETS
+    });
+    const cache = makeVerdictCache();
+    // The injected verifier, swappable per test. The gate and the chaser share this reference.
+    // The chaser's offline stage runs the same swapped implementation, so a test that makes the
+    // verifier fail still sees the chase drop the bundle BEFORE admit (the two-node assertions
+    // pin admission, not which stage deferred — deferred checks are unit-tested in
+    // verify/background.test.ts).
+    let verifyImpl = async () => okVerifier();
+    const verifier = {
+        verify: (bundle) => verifyImpl(bundle),
+        verifyOffline: (bundle) => verifyImpl(bundle)
+    };
+    const admit = async ({ cid, bytes }) => {
+        await blockstore.put(cid, bytes);
+        await crdt.merge([cid]);
+    };
+    const acceptedBundles = [];
+    const heardRoots = [];
+    let matchedOwnRoot = false;
+    async function checkpointRootRecord() {
+        const winners = crdt.current(CURRENT_BUCKET);
+        const { root, blocks } = await encodeCheckpoint(winners);
+        for (const block of blocks)
+            await blockstore.put(block.cid, block.bytes);
+        return {
+            version: ROOT_RECORD_VERSION,
+            root,
+            count: winners.length,
+            sizeBytes: blocks.reduce((total, block) => total + block.bytes.length, 0)
+        };
+    }
+    const openedSessions = [];
+    const chaseLimit = pLimit(2);
+    const chaser = makeRootChaser({
+        getBlock: async (cid, signal) => {
+            try {
+                return await blockstore.get(cid, { signal });
+            }
+            catch {
+                return undefined;
+            }
+        },
+        // Mirror `PubsubVoter`'s seeded-session wiring (voter.ts `openSession`), with a recorder
+        // so the test can assert the chase really pulled through a session seeded with the
+        // advertiser — convergence alone cannot tell the session path from the broadcast fallback.
+        openSession: (root, providers) => {
+            const createSession = blockstore.createSession?.bind(blockstore);
+            if (createSession === undefined)
+                return undefined;
+            openedSessions.push({ root: root.toString(), providers: providers.map((p) => p.toString()) });
+            return toChaseSession(createSession(root, { providers, maxProviders: providers.length + 1 }));
+        },
+        verifyOffline: (bundle) => verifier.verifyOffline(bundle),
+        cache,
+        hasBundle: (cid) => store.has(cid),
+        admit,
+        // The harness runs the whole swapped pipeline in `verifyOffline` above, so nothing is
+        // left deferred; the background verifier has its own unit tests.
+        deferVerify: () => { },
+        limit: (fn) => chaseLimit(fn),
+        timeoutMs: 30_000
+    });
+    const gateLimit = pLimit(8);
+    const gate = makeGossipGate({
+        decodeMessage: decodeVoteMessage,
+        parseBundle: async (blockBytes) => ({
+            cid: await bundleCidForBytes(blockBytes),
+            bundle: decodeBundle(blockBytes)
+        }),
+        verifier,
+        cache,
+        admit,
+        limit: (fn) => gateLimit(fn),
+        allowBundlePeer: () => true,
+        allowRootPeer: () => true,
+        onAccept: (_cid, _bundle, _from) => { },
+        // Mirror `PubsubVoter.#handleRootRecord`: a matching root is the suppression signal (no
+        // chase, no echo); a divergent root is chased over directed bitswap, its session seeded
+        // with the sender — resolved from the live connections exactly as the voter does.
+        onRootRecord: (record, from) => {
+            heardRoots.push(record);
+            void (async () => {
+                const own = await checkpointRootRecord();
+                if (own.root.equals(record.root)) {
+                    matchedOwnRoot = true;
+                    return;
+                }
+                const advertiser = libp2p
+                    .getConnections()
+                    .find((connection) => connection.remotePeer.toString() === from)?.remotePeer;
+                chaser.chase(record.root, undefined, advertiser === undefined ? [] : [advertiser]);
+            })().catch(() => { });
+        },
+        maxBundleMessageBytes: maxBundleMessageBytes({ maxVotesPerAddress: 1 }),
+        maxRootMessageBytes: MAX_ROOT_MESSAGE_BYTES,
+        timeoutMs
+    });
+    const transport = makeVoteTransport({ pubsub, topic, gate });
+    await transport.start();
+    // Record every ACCEPTED message. gossipsub emits "message" only after the topic validator
+    // returns accept, so a delivered bundle is one this node forwarded — and a rejected/ignored
+    // one never appears here. This is the observable for the forward / no-forward assertions.
+    pubsub.addEventListener("message", (evt) => {
+        if (evt.detail.topic !== topic)
+            return;
+        try {
+            const message = decodeVoteMessage(evt.detail.data);
+            if (message.kind === "bundle")
+                acceptedBundles.push(message.bundle);
+        }
+        catch {
+            // A delivered message always decodes (it passed the gate); ignore anything else.
+        }
+    });
+    return {
+        helia,
+        libp2p,
+        pubsub,
+        peerId: libp2p.peerId.toString(),
+        topic,
+        crdt,
+        cache,
+        chaser,
+        transport,
+        acceptedBundles,
+        heardRoots,
+        openedSessions,
+        heardMatchingRoot: () => matchedOwnRoot,
+        setVerifier: (verify) => {
+            verifyImpl = verify;
+        },
+        checkpointRootRecord,
+        publishOwnRoot: async () => {
+            await transport.publishRootRecord(await checkpointRootRecord());
+        },
+        admitBundle: async (bundle) => {
+            const bytes = encodeBundle(bundle);
+            const cid = await bundleCidForBytes(bytes);
+            await blockstore.put(cid, bytes);
+            await crdt.merge([cid]);
+        },
+        stop: async () => {
+            await transport.stop();
+            await helia.stop();
+        }
+    };
+}
+/**
+ * Dial `b` from `a` and wait until gossipsub has grafted them into each other's mesh for
+ * `topic` — after which a publish is reliably delivered (so negative assertions like "not
+ * forwarded" are meaningful, not just races against an unformed mesh).
+ */
+export async function connectNodes(a, b) {
+    await a.libp2p.dial(b.libp2p.getMultiaddrs());
+    await waitFor(() => a.pubsub.getMeshPeers(a.topic).includes(b.peerId) && b.pubsub.getMeshPeers(b.topic).includes(a.peerId), 15_000, "gossipsub mesh to form between the two nodes");
+}
+/** Poll `predicate` until it is truthy or `timeoutMs` elapses (then throw with `description`). */
+export async function waitFor(predicate, timeoutMs = 15_000, description = "condition") {
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        if (await predicate())
+            return;
+        if (Date.now() > deadline)
+            throw new Error(`timed out after ${timeoutMs}ms waiting for ${description}`);
+        await delay(50);
+    }
+}
+/** Resolve after `ms`; used only to space out polls, never as an observation substitute. */
+export function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/** A well-formed one-vote bundle. The signature is a well-formed 65 bytes; validity is the verifier's job. */
+export function sampleBundle(address, publicKey, blockNumber = 10) {
+    return {
+        address,
+        votes: [{ community: { publicKey }, vote: 1 }],
+        blockNumber,
+        signature: { signature: `0x${"11".repeat(65)}`, type: "eip712" }
+    };
+}

package/dist/transport/messages.d.ts

@@ -0,0 +1,97 @@
+import { CID } from "multiformats/cid";
+import type { Criteria } from "../schema/criteria.js";
+/**
+ * The pubsub message payload: a two-kind discriminated union (see DESIGN.md "Transport").
+ *
+ *   - `bundle`: one wallet's own bundle as a **live delta** — the exact binary bundle-block
+ *     bytes (crdt/codec.ts) inlined, so the receiver validates straight from the message,
+ *     hashing the embedded bytes yields the bundle CID (the verdict-cache key), and the
+ *     blockstore put is byte-identical. No fetch toward the publisher exists on this path.
+ *   - `root`: the constant-size **root record** `{ version, root, count, sizeBytes }` — the
+ *     checkpoint heartbeat (see DESIGN.md "Checkpoints"). An unverifiable *hint*, never
+ *     trusted; the same record also travels over the libp2p fetch protocol, so its codec is
+ *     standalone (`encodeRootRecord`/`decodeRootRecord`).
+ *
+ * A message carries **no authority** either way: all trust comes from re-verifying the
+ * self-authenticating bundle (or the self-verifying blocks behind a root) before acting.
+ * Encoding is the same canonical dag-cbor as the rest of the protocol; the layout is pinned
+ * by fixed test vectors in `messages.test.ts` — any change is a breaking wire change.
+ */
+/** Envelope wire version (the root record carries its own `version` for the fetch path). */
+export declare const MESSAGE_VERSION = 1;
+export declare const ROOT_RECORD_VERSION = 1;
+/** A topic's compacted-state advertisement: tiny, constant-size, unauthenticated (a hint). */
+export interface RootRecord {
+    version: number;
+    /** The checkpoint root CID of the advertiser's current winner-set. */
+    root: CID;
+    /** Advisory: winners inlined behind the root. Unverifiable until the blocks arrive. */
+    count: number;
+    /** Advisory: total checkpoint block bytes behind the root. Unverifiable until they arrive. */
+    sizeBytes: number;
+}
+/**
+ * The **fetch-protocol** root response: the advertisement plus the checkpoint's chunk-CID index
+ * (the root manifest's contents). Carrying it lets a cold joiner skip the root-manifest bitswap
+ * round-trip — it re-derives `CID(dag-cbor({ chunks }))`, checks it equals `root` (self-verifying,
+ * so the index is never a new trust vector), and pulls every chunk in parallel (see DESIGN.md
+ * "Checkpoints", "Block pull"). Only the *direct fetch response* carries the index; the pubsub
+ * heartbeat stays the bare {@link RootRecord} so its message cap remains a tiny fixed constant
+ * (the anti-amplification property — the index is O(sizeBytes / chunk-ceiling), a ~36 B/MiB
+ * pointer list, not the payload, but the broadcast path keeps the stricter guarantee anyway).
+ */
+export interface FetchRootRecord extends RootRecord {
+    /** The checkpoint's chunk CIDs, in root order. `CID(dag-cbor({ chunks })) === root`. */
+    chunks: CID[];
+}
+export type VoteMessage = {
+    kind: "bundle";
+    bundle: Uint8Array;
+} | {
+    kind: "root";
+    record: RootRecord;
+};
+/** Encode one bundle's binary block bytes as a live-delta message. */
+export declare function encodeBundleMessage(blockBytes: Uint8Array): Uint8Array;
+/**
+ * Encode a root record as a heartbeat message. The broadcast heartbeat carries only the bare
+ * advertisement (never the fetch response's chunk index), so its size stays a tiny fixed
+ * constant — accepts a {@link FetchRootRecord} and drops the index (see {@link FetchRootRecord}).
+ */
+export declare function encodeRootMessage(record: RootRecord): Uint8Array;
+/**
+ * Decode a pubsub payload to its message kind, throwing on anything malformed. The gate
+ * treats a throw as layer-1 badness (`reject`) — the cheapest, pre-verify check.
+ */
+export declare function decodeVoteMessage(data: Uint8Array): VoteMessage;
+/**
+ * The libp2p fetch-protocol key suffix for a topic's root record: the full key is
+ * `topic + "/root"` (the topic prefix only namespaces *which* contest a multi-contest
+ * responder is asked about — it is not a pubsub topic). See DESIGN.md "Checkpoints".
+ */
+export declare const ROOT_FETCH_KEY_SUFFIX = "/root";
+/** The fetch-protocol key for one contest's root record. */
+export declare function rootFetchKey(topic: string): string;
+/**
+ * Standalone root-record codec — the record served over the libp2p fetch protocol, carrying the
+ * chunk-CID index so a cold joiner can skip the root-manifest round-trip (see {@link FetchRootRecord}).
+ */
+export declare function encodeRootRecord(record: FetchRootRecord): Uint8Array;
+/** Decode a fetch-protocol root-record value (with its chunk index); throws on malformed. */
+export declare function decodeRootRecord(bytes: Uint8Array): FetchRootRecord;
+/**
+ * The fixed byte cap for a root-kind message. The record is ~100 B by construction (version +
+ * CID link + two small ints + envelope), so this is a generous constant — anything larger is
+ * provably not a well-formed root message.
+ */
+export declare const MAX_ROOT_MESSAGE_BYTES = 256;
+/**
+ * The derived per-message cap for a bundle-kind message — a pure function of the criteria
+ * (see DESIGN.md "Message size cap"): the criteria's own `maxVotesPerAddress` bounds the
+ * entry count, the schema's fixed field bounds (253-byte name, binary crypto fields) bound
+ * the entry size, so every peer computes the same cap from the same criteria bytes and an
+ * over-cap `reject` stays deterministic, penalizable, and cacheable. Deliberately NOT a
+ * criteria field: a raw byte knob could contradict `maxVotesPerAddress` and reject valid
+ * bundles.
+ */
+export declare function maxBundleMessageBytes(criteria: Pick<Criteria, "maxVotesPerAddress">): number;