@bitsocial/pubsub-votes 0.0.2

package/dist/store/types.d.ts

@@ -0,0 +1,57 @@
+import type { Vote } from "../schema/votes.js";
+/**
+ * Vote-intent persistence.
+ *
+ * A live vote decays on its own: a bundle is valid for only `voteExpiryBuckets` after its
+ * `blockNumber` (see DESIGN.md "Passive expiry"). Keeping a vote alive means periodically
+ * re-signing the *same choice* with a fresh `blockNumber` and re-broadcasting it. To do
+ * that across a process restart the voter must remember what it chose — but not the signed
+ * bundles (those are immutable, content-addressed, and live in the host's Helia blockstore;
+ * a stale `blockNumber` makes an old bundle useless). What it persists is the re-signable
+ * *intent*: which communities this wallet picked in which contest. On `start()` the voter loads
+ * every stored intent and republishes it; the republish scheduler re-signs each on the
+ * liveness cadence (`ceil(voteExpiryBuckets / 2)` buckets — see DESIGN.md "Lifecycle").
+ *
+ * This is a plain key-value contract, keyed by `topic` (one intent per contest per wallet).
+ * It is internal: the library picks the backend by environment — IndexedDB in the browser,
+ * a SQLite file under the constructor's `dataPath` on Node — with no host-facing store seam.
+ * Declared as its own interface (like `BundleStore` in crdt/types.ts) so the voter can be
+ * tested against an in-memory store with no I/O.
+ */
+/** One contest's re-signable (or, when empty, re-announceable) choice for this wallet. */
+export interface VoteIntent {
+    /** The gossipsub topic this intent votes in = "bitsocial-votes/" + CID(dag-cbor(criteria)). */
+    topic: string;
+    /** The voting wallet address (recovered from the bundle signature). One intent per topic per address. */
+    address: string;
+    /**
+     * The communities this wallet chose. A non-empty intent is an active vote the scheduler re-signs
+     * (fresh `blockNumber`) each cadence to keep alive. An **empty array is a withdrawal
+     * tombstone**: the empty bundle supersedes the prior vote under LWW, and the scheduler
+     * re-announces its existing CID (never re-signing it) each cadence until it expires, then
+     * deletes the intent — the bundle decays on its own via expiry + prune. See DESIGN.md
+     * "Cancelling a vote".
+     */
+    votes: Vote[];
+    /** The bucket of the last successful republish, so the scheduler knows when the next is due. */
+    lastBucket: number;
+}
+/**
+ * Where the voter keeps its own vote intents. Only ever holds *this* voter's choices, not
+ * the CRDT of everyone's bundles. `list` feeds the republish loop on `start()`; `put` is
+ * written on every cast and every successful republish; `delete` drops an intent that has
+ * expired or been explicitly cancelled. `destroy` releases backend handles (close the DB
+ * or file) and is called by `PubsubVoter.destroy()`.
+ */
+export interface VoteStore {
+    /** Every intent to keep alive. Called once on `start()` to seed the republish scheduler. */
+    list(): Promise<VoteIntent[]>;
+    /** The intent for one contest, or `undefined` if this wallet has not voted there. */
+    get(topic: string): Promise<VoteIntent | undefined>;
+    /** Insert or replace one contest's intent (last write wins, mirroring the CRDT). */
+    put(intent: VoteIntent): Promise<void>;
+    /** Drop one contest's intent (expiry or explicit cancel). Idempotent. */
+    delete(topic: string): Promise<void>;
+    /** Release backend handles. Optional: the in-memory store has nothing to release. */
+    destroy?(): Promise<void>;
+}

package/dist/store/types.js

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

package/dist/tally/tally.d.ts

@@ -0,0 +1,44 @@
+import type { Criteria } from "../schema/criteria.js";
+import type { VotesBundle } from "../schema/votes.js";
+import type { RuleRegistry } from "../rules/types.js";
+import type { ChainClient, BucketMath } from "../chain/types.js";
+import type { BundleChecks } from "../verify/types.js";
+import type { Tally } from "./types.js";
+/**
+ * Deterministic per-contest aggregation over the CRDT's current bundles. Every aggregated
+ * bundle passed the synchronous offline checks (signature, constraints) at admission; each
+ * entry's {@link BundleChecks} says where its two deferred NETWORK checks stand (the on-chain
+ * gate read and name resolution — run inline by the forward-gate for live gossip, in the
+ * background chain verifier for cold-join admits). The tally never re-does verification: it
+ * sums *weight magnitude* per community, folds each entry's check state into the row's
+ * `chainVerified` / `nameResolved` flags, and orders the rows. In v1 the weight rule is
+ * `constant`, so this does ZERO chain reads (see DESIGN.md "Tally"). The reserved
+ * balance-derived weight path (`erc20-balance`) is where the lazy ceiling/floor early-stop
+ * would live; v1 has a trivial `1` ceiling per vote, so the common case simply sums.
+ *
+ * Rows are keyed by `community.publicKey`, so votes carrying different names for the same key
+ * fold into one row. Ties are broken by the rolling seed `sha256(bucketBlockHash ‖ publicKey)`
+ * — ungrindable because a future block hash cannot be predicted — and the one block-hash read
+ * happens only when an actual tie must be broken.
+ */
+export interface TallyDeps {
+    criteria: Criteria;
+    registry: RuleRegistry;
+    chainFor: (ticker: string) => ChainClient;
+    bucketMath: BucketMath;
+    /**
+     * The CRDT's current bundles (one per wallet, LWW-resolved; empty-votes bundles are
+     * withdrawals), each with its deferred-check state (see verify/types.ts `BundleChecks`).
+     */
+    current: () => Array<{
+        bundle: VotesBundle;
+        checks: BundleChecks;
+    }>;
+    /**
+     * Hash of the current bucket boundary block on the criteria's chain, for the rolling tie
+     * seed. Invoked at most once per `compute`, and only when a tie must actually be broken —
+     * so a tie-free tally still does no extra read.
+     */
+    bucketBlockHash: () => Promise<Uint8Array>;
+}
+export declare function makeTally(deps: TallyDeps): Tally;

package/dist/tally/tally.js

@@ -0,0 +1,89 @@
+import { base58btc } from "multiformats/bases/base58";
+import { sha256 } from "multiformats/hashes/sha2";
+import { tickerForRef } from "../chain/ticker.js";
+import { UnknownRuleError } from "../errors.js";
+/** Byte-lexicographic compare of two byte arrays (returns <0, 0, >0). */
+function compareBytes(x, y) {
+    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;
+}
+export function makeTally(deps) {
+    const { criteria, registry, chainFor, bucketMath, current, bucketBlockHash } = deps;
+    // Resolve the weight rule, its options, and its chain once (see verify/bundle.ts).
+    const weight = registry[criteria.weight.type];
+    if (!weight)
+        throw new UnknownRuleError("weight", criteria.weight.type);
+    const weightOptions = weight.optionsSchema.parse(criteria.weight);
+    const weightChain = chainFor(tickerForRef(criteria, criteria.weight, weightOptions));
+    const weightFor = async (wallet, blockNumber) => {
+        const sampleBlock = bucketMath.sampleBlockForBucket(bucketMath.bucketForBlock(blockNumber));
+        const { score } = await weight.evaluate({
+            options: weightOptions,
+            walletAddress: wallet,
+            ctx: { chain: weightChain, blockNumber: sampleBlock }
+        });
+        return score;
+    };
+    /** The rolling tie seed for a community: sha256(bucketBlockHash ‖ publicKey bytes). */
+    const tieSeed = async (blockHash, publicKey) => {
+        const pkBytes = base58btc.decode(`z${publicKey}`);
+        const buf = new Uint8Array(blockHash.length + pkBytes.length);
+        buf.set(blockHash, 0);
+        buf.set(pkBytes, blockHash.length);
+        return (await sha256.digest(buf)).digest;
+    };
+    return {
+        async compute() {
+            // Aggregate weight per community.publicKey, folding each contribution's deferred-check
+            // state into the row: `chainVerified` only once EVERY contributing bundle's gate read
+            // confirmed, and the shown name prefers (and reports) a registry-resolved one.
+            const rows = new Map();
+            for (const { bundle, checks } of current()) {
+                if (bundle.votes.length === 0)
+                    continue; // withdrawal — expresses no vote
+                const w = await weightFor(bundle.address, bundle.blockNumber);
+                for (const v of bundle.votes) {
+                    const pk = v.community.publicKey;
+                    const row = rows.get(pk) ?? { weight: 0n, chainVerified: true };
+                    row.weight += w;
+                    row.chainVerified &&= checks.chainVerified;
+                    // Prefer a resolved name over a still-pending one; never downgrade to pending.
+                    if (v.community.name && row.nameResolved !== true) {
+                        row.name = v.community.name;
+                        row.nameResolved = checks.nameResolved === true;
+                    }
+                    rows.set(pk, row);
+                }
+            }
+            const list = [...rows.entries()].map(([publicKey, row]) => ({
+                community: row.name ? { name: row.name, publicKey } : { publicKey },
+                weight: row.weight,
+                chainVerified: row.chainVerified,
+                ...(row.name ? { nameResolved: row.nameResolved } : {})
+            }));
+            // Order by weight desc. Only if two rows tie on weight do we read the boundary
+            // block hash and order those by the ungrindable rolling seed.
+            const hasTie = new Set(list.map((r) => r.weight)).size !== list.length;
+            if (!hasTie) {
+                list.sort((a, b) => (a.weight < b.weight ? 1 : a.weight > b.weight ? -1 : 0));
+                return { contestId: criteria.contestId, ranking: list };
+            }
+            const blockHash = await bucketBlockHash();
+            const seeds = new Map();
+            for (const r of list)
+                seeds.set(r.community.publicKey, await tieSeed(blockHash, r.community.publicKey));
+            list.sort((a, b) => {
+                if (a.weight !== b.weight)
+                    return a.weight < b.weight ? 1 : -1;
+                return compareBytes(seeds.get(a.community.publicKey), seeds.get(b.community.publicKey));
+            });
+            return { contestId: criteria.contestId, ranking: list };
+        }
+    };
+}

package/dist/tally/types.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Tally interfaces.
+ *
+ * One topic decides one contest, so the tally aggregates the current bundles into a single
+ * contest ranking. The synchronous checks (signature, constraints) are admission
+ * preconditions — every aggregated bundle has passed them — so the per-row flags below track
+ * only the two deferred NETWORK checks, one field per verification operation (mirroring
+ * pkc-js's `nameResolved`): the on-chain gate read and community-name resolution. A cold join
+ * admits a checkpoint's bundles provisionally and renders immediately; the background chain
+ * verifier then confirms (flipping the flags, re-emitting `update`) or evicts. See DESIGN.md
+ * "Background chain verification" and "Tally".
+ */
+/** One community's standing within a contest. */
+export interface CommunityTally {
+    /**
+     * The community this row aggregates. Rows are keyed by `community.publicKey`; `name` is the
+     * community's resolvable domain carried through from the votes. It never affects which
+     * votes fold into this row, and `nameResolved` below says whether it has been checked
+     * against the registry yet. See DESIGN.md "Votes wire" and "Tally".
+     */
+    community: {
+        name?: string;
+        publicKey: string;
+    };
+    /** Summed weight of upvotes counted so far, in rule score units (`bigint`). */
+    weight: bigint;
+    /**
+     * True once every bundle contributing to this row has had its gate `rule` confirmed `> 0n`
+     * by an on-chain read at its bucket block. `false` means at least one contribution is still
+     * awaiting its background gate read — never that one failed (a failed gate evicts the
+     * bundle and recounts the row).
+     */
+    chainVerified: boolean;
+    /**
+     * Present only when the row carries a `name`: true once the shown name resolved to this
+     * row's `publicKey` through the registry (pkc-js's `nameResolved` shape). `false` while the
+     * carried name is still awaiting background resolution — a name that resolves to a
+     * DIFFERENT key evicts its bundle instead, so a mismatched name is never shown.
+     */
+    nameResolved?: boolean;
+}
+/** A contest's ranking, highest weight first. Ordering is deterministic. */
+export interface ContestTally {
+    /** The `contestId` of the criteria this ranking is for. */
+    contestId: string;
+    ranking: CommunityTally[];
+}
+/** Computes the contest ranking from the CRDT's current bundles. */
+export interface Tally {
+    compute(): Promise<ContestTally>;
+}

package/dist/tally/types.js

@@ -0,0 +1,13 @@
+/**
+ * Tally interfaces.
+ *
+ * One topic decides one contest, so the tally aggregates the current bundles into a single
+ * contest ranking. The synchronous checks (signature, constraints) are admission
+ * preconditions — every aggregated bundle has passed them — so the per-row flags below track
+ * only the two deferred NETWORK checks, one field per verification operation (mirroring
+ * pkc-js's `nameResolved`): the on-chain gate read and community-name resolution. A cold join
+ * admits a checkpoint's bundles provisionally and renders immediately; the background chain
+ * verifier then confirms (flipping the flags, re-emitting `update`) or evicts. See DESIGN.md
+ * "Background chain verification" and "Tally".
+ */
+export {};

package/dist/topic.d.ts

@@ -0,0 +1,20 @@
+import { CID } from "multiformats/cid";
+import type { Criteria } from "./schema/criteria.js";
+/**
+ * Topic derivation.
+ *
+ *   topic = "bitsocial-votes/" + CID(dag-cbor(criteria))
+ *
+ * The topic is the content address of the criteria document, so subscribing to a
+ * topic is itself proof that two peers ran byte-identical rules. A different value
+ * (different contest, gate, expiry, ...) yields different bytes, a different CID, and
+ * therefore a different topic — which is how criteria upgrades fork cleanly. Reordering
+ * keys does NOT fork the topic, because dag-cbor sorts them. See DESIGN.md
+ * "Criteria document". Pure and offline: no libp2p/helia, no network.
+ */
+/** Prefix that namespaces every vote topic. */
+export declare const TOPIC_PREFIX = "bitsocial-votes/";
+/** The CIDv1 (dag-cbor, sha2-256) of a criteria document's canonical encoding. */
+export declare function criteriaCid(criteria: Criteria): Promise<CID>;
+/** The gossipsub topic a criteria document maps to. */
+export declare function topicFor(criteria: Criteria): Promise<string>;

package/dist/topic.js

@@ -0,0 +1,28 @@
+import { CID } from "multiformats/cid";
+import { sha256 } from "multiformats/hashes/sha2";
+import { encodeCriteria, dagCborCode } from "./encoding/canonical.js";
+/**
+ * Topic derivation.
+ *
+ *   topic = "bitsocial-votes/" + CID(dag-cbor(criteria))
+ *
+ * The topic is the content address of the criteria document, so subscribing to a
+ * topic is itself proof that two peers ran byte-identical rules. A different value
+ * (different contest, gate, expiry, ...) yields different bytes, a different CID, and
+ * therefore a different topic — which is how criteria upgrades fork cleanly. Reordering
+ * keys does NOT fork the topic, because dag-cbor sorts them. See DESIGN.md
+ * "Criteria document". Pure and offline: no libp2p/helia, no network.
+ */
+/** Prefix that namespaces every vote topic. */
+export const TOPIC_PREFIX = "bitsocial-votes/";
+/** The CIDv1 (dag-cbor, sha2-256) of a criteria document's canonical encoding. */
+export async function criteriaCid(criteria) {
+    const bytes = encodeCriteria(criteria);
+    const digest = await sha256.digest(bytes);
+    return CID.createV1(dagCborCode, digest);
+}
+/** The gossipsub topic a criteria document maps to. */
+export async function topicFor(criteria) {
+    const cid = await criteriaCid(criteria);
+    return TOPIC_PREFIX + cid.toString();
+}

package/dist/transport/accepted-dedup.d.ts

@@ -0,0 +1,30 @@
+import type { BucketMath } from "../chain/types.js";
+import type { VotesBundle } from "../schema/votes.js";
+/**
+ * A bounded set of already-accepted votes, keyed by `(wallet, bucket, votes)`, used by the forward
+ * gate to drop a **re-sign flood**: an eligible wallet re-signing the same choice with fresh
+ * signature nonces (or a bumped `blockNumber` inside the same bucket) mints a new bundle CID each
+ * time, so the per-CID verdict cache never hits. Each such bundle is inert under LWW (same wallet)
+ * and shares the same expiry bucket and the same tally choice as the one already accepted, so
+ * re-forwarding it is pure amplification (see DESIGN.md "Transport", resource-exhaustion residual).
+ *
+ * Keyed on the *bucket* (not the raw `blockNumber`) and the canonical `votes` bytes, so a genuine
+ * heartbeat re-sign — which lands in a *later* bucket on the liveness cadence — is NOT a duplicate,
+ * and a genuine vote *change* (different `votes`) is NOT a duplicate. Only a same-bucket, same-choice
+ * re-sign matches.
+ *
+ * Safety: `isResignDuplicate` may be consulted on the *untrusted* claimed `bundle.address` (before
+ * the signature is verified), because a hit only ever yields "drop, do not forward" — never accept
+ * or store. A hit means an equivalent vote was already verified and forwarded, so dropping an
+ * attacker's matching-key garbage suppresses nothing an honest peer lacks; a non-hit falls through
+ * to the full verifier, where a bad signature is `reject`ed. `record` is therefore only ever called
+ * for a bundle that has passed the full gate.
+ */
+export interface AcceptedDedup {
+    /** Is `bundle` a same-bucket, same-choice re-sign of a vote already accepted from its wallet? */
+    isResignDuplicate(bundle: VotesBundle): boolean;
+    /** Record a fully-verified, accepted bundle so later re-signs of it are recognised as duplicates. */
+    record(bundle: VotesBundle): void;
+}
+/** An in-memory {@link AcceptedDedup} bounded to `maxEntries` with FIFO eviction. */
+export declare function makeAcceptedDedup(bucketMath: BucketMath, maxEntries?: number): AcceptedDedup;

package/dist/transport/accepted-dedup.js

@@ -0,0 +1,34 @@
+import { encodeCanonical } from "../encoding/canonical.js";
+function toHex(bytes) {
+    let s = "";
+    for (const b of bytes)
+        s += b.toString(16).padStart(2, "0");
+    return s;
+}
+/** An in-memory {@link AcceptedDedup} bounded to `maxEntries` with FIFO eviction. */
+export function makeAcceptedDedup(bucketMath, maxEntries = 4096) {
+    const keys = new Set();
+    const order = [];
+    const keyFor = (bundle) => {
+        const bucket = bucketMath.bucketForBlock(bundle.blockNumber);
+        // `votes` is canonically dag-cbor encoded (sorted keys), so the same choice always yields
+        // the same key regardless of authoring order. Votes are tiny in v1, so raw hex is a cheap,
+        // sync key — no hashing needed.
+        return `${bundle.address.toLowerCase()}:${bucket}:${toHex(encodeCanonical(bundle.votes))}`;
+    };
+    return {
+        isResignDuplicate: (bundle) => keys.has(keyFor(bundle)),
+        record: (bundle) => {
+            const k = keyFor(bundle);
+            if (keys.has(k))
+                return;
+            keys.add(k);
+            order.push(k);
+            if (order.length > maxEntries) {
+                const evicted = order.shift();
+                if (evicted !== undefined)
+                    keys.delete(evicted);
+            }
+        }
+    };
+}

package/dist/transport/announce/browser.d.ts

@@ -0,0 +1,9 @@
+import type { Announcer, AnnouncerOptions } from "./types.js";
+/**
+ * The browser announcer: inert by design. A browser peer is not dialable — no listener, no
+ * public address — so a provider record naming it would only misdirect cold joiners; it must
+ * never announce, whatever `httpRouterUrls` says. The package.json `browser` field remaps
+ * `./dist/transport/announce/node.js` to this module (the same swap as `src/storage/`), so the
+ * voter's wiring is identical on both platforms and only the effect differs.
+ */
+export declare function makeAnnouncer(_options: AnnouncerOptions): Announcer;

package/dist/transport/announce/browser.js

@@ -0,0 +1,14 @@
+/**
+ * The browser announcer: inert by design. A browser peer is not dialable — no listener, no
+ * public address — so a provider record naming it would only misdirect cold joiners; it must
+ * never announce, whatever `httpRouterUrls` says. The package.json `browser` field remaps
+ * `./dist/transport/announce/node.js` to this module (the same swap as `src/storage/`), so the
+ * voter's wiring is identical on both platforms and only the effect differs.
+ */
+export function makeAnnouncer(_options) {
+    return {
+        start() { },
+        stop() { },
+        notifyChange() { }
+    };
+}

package/dist/transport/announce/node.d.ts

@@ -0,0 +1,38 @@
+import type { Announcer, AnnouncerOptions } from "./types.js";
+/**
+ * The Node provider-record announcer (see types.ts for the seam rationale, and DESIGN.md
+ * "Deferred pkc-js work", provider-record announces): one unsigned `PUT /routing/v1/providers`
+ * per configured router per tick, kubo's body shape —
+ * `{ Providers: [{ Schema: "peer", Payload: { ID, Addrs, Keys } }] }` — with `Keys` batched
+ * across ALL joined contests. Unsigned is correct against the production router
+ * (pkc-http-router reads only `Payload.{ID, Addrs, Keys, AdvisoryTTL}`; no signature field
+ * exists), and its anti-spoofing keeps `/ip4`/`/ip6` addrs only when the IP matches the PUT's
+ * source IP — which a seeder announcing its own addresses passes naturally.
+ *
+ * Ticks: the debounced change trigger ({@link Announcer.notifyChange} — contest joins, checkpoint
+ * root changes, `self:peer:update` address changes) plus an hourly re-announce (pkc-js's
+ * `providePubsubTopicRoutingCidsIfNeeded` cadence; the production router's record TTL is 24h, so
+ * hourly has a 24× margin). Best-effort per router: a failing or slow router is reported through
+ * `onError` and never throws into the voter; there is no retry — the next tick covers it.
+ */
+/** Hourly re-announce — pkc-js's `providePubsubTopicRoutingCidsIfNeeded` cadence, ≪ the 24h TTL. */
+export declare const ANNOUNCE_INTERVAL_MS = 3600000;
+/**
+ * Change-coalescing window: a gossip burst re-dirties the checkpoint per accepted bundle and a
+ * directory join fires once per contest, so the first trigger arms one timer and the burst rides
+ * it — bounding announces to one per window while a hot topic churns.
+ */
+export declare const ANNOUNCE_DEBOUNCE_MS = 10000;
+/** Per-router PUT deadline — same order as the cold-join router lookup deadline. */
+export declare const ANNOUNCE_ROUTER_TIMEOUT_MS = 10000;
+/**
+ * Filter a node's multiaddrs down to what belongs in a public provider record: public `/ip4` /
+ * `/ip6` addrs and DNS addrs (`/dns4`/`/dns6`/`/dnsaddr` — the AutoTLS `<peerId>.libp2p.direct`
+ * WSS addrs travel this way, and the production router passes DNS through unvalidated). Private,
+ * loopback, link-local, CGNAT, and unspecified IPs are dropped CLIENT-side rather than trusting
+ * the router to drop them; a `p2p-circuit` addr is judged by its relay's leading component like
+ * any other. Exported for the announcer's unit tests.
+ */
+export declare function announceableAddrs(addrs: readonly string[]): string[];
+/** Build the Node announcer. The browser build never sees this file (package.json `browser` remap). */
+export declare function makeAnnouncer(options: AnnouncerOptions): Announcer;

package/dist/transport/announce/node.js

@@ -0,0 +1,162 @@
+/**
+ * The Node provider-record announcer (see types.ts for the seam rationale, and DESIGN.md
+ * "Deferred pkc-js work", provider-record announces): one unsigned `PUT /routing/v1/providers`
+ * per configured router per tick, kubo's body shape —
+ * `{ Providers: [{ Schema: "peer", Payload: { ID, Addrs, Keys } }] }` — with `Keys` batched
+ * across ALL joined contests. Unsigned is correct against the production router
+ * (pkc-http-router reads only `Payload.{ID, Addrs, Keys, AdvisoryTTL}`; no signature field
+ * exists), and its anti-spoofing keeps `/ip4`/`/ip6` addrs only when the IP matches the PUT's
+ * source IP — which a seeder announcing its own addresses passes naturally.
+ *
+ * Ticks: the debounced change trigger ({@link Announcer.notifyChange} — contest joins, checkpoint
+ * root changes, `self:peer:update` address changes) plus an hourly re-announce (pkc-js's
+ * `providePubsubTopicRoutingCidsIfNeeded` cadence; the production router's record TTL is 24h, so
+ * hourly has a 24× margin). Best-effort per router: a failing or slow router is reported through
+ * `onError` and never throws into the voter; there is no retry — the next tick covers it.
+ */
+/** Hourly re-announce — pkc-js's `providePubsubTopicRoutingCidsIfNeeded` cadence, ≪ the 24h TTL. */
+export const ANNOUNCE_INTERVAL_MS = 3_600_000;
+/**
+ * Change-coalescing window: a gossip burst re-dirties the checkpoint per accepted bundle and a
+ * directory join fires once per contest, so the first trigger arms one timer and the burst rides
+ * it — bounding announces to one per window while a hot topic churns.
+ */
+export const ANNOUNCE_DEBOUNCE_MS = 10_000;
+/** Per-router PUT deadline — same order as the cold-join router lookup deadline. */
+export const ANNOUNCE_ROUTER_TIMEOUT_MS = 10_000;
+/** RFC1918/loopback/link-local/CGNAT/unspecified IPv4 — never announceable. */
+function isPrivateIp4(ip) {
+    const parts = ip.split(".").map(Number);
+    if (parts.length !== 4 || parts.some((p) => !Number.isInteger(p) || p < 0 || p > 255))
+        return true;
+    const [a, b] = parts;
+    return (a === 0 || // unspecified / "this network"
+        a === 10 ||
+        a === 127 || // loopback
+        (a === 100 && b >= 64 && b < 128) || // CGNAT 100.64/10
+        (a === 169 && b === 254) || // link-local
+        (a === 172 && b >= 16 && b < 32) ||
+        (a === 192 && b === 168));
+}
+/** Loopback/link-local/ULA/unspecified IPv6 — never announceable. */
+function isPrivateIp6(ip) {
+    const lower = ip.toLowerCase();
+    if (lower === "::" || lower === "::1")
+        return true;
+    // fe80::/10 link-local (fe8x..febx), fc00::/7 unique-local (fcxx/fdxx).
+    return /^fe[89ab]/.test(lower) || /^f[cd]/.test(lower);
+}
+/**
+ * Filter a node's multiaddrs down to what belongs in a public provider record: public `/ip4` /
+ * `/ip6` addrs and DNS addrs (`/dns4`/`/dns6`/`/dnsaddr` — the AutoTLS `<peerId>.libp2p.direct`
+ * WSS addrs travel this way, and the production router passes DNS through unvalidated). Private,
+ * loopback, link-local, CGNAT, and unspecified IPs are dropped CLIENT-side rather than trusting
+ * the router to drop them; a `p2p-circuit` addr is judged by its relay's leading component like
+ * any other. Exported for the announcer's unit tests.
+ */
+export function announceableAddrs(addrs) {
+    return addrs.filter((addr) => {
+        const [, proto, value] = addr.split("/");
+        if (proto === undefined || value === undefined)
+            return false;
+        if (proto === "dns4" || proto === "dns6" || proto === "dnsaddr" || proto === "dns")
+            return true;
+        if (proto === "ip4")
+            return !isPrivateIp4(value);
+        if (proto === "ip6")
+            return !isPrivateIp6(value);
+        return false;
+    });
+}
+/** One unsigned kubo-shape provider PUT; throws on timeout or a non-2xx answer. */
+async function putProviders(baseUrl, body, timeoutMs) {
+    const endpoint = `${baseUrl.replace(/\/+$/, "")}/routing/v1/providers`;
+    const res = await fetch(endpoint, {
+        method: "PUT",
+        headers: { "content-type": "application/json" },
+        body,
+        signal: AbortSignal.timeout(timeoutMs)
+    });
+    if (!res.ok)
+        throw new Error(`router ${endpoint} answered ${res.status}`);
+    // Drain so the connection can be reused; the ProvideResults echo carries nothing we act on.
+    await res.arrayBuffer().catch(() => { });
+}
+/** Build the Node announcer. The browser build never sees this file (package.json `browser` remap). */
+export function makeAnnouncer(options) {
+    const intervalMs = options.intervalMs ?? ANNOUNCE_INTERVAL_MS;
+    const debounceMs = options.debounceMs ?? ANNOUNCE_DEBOUNCE_MS;
+    const timeoutMs = options.timeoutMs ?? ANNOUNCE_ROUTER_TIMEOUT_MS;
+    let started = false;
+    let intervalTimer;
+    let debounceTimer;
+    /** True while one announce runs; a trigger landing mid-run re-runs once after (never overlaps). */
+    let running = false;
+    let rerun = false;
+    const announceNow = async () => {
+        if (running) {
+            rerun = true;
+            return;
+        }
+        running = true;
+        try {
+            do {
+                rerun = false;
+                const keys = await options.keys();
+                const addrs = announceableAddrs(options.libp2p.getMultiaddrs().map((a) => a.toString()));
+                // Nothing joined, or no publicly dialable address: announce nothing. The production
+                // router drops a provider whose addrs come up empty anyway — an undialable node
+                // (plain client, NATed box with no configured announce addrs) must not announce.
+                if (keys.length === 0 || addrs.length === 0)
+                    continue;
+                const body = JSON.stringify({
+                    Providers: [{ Schema: "peer", Payload: { ID: options.libp2p.peerId.toString(), Addrs: addrs, Keys: keys } }]
+                });
+                await Promise.all(options.routerUrls.map(async (url) => {
+                    try {
+                        await putProviders(url, body, timeoutMs);
+                    }
+                    catch (error) {
+                        options.onError?.(url, error);
+                    }
+                }));
+            } while (rerun);
+        }
+        finally {
+            running = false;
+        }
+    };
+    const notifyChange = () => {
+        if (!started || debounceTimer !== undefined)
+            return;
+        debounceTimer = setTimeout(() => {
+            debounceTimer = undefined;
+            void announceNow();
+        }, debounceMs);
+        debounceTimer.unref?.();
+    };
+    const onAddressChange = () => notifyChange();
+    return {
+        start() {
+            if (started)
+                return;
+            started = true;
+            options.libp2p.addEventListener("self:peer:update", onAddressChange);
+            intervalTimer = setInterval(() => void announceNow(), intervalMs);
+            intervalTimer.unref?.();
+        },
+        stop() {
+            if (!started)
+                return;
+            started = false;
+            options.libp2p.removeEventListener("self:peer:update", onAddressChange);
+            if (intervalTimer !== undefined)
+                clearInterval(intervalTimer);
+            intervalTimer = undefined;
+            if (debounceTimer !== undefined)
+                clearTimeout(debounceTimer);
+            debounceTimer = undefined;
+        },
+        notifyChange
+    };
+}