@bitsocial/pubsub-votes 0.0.2

package/README.md

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

package/dist/chain/bucket.d.ts

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

package/dist/chain/bucket.js

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

package/dist/chain/ticker.d.ts

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

package/dist/chain/ticker.js

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

package/dist/chain/types.d.ts

@@ -0,0 +1,90 @@
+import type { PublicClient } from "viem";
+import type { ChainConfig } from "../schema/criteria.js";
+/**
+ * Chain access.
+ *
+ * A `ChainClient` is just a viem `PublicClient`. The library does not wrap it in a
+ * curated read API (no `balanceOfErc20`/`balanceOfErc721` helpers): every rule
+ * writes its own reads with the full viem surface (`readContract`, `getBalance`,
+ * `call`, multicall, ...) against whatever ABI it needs. That keeps custom
+ * rules unconstrained — a host can read any contract shape without waiting for
+ * a helper to be added here.
+ *
+ * Reads must be pinned to an explicit historical block (the sampled block for a
+ * bundle's bucket) so every verifier prices the same state — rules pass
+ * `blockNumber: BigInt(ctx.blockNumber)` to each viem call. viem is allowed in the
+ * core (it carries no libp2p/helia import); only `src/transport/` touches the node.
+ *
+ * pkc-js has no equivalent: it touches chains only for name resolution and has no
+ * balance reads or chainTicker-to-RPC mapping. All of this is net-new here.
+ */
+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.
+ */
+export type ChainClientFactory = (args: {
+    chain: string;
+    config: ChainConfig;
+}) => ChainClient;
+/**
+ * A community-name resolver the host injects (`PubsubVoterOptions.nameResolvers`). The
+ * shape is structurally identical to pkc-js's `NameResolverInterface`, so a host passes
+ * the very same instances it already gives pkc-js (e.g. `@bitsocial/bso-resolver`'s
+ * `BsoResolver`, which resolves `name.bso` through the `bitsocial` text record) —
+ * declared here rather than imported so this library depends on no resolver package.
+ *
+ * The tally uses it to verify a vote's `community.name` claim: resolve the name and drop
+ * the bundle when it does not resolve or resolves to a different `publicKey` than the
+ * vote claims (see DESIGN.md "Tally"). `resolve` returning `undefined` means the name
+ * has no record. `resolve` accepts an optional `blockNumber` to pin the read to a
+ * canonical historical block (bso-resolver#3, since resolved upstream); when omitted it
+ * resolves at head. v1 still resolves at head: the registry lives on its own chain, so
+ * pinning also needs a canonical per-bucket block *on the registry's chain* — that
+ * multi-chain block-selection half is still open. See DESIGN.md "Open questions",
+ * "Pinned-block name resolution".
+ */
+export interface NameResolver {
+    /** Identifies this resolver instance (e.g. "bso-viem"). */
+    key: string;
+    /** The backing provider label (e.g. "viem"). */
+    provider: string;
+    /** Resolve a name to its record; `undefined` when the name has no record. */
+    resolve: (opts: {
+        name: string;
+        /**
+         * Pin the text-record read to a canonical historical block; resolves at head
+         * when omitted. v1 leaves it unset (head) until per-bucket block selection on
+         * the registry's chain lands — see the interface note above.
+         */
+        blockNumber?: bigint;
+        abortSignal?: AbortSignal;
+    }) => Promise<{
+        publicKey: string;
+        [key: string]: string;
+    } | undefined>;
+    /** True when this resolver handles the name's TLD (e.g. ends with ".bso"). */
+    canResolve: (opts: {
+        name: string;
+    }) => boolean;
+    destroy?: () => Promise<void>;
+}
+/**
+ * Bucket math (documented here, implemented later).
+ *
+ *   bucketForBlock(block)        = Math.floor(block / blocksPerBucket)
+ *   sampleBlockForBucket(bucket) = the canonical block at which balances are read
+ *                                  for that bucket
+ *
+ * Using one sample block per bucket is what stops votes from flip-flopping mid
+ * bucket and what makes every verifier agree. The exact sample-block rule (bucket
+ * start, or a block derived from a blockhash to resist flash-loan timing) is a
+ * tuning decision recorded in DESIGN.md.
+ */
+export interface BucketMath {
+    bucketForBlock(blockNumber: number): number;
+    sampleBlockForBucket(bucket: number): number;
+}

package/dist/chain/types.js

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

package/dist/checkpoint/codec.d.ts

@@ -0,0 +1,54 @@
+import { CID } from "multiformats/cid";
+import type { VotesBundle } from "../schema/votes.js";
+/**
+ * Checkpoint codec — the compacted snapshot of a topic's current LWW winners (one bundle per
+ * wallet), used for fast cold-start and storage compaction (see DESIGN.md "Checkpoints"). Pure and
+ * network-free: it turns a winner set into content-addressed blocks and back, so it is unit-testable
+ * offline. Fetching/publishing those blocks over libp2p is a separate, host-blocked concern.
+ *
+ * Format — a shallow depth-2 pagination DAG (NOT a history DAG: no parent links, regenerated fresh
+ * each cut):
+ *   - winners are sorted **ascending by `address`** (unique per wallet under LWW, so no tie);
+ *   - the sorted bundles are packed, **full and inlined**, into chunk blocks by a size-cap fill:
+ *     append bundles into a chunk until the next would push the chunk's inlined-bundle bytes over
+ *     `maxChunkBytes`, then start a new chunk (a single oversized bundle still forms its own chunk);
+ *   - a root block lists the chunk CIDs: `{ chunks: CID[] }`.
+ *
+ * Canonical dag-cbor + the address sort + the size-cap rule make the bytes a pure function of the
+ * winner set, so any two seeders with the same view produce the **same root CID** and their blocks
+ * dedupe. The byte layout is pinned by the fixed test vector in `codec.test.ts`.
+ */
+/** One content-addressed checkpoint block (a chunk, or the root manifest). */
+export interface CheckpointBlock {
+    cid: CID;
+    bytes: Uint8Array;
+}
+/** The result of a checkpoint cut: the root CID plus every block to store (chunks + root). */
+export interface EncodedCheckpoint {
+    root: CID;
+    /**
+     * The chunk-CID index (the root manifest's contents), in root order. Exposed so the
+     * root record can carry it (see DESIGN.md "Checkpoints", "Block pull"): a cold joiner
+     * handed a verified chunk index skips the root-manifest bitswap round-trip and pulls
+     * every chunk in parallel. `CID(encodeCanonical({ chunks })) === root`, so it is
+     * self-verifying against the root and cannot be a new trust vector.
+     */
+    chunks: CID[];
+    blocks: CheckpointBlock[];
+}
+/** Default chunk ceiling (bytes of inlined bundles per chunk), just under a 1 MiB block. */
+export declare const DEFAULT_MAX_CHUNK_BYTES: number;
+/**
+ * Encode a winner set into checkpoint blocks. `winners` should be the CRDT's current (non-expired)
+ * LWW winners; order does not matter (they are sorted here). Returns the root CID and every block to
+ * persist. Deterministic: identical winners + `maxChunkBytes` ⇒ identical bytes and root CID.
+ */
+export declare function encodeCheckpoint(winners: VotesBundle[], maxChunkBytes?: number): Promise<EncodedCheckpoint>;
+/**
+ * Decode a checkpoint back into its inlined winner bundles, given a way to fetch each block by CID
+ * (blockstore/bitswap). This is a *structural* decode — each bundle is schema-validated (wire shape,
+ * B58 key, distinct communities) but NOT signature-verified; the caller re-verifies each through the
+ * same verifier the gate uses before merging (a single seeder cannot forge or hide a vote — see
+ * DESIGN.md "Checkpoints"). Throws if a referenced block is unavailable or malformed.
+ */
+export declare function decodeCheckpoint(root: CID, getBlock: (cid: CID) => Promise<Uint8Array | undefined>, knownChunks?: CID[]): Promise<VotesBundle[]>;

package/dist/checkpoint/codec.js

@@ -0,0 +1,99 @@
+import { CID } from "multiformats/cid";
+import { sha256 } from "multiformats/hashes/sha2";
+import * as dagCbor from "@ipld/dag-cbor";
+import { encodeCanonical, dagCborCode } from "../encoding/canonical.js";
+import { encodeBundle, toWireBundle, fromWireBundle } from "../crdt/codec.js";
+/** Default chunk ceiling (bytes of inlined bundles per chunk), just under a 1 MiB block. */
+export const DEFAULT_MAX_CHUNK_BYTES = 1 << 20;
+async function blockFor(bytes) {
+    const digest = await sha256.digest(bytes);
+    return { cid: CID.createV1(dagCborCode, digest), bytes };
+}
+/**
+ * The root-manifest block for a chunk-CID list: `{ chunks }` canonically encoded and hashed. Its
+ * CID is the checkpoint root, so re-deriving it from a chunk list proves the list belongs to a
+ * given root — the local check that lets a joiner trust a piggybacked chunk index (see
+ * {@link decodeCheckpoint}) without fetching the manifest.
+ */
+async function checkpointRootBlock(chunks) {
+    const root = { chunks };
+    return blockFor(encodeCanonical(root));
+}
+/**
+ * Encode a winner set into checkpoint blocks. `winners` should be the CRDT's current (non-expired)
+ * LWW winners; order does not matter (they are sorted here). Returns the root CID and every block to
+ * persist. Deterministic: identical winners + `maxChunkBytes` ⇒ identical bytes and root CID.
+ */
+export async function encodeCheckpoint(winners, maxChunkBytes = DEFAULT_MAX_CHUNK_BYTES) {
+    // Lowercase before comparing so the sort equals raw byte order regardless of how a caller
+    // cased an address — casing is presentation, the wire form is lowercase bytes.
+    const sorted = [...winners]
+        .map((bundle) => ({ bundle, key: bundle.address.toLowerCase() }))
+        .sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0))
+        .map((entry) => entry.bundle);
+    // Size-cap fill on the inlined-bundle byte total (a pure function of the bundles, so seeders
+    // agree without encoding a partial chunk each step).
+    const chunks = [];
+    let current = [];
+    let currentBytes = 0;
+    for (const bundle of sorted) {
+        const size = encodeBundle(bundle).length;
+        if (current.length > 0 && currentBytes + size > maxChunkBytes) {
+            chunks.push(current);
+            current = [];
+            currentBytes = 0;
+        }
+        current.push(bundle);
+        currentBytes += size;
+    }
+    if (current.length > 0)
+        chunks.push(current);
+    const blocks = [];
+    const chunkCids = [];
+    for (const chunk of chunks) {
+        // Chunks inline the same binary wire objects the bundle block uses (see crdt/codec.ts),
+        // so the binary-field byte saving multiplies across every inlined winner.
+        const block = await blockFor(encodeCanonical(chunk.map(toWireBundle)));
+        blocks.push(block);
+        chunkCids.push(block.cid);
+    }
+    const rootBlock = await checkpointRootBlock(chunkCids);
+    blocks.push(rootBlock);
+    return { root: rootBlock.cid, chunks: chunkCids, blocks };
+}
+/**
+ * Decode a checkpoint back into its inlined winner bundles, given a way to fetch each block by CID
+ * (blockstore/bitswap). This is a *structural* decode — each bundle is schema-validated (wire shape,
+ * B58 key, distinct communities) but NOT signature-verified; the caller re-verifies each through the
+ * same verifier the gate uses before merging (a single seeder cannot forge or hide a vote — see
+ * DESIGN.md "Checkpoints"). Throws if a referenced block is unavailable or malformed.
+ */
+export async function decodeCheckpoint(root, getBlock, knownChunks) {
+    // If the caller supplies a chunk index (piggybacked on the root record — see DESIGN.md
+    // "Block pull"), trust it only after re-deriving the manifest and checking its CID equals
+    // `root`: a lie fails this local check and falls back to the manifest fetch, so the index is
+    // an optimization, never a new trust vector. When it verifies, the root-manifest bitswap
+    // round-trip is skipped entirely.
+    let chunks;
+    if (knownChunks !== undefined && (await checkpointRootBlock(knownChunks)).cid.equals(root)) {
+        chunks = knownChunks;
+    }
+    else {
+        const rootBytes = await getBlock(root);
+        if (!rootBytes)
+            throw new Error(`checkpoint root block ${root.toString()} is unavailable`);
+        chunks = dagCbor.decode(rootBytes).chunks;
+    }
+    // The chunks are independent blocks, so pull them concurrently (one bitswap round-trip for
+    // the whole set, not one per chunk); decode preserves root order for a deterministic result.
+    const perChunk = await Promise.all(chunks.map(async (chunkCid) => {
+        const chunkBytes = await getBlock(chunkCid);
+        if (!chunkBytes)
+            throw new Error(`checkpoint chunk block ${chunkCid.toString()} is unavailable`);
+        const wires = dagCbor.decode(chunkBytes);
+        if (!Array.isArray(wires))
+            throw new Error(`checkpoint chunk ${chunkCid.toString()} is not a bundle array`);
+        return wires.map(fromWireBundle);
+    }));
+    return perChunk.flat();
+}

package/dist/client/root-puller.d.ts

@@ -0,0 +1,49 @@
+import type { PeerId } from "@libp2p/interface";
+import type { FetchServiceLike } from "../transport/types.js";
+import { type FetchRootRecord } from "../transport/messages.js";
+/**
+ * The cold-start root puller: the voter-wide seam every engine's cold-join pull goes through
+ * (see DESIGN.md "Checkpoints"). One instance per voter, because everything it guards is
+ * per-PEER, not per-topic:
+ *
+ *   - **Batching.** Pulls to the same peer that arrive within {@link BATCH_WINDOW_MS} coalesce
+ *     into ONE fetch stream carrying a batch key ({@link batchRootsFetchKey}), so a directory-
+ *     scale join pays the ~2-RTT multistream-select negotiation once per peer instead of once
+ *     per contest. A single pending topic skips the batch key entirely (the common single-board
+ *     case has zero new wire surface). A responder that predates the batch key answers
+ *     NOT_FOUND (or garbage), and the puller falls back to today's per-topic keys.
+ *   - **Budget.** At most {@link COLD_START_PEER_FETCH_LIMIT} concurrent fetch streams per peer
+ *     across ALL contests, under libp2p's default per-protocol caps (32 inbound on the
+ *     responder, 64 outbound on us — both enforced PER CONNECTION per direction, so one
+ *     connection's budget is exactly the scope of the remote cap; other users of a shared
+ *     seeder arrive on their own connections and do not eat these slots). 24 rather than the
+ *     full 32 because running at the cliff still resets: our slot frees when the response
+ *     lands, but the responder only decrements its count when it sees the stream *close*, so
+ *     back-to-back reuse races that bookkeeping — and the same connection can carry fetch
+ *     streams the budget cannot see (the host's own IPNS-over-pubsub record fetches ride the
+ *     same protocol; so would a second voter on the shared node).
+ *   - **Retry.** A THROWN fetch retries with full-jittered exponential backoff until
+ *     {@link COLD_START_FETCH_DEADLINE_MS} — the safety net for a responder saturated by
+ *     streams the budget cannot see. While the cap is saturated every freed slot is instantly
+ *     retaken, so a fixed attempt count can lose the race and strand a board (measured: no
+ *     retry → 32/63 boards converge; 5 fixed retries → 53/63; retry-to-deadline → 63/63). Only
+ *     a throw retries — a definitive `undefined`/`null` ("no record") returns as-is — and a
+ *     pull whose contest was torn down (`isLive()` false) abandons quietly. Each attempt (not
+ *     the whole loop, so a backoff sleep never holds a slot) passes through the budget; queue
+ *     wait counts against the same deadline.
+ */
+export interface RootPuller {
+    /**
+     * Pull one topic's root record from one peer: the decoded record, or `null`/`undefined`
+     * ("no record", definitive), or a rejection (unreachable peer past the deadline, or a
+     * garbage answer). `isLive` is polled between retries and before resolving, so a contest
+     * left mid-pull abandons instead of holding work alive.
+     */
+    pull(peer: PeerId, topic: string, isLive: () => boolean): Promise<FetchRootRecord | null | undefined>;
+}
+/** See the budget note on {@link RootPuller}. */
+export declare const COLD_START_PEER_FETCH_LIMIT = 24;
+/** See the retry note on {@link RootPuller}. */
+export declare const COLD_START_FETCH_DEADLINE_MS = 30000;
+/** Build the voter-wide puller over the host's fetch service. */
+export declare function makeRootPuller(fetch: FetchServiceLike): RootPuller;