@bitsocial/pubsub-voting 0.0.6

package/dist/errors.js

@@ -0,0 +1,126 @@
+/**
+ * Library error types.
+ *
+ * The engine and client lifecycle are implemented — schemas, encoding, topic derivation,
+ * the verify pipeline, the LWW winner-set CRDT, the tally, the transport's
+ * validate-before-forward gossip gate, and the reactive `PubsubVoter` / `Contest` / `ContestVote`
+ * facade. Republishing a live vote is the client's job (no scheduler, no persistence); see
+ * DESIGN.md "Republishing is the client's job".
+ */
+/** Thrown by any facade path deferred to a later version (none in v1's shipped surface). */
+export class NotImplementedError extends Error {
+    constructor(what) {
+        super(`${what} is not implemented yet. See DESIGN.md / ROADMAP.md.`);
+        this.name = "NotImplementedError";
+    }
+}
+/**
+ * Thrown when a criteria document names a rule `type` this client does not
+ * implement (in the `rule`/`weight` slot or in `requires.rules`). A
+ * client that hits this is too old (or missing a host override) and must recuse
+ * itself from the contest rather than miscount. See DESIGN.md "Rules".
+ */
+export class UnknownRuleError extends Error {
+    slot;
+    type;
+    constructor(slot, type) {
+        super(`Unknown rule "${type}" referenced by the criteria ${slot}. This client does not ` +
+            `implement it; pass it via the \`rules\` option to shadow/extend the built-ins, ` +
+            `or recuse this contest. Built-ins: see registry.ts.`);
+        this.slot = slot;
+        this.type = type;
+        this.name = "UnknownRuleError";
+    }
+}
+/**
+ * Thrown at construction when the injected Helia node's libp2p has no usable pubsub
+ * (gossipsub) service at `libp2p.services.pubsub`. The library broadcasts and receives
+ * winner bundle CIDs over gossipsub, so a node without it cannot participate. Helia's default
+ * libp2p services do NOT include pubsub — the host must register a gossipsub service
+ * (e.g. `@chainsafe/libp2p-gossipsub`) before passing the node in. We fail fast here
+ * rather than letting a later `publish`/`subscribe` fail obscurely. See DESIGN.md
+ * "Transport".
+ */
+export class MissingPubsubError extends Error {
+    constructor() {
+        super("The injected Helia node's libp2p has no usable pubsub service at " +
+            "`libp2p.services.pubsub`. This library needs a gossipsub service to broadcast " +
+            "and receive votes. Register one before constructing PubsubVoter (Helia's " +
+            "default services do not include pubsub; e.g. add `@chainsafe/libp2p-gossipsub` " +
+            "as `services.pubsub`). See DESIGN.md \"Transport\".");
+        this.name = "MissingPubsubError";
+    }
+}
+/**
+ * Thrown at construction when the injected Helia node has no usable `blockstore`. Vote
+ * bundles are immutable content-addressed blocks fetched by CID through the host's
+ * blockstore (bitswap retrieves through it), so the engine cannot resolve a bundle without
+ * one. Note "bitswap" is not a separately introspectable property of a Helia node — it
+ * is a block broker wired *beneath* `blockstore` — so the checkable guarantee is a
+ * well-formed blockstore, the surface bitswap retrieves through. See DESIGN.md
+ * "Transport".
+ */
+export class MissingBlockstoreError extends Error {
+    constructor() {
+        super("The injected Helia node has no usable `blockstore`. This library fetches vote " +
+            "bundles by CID through it (bitswap retrieves through the blockstore), so a " +
+            "node without one cannot resolve votes. Pass a full Helia instance (e.g. the " +
+            "result of `createHelia`). See DESIGN.md \"Transport\".");
+        this.name = "MissingBlockstoreError";
+    }
+}
+/**
+ * Thrown at construction when the injected Helia node's libp2p has no usable **fetch
+ * service** at `libp2p.services.fetch`. The root-record pull — cold-start / reconnect
+ * checkpoint sync — rides the libp2p fetch protocol (this library registers its own lookup
+ * and runs its own requester), so the host must register `@libp2p/fetch` on the shared
+ * node. See DESIGN.md "Checkpoints" and "Deferred pkc-js work".
+ */
+export class MissingFetchError extends Error {
+    constructor() {
+        super("The injected Helia node's libp2p has no usable fetch service at " +
+            "`libp2p.services.fetch`. This library pulls peers' checkpoint root records " +
+            "over the libp2p fetch protocol on cold start, so the service is required. " +
+            "Register `@libp2p/fetch` as `services.fetch` before constructing PubsubVoter. " +
+            "See DESIGN.md \"Checkpoints\".");
+        this.name = "MissingFetchError";
+    }
+}
+/**
+ * Thrown once a voter has been `destroy()`ed and something tries to keep using it. Unlike `stop()`
+ * (which leaves every topic but keeps the client reusable), `destroy()` is terminal: every contest
+ * is stopped and can no longer update or publish. Surfaced by `createContest` / `createContestVote`,
+ * and by a pre-existing `Contest.update()` / `ContestVote.publish()`. Construct a new
+ * `PubsubVoter` to participate again.
+ */
+export class VoterDestroyedError extends Error {
+    constructor() {
+        super("This voter has been destroyed: its contests are stopped and can no longer update or " +
+            "publish. `destroy()` is terminal (unlike the reusable `stop()`). Construct a new " +
+            "PubsubVoter to participate again.");
+        this.name = "VoterDestroyedError";
+    }
+}
+/**
+ * Thrown by `deriveDirectoryCriteria` when two manifest entries derive the same `contestId`.
+ * One directory slot decided by two topics is an authoring bug in the manifest: either the
+ * duplicate entry is a copy-paste mistake, or the slot's electorate would be split.
+ */
+export class DuplicateContestIdError extends Error {
+    contestId;
+    constructor(contestId) {
+        super(`Directory manifest derives contestId "${contestId}" twice. Each directory slot must ` +
+            `be decided by exactly one contest (one criteria document, one topic); remove or ` +
+            `rename the duplicate entry.`);
+        this.contestId = contestId;
+        this.name = "DuplicateContestIdError";
+    }
+}
+/** Thrown when a publish (vote/withdraw) is attempted on a voter constructed without a signer. */
+export class ReadOnlyError extends Error {
+    constructor() {
+        super("This voter is read-only: it was constructed without a `signer`. " +
+            "Provide a VoteSigner to publish or withdraw votes; reading tallies needs no signer.");
+        this.name = "ReadOnlyError";
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Public entry.
+ *
+ * The engine is implemented and unit-tested: the zod schemas, canonical dag-cbor encoding,
+ * topic derivation, the verify pipeline (signature + constraints +
+ * gate + name resolution), the state-based grow-only LWW winner-set CRDT, the tally, and the
+ * transport's validate-before-forward gossip gate. The public facade is the reactive
+ * `PubsubVoter` / `Contest` (`createContest`) / `ContestVote` (`createContestVote`) trio. Keeping a
+ * live vote from decaying is the consuming client's job — this library publishes each vote once
+ * (see `republishIntervalBuckets` and DESIGN.md "Republishing is the client's job"). See DESIGN.md
+ * for architecture, and "Transport" for the forward-gate that verifies a bundle (signature,
+ * on-chain gate, community-name resolution) before gossipsub re-forwards it.
+ */
+export * from "./schema/common.js";
+export * from "./schema/votes.js";
+export * from "./schema/criteria.js";
+export * from "./schema/directory.js";
+export * from "./rules/erc721-min-balance.js";
+export * from "./rules/constant.js";
+export * from "./rules/registry.js";
+export * from "./encoding/canonical.js";
+export * from "./topic.js";
+export * from "./errors.js";
+export * from "./client/voter.js";
+export * from "./signer/eip712.js";
+export type { VoteSigner } from "./signer/types.js";
+export type * from "./rules/types.js";
+export type * from "./chain/types.js";
+export type * from "./verify/types.js";
+export type * from "./crdt/types.js";
+export type * from "./transport/types.js";
+export type * from "./tally/types.js";

package/dist/index.js

@@ -0,0 +1,43 @@
+/**
+ * Public entry.
+ *
+ * The engine is implemented and unit-tested: the zod schemas, canonical dag-cbor encoding,
+ * topic derivation, the verify pipeline (signature + constraints +
+ * gate + name resolution), the state-based grow-only LWW winner-set CRDT, the tally, and the
+ * transport's validate-before-forward gossip gate. The public facade is the reactive
+ * `PubsubVoter` / `Contest` (`createContest`) / `ContestVote` (`createContestVote`) trio. Keeping a
+ * live vote from decaying is the consuming client's job — this library publishes each vote once
+ * (see `republishIntervalBuckets` and DESIGN.md "Republishing is the client's job"). See DESIGN.md
+ * for architecture, and "Transport" for the forward-gate that verifies a bundle (signature,
+ * on-chain gate, community-name resolution) before gossipsub re-forwards it.
+ */
+// Schemas (runtime values) and their inferred types.
+export * from "./schema/common.js";
+export * from "./schema/votes.js";
+export * from "./schema/criteria.js";
+// Directory authoring: derive per-contest criteria documents from a defaults+contests
+// manifest. Pure and offline; exported so every consumer (web client, seeder) shares the
+// exact merge semantics — byte-identical documents are what make peers share a topic.
+export * from "./schema/directory.js";
+// Rules: a single kind, one file per `type`, each owning its option schema and an
+// `evaluate` returning `{ score: bigint }` (the `rule` slot gates on `score > 0n`,
+// the weight slot uses the magnitude), plus the registry (built-ins, the host-shadowing resolver, and criteria
+// validation). The leaf rules read through the injected viem `PublicClient`
+// (`ctx.chain`). Rule composition (combining several into one slot) is a
+// documented future extension, not a built-in — see DESIGN.md "Future improvements".
+// v1 ships the NFT path only: `erc721-min-balance` + `constant`. `erc20-balance` stays in
+// the tree but is not registered or re-exported — see ROADMAP.md ("Deferred").
+export * from "./rules/erc721-min-balance.js";
+export * from "./rules/constant.js";
+export * from "./rules/registry.js";
+// Implemented runtime: encoding, topic, errors, identity seam, facade.
+export * from "./encoding/canonical.js";
+export * from "./topic.js";
+export * from "./errors.js";
+export * from "./client/voter.js";
+// There is no library-side vote persistence: republishing a live vote is the client's job, so
+// the client tracks what it voted for (see DESIGN.md "Republishing is the client's job"). The
+// facade exports `republishIntervalBuckets` to help the client schedule its own refreshes.
+// Identity seam: the EIP-712 ballot builder + constants a host needs to implement a
+// signer, plus the signer interface itself.
+export * from "./signer/eip712.js";

package/dist/rules/constant.d.ts

@@ -0,0 +1,14 @@
+import { z } from "zod";
+import type { Rule } from "./types.js";
+/**
+ * A fixed score for every wallet. v1.
+ *
+ * In the weight slot this is "1 pass = 1 vote" (`value: 1`). In the rule slot a
+ * positive `value` admits everyone (a no-op gate). No chain read.
+ */
+export declare const ConstantOptionsSchema: z.ZodObject<{
+    type: z.ZodLiteral<"constant">;
+    value: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+export type ConstantOptions = z.infer<typeof ConstantOptionsSchema>;
+export declare const constant: Rule<ConstantOptions>;

package/dist/rules/constant.js

@@ -0,0 +1,18 @@
+import { z } from "zod";
+/**
+ * A fixed score for every wallet. v1.
+ *
+ * In the weight slot this is "1 pass = 1 vote" (`value: 1`). In the rule slot a
+ * positive `value` admits everyone (a no-op gate). No chain read.
+ */
+export const ConstantOptionsSchema = z.object({
+    type: z.literal("constant"),
+    value: z.number().int().positive().default(1)
+});
+export const constant = {
+    type: "constant",
+    optionsSchema: ConstantOptionsSchema,
+    async evaluate({ options }) {
+        return { score: BigInt(options.value) };
+    }
+};

package/dist/rules/erc20-balance.d.ts

@@ -0,0 +1,30 @@
+import { z } from "zod";
+import type { Rule } from "./types.js";
+/**
+ * Score by ERC-20 balance (for example BSO). Reserved for the pass + BSO combo path.
+ *
+ * Score = the wallet's raw balance (base units) at the bucket block if it meets `min`,
+ * else 0n. `min` (in whole tokens, default 0) is what lets this single rule serve
+ * BOTH slots: in the weight slot leave `min` at 0 and the score is the magnitude; in the
+ * rule slot set `min` and a wallet below it scores 0n (rejected).
+ *
+ * The score is the exact `bigint` viem returns — no `Number()` cast, no precision loss.
+ * We deliberately do NOT divide by `decimals`: that divide is monotonic, so it never
+ * changes the ranking, and doing it in a JS `number` is exactly what used to lose
+ * precision. `decimals` is retained only to convert `min` (whole tokens) to base units
+ * via viem `parseUnits`, so the gate compares like-for-like. The score's absolute
+ * magnitude is therefore base units; formatting to whole tokens for display is a caller
+ * concern (`viem.formatUnits`). See DESIGN.md "Rules".
+ *
+ * (Edge: `min` is a normal token threshold. A `min` large enough that `.toString()`
+ * yields scientific notation would break `parseUnits` — out of scope for real thresholds.)
+ */
+export declare const Erc20BalanceOptionsSchema: z.ZodObject<{
+    type: z.ZodLiteral<"erc20-balance">;
+    chain: z.ZodString;
+    contract: z.ZodString;
+    decimals: z.ZodDefault<z.ZodNumber>;
+    min: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+export type Erc20BalanceOptions = z.infer<typeof Erc20BalanceOptionsSchema>;
+export declare const erc20Balance: Rule<Erc20BalanceOptions>;

package/dist/rules/erc20-balance.js

@@ -0,0 +1,44 @@
+import { erc20Abi, getAddress, parseUnits } from "viem";
+import { z } from "zod";
+import { ChainTickerSchema } from "../schema/common.js";
+/**
+ * Score by ERC-20 balance (for example BSO). Reserved for the pass + BSO combo path.
+ *
+ * Score = the wallet's raw balance (base units) at the bucket block if it meets `min`,
+ * else 0n. `min` (in whole tokens, default 0) is what lets this single rule serve
+ * BOTH slots: in the weight slot leave `min` at 0 and the score is the magnitude; in the
+ * rule slot set `min` and a wallet below it scores 0n (rejected).
+ *
+ * The score is the exact `bigint` viem returns — no `Number()` cast, no precision loss.
+ * We deliberately do NOT divide by `decimals`: that divide is monotonic, so it never
+ * changes the ranking, and doing it in a JS `number` is exactly what used to lose
+ * precision. `decimals` is retained only to convert `min` (whole tokens) to base units
+ * via viem `parseUnits`, so the gate compares like-for-like. The score's absolute
+ * magnitude is therefore base units; formatting to whole tokens for display is a caller
+ * concern (`viem.formatUnits`). See DESIGN.md "Rules".
+ *
+ * (Edge: `min` is a normal token threshold. A `min` large enough that `.toString()`
+ * yields scientific notation would break `parseUnits` — out of scope for real thresholds.)
+ */
+export const Erc20BalanceOptionsSchema = z.object({
+    type: z.literal("erc20-balance"),
+    chain: ChainTickerSchema,
+    contract: z.string(),
+    decimals: z.number().int().nonnegative().default(18),
+    min: z.number().nonnegative().default(0)
+});
+export const erc20Balance = {
+    type: "erc20-balance",
+    optionsSchema: Erc20BalanceOptionsSchema,
+    async evaluate({ options, walletAddress, ctx }) {
+        const raw = await ctx.chain.readContract({
+            address: getAddress(options.contract),
+            abi: erc20Abi,
+            functionName: "balanceOf",
+            args: [getAddress(walletAddress)],
+            blockNumber: BigInt(ctx.blockNumber)
+        });
+        const minUnits = parseUnits(options.min.toString(), options.decimals);
+        return { score: raw >= minUnits ? raw : 0n };
+    }
+};

package/dist/rules/erc721-min-balance.d.ts

@@ -0,0 +1,18 @@
+import { z } from "zod";
+import type { Rule } from "./types.js";
+/**
+ * Hold at least `min` of an ERC-721 (the 5chan Pass). v1.
+ *
+ * Score = the wallet's holding at the bucket block if it meets `min`, else 0. In the
+ * rule slot, `> 0` admits the wallet (it holds the Pass); in the weight slot it
+ * weights by the number of Passes held. The body reads its own `balanceOf` via the
+ * injected viem client (no libp2p/helia import), unit-testable against a stubbed client.
+ */
+export declare const Erc721MinBalanceOptionsSchema: z.ZodObject<{
+    type: z.ZodLiteral<"erc721-min-balance">;
+    chain: z.ZodString;
+    contract: z.ZodString;
+    min: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+export type Erc721MinBalanceOptions = z.infer<typeof Erc721MinBalanceOptionsSchema>;
+export declare const erc721MinBalance: Rule<Erc721MinBalanceOptions>;

package/dist/rules/erc721-min-balance.js

@@ -0,0 +1,100 @@
+import { erc721Abi, getAddress } from "viem";
+import { z } from "zod";
+import { CHAIN_CHUNK_RETRY_DELAY_MS, CHAIN_MULTICALL_CONCURRENCY, CHAIN_READS_PER_MULTICALL } from "../chain/coalescer.js";
+import { ChainTickerSchema } from "../schema/common.js";
+/**
+ * Hold at least `min` of an ERC-721 (the 5chan Pass). v1.
+ *
+ * Score = the wallet's holding at the bucket block if it meets `min`, else 0. In the
+ * rule slot, `> 0` admits the wallet (it holds the Pass); in the weight slot it
+ * weights by the number of Passes held. The body reads its own `balanceOf` via the
+ * injected viem client (no libp2p/helia import), unit-testable against a stubbed client.
+ */
+export const Erc721MinBalanceOptionsSchema = z.object({
+    type: z.literal("erc721-min-balance"),
+    chain: ChainTickerSchema,
+    contract: z.string(),
+    min: z.number().int().positive().default(1)
+});
+/** Score from one balance: the holding when it meets `min`, else `0n` (does not qualify). */
+function scoreOf(balance, min) {
+    return balance >= BigInt(min) ? balance : 0n;
+}
+/**
+ * Chunking policy shared with the voter-level read coalescer (src/chain/coalescer.ts). viem's
+ * own default chunking (1,024 bytes of calldata ≈ 27 `balanceOf`s) would split a 1000-wallet
+ * batch into ~38 chunks and fire them ALL concurrently — a burst public RPC endpoints throttle
+ * (measured against `mainnet.base.org`: 33/38 requests answered HTTP 429 `-32016 over rate
+ * limit` and the batch never settled). 200 reads is ~45 KB of calldata and ~2–5M `eth_call`
+ * gas — inside public request-size and gas caps — so a 1000-wallet batch is 5 round trips.
+ * The in-flight bound here is per evaluateMany call; the coalescer additionally enforces the
+ * same budget globally across parallel contests (its wrapped `multicall` is what this rule's
+ * batched path runs through).
+ */
+const READS_PER_MULTICALL = CHAIN_READS_PER_MULTICALL;
+const MULTICALL_CONCURRENCY = CHAIN_MULTICALL_CONCURRENCY;
+const CHUNK_RETRY_DELAY_MS = CHAIN_CHUNK_RETRY_DELAY_MS;
+export const erc721MinBalance = {
+    type: "erc721-min-balance",
+    optionsSchema: Erc721MinBalanceOptionsSchema,
+    async evaluate({ options, walletAddress, ctx }) {
+        const balance = await ctx.chain.readContract({
+            address: getAddress(options.contract),
+            abi: erc721Abi,
+            functionName: "balanceOf",
+            args: [getAddress(walletAddress)],
+            blockNumber: BigInt(ctx.blockNumber)
+        });
+        return { score: scoreOf(balance, options.min) };
+    },
+    async evaluateMany({ options, walletAddresses, ctx }) {
+        const contract = getAddress(options.contract);
+        // Multicall3 `aggregate3` batching — the path the background chain verifier rides on a
+        // cold join. The wallets are chunked HERE (`READS_PER_MULTICALL` per aggregate3,
+        // `batchSize: 0` disables viem's own 1KB re-chunking) and the chunks are sent with
+        // bounded concurrency plus one in-rule retry each, so a big batch is a handful of
+        // polite round trips rather than a ~40-request burst a public endpoint throttles —
+        // and one failed chunk never discards the others' results. Needs the client to know
+        // its chain's multicall3 deployment; a client built without a `chain` (or on a chain
+        // without multicall3) takes the per-wallet fallback below.
+        if (typeof ctx.chain.multicall === "function" && ctx.chain.chain?.contracts?.multicall3) {
+            const chunks = [];
+            for (let at = 0; at < walletAddresses.length; at += READS_PER_MULTICALL) {
+                chunks.push(walletAddresses.slice(at, at + READS_PER_MULTICALL));
+            }
+            const results = new Array(walletAddresses.length);
+            const readChunk = async (chunk) => ctx.chain.multicall({
+                contracts: chunk.map((wallet) => ({
+                    address: contract,
+                    abi: erc721Abi,
+                    functionName: "balanceOf",
+                    args: [getAddress(wallet)]
+                })),
+                allowFailure: false,
+                batchSize: 0,
+                blockNumber: BigInt(ctx.blockNumber)
+            });
+            let nextChunk = 0;
+            const worker = async () => {
+                while (nextChunk < chunks.length) {
+                    const index = nextChunk++;
+                    const chunk = chunks[index];
+                    let balances;
+                    try {
+                        balances = await readChunk(chunk);
+                    }
+                    catch {
+                        await new Promise((resolve) => setTimeout(resolve, CHUNK_RETRY_DELAY_MS));
+                        balances = await readChunk(chunk);
+                    }
+                    for (let i = 0; i < chunk.length; i++) {
+                        results[index * READS_PER_MULTICALL + i] = { score: scoreOf(balances[i], options.min) };
+                    }
+                }
+            };
+            await Promise.all(Array.from({ length: Math.min(MULTICALL_CONCURRENCY, chunks.length) }, worker));
+            return results;
+        }
+        return Promise.all(walletAddresses.map((walletAddress) => this.evaluate({ options, walletAddress, ctx })));
+    }
+};

package/dist/rules/registry.d.ts

@@ -0,0 +1,42 @@
+import type { Criteria } from "../schema/criteria.js";
+import type { RuleRegistry } from "./types.js";
+/**
+ * The rule registry: builtins, the shadowing resolver, and criteria validation.
+ *
+ * One flat `type -> rule` map (single kind; see types.ts), mirroring the pkc-js
+ * challenge registry (`pkc?.settings?.challenges?.[name] ?? pkcJsChallenges[name]`): a
+ * host's overrides shadow built-ins by `type`, so clients like 5chan or seedit register
+ * custom rules by passing `{ "their-type": rule }` to `PubsubVoter` without
+ * forking this library. A custom `type` becomes part of the criteria bytes, so it is
+ * provably pinned to the topic it runs on. Both criteria slots (rule, weight) draw
+ * from this single registry.
+ */
+/**
+ * The library's built-in rules, before any host override.
+ *
+ * v1 ships exactly the NFT path: `erc721-min-balance` (Pass gate) + `constant` weight.
+ * `erc20-balance` is intentionally NOT registered — it stays in the tree (`erc20-balance.ts`,
+ * unit-tested) as the design-open weight path, but is unshipped so a criteria naming it
+ * recuses via `UnknownRuleError` rather than silently enabling token-weighting. See
+ * ROADMAP.md ("Deferred") for when it re-ships.
+ */
+export declare const builtinRegistry: RuleRegistry;
+/** type ids the v1 implementation guarantees; checked against `requires.rules`. */
+export declare const V1_BUILTIN_RULE_TYPES: readonly ["erc721-min-balance", "constant"];
+/**
+ * Merge host overrides over the built-ins. Overrides shadow built-ins by `type`. The
+ * override map is a plain `RuleRegistry` (a flat record already allows any subset
+ * of `type`s), so a host passes only the rules it adds or replaces.
+ */
+export declare function resolveRegistry(overrides?: RuleRegistry): RuleRegistry;
+/**
+ * Validate a criteria document against a resolved registry: the `rule` and
+ * `weight` refs must name rules this registry implements, their options must
+ * parse against the rule's own schema, and every name in `requires.rules`
+ * must be resolvable (so an out-of-date client recuses itself instead of miscounting).
+ *
+ * Throws `UnknownRuleError` / a zod error on the first failure. This is a check,
+ * not a transform: it never mutates `criteria`, so the topic-bearing bytes are untouched
+ * (option defaults applied here do not leak back into the encoded criteria).
+ */
+export declare function validateCriteriaRules(criteria: Criteria, registry: RuleRegistry): void;

package/dist/rules/registry.js

@@ -0,0 +1,61 @@
+import { UnknownRuleError } from "../errors.js";
+import { erc721MinBalance } from "./erc721-min-balance.js";
+import { constant } from "./constant.js";
+/**
+ * The rule registry: builtins, the shadowing resolver, and criteria validation.
+ *
+ * One flat `type -> rule` map (single kind; see types.ts), mirroring the pkc-js
+ * challenge registry (`pkc?.settings?.challenges?.[name] ?? pkcJsChallenges[name]`): a
+ * host's overrides shadow built-ins by `type`, so clients like 5chan or seedit register
+ * custom rules by passing `{ "their-type": rule }` to `PubsubVoter` without
+ * forking this library. A custom `type` becomes part of the criteria bytes, so it is
+ * provably pinned to the topic it runs on. Both criteria slots (rule, weight) draw
+ * from this single registry.
+ */
+/**
+ * The library's built-in rules, before any host override.
+ *
+ * v1 ships exactly the NFT path: `erc721-min-balance` (Pass gate) + `constant` weight.
+ * `erc20-balance` is intentionally NOT registered — it stays in the tree (`erc20-balance.ts`,
+ * unit-tested) as the design-open weight path, but is unshipped so a criteria naming it
+ * recuses via `UnknownRuleError` rather than silently enabling token-weighting. See
+ * ROADMAP.md ("Deferred") for when it re-ships.
+ */
+export const builtinRegistry = {
+    [erc721MinBalance.type]: erc721MinBalance,
+    [constant.type]: constant
+};
+/** type ids the v1 implementation guarantees; checked against `requires.rules`. */
+export const V1_BUILTIN_RULE_TYPES = ["erc721-min-balance", "constant"];
+/**
+ * Merge host overrides over the built-ins. Overrides shadow built-ins by `type`. The
+ * override map is a plain `RuleRegistry` (a flat record already allows any subset
+ * of `type`s), so a host passes only the rules it adds or replaces.
+ */
+export function resolveRegistry(overrides) {
+    return { ...builtinRegistry, ...overrides };
+}
+/**
+ * Validate a criteria document against a resolved registry: the `rule` and
+ * `weight` refs must name rules this registry implements, their options must
+ * parse against the rule's own schema, and every name in `requires.rules`
+ * must be resolvable (so an out-of-date client recuses itself instead of miscounting).
+ *
+ * Throws `UnknownRuleError` / a zod error on the first failure. This is a check,
+ * not a transform: it never mutates `criteria`, so the topic-bearing bytes are untouched
+ * (option defaults applied here do not leak back into the encoded criteria).
+ */
+export function validateCriteriaRules(criteria, registry) {
+    const rule = registry[criteria.rule.type];
+    if (!rule)
+        throw new UnknownRuleError("rule", criteria.rule.type);
+    rule.optionsSchema.parse(criteria.rule);
+    const weight = registry[criteria.weight.type];
+    if (!weight)
+        throw new UnknownRuleError("weight", criteria.weight.type);
+    weight.optionsSchema.parse(criteria.weight);
+    for (const name of criteria.requires.rules) {
+        if (!registry[name])
+            throw new UnknownRuleError("requires", name);
+    }
+}

package/dist/rules/types.d.ts

@@ -0,0 +1,74 @@
+import type { z } from "zod";
+import type { ChainClient } from "../chain/types.js";
+/**
+ * Rule interface, design + leaves implemented.
+ *
+ * A rule turns a criteria `{ type, ...options }` reference into a non-negative
+ * score for one wallet, evaluated at the bundle's bucket block. There is a SINGLE kind
+ * (mirroring the flat pkc-js challenge registry: `Record<string, rule>`, user
+ * entries shadow builtins). The criteria still has two slots that draw from this one
+ * registry:
+ *
+ *   - rule slot:   the score is a GATE. `> 0n` admits the wallet, `0n` rejects it.
+ *   - weight slot: the score is the vote's MAGNITUDE.
+ *
+ * Final vote value = `evaluate(rule).score === 0n ? 0n : evaluate(weight).score`.
+ *
+ * A single numeric return covers both roles: a rule that needs a threshold
+ * (min Passes, min balance) bakes it in by returning 0n when the wallet falls short.
+ * That is why the gate slot does not need a separate boolean kind.
+ */
+/**
+ * The result of one evaluation. `score` is a non-negative `bigint`; `0n` means "does not
+ * qualify" (rejected in the rule slot, no weight in the weight slot). It is an
+ * object, not a bare `bigint`, so slot-specific fields can be added without changing the
+ * signature again — e.g. a self-declared `ceiling` for balance-derived weight, which the
+ * lazy tally needs as a wire-side upper bound (see DESIGN.md "Open questions").
+ */
+export interface RuleResult {
+    score: bigint;
+}
+/** Everything a rule needs to read chain state for one evaluation. */
+export interface ChainReadContext {
+    /**
+     * The viem `PublicClient` for the rule's `options.chain`. Use the full viem
+     * read surface directly (`readContract`, `getBalance`, ...), pinning every call to
+     * the sampled block with `blockNumber: BigInt(ctx.blockNumber)`.
+     */
+    chain: ChainClient;
+    /** The single sampled block for the bundle's bucket. */
+    blockNumber: number;
+}
+/**
+ * The one rule kind. `O` is the validated options type (from its `optionsSchema`).
+ * `evaluate` returns a `RuleResult` whose `score` is a non-negative `bigint`; `0n`
+ * means "does not qualify" (rejected in the rule slot, no weight in the weight slot).
+ */
+export interface Rule<O = unknown> {
+    readonly type: string;
+    readonly optionsSchema: z.ZodType<O>;
+    evaluate(args: {
+        options: O;
+        walletAddress: string;
+        ctx: ChainReadContext;
+    }): Promise<RuleResult>;
+    /**
+     * Optional batched form of {@link evaluate}: score many wallets at the SAME sampled block in
+     * as few RPC round trips as the rule can manage (e.g. one multicall3 `aggregate3` for a whole
+     * checkpoint's wallets). Returns one result per input wallet, in order. Semantics MUST equal
+     * mapping `evaluate` over the wallets — this is a transport optimization, never a different
+     * answer. The background chain verifier prefers it when present and falls back to per-wallet
+     * `evaluate` calls otherwise (see verify/background.ts).
+     */
+    evaluateMany?(args: {
+        options: O;
+        walletAddresses: string[];
+        ctx: ChainReadContext;
+    }): Promise<RuleResult[]>;
+}
+/**
+ * The registry: a flat `type -> rule` map. Built-ins are provided by this
+ * library; hosts may pass overrides that shadow built-ins by `type`. Mirrors pkc-js
+ * src/runtime/node/community/challenges/index.ts.
+ */
+export type RuleRegistry = Record<string, Rule>;

package/dist/rules/types.js

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

package/dist/schema/common.d.ts

@@ -0,0 +1,25 @@
+import { z } from "zod";
+/**
+ * Shared wire primitives.
+ *
+ * There is no pkc-js author in this library: a vote is signed directly by the
+ * gating-chain wallet that holds the Pass/ERC-20 (see DESIGN.md "Identity: the
+ * voting wallet, nothing else"). What survives from the old author/wallet schema is
+ * two small, identity-agnostic primitives reused across the wire:
+ *   - `ChainTickerSchema`: the chain identifier ("base", "eth", ...) used by criteria
+ *     and chain-reading rules.
+ *   - `SignatureSchema`: the detached `{ signature, type }` shape (kept from pkc-js),
+ *     here carrying the wallet's EIP-712 ballot signature.
+ */
+/** Chain ticker is unrestricted ("base", "eth", ...), matching pkc-js. */
+export declare const ChainTickerSchema: z.ZodString;
+/**
+ * A detached signature with an explicit scheme tag. For a Votes bundle the `type` is
+ * the EIP-712 scheme ({@link EIP712_SIGNATURE_TYPE}) and `signature` is the hex
+ * signature the voting wallet produced over the ballot typed data.
+ */
+export declare const SignatureSchema: z.ZodObject<{
+    signature: z.ZodString;
+    type: z.ZodString;
+}, z.core.$strip>;
+export type Signature = z.infer<typeof SignatureSchema>;