@bitsocial/pubsub-votes 0.0.2

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

@@ -0,0 +1,60 @@
+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[];
+    /** 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,262 @@
+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 } 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 chaseLimit = pLimit(2);
+    const chaser = makeRootChaser({
+        getBlock: async (cid, signal) => {
+            try {
+                return await blockstore.get(cid, { signal });
+            }
+            catch {
+                return undefined;
+            }
+        },
+        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.
+        onRootRecord: (record) => {
+            heardRoots.push(record);
+            void (async () => {
+                const own = await checkpointRootRecord();
+                if (own.root.equals(record.root)) {
+                    matchedOwnRoot = true;
+                    return;
+                }
+                chaser.chase(record.root);
+            })().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,
+        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;

package/dist/transport/messages.js

@@ -0,0 +1,117 @@
+import { CID } from "multiformats/cid";
+import * as dagCbor from "@ipld/dag-cbor";
+import { z } from "zod";
+import { encodeCanonical } from "../encoding/canonical.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 const MESSAGE_VERSION = 1;
+export const ROOT_RECORD_VERSION = 1;
+/** See `z.custom` note in crdt/codec.ts — `z.instanceof(Uint8Array)` over-narrows the buffer type. */
+const BytesSchema = z.custom((value) => value instanceof Uint8Array, "expected bytes");
+const CidSchema = z.custom((value) => CID.asCID(value) !== null, "expected a CID link");
+const RootRecordSchema = z.strictObject({
+    version: z.number().int().positive(),
+    // Points to a `CheckpointRoot` block (`{ chunks: CID[] }`, checkpoint/codec.ts).
+    root: CidSchema,
+    count: z.number().int().nonnegative(),
+    sizeBytes: z.number().int().nonnegative()
+});
+const FetchRootRecordSchema = z.strictObject({
+    version: z.number().int().positive(),
+    root: CidSchema,
+    chunks: z.array(CidSchema),
+    count: z.number().int().nonnegative(),
+    sizeBytes: z.number().int().nonnegative()
+});
+const MessageSchema = z.discriminatedUnion("kind", [
+    z.strictObject({ v: z.literal(MESSAGE_VERSION), kind: z.literal("bundle"), bundle: BytesSchema }),
+    z.strictObject({ v: z.literal(MESSAGE_VERSION), kind: z.literal("root"), record: RootRecordSchema })
+]);
+/** Project any root record (possibly a {@link FetchRootRecord}) to the bare advertisement fields. */
+function toRootRecord(record) {
+    return { version: record.version, root: record.root, count: record.count, sizeBytes: record.sizeBytes };
+}
+/** Encode one bundle's binary block bytes as a live-delta message. */
+export function encodeBundleMessage(blockBytes) {
+    return encodeCanonical({ v: MESSAGE_VERSION, kind: "bundle", bundle: blockBytes });
+}
+/**
+ * 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 function encodeRootMessage(record) {
+    return encodeCanonical({ v: MESSAGE_VERSION, kind: "root", record: RootRecordSchema.parse(toRootRecord(record)) });
+}
+/**
+ * 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 function decodeVoteMessage(data) {
+    const parsed = MessageSchema.parse(dagCbor.decode(data));
+    return parsed.kind === "bundle" ? { kind: "bundle", bundle: parsed.bundle } : { kind: "root", record: parsed.record };
+}
+/**
+ * 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 const ROOT_FETCH_KEY_SUFFIX = "/root";
+/** The fetch-protocol key for one contest's root record. */
+export function rootFetchKey(topic) {
+    return `${topic}${ROOT_FETCH_KEY_SUFFIX}`;
+}
+/**
+ * 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 function encodeRootRecord(record) {
+    return encodeCanonical(FetchRootRecordSchema.parse(record));
+}
+/** Decode a fetch-protocol root-record value (with its chunk index); throws on malformed. */
+export function decodeRootRecord(bytes) {
+    return FetchRootRecordSchema.parse(dagCbor.decode(bytes));
+}
+/**
+ * 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 const MAX_ROOT_MESSAGE_BYTES = 256;
+/** Envelope + fixed bundle fields (address, blockNumber, signature, structure), generously. */
+const BUNDLE_MESSAGE_OVERHEAD_BYTES = 256;
+/**
+ * One vote entry's ceiling: a 253-byte name (the schema's DNS bound), a raw-multihash
+ * publicKey (≲64 B for any realistic key hash), a small int vote, and map structure —
+ * rounded up generously. Generosity is safe: the cap exists to bound *adversarial* payloads,
+ * and what matters is that every peer derives the identical number from the criteria.
+ */
+const MAX_VOTE_ENTRY_BYTES = 512;
+/**
+ * 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 function maxBundleMessageBytes(criteria) {
+    return BUNDLE_MESSAGE_OVERHEAD_BYTES + MAX_VOTE_ENTRY_BYTES * criteria.maxVotesPerAddress;
+}

package/dist/transport/rate-limit.d.ts

@@ -0,0 +1,11 @@
+/**
+ * A per-peer fixed-window rate gate for the forward-gate. Bounds how many messages one peer
+ * can make us validate per window, capping the resource cost of a flood of plausible-looking
+ * announcements (the residual "resource exhaustion, not incorrectness" concern in DESIGN.md
+ * "Transport"). Over-rate returns `false`, which the gate maps to `ignore` — dropped without
+ * a peer-score penalty, since being briefly over a local rate is not provable misbehavior.
+ */
+export declare function makeRateLimiter(opts: {
+    limit: number;
+    intervalMs: number;
+}): (peer: string) => boolean;

package/dist/transport/rate-limit.js

@@ -0,0 +1,20 @@
+/**
+ * A per-peer fixed-window rate gate for the forward-gate. Bounds how many messages one peer
+ * can make us validate per window, capping the resource cost of a flood of plausible-looking
+ * announcements (the residual "resource exhaustion, not incorrectness" concern in DESIGN.md
+ * "Transport"). Over-rate returns `false`, which the gate maps to `ignore` — dropped without
+ * a peer-score penalty, since being briefly over a local rate is not provable misbehavior.
+ */
+export function makeRateLimiter(opts) {
+    const windows = new Map();
+    return (peer) => {
+        const now = Date.now();
+        const window = windows.get(peer);
+        if (!window || now - window.start >= opts.intervalMs) {
+            windows.set(peer, { count: 1, start: now });
+            return true;
+        }
+        window.count += 1;
+        return window.count <= opts.limit;
+    };
+}

package/dist/transport/transport.d.ts

@@ -0,0 +1,20 @@
+import type { PubsubService, VoteTransport } from "./types.js";
+import type { GossipGate } from "./gossip-validator.js";
+/**
+ * The live transport: wires the host's gossipsub to the forward-gate. This is the only place
+ * the async validator is installed on a real topic; the decision logic lives in the pure
+ * {@link GossipGate} (gossip-validator.ts), so this module is thin glue.
+ *
+ * On `start` it installs the gate as the topic validator (gossipsub awaits it before
+ * re-forwarding — see DESIGN.md "Transport") and subscribes. Publishing is the live-delta
+ * model: one inline bundle per message (a new vote, a client re-publish, or a withdrawal), or a
+ * root-record heartbeat. Cold-start root pulls ride the libp2p fetch protocol, not pubsub
+ * (see DESIGN.md "Checkpoints").
+ */
+export interface VoteTransportDeps {
+    pubsub: PubsubService;
+    topic: string;
+    /** The forward-gate; validates + merges accepted bundles, surfaces root records. */
+    gate: GossipGate;
+}
+export declare function makeVoteTransport(deps: VoteTransportDeps): VoteTransport;

package/dist/transport/transport.js

@@ -0,0 +1,35 @@
+import { encodeBundleMessage, encodeRootMessage } from "./messages.js";
+export function makeVoteTransport(deps) {
+    const { pubsub, topic, gate } = deps;
+    // The installed gossipsub validator: filter to our topic and run the gate. Returning a
+    // promise makes gossipsub await the full pipeline before forwarding. Accepted bundles are
+    // merged (and root records surfaced) by the gate's own callbacks.
+    const validator = async (peer, message) => {
+        if (message.topic !== topic)
+            return "ignore";
+        return gate.validate(message.data, peer.toString());
+    };
+    return {
+        async start() {
+            if (!pubsub.topicValidators) {
+                throw new Error("the injected pubsub has no `topicValidators` map; a gossipsub service is required to " +
+                    "install the validate-before-forward gate. See DESIGN.md \"Transport\".");
+            }
+            pubsub.topicValidators.set(topic, validator);
+            pubsub.subscribe(topic);
+        },
+        async stop() {
+            pubsub.topicValidators?.delete(topic);
+            pubsub.unsubscribe(topic);
+        },
+        async publishBundle(blockBytes) {
+            // gossipsub resolves `{ recipients }`; a non-gossipsub pubsub may resolve nothing —
+            // fall back to 0 rather than assume the shape.
+            const result = await pubsub.publish(topic, encodeBundleMessage(blockBytes));
+            return { recipientCount: result?.recipients?.length ?? 0 };
+        },
+        async publishRootRecord(record) {
+            await pubsub.publish(topic, encodeRootMessage(record));
+        }
+    };
+}