@bitsocial/pubsub-voting 0.7.5 → 0.7.7

package/README.md

@@ -34,6 +34,18 @@ See [DESIGN.md](./DESIGN.md) for the full rationale, including how this resists
 
 ## Usage
 
+Hosts with a dedicated votes blockstore can use `voter.retainsBlock(cid)` during garbage
+collection. This synchronous, network-free check protects every joined contest's admitted
+bundles (including provisional votes and verified fallback winners) and its last encoded
+checkpoint root/chunks. It compares multihashes, so filesystem stores that enumerate CIDs
+with another codec work too. Recheck immediately before deletion under your blockstore's
+operation lock; also protect concurrent reads/writes and retain superseded blocks for a
+grace period so peers can finish pulling older checkpoints. For a shared store, retain
+other applications' blocks too. The method does not run GC, refresh checkpoints, or impose
+a storage quota. Persisted checkpoint snapshots are self-contained and must be retained
+independently of the blockstore.
+
+
 The library never starts a node and never takes a host SDK (there is no `pkc` argument). A host passes its own running Helia node in directly and injects its seams into a single `PubsubVoter`. **Identity is not one of the seams**: the voting wallet (`VoteSigner`) belongs to each ballot, passed to `createContestVote`, so one voter on the host's shared node publishes for as many wallets as the host holds keys for — and a client that only renders tallies never touches key material.
 
 | Seam | Type | Required | Purpose |

package/dist/client/voter.d.ts

@@ -348,6 +348,15 @@ export interface VoteClient {
      * `createContest` / `update()` after.
      */
     stop(): Promise<void>;
+    /**
+     * Synchronous GC retention check for joined contests: admitted bundles (including
+     * pending verification and fallback winners) and the last encoded checkpoint.
+     * Compares multihashes, since filesystem stores may enumerate another CID codec.
+     * Recheck immediately before deletion under the host's blockstore lock; protect
+     * in-flight reads/writes, other users of a shared store, and a grace period for
+     * superseded checkpoints. No I/O and no permission to delete a shared store's data.
+     */
+    retainsBlock(cid: CID): boolean;
     /**
      * Terminal teardown (mirrors pkc-js `destroy`): leave every topic, unregister the fetch
      * responder, and mark the voter and all its contests destroyed. Unlike `stop`, this is NOT
@@ -468,6 +477,7 @@ export declare class PubsubVoter implements VoteClient {
         votes: Vote[];
         signer: VoteSigner;
     }): Promise<ContestVote>;
+    retainsBlock(cid: CID): boolean;
     stop(): Promise<void>;
     destroy(): Promise<void>;
 }

package/dist/client/voter.js

@@ -20,7 +20,7 @@ import { makeVerdictCache } from "../verify/cache.js";
 import { makeNameResolutionCache } from "../verify/name-resolution-cache.js";
 import { makeStorage } from "../storage/node.js";
 import { makeAnnouncer } from "../transport/announce/node.js";
-import { encode as encodeDagCbor } from "@ipld/dag-cbor";
+import { encode as encodeDagCbor, code as dagCborCode } from "@ipld/dag-cbor";
 import { sha256 } from "viem";
 import { makeBackgroundVerifier } from "../verify/background.js";
 import { preflightCommunityNames } from "../verify/name-preflight.js";
@@ -1110,6 +1110,10 @@ class ContestEngine {
             throw new VoterDestroyedError();
         if (this.#joined)
             return;
+        // A host may have collected this stopped contest's old checkpoint blocks.
+        // Re-encode/re-store them before serving the cached root on a re-join.
+        this.#checkpointDirty = true;
+        this.#rootRecordCache = undefined;
         const limit = pLimit(GATE_CONCURRENCY);
         const gate = makeGossipGate({
             decodeMessage: decodeVoteMessage,
@@ -1768,6 +1772,13 @@ class ContestEngine {
     latestCheckpointRoot() {
         return this.#rootRecordCache?.record.root;
     }
+    /** Keep all admitted bundles, including pending checks and verified fallback winners. */
+    retainsBlock(cid) {
+        if (!this.#joined)
+            return false;
+        const key = CID.createV1(dagCborCode, cid.multihash).toString();
+        return this.#checks.has(key) || (this.#rootRecordCache?.blocks.some((block) => block.cid.toString() === key) ?? false);
+    }
     /**
      * The current root record plus its checkpoint chunk blocks, for the bulk responder's inline
      * path (see `BulkFetchRootRecord.chunkBlocks`): the blocks are already in hand from the same
@@ -2528,6 +2539,13 @@ export class PubsubVoter {
             this.#unregisterResponder();
         }
     };
+    retainsBlock(cid) {
+        for (const engine of this.#engines.values()) {
+            if (engine.retainsBlock(cid))
+                return true;
+        }
+        return false;
+    }
     async stop() {
         // Reset each read view (detach its engine listeners, clear `#subscribed`) so it can
         // `update()` again — this is what keeps `stop()` reusable. Then leave any engine with no

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bitsocial/pubsub-voting",
-  "version": "0.7.5",
+  "version": "0.7.7",
   "description": "Trustless pubsub voting over a shared libp2p/Helia node.",
   "type": "module",
   "license": "GPL-3.0-or-later",
@@ -74,11 +74,11 @@
     "@libp2p/identify": "4.1.13",
     "@libp2p/tcp": "11.0.27",
     "@multiformats/multiaddr": "13.0.3",
-    "@pkcprotocol/pkc-js": "0.0.95",
+    "@pkcprotocol/pkc-js": "0.0.96",
     "@release-it/conventional-changelog": "10.0.6",
     "@types/better-sqlite3": "7.6.13",
     "@vitest/coverage-v8": "4.1.11",
-    "commitizen": "4.3.1",
+    "commitizen": "4.3.2",
     "cz-conventional-changelog": "3.3.0",
     "husky": "9.1.7",
     "libp2p": "3.3.9",
@@ -86,5 +86,16 @@
     "strip-json-comments": "5.0.3",
     "typescript": "5.9.3",
     "vitest": "4.1.11"
+  },
+  "overrides": {
+    "@pkcprotocol/pkc-js": {
+      "undici": "7.29.0",
+      "uuid": "13.0.1",
+      "ws": "8.21.3"
+    },
+    "protobufjs": "7.6.6",
+    "release-it": {
+      "undici": "6.28.0"
+    }
   }
 }