@bitsocial/pubsub-voting 0.0.6

package/dist/transport/announce/types.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Provider-record announcer types (see DESIGN.md "Deferred pkc-js work", provider-record
+ * announces). The announcer is the write side of the delegated-routing seam: querying rides the
+ * injected node's `libp2p.contentRouting` (the host wires its routers into `libp2p.services`), but
+ * the pinned js stack has NO working announce path — `@helia/delegated-routing-v1-http-api-client`'s
+ * `provide()` is a literal noop — so provider records only get written by a direct
+ * `PUT /routing/v1/providers` to each router. This library is the node that actually holds the
+ * state (topic membership, fetch responder, blockstore), so its records are always truthful and
+ * current; `PubsubVoterOptions.httpRouterUrls` exists ONLY because announcing cannot ride the
+ * `contentRouting` seam.
+ *
+ * The implementation is Node-only: the browser build swaps `node.js` for the inert `browser.js`
+ * stub via the package.json `browser` field (the same remap as `src/storage/`), because a browser
+ * peer is not dialable and must never announce.
+ */
+/**
+ * The slice of the injected node's libp2p the announcer reads, declared structurally (a running
+ * `Libp2p` satisfies it). `self:peer:update` fires when the node's address set changes — an
+ * AutoTLS certificate landing, a WebRTC-Direct certhash rotation — and triggers a re-announce so
+ * records never carry stale addresses for more than a debounce window.
+ */
+export interface AnnouncerLibp2p {
+    peerId: {
+        toString(): string;
+    };
+    getMultiaddrs(): Array<{
+        toString(): string;
+    }>;
+    addEventListener(type: "self:peer:update", listener: () => void): void;
+    removeEventListener(type: "self:peer:update", listener: () => void): void;
+}
+export interface AnnouncerOptions {
+    /** Delegated Routing V1 base URLs to PUT provider records to. Empty means never announce. */
+    routerUrls: readonly string[];
+    /** The injected node's libp2p (peer id, current addresses, address-change events). */
+    libp2p: AnnouncerLibp2p;
+    /**
+     * The CIDs to announce, collected fresh per tick: every joined contest's criteria CID plus its
+     * current checkpoint root + chunk CIDs, batched into ONE record (`Keys` is an array) so a
+     * directory host costs one request per router per tick. An empty list skips the tick.
+     */
+    keys(): Promise<string[]>;
+    /** Re-announce cadence (ms). Test seam; defaults to hourly (see `ANNOUNCE_INTERVAL_MS`). */
+    intervalMs?: number;
+    /** Change-coalescing window (ms). Test seam; defaults to `ANNOUNCE_DEBOUNCE_MS`. */
+    debounceMs?: number;
+    /** Per-router PUT deadline (ms). Test seam; defaults to `ANNOUNCE_ROUTER_TIMEOUT_MS`. */
+    timeoutMs?: number;
+    /**
+     * Per-router failure hook (timeout, non-2xx, network error). Purely observational — a failing
+     * router never throws into the voter and is not retried; the next tick covers it.
+     */
+    onError?(url: string, error: unknown): void;
+}
+/** The voter-facing announcer handle. All methods are synchronous and idempotent. */
+export interface Announcer {
+    /**
+     * Begin announcing: subscribe to address changes and arm the periodic re-announce. Called when
+     * the voter's first topic joins (symmetric with the lazy fetch-responder lifecycle). Does not
+     * announce by itself — the join that triggered it also calls {@link notifyChange}.
+     */
+    start(): void;
+    /**
+     * Stop announcing and drop timers/listeners. Called when the last topic is left. Records
+     * already written age out by the router's TTL; there is no un-announce.
+     */
+    stop(): void;
+    /**
+     * Coalesced re-announce trigger: a contest joined, a checkpoint root changed, or the address
+     * set changed. The first call arms one debounce timer; further calls within the window ride
+     * it, so a gossip burst (or a directory-wide join) costs one announce.
+     */
+    notifyChange(): void;
+}

package/dist/transport/announce/types.js

@@ -0,0 +1,16 @@
+/**
+ * Provider-record announcer types (see DESIGN.md "Deferred pkc-js work", provider-record
+ * announces). The announcer is the write side of the delegated-routing seam: querying rides the
+ * injected node's `libp2p.contentRouting` (the host wires its routers into `libp2p.services`), but
+ * the pinned js stack has NO working announce path — `@helia/delegated-routing-v1-http-api-client`'s
+ * `provide()` is a literal noop — so provider records only get written by a direct
+ * `PUT /routing/v1/providers` to each router. This library is the node that actually holds the
+ * state (topic membership, fetch responder, blockstore), so its records are always truthful and
+ * current; `PubsubVoterOptions.httpRouterUrls` exists ONLY because announcing cannot ride the
+ * `contentRouting` seam.
+ *
+ * The implementation is Node-only: the browser build swaps `node.js` for the inert `browser.js`
+ * stub via the package.json `browser` field (the same remap as `src/storage/`), because a browser
+ * peer is not dialable and must never announce.
+ */
+export {};

package/dist/transport/bundle-store.d.ts

@@ -0,0 +1,11 @@
+import type { BundleStore } from "../crdt/types.js";
+import type { BlockstoreLike } from "./types.js";
+/**
+ * A {@link BundleStore} backed by the host's Helia blockstore. `put` writes a bundle as a
+ * dag-cbor block locally; `get` reads by CID — and because bitswap retrieves through the
+ * blockstore, an unknown CID is fetched from peers. A fetch that fails or times out surfaces
+ * as `undefined` (not a throw), which the forward-gate reads as "unfetchable -> ignore"
+ * rather than a provable fault. Lives in transport/ (not crdt/) because it touches the
+ * blockstore; the CRDT stays libp2p-free.
+ */
+export declare function makeBlockstoreBundleStore(blockstore: BlockstoreLike): BundleStore;

package/dist/transport/bundle-store.js

@@ -0,0 +1,34 @@
+import { encodeBundle, decodeBundle, bundleCid } from "../crdt/codec.js";
+/**
+ * A {@link BundleStore} backed by the host's Helia blockstore. `put` writes a bundle as a
+ * dag-cbor block locally; `get` reads by CID — and because bitswap retrieves through the
+ * blockstore, an unknown CID is fetched from peers. A fetch that fails or times out surfaces
+ * as `undefined` (not a throw), which the forward-gate reads as "unfetchable -> ignore"
+ * rather than a provable fault. Lives in transport/ (not crdt/) because it touches the
+ * blockstore; the CRDT stays libp2p-free.
+ */
+export function makeBlockstoreBundleStore(blockstore) {
+    return {
+        async put(bundle) {
+            const cid = await bundleCid(bundle);
+            await blockstore.put(cid, encodeBundle(bundle));
+            return cid;
+        },
+        async get(cid, options) {
+            try {
+                return decodeBundle(await blockstore.get(cid, options));
+            }
+            catch {
+                return undefined; // unfetchable / undecodable / aborted — gate treats as ignore
+            }
+        },
+        async has(cid) {
+            try {
+                return await blockstore.has(cid);
+            }
+            catch {
+                return false;
+            }
+        }
+    };
+}

package/dist/transport/chase.d.ts

@@ -0,0 +1,125 @@
+import type { CID } from "multiformats/cid";
+import type { PeerId } from "@libp2p/interface";
+import type { BlockSessionLike } from "./types.js";
+import type { VotesBundle } from "../schema/votes.js";
+import type { VerdictCache } from "../verify/cache.js";
+import type { VerifyResult } from "../verify/types.js";
+import type { PendingBundle } from "../verify/background.js";
+/**
+ * The divergence chase: act on an advertised checkpoint root that differs from our own (a
+ * heartbeat or fetch-protocol hint — see DESIGN.md "Checkpoints", "Block pull"). Pull the
+ * blocks behind the root by CID — through a bitswap session seeded with the root's advertisers
+ * when the `openSession` seam is present (targeted wants, one provider lookup per root), the
+ * broadcast `getBlock` otherwise or on session failure — and admit each inlined bundle in two
+ * stages:
+ *
+ *   1. **Offline, synchronous, before admit** (µs each): signature + criteria constraints via
+ *      `verifyOffline` — a forged or malformed bundle dies here and is never admitted.
+ *   2. **Network, deferred**: the on-chain gate read and name resolution run in the background
+ *      chain verifier (`deferVerify`, one batch per chased root so the gate reads batch into
+ *      as few RPC round trips as the rule allows), which confirms or evicts each bundle after
+ *      the fact. This is what keeps a cold join non-blocking: a 100-vote checkpoint admits in
+ *      milliseconds instead of serializing 100 chain reads (see DESIGN.md "Background chain
+ *      verification").
+ *
+ * So a single liar cannot inject a forged vote (offline check) nor hide an honest one
+ * (union-only merge); an *ineligible-wallet* bundle it injects is admitted provisionally,
+ * surfaces only as a `chainVerified: false` tally row, is never re-served in our checkpoint,
+ * and is evicted as soon as its batched gate read lands.
+ *
+ * Bounded like everything at the gate: a shared concurrency cap (`limit`), a per-root
+ * deadline whose `AbortSignal` cancels in-flight block wants, and in-flight dedup so a spray
+ * of the same root queues one chase, not many. A failed chase (unfetchable blocks, malformed
+ * chunks, all-invalid bundles) contributes nothing and throws nothing — the hint was never
+ * trusted. No libp2p import; pure seams, unit-testable offline.
+ */
+/**
+ * A directed block-pull session for one chased root, seeded with the peers that advertised it
+ * (see DESIGN.md "Block pull"). The chase tries it before the broadcast `getBlock` and falls
+ * back on any failure, so a session is an optimisation, never a correctness dependency.
+ */
+export interface ChaseSession {
+    /** Fetch one block through the session; `undefined` or a throw falls back to `getBlock`. */
+    get(cid: CID, signal: AbortSignal): Promise<Uint8Array | undefined>;
+    /** Seed a late advertiser of the same root into the running pull. MUST NOT throw. */
+    addPeer(peer: PeerId): void;
+    /** Abort the session's in-flight wants and release it. MUST NOT throw. */
+    close(): void;
+}
+/**
+ * Wrap a raw block session into a {@link ChaseSession}, enforcing the contracts above at the one
+ * boundary where they can be violated: `get` maps any failure to `undefined` (the chase falls
+ * back to the broadcast want), and `addPeer`/`close` swallow synchronous throws as well as
+ * rejections — a late hint can race the chase deadline and land on an already-closed session,
+ * and nothing on that path guards again (`addProviders` relies on the MUST NOT throw contract,
+ * and `chase()` is a fire-and-forget API). Shared by the voter and the integration harness so
+ * the harness stays faithful to the production seam it mirrors.
+ */
+export declare function toChaseSession(session: BlockSessionLike): ChaseSession;
+export interface RootChaserDeps {
+    /**
+     * Fetch one checkpoint block by CID (blockstore + directed bitswap); `undefined` or a
+     * throw means unavailable. `signal` aborts the want when the per-root deadline fires.
+     */
+    getBlock: (cid: CID, signal: AbortSignal) => Promise<Uint8Array | undefined>;
+    /**
+     * Open a bitswap session for one chased root, seeded with `providers` — the advertisers of
+     * that exact root, who provably hold its blocks. Optional twice over: absent when the host
+     * blockstore cannot make sessions (plain blockstores, unit-test mocks), and a call may
+     * return `undefined` to decline. NEVER invoked with zero providers — nothing announces
+     * these CIDs to routing yet, so an unseeded session would fail-fast where the broadcast
+     * `getBlock` succeeds via any connected topic peer.
+     */
+    openSession?: (root: CID, providers: PeerId[]) => ChaseSession | undefined;
+    /** Stage 1 only — signature + constraints, local and synchronous (the gate's same stage). */
+    verifyOffline: (bundle: VotesBundle) => Promise<VerifyResult>;
+    /** The gate's per-CID verdict cache, shared so chased bundles reuse (and feed) it. */
+    cache: VerdictCache;
+    /** The gate's freshness guard (see gossip-validator.ts); omitted ⇒ no check. */
+    isEvaluableNow?: (bundle: VotesBundle) => Promise<boolean>;
+    /** Skip bundles we already hold (their CID is in the store) without re-verifying. */
+    hasBundle: (cid: CID) => Promise<boolean>;
+    /**
+     * Store an offline-valid bundle's block bytes and admit its CID into the CRDT (idempotent).
+     * `verified: true` means a cached terminal verdict already covers the FULL pipeline (the
+     * bundle was verified before, e.g. by the forward-gate); `verified: false` is a provisional
+     * admit whose deferred checks ride `deferVerify`.
+     */
+    admit: (args: {
+        cid: CID;
+        bytes: Uint8Array;
+        bundle: VotesBundle;
+        verified: boolean;
+    }) => Promise<void>;
+    /** Hand one chased root's provisionally admitted bundles to the background chain verifier. */
+    deferVerify: (entries: PendingBundle[]) => void;
+    /** Called once per chase that admitted at least one bundle (drives tally updates). */
+    onMerged?: () => void;
+    /** Concurrency limiter shared across chases (a root spray queues, never floods). */
+    limit: <T>(fn: () => Promise<T>) => Promise<T>;
+    /** Per-root deadline (ms); on expiry the abort signal fires and the chase yields nothing. */
+    timeoutMs: number;
+}
+export interface RootChaser {
+    /**
+     * Chase one advertised root, fire-and-forget: never throws, never blocks the caller
+     * (the validator hands hints here without awaiting). A root already being chased is
+     * dropped — the in-flight run covers it.
+     *
+     * `chunks` is the optional piggybacked chunk-CID index from a fetch-protocol root record
+     * (see DESIGN.md "Block pull"): when supplied and it re-derives to `root`, the chase skips
+     * the root-manifest bitswap round-trip and pulls the chunks directly. A heartbeat hint (no
+     * index) omits it and takes the manifest-fetch path. The index is verified against `root`,
+     * so a bad one simply falls back — never a trust vector.
+     *
+     * `providers` are the peers known to have advertised this exact root (the triggering
+     * sender plus any prior advertisers still connected — see the voter's peer-root map); the
+     * chase pulls through a bitswap session seeded with them when the `openSession` seam is
+     * present, broadcasting only as fallback. A provider hint for a root already in flight is
+     * added to the running session instead of dropped.
+     */
+    chase(root: CID, chunks?: CID[], providers?: readonly PeerId[]): void;
+    /** Roots currently being chased (for tests/introspection). */
+    inFlight(): number;
+}
+export declare function makeRootChaser(deps: RootChaserDeps): RootChaser;

package/dist/transport/chase.js

@@ -0,0 +1,182 @@
+import { decodeCheckpoint } from "../checkpoint/codec.js";
+import { encodeBundle, bundleCidForBytes } from "../crdt/codec.js";
+/**
+ * Wrap a raw block session into a {@link ChaseSession}, enforcing the contracts above at the one
+ * boundary where they can be violated: `get` maps any failure to `undefined` (the chase falls
+ * back to the broadcast want), and `addPeer`/`close` swallow synchronous throws as well as
+ * rejections — a late hint can race the chase deadline and land on an already-closed session,
+ * and nothing on that path guards again (`addProviders` relies on the MUST NOT throw contract,
+ * and `chase()` is a fire-and-forget API). Shared by the voter and the integration harness so
+ * the harness stays faithful to the production seam it mirrors.
+ */
+export function toChaseSession(session) {
+    return {
+        get: async (cid, signal) => {
+            try {
+                return await session.get(cid, { signal });
+            }
+            catch {
+                return undefined; // the chase falls back to the broadcast want
+            }
+        },
+        addPeer: (peer) => {
+            // A bad late hint (undialable, session at capacity, session already closed) must
+            // never surface. `Promise.resolve(...)` alone would miss a synchronous throw — it
+            // happens while evaluating the argument — so the call itself needs the try.
+            try {
+                void Promise.resolve(session.addPeer(peer)).catch(() => { });
+            }
+            catch {
+                // same no-op as a rejection
+            }
+        },
+        close: () => {
+            try {
+                session.close();
+            }
+            catch {
+                // releasing a finished session must not fail the chase
+            }
+        }
+    };
+}
+export function makeRootChaser(deps) {
+    const { getBlock, openSession, verifyOffline, cache, isEvaluableNow, hasBundle, admit, deferVerify, onMerged, limit, timeoutMs } = deps;
+    const inFlight = new Map();
+    function addProviders(flight, providers) {
+        for (const peer of providers) {
+            const id = peer.toString();
+            if (flight.seeded.has(id))
+                continue;
+            flight.seeded.add(id);
+            if (flight.session !== undefined)
+                flight.session.addPeer(peer);
+            else if (!flight.started)
+                flight.queued.push(peer);
+            // started with no session (seam absent/declined): a late hint cannot help — drop it.
+        }
+    }
+    async function runChase(flight, root, chunks) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        // Open the session only now (not at enqueue): hints that arrived while queued behind the
+        // concurrency cap are all in `queued`, so they seed the session instead of dialing addPeer.
+        // A throwing factory degrades to the broadcast path exactly like an absent seam — a
+        // session is an optimisation, never something a chase may die on.
+        if (flight.queued.length > 0) {
+            try {
+                flight.session = openSession?.(root, flight.queued.splice(0));
+            }
+            catch {
+                flight.session = undefined;
+            }
+        }
+        flight.started = true;
+        // One failed session want marks the whole session dead (a converged advertiser holds all
+        // blocks or none) — the remaining blocks skip straight to the broadcast fallback instead
+        // of paying a doomed session attempt each.
+        let sessionDead = false;
+        const fetchBlock = async (cid) => {
+            if (controller.signal.aborted)
+                return undefined;
+            if (flight.session !== undefined && !sessionDead) {
+                try {
+                    const bytes = await flight.session.get(cid, controller.signal);
+                    if (bytes !== undefined)
+                        return bytes;
+                }
+                catch {
+                    // fall through to the broadcast path
+                }
+                sessionDead = true;
+                if (controller.signal.aborted)
+                    return undefined; // deadline, not a session miss
+            }
+            try {
+                return await getBlock(cid, controller.signal);
+            }
+            catch {
+                return undefined; // unfetchable/aborted — decode throws "unavailable", chase yields nothing
+            }
+        };
+        try {
+            // Race the decode against the deadline so even a `getBlock` that ignores its abort
+            // signal cannot pin this chase slot past `timeoutMs` — the slot is always freed.
+            const winners = await Promise.race([
+                decodeCheckpoint(root, fetchBlock, chunks),
+                new Promise((resolve) => {
+                    controller.signal.addEventListener("abort", () => resolve(undefined), { once: true });
+                })
+            ]);
+            if (winners === undefined)
+                return; // deadline hit — the hint contributed nothing
+            let merged = false;
+            const pending = [];
+            for (const bundle of winners) {
+                if (controller.signal.aborted)
+                    break;
+                // Re-encoding the decoded bundle reproduces the exact block bytes (the codec is
+                // canonical), so the CID matches the advertiser's block and dedups everywhere.
+                const bytes = encodeBundle(bundle);
+                const cid = await bundleCidForBytes(bytes);
+                if (await hasBundle(cid))
+                    continue; // already held — nothing to verify
+                const cached = cache.get(cid);
+                if (cached) {
+                    if (!cached.valid)
+                        continue; // known bad — skip
+                    await admit({ cid, bytes, bundle, verified: true }); // full pipeline already passed
+                    merged = true;
+                    continue;
+                }
+                if (isEvaluableNow && !(await isEvaluableNow(bundle)))
+                    continue; // transient, uncached
+                const offline = await verifyOffline(bundle);
+                if (!offline.valid) {
+                    // A liar's forged/malformed bundle dies here, before admit. A provable
+                    // offline reject (bad signature, constraints) is terminal — cache it so a
+                    // re-served copy short-circuits; a transient `ignore` stays uncached.
+                    if (offline.disposition === "reject")
+                        cache.set(cid, offline);
+                    continue;
+                }
+                await admit({ cid, bytes, bundle, verified: false });
+                pending.push({ cid, bundle });
+                merged = true;
+            }
+            // One batch per chased root: the background verifier groups these by sample block
+            // and batches the gate reads (see verify/background.ts).
+            if (pending.length > 0)
+                deferVerify(pending);
+            if (merged)
+                onMerged?.();
+        }
+        finally {
+            clearTimeout(timer);
+            flight.session?.close();
+        }
+    }
+    return {
+        chase(root, chunks, providers) {
+            const key = root.toString();
+            const existing = inFlight.get(key);
+            if (existing !== undefined) {
+                // The in-flight run covers this hint (chunks derive from root) — but a new
+                // advertiser joins its session rather than being dropped on the floor.
+                if (providers !== undefined)
+                    addProviders(existing, providers);
+                return;
+            }
+            const flight = { seeded: new Set(), queued: [], session: undefined, started: false };
+            if (providers !== undefined)
+                addProviders(flight, providers);
+            inFlight.set(key, flight);
+            void limit(() => runChase(flight, root, chunks))
+                .catch(() => { }) // a failed chase contributes nothing; the hint was never trusted
+                .finally(() => inFlight.delete(key));
+        },
+        inFlight() {
+            return inFlight.size;
+        }
+    };
+}

package/dist/transport/gossip-validator.d.ts

@@ -0,0 +1,107 @@
+import type { CID } from "multiformats/cid";
+import type { VotesBundle } from "../schema/votes.js";
+import { type VerdictCache } from "../verify/cache.js";
+import type { BundleVerifier } from "../verify/types.js";
+import type { AcceptedDedup } from "./accepted-dedup.js";
+import type { RootRecord, VoteMessage } from "./messages.js";
+/**
+ * The forward-gate: the async gossipsub topic validator's decision core, written as a pure
+ * function over injected seams (no libp2p import) so it is fully unit-testable. It runs the
+ * FULL validity pipeline on the bundle INLINED in a received message BEFORE the message is
+ * re-forwarded, so an invalid bundle never crosses an honest hop and gossipsub's `reject`
+ * scores the sender for semantic — not just byte-level — badness. See DESIGN.md "Transport".
+ *
+ * The payload is a two-kind discriminated union (see transport/messages.ts):
+ *   - a **bundle delta** — the wallet's own bundle as exact block bytes, validated straight
+ *     from the message (no fetch toward the publisher exists on this path);
+ *   - a **root record** — the checkpoint heartbeat, a fixed-shape unverifiable *hint* that
+ *     short-circuits at layer 1: forwarded within its own per-peer rate and handed to the
+ *     chase logic, never verified here (only equality with our own root is checkable) and
+ *     never trusted.
+ *
+ * Verdicts (who gets blamed):
+ *   - "accept": the inlined bundle verified (or is a known-valid re-publish), or a
+ *     well-formed within-rate root record — deliver, merge (bundles), forward.
+ *   - "reject": something is PROVABLY invalid (malformed message, over the derived size cap,
+ *     a bundle that fails verification) — drop, do not forward, penalize the sender.
+ *   - "ignore": no verdict reachable through no provable fault of the sender — either a
+ *     transient/local condition (over the per-peer rate, internal error, deadline) or a
+ *     view-/clock-dependent verdict two honest peers can disagree on right now: a bundle
+ *     bucketed ahead of our chain head (`isEvaluableNow`), or a `community.name` resolved at
+ *     head during a re-point window. Drop, do not forward, do NOT penalize, and do NOT cache
+ *     (it can change) — using `reject` here would punish honest relayers for transient
+ *     conditions and hand attackers a grief vector.
+ *
+ * Cheap-to-expensive with early exit: size/decode/rate first, then hash + caches, then the
+ * verify pipeline — so a re-published known bundle costs one hash and zero chain work.
+ */
+export type MessageVerdict = "accept" | "reject" | "ignore";
+export interface GossipGateDeps {
+    /** Decode a payload to its message kind; throws on malformed (see transport/messages.ts). */
+    decodeMessage: (data: Uint8Array) => VoteMessage;
+    /**
+     * Decode inlined bundle-block bytes and hash them to the bundle CID (the verdict-cache
+     * key). Throws on malformed block bytes — provable layer-1 badness.
+     */
+    parseBundle: (blockBytes: Uint8Array) => Promise<{
+        cid: CID;
+        bundle: VotesBundle;
+    }>;
+    /** The full validity pipeline for one bundle (see verify/bundle.ts). */
+    verifier: BundleVerifier;
+    /**
+     * Clock-aware freshness guard, kept OUT of the pure (cacheable) verifier: is this bundle's
+     * bucket sample block already reachable from our chain head? A bundle dated to a future
+     * bucket (the voter's head ahead of ours, clock skew, or an absurd `blockNumber`) is not
+     * yet evaluable — transient, so the gate `ignore`s it (no penalty, uncached) until our head
+     * catches up. Omitted ⇒ no freshness check. Steady-state votes resolve `true` with no chain
+     * read; only a look-ahead bundle costs a (memoized) head read.
+     */
+    isEvaluableNow?: (bundle: VotesBundle) => Promise<boolean>;
+    /** Per-CID verdict cache — dedups re-published bundles and known-bad blocks. */
+    cache: VerdictCache;
+    /**
+     * Optional dedup of already-accepted votes by `(wallet, bucket, votes)`. A same-bucket,
+     * same-choice re-sign under fresh bytes is dropped — not verified, not merged, not
+     * forwarded — so a re-sign flood costs no gate read and does not amplify. Omitted ⇒ every
+     * fresh bundle is verified on its own.
+     */
+    acceptedDedup?: AcceptedDedup;
+    /**
+     * Store the verified bundle's exact block bytes and admit its CID into the CRDT
+     * (idempotent). Exact bytes preserve byte-identity with the sender's block.
+     */
+    admit: (args: {
+        cid: CID;
+        bytes: Uint8Array;
+        bundle: VotesBundle;
+    }) => Promise<void>;
+    /**
+     * Concurrency limiter (p-limit) shared across in-flight verifications — the gate chain
+     * read and name resolution are network calls, so concurrent RPC work stays bounded.
+     */
+    limit: <T>(fn: () => Promise<T>) => Promise<T>;
+    /** Per-peer rate gate for bundle-kind messages; `false` means over-rate this window. */
+    allowBundlePeer: (peer: string) => boolean;
+    /** Per-peer rate gate for root-kind messages (heartbeats are ~1 per 10 min when honest). */
+    allowRootPeer: (peer: string) => boolean;
+    /** Called after a fresh bundle is verified and merged (drives tally-update notifications). */
+    onAccept?: (cid: CID, bundle: VotesBundle, from: string) => void;
+    /**
+     * Called with every well-formed, within-rate root record (an unverifiable hint). NOT
+     * awaited — acting on a hint (the directed-bitswap chase) is lazy and bounded elsewhere,
+     * never on the validator's critical path.
+     */
+    onRootRecord?: (record: RootRecord, from: string) => void;
+    /** The criteria-derived cap for a bundle-kind message (see messages.ts). Over ⇒ reject. */
+    maxBundleMessageBytes: number;
+    /** The fixed cap for a root-kind message (~100 B record). Over ⇒ reject. */
+    maxRootMessageBytes: number;
+    /** Hard per-message validation deadline; on expiry the verdict is `ignore`. */
+    timeoutMs: number;
+}
+export interface GossipGate {
+    /** Validate one received message; the returned verdict maps to gossipsub accept/reject/ignore. */
+    validate(data: Uint8Array, from: string): Promise<MessageVerdict>;
+}
+export declare function makeGossipGate(deps: GossipGateDeps): GossipGate;

package/dist/transport/gossip-validator.js

@@ -0,0 +1,99 @@
+import { isCacheableVerdict } from "../verify/cache.js";
+/** Resolve `p`, or `onTimeout` if it does not settle within `ms`; a rejection also yields `onTimeout`. */
+function withDeadline(p, ms, onTimeout) {
+    return new Promise((resolve) => {
+        let settled = false;
+        const timer = setTimeout(() => {
+            if (!settled) {
+                settled = true;
+                resolve(onTimeout);
+            }
+        }, ms);
+        p.then((v) => {
+            if (!settled) {
+                settled = true;
+                clearTimeout(timer);
+                resolve(v);
+            }
+        }, () => {
+            if (!settled) {
+                settled = true;
+                clearTimeout(timer);
+                resolve(onTimeout);
+            }
+        });
+    });
+}
+export function makeGossipGate(deps) {
+    const { decodeMessage, parseBundle, verifier, isEvaluableNow, cache, acceptedDedup, admit, limit, allowBundlePeer, allowRootPeer, onAccept, onRootRecord, maxBundleMessageBytes, maxRootMessageBytes, timeoutMs } = deps;
+    async function doValidate(data, from) {
+        // Layer 1: size and decode — the cheapest, pre-verify checks.
+        if (data.length > Math.max(maxBundleMessageBytes, maxRootMessageBytes))
+            return "reject";
+        let message;
+        try {
+            message = decodeMessage(data);
+        }
+        catch {
+            return "reject"; // malformed bytes / not one of the two kinds — provable layer-1 badness
+        }
+        if (message.kind === "root") {
+            if (data.length > maxRootMessageBytes)
+                return "reject";
+            if (!allowRootPeer(from))
+                return "ignore";
+            // An unverifiable hint: forward within rate, hand to the (lazy, bounded) chase.
+            // Never `reject`ed on content — only equality with our own root is checkable.
+            onRootRecord?.(message.record, from);
+            return "accept";
+        }
+        if (data.length > maxBundleMessageBytes)
+            return "reject";
+        if (!allowBundlePeer(from))
+            return "ignore";
+        let cid;
+        let bundle;
+        try {
+            ({ cid, bundle } = await parseBundle(message.bundle));
+        }
+        catch {
+            return "reject"; // malformed bundle block bytes — provable
+        }
+        // A known bundle short-circuits on the verdict cache for the cost of one hash: a
+        // re-published valid bundle (e.g. a client refreshing its vote or re-announcing a
+        // withdrawal) is forwarded so late peers converge, without re-verifying or re-merging;
+        // a known-bad one rejects without work.
+        const cached = cache.get(cid);
+        if (cached)
+            return cached.valid ? "accept" : cached.disposition;
+        // Freshness guard (transient, so it runs here — not in the cacheable verifier — and
+        // its verdict is never cached): a bundle bucketed ahead of our head is not yet
+        // evaluable, so `ignore` it without penalty until our head advances. Also defuses an
+        // absurd-future `blockNumber` (e.g. uint256.max) — it never merges into the set.
+        if (isEvaluableNow && !(await isEvaluableNow(bundle)))
+            return "ignore";
+        // Re-sign flood guard: a same-bucket, same-choice re-sign of a vote we already accepted
+        // is inert under LWW, so drop it WITHOUT verifying (no gate read), merging, or
+        // forwarding — the anti-amplification win. Safe on the untrusted `address` because a
+        // hit only ever suppresses something an honest peer already forwarded.
+        if (acceptedDedup?.isResignDuplicate(bundle))
+            return "ignore";
+        const verdict = await limit(() => verifier.verify(bundle));
+        if (isCacheableVerdict(verdict))
+            cache.set(cid, verdict); // only terminal verdicts (accept / provable reject)
+        if (!verdict.valid)
+            return verdict.disposition;
+        await admit({ cid, bytes: message.bundle, bundle });
+        acceptedDedup?.record(bundle);
+        onAccept?.(cid, bundle, from);
+        return "accept";
+    }
+    return {
+        validate(data, from) {
+            // Whole-message deadline: an internal hang or slow RPC/name resolution yields
+            // `ignore`, never a stuck validator (which would strand the message in gossipsub's
+            // mcache).
+            return withDeadline(doValidate(data, from), timeoutMs, "ignore");
+        }
+    };
+}