@bitsocial/pubsub-voting 0.5.0 → 0.6.0

package/README.md

@@ -34,13 +34,12 @@ See [DESIGN.md](./DESIGN.md) for the full rationale, including how this resists
 
 ## 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`:
+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`. **Identity is not one of the seams**: the voting wallet (`VoteSigner`) belongs to each ballot, passed to `createContestVote`, so one voter on the host's shared node publishes for as many wallets as the host holds keys for — and a client that only renders tallies never touches key material.
 
 | 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 | resolves the chain a contest counts in (`{ chainId }`, from `criteria.bucketChainId`) to a viem `PublicClient`; every gate rule and the weight rule read through it. **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 carries a multicall3 deployment in its viem `chain` config and serves **historical state at least `voteExpiryBuckets × blocksPerBucket` blocks behind head** (the v1 gate reads the head first, but falls back to the block a ballot names — see [Custom rules](#custom-rules)); 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 |
@@ -78,7 +77,6 @@ const viemChainFactory = (): ChainClientFactory => {
 const voter = new PubsubVoter({
   helia,                        // the host's Helia node; needs a gossipsub service at libp2p.services.pubsub + a blockstore
   chains: viemChainFactory(),   // ({ 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)
   httpRouterUrls: [             // optional, SEEDERS ONLY (publicly reachable node): announce provider
@@ -89,7 +87,7 @@ const voter = new PubsubVoter({
 
 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)
+### Read a tally reactively
 
 `createContest` mints a per-contest read object; `update()` starts syncing and it emits `update` (carrying a fresh `tally`) and `error`, just like a pkc-js `community`:
 
@@ -176,31 +174,56 @@ A cold join **renders fast and refines**: checkpoint bundles are admitted after
 
 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)
+### Publish or withdraw a vote
 
-`createContestVote` mints a publishable ballot; `publish()` signs and broadcasts it once and emits `publishingstatechange`, like a pkc-js publication:
+`createContestVote` mints a publishable ballot; `publish()` signs and broadcasts it once and emits `publishingstatechange`, like a pkc-js publication. The `signer` is the ballot's — the wallet that holds the Pass and whose recovered address *is* the voter:
 
 ```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
+const vote = await voter.createContestVote({
+  criteria,
+  votes: [{ community: { publicKey: "12D3KooW..." }, vote: 1 }],
+  signer: mySigner                                                // VoteSigner: address() + signBallot()
+});
+vote.on("publishingstatechange", (state) => console.log(state)); // stopped → signing → publishing → published, then verified-locally and/or verified-by-peer (or failed)
+const { bundle, cid, recipientCount } = await vote.publish();     // the signed VotesBundle, its CID, and how many peers gossipsub sent it directly to
+vote.signer === mySigner;                                         // the ballot carries the wallet it was minted with
 
 // Withdraw (active): publish an empty ballot; it supersedes the prior vote under LWW.
-await (await voter.createContestVote({ criteria, votes: [] })).publish();
+await (await voter.createContestVote({ criteria, votes: [], signer: mySigner })).publish();
 ```
 
+A ballot is required to name its wallet, so a client that holds no key simply never mints one — there is no read-only mode to check, and nothing on an unpublished ballot to render. Two wallets on one voter are two `createContestVote` calls with two signers; the CRDT keys them apart by recovered address, so both land in the tally.
+
 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`).
-
 #### 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.
+- **After `publish()` resolved**: `"published"` 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.
+
+The positive verdicts are states too, so a client never has to infer "it counted" from the absence of an error:
+
+- `"verified-locally"` — our own deferred checks came back clean for this bundle. Still our verdict, but every honest peer runs byte-identical checks, so it is the strongest inference available without hearing from anyone.
+- `"verified-by-peer"` — a peer advertised a checkpoint containing this bundle. A node serves only fully verified bundles in its own checkpoint, so an honest peer including it implies that peer verified it too; what is *observed* is that somebody other than us is keeping the vote.
+
+The two are independent outcomes of two asynchronous races, not a sequence: a peer can serve our bundle back before our own gate read returns, in which case `"verified-by-peer"` is reached directly and `"verified-locally"` is never emitted. Peer evidence is the stronger of the two, so it is never walked back to the local verdict arriving late. Treat both as terminal-positive; do not wait for `"verified-locally"` before `"verified-by-peer"`.
+
+Both are readable from the contest by bundle CID, which is how a restored vote asks after a reload — the publishing `ContestVote` is long gone by then, but the vote lives for `voteExpiryBuckets`. Persist `PublishOutcome.cid` and ask with it:
+
+```ts
+contest.checksFor(cid);          // { chainVerified, nameResolved? } — or undefined if not held (never admitted, evicted, expired)
+contest.checkpointPeersFor(cid); // peer ids seen serving OUR bundle back in their checkpoint (own bundles only; a lower bound)
+```
+
+`checksFor` needs nothing extra: the checks are recorded on every admit path, including the snapshot restore. **`checkpointPeersFor` does**, because the engine cannot recognise a bundle it did not sign — the signer belongs to the publication, not the contest, so a restored bundle looks like any other wallet's. A client that persisted the CID re-arms attribution once, after `update()`:
+
+```ts
+contest.trackOwnBundle(cid); // idempotent; attribution runs from here forward, not backwards
+```
 
 ```ts
 vote.on("error", (err) => {
@@ -211,7 +234,7 @@ await vote.publish(); // throws InvalidCommunityNameError if a carried name can'
 
 ### 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:
+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 (with the same signer); 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";
@@ -245,7 +268,7 @@ There is no separate seeder API: a node that joins a topic (via `update()` or `p
 `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 });
+const voter = new PubsubVoter({ helia, chains });
 // … create + update contests, app runs …
 await voter.destroy();   // terminal: leave all topics, unregister the responder, forbid reuse
 ```

package/dist/client/voter.d.ts

@@ -3,6 +3,8 @@ import { type Vote, type VotesBundle } from "../schema/votes.js";
 import type { ChainClient, ChainClientFactory, NameResolver } from "../chain/types.js";
 import type { HeliaInstance } from "../transport/types.js";
 import type { RuleRegistry } from "../rules/types.js";
+import type { BundleChecks } from "../verify/types.js";
+import { CID } from "multiformats/cid";
 import type { ContestTally } from "../tally/types.js";
 import type { VoteSigner } from "../signer/types.js";
 /**
@@ -17,7 +19,7 @@ import type { VoteSigner } from "../signer/types.js";
  * `blockNumber` on a published `VotesBundle`, and `criteria.voteExpiryBuckets` /
  * `criteria.blocksPerBucket` are what a client uses to schedule its own refreshes: a vote sampled
  * at bucket `b` expires once the current bucket exceeds `b + voteExpiryBuckets`; refresh by
- * calling `createContestVote({ criteria, votes }).publish()` again before then.
+ * calling `createContestVote({ criteria, votes, signer }).publish()` again before then.
  */
 export declare function republishIntervalBuckets(criteria: Criteria): number;
 /**
@@ -42,18 +44,41 @@ export declare function republishIntervalBuckets(criteria: Criteria): number;
  * {@link republishIntervalBuckets} and DESIGN.md "Republishing is the client's job").
  */
 /**
- * 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).
+ * A vote publication's lifecycle, walked by {@link ContestVote.publish}, then continued by the
+ * deferred checks that settle after it resolves. Three states describe a bundle that is on the
+ * wire, and they are deliberately not synonyms:
+ *
+ *   - `"published"` — signed, admitted to our OWN local set, and broadcast. It says what we did,
+ *     and nothing about anyone else: gossipsub gives a publisher no acceptance feedback, so an
+ *     ineligible wallet reaches this state exactly like an eligible one. (This state was called
+ *     `"succeeded"` before 0.6.0, a name borrowed from pkc-js — where a publish really is
+ *     acknowledged, by the challenge exchange. Nothing acknowledges a vote here.)
+ *   - `"verified-locally"` — OUR deferred checks came back clean for this bundle: the gate rule
+ *     scored the wallet `> 0n` at its bucket block, and every carried `community.name` resolved
+ *     to the key it claimed. Still our own verdict — but every honest peer runs byte-identical
+ *     checks, so it is the strongest inference a publisher can draw without hearing from anyone.
+ *   - `"verified-by-peer"` — a peer advertised a checkpoint that contained this bundle. Since a
+ *     node serves only fully verified bundles in its own checkpoint, an honest peer including it
+ *     implies that peer verified it too; what we OBSERVE is that somebody other than us kept the
+ *     vote. See {@link Contest.checkpointPeersFor} for who, and its caveats.
+ *
+ * `"failed"` is the counterpart of `"verified-locally"`: if the deferred checks EVICT the bundle
+ * the vote emits a `VoteEvictedError` and fails post hoc (see DESIGN.md "Background chain
+ * verification", publisher feedback). The two verified states are reached in order and neither is
+ * reached after `"failed"` — an evicted bundle is gone from the set that checkpoints are cut from.
  */
-export type PublishingState = "stopped" | "signing" | "publishing" | "succeeded" | "failed";
+export type PublishingState = "stopped" | "signing" | "publishing" | "published" | "verified-locally" | "verified-by-peer" | "failed";
 /** What {@link ContestVote.publish} resolves: the signed bundle plus a peer-reach hint. */
 export interface PublishOutcome {
     /** The signed bundle; its `blockNumber` drives the client's own refresh schedule. */
     readonly bundle: VotesBundle;
+    /**
+     * The bundle's CID — the key its deferred-check state and peer attribution are tracked
+     * under. Worth persisting alongside a stored vote: after a reload the `ContestVote` that
+     * published it is gone, and this is what {@link Contest.checksFor} /
+     * {@link Contest.checkpointPeersFor} are asked with.
+     */
+    readonly cid: CID;
     /**
      * How many peers gossipsub sent this vote *directly* to — first-hop fan-out, not total network
      * reach and not an acceptance confirmation (each recipient still runs the forward-gate before
@@ -182,6 +207,47 @@ export interface Contest {
     checkEligibility(args: {
         address: string;
     }): Promise<EligibilityResult>;
+    /**
+     * The deferred-check state of one bundle by CID, or `undefined` if this contest is not
+     * holding that bundle (never admitted, evicted, or expired — the three are not
+     * distinguishable here, and none of them means "counted").
+     *
+     * The publisher's question after a reload. A `ContestVote` reports its own bundle's progress
+     * through `publishingstatechange`, but that object dies with the page, while a vote lives for
+     * `voteExpiryBuckets` — so a tab that restored a vote from its own storage asks here instead,
+     * with the CID from {@link PublishOutcome.cid}.
+     *
+     * `{ chainVerified: true, nameResolved: true | undefined }` is the fully settled state (the
+     * same condition that drives `"verified-locally"`). `chainVerified: false` means NOT YET
+     * READ, never "failed" — a failed gate evicts the bundle, and this returns `undefined`.
+     */
+    checksFor(cid: CID): BundleChecks | undefined;
+    /**
+     * The peers seen advertising a checkpoint that contained `cid` — for THIS wallet's own
+     * published bundles only (see DESIGN.md "Checkpoints"). Empty for anything else, including
+     * other wallets' bundles, which this node deliberately does not index.
+     *
+     * What it proves, exactly: a node serves only fully verified bundles in its own checkpoint,
+     * so an honest peer including ours implies that peer verified it too — but honesty is not
+     * provable, and a peer may serve whatever it likes. So read this as evidence of RETENTION
+     * and propagation ("somebody other than us is keeping this vote"), and only inferentially of
+     * verification. It is also a lower bound in a second way: it counts peers whose checkpoints
+     * we happened to chase, not every peer holding the vote.
+     */
+    checkpointPeersFor(cid: CID): string[];
+    /**
+     * Declare that `cid` is one of THIS client's own published bundles, so peer-checkpoint
+     * attribution starts tracking it. Only needed after a restart: within one session
+     * `publish()` registers its own bundle, but the engine cannot recognise a bundle it did not
+     * sign — the signer belongs to the publication, not to the contest, and a restored bundle
+     * arrives through the snapshot like any other wallet's.
+     *
+     * So a client that persisted {@link PublishOutcome.cid} calls this after `update()` to
+     * re-arm {@link checkpointPeersFor}. Attribution runs from the call forward, not backwards:
+     * the first peer credited is the next one seen advertising a checkpoint that holds the
+     * bundle — at most one heartbeat interval away on a live topic. Idempotent.
+     */
+    trackOwnBundle(cid: CID): void;
     /**
      * Fired when incoming votes change the state; `tally` carries the freshly recomputed
      * ranking. Background check settlements fire it too: a cold join emits a first tally with
@@ -206,21 +272,34 @@ export interface ContestVote {
     readonly topic: string;
     /** The votes this ballot will sign and broadcast (empty array = a withdrawal). */
     readonly votes: readonly Vote[];
+    /**
+     * The wallet that signs this ballot. Identity is per-ballot, not per-voter: one
+     * `PubsubVoter` on the host's shared node publishes for as many wallets as the host holds
+     * keys for, and the address recovered from the signature is the only voter identity there
+     * is (see DESIGN.md "Identity: the voting wallet, nothing else").
+     */
+    readonly signer: VoteSigner;
     /** Where in the publish lifecycle this ballot is. */
     readonly publishingState: PublishingState;
     /** The signed bundle, once `publish()` has produced it (`undefined` before then). */
     readonly bundle: VotesBundle | undefined;
+    /**
+     * This ballot's deferred-check state — which of the two network checks have settled — or
+     * `undefined` before it is signed, and once the bundle has left the working set (evicted or
+     * expired). The detail behind `"verified-locally"`, for a UI that wants to say WHICH check is
+     * still outstanding rather than just "pending".
+     */
+    readonly checks: BundleChecks | undefined;
     /**
      * Sign the votes into a bundle for the current bucket, add it to the local CRDT, and broadcast
      * it once as a live delta. Joins the topic first if needed. Resolves a {@link PublishOutcome}:
      * 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: `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()`
+     * failure: `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>;
@@ -237,8 +316,6 @@ export interface ContestVote {
 }
 /** The factory: one set of injected dependencies, many contests. */
 export interface VoteClient {
-    /** True when constructed without a signer: every contest is read-only. */
-    readonly readOnly: boolean;
     /**
      * Create the reactive read view for one contest from its full criteria document. The document
      * is strictly validated (`CriteriaSchema` + the rule registry — an unimplemented rule throws
@@ -253,10 +330,16 @@ export interface VoteClient {
      * Create a publishable ballot for one contest, validated and addressed exactly like
      * `createContest`. Each call returns a fresh `ContestVote` over the shared per-topic engine;
      * pass `votes: []` to build a withdrawal.
+     *
+     * The `signer` is per-ballot, and required. Identity belongs to the vote rather than to the
+     * client, so one voter on the host's shared node can publish for several wallets; and a
+     * ballot that cannot be signed has nothing to show (every other field on it is
+     * publish-derived), so reading a contest is `createContest`'s job, not this one's.
      */
     createContestVote(args: {
         criteria: Criteria;
         votes: Vote[];
+        signer: VoteSigner;
     }): Promise<ContestVote>;
     /**
      * Leave every topic this client joined, resetting each read view so it can `update()` again.
@@ -297,8 +380,6 @@ export interface PubsubVoterOptions {
      * See `ChainClientFactory` (src/chain/types.ts) for the full contract.
      */
     chains: ChainClientFactory;
-    /** Identity. Omit for a read-only voter (renders tallies, cannot publish). */
-    signer?: VoteSigner;
     /** Rule overrides that shadow built-ins by `type` (a flat `type -> rule` map). */
     rules?: RuleRegistry;
     /**
@@ -379,13 +460,13 @@ export declare function makeHeadReader(): (chain: ChainClient) => Promise<bigint
 export declare class PubsubVoter implements VoteClient {
     #private;
     constructor(options: PubsubVoterOptions);
-    get readOnly(): boolean;
     createContest(args: {
         criteria: Criteria;
     }): Promise<Contest>;
     createContestVote(args: {
         criteria: Criteria;
         votes: Vote[];
+        signer: VoteSigner;
     }): Promise<ContestVote>;
     stop(): Promise<void>;
     destroy(): Promise<void>;

package/dist/client/voter.js

@@ -31,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 { InvalidCommunityNameError, MissingChainClientError, ReadOnlyError, UnknownRuleError, VoteEvictedError, VoterDestroyedError } from "../errors.js";
+import { InvalidCommunityNameError, MissingChainClientError, 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
@@ -44,7 +44,7 @@ import { InvalidCommunityNameError, MissingChainClientError, ReadOnlyError, Unkn
  * `blockNumber` on a published `VotesBundle`, and `criteria.voteExpiryBuckets` /
  * `criteria.blocksPerBucket` are what a client uses to schedule its own refreshes: a vote sampled
  * at bucket `b` expires once the current bucket exceeds `b + voteExpiryBuckets`; refresh by
- * calling `createContestVote({ criteria, votes }).publish()` again before then.
+ * calling `createContestVote({ criteria, votes, signer }).publish()` again before then.
  */
 export function republishIntervalBuckets(criteria) {
     return Math.ceil(criteria.voteExpiryBuckets / 2);
@@ -165,6 +165,14 @@ const CHASE_SESSION_PROVIDER_HEADROOM = 1;
  * cannot grow memory.
  */
 const PEER_ROOTS_MAX = 256;
+/**
+ * How many distinct chased roots we remember the contents of, for peer-checkpoint attribution
+ * ({@link ContestEngine.checkpointPeersFor}). Bounded for the same reason as {@link PEER_ROOTS_MAX}:
+ * a busy topic mints a new root on every admitted vote, so an unbounded index would grow with
+ * traffic forever. Forgetting a root only costs attribution for peers still advertising it — the
+ * next chase of a newer root re-establishes it.
+ */
+const DECODED_ROOTS_MAX = 64;
 /**
  * How long a gating-chain head read stays fresh (ms) for the gate's freshness guard. Steady-
  * state votes cost no read (they resolve against the cached bucket); only a look-ahead bundle
@@ -530,7 +538,6 @@ function hexToBytes(hex) {
 class ContestEngine {
     criteria;
     topic;
-    readOnly;
     #deps;
     #criteriaCid;
     /** The contest's chain id (`criteria.bucketChainId`), bound into every ballot signature. */
@@ -598,7 +605,6 @@ class ContestEngine {
     constructor(criteria, topic, criteriaCidBytes, deps) {
         this.criteria = criteria;
         this.topic = topic;
-        this.readOnly = deps.signer === undefined;
         this.#deps = deps;
         this.#criteriaCid = criteriaCidBytes;
         // The contest's ONE chain (`bucketChainId`): it fixes the ballot's chainId, the blocks the
@@ -721,6 +727,45 @@ class ContestEngine {
     #ownPublishes = new Map();
     /** Per-own-CID eviction callbacks: the publishing `ContestVote` registers one at sign time. */
     #ownEvictionCbs = new Map();
+    /**
+     * Per-own-CID verification callbacks — the positive counterpart of {@link #ownEvictionCbs},
+     * registered by the publishing `ContestVote` at sign time and fired once every deferred check
+     * on that bundle has settled clean.
+     */
+    #ownVerifiedCbs = new Map();
+    /**
+     * Per-own-CID first-peer-checkpoint callbacks. Fires once — the state it drives has no
+     * degrees, and a second peer holding the vote is not a new fact about the publish.
+     */
+    #ownCheckpointCbs = new Map();
+    /**
+     * Every bundle CID this wallet published that is still in the working set. Unlike
+     * {@link #ownPublishes} — which exists only to report an eviction and is dropped the moment
+     * the checks settle — this outlives verification, because peer-checkpoint attribution keeps
+     * mattering afterwards: a bundle stays live for `voteExpiryBuckets` and peers go on
+     * re-serving it, so "who else kept my vote" is a longer-lived question than "is it valid".
+     * Dropped on eviction and on expiry prune.
+     */
+    #ownCids = new Set();
+    /**
+     * Roots we decoded → which of OUR CIDs that checkpoint contained. Kept so a peer that
+     * advertises an ALREADY-decoded root is attributed without re-chasing it (the common case:
+     * many peers converge on one root). Bounded by {@link DECODED_ROOTS_MAX}, oldest evicted first.
+     */
+    #decodedRoots = new Map();
+    /**
+     * Own CID → the peers seen advertising a checkpoint that contained it. Bounded twice over:
+     * one entry per own bundle (one per wallet per contest), and the peers can only ever come
+     * from {@link #peerRoots}, itself capped at {@link PEER_ROOTS_MAX}.
+     */
+    #ownCheckpointPeers = new Map();
+    /**
+     * Cap on {@link #ownCids}. A wallet holds one live bundle per contest and a re-publish
+     * supersedes it, so real use sits far below this; the cap exists because
+     * {@link ContestEngine.trackOwnBundle} lets a caller add CIDs, and no public entry point
+     * should be able to grow a map without bound.
+     */
+    static #OWN_CIDS_MAX = 64;
     /** Does any vote in the bundle carry a `community.name` claim (needing resolution)? */
     #carriesName(bundle) {
         return bundle.votes.some((v) => v.community.name !== undefined);
@@ -755,9 +800,13 @@ class ContestEngine {
             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());
+        // its eviction-reporting entries are done (see #ownPublishes). Tell the publishing
+        // ContestVote first: this is the positive verdict it has no other way to hear.
+        if (this.#isFullyVerified(cid)) {
+            const key = cid.toString();
+            this.#ownVerifiedCbs.get(key)?.(cid);
+            this.#dropOwnTracking(key);
+        }
         this.#onStateChanged();
     }
     /**
@@ -771,11 +820,13 @@ class ContestEngine {
         this.#crdt.remove(cid);
         const key = cid.toString();
         this.#checks.delete(key);
+        this.#ownCids.delete(key);
+        this.#ownCheckpointPeers.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);
+            this.#forgetOwnBundle(key);
             notifyVote?.(error);
             this.#emitError(error);
         }
@@ -785,6 +836,19 @@ class ContestEngine {
     #dropOwnTracking(key) {
         this.#ownPublishes.delete(key);
         this.#ownEvictionCbs.delete(key);
+        this.#ownVerifiedCbs.delete(key);
+    }
+    /**
+     * Forget an own bundle entirely — its verdict-reporting entries AND its peer-checkpoint
+     * attribution. Only for a bundle that has LEFT the working set (evicted or expired):
+     * settlement alone must not reach this, because attribution goes on accruing for a bundle
+     * that is verified and live (see {@link #ownCids}).
+     */
+    #forgetOwnBundle(key) {
+        this.#dropOwnTracking(key);
+        this.#ownCheckpointCbs.delete(key);
+        this.#ownCids.delete(key);
+        this.#ownCheckpointPeers.delete(key);
     }
     #emitError(error) {
         for (const cb of [...this.#errorListeners])
@@ -944,7 +1008,7 @@ class ContestEngine {
             for (const removed of await this.#crdt.prune(this.#currentBucketCache)) {
                 const key = removed.toString();
                 this.#checks.delete(key);
-                this.#dropOwnTracking(key); // expiry is decay, not an eviction — no error
+                this.#forgetOwnBundle(key); // expiry is decay, not an eviction — no error
             }
         }
         return this.#tally.compute();
@@ -1079,6 +1143,9 @@ class ContestEngine {
                 this.#markStateChanged();
             },
             deferVerify: (entries) => this.#background.enqueue(entries),
+            // Every CID the checkpoint referenced, admitted or skipped — the skipped ones are
+            // what tier-3 attribution is made of (see #noteCheckpointContents).
+            onCheckpointContents: (root, cids) => this.#noteCheckpointContents(root, cids),
             onMerged: () => this.#onStateChanged(),
             limit: (fn) => chaseLimit(fn),
             timeoutMs: CHASE_TIMEOUT_MS
@@ -1343,15 +1410,13 @@ class ContestEngine {
     /**
      * 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. `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.
+     * broadcast with the wallet the caller hands it (identity is the ballot's, see
+     * {@link VoteClient.createContestVote}). `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, opts = {}) {
-        const signer = this.#deps.signer;
-        if (signer === undefined)
-            throw new ReadOnlyError();
+    async signVote(votes, signer, opts = {}) {
         const head = await this.#ruleChain.getBlockNumber();
         const bucket = this.#bucketMath.bucketForBlock(Number(head));
         this.#currentBucketCache = bucket;
@@ -1368,11 +1433,16 @@ class ContestEngine {
         // 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);
+        this.#ownCids.add(cid.toString());
         if (opts.onEvicted)
             this.#ownEvictionCbs.set(cid.toString(), opts.onEvicted);
+        if (opts.onVerified)
+            this.#ownVerifiedCbs.set(cid.toString(), opts.onVerified);
+        if (opts.onCheckpointedByPeer)
+            this.#ownCheckpointCbs.set(cid.toString(), opts.onCheckpointedByPeer);
         this.#background.enqueue([{ cid, bundle }]);
         this.#onStateChanged();
-        return { bundle, encoded: encodeBundle(bundle) };
+        return { bundle, encoded: encodeBundle(bundle), cid };
     }
     /**
      * Broadcast an encoded bundle inline as a live delta (this wallet's own delta, never the set).
@@ -1603,6 +1673,12 @@ class ContestEngine {
         const own = await this.rootRecord();
         if (own.root.equals(record.root)) {
             this.#heardMatchingRoot = true;
+            // Their checkpoint is ours byte for byte, so it demonstrably contains every bundle
+            // ours does — including our own. Nothing is chased here (there is no divergence to
+            // chase), so without this the ONE case tier-3 attribution most wants to catch — a
+            // healthy topic where we and the seeder have converged — would be the one case it
+            // never saw.
+            this.#indexRootContents(record.root, this.#ownVerifiedCids());
             return;
         }
         this.#chaser?.chase(record.root, undefined, this.#sessionProvidersFor(record.root));
@@ -1621,7 +1697,112 @@ class ContestEngine {
             if (oldest !== undefined)
                 this.#peerRoots.delete(oldest);
         }
-        this.#peerRoots.set(peerId, root.toString());
+        const key = root.toString();
+        this.#peerRoots.set(peerId, key);
+        // Many peers converge on one root, and most of them advertise it AFTER we chased it —
+        // so attribution cannot wait for a decode that already happened. #decodedRoots is what
+        // makes that retroactive.
+        this.#attributeRoot(peerId, key);
+    }
+    /**
+     * Record which of OUR bundles a decoded checkpoint contained, and credit every peer already
+     * known to advertise that root. Called once per successful chase decode, with every bundle
+     * CID the checkpoint referenced — INCLUDING ones we already hold, which is the whole point:
+     * our own bundle is always already held, so the chase skips admitting it and would otherwise
+     * never mention it.
+     */
+    #noteCheckpointContents(root, cids) {
+        const mine = new Set();
+        for (const cid of cids) {
+            const key = cid.toString();
+            if (this.#ownCids.has(key))
+                mine.add(key);
+        }
+        this.#indexRootContents(root, mine);
+    }
+    /**
+     * Our own bundles that are in our OWN checkpoint right now — i.e. fully verified ones. A
+     * pending bundle is deliberately excluded: the encoder does not serve it, so a peer holding
+     * our root is not thereby holding it.
+     */
+    #ownVerifiedCids() {
+        const mine = new Set();
+        for (const key of this.#ownCids) {
+            if (this.#isFullyVerified(CID.parse(key)))
+                mine.add(key);
+        }
+        return mine;
+    }
+    /** Index `mine` under `root` (bounded, LRU) and credit every peer already at that root. */
+    #indexRootContents(root, mine) {
+        if (mine.size === 0)
+            return; // nothing of ours in it — not worth an index entry
+        const rootKey = root.toString();
+        if (this.#decodedRoots.has(rootKey))
+            this.#decodedRoots.delete(rootKey); // refresh LRU slot
+        else if (this.#decodedRoots.size >= DECODED_ROOTS_MAX) {
+            const oldest = this.#decodedRoots.keys().next().value;
+            if (oldest !== undefined)
+                this.#decodedRoots.delete(oldest);
+        }
+        this.#decodedRoots.set(rootKey, mine);
+        let credited = false;
+        for (const [peerId, peerRoot] of this.#peerRoots) {
+            if (peerRoot === rootKey)
+                credited = this.#creditPeer(peerId, mine) || credited;
+        }
+        if (credited)
+            this.#onStateChanged();
+    }
+    /** Credit `peerId` with every own CID in a root it advertises, if we decoded that root. */
+    #attributeRoot(peerId, rootKey) {
+        const mine = this.#decodedRoots.get(rootKey);
+        if (mine !== undefined && this.#creditPeer(peerId, mine))
+            this.#onStateChanged();
+    }
+    /** Add `peerId` to each own CID's attribution set; true if anything was new. */
+    #creditPeer(peerId, ownCids) {
+        let added = false;
+        for (const key of ownCids) {
+            if (!this.#ownCids.has(key))
+                continue; // evicted or expired since the decode
+            let peers = this.#ownCheckpointPeers.get(key);
+            if (peers === undefined) {
+                peers = new Set();
+                this.#ownCheckpointPeers.set(key, peers);
+            }
+            if (!peers.has(peerId)) {
+                const first = peers.size === 0;
+                peers.add(peerId);
+                added = true;
+                if (first) {
+                    this.#ownCheckpointCbs.get(key)?.(CID.parse(key));
+                    this.#ownCheckpointCbs.delete(key);
+                }
+            }
+        }
+        return added;
+    }
+    /** {@link Contest.trackOwnBundle}. */
+    trackOwnBundle(cid) {
+        const key = cid.toString();
+        if (this.#ownCids.has(key))
+            return;
+        if (this.#ownCids.size >= ContestEngine.#OWN_CIDS_MAX) {
+            const oldest = this.#ownCids.values().next().value;
+            if (oldest !== undefined)
+                this.#forgetOwnBundle(oldest);
+        }
+        this.#ownCids.add(key);
+    }
+    /** {@link Contest.checksFor}. */
+    checksFor(cid) {
+        const checks = this.#checks.get(cid.toString());
+        return checks === undefined ? undefined : { ...checks };
+    }
+    /** {@link Contest.checkpointPeersFor}. */
+    checkpointPeersFor(cid) {
+        return [...(this.#ownCheckpointPeers.get(cid.toString()) ?? [])];
     }
     /**
      * The session seeds for chasing `root`: every still-connected peer whose last advertised
@@ -1707,6 +1888,15 @@ class ContestView {
     get tally() {
         return this.#engine.cachedTally;
     }
+    checksFor(cid) {
+        return this.#engine.checksFor(cid);
+    }
+    checkpointPeersFor(cid) {
+        return this.#engine.checkpointPeersFor(cid);
+    }
+    trackOwnBundle(cid) {
+        this.#engine.trackOwnBundle(cid);
+    }
     async update() {
         if (this.#subscribed)
             return;
@@ -1754,22 +1944,62 @@ class ContestView {
 class ContestVotePublication {
     contestId;
     votes;
+    signer;
     #engine;
     #stateCbs = [];
     #errorCbs = [];
     #state = "stopped";
     #bundle;
+    #cid;
+    /**
+     * Which `publish()` call owns the state machine. Incremented synchronously at the top of
+     * `publish()`, BEFORE any await, and captured by every callback that attempt registers.
+     *
+     * A re-publish in a later window signs new bytes, so the previous attempt's bundle keeps its
+     * own CID, stays live in the CRDT (a superseded bundle outlives its superseder's deferred
+     * checks) and can still be verified, served by a peer, or evicted — long after a newer
+     * attempt owns this object. Matching on the CID cannot separate the two: `#cid` still holds
+     * the PREVIOUS attempt's value until the new `signVote()` resolves, so an old verdict landing
+     * in that window passes a CID check and moves the wrong attempt. The token is established
+     * before that window opens, so it does not. It also decouples the check from `#cid` entirely,
+     * which is what lets a verdict that settles BEFORE `#cid` is assigned still be delivered
+     * (the engine delivers each callback once and then drops it — a settlement ignored here is
+     * lost for good).
+     */
+    #attempt = 0;
     /**
      * 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.
+     * with `"publishing"`/`"published"`. Reset by the next `publish()` call.
      */
     #evicted = false;
-    constructor(engine, votes) {
+    /** Is this callback's attempt still the one that owns the object? (see {@link #attempt}) */
+    #isCurrent(attempt) {
+        return attempt === this.#attempt;
+    }
+    /**
+     * Advance to a settled state, unless this attempt is already finished or further along.
+     * Two orderings have to be tolerated, not just one: the deferred checks race the broadcast,
+     * so a verdict can land before `publish()` resolves, and a peer can serve our bundle back to
+     * us before our OWN gate read returns — peer evidence is strictly stronger (a peer
+     * checkpoints only fully verified bundles), so it must never be overwritten by the weaker
+     * local one arriving late.
+     */
+    #settle(attempt, state) {
+        if (!this.#isCurrent(attempt))
+            return;
+        if (this.#evicted || this.#state === "failed" || this.#state === "verified-by-peer")
+            return;
+        if (state === "verified-locally" && this.#state === "verified-locally")
+            return;
+        this.#setState(state);
+    }
+    constructor(engine, votes, signer) {
         this.#engine = engine;
         this.contestId = engine.criteria.contestId;
         this.votes = votes;
+        this.signer = signer;
     }
     get topic() {
         return this.#engine.topic;
@@ -1780,6 +2010,9 @@ class ContestVotePublication {
     get bundle() {
         return this.#bundle;
     }
+    get checks() {
+        return this.#cid === undefined ? undefined : this.#engine.checksFor(this.#cid);
+    }
     #setState(state) {
         this.#state = state;
         for (const cb of [...this.#stateCbs])
@@ -1791,12 +2024,11 @@ class ContestVotePublication {
             cb(error);
     }
     async publish() {
-        // Fail before joining a read-only voter needlessly to the topic.
-        if (this.#engine.readOnly) {
-            const error = new ReadOnlyError();
-            this.#fail(error);
-            throw error;
-        }
+        // Before the first await: every callback below is bound to THIS attempt, and the
+        // previous attempt's callbacks stop being able to move this object the moment the
+        // counter ticks — even though its bundle is still live and still verifiable.
+        const attempt = ++this.#attempt;
+        this.#evicted = false;
         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
@@ -1805,30 +2037,48 @@ class ContestVotePublication {
             // 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, cid } = await this.#engine.signVote([...this.votes], this.signer, {
                 namesSettled,
+                // The positive counterparts of `onEvicted`: our own deferred checks settling
+                // clean, then a peer serving the bundle back to us in its checkpoint. Both
+                // normally land after publish() has resolved.
+                onVerified: () => this.#settle(attempt, "verified-locally"),
+                onCheckpointedByPeer: () => this.#settle(attempt, "verified-by-peer"),
                 // 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) => {
+                    // Attempt-scoped like the positive verdicts: a superseded bundle is kept
+                    // alive while its superseder's checks are pending, so an eviction of the
+                    // PREVIOUS attempt's bytes must not fail the attempt that replaced it.
+                    if (!this.#isCurrent(attempt))
+                        return;
                     this.#evicted = true;
                     this.#fail(error);
                 }
             });
             this.#bundle = bundle;
-            if (!this.#evicted)
+            this.#cid = cid;
+            // Only from "signing": a deferred check can settle before this line runs (a cached
+            // verdict needs no round trip), and "publishing" would walk that verdict backwards.
+            if (this.#state === "signing")
                 this.#setState("publishing");
             const { recipientCount } = await this.#engine.broadcastBundle(encoded);
             // 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 };
+            // still resolves (the bundle DID hit the wire) but the state stays "failed". A
+            // check that SETTLED mid-broadcast is not stomped either: "published" describes
+            // the broadcast, and a verdict already in hand is further along than that.
+            if (!this.#evicted && this.#state === "publishing")
+                this.#setState("published");
+            return { bundle, recipientCount, cid };
         }
         catch (error) {
-            this.#fail(error);
+            // Same scoping: two overlapping `publish()` calls are a misuse, but the loser's
+            // rejection belongs to ITS caller (it is rethrown), not to the state machine a
+            // later attempt now owns.
+            if (this.#isCurrent(attempt))
+                this.#fail(error);
             throw error;
         }
     }
@@ -1894,7 +2144,6 @@ export class PubsubVoter {
             // the background verifier) merge into shared multicall3 round trips under one
             // per-client in-flight budget — see src/chain/coalescer.ts.
             chains: coalescingChainFactory(options.chains),
-            signer: options.signer,
             registry: resolveRegistry(options.rules),
             nameResolvers: options.nameResolvers ?? [],
             onTopicJoined: this.#onTopicJoined,
@@ -1974,9 +2223,6 @@ export class PubsubVoter {
         // Contests can share CIDs (e.g. two vote-less contests share the empty-checkpoint root).
         return [...new Set(keys)];
     };
-    get readOnly() {
-        return this.#deps.signer === undefined;
-    }
     /** Guard the create paths after {@link destroy}: a destroyed voter is terminal. */
     #assertLive() {
         if (this.#destroyed)
@@ -1995,7 +2241,7 @@ export class PubsubVoter {
     async createContestVote(args) {
         this.#assertLive();
         const engine = await this.#engineFor(this.#validateCriteria(args.criteria));
-        return new ContestVotePublication(engine, args.votes);
+        return new ContestVotePublication(engine, args.votes, args.signer);
     }
     /**
      * Strictly validate one criteria document at the create seam: `CriteriaSchema` (shape,

package/dist/errors.d.ts

@@ -87,10 +87,6 @@ export declare class DuplicateContestIdError extends Error {
     readonly contestId: string;
     constructor(contestId: string);
 }
-/** Thrown when a publish (vote/withdraw) is attempted on a voter constructed without a signer. */
-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

package/dist/errors.js

@@ -133,14 +133,6 @@ export class DuplicateContestIdError extends Error {
         this.name = "DuplicateContestIdError";
     }
 }
-/** Thrown when a publish (vote/withdraw) is attempted on a voter constructed without a signer. */
-export class ReadOnlyError extends Error {
-    constructor() {
-        super("This voter is read-only: it was constructed without a `signer`. " +
-            "Provide a VoteSigner to publish or withdraw votes; reading tallies needs no signer.");
-        this.name = "ReadOnlyError";
-    }
-}
 /**
  * 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

package/dist/transport/chase.d.ts

@@ -95,6 +95,14 @@ export interface RootChaserDeps {
     deferVerify: (entries: PendingBundle[]) => void;
     /** Called once per chase that admitted at least one bundle (drives tally updates). */
     onMerged?: () => void;
+    /**
+     * Called once per successfully decoded checkpoint with EVERY bundle CID it referenced —
+     * including the ones this chase skipped because we already hold them. That inclusion is the
+     * point: a publisher's own bundle is by definition already held, so it never reaches
+     * {@link admit}, and "which peers are serving my vote back to me" would be unanswerable from
+     * the admit path alone. Reports what the checkpoint CONTAINED, not what was new.
+     */
+    onCheckpointContents?: (root: CID, cids: CID[]) => void;
     /** Concurrency limiter shared across chases (a root spray queues, never floods). */
     limit: <T>(fn: () => Promise<T>) => Promise<T>;
     /** Per-root deadline (ms); on expiry the abort signal fires and the chase yields nothing. */

package/dist/transport/chase.js

@@ -41,7 +41,7 @@ export function toChaseSession(session) {
     };
 }
 export function makeRootChaser(deps) {
-    const { getBlock, openSession, verifyOffline, cache, isEvaluableNow, hasBundle, admit, deferVerify, onMerged, limit, timeoutMs } = deps;
+    const { getBlock, openSession, verifyOffline, cache, isEvaluableNow, hasBundle, admit, deferVerify, onMerged, onCheckpointContents, limit, timeoutMs } = deps;
     const inFlight = new Map();
     function addProviders(flight, providers) {
         for (const peer of providers) {
@@ -112,6 +112,7 @@ export function makeRootChaser(deps) {
                 return; // deadline hit — the hint contributed nothing
             let merged = false;
             const pending = [];
+            const contained = [];
             for (const bundle of winners) {
                 if (controller.signal.aborted)
                     break;
@@ -119,6 +120,7 @@ export function makeRootChaser(deps) {
                 // canonical), so the CID matches the advertiser's block and dedups everywhere.
                 const bytes = encodeBundle(bundle);
                 const cid = await bundleCidForBytes(bytes);
+                contained.push(cid); // recorded BEFORE the skip below — see onCheckpointContents
                 if (await hasBundle(cid))
                     continue; // already held — nothing to verify
                 const cached = cache.get(cid);
@@ -148,6 +150,8 @@ export function makeRootChaser(deps) {
             // and batches the gate reads (see verify/background.ts).
             if (pending.length > 0)
                 deferVerify(pending);
+            if (contained.length > 0)
+                onCheckpointContents?.(root, contained);
             if (merged)
                 onMerged?.();
         }

package/package.json

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