@bitsocial/pubsub-voting 0.0.10 → 0.1.0

package/README.md

@@ -35,22 +35,34 @@ The library never starts a node and never takes a host SDK (there is no `pkc` ar
 | Seam | Type | Required | Purpose |
 |---|---|---|---|
 | `helia` | `HeliaInstance` | yes | the host's running Helia node; must carry a gossipsub service at `libp2p.services.pubsub` (else `MissingPubsubError`), a `blockstore` (else `MissingBlockstoreError`), and a libp2p fetch service at `libp2p.services.fetch` (else `MissingFetchError`) |
-| `chains` | `ChainClientFactory` | yes | builds a viem `PublicClient` per chain; rules read through it for the gate and weight |
+| `chains` | `ChainClientFactory` | yes | resolves each chain a contest's criteria requires (`{ chain, chainId }`) to a viem `PublicClient`; rules read through it for the gate and weight. **RPC endpoints are this client's own settings, never part of the criteria document** — return one shared (memoized) client per chain, pointed at a gateway that serves historical state at least `voteExpiryBuckets × blocksPerBucket` blocks behind head and carries a multicall3 deployment in its viem `chain` config; return `undefined` for a chain with no RPC configured, and `createContest`/`createContestVote` throws `MissingChainClientError` (recuse, don't miscount) |
 | `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 state (gate-result + name-resolution caches, and each joined contest's **checkpoint snapshot** — its last fully-verified winner-set, reloaded at join so a restart with no other peer online keeps the tally), the pkc-js `dataPath` equivalent. Node default: `{cwd}/.bitsocial-pubsub-voting` (better-sqlite3 under `{dataPath}/lru-storage/` + `{dataPath}/checkpoints.db`); in the browser the path is ignored and everything lives 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, and restores each contest's checkpoint before the cold-start pull. A seeder should always set a stable path |
 | `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 **reachable** (its listening port open/forwarded/published), but it does not need to know its own public IP: private, loopback, and link-local addrs are filtered client-side, and when nothing survives — the normal zero-config case behind NAT or a Docker bridge, and even on public-IP hosts, since libp2p withholds unconfirmed public addrs pending AutoNAT — the announcer sends the wildcard sentinels (`/ip4/0.0.0.0/...`, `/ip6/::/...`) that the router rewrites to the PUT's observed source IP, exactly as kubo announces work. Configured `addresses.announce` values (concrete public addrs, DNS/AutoTLS, or a kubo-style wildcard) are used as-is. Only a loopback-only node announces nothing. *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.
+A contest is addressed by its **full criteria document**, passed to `createContest` / `createContestVote`. The document is strictly validated there (`CriteriaSchema` + the rule registry + the `chains` factory: an unimplemented rule throws `UnknownRuleError`, an unresolvable required chain throws `MissingChainClientError` — recuse, don't miscount), and its canonical bytes derive the topic — so the exact document every participant shares is the only contest configuration that exists. The document names each required chain only by ticker + `chainId`; RPC endpoints stay out of it, so operators can swap gateways without forking the topic.
 
 ### Construct a voter
 
 ```ts
-import { PubsubVoter } from "@bitsocial/pubsub-voting";
+import { PubsubVoter, type ChainClientFactory } from "@bitsocial/pubsub-voting";
+import { createPublicClient, http } from "viem";
+import { base } from "viem/chains";
+
+// The host's chain settings: which RPC gateway to trust per chain is THIS client's choice
+// (never part of a criteria document). One shared client per chain, memoized — sharing is
+// what lets parallel contests' pinned-block reads coalesce into shared multicalls.
+const viemChainFactory = (): ChainClientFactory => {
+  const clients: Record<number, ReturnType<typeof createPublicClient>> = {
+    [base.id]: createPublicClient({ chain: base, transport: http("https://my-trusted-base-rpc.example") })
+  };
+  return ({ chainId }) => clients[chainId]; // undefined → recuse contests requiring that chain
+};
 
 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
+  chains: viemChainFactory(),   // ({ chain, chainId }) => viem PublicClient | undefined
   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 state: caches + checkpoint snapshots (default {cwd}/.bitsocial-pubsub-voting; false → in-memory)

package/dist/chain/coalescer.js

@@ -207,6 +207,10 @@ export function coalescingChainFactory(factory, options) {
     const wrapped = new WeakMap();
     return (args) => {
         const client = factory(args);
+        // No client for this chain — the host has no RPC configured; the voter turns this
+        // into MissingChainClientError at the create seam.
+        if (client === undefined)
+            return undefined;
         let coalesced = wrapped.get(client);
         if (!coalesced) {
             coalesced = coalescingChainClient(client, options);

package/dist/chain/types.d.ts

@@ -1,5 +1,4 @@
 import type { PublicClient } from "viem";
-import type { ChainConfig } from "../schema/criteria.js";
 /**
  * Chain access.
  *
@@ -22,14 +21,27 @@ export type ChainClient = PublicClient;
 /** chainTicker -> client, built from `criteria.requires.chains`. */
 export type ChainClients = Record<string, ChainClient>;
 /**
- * Factory the host provides: turn a chain config into a viem `PublicClient`
- * (typically `createPublicClient({ transport: http(config.rpcUrls[0]) })`).
- * Declared here so the public API can describe how chain clients are supplied.
+ * Factory the host provides: resolve a chain named by the criteria (`requires.chains`,
+ * ticker + chainId) to a viem `PublicClient`. The RPC endpoint is the HOST's setting —
+ * deliberately not part of the criteria document (see schema/criteria.ts,
+ * `ChainConfigSchema`) — so this factory is where ticker/chainId meets the gateways this
+ * client trusts (typically `createPublicClient({ chain, transport: http(myRpcUrl) })`).
+ *
+ * Return `undefined` (or throw) when no RPC is configured for the named chain: the voter
+ * then throws `MissingChainClientError` at the create seam (`createContest` /
+ * `createContestVote`) — this client must recuse the contest rather than miscount.
+ *
+ * Return ONE shared client per chain (memoize on `chainId`), not a fresh client per call:
+ * the voter wraps each distinct client with the cross-contest read coalescer
+ * (src/chain/coalescer.ts), so sharing is what merges parallel contests' pinned-block reads
+ * into shared multicalls under one in-flight budget. Pick a gateway that serves historical
+ * state at least `voteExpiryBuckets × blocksPerBucket` blocks behind head (gate reads pin
+ * to bucket sample blocks) and carries a multicall3 deployment in its viem `chain` config.
  */
 export type ChainClientFactory = (args: {
     chain: string;
-    config: ChainConfig;
-}) => ChainClient;
+    chainId: number;
+}) => ChainClient | undefined;
 /**
  * A community-name resolver the host injects (`PubsubVoterOptions.nameResolvers`). The
  * shape is structurally identical to pkc-js's `NameResolverInterface`, so a host passes

package/dist/client/voter.d.ts

@@ -172,9 +172,13 @@ export interface PubsubVoterOptions {
      */
     helia: HeliaInstance;
     /**
-     * Builds a chain client from a `{ chain, config }` pair. Each contest builds its
-     * own clients from `criteria.requires.chains` via this factory, so chains are
-     * per-contest data, not a global injection.
+     * Resolves a chain named by a contest's criteria (`requires.chains`, ticker + chainId)
+     * to a viem `PublicClient`. Which RPC gateway to use is THIS client's setting — RPC URLs
+     * are deliberately not part of the criteria document, so this factory is where the host
+     * maps chains to the endpoints it trusts. Return one shared client per chain (memoized),
+     * and `undefined` for a chain with no RPC configured — `createContest` /
+     * `createContestVote` then throws `MissingChainClientError` (recuse, don't miscount).
+     * See `ChainClientFactory` (src/chain/types.ts) for the full contract.
      */
     chains: ChainClientFactory;
     /** Identity. Omit for a read-only voter (renders tallies, cannot publish). */

package/dist/client/voter.js

@@ -30,7 +30,7 @@ import { CID } from "multiformats/cid";
 import { makeTally } from "../tally/tally.js";
 import { ballotTypedData } from "../signer/eip712.js";
 import { criteriaCid, TOPIC_PREFIX } from "../topic.js";
-import { ReadOnlyError, UnknownRuleError, VoterDestroyedError } from "../errors.js";
+import { MissingChainClientError, ReadOnlyError, UnknownRuleError, VoterDestroyedError } from "../errors.js";
 /**
  * The recommended cadence, in buckets, at which a client should re-publish a live vote to keep
  * it alive: half its expiry window, rounded up. A bundle is valid for `voteExpiryBuckets` after
@@ -284,7 +284,14 @@ class ContestEngine {
         this.readOnly = deps.signer === undefined;
         this.#deps = deps;
         this.#criteriaCid = criteriaCidBytes;
-        this.#chainClients = Object.fromEntries(Object.entries(criteria.requires.chains).map(([chain, config]) => [chain, deps.chains({ chain, config })]));
+        // Resolve every chain the manifest requires, eagerly: a client with no RPC configured
+        // for one of them must find out at the create seam (recuse), not on its first verify.
+        this.#chainClients = Object.fromEntries(Object.entries(criteria.requires.chains).map(([chain, config]) => {
+            const client = deps.chains({ chain, chainId: config.chainId });
+            if (client === undefined)
+                throw new MissingChainClientError(chain, config.chainId);
+            return [chain, client];
+        }));
         // The gating (`rule`) chain fixes the ballot's chainId and the tie-break seed chain.
         const rule = deps.registry[criteria.rule.type];
         if (!rule)

package/dist/errors.d.ts

@@ -22,6 +22,18 @@ export declare class UnknownRuleError extends Error {
     readonly type: string;
     constructor(slot: "rule" | "weight" | "requires", type: string);
 }
+/**
+ * Thrown by `createContest` / `createContestVote` when the criteria's dependency manifest
+ * names a chain (`requires.chains`) the host's `ChainClientFactory` cannot resolve to a
+ * client (it returned `undefined`). RPC endpoints are client-local settings, not part of
+ * the criteria document, so a client with no gateway configured for a required chain must
+ * recuse the contest rather than miscount — the chain-side twin of `UnknownRuleError`.
+ */
+export declare class MissingChainClientError extends Error {
+    readonly chain: string;
+    readonly chainId: number;
+    constructor(chain: string, chainId: number);
+}
 /**
  * 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

package/dist/errors.js

@@ -32,6 +32,26 @@ export class UnknownRuleError extends Error {
         this.name = "UnknownRuleError";
     }
 }
+/**
+ * Thrown by `createContest` / `createContestVote` when the criteria's dependency manifest
+ * names a chain (`requires.chains`) the host's `ChainClientFactory` cannot resolve to a
+ * client (it returned `undefined`). RPC endpoints are client-local settings, not part of
+ * the criteria document, so a client with no gateway configured for a required chain must
+ * recuse the contest rather than miscount — the chain-side twin of `UnknownRuleError`.
+ */
+export class MissingChainClientError extends Error {
+    chain;
+    chainId;
+    constructor(chain, chainId) {
+        super(`No chain client for "${chain}" (chainId ${chainId}), which this contest's criteria ` +
+            `requires. RPC endpoints are client settings, not part of the criteria document: ` +
+            `configure the \`chains\` factory (PubsubVoterOptions.chains) to return a viem ` +
+            `PublicClient for this chain, or recuse this contest.`);
+        this.chain = chain;
+        this.chainId = chainId;
+        this.name = "MissingChainClientError";
+    }
+}
 /**
  * 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

package/dist/schema/criteria.d.ts

@@ -30,11 +30,25 @@ export declare const VoteRangeSchema: z.ZodObject<{
 export declare const RuleRefSchema: z.ZodObject<{
     type: z.ZodString;
 }, z.core.$loose>;
-/** RPC configuration for one chain ticker. Part of the dependency manifest. */
+/**
+ * One chain the contest reads, by ticker. Part of the dependency manifest.
+ *
+ * Only the `chainId` is here — it is consensus-critical (bound into every EIP-712 ballot
+ * domain and defining which chain the rules read). RPC endpoints are deliberately NOT part
+ * of the criteria: which gateway a client trusts is client-local transport configuration
+ * (`PubsubVoterOptions.chains` maps ticker/chainId to a client), and two honest verifiers
+ * reading the same pinned block through different gateways compute identical results. Keeping
+ * URLs out means an operator can swap a dead RPC provider without changing the document's
+ * bytes — i.e. without forking the topic and orphaning the contest's votes.
+ *
+ * Strict on purpose: the topic is derived from the PARSED document, so an unknown key must
+ * fail loudly here — a plain (stripping) object would silently drop it and derive a different
+ * topic than the author's raw document implies. This also makes pre-v1 documents that still
+ * carry `rpcUrls` a loud error instead of a silent re-topic.
+ */
 export declare const ChainConfigSchema: z.ZodObject<{
     chainId: z.ZodNumber;
-    rpcUrls: z.ZodArray<z.ZodString>;
-}, z.core.$strip>;
+}, z.core.$strict>;
 /**
  * The dependency manifest. A client reads this on join and checks that it
  * implements every named rule; if not, it is too old and must recuse
@@ -44,8 +58,7 @@ export declare const RequiresSchema: z.ZodObject<{
     rules: z.ZodArray<z.ZodString>;
     chains: z.ZodRecord<z.ZodString, z.ZodObject<{
         chainId: z.ZodNumber;
-        rpcUrls: z.ZodArray<z.ZodString>;
-    }, z.core.$strip>>;
+    }, z.core.$strict>>;
 }, z.core.$strip>;
 export declare const CriteriaSchema: z.ZodObject<{
     name: z.ZodString;
@@ -67,8 +80,7 @@ export declare const CriteriaSchema: z.ZodObject<{
         rules: z.ZodArray<z.ZodString>;
         chains: z.ZodRecord<z.ZodString, z.ZodObject<{
             chainId: z.ZodNumber;
-            rpcUrls: z.ZodArray<z.ZodString>;
-        }, z.core.$strip>>;
+        }, z.core.$strict>>;
     }, z.core.$strip>;
 }, z.core.$strict>;
 export type VoteRange = z.infer<typeof VoteRangeSchema>;

package/dist/schema/criteria.js

@@ -31,10 +31,24 @@ export const VoteRangeSchema = z.object({
 export const RuleRefSchema = z.looseObject({
     type: z.string().min(1)
 });
-/** RPC configuration for one chain ticker. Part of the dependency manifest. */
-export const ChainConfigSchema = z.object({
-    chainId: z.number().int().positive(),
-    rpcUrls: z.array(z.string().min(1)).nonempty()
+/**
+ * One chain the contest reads, by ticker. Part of the dependency manifest.
+ *
+ * Only the `chainId` is here — it is consensus-critical (bound into every EIP-712 ballot
+ * domain and defining which chain the rules read). RPC endpoints are deliberately NOT part
+ * of the criteria: which gateway a client trusts is client-local transport configuration
+ * (`PubsubVoterOptions.chains` maps ticker/chainId to a client), and two honest verifiers
+ * reading the same pinned block through different gateways compute identical results. Keeping
+ * URLs out means an operator can swap a dead RPC provider without changing the document's
+ * bytes — i.e. without forking the topic and orphaning the contest's votes.
+ *
+ * Strict on purpose: the topic is derived from the PARSED document, so an unknown key must
+ * fail loudly here — a plain (stripping) object would silently drop it and derive a different
+ * topic than the author's raw document implies. This also makes pre-v1 documents that still
+ * carry `rpcUrls` a loud error instead of a silent re-topic.
+ */
+export const ChainConfigSchema = z.strictObject({
+    chainId: z.number().int().positive()
 });
 /**
  * The dependency manifest. A client reads this on join and checks that it

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bitsocial/pubsub-voting",
-  "version": "0.0.10",
+  "version": "0.1.0",
   "description": "Trustless pubsub voting over a shared libp2p/Helia node.",
   "type": "module",
   "license": "GPL-3.0-or-later",