@bitsocial/pubsub-voting 0.0.6

package/dist/verify/gate-result-cache.js

@@ -0,0 +1,91 @@
+const memKeyFor = (wallet, sampleBlock) => `${wallet.toLowerCase()}:${sampleBlock}`;
+/**
+ * An in-memory {@link GateResultCache} bounded to `maxEntries` with FIFO eviction. Eviction is
+ * safe because a score is deterministic — an evicted entry only ever costs a re-read, never a
+ * wrong answer; without a bound, a flood of fresh wallets is a memory-exhaustion vector (see
+ * DESIGN.md "Can valid votes clog the topic?").
+ */
+export function makeGateResultCache(maxEntries = 4096) {
+    const byKey = new Map();
+    const order = [];
+    return {
+        get: async (wallet, sampleBlock) => byKey.get(memKeyFor(wallet, sampleBlock)),
+        set: (wallet, sampleBlock, score) => {
+            const k = memKeyFor(wallet, sampleBlock);
+            if (byKey.has(k))
+                return; // idempotent: never refresh position or overwrite a pinned score
+            byKey.set(k, score);
+            order.push(k);
+            if (order.length > maxEntries) {
+                const evicted = order.shift();
+                if (evicted !== undefined)
+                    byKey.delete(evicted);
+            }
+        }
+    };
+}
+/** The persistent gate store's key. `ruleHash` disambiguates: the shared store spans every
+ * contest on the voter, and one wallet can hold different scores under different gate rules
+ * (or the same rule at different chainIds). Same score under the same rule is what lets two
+ * contests over one gate (a 5chan-style directory) share each other's reads. */
+const storeKeyFor = (ruleHash, wallet, sampleBlock) => `${ruleHash}:${wallet.toLowerCase()}:${sampleBlock}`;
+/**
+ * A {@link GateResultCache} layered over the voter's persistent store: an in-memory FIFO front
+ * (the hot path — steady-state gossip hits it synchronously) with read-through to the store on
+ * a miss and fire-and-forget write-through on `set`. Scores travel as decimal strings (JSON has
+ * no bigint). A broken store read or write degrades to a live chain read — never an error into
+ * the verify pipeline — because everything here is a pure function of pinned historical state.
+ */
+export function makePersistentGateResultCache(opts) {
+    const { store, ruleHash } = opts;
+    const mem = makeGateResultCache(opts.maxMemEntries);
+    return {
+        async get(wallet, sampleBlock) {
+            const cached = await mem.get(wallet, sampleBlock);
+            if (cached !== undefined)
+                return cached;
+            let persisted;
+            try {
+                persisted = await store.getItem(storeKeyFor(ruleHash, wallet, sampleBlock));
+            }
+            catch {
+                return undefined;
+            }
+            if (typeof persisted !== "string" || !/^\d+$/.test(persisted))
+                return undefined;
+            const score = BigInt(persisted);
+            mem.set(wallet, sampleBlock, score);
+            return score;
+        },
+        set(wallet, sampleBlock, score) {
+            mem.set(wallet, sampleBlock, score);
+            void store.setItem(storeKeyFor(ruleHash, wallet, sampleBlock), score.toString()).catch(() => {
+                // a failed persist costs a future re-read, never a wrong answer
+            });
+        }
+    };
+}
+/**
+ * Deterministic expiry purge for one rule's persisted gate results — better than LRU here
+ * because staleness is *provable*: a score at bucket B's sample block is only ever consulted
+ * while bundles from B are admissible (within `voteExpiryBuckets` of head), so anything older
+ * than the oldest admissible sample block can never be read again. Run per contest whenever a
+ * head read advances the expiry boundary (see the engine's `#maybePurgeGateResults`); the
+ * store's LRU bound stays as the backstop for rules never purged.
+ */
+export async function purgeExpiredGateResults(opts) {
+    const prefix = `${opts.ruleHash}:`;
+    try {
+        for (const key of await opts.store.keys()) {
+            if (!key.startsWith(prefix))
+                continue;
+            const sampleBlock = Number(key.slice(key.lastIndexOf(":") + 1));
+            if (Number.isFinite(sampleBlock) && sampleBlock < opts.oldestSampleBlock) {
+                await opts.store.removeItem(key);
+            }
+        }
+    }
+    catch {
+        // purge is best-effort; the store's LRU bound is the correctness-free backstop
+    }
+}

package/dist/verify/name-resolution-cache.d.ts

@@ -0,0 +1,59 @@
+import type { NameResolver } from "../chain/types.js";
+import type { LruStorage } from "../storage/types.js";
+/**
+ * Persistent cache of community-name resolutions, a port of pkc-js's `NameResolutionCache`
+ * (clients/name-resolution-cache.ts) — the SAME rule, so a host reasons about one caching
+ * policy across both libraries:
+ *
+ *   - LRU-bounded persistent store, no stored TTL: an entry lives until evicted.
+ *   - Freshness is a per-CALL max-age, modeled on HTTP `Cache-Control: max-age` (RFC 9111
+ *     §5.2.1.1): `maxAgeSeconds: 0` bypasses the cache, `N` serves an entry only while
+ *     `Date.now() - resolvedAtMs <= N * 1000`, `undefined` serves whatever is cached.
+ *   - Only SUCCESSFUL resolutions are stored; a name that fails to resolve is retried by the
+ *     caller, never negatively cached. No stale-while-revalidate.
+ *   - Keyed `{name}::{resolverKey}::{sha256(provider)}` — per resolver identity, because two
+ *     resolvers (or providers) may legitimately disagree during a migration.
+ *
+ * This cache exists because the host's own pkc-js instance caches at ITS call sites, not
+ * inside the injected resolver — so without this layer every verify here pays a live
+ * registry read that pkc-js would have served from cache.
+ */
+export interface NameResolutionCacheEntry {
+    publicKey: string;
+    resolverKey: string;
+    provider: string;
+    resolvedAtMs: number;
+}
+export interface NameResolutionCache {
+    get(args: {
+        name: string;
+        resolverKey: string;
+        provider: string;
+        maxAgeSeconds?: number;
+    }): Promise<NameResolutionCacheEntry | undefined>;
+    set(args: {
+        name: string;
+        resolverKey: string;
+        provider: string;
+        publicKey: string;
+    }): Promise<void>;
+}
+/**
+ * The verify pipeline's freshness bound, matching pkc-js's background resolution call site
+ * (`cache: { maxAge: 3600 }`): a re-pointed name is honored here within at most one hour.
+ * Names gate vote validity, so this is the staleness ceiling a community re-point can see.
+ */
+export declare const NAME_RESOLUTION_MAX_AGE_SECONDS = 3600;
+export declare function makeNameResolutionCache(store: LruStorage): NameResolutionCache;
+/**
+ * The verify pipeline's single resolution path (inline forward-gate AND background verifier):
+ * serve from the cache within {@link NAME_RESOLUTION_MAX_AGE_SECONDS}, otherwise resolve live
+ * and persist a success. `undefined` (no record) is returned uncached — the pkc-js rule.
+ */
+export declare function resolveNameThroughCache(opts: {
+    resolver: NameResolver;
+    name: string;
+    cache: NameResolutionCache | undefined;
+}): Promise<{
+    publicKey: string;
+} | undefined>;

package/dist/verify/name-resolution-cache.js

@@ -0,0 +1,64 @@
+import { sha256, stringToHex } from "viem";
+/**
+ * The verify pipeline's freshness bound, matching pkc-js's background resolution call site
+ * (`cache: { maxAge: 3600 }`): a re-pointed name is honored here within at most one hour.
+ * Names gate vote validity, so this is the staleness ceiling a community re-point can see.
+ */
+export const NAME_RESOLUTION_MAX_AGE_SECONDS = 3600;
+const keyFor = (args) => `${args.name}::${args.resolverKey}::${sha256(stringToHex(args.provider))}`;
+export function makeNameResolutionCache(store) {
+    return {
+        async get(args) {
+            if (args.maxAgeSeconds === 0)
+                return undefined;
+            let entry;
+            try {
+                entry = await store.getItem(keyFor(args));
+            }
+            catch {
+                return undefined; // a broken cache read degrades to a live resolution, never a failure
+            }
+            if (entry === null ||
+                typeof entry !== "object" ||
+                typeof entry.publicKey !== "string" ||
+                typeof entry.resolvedAtMs !== "number") {
+                return undefined;
+            }
+            const cached = entry;
+            if (typeof args.maxAgeSeconds === "number" && Date.now() - cached.resolvedAtMs > args.maxAgeSeconds * 1000) {
+                return undefined;
+            }
+            return cached;
+        },
+        async set(args) {
+            const entry = {
+                publicKey: args.publicKey,
+                resolverKey: args.resolverKey,
+                provider: args.provider,
+                resolvedAtMs: Date.now()
+            };
+            try {
+                await store.setItem(keyFor(args), entry);
+            }
+            catch {
+                // a failed cache write costs a future re-resolution, never a wrong answer
+            }
+        }
+    };
+}
+/**
+ * The verify pipeline's single resolution path (inline forward-gate AND background verifier):
+ * serve from the cache within {@link NAME_RESOLUTION_MAX_AGE_SECONDS}, otherwise resolve live
+ * and persist a success. `undefined` (no record) is returned uncached — the pkc-js rule.
+ */
+export async function resolveNameThroughCache(opts) {
+    const { resolver, name, cache } = opts;
+    const identity = { name, resolverKey: resolver.key, provider: resolver.provider };
+    const cached = await cache?.get({ ...identity, maxAgeSeconds: NAME_RESOLUTION_MAX_AGE_SECONDS });
+    if (cached)
+        return { publicKey: cached.publicKey };
+    const record = await resolver.resolve({ name });
+    if (record && cache)
+        await cache.set({ ...identity, publicKey: record.publicKey });
+    return record;
+}

package/dist/verify/signature.d.ts

@@ -0,0 +1,9 @@
+import type { VotesBundle } from "../schema/votes.js";
+import type { OfflineBundleVerifier, VerifyResult } from "./types.js";
+export declare function verifyBundleSignature(args: {
+    bundle: VotesBundle;
+    criteriaCid: Uint8Array;
+    chainId: number;
+}): Promise<VerifyResult>;
+/** The {@link OfflineBundleVerifier} seam, backed by {@link verifyBundleSignature}. */
+export declare const offlineBundleVerifier: OfflineBundleVerifier;

package/dist/verify/signature.js

@@ -0,0 +1,55 @@
+import { recoverTypedDataAddress } from "viem";
+import { ballotTypedData, EIP712_SIGNATURE_TYPE } from "../signer/eip712.js";
+/**
+ * Offline verify stage 1, signature half: recover the EIP-712 ballot signer and check it
+ * equals `bundle.address`. Pure and cheap (no chain read), so it runs first in the gate —
+ * a bad signature drops a vote before any fetch or chain work (see DESIGN.md "Transport").
+ *
+ * The recovered signer *is* the voter (there is no pkc-js author, no author->wallet
+ * binding). Rebuilding the typed data from the criteria CID bytes + chainId + the bundle's
+ * `votes`/`blockNumber` means a signature gathered for one contest, chain, or block cannot
+ * validate on another — the binding is in the hash, not in a trusted `address` field, so a
+ * forged `address` simply fails the recovery check here.
+ */
+/** True when `s` is `0x`-hex, narrowing it to viem's `Hex` without an `any` cast. */
+function isHex(s) {
+    return s.startsWith("0x");
+}
+export async function verifyBundleSignature(args) {
+    const { bundle, criteriaCid, chainId } = args;
+    if (bundle.signature.type !== EIP712_SIGNATURE_TYPE) {
+        return {
+            valid: false,
+            disposition: "reject",
+            reason: `unsupported signature type "${bundle.signature.type}" (expected "${EIP712_SIGNATURE_TYPE}")`
+        };
+    }
+    if (!isHex(bundle.signature.signature)) {
+        return { valid: false, disposition: "reject", reason: "signature is not 0x-hex" };
+    }
+    const typedData = ballotTypedData({
+        criteriaCid,
+        chainId,
+        votes: bundle.votes,
+        blockNumber: bundle.blockNumber
+    });
+    let recovered;
+    try {
+        recovered = await recoverTypedDataAddress({ ...typedData, signature: bundle.signature.signature });
+    }
+    catch (err) {
+        return { valid: false, disposition: "reject", reason: `signature does not recover: ${err.message}` };
+    }
+    // The recovered address is EIP-55 checksummed; `bundle.address` may be lowercase or
+    // differently cased. Compare case-insensitively.
+    if (recovered.toLowerCase() !== bundle.address.toLowerCase()) {
+        return {
+            valid: false,
+            disposition: "reject",
+            reason: `recovered signer ${recovered} does not match bundle.address ${bundle.address}`
+        };
+    }
+    return { valid: true };
+}
+/** The {@link OfflineBundleVerifier} seam, backed by {@link verifyBundleSignature}. */
+export const offlineBundleVerifier = { verifyBundleSignature };

package/dist/verify/types.d.ts

@@ -0,0 +1,101 @@
+import type { VotesBundle } from "../schema/votes.js";
+/**
+ * Verification interfaces, design only.
+ *
+ * Verification has one cheap, offline stage (no chain reads) and one chain stage:
+ *   1. offline: recover the EIP-712 signer and check it equals bundle.address, and the
+ *      criteria-bound constraints (votes.length <= maxVotesPerAddress, vote in range).
+ *      Pairwise-distinct community.publicKeys is enforced even earlier, by
+ *      VotesBundleSchema at parse time (see DESIGN.md "Votes wire")
+ *   2. chain: the `rule` (gate) + weight rules read state at the bucket block, and
+ *      each vote's community.name claim is resolved through the injected nameResolvers
+ *      (a name that does not resolve to the claimed publicKey drops the bundle)
+ *
+ * The tally runs stage 2 lazily (only where it can change the visible ranking), so the
+ * cheap offline check is split out and runs first — a bad signature drops a vote for zero
+ * chain reads. There is no separate wallet-binding stage: the single wallet signature is
+ * the identity. See DESIGN.md "Identity: the voting wallet, nothing else" and "Tally".
+ */
+/**
+ * How a failing verdict should be blamed, mirroring the gossip gate's `reject`/`ignore`
+ * split (see DESIGN.md "Transport"):
+ *   - "reject": PROVABLY invalid — a pure function of the bundle bytes and pinned historical
+ *     chain state (bad signature, out-of-range vote, wallet the gate rejects at the bucket
+ *     block). Deterministic and stable, so it is safe to penalize the sender AND to cache.
+ *   - "ignore": not provably the sender's fault because the check is view- or clock-dependent
+ *     and two honest peers can legitimately disagree right now (a `community.name` resolved *at
+ *     head* during a re-point window; a `blockNumber` bucket ahead of this verifier's chain
+ *     head). No penalty, and NOT cached — the verdict can change as heads/records converge.
+ */
+export type VerdictDisposition = "reject" | "ignore";
+export type VerifyOk = {
+    valid: true;
+};
+export type VerifyFail = {
+    valid: false;
+    disposition: VerdictDisposition;
+    reason: string;
+};
+export type VerifyResult = VerifyOk | VerifyFail;
+/** Stage 1: ballot signature only. No chain access. */
+export interface OfflineBundleVerifier {
+    /**
+     * Rebuild the EIP-712 ballot typed data from the criteria CID bytes + chainId + the
+     * bundle's `votes` and `blockNumber` (see signer/eip712.ts), recover the signer with
+     * `viem.recoverTypedDataAddress`, and check it equals `bundle.address`. No chain read.
+     */
+    verifyBundleSignature(args: {
+        bundle: VotesBundle;
+        criteriaCid: Uint8Array;
+        chainId: number;
+    }): Promise<VerifyResult>;
+}
+/**
+ * A passing full-bundle verdict. Beyond `valid: true` it carries the work the gate already
+ * did so downstream stages need not redo it:
+ *   - `ruleScore`: the gate `rule`'s score for the voting wallet at the bucket block
+ *     (always `> 0n` here — `0n` would have failed the gate).
+ *   - `resolvedNames`: for each vote that carried a `community.name`, the `publicKey` the name
+ *     resolved to (equal to the claimed key, since a mismatch fails the gate). Votes with no
+ *     name are absent. Lets a UI show a verified name without re-resolving.
+ */
+export interface BundleVerdictValid {
+    valid: true;
+    ruleScore: bigint;
+    resolvedNames: Record<string, string>;
+}
+/**
+ * The full validity verdict for one bundle: signature + criteria constraints + on-chain
+ * gate (`rule`) + community-name resolution, in cheap-to-expensive order with early exit. This is
+ * what the gossip forward-gate runs *before* re-forwarding (see DESIGN.md "Transport"): a
+ * failing verdict is dropped and never forwarded, stored, or counted. Weight *magnitude*
+ * (ranking, not validity) is deliberately NOT computed here — the tally derives it lazily.
+ */
+export type BundleVerdict = BundleVerdictValid | VerifyFail;
+/** Runs the full validity pipeline for one already-fetched, schema-parsed bundle. */
+export interface BundleVerifier {
+    verify(bundle: VotesBundle): Promise<BundleVerdict>;
+    /**
+     * Stage 1 only: signature + criteria constraints — local, µs, no chain read and no name
+     * resolution. This is what admits a bundle *provisionally* on the cold-join chase path; the
+     * deferred network checks (gate chain read, name resolution) then run in the background
+     * chain verifier and either confirm the bundle or evict it (see verify/background.ts and
+     * DESIGN.md "Background chain verification").
+     */
+    verifyOffline(bundle: VotesBundle): Promise<VerifyResult>;
+}
+/**
+ * The per-bundle record of the two deferred *network* checks. The offline checks (signature,
+ * constraints) are never recorded here — they are synchronous preconditions for admission, so
+ * an admitted bundle has always passed them.
+ *
+ *   - `chainVerified`: the gate `rule` scored the wallet `> 0n` at the bucket block. `false`
+ *     means "not yet read", never "failed" — a failed gate evicts the bundle instead.
+ *   - `nameResolved`: `undefined` when the bundle carries no `community.name`; `false` while
+ *     the carried name is unresolved; `true` once it resolved to the claimed `publicKey`. A
+ *     name that resolves to a DIFFERENT key evicts the bundle (it is never counted unchecked).
+ */
+export interface BundleChecks {
+    chainVerified: boolean;
+    nameResolved?: boolean;
+}

package/dist/verify/types.js

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

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "@bitsocial/pubsub-voting",
+  "version": "0.0.6",
+  "description": "Trustless pubsub voting over a shared libp2p/Helia node.",
+  "type": "module",
+  "license": "GPL-3.0-or-later",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bitsocialnet/pubsub-voting.git"
+  },
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "browser": {
+    "./dist/storage/node.js": "./dist/storage/browser.js",
+    "./dist/transport/announce/node.js": "./dist/transport/announce/browser.js"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "typecheck:examples": "tsc -p tsconfig.examples.json --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:integration": "vitest run -c vitest.integration.config.ts",
+    "build:bench": "tsc -p benchmark/tsconfig.json",
+    "bench:cold-join": "node benchmark/run.mjs",
+    "bench:directory-load": "node benchmark/run-directory.mjs",
+    "release": "HUSKY=0 release-it --config config/.release-it.json",
+    "prepare": "husky",
+    "prepublishOnly": "npm run build",
+    "commit": "cz"
+  },
+  "config": {
+    "commitizen": {
+      "path": "cz-conventional-changelog"
+    }
+  },
+  "dependencies": {
+    "@ipld/dag-cbor": "9.2.7",
+    "@libp2p/interface": "3.2.4",
+    "better-sqlite3": "12.9.0",
+    "helia": "6.1.4",
+    "localforage": "1.10.0",
+    "multiformats": "13.4.2",
+    "p-limit": "6.2.0",
+    "viem": "2.54.0",
+    "zod": "4.3.6"
+  },
+  "devDependencies": {
+    "@chainsafe/libp2p-noise": "17.0.0",
+    "@chainsafe/libp2p-yamux": "8.0.1",
+    "@commitlint/cli": "20.4.3",
+    "@commitlint/config-conventional": "20.4.3",
+    "@helia/delegated-routing-v1-http-api-client": "6.0.1",
+    "@libp2p/fetch": "4.1.7",
+    "@libp2p/gossipsub": "16.0.3",
+    "@libp2p/identify": "4.1.8",
+    "@libp2p/tcp": "11.0.22",
+    "@multiformats/multiaddr": "13.0.3",
+    "@pkcprotocol/pkc-js": "0.0.63",
+    "@release-it/conventional-changelog": "10.0.6",
+    "@types/better-sqlite3": "7.6.13",
+    "commitizen": "4.3.1",
+    "cz-conventional-changelog": "3.3.0",
+    "husky": "9.1.7",
+    "libp2p": "3.3.4",
+    "release-it": "19.2.4",
+    "strip-json-comments": "5.0.3",
+    "typescript": "5.9.3",
+    "vitest": "4.1.9"
+  }
+}