@bitsocial/pubsub-votes 0.0.2

package/dist/crdt/codec.d.ts

@@ -0,0 +1,41 @@
+import { CID } from "multiformats/cid";
+import { z } from "zod";
+import { type VotesBundle } from "../schema/votes.js";
+/** The binary wire shape of one bundle block (dag-cbor map, canonical key order). */
+declare const WireBundleSchema: z.ZodObject<{
+    address: z.ZodCustom<Uint8Array<ArrayBufferLike>, Uint8Array<ArrayBufferLike>>;
+    blockNumber: z.ZodNumber;
+    signature: z.ZodObject<{
+        signature: z.ZodCustom<Uint8Array<ArrayBufferLike>, Uint8Array<ArrayBufferLike>>;
+        type: z.ZodString;
+    }, z.core.$strip>;
+    votes: z.ZodArray<z.ZodObject<{
+        community: z.ZodObject<{
+            name: z.ZodOptional<z.ZodString>;
+            publicKey: z.ZodCustom<Uint8Array<ArrayBufferLike>, Uint8Array<ArrayBufferLike>>;
+        }, z.core.$strip>;
+        vote: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+type WireBundle = z.infer<typeof WireBundleSchema>;
+/**
+ * Map a (schema-valid) VotesBundle to its binary wire shape. Exported for the checkpoint
+ * codec, which inlines these same wire objects into its chunk blocks so the byte saving
+ * multiplies across every inlined winner.
+ */
+export declare function toWireBundle(bundle: VotesBundle): WireBundle;
+/**
+ * Map a decoded wire value back to a VotesBundle, validating both the wire shape and the
+ * full bundle schema (B58 key, distinct communities, name bound). Throws on anything
+ * malformed — callers on untrusted paths treat a throw as an invalid block.
+ */
+export declare function fromWireBundle(wire: unknown): VotesBundle;
+/** Canonically encode a VotesBundle to its binary dag-cbor block bytes. */
+export declare function encodeBundle(bundle: VotesBundle): Uint8Array;
+/** Decode binary block bytes back to a VotesBundle. Throws on malformed bytes. */
+export declare function decodeBundle(bytes: Uint8Array): VotesBundle;
+/** The CIDv1 (dag-cbor, sha2-256) content address of already-encoded bundle block bytes. */
+export declare function bundleCidForBytes(bytes: Uint8Array): Promise<CID>;
+/** The CIDv1 (dag-cbor, sha2-256) content address of a VotesBundle. */
+export declare function bundleCid(bundle: VotesBundle): Promise<CID>;
+export {};

package/dist/crdt/codec.js

@@ -0,0 +1,137 @@
+import { CID } from "multiformats/cid";
+import { sha256 } from "multiformats/hashes/sha2";
+import * as dagCbor from "@ipld/dag-cbor";
+import { base58btc } from "multiformats/bases/base58";
+import { z } from "zod";
+import { encodeCanonical, dagCborCode } from "../encoding/canonical.js";
+import { VotesBundleSchema } from "../schema/votes.js";
+/**
+ * VotesBundle <-> bytes, using the same canonical dag-cbor encoder as the criteria topic. A
+ * bundle is a standalone dag-cbor block with no parent links; content-addressing makes the
+ * CID a checksum over the bundle bytes, which is what the CRDT relies on to de-duplicate and
+ * LWW-tiebreak (see DESIGN.md "CRDT").
+ *
+ * The block layout is BINARY (see DESIGN.md "Bundle wire encoding"): crypto material travels
+ * as raw bytes, not strings — `address` as its 20 bytes, `signature.signature` as its 65
+ * bytes, `community.publicKey` as the raw multihash behind the B58 IPNS name — roughly
+ * halving a one-vote bundle. This is a *separate* serialization from the frozen EIP-712
+ * signed struct (signer/eip712.ts): changing it re-hashes the bundle CID but never the
+ * signature vector. Decoding maps each field back to the string form the schema and EIP-712
+ * verification expect; hex round-trips to lowercase (signature recovery compares addresses
+ * case-insensitively, so casing is presentation, not identity). The layout is pinned by the
+ * fixed test vector in `codec.test.ts` — any change is a breaking wire change that re-freezes
+ * the vector (and the checkpoint vector, which inlines these bytes).
+ */
+const ADDRESS_BYTES = 20;
+const SIGNATURE_BYTES = 65;
+// `z.instanceof(Uint8Array)` infers `Uint8Array<ArrayBuffer>`, which rejects the
+// `ArrayBufferLike`-backed arrays multiformats/dag-cbor produce — hence the custom check.
+const BytesSchema = z.custom((value) => value instanceof Uint8Array, "expected bytes");
+/** The binary wire shape of one bundle block (dag-cbor map, canonical key order). */
+const WireBundleSchema = z.object({
+    address: BytesSchema,
+    blockNumber: z.number().int().nonnegative(),
+    signature: z.object({
+        signature: BytesSchema,
+        type: z.string().min(1)
+    }),
+    votes: z.array(z.object({
+        community: z.object({
+            name: z.string().optional(),
+            publicKey: BytesSchema
+        }),
+        vote: z.number().int()
+    }))
+});
+function hexToBytes(hex, expectedBytes, label) {
+    if (!/^0x[0-9a-fA-F]*$/.test(hex) || hex.length !== 2 + expectedBytes * 2) {
+        throw new Error(`${label} must be 0x-hex of exactly ${expectedBytes} bytes`);
+    }
+    const out = new Uint8Array(expectedBytes);
+    for (let i = 0; i < expectedBytes; i++)
+        out[i] = parseInt(hex.slice(2 + i * 2, 4 + i * 2), 16);
+    return out;
+}
+function bytesToHex(bytes) {
+    let hex = "0x";
+    for (const byte of bytes)
+        hex += byte.toString(16).padStart(2, "0");
+    return hex;
+}
+/** B58 IPNS name ("12D3KooW…", base58btc without the multibase prefix) -> raw multihash bytes. */
+function publicKeyToBytes(publicKey) {
+    return base58btc.decode(`z${publicKey}`);
+}
+/** Raw multihash bytes -> the B58 IPNS name (drop base58btc's leading `z`). */
+function publicKeyFromBytes(bytes) {
+    return base58btc.encode(bytes).slice(1);
+}
+/**
+ * Map a (schema-valid) VotesBundle to its binary wire shape. Exported for the checkpoint
+ * codec, which inlines these same wire objects into its chunk blocks so the byte saving
+ * multiplies across every inlined winner.
+ */
+export function toWireBundle(bundle) {
+    const parsed = VotesBundleSchema.parse(bundle);
+    return {
+        address: hexToBytes(parsed.address, ADDRESS_BYTES, "address"),
+        blockNumber: parsed.blockNumber,
+        signature: {
+            signature: hexToBytes(parsed.signature.signature, SIGNATURE_BYTES, "signature.signature"),
+            type: parsed.signature.type
+        },
+        votes: parsed.votes.map((vote) => ({
+            community: {
+                // dag-cbor rejects `undefined`, so an absent name omits the key entirely.
+                ...(vote.community.name !== undefined ? { name: vote.community.name } : {}),
+                publicKey: publicKeyToBytes(vote.community.publicKey)
+            },
+            vote: vote.vote
+        }))
+    };
+}
+/**
+ * Map a decoded wire value back to a VotesBundle, validating both the wire shape and the
+ * full bundle schema (B58 key, distinct communities, name bound). Throws on anything
+ * malformed — callers on untrusted paths treat a throw as an invalid block.
+ */
+export function fromWireBundle(wire) {
+    const parsed = WireBundleSchema.parse(wire);
+    if (parsed.address.length !== ADDRESS_BYTES)
+        throw new Error(`address must be ${ADDRESS_BYTES} bytes`);
+    if (parsed.signature.signature.length !== SIGNATURE_BYTES) {
+        throw new Error(`signature.signature must be ${SIGNATURE_BYTES} bytes`);
+    }
+    return VotesBundleSchema.parse({
+        address: bytesToHex(parsed.address),
+        blockNumber: parsed.blockNumber,
+        signature: {
+            signature: bytesToHex(parsed.signature.signature),
+            type: parsed.signature.type
+        },
+        votes: parsed.votes.map((vote) => ({
+            community: {
+                ...(vote.community.name !== undefined ? { name: vote.community.name } : {}),
+                publicKey: publicKeyFromBytes(vote.community.publicKey)
+            },
+            vote: vote.vote
+        }))
+    });
+}
+/** Canonically encode a VotesBundle to its binary dag-cbor block bytes. */
+export function encodeBundle(bundle) {
+    return encodeCanonical(toWireBundle(bundle));
+}
+/** Decode binary block bytes back to a VotesBundle. Throws on malformed bytes. */
+export function decodeBundle(bytes) {
+    return fromWireBundle(dagCbor.decode(bytes));
+}
+/** The CIDv1 (dag-cbor, sha2-256) content address of already-encoded bundle block bytes. */
+export async function bundleCidForBytes(bytes) {
+    const digest = await sha256.digest(bytes);
+    return CID.createV1(dagCborCode, digest);
+}
+/** The CIDv1 (dag-cbor, sha2-256) content address of a VotesBundle. */
+export async function bundleCid(bundle) {
+    return bundleCidForBytes(encodeBundle(bundle));
+}

package/dist/crdt/crdt.d.ts

@@ -0,0 +1,22 @@
+import type { CID } from "multiformats/cid";
+import type { BucketMath } from "../chain/types.js";
+import type { BundleStore, LwwResolve, VoteCrdt } from "./types.js";
+/** Highest `blockNumber` wins; tie broken by lowest bundle CID. */
+export declare const lwwResolve: LwwResolve;
+export interface VoteCrdtDeps {
+    store: BundleStore;
+    /** Bucket math for `criteria.blocksPerBucket`, used by `prune` to age out expired bundles. */
+    bucketMath: BucketMath;
+    /** How many buckets a bundle stays valid after its blockNumber's bucket (`criteria.voteExpiryBuckets`). */
+    voteExpiryBuckets: number;
+    /** Conflict resolver; defaults to {@link lwwResolve}. */
+    resolve?: LwwResolve;
+    /**
+     * True while a bundle's deferred chain/name checks are still pending (see
+     * verify/background.ts). `prune` keeps a superseded bundle whose superseder is provisional —
+     * the fallback winner if the provisional bundle is later evicted. Omitted ⇒ nothing is
+     * provisional (prior behaviour).
+     */
+    isProvisional?: (cid: CID) => boolean;
+}
+export declare function makeVoteCrdt(deps: VoteCrdtDeps): VoteCrdt;

package/dist/crdt/crdt.js

@@ -0,0 +1,127 @@
+/**
+ * The state-based grow-only CRDT: a last-write-wins element-set keyed by the voting wallet.
+ * Each bundle is a standalone dag-cbor block; there are no parent links and no DAG to walk.
+ * Aggregation is a monotonic union (a CRDT join) — combining two peers' sets can only add
+ * bundles, never remove one — so a liar can omit a vote but cannot subtract one an honest
+ * peer serves (see DESIGN.md "CRDT", "Can always-online peers drop votes?").
+ *
+ * Conflict resolution per wallet: highest `blockNumber` wins, tie broken by lowest bundle CID,
+ * for determinism across clients. Bundles admitted here are assumed already validity-gated
+ * (signature, gate, name) by the transport before merge — the CRDT is trust-neutral
+ * storage, not a verifier.
+ */
+/** Byte-lexicographic compare of two CIDs (returns <0, 0, >0). */
+function compareCid(a, b) {
+    const x = a.bytes;
+    const y = b.bytes;
+    const n = Math.min(x.length, y.length);
+    for (let i = 0; i < n; i++) {
+        const xi = x[i];
+        const yi = y[i];
+        if (xi !== yi)
+            return xi - yi;
+    }
+    return x.length - y.length;
+}
+/** Highest `blockNumber` wins; tie broken by lowest bundle CID. */
+export const lwwResolve = (a, b) => {
+    if (a.bundle.blockNumber !== b.bundle.blockNumber) {
+        return a.bundle.blockNumber > b.bundle.blockNumber ? a.cid : b.cid;
+    }
+    return compareCid(a.cid, b.cid) <= 0 ? a.cid : b.cid;
+};
+export function makeVoteCrdt(deps) {
+    const { store, bucketMath, voteExpiryBuckets } = deps;
+    const resolve = deps.resolve ?? lwwResolve;
+    const isProvisional = deps.isProvisional ?? (() => false);
+    // The working set of integrated bundles, keyed by CID string, mirrored from the store for
+    // fast reduction.
+    const bundles = new Map();
+    /**
+     * A bundle has decayed once the current bucket is past its `blockNumber`'s bucket plus the
+     * expiry window (see DESIGN.md "Passive expiry"). This is the read-time filter that keeps an
+     * expired vote out of the tally and the checkpoint — the same predicate `prune` uses to
+     * bound memory.
+     */
+    function isExpired(bundle, currentBucket) {
+        return currentBucket > bucketMath.bucketForBlock(bundle.blockNumber) + voteExpiryBuckets;
+    }
+    /** Integrate one bundle CID from the store into the working set (idempotent). */
+    async function integrate(cid) {
+        const key = cid.toString();
+        if (bundles.has(key))
+            return;
+        const bundle = await store.get(cid);
+        if (!bundle) {
+            throw new Error(`missing bundle ${key} during merge; fetch it into the store before merging`);
+        }
+        bundles.set(key, { cid, bundle });
+    }
+    /** LWW winner per wallet across the working set; `eligible` restricts the reduction. */
+    function winnersByWallet(eligible) {
+        const winners = new Map();
+        for (const entry of bundles.values()) {
+            if (eligible && !eligible(entry.cid))
+                continue;
+            const wallet = entry.bundle.address.toLowerCase();
+            const prev = winners.get(wallet);
+            if (!prev) {
+                winners.set(wallet, entry);
+                continue;
+            }
+            const winnerCid = resolve({ bundle: prev.bundle, cid: prev.cid }, { bundle: entry.bundle, cid: entry.cid });
+            winners.set(wallet, winnerCid.equals(prev.cid) ? prev : entry);
+        }
+        return winners;
+    }
+    /**
+     * One winner per wallet (LWW, optionally restricted to `eligible` bundles), minus expired
+     * winners. A winning empty-votes bundle is the withdrawal form and is returned as-is; the
+     * tally treats it as "no vote". A winner past its expiry window drops the wallet entirely —
+     * the read-time filter that keeps a decayed vote out of the tally and the checkpoint.
+     */
+    function currentEntries(currentBucket, eligible) {
+        return [...winnersByWallet(eligible).values()].filter((e) => !isExpired(e.bundle, currentBucket));
+    }
+    return {
+        async add(bundle) {
+            const cid = await store.put(bundle);
+            bundles.set(cid.toString(), { cid, bundle });
+            return cid;
+        },
+        async merge(cids) {
+            for (const cid of cids)
+                await integrate(cid);
+        },
+        current(currentBucket) {
+            return currentEntries(currentBucket).map((e) => e.bundle);
+        },
+        currentEntries,
+        remove(cid) {
+            bundles.delete(cid.toString());
+        },
+        nodeCount() {
+            return bundles.size;
+        },
+        async prune(currentBucket) {
+            const winners = winnersByWallet();
+            const removed = [];
+            for (const [key, entry] of bundles) {
+                const wallet = entry.bundle.address.toLowerCase();
+                const winner = winners.get(wallet);
+                const isWinner = winner === entry;
+                const bundleBucket = bucketMath.bucketForBlock(entry.bundle.blockNumber);
+                const expired = currentBucket > bundleBucket + voteExpiryBuckets;
+                // Drop superseded (non-winning) bundles and any bundle past its expiry window —
+                // EXCEPT a superseded bundle whose superseder is still provisional: it is the
+                // fallback winner if that bundle's deferred check evicts it.
+                const shieldedByProvisionalWinner = !isWinner && !expired && winner !== undefined && isProvisional(winner.cid);
+                if ((!isWinner || expired) && !shieldedByProvisionalWinner) {
+                    bundles.delete(key);
+                    removed.push(entry.cid);
+                }
+            }
+            return removed;
+        }
+    };
+}

package/dist/crdt/store.d.ts

@@ -0,0 +1,8 @@
+import type { BundleStore } from "./types.js";
+/**
+ * In-memory {@link BundleStore}, keyed by content address. Used by the engine's unit
+ * tests and as a no-persistence default; the transport backs the same interface with the
+ * host's Helia blockstore (put/get by CID, bitswap for unknown CIDs) — see DESIGN.md
+ * "Transport". The store computes the CID on `put`, so callers never assign addresses.
+ */
+export declare function makeMemoryBundleStore(): BundleStore;

package/dist/crdt/store.js

@@ -0,0 +1,23 @@
+import { bundleCid } from "./codec.js";
+/**
+ * In-memory {@link BundleStore}, keyed by content address. Used by the engine's unit
+ * tests and as a no-persistence default; the transport backs the same interface with the
+ * host's Helia blockstore (put/get by CID, bitswap for unknown CIDs) — see DESIGN.md
+ * "Transport". The store computes the CID on `put`, so callers never assign addresses.
+ */
+export function makeMemoryBundleStore() {
+    const byCid = new Map();
+    return {
+        async put(bundle) {
+            const cid = await bundleCid(bundle);
+            byCid.set(cid.toString(), bundle);
+            return cid;
+        },
+        async get(cid) {
+            return byCid.get(cid.toString());
+        },
+        async has(cid) {
+            return byCid.has(cid.toString());
+        }
+    };
+}

package/dist/crdt/types.d.ts

@@ -0,0 +1,87 @@
+import type { CID } from "multiformats/cid";
+import type { VotesBundle } from "../schema/votes.js";
+/**
+ * State-based grow-only LWW winner-set interfaces.
+ *
+ * State is a last-write-wins element-set keyed by the gating-chain wallet address. Each
+ * bundle is a standalone dag-cbor block addressed by its CID — it carries no parent links.
+ * The live path gossips individual bundle CIDs; a peer fetches each unknown bundle by CID,
+ * verifies it (at the transport gate), and LWW-merges it into its per-wallet winner-set.
+ * There is no DAG to walk and no notion of history "heads" — convergence comes from
+ * gossipsub flood, the heartbeat re-gossip, and checkpoint reconciliation.
+ * See DESIGN.md "CRDT".
+ */
+/**
+ * The conflict-resolution rule for two bundles claiming the same wallet:
+ * higher blockNumber wins; tie broken by lower bundle CID. Returns the winner.
+ * Pure and deterministic so all clients agree.
+ */
+export type LwwResolve = (a: {
+    bundle: VotesBundle;
+    cid: CID;
+}, b: {
+    bundle: VotesBundle;
+    cid: CID;
+}) => CID;
+/**
+ * The CRDT store. `add` and `merge` only ever grow knowledge; `current` is the
+ * LWW reduction (one bundle per wallet) that the tally consumes.
+ */
+export interface VoteCrdt {
+    /** Store a locally produced bundle as a standalone dag-cbor block. Returns its CID. */
+    add(bundle: VotesBundle): Promise<CID>;
+    /**
+     * Integrate remote bundle CIDs: fetch any unknown bundle by CID and LWW-merge it into the
+     * winner-set. There is no ancestor recursion — each CID is a standalone bundle. Idempotent
+     * and order-independent.
+     */
+    merge(cids: CID[]): Promise<void>;
+    /**
+     * LWW reduction (at most one bundle per wallet), filtered to the given bucket: a wallet
+     * whose winning bundle has expired drops out entirely, so neither the tally nor a
+     * checkpoint ever carries a decayed vote. `currentBucket` is `bucketForBlock(currentBlock)`.
+     */
+    current(currentBucket: number): VotesBundle[];
+    /**
+     * {@link current} with each winner's CID alongside its bundle — the CID is the key the
+     * engine's per-bundle check state ({@link BundleChecks}) is tracked under. The optional
+     * `eligible` predicate restricts the LWW reduction to bundles it admits: the checkpoint
+     * encoder passes "fully verified", so a provisionally admitted winner does not HIDE its
+     * verified predecessor from the served checkpoint — the reduction falls back to the newest
+     * bundle that IS eligible. No predicate reduces over everything (the tally's view).
+     */
+    currentEntries(currentBucket: number, eligible?: (cid: CID) => boolean): Array<{
+        cid: CID;
+        bundle: VotesBundle;
+    }>;
+    /**
+     * Drop one bundle from the working set — the eviction path for a provisionally admitted
+     * bundle whose deferred chain/name check failed (see verify/background.ts). Local
+     * housekeeping of an invalid admit, not a protocol subtract: the union/LWW semantics over
+     * VALID bundles are untouched, and the block bytes may stay in the blockstore.
+     */
+    remove(cid: CID): void;
+    /**
+     * Drop bundles older than `voteExpiryBuckets` and those superseded per wallet from the
+     * in-memory working set, bounding memory. Correctness does not depend on it — `current`
+     * filters expiry at read time — so this is housekeeping, not the guarantee. A superseded
+     * bundle whose superseder is still provisional (per the injected `isProvisional`) is KEPT:
+     * it is the fallback winner if the provisional bundle's deferred check evicts it. Returns
+     * the removed CIDs so the engine can drop their per-bundle check state.
+     */
+    prune(currentBucket: number): Promise<CID[]>;
+    /** Size of the in-memory working set — lets callers/tests observe that `prune` shrinks it. */
+    nodeCount(): number;
+}
+/**
+ * Persistence for vote bundles, backed by the host's Helia blockstore (dag-cbor).
+ * Declared as its own seam so the CRDT can be tested against an in-memory store.
+ */
+export interface BundleStore {
+    put(bundle: VotesBundle): Promise<CID>;
+    /** `options.signal` cancels an in-flight bitswap fetch (the gate's per-fetch timeout aborts it). */
+    get(cid: CID, options?: {
+        signal?: AbortSignal;
+    }): Promise<VotesBundle | undefined>;
+    has(cid: CID): Promise<boolean>;
+}

package/dist/crdt/types.js

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

package/dist/encoding/canonical.d.ts

@@ -0,0 +1,22 @@
+import type { Criteria } from "../schema/criteria.js";
+/**
+ * Canonical encoding.
+ *
+ * dag-cbor is itself the canonical form the whole protocol relies on: it sorts map
+ * keys deterministically and rejects `undefined`, so identical logical objects encode
+ * to identical bytes regardless of authoring key order. That property is what makes
+ * `topic = CID(dag-cbor(criteria))` a self-validating binding (see DESIGN.md
+ * "Criteria document"). Nothing here re-implements canonicalisation; it just names the
+ * single encoder the rest of the library must route through so the bytes never diverge.
+ *
+ * This module is pure and has no libp2p/helia import, so it is unit-testable offline.
+ */
+/** Canonically encode any dag-cbor-safe value to bytes. */
+export declare function encodeCanonical(value: unknown): Uint8Array;
+/**
+ * Canonically encode a criteria document. This is the exact byte sequence whose CID
+ * becomes the pubsub topic, so it MUST be stable across clients and library versions.
+ */
+export declare function encodeCriteria(criteria: Criteria): Uint8Array;
+/** The dag-cbor codec code (0x71), exposed so callers build CIDs with the right codec. */
+export declare const dagCborCode: 113;

package/dist/encoding/canonical.js

@@ -0,0 +1,26 @@
+import * as dagCbor from "@ipld/dag-cbor";
+/**
+ * Canonical encoding.
+ *
+ * dag-cbor is itself the canonical form the whole protocol relies on: it sorts map
+ * keys deterministically and rejects `undefined`, so identical logical objects encode
+ * to identical bytes regardless of authoring key order. That property is what makes
+ * `topic = CID(dag-cbor(criteria))` a self-validating binding (see DESIGN.md
+ * "Criteria document"). Nothing here re-implements canonicalisation; it just names the
+ * single encoder the rest of the library must route through so the bytes never diverge.
+ *
+ * This module is pure and has no libp2p/helia import, so it is unit-testable offline.
+ */
+/** Canonically encode any dag-cbor-safe value to bytes. */
+export function encodeCanonical(value) {
+    return dagCbor.encode(value);
+}
+/**
+ * Canonically encode a criteria document. This is the exact byte sequence whose CID
+ * becomes the pubsub topic, so it MUST be stable across clients and library versions.
+ */
+export function encodeCriteria(criteria) {
+    return dagCbor.encode(criteria);
+}
+/** The dag-cbor codec code (0x71), exposed so callers build CIDs with the right codec. */
+export const dagCborCode = dagCbor.code;

package/dist/errors.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Library error types.
+ *
+ * The engine and client lifecycle are implemented — schemas, encoding, topic derivation,
+ * the verify pipeline, the LWW winner-set CRDT, the tally, the transport's
+ * validate-before-forward gossip gate, and the reactive `PubsubVoter` / `Contest` / `ContestVote`
+ * facade. Republishing a live vote is the client's job (no scheduler, no persistence); see
+ * DESIGN.md "Republishing is the client's job".
+ */
+/** Thrown by any facade path deferred to a later version (none in v1's shipped surface). */
+export declare class NotImplementedError extends Error {
+    constructor(what: string);
+}
+/**
+ * Thrown when a criteria document names a rule `type` this client does not
+ * implement (in the `rule`/`weight` slot or in `requires.rules`). A
+ * client that hits this is too old (or missing a host override) and must recuse
+ * itself from the contest rather than miscount. See DESIGN.md "Rules".
+ */
+export declare class UnknownRuleError extends Error {
+    readonly slot: "rule" | "weight" | "requires";
+    readonly type: string;
+    constructor(slot: "rule" | "weight" | "requires", type: string);
+}
+/**
+ * Thrown at construction when the injected Helia node's libp2p has no usable pubsub
+ * (gossipsub) service at `libp2p.services.pubsub`. The library broadcasts and receives
+ * winner bundle CIDs over gossipsub, so a node without it cannot participate. Helia's default
+ * libp2p services do NOT include pubsub — the host must register a gossipsub service
+ * (e.g. `@chainsafe/libp2p-gossipsub`) before passing the node in. We fail fast here
+ * rather than letting a later `publish`/`subscribe` fail obscurely. See DESIGN.md
+ * "Transport".
+ */
+export declare class MissingPubsubError extends Error {
+    constructor();
+}
+/**
+ * Thrown at construction when the injected Helia node has no usable `blockstore`. Vote
+ * bundles are immutable content-addressed blocks fetched by CID through the host's
+ * blockstore (bitswap retrieves through it), so the engine cannot resolve a bundle without
+ * one. Note "bitswap" is not a separately introspectable property of a Helia node — it
+ * is a block broker wired *beneath* `blockstore` — so the checkable guarantee is a
+ * well-formed blockstore, the surface bitswap retrieves through. See DESIGN.md
+ * "Transport".
+ */
+export declare class MissingBlockstoreError extends Error {
+    constructor();
+}
+/**
+ * Thrown at construction when the injected Helia node's libp2p has no usable **fetch
+ * service** at `libp2p.services.fetch`. The root-record pull — cold-start / reconnect
+ * checkpoint sync — rides the libp2p fetch protocol (this library registers its own lookup
+ * and runs its own requester), so the host must register `@libp2p/fetch` on the shared
+ * node. See DESIGN.md "Checkpoints" and "Deferred pkc-js work".
+ */
+export declare class MissingFetchError extends Error {
+    constructor();
+}
+/**
+ * Thrown once a voter has been `destroy()`ed and something tries to keep using it. Unlike `stop()`
+ * (which leaves every topic but keeps the client reusable), `destroy()` is terminal: every contest
+ * is stopped and can no longer update or publish. Surfaced by `createContest` / `createContestVote`,
+ * and by a pre-existing `Contest.update()` / `ContestVote.publish()`. Construct a new
+ * `PubsubVoter` to participate again.
+ */
+export declare class VoterDestroyedError extends Error {
+    constructor();
+}
+/** Thrown when a publish (vote/withdraw) is attempted on a voter constructed without a signer. */
+export declare class ReadOnlyError extends Error {
+    constructor();
+}