@bitsocial/pubsub-voting 0.0.6

package/README.md

@@ -0,0 +1,223 @@
+# @bitsocial/pubsub-voting
+
+Trustless, leaderless voting over libp2p pubsub, designed to run on top of a host node's shared libp2p/Helia instance.
+
+> **Status: engine, reactive facade, and live-delta transport implemented and unit-tested.** The zod schemas, canonical dag-cbor encoding, topic derivation, the verify pipeline (signature + constraints + on-chain gate + community-name resolution), the LWW winner-set CRDT with its binary bundle codec, the tally, the transport's **validate-before-forward gossip gate** over **inline bundle deltas**, and the **root-record checkpoint sync** (on-demand encode, suppressed 10-minute topic heartbeat, libp2p-fetch pull, divergent roots chased via directed bitswap) are all implemented — so the reactive `PubsubVoter` / `Contest` (`createContest`) / `ContestVote` (`createContestVote`) facade is live. The gate runs the full validity pipeline on the message bytes in an async gossipsub topic validator *before* re-forwarding, so an invalid bundle (bad signature, wallet the gate rejects, squatted name) is never propagated and `reject` scores the sender. Cold-join checkpoint bundles instead admit on the synchronous offline checks and settle their **deferred chain checks in the background, batched via multicall3** — the tally renders immediately with per-row `chainVerified`/`nameResolved` flags and refines as they land, and a node's own checkpoint only ever serves fully verified bundles (see [DESIGN.md, Background chain verification](./DESIGN.md#background-chain-verification)). **Keeping a live vote from decaying is the consuming client's job** — this library publishes each vote once and exposes `republishIntervalBuckets` so the client can schedule its own refreshes (see [DESIGN.md, Republishing is the client's job](./DESIGN.md#republishing-is-the-clients-job-not-this-librarys)). What remains is host-side (pkc-js registering gossipsub + `@libp2p/fetch` on the shared node) — see [ROADMAP.md](./ROADMAP.md), [DESIGN.md](./DESIGN.md), the [Transport gate](./DESIGN.md#transport-gossipsub-topic--validation), and [open questions](./DESIGN.md#open-questions).
+
+## What it is for
+
+The first consumer is [5chan](https://github.com/bitsocialnet/5chan), a serverless, adminless imageboard on the Bitsocial protocol. 5chan has a [competitive directory system](https://github.com/bitsocialnet/5chan/blob/master/README.md#competitive-directory-system): many communities compete for each directory slot (for example, multiple "Business & Finance" communities), but only the highest-voted one appears on the homepage. Today those assignments are curated by hand through pull requests to [`5chan-directories.json`](https://github.com/bitsocialnet/lists/blob/master/5chan-directories.json). This library is the planned replacement: directory voting that is decided by holders rather than by maintainers, with no server to trust.
+
+The same engine generalizes to the original use case in [pkc-js issue #25](https://github.com/pkcprotocol/pkc-js/issues/25) (a default-communities list voted on over pubsub) and to any future Bitsocial client that needs holder-weighted, censorship-resistant curation.
+
+## Why a separate library (not in pkc-js)
+
+[pkc-js](https://github.com/pkcprotocol/pkc-js) (Public Key Communities) is the protocol layer: communities, publications, the challenge exchange. Voting is application/governance layer. Keeping it separate means:
+
+- Chain-RPC and governance churn stay out of pkc-js core. pkc-js deliberately touches chains only for name resolution; it has no balance lookups, no chainTicker-to-RPC mapping, and no off-chain vote signing or verification. This library owns all of that.
+- The engine is reusable across clients and contests.
+- The core (`schema/`, `verify/`, `crdt/`, `tally/`) is transport-agnostic and unit-testable without a network. libp2p only appears in `transport/`.
+
+This library does not start its own node. It consumes the host's running Helia node directly — no adapter — and drives that node's gossipsub service and blockstore itself. The node must carry a pubsub service at `libp2p.services.pubsub` (a plain Helia node does not — register e.g. `@chainsafe/libp2p-gossipsub`), a usable `blockstore`, and a libp2p fetch service at `libp2p.services.fetch` (register `@libp2p/fetch` — the checkpoint root-record pull rides it); construction throws `MissingPubsubError` / `MissingBlockstoreError` / `MissingFetchError` otherwise. With pkc-js today that node is reached at `pkc.clients.libp2pJsClients[key]._helia`; a version-stable accessor on pkc-js is a planned follow-up (see [DESIGN.md, Deferred pkc-js work](./DESIGN.md#deferred-pkc-js-work)).
+
+## Design at a glance
+
+- **Settings live in the topic.** `topic = "bitsocial-votes/" + CID(dag-cbor(criteria))`. Two peers on the same topic provably ran identical rules, so the network validates itself with no intermediary.
+- **Votes are a state-based grow-only CRDT.** A signed `Votes` bundle is a standalone dag-cbor block (no parent links); each wallet gossips its own bundle **inline as a live delta**, validated straight from the message bytes — no fetch toward the publisher. State is a last-write-wins set keyed by wallet, so aggregation is a monotonic union: a peer can omit a vote but can never subtract one that an honest peer serves. Cold start and gap-fill exchange a tiny **root record** (libp2p-fetch pull + a slow topic heartbeat) and pull the checkpoint blocks behind it via directed bitswap from its advertisers.
+- **The gate and weight are data, not code.** A fixed rule registry (mirroring pkc-js's challenge registry) maps a `type` string to a verifier. v1 ships exactly the NFT path — an `erc721-min-balance` gate `rule` (5chan Pass) and `constant` weight (1 pass = 1 vote). Balance-derived (token-weighted) voting is deferred; see [ROADMAP.md](./ROADMAP.md).
+
+See [DESIGN.md](./DESIGN.md) for the full rationale, including how this resists vote-dropping and how criteria upgrades fork cleanly.
+
+## Usage
+
+The library never starts a node and never takes a host SDK (there is no `pkc` argument). A host passes its own running Helia node in directly and injects its seams into a single `PubsubVoter`:
+
+| Seam | Type | Required | Purpose |
+|---|---|---|---|
+| `helia` | `HeliaInstance` | yes | the host's running Helia node; must carry a gossipsub service at `libp2p.services.pubsub` (else `MissingPubsubError`) and a `blockstore` (else `MissingBlockstoreError`) |
+| `chains` | `ChainClientFactory` | yes | builds a viem `PublicClient` per chain; rules read through it for the gate and weight |
+| `signer` | `VoteSigner` | no | the voting wallet's address + EIP-712 ballot signing; omit for a read-only voter |
+| `nameResolvers` | `NameResolver[]` | no | community-name resolvers (same interface and instances as pkc-js's `nameResolvers`, e.g. `@bitsocial/bso-resolver` for `name.bso`); each vote's `community.name` claim is verified through them — inline at the forward-gate for live votes, in the background verifier for cold-join admits — and a bundle whose name resolves to a different `publicKey` than claimed is dropped/evicted |
+| `dataPath` | `string \| false` | no | directory for the voter's persistent caches (gate results + name resolutions), the pkc-js `dataPath` equivalent. Node default: `{cwd}/.bitsocial-pubsub-voting` (better-sqlite3 under `{dataPath}/lru-storage/`); in the browser the path is ignored and the caches live in IndexedDB. Pass `false` for in-memory-only (the pkc-js `noData` equivalent). A restart re-serves settled gate reads and fresh name resolutions from the store instead of the RPC |
+| `httpRouterUrls` | `string[]` | no | Delegated Routing V1 router base URLs to **announce provider records to** (one unsigned `PUT /routing/v1/providers` per router; `Keys` batches every joined contest's criteria CID + current checkpoint root + chunk CIDs — hourly, debounced on root changes, and on address changes). **Seeders only**: absent/empty means never announce (the default — plain clients are not dialable), and the browser build never announces regardless. The node must be publicly dialable, with its dialable addresses in `libp2p` (listen/announce/AutoTLS): private, loopback, and link-local addrs are filtered client-side, and an announce with no surviving address is skipped. *Querying* needs no URLs here — cold-join discovery uses the injected node's `libp2p.contentRouting`, which the host wires its routers into |
+
+A contest is addressed by its **full criteria document**, passed to `createContest` / `createContestVote`. The document is strictly validated there (`CriteriaSchema` + the rule registry), and its canonical bytes derive the topic — so the exact document every participant shares is the only contest configuration that exists.
+
+### Construct a voter
+
+```ts
+import { PubsubVoter } from "@bitsocial/pubsub-voting";
+
+const voter = new PubsubVoter({
+  helia,                        // the host's Helia node; needs a gossipsub service at libp2p.services.pubsub + a blockstore
+  chains: viemChainFactory(),   // ({ chain, config }) => viem PublicClient
+  signer: mySigner,             // optional; omit → read-only voter
+  nameResolvers: [bsoResolver], // optional; verifies community-name claims (e.g. @bitsocial/bso-resolver)
+  dataPath: "/path/to/data",    // optional; persistent-cache directory (default {cwd}/.bitsocial-pubsub-voting; false → in-memory)
+  httpRouterUrls: [             // optional, SEEDERS ONLY (publicly dialable node): announce provider
+    "https://routing.example"   // records (criteria CID + checkpoint root + chunks) so cold joiners
+  ]                             // can discover this node via the routers; clients omit this
+});
+```
+
+Construction throws `MissingPubsubError`, `MissingBlockstoreError`, or `MissingFetchError` if the node lacks a usable pubsub service, blockstore, or libp2p fetch service — the library fails fast rather than letting a later `publish`/`subscribe`/`fetch` fail obscurely. ("Bitswap" is not a separately checkable property — it is a block broker wired beneath `blockstore` — so the validated guarantee is a well-formed blockstore, the surface bitswap retrieves through. The fetch service carries the checkpoint root-record pull; the library registers its own responder on it.)
+
+### Read a tally reactively (no signer needed)
+
+`createContest` mints a per-contest read object; `update()` starts syncing and it emits `update` (carrying a fresh `tally`) and `error`, just like a plebbit-js `subplebbit`:
+
+```ts
+const contest = await voter.createContest({ criteria });  // criteria: the contest's full document (strictly validated here)
+contest.on("update", () => render(contest.tally));        // tally rides the object; recomputed before each emit
+contest.on("error", (err) => showConnectivityWarning(err)); // tally chain read failed, or the background verifier's RPC/resolver is down (retrying)
+await contest.update();                                   // join the topic, cold-start, begin emitting
+// const fresh = await contest.getTally();                // or force a fresh read, bypassing the cache
+// await contest.stop();                                  // leave the topic
+```
+
+Each ranking row carries one flag **per deferred verification operation** (mirroring pkc-js's
+`nameResolved`), and every background settlement re-fires `update` — so a leaderboard can render
+provisional rows immediately and refine them in place:
+
+```ts
+contest.on("update", () => {
+    for (const row of contest.tally?.ranking ?? []) {
+        // row.community: { name?: string, publicKey: string } — identity is ALWAYS publicKey.
+        // Show the name only once it has been checked against the registry.
+        const label = row.community.name && row.nameResolved ? row.community.name : row.community.publicKey;
+        // row.chainVerified: true once EVERY contributing vote's on-chain gate read confirmed.
+        // false means "still being read in the background", never "failed" — a vote that fails
+        // a deferred check is evicted and the row recounted instead.
+        renderRow(label, row.weight, row.chainVerified ? "verified" : "verifying…");
+    }
+});
+```
+
+A cold join **renders fast and refines**: checkpoint bundles are admitted after the synchronous offline checks (signature + constraints), so the first tally arrives with `chainVerified: false` rows, and the background verifier then batches the deferred gate reads (one multicall per bucket) and name resolutions — each settlement re-fires `update` with the flags flipped. See [DESIGN.md, Background chain verification](./DESIGN.md#background-chain-verification).
+
+Repeated `createContest` calls with byte-identical criteria return the same `Contest` (engines are keyed by topic, the criteria CID).
+
+### Publish or withdraw a vote (needs a signer)
+
+`createContestVote` mints a publishable ballot; `publish()` signs and broadcasts it once and emits `publishingstatechange`, like a plebbit-js publication:
+
+```ts
+const vote = await voter.createContestVote({ criteria, votes: [{ community: { publicKey: "12D3KooW..." }, vote: 1 }] });
+vote.on("publishingstatechange", (state) => console.log(state)); // stopped → signing → publishing → succeeded (or failed)
+const { bundle, recipientCount } = await vote.publish();          // the signed VotesBundle + how many peers gossipsub sent it directly to
+
+// Withdraw (active): publish an empty ballot; it supersedes the prior vote under LWW.
+await (await voter.createContestVote({ criteria, votes: [] })).publish();
+```
+
+A community's identity is its `publicKey`. The optional `name` is the community's resolvable domain (e.g. `memes.bso`) — unique per community, never a free label: the schema requires a TLD, the name is resolved through the injected `nameResolvers` (inline at the forward-gate for live votes, in the background verifier for cold-join admits), and any bundle whose name resolves to a different `publicKey` than claimed is dropped/evicted. Bundles must also name pairwise-distinct `community.publicKey`s. See [DESIGN.md, Votes wire](./DESIGN.md#votes-wire).
+
+`recipientCount` is the peer-reach hint gossipsub reports: how many peers it sent the vote *directly* to at publish time (first-hop fan-out, filtered for send failures) — **not** total network reach, and **not** an acceptance confirmation, since each recipient still runs the forward-gate before re-forwarding. Treat it as a coarse "did this reach anyone?" signal. Note that gossipsub *rejects* the publish with `NoPeersSubscribedToTopic` when it would reach zero peers (common right after joining, before the mesh grafts), unless the host enables `allowPublishToZeroTopicPeers` — so a resolved `recipientCount === 0` only occurs under that host setting; otherwise a no-reach publish surfaces as a thrown error (and a `failed` state).
+
+`publish()` on a voter built without a `signer` throws `ReadOnlyError` (and emits an `error`).
+
+### Republishing is the client's job
+
+A vote is not permanent: a bundle is valid only for `voteExpiryBuckets` after its `blockNumber`, so a live vote must be re-published before it decays. **This library does not do that automatically** — it publishes each vote once and the consuming client decides when (or whether) to refresh. To refresh, just `createContestVote(...).publish()` again; a new bundle at the current bucket supersedes the old one. To stop, simply stop refreshing and let the vote lapse. The library gives you what you need to schedule it — all pure, no chain reads:
+
+```ts
+import { republishIntervalBuckets } from "@bitsocial/pubsub-voting";
+
+const cadence = republishIntervalBuckets(criteria); // ceil(voteExpiryBuckets / 2) — the recommended cadence, in buckets
+// A vote sampled at bucket b (bundle.blockNumber / criteria.blocksPerBucket) expires once the
+// current bucket exceeds b + criteria.voteExpiryBuckets; refresh before then.
+```
+
+See [DESIGN.md, Republishing is the client's job](./DESIGN.md#republishing-is-the-clients-job-not-this-librarys) for why an always-on re-signer was deliberately kept out of a library that runs on the host's shared node.
+
+### Many contests (a 5chan-style directory)
+
+One criteria document is one contest (one topic). A directory is conveniently authored as a single manifest of shared `defaults` plus one entry per slot — as in [5chan-directory-criteria.jsonc](./5chan-directory-criteria.jsonc) and [examples/5chan.ts](./examples/5chan.ts) — and `deriveDirectoryCriteria` derives the finished documents (`{ ...defaults, ...entry }`, shallow — an override replaces that whole field) and validates each one. What participants must share **byte-identically** is the derived documents (the topic is their CID), which is why every consumer of the same directory should derive through this one helper rather than re-implement the merge. The manifest is JSONC by convention; strip comments before parsing:
+
+```ts
+import { deriveDirectoryCriteria } from "@bitsocial/pubsub-voting";
+import stripJsonComments from "strip-json-comments";
+
+const manifest = JSON.parse(stripJsonComments(manifestJsonc)) as unknown;
+const allCriteria = deriveDirectoryCriteria(manifest); // → Criteria[], throws on invalid entries or duplicate contestIds
+
+const contests = await Promise.all(allCriteria.map((criteria) => voter.createContest({ criteria }))); // → Contest[]
+for (const contest of contests) await contest.update(); // a full host joins + serves the whole directory
+```
+
+There is no separate seeder API: a node that joins a topic (via `update()` or `publish()`) automatically serves that contest's checkpoint root record over libp2p-fetch — the responder registers itself on the first joined topic and unregisters when the last is left. A seeder is just a client that joins everything.
+
+### Lifecycle (`stop` / `destroy`)
+
+`stop()` leaves every joined topic but keeps the voter **reusable** — each `Contest` can `update()` again and you can `createContest` afterward. `destroy()` is **terminal** (like pkc-js): it leaves every topic, unregisters the fetch responder, and marks the voter and its contests dead — any later `createContest`/`createContestVote`, or a pre-existing `Contest.update()`/`ContestVote.publish()`, throws `VoterDestroyedError`. Construct a new `PubsubVoter` to participate again. (There is no store to dispose — republishing is the client's concern.)
+
+```ts
+const voter = new PubsubVoter({ helia, chains, signer });
+// … create + update contests, app runs …
+await voter.destroy();   // terminal: leave all topics, unregister the responder, forbid reuse
+```
+
+### Pure helpers (no node, no network)
+
+```ts
+import { topicFor, deriveDirectoryCriteria } from "@bitsocial/pubsub-voting";
+
+const topic = await topicFor(criteria);            // "bitsocial-votes/" + CID(dag-cbor(criteria))
+const allCriteria = deriveDirectoryCriteria(json); // directory manifest → validated Criteria[] (see above)
+```
+
+Full, type-checked call patterns for a pkc-js host, a plebbit/seedit host, and a read-only consumer are in [examples/](./examples/).
+
+### Custom rules
+
+The gate and weight are a single flat registry of rules, one `type` per file, mirroring the pkc-js challenge registry. Each rule owns its option schema and is evaluated at the bundle's bucket block. Chain-reading rules get `ctx.chain` — the viem `PublicClient` for their `options.chain` — and write their own reads (`readContract`, `getBalance`, ...), pinning each call to the sampled block with `blockNumber: BigInt(ctx.blockNumber)`. There is **one kind**: `evaluate → { score: bigint }`, a non-negative score where `0n` means "does not qualify" (a result object, not a bare `bigint`, so slot-specific fields can be added later). The criteria has two *slots* drawing from the one registry — the **rule** slot treats the score as a gate (`> 0n` admits), the **weight** slot as the vote's magnitude. A wallet's vote counts as `rule.score > 0n ? weight.score : 0n`. A rule that needs a threshold returns `0n` below it (so `erc721-min-balance`'s optional `min` gates), which lets the same rule serve either slot.
+
+Built-ins: `erc721-min-balance` (v1) and `constant` (v1). A host adds or shadows rules by `type` via the `rules` option — this is how clients like 5chan or seedit register custom rules without forking the library:
+
+```ts
+import { PubsubVoter, type Rule } from "@bitsocial/pubsub-voting";
+import { z } from "zod";
+
+const seeditModAllowlist: Rule<{ type: "seedit-mod-allowlist"; allow: string[] }> = {
+  type: "seedit-mod-allowlist",
+  optionsSchema: z.object({ type: z.literal("seedit-mod-allowlist"), allow: z.array(z.string()) }),
+  async evaluate({ options, walletAddress }) {
+    return { score: options.allow.includes(walletAddress) ? 1n : 0n }; // gate: 1n admits, 0n rejects
+  }
+};
+
+const voter = new PubsubVoter({
+  helia, chains,
+  rules: { "seedit-mod-allowlist": seeditModAllowlist } // flat map; shadows/extends built-ins by `type`
+});
+```
+
+A custom `type` becomes part of `dag-cbor(criteria)`, so it is provably pinned to the topic it runs on, and a client that does not implement a `type` named in `criteria.requires.rules` throws `UnknownRuleError` and recuses itself rather than miscounting.
+
+### Weighted voting (deferred)
+
+v1 ships `constant` weight (one Pass, one vote) **on purpose** — it resists whale dominance and downvote weaponization. Balance-derived, token-weighted voting (Pass gate + BSO weight via `erc20-balance`) is a designed-but-unshipped capability: the rule path and result shape leave room for it with no engine change, but it is not in the v1 built-ins and carries open governance/abuse and lazy-tally questions. See [ROADMAP.md](./ROADMAP.md) and [DESIGN.md, Future improvements](./DESIGN.md#future-improvements).
+
+## Layout
+
+```
+src/
+  schema/        zod schemas (criteria, votes, shared wire primitives) + inferred types
+  encoding/      canonical dag-cbor encoding                      [implemented]
+  topic.ts       topic = "bitsocial-votes/" + CID(dag-cbor)       [implemented]
+  signer/        VoteSigner seam + EIP-712 ballot typed data       [implemented]
+  client/        reactive facade: PubsubVoter + Contest (createContest) + ContestVote (createContestVote) [implemented]
+  errors.ts      ReadOnly/MissingPubsub/MissingBlockstore/MissingFetch/... [implemented]
+  rules/         one file per `type` + registry/resolver          [implemented]
+  chain/         ChainClient = viem PublicClient + bucket math     [implemented]
+  verify/        signature + constraints + full BundleVerifier + verdict cache [implemented]
+  crdt/          state-based LWW winner-set: union, binary bundle codec, in-memory store [implemented]
+  checkpoint/    deterministic checkpoint codec (root manifest + size-capped chunks) [implemented]
+  transport/     async validate-before-forward gossip gate + message codec (inline bundle / root record) + root chase + transport [implemented]
+  tally/         deterministic aggregation over pre-validated bundles [implemented]
+  index.ts       public entry: re-exports + facade + design types
+```
+
+## License
+
+GPL-3.0-or-later, matching 5chan.

package/dist/chain/bucket.d.ts

@@ -0,0 +1,13 @@
+import type { BucketMath } from "./types.js";
+/**
+ * Bucket math for one criteria's `blocksPerBucket`.
+ *
+ *   bucketForBlock(block)        = Math.floor(block / blocksPerBucket)
+ *   sampleBlockForBucket(bucket) = bucket * blocksPerBucket  (the bucket boundary block)
+ *
+ * Every verifier prices balances at one sample block per bucket so votes cannot
+ * flip-flop mid-bucket and every client agrees. v1 uses the bucket boundary (the head
+ * rounded down to `blocksPerBucket`); the boundary lags the head by up to a full bucket,
+ * which also places it past any realistic reorg depth (see DESIGN.md "Tally", "CRDT").
+ */
+export declare function makeBucketMath(blocksPerBucket: number): BucketMath;

package/dist/chain/bucket.js

@@ -0,0 +1,24 @@
+/**
+ * Bucket math for one criteria's `blocksPerBucket`.
+ *
+ *   bucketForBlock(block)        = Math.floor(block / blocksPerBucket)
+ *   sampleBlockForBucket(bucket) = bucket * blocksPerBucket  (the bucket boundary block)
+ *
+ * Every verifier prices balances at one sample block per bucket so votes cannot
+ * flip-flop mid-bucket and every client agrees. v1 uses the bucket boundary (the head
+ * rounded down to `blocksPerBucket`); the boundary lags the head by up to a full bucket,
+ * which also places it past any realistic reorg depth (see DESIGN.md "Tally", "CRDT").
+ */
+export function makeBucketMath(blocksPerBucket) {
+    if (!Number.isInteger(blocksPerBucket) || blocksPerBucket <= 0) {
+        throw new RangeError(`blocksPerBucket must be a positive integer, got ${blocksPerBucket}`);
+    }
+    return {
+        bucketForBlock(blockNumber) {
+            return Math.floor(blockNumber / blocksPerBucket);
+        },
+        sampleBlockForBucket(bucket) {
+            return bucket * blocksPerBucket;
+        }
+    };
+}

package/dist/chain/coalescer.d.ts

@@ -0,0 +1,56 @@
+import type { ChainClient, ChainClientFactory } from "./types.js";
+/**
+ * Chain-read coalescing — a DataLoader for pinned-block contract reads.
+ *
+ * Rules read the chain through the full viem surface (`readContract`, `multicall`, ...), and
+ * verification runs in parallel: a directory join verifies dozens of contests at once, the
+ * gossip forward-gate verifies each incoming vote individually, and the background verifier
+ * batches per bucket. Left alone, that parallelism turns into a burst of concurrent HTTP posts
+ * that free public RPC endpoints throttle (measured against `mainnet.base.org`: 38 concurrent
+ * `aggregate3` posts → 33× HTTP 429 `-32016 over rate limit`). Per-call politeness inside one
+ * rule invocation cannot fix this — the burst forms ACROSS calls — so the voter wraps each
+ * chain client ONCE ({@link coalescingChainFactory}) and every consumer shares the wrapper:
+ *
+ *   - `readContract` calls pinned to an explicit `blockNumber` are collected for a short
+ *     window ({@link COALESCE_WINDOW_MS} — noise next to a WAN RTT), deduped on
+ *     `(block, contract, calldata)`, grouped per block (an `eth_call` reads ONE block, so
+ *     different bucket sample blocks can never share a multicall), and flushed as multicall3
+ *     `aggregate3` chunks of {@link CHAIN_READS_PER_MULTICALL} reads.
+ *   - Explicit pinned-block `multicall` calls (e.g. a rule's own `evaluateMany` batching) are
+ *     DECOMPOSED into that same pool, so parallel contests' per-contest batches merge into
+ *     shared round trips too (measured: without this, a 10-board directory join fired 10
+ *     separate small multicalls plus head reads and the sustained stream still tripped the
+ *     endpoint's rate limit). Unpinned/exotic multicalls pass through under the same budget.
+ *   - At most {@link CHAIN_MULTICALL_CONCURRENCY} round trips are in flight per underlying
+ *     client, across everything; a failed coalesced chunk retries once
+ *     ({@link CHAIN_CHUNK_RETRY_DELAY_MS}) without re-reading completed chunks.
+ *
+ * Caveat (shared with any multicall batching): a coalesced read executes as an inner CALL from
+ * the multicall3 contract, so `msg.sender` differs from a direct `eth_call`. That is irrelevant
+ * for `balanceOf`-style views — and reads that must not batch keep their semantics by omitting
+ * `blockNumber` or passing extra call options, which routes them through the raw client.
+ * Clients without a known multicall3 deployment are returned unwrapped.
+ */
+/** `balanceOf`-sized reads per multicall3 `aggregate3` round trip (~45 KB calldata, ~2–5M gas). */
+export declare const CHAIN_READS_PER_MULTICALL = 200;
+/** Multicall round trips in flight at once per chain client — polite to free public endpoints. */
+export declare const CHAIN_MULTICALL_CONCURRENCY = 2;
+/** One retry per failed coalesced chunk, after this pause. */
+export declare const CHAIN_CHUNK_RETRY_DELAY_MS = 500;
+export interface CoalescerOptions {
+    readsPerCall?: number;
+    concurrency?: number;
+    windowMs?: number;
+}
+/**
+ * Wrap one chain client with the shared read coalescer + in-flight budget. Idempotent per
+ * client only via {@link coalescingChainFactory} — call sites should not wrap twice.
+ */
+export declare function coalescingChainClient(client: ChainClient, options?: CoalescerOptions): ChainClient;
+/**
+ * Wrap a host's `ChainClientFactory` so every client it hands out is coalesced, memoized on the
+ * UNDERLYING client instance: a host factory that returns one shared client per chain (the
+ * normal shape — and what makes cross-contest coalescing possible at all) gets exactly one
+ * coalescer per chain, shared by every contest, the gossip gate, and the background verifier.
+ */
+export declare function coalescingChainFactory(factory: ChainClientFactory, options?: CoalescerOptions): ChainClientFactory;

package/dist/chain/coalescer.js

@@ -0,0 +1,217 @@
+import { encodeFunctionData } from "viem";
+/**
+ * Chain-read coalescing — a DataLoader for pinned-block contract reads.
+ *
+ * Rules read the chain through the full viem surface (`readContract`, `multicall`, ...), and
+ * verification runs in parallel: a directory join verifies dozens of contests at once, the
+ * gossip forward-gate verifies each incoming vote individually, and the background verifier
+ * batches per bucket. Left alone, that parallelism turns into a burst of concurrent HTTP posts
+ * that free public RPC endpoints throttle (measured against `mainnet.base.org`: 38 concurrent
+ * `aggregate3` posts → 33× HTTP 429 `-32016 over rate limit`). Per-call politeness inside one
+ * rule invocation cannot fix this — the burst forms ACROSS calls — so the voter wraps each
+ * chain client ONCE ({@link coalescingChainFactory}) and every consumer shares the wrapper:
+ *
+ *   - `readContract` calls pinned to an explicit `blockNumber` are collected for a short
+ *     window ({@link COALESCE_WINDOW_MS} — noise next to a WAN RTT), deduped on
+ *     `(block, contract, calldata)`, grouped per block (an `eth_call` reads ONE block, so
+ *     different bucket sample blocks can never share a multicall), and flushed as multicall3
+ *     `aggregate3` chunks of {@link CHAIN_READS_PER_MULTICALL} reads.
+ *   - Explicit pinned-block `multicall` calls (e.g. a rule's own `evaluateMany` batching) are
+ *     DECOMPOSED into that same pool, so parallel contests' per-contest batches merge into
+ *     shared round trips too (measured: without this, a 10-board directory join fired 10
+ *     separate small multicalls plus head reads and the sustained stream still tripped the
+ *     endpoint's rate limit). Unpinned/exotic multicalls pass through under the same budget.
+ *   - At most {@link CHAIN_MULTICALL_CONCURRENCY} round trips are in flight per underlying
+ *     client, across everything; a failed coalesced chunk retries once
+ *     ({@link CHAIN_CHUNK_RETRY_DELAY_MS}) without re-reading completed chunks.
+ *
+ * Caveat (shared with any multicall batching): a coalesced read executes as an inner CALL from
+ * the multicall3 contract, so `msg.sender` differs from a direct `eth_call`. That is irrelevant
+ * for `balanceOf`-style views — and reads that must not batch keep their semantics by omitting
+ * `blockNumber` or passing extra call options, which routes them through the raw client.
+ * Clients without a known multicall3 deployment are returned unwrapped.
+ */
+/** `balanceOf`-sized reads per multicall3 `aggregate3` round trip (~45 KB calldata, ~2–5M gas). */
+export const CHAIN_READS_PER_MULTICALL = 200;
+/** Multicall round trips in flight at once per chain client — polite to free public endpoints. */
+export const CHAIN_MULTICALL_CONCURRENCY = 2;
+/** One retry per failed coalesced chunk, after this pause. */
+export const CHAIN_CHUNK_RETRY_DELAY_MS = 500;
+/** How long the first read of a batch waits for company before its chunk flushes. */
+const COALESCE_WINDOW_MS = 25;
+const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * Wrap one chain client with the shared read coalescer + in-flight budget. Idempotent per
+ * client only via {@link coalescingChainFactory} — call sites should not wrap twice.
+ */
+export function coalescingChainClient(client, options = {}) {
+    // Without a known multicall3 deployment there is nothing to coalesce INTO — pass through.
+    if (typeof client.multicall !== "function" || !client.chain?.contracts?.multicall3)
+        return client;
+    const readsPerCall = options.readsPerCall ?? CHAIN_READS_PER_MULTICALL;
+    const concurrency = options.concurrency ?? CHAIN_MULTICALL_CONCURRENCY;
+    const windowMs = options.windowMs ?? COALESCE_WINDOW_MS;
+    // --- the shared in-flight budget (coalesced chunks AND explicit multicalls) ---
+    let active = 0;
+    const queue = [];
+    const acquire = () => new Promise((resolve) => {
+        const attempt = () => {
+            if (active < concurrency) {
+                active++;
+                resolve();
+            }
+            else {
+                queue.push(attempt);
+            }
+        };
+        attempt();
+    });
+    const release = () => {
+        active--;
+        queue.shift()?.();
+    };
+    // --- pending pinned reads, grouped per block; deduped until their read settles ---
+    const groups = new Map();
+    const inFlight = new Map();
+    const runChunk = async (reads, blockNumber) => {
+        await acquire();
+        try {
+            const call = () => client.multicall({
+                contracts: reads.map((read) => read.contract),
+                allowFailure: true,
+                batchSize: 0,
+                blockNumber
+            });
+            let results;
+            try {
+                results = await call();
+            }
+            catch {
+                await delay(CHAIN_CHUNK_RETRY_DELAY_MS);
+                results = await call();
+            }
+            for (let i = 0; i < reads.length; i++) {
+                const outcome = results[i];
+                if (outcome?.status === "success")
+                    reads[i].resolve(outcome.result);
+                else
+                    reads[i].reject(outcome?.error ?? new Error("multicall returned no result for this read"));
+            }
+        }
+        catch (err) {
+            for (const read of reads)
+                read.reject(err);
+        }
+        finally {
+            release();
+            for (const read of reads)
+                inFlight.delete(read.key);
+        }
+    };
+    const flushGroup = (blockKey) => {
+        const group = groups.get(blockKey);
+        if (!group)
+            return;
+        clearTimeout(group.timer);
+        groups.delete(blockKey);
+        for (let at = 0; at < group.reads.length; at += readsPerCall) {
+            void runChunk(group.reads.slice(at, at + readsPerCall), group.blockNumber);
+        }
+    };
+    const rawReadContract = client.readContract.bind(client);
+    /** Add one pinned read to its block's pending group (deduped); returns its shared promise. */
+    const enqueueRead = (contract, blockNumber) => {
+        let calldata;
+        try {
+            calldata = encodeFunctionData({ abi: contract.abi, functionName: contract.functionName, args: contract.args });
+        }
+        catch {
+            // Un-encodable entry (exotic abi shape) — read it directly, keeping pinned semantics.
+            return rawReadContract({ ...contract, blockNumber });
+        }
+        const key = `${blockNumber}:${contract.address.toLowerCase()}:${calldata}`;
+        const existing = inFlight.get(key);
+        if (existing)
+            return existing.promise;
+        let resolve;
+        let reject;
+        const promise = new Promise((res, rej) => {
+            resolve = res;
+            reject = rej;
+        });
+        const read = {
+            contract: { address: contract.address, abi: contract.abi, functionName: contract.functionName, args: contract.args ?? [] },
+            key,
+            promise,
+            resolve,
+            reject
+        };
+        inFlight.set(key, read);
+        const blockKey = blockNumber.toString();
+        let group = groups.get(blockKey);
+        if (!group) {
+            group = { blockNumber, reads: [], timer: setTimeout(() => flushGroup(blockKey), windowMs) };
+            groups.set(blockKey, group);
+        }
+        group.reads.push(read);
+        if (group.reads.length >= readsPerCall)
+            flushGroup(blockKey);
+        return promise;
+    };
+    const readContract = (async (params) => {
+        const { address, abi, functionName, args, blockNumber, ...rest } = params;
+        // Coalesce only the plain pinned-block read shape; anything else (head reads, blockTag,
+        // account/state overrides, ...) keeps direct-call semantics through the raw client.
+        if (typeof blockNumber !== "bigint" || Object.keys(rest).length > 0 || !address || !abi || !functionName) {
+            return rawReadContract(params);
+        }
+        return enqueueRead({ address, abi, functionName, args }, blockNumber);
+    });
+    const rawMulticall = client.multicall.bind(client);
+    const multicall = (async (params) => {
+        // A pinned multicall DECOMPOSES into the shared pool: parallel contests' per-contest
+        // batches (each rule's evaluateMany) merge into the same aggregate3 round trips as
+        // coalesced single reads, and duplicate reads (one wallet voting on many boards at one
+        // sample block) collapse. `batchSize` is dropped on decomposition (the pool re-chunks at
+        // `readsPerCall` anyway); any OTHER extra option (`stateOverride`, `multicallAddress`,
+        // `deployless`, ...) changes viem's execution semantics, so — like unpinned calls —
+        // those shapes pass through raw under the budget.
+        const { contracts, allowFailure = true, batchSize: _batchSize, blockNumber, ...rest } = params;
+        if (typeof blockNumber !== "bigint" || !Array.isArray(contracts) || Object.keys(rest).length > 0) {
+            await acquire();
+            try {
+                return await rawMulticall(params);
+            }
+            finally {
+                release();
+            }
+        }
+        const settled = await Promise.allSettled(contracts.map((contract) => enqueueRead(contract, blockNumber)));
+        if (!allowFailure) {
+            const failed = settled.find((s) => s.status === "rejected");
+            if (failed)
+                throw failed.reason;
+            return settled.map((s) => s.value);
+        }
+        return settled.map((s) => s.status === "fulfilled" ? { status: "success", result: s.value } : { status: "failure", error: s.reason, result: undefined });
+    });
+    return { ...client, readContract, multicall };
+}
+/**
+ * Wrap a host's `ChainClientFactory` so every client it hands out is coalesced, memoized on the
+ * UNDERLYING client instance: a host factory that returns one shared client per chain (the
+ * normal shape — and what makes cross-contest coalescing possible at all) gets exactly one
+ * coalescer per chain, shared by every contest, the gossip gate, and the background verifier.
+ */
+export function coalescingChainFactory(factory, options) {
+    const wrapped = new WeakMap();
+    return (args) => {
+        const client = factory(args);
+        let coalesced = wrapped.get(client);
+        if (!coalesced) {
+            coalesced = coalescingChainClient(client, options);
+            wrapped.set(client, coalesced);
+        }
+        return coalesced;
+    };
+}

package/dist/chain/ticker.d.ts

@@ -0,0 +1,15 @@
+import type { Criteria, RuleRef } from "../schema/criteria.js";
+/**
+ * Resolve which chain a rule reads. A rule's parsed options may name a
+ * `chain` ticker (e.g. `erc721-min-balance` -> "base"); a chainless rule (e.g.
+ * `constant`) names none, so callers fall back to the first configured chain. Shared by the
+ * verifier, the tally, and the facade so the fallback rule stays identical everywhere.
+ */
+/** The `chain` ticker named in a rule's parsed options, or `undefined` if none. */
+export declare function chainTickerOf(options: unknown): string | undefined;
+/**
+ * The chain ticker a rule ref uses: its own `chain` option, else the first chain in
+ * `requires.chains`. Throws if neither exists (a chainless rule with no configured
+ * chains cannot be read).
+ */
+export declare function tickerForRef(criteria: Criteria, ref: RuleRef, options: unknown): string;

package/dist/chain/ticker.js

@@ -0,0 +1,25 @@
+import { z } from "zod";
+/**
+ * Resolve which chain a rule reads. A rule's parsed options may name a
+ * `chain` ticker (e.g. `erc721-min-balance` -> "base"); a chainless rule (e.g.
+ * `constant`) names none, so callers fall back to the first configured chain. Shared by the
+ * verifier, the tally, and the facade so the fallback rule stays identical everywhere.
+ */
+/** The `chain` ticker named in a rule's parsed options, or `undefined` if none. */
+export function chainTickerOf(options) {
+    const parsed = z.object({ chain: z.string().min(1) }).safeParse(options);
+    return parsed.success ? parsed.data.chain : undefined;
+}
+/**
+ * The chain ticker a rule ref uses: its own `chain` option, else the first chain in
+ * `requires.chains`. Throws if neither exists (a chainless rule with no configured
+ * chains cannot be read).
+ */
+export function tickerForRef(criteria, ref, options) {
+    const ticker = chainTickerOf(options) ?? Object.keys(criteria.requires.chains)[0];
+    if (!ticker) {
+        throw new Error(`criteria rule "${ref.type}" names no chain and requires.chains is empty; ` +
+            `cannot resolve a chain client to read it`);
+    }
+    return ticker;
+}