@bitsocial/pubsub-voting 0.0.6

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;

package/dist/client/root-puller.js

@@ -0,0 +1,140 @@
+import pLimit from "p-limit";
+import { batchRootsFetchKey, decodeBatchRootsResponse, decodeRootRecord, rootFetchKey, MAX_BATCH_ROOT_KEYS } from "../transport/messages.js";
+/** See the budget note on {@link RootPuller}. */
+export const COLD_START_PEER_FETCH_LIMIT = 24;
+/** See the retry note on {@link RootPuller}. */
+export const COLD_START_FETCH_DEADLINE_MS = 30_000;
+const COLD_START_FETCH_BACKOFF_MS = 400;
+const COLD_START_FETCH_BACKOFF_CAP_MS = 4_000;
+/**
+ * How long a peer's first pending pull waits for same-peer company before its batch flushes.
+ * A directory join fires all its cold starts in one synchronous burst, so one tick would
+ * usually do; a few ms of slack covers joins interleaved with per-contest async work (topic
+ * hashing, chain-client setup) without adding perceptible latency to a lone join.
+ */
+const BATCH_WINDOW_MS = 20;
+/**
+ * One `pLimit(limitPerPeer)` per peer id, created on first use and dropped once its queue
+ * drains, so a long-lived voter does not accumulate limiters for every peer it ever
+ * cold-started against.
+ */
+function makePerPeerBudget(limitPerPeer) {
+    const limiters = new Map();
+    return async (peerId, task) => {
+        let limiter = limiters.get(peerId);
+        if (limiter === undefined) {
+            limiter = pLimit(limitPerPeer);
+            limiters.set(peerId, limiter);
+        }
+        try {
+            return await limiter(task);
+        }
+        finally {
+            if (limiter.activeCount === 0 && limiter.pendingCount === 0)
+                limiters.delete(peerId);
+        }
+    };
+}
+/** Build the voter-wide puller over the host's fetch service. */
+export function makeRootPuller(fetch) {
+    const budget = makePerPeerBudget(COLD_START_PEER_FETCH_LIMIT);
+    const pending = new Map();
+    /** One budgeted+retried fetch of one key (see the retry note on {@link RootPuller}). */
+    const fetchWithRetry = async (peer, key, isLive) => {
+        const deadline = Date.now() + COLD_START_FETCH_DEADLINE_MS;
+        let lastError;
+        for (let attempt = 0;; attempt++) {
+            if (attempt > 0) {
+                if (!isLive() || Date.now() >= deadline)
+                    break; // left or out of time
+                const ceiling = Math.min(COLD_START_FETCH_BACKOFF_CAP_MS, COLD_START_FETCH_BACKOFF_MS * 2 ** (attempt - 1));
+                await new Promise((resolve) => setTimeout(resolve, Math.random() * ceiling));
+                if (!isLive())
+                    return undefined; // left mid-backoff — abandon quietly
+            }
+            try {
+                return await budget(peer.toString(), () => fetch.fetch(peer, key));
+            }
+            catch (error) {
+                lastError = error; // transient (e.g. responder over its inbound-stream cap) — back off and retry
+            }
+        }
+        throw lastError;
+    };
+    /** The per-topic path: today's `<topic>/root` key; a garbage answer rejects the waiters. */
+    const pullSingle = async (peer, topic, waiters) => {
+        try {
+            const value = await fetchWithRetry(peer, rootFetchKey(topic), () => waiters.some((w) => w.isLive()));
+            const record = value === undefined || value === null ? value : decodeRootRecord(value);
+            waiters.forEach((w) => w.resolve(record));
+        }
+        catch (error) {
+            waiters.forEach((w) => w.reject(error));
+        }
+    };
+    /**
+     * The batch path: one stream, one key carrying every pending topic, answers distributed by
+     * request order. NOT_FOUND (a responder without the batch key), a malformed response, or a
+     * length mismatch all degrade to the per-topic path — never to silence.
+     */
+    const pullBatch = async (peer, topics) => {
+        const order = [...topics.keys()];
+        const isLive = () => [...topics.values()].some((waiters) => waiters.some((w) => w.isLive()));
+        try {
+            const value = await fetchWithRetry(peer, batchRootsFetchKey(order), isLive);
+            if (value !== undefined && value !== null) {
+                let records;
+                try {
+                    records = decodeBatchRootsResponse(value);
+                }
+                catch {
+                    records = undefined; // hostile/buggy answer — fall through to per-topic
+                }
+                if (records !== undefined && records.length === order.length) {
+                    order.forEach((topic, i) => topics.get(topic).forEach((w) => w.resolve(records[i] ?? null)));
+                    return;
+                }
+            }
+            // Old responder (NOT_FOUND) or malformed batch answer: degrade to per-topic keys.
+            await Promise.all([...topics.entries()].map(([topic, waiters]) => pullSingle(peer, topic, waiters)));
+        }
+        catch (error) {
+            for (const waiters of topics.values())
+                waiters.forEach((w) => w.reject(error));
+        }
+    };
+    const flush = (peerId) => {
+        const batch = pending.get(peerId);
+        if (batch === undefined)
+            return;
+        pending.delete(peerId);
+        clearTimeout(batch.timer);
+        // A lone topic keeps today's per-topic key — no batch envelope for the common
+        // single-board join; two or more ride one batch stream.
+        if (batch.topics.size === 1) {
+            for (const [topic, waiters] of batch.topics)
+                void pullSingle(batch.peer, topic, waiters);
+        }
+        else {
+            void pullBatch(batch.peer, batch.topics);
+        }
+    };
+    return {
+        pull: (peer, topic, isLive) => new Promise((resolve, reject) => {
+            const peerId = peer.toString();
+            let batch = pending.get(peerId);
+            if (batch === undefined) {
+                const timer = setTimeout(() => flush(peerId), BATCH_WINDOW_MS);
+                timer.unref?.();
+                batch = { peer, topics: new Map(), timer };
+                pending.set(peerId, batch);
+            }
+            const waiters = batch.topics.get(topic) ?? [];
+            waiters.push({ isLive, resolve, reject });
+            batch.topics.set(topic, waiters);
+            // A full batch flushes immediately; the next pull opens a fresh window.
+            if (batch.topics.size >= MAX_BATCH_ROOT_KEYS)
+                flush(peerId);
+        })
+    };
+}