@bitsocial/pubsub-votes 0.0.2

package/dist/transport/types.d.ts

@@ -0,0 +1,165 @@
+import type { CID } from "multiformats/cid";
+import type { PeerId } from "@libp2p/interface";
+import type { Helia } from "helia";
+import type { RootRecord } from "./messages.js";
+/**
+ * Transport interfaces. This is the ONLY part of the library that
+ * touches libp2p/helia. The core (schema/verify/crdt/tally) does not import it, so the
+ * engine is testable without a network.
+ *
+ * Three exchanges (see DESIGN.md "Transport"):
+ *   - pubsub: broadcast and receive **inline bundle deltas** and **root-record heartbeats**
+ *     (gossipsub), with a topic validator that drops invalid messages before the mesh
+ *     re-forwards them.
+ *   - fetch protocol: pull a connected peer's current root record on cold start / reconnect,
+ *     then union across peers so a single liar cannot hide a vote.
+ *   - directed bitswap: pull the checkpoint blocks behind an advertised root from the
+ *     connected peers that advertised it (through the blockstore) — the only bitswap use.
+ *
+ * The library does not start a node and does not take a host SDK. It receives the
+ * host's already-running **Helia node** directly (e.g. the value `createHelia` returns,
+ * which for a pkc-js host is `pkc.clients.libp2pJsClients[key]._helia`) and drives its
+ * libp2p pubsub + blockstore itself — there is no host-written adapter. The node must
+ * carry a gossipsub service at `libp2p.services.pubsub` and a usable `blockstore`;
+ * construction enforces both (see `requireHeliaServices` / `MissingPubsubError` /
+ * `MissingBlockstoreError`).
+ */
+/**
+ * Verdict from a gossipsub topic validator. Mirrors the semantics of libp2p's
+ * `TopicValidatorResult` (accept / reject / ignore) but is declared locally:
+ * `@libp2p/interface` 3.x no longer re-exports the pubsub types, so the
+ * implementation maps these onto whatever enum the host's gossipsub uses.
+ *   - "accept": valid; deliver to subscribers and let the mesh re-forward it.
+ *   - "reject": invalid; drop, do not forward, and penalize the sender's peer score.
+ *   - "ignore": drop and do not forward, without penalizing (well-formed but not useful).
+ */
+export type TopicValidatorResult = "accept" | "reject" | "ignore";
+/**
+ * The subset of a libp2p pubsub (gossipsub) service this library drives, declared
+ * structurally because `@libp2p/interface` 3.x no longer re-exports `PubSub`. Any
+ * gossipsub implementation the host registers at `services.pubsub` satisfies this
+ * (e.g. `@chainsafe/libp2p-gossipsub`). Kept minimal on purpose; the full transport
+ * (topic validators, fetch protocol) is design-only and may widen this as it lands.
+ */
+export interface PubsubService {
+    /**
+     * Broadcast bytes to a topic mesh. gossipsub resolves to `{ recipients }` — the peers it
+     * *directly sent the RPC to* at publish time (first-hop fan-out, filtered for send failures),
+     * NOT total network reach and NOT an acceptance confirmation (each recipient still runs the
+     * forward-gate). With the host's default `floodPublish`, that's every connected topic peer
+     * above the publish score threshold. Typed loosely (`recipients` optional) so a non-gossipsub
+     * pubsub still satisfies it; the transport reads `recipients?.length ?? 0`. Note gossipsub
+     * *rejects* with `NoPeersSubscribedToTopic` when it would send to zero peers unless the host
+     * sets `allowPublishToZeroTopicPeers`.
+     */
+    publish(topic: string, data: Uint8Array): Promise<{
+        recipients?: readonly PeerId[];
+    }>;
+    /** Join a topic; received messages arrive via the "message" event. */
+    subscribe(topic: string): void;
+    /** Leave a topic. */
+    unsubscribe(topic: string): void;
+    /** Peers we currently see subscribed to a topic, used to pick fetch targets. */
+    getSubscribers(topic: string): PeerId[];
+    addEventListener(type: "message", listener: (evt: {
+        detail: {
+            topic: string;
+            data: Uint8Array;
+            from?: PeerId;
+        };
+    }) => void): void;
+    removeEventListener(type: "message", listener: (evt: {
+        detail: {
+            topic: string;
+            data: Uint8Array;
+            from?: PeerId;
+        };
+    }) => void): void;
+    /**
+     * gossipsub's per-topic validator map. The transport installs the async forward-gate
+     * here (`topicValidators.set(topic, gate)`); gossipsub awaits the returned promise
+     * before re-forwarding the message to the mesh, which is what makes `reject` land on the
+     * sender for semantic invalidity. Optional because a non-gossipsub pubsub lacks it — the
+     * transport checks for it at `start()` and throws if absent. `@libp2p/gossipsub` exposes
+     * it as a mutable `Map`. See DESIGN.md "Transport".
+     */
+    topicValidators?: Map<string, GossipTopicValidator>;
+}
+/** A received pubsub message, as passed to a gossipsub topic validator. */
+export interface GossipMessage {
+    topic: string;
+    data: Uint8Array;
+    from?: PeerId;
+}
+/**
+ * A gossipsub topic validator: run on every received message BEFORE re-forwarding, returning
+ * (or resolving to) a {@link TopicValidatorResult}. Returning a promise makes the gate async —
+ * gossipsub awaits it, so the full fetch + verify pipeline can run before the message is
+ * forwarded (see DESIGN.md "Transport"). Declared structurally so the library imports no
+ * gossipsub package; `@libp2p/gossipsub`'s `TopicValidatorFn` satisfies it.
+ */
+export type GossipTopicValidator = (peer: PeerId, message: GossipMessage) => TopicValidatorResult | Promise<TopicValidatorResult>;
+/**
+ * The subset of the libp2p **fetch service** (`@libp2p/fetch`) this library drives,
+ * declared structurally so no runtime dependency on the package is needed. The host MUST
+ * register it at `libp2p.services.fetch`; construction throws `MissingFetchError`
+ * otherwise. Used for the root-record pull (see DESIGN.md "Checkpoints"): this library
+ * registers a lookup for its own key prefix (the responder) and fetches connected topic
+ * peers' records on cold start (the requester).
+ */
+export interface FetchServiceLike {
+    /** Request the value for `key` from a connected peer; nullish when the peer has none. */
+    fetch(peer: PeerId, key: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<Uint8Array | undefined | null>;
+    /**
+     * Register the responder for every key starting with `prefix`. `@libp2p/fetch` invokes the
+     * lookup with the requested key as **raw bytes** (`Uint8Array`), not a string — it matches the
+     * `prefix` against the utf8-decoded key but hands the callback the identifier bytes. The
+     * responder decodes them itself (see `PubsubVoter.#rootLookup`).
+     */
+    registerLookupFunction(prefix: string, lookup: (key: Uint8Array) => Promise<Uint8Array | undefined>): void;
+    /** Remove a registered responder (all of the prefix's, when `lookup` is omitted). */
+    unregisterLookupFunction(prefix: string, lookup?: (key: Uint8Array) => Promise<Uint8Array | undefined>): void;
+}
+/**
+ * The subset of a Helia blockstore this library drives, declared structurally. Vote
+ * bundles are content-addressed blocks fetched/stored by CID through it (bitswap
+ * retrieves through the blockstore). The full `Blocks` type carries progress-event
+ * generics we do not need here.
+ */
+export interface BlockstoreLike {
+    /** `options.signal` cancels an in-flight bitswap fetch — see the chase deadline (DESIGN.md "Checkpoints"). */
+    get(cid: CID, options?: {
+        signal?: AbortSignal;
+    }): Promise<Uint8Array>;
+    put(cid: CID, block: Uint8Array): Promise<CID>;
+    has(cid: CID): Promise<boolean>;
+}
+/**
+ * The host's running Helia node, as injected into {@link PubsubVoter}. Typed with the
+ * default libp2p `ServiceMap`, so `libp2p.services.pubsub` is `unknown` and cannot be
+ * trusted at compile time (a plain Helia node has no pubsub) — `requireHeliaServices`
+ * validates the gossipsub service and the blockstore at construction and narrows them.
+ */
+export type HeliaInstance = Helia;
+/** Live-delta propagation over pubsub (one inline bundle per message + root heartbeats). */
+export interface VoteTransport {
+    /**
+     * Subscribe to the topic and install the async validate-before-forward gate as the
+     * topic validator. See DESIGN.md "Transport: gossipsub topic + validation".
+     */
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    /**
+     * Publish one bundle's exact binary block bytes as a live delta (a new vote, a client
+     * re-publish, or a withdrawal). Resolves `recipientCount`: how many peers gossipsub sent the
+     * message directly to (see {@link PubsubService.publish} for what that number does and does not
+     * mean).
+     */
+    publishBundle(blockBytes: Uint8Array): Promise<{
+        recipientCount: number;
+    }>;
+    /** Publish a root-record heartbeat (see DESIGN.md "Checkpoints"). */
+    publishRootRecord(record: RootRecord): Promise<void>;
+}

package/dist/transport/types.js

@@ -0,0 +1 @@
+export {};

package/dist/verify/background.d.ts

@@ -0,0 +1,81 @@
+import type { CID } from "multiformats/cid";
+import type { VotesBundle } from "../schema/votes.js";
+import type { Criteria } from "../schema/criteria.js";
+import type { RuleRegistry } from "../rules/types.js";
+import type { ChainClient, BucketMath, NameResolver } from "../chain/types.js";
+import type { GateResultCache } from "./gate-result-cache.js";
+import { type NameResolutionCache } from "./name-resolution-cache.js";
+import type { VerdictCache } from "./cache.js";
+import type { VerifyFail } from "./types.js";
+/**
+ * The background chain verifier: runs the two deferred NETWORK checks — the on-chain gate
+ * (`rule` scores the wallet `> 0n` at the bucket block) and community-name resolution — for
+ * bundles that were admitted *provisionally* after the synchronous offline checks (signature +
+ * constraints). This is what makes a cold join non-blocking: the chase admits a checkpoint's
+ * bundles on offline validity alone (µs each), the first tally renders immediately with
+ * `chainVerified: false` rows, and this verifier confirms or evicts in the background (see
+ * DESIGN.md "Background chain verification").
+ *
+ * Batched, not sequential: a checkpoint's bundles share one bucket sample block, so the gate
+ * stage groups pending wallets per sample block and prefers the rule's `evaluateMany` (one
+ * multicall3 round trip for N wallets) over N serial `readContract` calls, falling back to
+ * `limit`-bounded per-wallet reads for rules without a batched form. Results feed the shared
+ * `(wallet, sampleBlock)` gate-result cache, and a settled bundle's terminal verdict feeds the
+ * shared per-CID verdict cache — so a later re-publish of the same bundle short-circuits at
+ * the gossip gate with zero chain work.
+ *
+ * Failure classes are kept apart, mirroring the forward-gate's `reject`/`ignore` split:
+ *   - gate scores `0n`            → EVICT + cache the provable `reject` (deterministic).
+ *   - name missing/mismatched     → EVICT, NOT cached (view-dependent `ignore`-class: v1
+ *                                   resolves at head — see verify/bundle.ts step 4).
+ *   - RPC / resolver THREW        → infra, nobody's verdict: the bundle STAYS pending, the
+ *                                   round retries with capped full-jitter backoff, and
+ *                                   `onError` surfaces the degraded state to the host
+ *                                   (Contest `error`) so "RPC down" is not silent.
+ *
+ * Pure seams, no libp2p import — unit-testable offline like the rest of the engine.
+ */
+/** One provisionally admitted bundle awaiting its deferred checks. */
+export interface PendingBundle {
+    cid: CID;
+    bundle: VotesBundle;
+}
+export interface BackgroundVerifierDeps {
+    criteria: Criteria;
+    registry: RuleRegistry;
+    chainFor: (ticker: string) => ChainClient;
+    bucketMath: BucketMath;
+    nameResolvers: NameResolver[];
+    /** Shared `(wallet, sampleBlock)` gate scores — batch results land here, hits skip the read. */
+    gateResultCache: GateResultCache;
+    /** Shared persistent name-resolution cache (pkc-js rule, 1h max-age); omitted ⇒ resolve live. */
+    nameResolutionCache?: NameResolutionCache;
+    /** The gate's per-CID verdict cache — a settled bundle's terminal verdict is stored here. */
+    cache: VerdictCache;
+    /** The bundle's gate read confirmed `> 0n` (flip `chainVerified`, kick the tally). */
+    onGateVerified: (cid: CID) => void;
+    /** The bundle's carried name resolved to its claimed publicKey (flip `nameResolved`). */
+    onNameResolved: (cid: CID) => void;
+    /** Remove a failed bundle from the working set (gate `0n`, or a name that did not check out). */
+    onEvict: (cid: CID, verdict: VerifyFail) => void;
+    /** An infra-class failure (RPC/resolver threw): the round will retry; surface the degradation. */
+    onError: (error: unknown) => void;
+    /** Concurrency cap for the un-batched fallbacks (per-wallet reads, name resolutions). */
+    limit: <T>(fn: () => Promise<T>) => Promise<T>;
+    /** Infra-retry backoff base / cap (ms). Full-jittered exponential between rounds. */
+    retryBaseMs?: number;
+    retryCapMs?: number;
+}
+export interface BackgroundChainVerifier {
+    /** Queue provisionally admitted bundles and return immediately; the drain runs detached. */
+    enqueue(entries: PendingBundle[]): void;
+    /** Bundles whose deferred checks have not settled yet (queued, in-flight, or awaiting retry). */
+    pendingCount(): number;
+    /** Resolves once every queued bundle has settled and no retry is armed (tests/introspection). */
+    idle(): Promise<void>;
+    /** Clear the retry timer (topic leave / voter destroy). Pending state is kept for `resume`. */
+    stop(): void;
+    /** Re-kick the drain after `stop()` if anything is still pending (topic re-join). */
+    resume(): void;
+}
+export declare function makeBackgroundVerifier(deps: BackgroundVerifierDeps): BackgroundChainVerifier;

package/dist/verify/background.js

@@ -0,0 +1,236 @@
+import { tickerForRef } from "../chain/ticker.js";
+import { UnknownRuleError } from "../errors.js";
+import { resolveNameThroughCache } from "./name-resolution-cache.js";
+const RETRY_BASE_MS = 2_000;
+const RETRY_CAP_MS = 60_000;
+export function makeBackgroundVerifier(deps) {
+    const { criteria, registry, chainFor, bucketMath, nameResolvers, gateResultCache, nameResolutionCache, cache, limit } = deps;
+    const retryBaseMs = deps.retryBaseMs ?? RETRY_BASE_MS;
+    const retryCapMs = deps.retryCapMs ?? RETRY_CAP_MS;
+    // Resolve the gate `rule`, its options, and its chain once (same shape as verify/bundle.ts).
+    // The re-binding after the guard keeps the non-undefined narrowing inside the closures below.
+    const maybeRule = registry[criteria.rule.type];
+    if (!maybeRule)
+        throw new UnknownRuleError("rule", criteria.rule.type);
+    const rule = maybeRule;
+    const ruleOptions = rule.optionsSchema.parse(criteria.rule);
+    const ruleChain = chainFor(tickerForRef(criteria, criteria.rule, ruleOptions));
+    const queue = [];
+    /** CIDs queued or in-flight, so a re-chased root cannot double-verify a bundle. */
+    const inFlight = new Set();
+    let draining = false;
+    let stopped = false;
+    /** Consecutive infra-failed rounds, driving the backoff exponent. */
+    let failedRounds = 0;
+    let retryTimer;
+    const idleResolvers = [];
+    function settle(item) {
+        inFlight.delete(item.cid.toString());
+    }
+    function maybeResolveIdle() {
+        if (queue.length === 0 && !draining && retryTimer === undefined) {
+            for (const resolve of idleResolvers.splice(0))
+                resolve();
+        }
+    }
+    /** The wallet's gate score at its bundle's bucket sample block. */
+    function sampleBlockFor(bundle) {
+        return bucketMath.sampleBlockForBucket(bucketMath.bucketForBlock(bundle.blockNumber));
+    }
+    /**
+     * Gate stage for one round's batch: group the not-yet-gated items per sample block, read the
+     * distinct uncached wallets — `evaluateMany` when the rule has it, `limit`-bounded singles
+     * otherwise — and feed every score into the shared gate-result cache. Throws on the FIRST
+     * infra failure: the round's unfinished items are re-queued by the caller.
+     */
+    async function gateStage(items) {
+        const groups = new Map();
+        for (const item of items) {
+            if (item.gateDone)
+                continue;
+            const block = sampleBlockFor(item.bundle);
+            groups.set(block, [...(groups.get(block) ?? []), item]);
+        }
+        for (const [sampleBlock, group] of groups) {
+            const wallets = [];
+            for (const item of group) {
+                const wallet = item.bundle.address;
+                if ((await gateResultCache.get(wallet, sampleBlock)) === undefined && !wallets.includes(wallet)) {
+                    wallets.push(wallet);
+                }
+            }
+            if (wallets.length > 0) {
+                const ctx = { chain: ruleChain, blockNumber: sampleBlock };
+                const results = rule.evaluateMany
+                    ? await rule.evaluateMany({ options: ruleOptions, walletAddresses: wallets, ctx })
+                    : await Promise.all(wallets.map((walletAddress) => limit(() => rule.evaluate({ options: ruleOptions, walletAddress, ctx }))));
+                wallets.forEach((wallet, i) => gateResultCache.set(wallet, sampleBlock, results[i].score));
+            }
+            for (const item of group) {
+                item.ruleScore = (await gateResultCache.get(item.bundle.address, sampleBlock));
+                item.gateDone = true;
+            }
+        }
+    }
+    /**
+     * Settle one gate-passed item's name checks. Resolutions are deduped per round via
+     * `resolutions`. Returns "verified" | "evicted"; throws on a resolver infra failure
+     * (the caller re-queues the item — its `gateDone` survives, so only names re-run).
+     */
+    async function nameStage(item, resolutions) {
+        for (const v of item.bundle.votes) {
+            const name = v.community.name;
+            if (!name || item.resolvedNames[name])
+                continue;
+            const resolver = nameResolvers.find((r) => r.canResolve({ name }));
+            if (!resolver) {
+                // `ignore`-class, view-dependent (a missing resolver differs per verifier) — evict,
+                // never cache (see verify/bundle.ts step 4).
+                deps.onEvict(item.cid, { valid: false, disposition: "ignore", reason: `no resolver handles community name "${name}"` });
+                return "evicted";
+            }
+            let resolution = resolutions.get(name);
+            if (!resolution) {
+                resolution = limit(() => resolveNameThroughCache({ resolver, name, cache: nameResolutionCache }));
+                resolutions.set(name, resolution);
+            }
+            const record = await resolution;
+            if (!record) {
+                deps.onEvict(item.cid, { valid: false, disposition: "ignore", reason: `community name "${name}" does not resolve` });
+                return "evicted";
+            }
+            if (record.publicKey !== v.community.publicKey) {
+                deps.onEvict(item.cid, {
+                    valid: false,
+                    disposition: "ignore",
+                    reason: `community name "${name}" resolves to ${record.publicKey}, not the claimed ${v.community.publicKey}`
+                });
+                return "evicted";
+            }
+            item.resolvedNames[name] = record.publicKey;
+        }
+        return "verified";
+    }
+    /** One drain round over everything currently queued. Re-queues + backs off on infra failure. */
+    async function round() {
+        const batch = queue.splice(0);
+        const requeue = [];
+        let infraError;
+        // Gate stage first, whole batch: this is where batching wins (one multicall per sample
+        // block instead of one read per wallet). An infra throw leaves every un-gated item intact.
+        try {
+            await gateStage(batch);
+        }
+        catch (error) {
+            infraError = error;
+        }
+        const resolutions = new Map();
+        for (const item of batch) {
+            if (!item.gateDone) {
+                requeue.push(item); // gate read never happened (infra) — retry the whole item
+                continue;
+            }
+            if (item.ruleScore === 0n) {
+                // Provable, deterministic reject — safe to cache so a re-publish short-circuits.
+                const verdict = {
+                    valid: false,
+                    disposition: "reject",
+                    reason: `not admitted: rule score is 0n at block ${sampleBlockFor(item.bundle)}`
+                };
+                cache.set(item.cid, verdict);
+                deps.onEvict(item.cid, verdict);
+                settle(item);
+                continue;
+            }
+            if (!item.gateNotified) {
+                item.gateNotified = true;
+                deps.onGateVerified(item.cid);
+            }
+            try {
+                if ((await nameStage(item, resolutions)) === "evicted") {
+                    settle(item);
+                    continue;
+                }
+            }
+            catch (error) {
+                infraError = error;
+                requeue.push(item); // gateDone survives — the retry only re-runs names
+                continue;
+            }
+            if (item.bundle.votes.some((v) => v.community.name))
+                deps.onNameResolved(item.cid);
+            // Fully settled: store the terminal valid verdict (same shape the forward-gate caches).
+            cache.set(item.cid, { valid: true, ruleScore: item.ruleScore, resolvedNames: item.resolvedNames });
+            settle(item);
+        }
+        if (requeue.length > 0) {
+            queue.push(...requeue);
+            failedRounds += 1;
+            deps.onError(infraError);
+            armRetry();
+        }
+        else {
+            failedRounds = 0;
+        }
+    }
+    function armRetry() {
+        if (stopped || retryTimer !== undefined)
+            return;
+        const ceiling = Math.min(retryCapMs, retryBaseMs * 2 ** (failedRounds - 1));
+        const timer = setTimeout(() => {
+            retryTimer = undefined;
+            kickDrain();
+        }, Math.random() * ceiling);
+        timer.unref?.();
+        retryTimer = timer;
+    }
+    function kickDrain() {
+        if (draining || stopped || queue.length === 0) {
+            maybeResolveIdle();
+            return;
+        }
+        draining = true;
+        void (async () => {
+            try {
+                // A round that infra-fails re-queues and arms the retry timer instead of spinning.
+                while (queue.length > 0 && !stopped && retryTimer === undefined)
+                    await round();
+            }
+            finally {
+                draining = false;
+                maybeResolveIdle();
+            }
+        })();
+    }
+    return {
+        enqueue(entries) {
+            for (const entry of entries) {
+                const key = entry.cid.toString();
+                if (inFlight.has(key))
+                    continue;
+                inFlight.add(key);
+                queue.push({ ...entry, gateDone: false, gateNotified: false, ruleScore: 0n, resolvedNames: {} });
+            }
+            kickDrain();
+        },
+        pendingCount() {
+            return inFlight.size;
+        },
+        idle() {
+            if (queue.length === 0 && !draining && retryTimer === undefined)
+                return Promise.resolve();
+            return new Promise((resolve) => idleResolvers.push(resolve));
+        },
+        stop() {
+            stopped = true;
+            if (retryTimer !== undefined)
+                clearTimeout(retryTimer);
+            retryTimer = undefined;
+            maybeResolveIdle();
+        },
+        resume() {
+            stopped = false;
+            kickDrain();
+        }
+    };
+}

package/dist/verify/bundle.d.ts

@@ -0,0 +1,58 @@
+import type { Criteria } from "../schema/criteria.js";
+import type { RuleRegistry } from "../rules/types.js";
+import type { ChainClient, BucketMath, NameResolver } from "../chain/types.js";
+import type { GateResultCache } from "./gate-result-cache.js";
+import { type NameResolutionCache } from "./name-resolution-cache.js";
+import type { BundleVerifier } from "./types.js";
+/**
+ * The full validity pipeline for one bundle — the work the gossip forward-gate runs before
+ * re-forwarding (see DESIGN.md "Transport"). Cheap-to-expensive with early exit so the
+ * costly network/chain steps only run for genuinely-new, signature-valid bundles:
+ *
+ *   1. signature   (local, µs): recover the EIP-712 signer, must equal `bundle.address`.
+ *   2. constraints (local, µs): `votes.length <= maxVotesPerAddress`, each vote in range.
+ *   3. gate        (chain):     the `rule` scores the wallet `> 0n` at the bucket block.
+ *                               `0n` -> not admitted -> drop.
+ *   4. name        (network):   each vote's `community.name` (if any) must resolve to the
+ *                               claimed `publicKey`; a squatted/absent name drops the bundle.
+ *
+ * Every step only ever SUBTRACTS trust (a bundle is valid or dropped), which is what lets the
+ * gate reject without forwarding. Weight *magnitude* is not computed here — it is a ranking
+ * concern the tally derives lazily, not a validity concern (see DESIGN.md "Tally").
+ *
+ * Expiry is deliberately out of scope here: it depends on the current bucket (a clock), so it
+ * is enforced by the CRDT's read-time filter (`current` drops decayed votes given the
+ * current bucket; `prune` bounds memory), not by this time-independent verifier.
+ */
+/** Everything the verifier needs, resolved once per contest. */
+export interface BundleVerifierDeps {
+    criteria: Criteria;
+    /** The criteria document's CID bytes (`(await criteriaCid(criteria)).bytes`) — signature binding. */
+    criteriaCid: Uint8Array;
+    /** The rule chain's numeric chainId (bound in the ballot domain). */
+    chainId: number;
+    /** Resolved rule registry (built-ins + host overrides). */
+    registry: RuleRegistry;
+    /** Resolve a chain ticker (e.g. "base") to its viem client. */
+    chainFor: (ticker: string) => ChainClient;
+    /** Bucket math for `criteria.blocksPerBucket`. */
+    bucketMath: BucketMath;
+    /** Host-injected community-name resolvers (`PubsubVoterOptions.nameResolvers`). */
+    nameResolvers: NameResolver[];
+    /**
+     * Optional cache of gate results, keyed by `(wallet, sampleBlock)`. When present, a wallet's
+     * score at a bucket's sample block is read from chain at most once — a `0n` miss short-circuits
+     * a flood of fresh-signed bundles from an ineligible wallet, and a `> 0n` hit short-circuits an
+     * *eligible* wallet re-signing or cycling choices within a bucket. Both are deterministic,
+     * historical reads. Omitted ⇒ every novel bundle pays its own gate read (prior behaviour).
+     */
+    gateResultCache?: GateResultCache;
+    /**
+     * Optional persistent cache of name resolutions (the pkc-js rule — see
+     * verify/name-resolution-cache.ts). When present, a carried name is resolved live at most
+     * once per {@link NAME_RESOLUTION_MAX_AGE_SECONDS} per resolver. Omitted ⇒ every verify
+     * resolves live (prior behaviour; unit tests).
+     */
+    nameResolutionCache?: NameResolutionCache;
+}
+export declare function makeBundleVerifier(deps: BundleVerifierDeps): BundleVerifier;

package/dist/verify/bundle.js

@@ -0,0 +1,84 @@
+import { tickerForRef } from "../chain/ticker.js";
+import { UnknownRuleError } from "../errors.js";
+import { verifyBundleSignature } from "./signature.js";
+import { checkBundleConstraints } from "./constraints.js";
+import { resolveNameThroughCache } from "./name-resolution-cache.js";
+export function makeBundleVerifier(deps) {
+    const { criteria, criteriaCid, chainId, registry, chainFor, bucketMath, nameResolvers, gateResultCache, nameResolutionCache } = deps;
+    // Resolve the gate `rule`, its options, and its chain client once. The rule reads at the
+    // bundle's bucket block, but which rule/chain to use is fixed by the criteria, so it need
+    // not be recomputed per bundle.
+    const rule = registry[criteria.rule.type];
+    if (!rule)
+        throw new UnknownRuleError("rule", criteria.rule.type);
+    const ruleOptions = rule.optionsSchema.parse(criteria.rule);
+    const ruleChain = chainFor(tickerForRef(criteria, criteria.rule, ruleOptions));
+    // Stage 1, shared by `verify` and `verifyOffline`: signature + constraints, local and µs.
+    const verifyOffline = async (bundle) => {
+        // 1. Signature (free) — a forged/tampered bundle drops before any chain/network read.
+        const signature = await verifyBundleSignature({ bundle, criteriaCid, chainId });
+        if (!signature.valid)
+            return signature;
+        // 2. Criteria constraints (free) — cap + vote range.
+        return checkBundleConstraints(bundle, criteria);
+    };
+    return {
+        verifyOffline,
+        async verify(bundle) {
+            const offline = await verifyOffline(bundle);
+            if (!offline.valid)
+                return offline;
+            // 3. Gate (chain) — read the `rule` at the bucket's sample block. The score is a pure
+            //    function of a pinned historical block, so it is memoized per `(wallet, sampleBlock)`:
+            //    a cache hit short-circuits the chain read for a flood of fresh-signed bundles from
+            //    the same wallet, whether it is ineligible (`0n`, a `reject`) or eligible (`> 0n`,
+            //    re-signing / cycling choices within one bucket).
+            const sampleBlock = bucketMath.sampleBlockForBucket(bucketMath.bucketForBlock(bundle.blockNumber));
+            let score = await gateResultCache?.get(bundle.address, sampleBlock);
+            if (score === undefined) {
+                ({ score } = await rule.evaluate({
+                    options: ruleOptions,
+                    walletAddress: bundle.address,
+                    ctx: { chain: ruleChain, blockNumber: sampleBlock }
+                }));
+                gateResultCache?.set(bundle.address, sampleBlock, score);
+            }
+            if (score === 0n) {
+                return { valid: false, disposition: "reject", reason: `not admitted: rule score is 0n at block ${sampleBlock}` };
+            }
+            // 4. Community-name resolution (network) — a carried name is a claim, verified against
+            //    the registry. A name that has no resolver, does not resolve, or resolves to a
+            //    different publicKey than the vote claims drops the whole bundle. These failures
+            //    are `ignore`, not `reject`: v1 resolves at head, so they are view-/clock-dependent
+            //    (a missing resolver differs per verifier; a re-point produces a transient window
+            //    where honest peers disagree — see DESIGN.md "Tally"/"Open questions"). Penalizing
+            //    the sender for that would punish honest relayers; the drop still stops propagation.
+            //    (Once pinned-block resolution lands, a steady-state mismatch becomes provable
+            //    `reject`.) The gossip gate therefore does NOT cache these verdicts. Successful
+            //    resolutions DO go through the shared name-resolution cache (the pkc-js rule,
+            //    1-hour max-age) — bounding the RPC cost, while a re-point is still honored
+            //    within the hour and a failed resolution is never negatively cached.
+            const resolvedNames = {};
+            for (const v of bundle.votes) {
+                const name = v.community.name;
+                if (!name)
+                    continue;
+                const resolver = nameResolvers.find((r) => r.canResolve({ name }));
+                if (!resolver)
+                    return { valid: false, disposition: "ignore", reason: `no resolver handles community name "${name}"` };
+                const record = await resolveNameThroughCache({ resolver, name, cache: nameResolutionCache });
+                if (!record)
+                    return { valid: false, disposition: "ignore", reason: `community name "${name}" does not resolve` };
+                if (record.publicKey !== v.community.publicKey) {
+                    return {
+                        valid: false,
+                        disposition: "ignore",
+                        reason: `community name "${name}" resolves to ${record.publicKey}, not the claimed ${v.community.publicKey}`
+                    };
+                }
+                resolvedNames[name] = record.publicKey;
+            }
+            return { valid: true, ruleScore: score, resolvedNames };
+        }
+    };
+}