@bitsocial/pubsub-voting 0.0.10 → 0.1.1

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)
@@ -69,7 +81,7 @@ Construction throws `MissingPubsubError`, `MissingBlockstoreError`, or `MissingF
 ```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)
+contest.on("error", (err) => showConnectivityWarning(err)); // tally chain read failed, the background verifier's RPC/resolver is down (retrying), or a deferred check evicted THIS wallet's own vote (VoteEvictedError)
 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
@@ -116,6 +128,20 @@ A community's identity is its `publicKey`. The optional `name` is the community'
 
 `publish()` on a voter built without a `signer` throws `ReadOnlyError` (and emits an `error`).
 
+#### Rejection feedback
+
+Gossipsub gives a publisher **no acceptance or rejection feedback** — a peer that drops a bundle does so silently. Since every honest peer runs the same checks this node runs, the library turns its own local verdict into the feedback the protocol can't provide, in two places:
+
+- **At `publish()`**: each vote's `community.name` is preflighted through the shared resolution cache first — a name that definitively fails (no resolver for its TLD, no record, or it resolves to a **different** `publicKey` than the vote claims) throws `InvalidCommunityNameError` before signing or joining the topic, since every verifier would silently drop that bundle anyway. A resolver that merely *throws* (registry outage) never blocks the publish — the check stays deferred to the background verifier.
+- **After `publish()` resolved**: `"succeeded"` means signed and broadcast, **not** accepted by the network. The deferred checks (the on-chain gate read, and any name resolution a preflight outage skipped) run in the background; if one evicts the bundle, the vote emits a `VoteEvictedError` on its `error` event — carrying the evicted `bundle` and the exact `verdict` any verifier would produce — and its `publishingState` flips to `"failed"` post hoc. The same error fires on the contest's `error` event, for long-lived views.
+
+```ts
+vote.on("error", (err) => {
+    if (err instanceof VoteEvictedError) console.log(err.verdict.reason); // e.g. "not admitted: rule score is 0n at block …"
+});
+await vote.publish(); // throws InvalidCommunityNameError if a carried name can't back the vote
+```
+
 ### 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:

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

@@ -41,7 +41,14 @@ export declare function republishIntervalBuckets(criteria: Criteria): number;
  * publishes each vote once and the client decides when to refresh (see
  * {@link republishIntervalBuckets} and DESIGN.md "Republishing is the client's job").
  */
-/** A vote publication's lifecycle, walked by {@link ContestVote.publish}. */
+/**
+ * A vote publication's lifecycle, walked by {@link ContestVote.publish}. `"succeeded"` means
+ * signed, admitted locally, and broadcast — NOT accepted by the network (gossipsub gives a
+ * publisher no acceptance/rejection feedback). It can therefore still flip to `"failed"`
+ * afterwards: if this node's own deferred checks — the same checks every peer runs — evict the
+ * bundle, the vote emits a `VoteEvictedError` and fails post hoc (see DESIGN.md "Background
+ * chain verification", publisher feedback).
+ */
 export type PublishingState = "stopped" | "signing" | "publishing" | "succeeded" | "failed";
 /** What {@link ContestVote.publish} resolves: the signed bundle plus a peer-reach hint. */
 export interface PublishOutcome {
@@ -86,9 +93,11 @@ export interface Contest {
      */
     on(event: "update", cb: () => void): void;
     /**
-     * Fired on a contest-level failure: the tally's chain read throws, or the background chain
+     * Fired on a contest-level failure: the tally's chain read throws, the background chain
      * verifier hits an infra-class failure (RPC/resolver down — its bundles stay pending and
-     * retry, but the degradation is surfaced here instead of silently stalling).
+     * retry, but the degradation is surfaced here instead of silently stalling), or a deferred
+     * check evicts THIS wallet's own published vote (`VoteEvictedError` — the same error the
+     * publishing `ContestVote` emits; here so a long-lived view hears it too).
      */
     on(event: "error", cb: (error: unknown) => void): void;
 }
@@ -110,13 +119,23 @@ export interface ContestVote {
      * the `VotesBundle` (whose `blockNumber` the client uses to schedule its own refresh — see
      * {@link republishIntervalBuckets}) plus `recipientCount`, the number of peers gossipsub sent
      * the vote directly to. Emits `publishingstatechange` as it goes; throws (and emits `error`) on
-     * failure, and `ReadOnlyError` with no signer. This library does not re-publish: to keep the
-     * vote alive, call `publish()` again before it expires.
+     * failure: `ReadOnlyError` with no signer, and `InvalidCommunityNameError` when a vote's
+     * carried `community.name` definitively does not resolve to its claimed `publicKey` (checked
+     * BEFORE signing or joining — every verifier drops such a bundle silently, so it is refused
+     * here instead of published into a network-wide silent drop; a resolver outage does not block
+     * the publish). This library does not re-publish: to keep the vote alive, call `publish()`
+     * again before it expires.
      */
     publish(): Promise<PublishOutcome>;
     /** Fired on each `publishingState` transition. */
     on(event: "publishingstatechange", cb: (state: PublishingState) => void): void;
-    /** Fired if publishing fails. */
+    /**
+     * Fired if publishing fails — including POST HOC, after `publish()` resolved: gossipsub
+     * peers reject a bad bundle silently, but this node runs the same deferred checks (gate
+     * chain read, name resolution) on its own publish, and if they evict it a `VoteEvictedError`
+     * fires here (and `publishingState` flips to `"failed"`) carrying the exact verdict every
+     * honest verifier would produce. See DESIGN.md "Background chain verification".
+     */
     on(event: "error", cb: (error: unknown) => void): void;
 }
 /** The factory: one set of injected dependencies, many contests. */
@@ -172,9 +191,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

@@ -23,6 +23,7 @@ import { makeAnnouncer } from "../transport/announce/node.js";
 import { encode as encodeDagCbor } from "@ipld/dag-cbor";
 import { sha256 } from "viem";
 import { makeBackgroundVerifier } from "../verify/background.js";
+import { preflightCommunityNames } from "../verify/name-preflight.js";
 import { makeAcceptedDedup } from "../transport/accepted-dedup.js";
 import { blockForBytes, decodeCheckpoint, encodeCheckpoint } from "../checkpoint/codec.js";
 import { decodeSnapshot, encodeSnapshot } from "../checkpoint/snapshot.js";
@@ -30,7 +31,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 { InvalidCommunityNameError, MissingChainClientError, ReadOnlyError, UnknownRuleError, VoteEvictedError, 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 +285,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)
@@ -341,7 +349,7 @@ class ContestEngine {
             cache: this.#cache,
             onGateVerified: (cid) => this.#settleCheck(cid, "chainVerified"),
             onNameResolved: (cid) => this.#settleCheck(cid, "nameResolved"),
-            onEvict: (cid) => this.#evictBundle(cid),
+            onEvict: (cid, verdict) => this.#evictBundle(cid, verdict),
             onError: (error) => this.#emitError(error),
             limit: (fn) => this.#backgroundLimit(fn)
         });
@@ -375,13 +383,26 @@ class ContestEngine {
      * settled bundles (never re-serve what we have not verified).
      */
     #checks = new Map();
+    /**
+     * This wallet's own published bundles still awaiting their deferred checks, keyed by CID
+     * string — the bundles whose background EVICTION must be reported instead of silent (see
+     * {@link #evictBundle} / `VoteEvictedError`; remote evictions are normal operation). An
+     * entry is dropped once its checks settle, on evict (after reporting), and on expiry prune.
+     */
+    #ownPublishes = new Map();
+    /** Per-own-CID eviction callbacks: the publishing `ContestVote` registers one at sign time. */
+    #ownEvictionCbs = new Map();
     /** Does any vote in the bundle carry a `community.name` claim (needing resolution)? */
     #carriesName(bundle) {
         return bundle.votes.some((v) => v.community.name !== undefined);
     }
-    /** Record a bundle's deferred-check state at admit: fully settled, or pending both checks. */
-    #recordChecks(cid, bundle, settled) {
-        this.#checks.set(cid.toString(), this.#carriesName(bundle) ? { chainVerified: settled, nameResolved: settled } : { chainVerified: settled });
+    /**
+     * Record a bundle's deferred-check state at admit: fully settled, pending both checks, or —
+     * for an own publish whose name preflight already resolved every carried name — pending the
+     * gate read only (`nameSettled`).
+     */
+    #recordChecks(cid, bundle, settled, nameSettled = settled) {
+        this.#checks.set(cid.toString(), this.#carriesName(bundle) ? { chainVerified: settled, nameResolved: nameSettled } : { chainVerified: settled });
     }
     /** The bundle's check state, pessimistic (all pending) if somehow unrecorded. */
     #checksFor(cid, bundle) {
@@ -404,14 +425,38 @@ class ContestEngine {
         if (!checks)
             return; // evicted or pruned while its check was in flight
         checks[key] = true;
+        // A fully settled own publish can no longer be evicted — its verdict is terminal — so
+        // its eviction-reporting entries are done (see #ownPublishes).
+        if (this.#isFullyVerified(cid))
+            this.#dropOwnTracking(cid.toString());
         this.#onStateChanged();
     }
-    /** A deferred check failed: drop the bundle (its verified predecessor, if any, wins again). */
-    #evictBundle(cid) {
+    /**
+     * A deferred check failed: drop the bundle (its verified predecessor, if any, wins again).
+     * Evicting this wallet's OWN publish is the one rejection a publisher can ever hear about —
+     * gossipsub peers drop a bad bundle silently, but this node runs the same checks (see
+     * DESIGN.md "Background chain verification") — so it is reported as a `VoteEvictedError`
+     * through the publishing `ContestVote` and the contest `error` event instead of silent.
+     */
+    #evictBundle(cid, verdict) {
         this.#crdt.remove(cid);
-        this.#checks.delete(cid.toString());
+        const key = cid.toString();
+        this.#checks.delete(key);
+        const own = this.#ownPublishes.get(key);
+        if (own) {
+            const error = new VoteEvictedError(own, verdict);
+            const notifyVote = this.#ownEvictionCbs.get(key);
+            this.#dropOwnTracking(key);
+            notifyVote?.(error);
+            this.#emitError(error);
+        }
         this.#onStateChanged();
     }
+    /** Forget an own publish's eviction-reporting entries (settled, evicted, or expired). */
+    #dropOwnTracking(key) {
+        this.#ownPublishes.delete(key);
+        this.#ownEvictionCbs.delete(key);
+    }
     #emitError(error) {
         for (const cb of [...this.#errorListeners])
             cb(error);
@@ -520,7 +565,9 @@ class ContestEngine {
         if (this.#crdt.nodeCount() > 0) {
             await this.#refreshBucket();
             for (const removed of await this.#crdt.prune(this.#currentBucketCache)) {
-                this.#checks.delete(removed.toString());
+                const key = removed.toString();
+                this.#checks.delete(key);
+                this.#dropOwnTracking(key); // expiry is decay, not an eviction — no error
             }
         }
         return this.#tally.compute();
@@ -890,12 +937,33 @@ class ContestEngine {
         if (wasJoined)
             this.#deps.onTopicLeft();
     }
+    /**
+     * Publish-time community-name preflight (see verify/name-preflight.ts): throws
+     * `InvalidCommunityNameError` when a carried name definitively fails to resolve to its
+     * vote's claimed key — before signing, before the caller joins the topic — because every
+     * verifier would silently drop such a bundle. Returns whether every carried name settled
+     * (false = a resolver outage skipped one; the background verifier still owns that check).
+     */
+    async preflightNames(votes) {
+        const result = await preflightCommunityNames({
+            votes,
+            nameResolvers: this.#deps.nameResolvers,
+            cache: this.#deps.nameResolutionCache
+        });
+        if (!result.ok) {
+            throw new InvalidCommunityNameError(result.communityName, result.claimedPublicKey, result.resolvedPublicKey, result.reason);
+        }
+        return result.settled;
+    }
     /**
      * Sign the votes into a bundle for the current bucket boundary block (the block every verifier
      * reads at), add it to the CRDT, and return the bundle plus its encoded block bytes for
-     * broadcast. Throws `ReadOnlyError` with no signer.
+     * broadcast. Throws `ReadOnlyError` with no signer. `namesSettled` carries the
+     * {@link preflightNames} outcome (default false: name checks still owed to the background
+     * verifier); `onEvicted` is told if a deferred check later evicts THIS bundle — registered
+     * here, before the background verifier can possibly settle, so the report cannot be missed.
      */
-    async signVote(votes) {
+    async signVote(votes, opts = {}) {
         const signer = this.#deps.signer;
         if (signer === undefined)
             throw new ReadOnlyError();
@@ -911,8 +979,12 @@ class ContestEngine {
         // Own bundles take the same deferred path as a chased checkpoint's: admitted
         // provisionally, then confirmed (or evicted) by the background gate read — so an
         // ineligible wallet's local tally does not silently disagree with the network's, and
-        // our checkpoint never serves a vote we have not verified (even our own).
-        this.#recordChecks(cid, bundle, false);
+        // our checkpoint never serves a vote we have not verified (even our own). A name the
+        // preflight already resolved is recorded settled, so it renders verified immediately.
+        this.#recordChecks(cid, bundle, false, opts.namesSettled ?? false);
+        this.#ownPublishes.set(cid.toString(), bundle);
+        if (opts.onEvicted)
+            this.#ownEvictionCbs.set(cid.toString(), opts.onEvicted);
         this.#background.enqueue([{ cid, bundle }]);
         this.#onStateChanged();
         return { bundle, encoded: encodeBundle(bundle) };
@@ -1259,6 +1331,13 @@ class ContestVotePublication {
     #errorCbs = [];
     #state = "stopped";
     #bundle;
+    /**
+     * True once the background verifier evicted the current publish's bundle. The eviction can
+     * land WHILE `publish()` is still broadcasting (the deferred checks run concurrently), and
+     * its `"failed"` is terminal for this attempt — the in-flight publish must not stomp it
+     * with `"publishing"`/`"succeeded"`. Reset by the next `publish()` call.
+     */
+    #evicted = false;
     constructor(engine, votes) {
         this.#engine = engine;
         this.contestId = engine.criteria.contestId;
@@ -1291,13 +1370,33 @@ class ContestVotePublication {
             throw error;
         }
         try {
+            // Name preflight, also before joining: a vote whose carried community name
+            // definitively fails to resolve to its claimed key would be silently dropped by
+            // every verifier, so it is refused here (`InvalidCommunityNameError`) instead of
+            // broadcast. A resolver outage does not block the publish (namesSettled: false —
+            // the background verifier owns the deferred check).
+            const namesSettled = await this.#engine.preflightNames(this.votes);
             await this.#engine.join();
+            this.#evicted = false;
             this.#setState("signing");
-            const { bundle, encoded } = await this.#engine.signVote([...this.votes]);
+            const { bundle, encoded } = await this.#engine.signVote([...this.votes], {
+                namesSettled,
+                // The one rejection a publisher can hear about (peers drop silently): our own
+                // node's deferred checks evicting this bundle. Usually post hoc — publish() has
+                // already resolved — so it surfaces as `error` + `publishingState: "failed"`.
+                onEvicted: (error) => {
+                    this.#evicted = true;
+                    this.#fail(error);
+                }
+            });
             this.#bundle = bundle;
-            this.#setState("publishing");
+            if (!this.#evicted)
+                this.#setState("publishing");
             const { recipientCount } = await this.#engine.broadcastBundle(encoded);
-            this.#setState("succeeded");
+            // An eviction that landed mid-broadcast already failed this attempt; the outcome
+            // still resolves (the bundle DID hit the wire) but the state stays "failed".
+            if (!this.#evicted)
+                this.#setState("succeeded");
             return { bundle, recipientCount };
         }
         catch (error) {

package/dist/errors.d.ts

@@ -1,3 +1,5 @@
+import type { VotesBundle } from "./schema/votes.js";
+import type { VerifyFail } from "./verify/types.js";
 /**
  * Library error types.
  *
@@ -22,6 +24,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
@@ -79,3 +93,51 @@ export declare class DuplicateContestIdError extends Error {
 export declare class ReadOnlyError extends Error {
     constructor();
 }
+/**
+ * Thrown by `ContestVote.publish()` when a vote carries a `community.name` that definitively
+ * fails the publish-time preflight (see verify/name-preflight.ts): no configured resolver
+ * handles it, it resolves to no record, or it resolves to a DIFFERENT key than the vote
+ * claims. Every honest verifier runs the same check and drops such a bundle without telling
+ * the publisher (gossipsub has no rejection feedback), so the vote is refused here — before
+ * signing, before joining the topic — instead of being published into a silent network-wide
+ * drop. Fix the name (or the claimed `publicKey`) and publish again. A resolver that merely
+ * THREW (registry outage) does not throw this: the vote publishes and the background verifier
+ * settles the check, surfacing a `VoteEvictedError` if it turns out bad.
+ */
+export declare class InvalidCommunityNameError extends Error {
+    /** The offending `community.name`. */
+    readonly communityName: string;
+    /** The `community.publicKey` the vote claims the name points at. */
+    readonly claimedPublicKey: string;
+    /** What the registry resolved the name to; `undefined` for no-resolver / no-record. */
+    readonly resolvedPublicKey: string | undefined;
+    constructor(
+    /** The offending `community.name`. */
+    communityName: string, 
+    /** The `community.publicKey` the vote claims the name points at. */
+    claimedPublicKey: string, 
+    /** What the registry resolved the name to; `undefined` for no-resolver / no-record. */
+    resolvedPublicKey: string | undefined, reason: string);
+}
+/**
+ * Emitted (never thrown) when a deferred network check EVICTS this wallet's own published
+ * vote: the background verifier read the gate rule as `0n` at the vote's sample block, or its
+ * carried community name did not check out (see DESIGN.md "Background chain verification").
+ * `publish()` resolves on the offline checks, so an own vote that fails a deferred check
+ * would otherwise just silently vanish from the local tally — while every honest peer,
+ * running the same checks, drops it with no feedback (gossipsub has no rejection channel).
+ * This error is that missing feedback, built from the local verdict: it fires on the
+ * publishing `ContestVote`'s `error` event (flipping its `publishingState` to `"failed"`)
+ * and on the contest's `error` event. Carries the evicted bundle and the exact verdict.
+ */
+export declare class VoteEvictedError extends Error {
+    /** The signed bundle that was evicted (the one `publish()` resolved with). */
+    readonly bundle: VotesBundle;
+    /** The failing verdict, with the same `reason` wording every verifier produces. */
+    readonly verdict: VerifyFail;
+    constructor(
+    /** The signed bundle that was evicted (the one `publish()` resolved with). */
+    bundle: VotesBundle, 
+    /** The failing verdict, with the same `reason` wording every verifier produces. */
+    verdict: VerifyFail);
+}

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
@@ -124,3 +144,64 @@ export class ReadOnlyError extends Error {
         this.name = "ReadOnlyError";
     }
 }
+/**
+ * Thrown by `ContestVote.publish()` when a vote carries a `community.name` that definitively
+ * fails the publish-time preflight (see verify/name-preflight.ts): no configured resolver
+ * handles it, it resolves to no record, or it resolves to a DIFFERENT key than the vote
+ * claims. Every honest verifier runs the same check and drops such a bundle without telling
+ * the publisher (gossipsub has no rejection feedback), so the vote is refused here — before
+ * signing, before joining the topic — instead of being published into a silent network-wide
+ * drop. Fix the name (or the claimed `publicKey`) and publish again. A resolver that merely
+ * THREW (registry outage) does not throw this: the vote publishes and the background verifier
+ * settles the check, surfacing a `VoteEvictedError` if it turns out bad.
+ */
+export class InvalidCommunityNameError extends Error {
+    communityName;
+    claimedPublicKey;
+    resolvedPublicKey;
+    constructor(
+    /** The offending `community.name`. */
+    communityName, 
+    /** The `community.publicKey` the vote claims the name points at. */
+    claimedPublicKey, 
+    /** What the registry resolved the name to; `undefined` for no-resolver / no-record. */
+    resolvedPublicKey, reason) {
+        super(`Cannot publish this vote: ${reason}. Every verifier checks a carried community ` +
+            `name against its registry and silently drops a bundle whose name does not ` +
+            `resolve to the claimed publicKey, so this vote would never be counted. Fix ` +
+            `the name (or the claimed publicKey), or drop the name from the vote, and ` +
+            `publish again.`);
+        this.communityName = communityName;
+        this.claimedPublicKey = claimedPublicKey;
+        this.resolvedPublicKey = resolvedPublicKey;
+        this.name = "InvalidCommunityNameError";
+    }
+}
+/**
+ * Emitted (never thrown) when a deferred network check EVICTS this wallet's own published
+ * vote: the background verifier read the gate rule as `0n` at the vote's sample block, or its
+ * carried community name did not check out (see DESIGN.md "Background chain verification").
+ * `publish()` resolves on the offline checks, so an own vote that fails a deferred check
+ * would otherwise just silently vanish from the local tally — while every honest peer,
+ * running the same checks, drops it with no feedback (gossipsub has no rejection channel).
+ * This error is that missing feedback, built from the local verdict: it fires on the
+ * publishing `ContestVote`'s `error` event (flipping its `publishingState` to `"failed"`)
+ * and on the contest's `error` event. Carries the evicted bundle and the exact verdict.
+ */
+export class VoteEvictedError extends Error {
+    bundle;
+    verdict;
+    constructor(
+    /** The signed bundle that was evicted (the one `publish()` resolved with). */
+    bundle, 
+    /** The failing verdict, with the same `reason` wording every verifier produces. */
+    verdict) {
+        super(`This wallet's published vote failed a deferred verification check and was ` +
+            `evicted from the local tally: ${verdict.reason}. Honest peers run the same ` +
+            `checks, so the network will not count this vote either. Fix the cause and ` +
+            `publish again.`);
+        this.bundle = bundle;
+        this.verdict = verdict;
+        this.name = "VoteEvictedError";
+    }
+}

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/dist/verify/name-preflight.d.ts

@@ -0,0 +1,60 @@
+import type { Vote } from "../schema/votes.js";
+import type { NameResolver } from "../chain/types.js";
+import { type NameResolutionCache } from "./name-resolution-cache.js";
+/**
+ * Publish-time community-name preflight — the publisher-side twin of the verify pipeline's
+ * step 4 (see bundle.ts). Gossipsub has no rejection-feedback channel: a peer that drops a
+ * bundle never tells the publisher why (or that it dropped it at all), so the only "clear
+ * error" a publisher can ever get is from running the same checks locally BEFORE the vote
+ * hits the wire. A vote naming a community whose name does not check out is guaranteed to be
+ * dropped by every honest verifier, so publishing it is pure waste; failing fast here turns
+ * that silent network-wide drop into an immediate, explainable publish error.
+ *
+ * The failure split mirrors the pipeline's `reject`/`ignore` philosophy, adapted to the
+ * publisher (who, unlike a relayer, can always just fix the vote and retry):
+ *   - definitive from this node's view — no resolver handles the TLD, the name has no record,
+ *     or it resolves to a DIFFERENT key than the vote claims — fails the preflight; every
+ *     verifier sharing this node's view would drop the bundle the same way.
+ *   - transient — the resolver THREW (registry RPC down) — passes the preflight with
+ *     `settled: false`: a resolver outage must not block voting (the same reason the
+ *     background verifier retries instead of evicting on a throw), and the deferred check
+ *     settles or evicts the bundle once the resolver recovers.
+ *
+ * Resolutions ride the shared {@link NameResolutionCache} (the pkc-js rule, 1-hour max-age),
+ * so a preflight-resolved name is a cache hit for the background verifier's own pass — the
+ * preflight adds at most one live registry read per name per hour, not a second read path.
+ */
+/** One name that definitively failed the preflight (the first failure aborts the scan). */
+export interface NamePreflightFailure {
+    ok: false;
+    communityName: string;
+    /** The `community.publicKey` the vote claims the name points at. */
+    claimedPublicKey: string;
+    /** What the registry actually resolved the name to; absent for no-resolver / no-record. */
+    resolvedPublicKey?: string;
+    /** Human-readable cause, same wording as the verify pipeline's step-4 verdicts. */
+    reason: string;
+}
+export type NamePreflightResult = {
+    ok: true;
+    /**
+     * True when every carried name resolved to its claimed key right now; false when at
+     * least one resolution was SKIPPED on a resolver throw (transient outage) and is
+     * still owed to the background verifier. Feeds the publisher's own
+     * `nameResolved` check state, so a preflight-settled vote renders verified
+     * immediately instead of flashing a pending row.
+     */
+    settled: boolean;
+} | NamePreflightFailure;
+/**
+ * Resolve every distinct `community.name` carried by `votes` and check each against its
+ * vote's claimed `publicKey`. Returns the first definitive failure, or `ok` with whether
+ * every name settled (see module doc for the definitive/transient split). Votes carrying no
+ * name are free: no resolver is consulted and `{ ok: true, settled: true }` returns
+ * synchronously.
+ */
+export declare function preflightCommunityNames(opts: {
+    votes: readonly Vote[];
+    nameResolvers: NameResolver[];
+    cache: NameResolutionCache | undefined;
+}): Promise<NamePreflightResult>;

package/dist/verify/name-preflight.js

@@ -0,0 +1,52 @@
+import { resolveNameThroughCache } from "./name-resolution-cache.js";
+/**
+ * Resolve every distinct `community.name` carried by `votes` and check each against its
+ * vote's claimed `publicKey`. Returns the first definitive failure, or `ok` with whether
+ * every name settled (see module doc for the definitive/transient split). Votes carrying no
+ * name are free: no resolver is consulted and `{ ok: true, settled: true }` returns
+ * synchronously.
+ */
+export async function preflightCommunityNames(opts) {
+    const { votes, nameResolvers, cache } = opts;
+    let settled = true;
+    for (const v of votes) {
+        const name = v.community.name;
+        if (!name)
+            continue;
+        const resolver = nameResolvers.find((r) => r.canResolve({ name }));
+        if (!resolver) {
+            return {
+                ok: false,
+                communityName: name,
+                claimedPublicKey: v.community.publicKey,
+                reason: `no resolver handles community name "${name}"`
+            };
+        }
+        let record;
+        try {
+            record = await resolveNameThroughCache({ resolver, name, cache });
+        }
+        catch {
+            settled = false; // transient registry outage — never blocks a publish
+            continue;
+        }
+        if (!record) {
+            return {
+                ok: false,
+                communityName: name,
+                claimedPublicKey: v.community.publicKey,
+                reason: `community name "${name}" does not resolve`
+            };
+        }
+        if (record.publicKey !== v.community.publicKey) {
+            return {
+                ok: false,
+                communityName: name,
+                claimedPublicKey: v.community.publicKey,
+                resolvedPublicKey: record.publicKey,
+                reason: `community name "${name}" resolves to ${record.publicKey}, not the claimed ${v.community.publicKey}`
+            };
+        }
+    }
+    return { ok: true, settled };
+}

package/package.json

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