@bitsocial/pubsub-votes 0.0.2

package/dist/schema/criteria.d.ts

@@ -0,0 +1,78 @@
+import { z } from "zod";
+/**
+ * The criteria document.
+ *
+ * Shipped static in the client bundle and used to derive the pubsub topic:
+ *   topic = "bitsocial-votes/" + CID(dag-cbor(criteria))
+ *
+ * One criteria document describes exactly one contest (one directory slot), so there
+ * is one topic per contest. The differing `contestId` value makes each contest's bytes
+ * distinct, which forks the topic automatically. A client joins only the contests it
+ * cares about, which is what keeps cold start cheap. See DESIGN.md "Criteria document".
+ *
+ * Because the topic is the CID of the canonical encoding of this object, two peers
+ * on the same topic provably ran identical rules. Therefore this object MUST be
+ * canonically encodable (no `undefined`, deterministic key order under dag-cbor);
+ * a non-canonical change silently changes the topic.
+ */
+/** Inclusive numeric bounds for a single `vote` value. v1 is { min: 1, max: 1 }. */
+export declare const VoteRangeSchema: z.ZodObject<{
+    min: z.ZodNumber;
+    max: z.ZodNumber;
+}, z.core.$strip>;
+/**
+ * A reference to a rule by `type`, plus rule-specific options.
+ * Kept loose on purpose: each rule owns and validates its own option schema
+ * (see rules/types.ts), so custom rules can be referenced without
+ * changing CriteriaSchema. This mirrors pkc-js challenge settings
+ * ({ name, options }) where the named challenge validates its own options.
+ */
+export declare const RuleRefSchema: z.ZodObject<{
+    type: z.ZodString;
+}, z.core.$loose>;
+/** RPC configuration for one chain ticker. Part of the dependency manifest. */
+export declare const ChainConfigSchema: z.ZodObject<{
+    chainId: z.ZodNumber;
+    rpcUrls: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * The dependency manifest. A client reads this on join and checks that it
+ * implements every named rule; if not, it is too old and must recuse
+ * itself rather than miscount. This is how criteria upgrades fork cleanly.
+ */
+export declare const RequiresSchema: z.ZodObject<{
+    rules: z.ZodArray<z.ZodString>;
+    chains: z.ZodRecord<z.ZodString, z.ZodObject<{
+        chainId: z.ZodNumber;
+        rpcUrls: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const CriteriaSchema: z.ZodObject<{
+    name: z.ZodString;
+    contestId: z.ZodString;
+    voteSchema: z.ZodObject<{
+        min: z.ZodNumber;
+        max: z.ZodNumber;
+    }, z.core.$strip>;
+    maxVotesPerAddress: z.ZodNumber;
+    blocksPerBucket: z.ZodNumber;
+    voteExpiryBuckets: z.ZodNumber;
+    rule: z.ZodObject<{
+        type: z.ZodString;
+    }, z.core.$loose>;
+    weight: z.ZodObject<{
+        type: z.ZodString;
+    }, z.core.$loose>;
+    requires: z.ZodObject<{
+        rules: z.ZodArray<z.ZodString>;
+        chains: z.ZodRecord<z.ZodString, z.ZodObject<{
+            chainId: z.ZodNumber;
+            rpcUrls: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+}, z.core.$strict>;
+export type VoteRange = z.infer<typeof VoteRangeSchema>;
+export type RuleRef = z.infer<typeof RuleRefSchema>;
+export type ChainConfig = z.infer<typeof ChainConfigSchema>;
+export type Requires = z.infer<typeof RequiresSchema>;
+export type Criteria = z.infer<typeof CriteriaSchema>;

package/dist/schema/criteria.js

@@ -0,0 +1,76 @@
+import { z } from "zod";
+import { ChainTickerSchema } from "./common.js";
+/**
+ * The criteria document.
+ *
+ * Shipped static in the client bundle and used to derive the pubsub topic:
+ *   topic = "bitsocial-votes/" + CID(dag-cbor(criteria))
+ *
+ * One criteria document describes exactly one contest (one directory slot), so there
+ * is one topic per contest. The differing `contestId` value makes each contest's bytes
+ * distinct, which forks the topic automatically. A client joins only the contests it
+ * cares about, which is what keeps cold start cheap. See DESIGN.md "Criteria document".
+ *
+ * Because the topic is the CID of the canonical encoding of this object, two peers
+ * on the same topic provably ran identical rules. Therefore this object MUST be
+ * canonically encodable (no `undefined`, deterministic key order under dag-cbor);
+ * a non-canonical change silently changes the topic.
+ */
+/** Inclusive numeric bounds for a single `vote` value. v1 is { min: 1, max: 1 }. */
+export const VoteRangeSchema = z.object({
+    min: z.number().int(),
+    max: z.number().int()
+});
+/**
+ * A reference to a rule by `type`, plus rule-specific options.
+ * Kept loose on purpose: each rule owns and validates its own option schema
+ * (see rules/types.ts), so custom rules can be referenced without
+ * changing CriteriaSchema. This mirrors pkc-js challenge settings
+ * ({ name, options }) where the named challenge validates its own options.
+ */
+export const RuleRefSchema = z.looseObject({
+    type: z.string().min(1)
+});
+/** RPC configuration for one chain ticker. Part of the dependency manifest. */
+export const ChainConfigSchema = z.object({
+    chainId: z.number().int().positive(),
+    rpcUrls: z.array(z.string().min(1)).nonempty()
+});
+/**
+ * The dependency manifest. A client reads this on join and checks that it
+ * implements every named rule; if not, it is too old and must recuse
+ * itself rather than miscount. This is how criteria upgrades fork cleanly.
+ */
+export const RequiresSchema = z.object({
+    rules: z.array(z.string().min(1)).nonempty(),
+    chains: z.record(ChainTickerSchema, ChainConfigSchema)
+});
+export const CriteriaSchema = z
+    .object({
+    /** Human-readable label, not consensus-critical beyond changing the CID. */
+    name: z.string().min(1),
+    /**
+     * The directory-slot code this topic decides. One contest per topic: a distinct
+     * `contestId` makes the document's bytes distinct, which forks the topic automatically.
+     */
+    contestId: z.string().min(1),
+    /** Allowed range for each `vote` value. v1: { min: 1, max: 1 }. */
+    voteSchema: VoteRangeSchema,
+    /**
+     * Max community selections per wallet in this contest (anti-spam). v1 = 1, the
+     * one-vote-per-topic rule: a wallet picks one community. An empty `votes` array is
+     * always allowed as withdrawal/abstention regardless of this cap.
+     */
+    maxVotesPerAddress: z.number().int().positive(),
+    /** Block bucket size; all verifiers price the same block per bucket. */
+    blocksPerBucket: z.number().int().positive(),
+    /** How many buckets a bundle stays valid after its blockNumber. */
+    voteExpiryBuckets: z.number().int().positive(),
+    /** Who may vote (gates a wallet in or out). */
+    rule: RuleRefSchema,
+    /** How much an eligible vote counts. */
+    weight: RuleRefSchema,
+    /** Dependency manifest + version negotiation. */
+    requires: RequiresSchema
+})
+    .strict();

package/dist/schema/directory.d.ts

@@ -0,0 +1,42 @@
+import { z } from "zod";
+import { type Criteria } from "./criteria.js";
+/**
+ * Directory authoring manifest → criteria documents.
+ *
+ * A directory (e.g. 5chan's 63 boards) is authored as ONE manifest of shared `defaults`
+ * plus one entry per slot, and each contest's standalone criteria document is derived by
+ * shallow merge: criteria = { ...defaults, ...entry }. The manifest itself is NOT a
+ * protocol object — it is never encoded or published, and `defaults` is flattened away at
+ * derivation. Only the derived documents matter: two clients must end up with
+ * byte-identical documents to share a topic (topic = CID(dag-cbor(criteria))), which is
+ * exactly why this derivation is library API rather than per-app code — two consumers
+ * (e.g. the 5chan web client and a standalone seeder) re-implementing the merge is a
+ * silent topic fork waiting to happen.
+ *
+ * The merge is shallow ON PURPOSE: an entry override replaces that whole top-level field
+ * (a `rule` override brings its own complete rule object), no deep merge. Editing
+ * `defaults` re-forks every inheriting contest in lockstep; editing one entry forks only
+ * that contest. See the authoring manifest example (5chan-directory-criteria.jsonc) and
+ * DESIGN.md "Criteria document".
+ *
+ * Manifest files are conventionally JSONC (commented for human readers); strip comments
+ * (e.g. with `strip-json-comments`) and JSON.parse before calling — this helper is pure
+ * and takes the parsed value.
+ */
+/**
+ * The manifest shape: `contests` is required, `defaults` optional, and everything else
+ * (name, description, ...) is ignored authoring metadata. Entries are kept loose here —
+ * each derived document is what gets validated, against the real CriteriaSchema.
+ */
+export declare const DirectoryManifestSchema: z.ZodObject<{
+    defaults: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    contests: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$loose>;
+export type DirectoryManifest = z.infer<typeof DirectoryManifestSchema>;
+/**
+ * Derive one complete, validated criteria document per manifest entry
+ * (`{ ...defaults, ...entry }`, shallow). Throws if the manifest is malformed, if any
+ * derived document fails CriteriaSchema, or if two entries claim the same `contestId`
+ * ({@link DuplicateContestIdError} — same slot decided by two topics is an authoring bug).
+ */
+export declare function deriveDirectoryCriteria(manifest: unknown): Criteria[];

package/dist/schema/directory.js

@@ -0,0 +1,52 @@
+import { z } from "zod";
+import { CriteriaSchema } from "./criteria.js";
+import { DuplicateContestIdError } from "../errors.js";
+/**
+ * Directory authoring manifest → criteria documents.
+ *
+ * A directory (e.g. 5chan's 63 boards) is authored as ONE manifest of shared `defaults`
+ * plus one entry per slot, and each contest's standalone criteria document is derived by
+ * shallow merge: criteria = { ...defaults, ...entry }. The manifest itself is NOT a
+ * protocol object — it is never encoded or published, and `defaults` is flattened away at
+ * derivation. Only the derived documents matter: two clients must end up with
+ * byte-identical documents to share a topic (topic = CID(dag-cbor(criteria))), which is
+ * exactly why this derivation is library API rather than per-app code — two consumers
+ * (e.g. the 5chan web client and a standalone seeder) re-implementing the merge is a
+ * silent topic fork waiting to happen.
+ *
+ * The merge is shallow ON PURPOSE: an entry override replaces that whole top-level field
+ * (a `rule` override brings its own complete rule object), no deep merge. Editing
+ * `defaults` re-forks every inheriting contest in lockstep; editing one entry forks only
+ * that contest. See the authoring manifest example (5chan-directory-criteria.jsonc) and
+ * DESIGN.md "Criteria document".
+ *
+ * Manifest files are conventionally JSONC (commented for human readers); strip comments
+ * (e.g. with `strip-json-comments`) and JSON.parse before calling — this helper is pure
+ * and takes the parsed value.
+ */
+/**
+ * The manifest shape: `contests` is required, `defaults` optional, and everything else
+ * (name, description, ...) is ignored authoring metadata. Entries are kept loose here —
+ * each derived document is what gets validated, against the real CriteriaSchema.
+ */
+export const DirectoryManifestSchema = z.looseObject({
+    defaults: z.record(z.string(), z.unknown()).optional(),
+    contests: z.array(z.record(z.string(), z.unknown())).nonempty()
+});
+/**
+ * Derive one complete, validated criteria document per manifest entry
+ * (`{ ...defaults, ...entry }`, shallow). Throws if the manifest is malformed, if any
+ * derived document fails CriteriaSchema, or if two entries claim the same `contestId`
+ * ({@link DuplicateContestIdError} — same slot decided by two topics is an authoring bug).
+ */
+export function deriveDirectoryCriteria(manifest) {
+    const { defaults = {}, contests } = DirectoryManifestSchema.parse(manifest);
+    const seen = new Set();
+    return contests.map((entry) => {
+        const criteria = CriteriaSchema.parse({ ...defaults, ...entry });
+        if (seen.has(criteria.contestId))
+            throw new DuplicateContestIdError(criteria.contestId);
+        seen.add(criteria.contestId);
+        return criteria;
+    });
+}

package/dist/schema/votes.d.ts

@@ -0,0 +1,55 @@
+import { z } from "zod";
+/**
+ * The community being voted for: identified by its `publicKey`, with an
+ * optional resolvable domain `name` (e.g. "memes.bso"). Community identity — the key the
+ * tally aggregates on — is `publicKey` alone, but a carried `name` is a *verified
+ * claim*, not a free label: names are unique (the naming registry maps one name to one
+ * community), and at tally time a bundle whose `name` does not resolve to the claimed
+ * `publicKey` is dropped. A vote that omits `name` still folds into the same
+ * `publicKey` row. See DESIGN.md "Votes wire" and "Tally".
+ */
+export declare const CommunitySchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    publicKey: z.ZodString;
+}, z.core.$strip>;
+/**
+ * A single vote inside a bundle. The contest is implied by the topic (one contest
+ * per topic), so it is not repeated on the wire.
+ * - `community` is the community being voted for (`{ name?, publicKey }`).
+ * - `vote` is numeric; its allowed range comes from `criteria.voteSchema`
+ *   (v1 is upvote-only, so exactly 1). Range is enforced at verify time, not here,
+ *   because the bounds live in the criteria, not in the wire type.
+ */
+export declare const VoteSchema: z.ZodObject<{
+    community: z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        publicKey: z.ZodString;
+    }, z.core.$strip>;
+    vote: z.ZodNumber;
+}, z.core.$strip>;
+/**
+ * The full wire node: the voting wallet, its votes, the bucket block, and the wallet's
+ * EIP-712 signature over the ballot. `address` is carried so the LWW key and chain reads
+ * are available without re-recovering; it MUST equal `recoverTypedDataAddress(signature)`
+ * (a forged `address` fails the recovery check at verify time). The signed payload is
+ * the EIP-712 ballot built from the contest CID + chainId + `votes` + `blockNumber`
+ * (see signer/eip712.ts), not these wire bytes directly.
+ */
+export declare const VotesBundleSchema: z.ZodObject<{
+    address: z.ZodString;
+    votes: z.ZodArray<z.ZodObject<{
+        community: z.ZodObject<{
+            name: z.ZodOptional<z.ZodString>;
+            publicKey: z.ZodString;
+        }, z.core.$strip>;
+        vote: z.ZodNumber;
+    }, z.core.$strip>>;
+    blockNumber: z.ZodNumber;
+    signature: z.ZodObject<{
+        signature: z.ZodString;
+        type: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type Community = z.infer<typeof CommunitySchema>;
+export type Vote = z.infer<typeof VoteSchema>;
+export type VotesBundle = z.infer<typeof VotesBundleSchema>;

package/dist/schema/votes.js

@@ -0,0 +1,116 @@
+import { z } from "zod";
+import { base58btc } from "multiformats/bases/base58";
+import * as Digest from "multiformats/hashes/digest";
+import { SignatureSchema } from "./common.js";
+/**
+ * True when `x` is a base58btc IPNS name (a `12D3KooW…` key), i.e. it decodes to a
+ * multihash digest. This is the same check pkc-js uses (`isIpns`): a community identity is
+ * either a resolvable domain (contains a dot) or this self-certifying B58 key. A community's
+ * `publicKey` must be the B58 key — the stable identity the tally aggregates on — never a
+ * domain, which is mutable/re-pointable. The leading `z` is base58btc's multibase prefix.
+ */
+function isB58IpnsKey(x) {
+    try {
+        Digest.decode(base58btc.decode(`z${x}`));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The Votes wire format.
+ *
+ * One bundle per voting wallet per heartbeat, scoped to the topic's single contest.
+ * The bundle is the value stored at each Merkle-CRDT node. An empty `votes` array is
+ * the withdrawal/abstention form: a newer bundle (higher blockNumber) with no votes
+ * supersedes an earlier one under LWW, removing the vote from the tally without
+ * breaking the monotonic union. See DESIGN.md "Votes wire", "Cancelling a vote", and
+ * "CRDT".
+ *
+ * The bundle is signed directly by the gating-chain wallet as EIP-712 typed data
+ * (see signer/eip712.ts); `address` is that wallet and MUST equal the address recovered
+ * from `signature`. There is no pkc-js author and no author->wallet binding.
+ */
+/**
+ * True when `x` is a dotted domain name — at least two non-empty, whitespace-free labels
+ * (e.g. "memes.bso"). Community names must carry a TLD so they are resolvable through a
+ * name resolver; the TLD itself is deliberately not pinned (`.bso` today, possibly other
+ * naming systems later) — which names actually resolve is decided by the host-injected
+ * `nameResolvers` at tally time, not by this schema.
+ */
+function isDottedDomain(x) {
+    const labels = x.split(".");
+    return labels.length >= 2 && labels.every((label) => label.length > 0 && !/\s/.test(label));
+}
+/**
+ * The community being voted for: identified by its `publicKey`, with an
+ * optional resolvable domain `name` (e.g. "memes.bso"). Community identity — the key the
+ * tally aggregates on — is `publicKey` alone, but a carried `name` is a *verified
+ * claim*, not a free label: names are unique (the naming registry maps one name to one
+ * community), and at tally time a bundle whose `name` does not resolve to the claimed
+ * `publicKey` is dropped. A vote that omits `name` still folds into the same
+ * `publicKey` row. See DESIGN.md "Votes wire" and "Tally".
+ */
+export const CommunitySchema = z.object({
+    // A pkc-js community identity: `name` is an optional resolvable domain (must be
+    // dotted — carry a TLD — e.g. "memes.bso" via @bitsocial/bso-resolver), `publicKey`
+    // is the B58 IPNS name (e.g. "12D3KooW..."): the self-certifying key the tally
+    // aggregates on. Not an EVM address; the gating-chain wallet lives on the
+    // enclosing bundle's `address`, not here. We validate the key strictly
+    // (`isB58IpnsKey`) — stricter than pkc-js's loose `z.string().min(1)` field —
+    // because this is the vote-identity boundary: a domain or garbage in the identity
+    // slot must not reach the tally.
+    name: z
+        .string()
+        .min(1)
+        // The DNS hostname ceiling. A wire-shape hygiene bound, not a criteria knob: it makes a
+        // vote entry's size finite so the per-message cap is derivable from the criteria alone
+        // (see DESIGN.md "Message size cap").
+        .max(253)
+        .refine(isDottedDomain, "name must be a resolvable domain with a TLD (e.g. memes.bso)")
+        .optional(),
+    publicKey: z
+        .string()
+        .min(1)
+        .refine(isB58IpnsKey, "publicKey must be a base58btc IPNS key (e.g. 12D3KooW…), not a domain")
+});
+/**
+ * A single vote inside a bundle. The contest is implied by the topic (one contest
+ * per topic), so it is not repeated on the wire.
+ * - `community` is the community being voted for (`{ name?, publicKey }`).
+ * - `vote` is numeric; its allowed range comes from `criteria.voteSchema`
+ *   (v1 is upvote-only, so exactly 1). Range is enforced at verify time, not here,
+ *   because the bounds live in the criteria, not in the wire type.
+ */
+export const VoteSchema = z.object({
+    community: CommunitySchema,
+    vote: z.number().int()
+});
+/**
+ * The full wire node: the voting wallet, its votes, the bucket block, and the wallet's
+ * EIP-712 signature over the ballot. `address` is carried so the LWW key and chain reads
+ * are available without re-recovering; it MUST equal `recoverTypedDataAddress(signature)`
+ * (a forged `address` fails the recovery check at verify time). The signed payload is
+ * the EIP-712 ballot built from the contest CID + chainId + `votes` + `blockNumber`
+ * (see signer/eip712.ts), not these wire bytes directly.
+ */
+export const VotesBundleSchema = z
+    .object({
+    address: z.string().min(1),
+    votes: z.array(VoteSchema),
+    blockNumber: z.number().int().nonnegative(),
+    signature: SignatureSchema
+})
+    // The votes must name pairwise-distinct communities. `maxVotesPerAddress` caps how many
+    // entries a bundle carries, but only distinctness makes that a cap on *communities*:
+    // without it a wallet allowed N approval votes could list one community N times and
+    // stack N× weight on it. Unlike the criteria-dependent constraints (length cap,
+    // vote range — enforced at verify time because their bounds live in the criteria),
+    // distinctness is pure wire shape, so the schema owns it. Duplicate *names* need no
+    // rule: same name + different keys dies at name resolution, same name + same key is
+    // caught here. See DESIGN.md "Votes wire".
+    .refine((bundle) => new Set(bundle.votes.map((v) => v.community.publicKey)).size === bundle.votes.length, {
+    message: "votes must name pairwise-distinct community.publicKeys (one entry per community)",
+    path: ["votes"]
+});

package/dist/signer/eip712.d.ts

@@ -0,0 +1,103 @@
+import type { Vote } from "../schema/votes.js";
+/**
+ * EIP-712 ballot typed data.
+ *
+ * The voting wallet signs this structure, not the raw wire bytes: it is the single
+ * canonical artifact the signer produces and the verifier recovers against (via viem's
+ * `signTypedData` / `recoverTypedDataAddress`). It replaces the old cbor "signed
+ * property names" scheme. See DESIGN.md "Votes wire".
+ *
+ * The signature binds three things so a vote cannot be replayed onto another contest or
+ * app, and cannot be re-stamped to a different block:
+ *   - `criteria`: the criteria CID (equivalently the topic), carried as the raw binary
+ *     CID bytes (`cid.bytes`) so there is no multibase/version representation ambiguity —
+ *     every client hashes the same bytes. Different rules -> different CID -> a signature
+ *     gathered for one contest does not validate on another. (This is the CID of the whole
+ *     criteria document, distinct from the `criteria.contestId` slot-code field inside it.)
+ *   - `votes`: each community (`{ name, publicKey }`) + numeric vote.
+ *   - `blockNumber`: the LWW key and the bucketized block every verifier reads at.
+ *
+ * The `domain.chainId` is the gating (`rule`) chain, giving cross-chain/cross-app domain
+ * separation for free. This module is pure: no key material, no network, no viem import
+ * — it only shapes the object both sides feed to viem.
+ */
+/** EIP-712 domain name shared by every contest. */
+export declare const EIP712_DOMAIN_NAME = "bitsocial-votes";
+/** The `type` tag carried in a bundle's {@link Signature} for an EIP-712 ballot signature. */
+export declare const EIP712_SIGNATURE_TYPE = "eip712";
+/**
+ * The EIP-712 `types` struct — frozen for v1 (see DESIGN.md "Wire freeze (v1)"). Field
+ * names and order are part of the type hash, so any change here is a breaking wire change
+ * that must re-freeze the conformance vector in eip712.test.ts. The domain deliberately
+ * carries no `version` field — nothing ever version-negotiates the domain, so a layout
+ * change is just a new frozen vector, not a version bump.
+ *   - `criteria` is `bytes` (the raw binary CID, `cid.bytes`), not a string: hashing the
+ *     canonical bytes avoids the multibase/version ambiguity a stringified CID would bake
+ *     in, so independent clients recover identical signers.
+ *   - `vote` is `int256` (signed) so a future criteria can widen the range to downvotes
+ *     without a layout change; v1 is upvote-only.
+ *   - `community` is a `Community` struct (`{ name, publicKey }`). EIP-712 has no optional
+ *     fields, so `name` is always signed as a string — the empty string when the wire
+ *     vote carries no name. Community identity is `publicKey`; `name` is a display label and
+ *     does not affect the tally, so signing `""` vs. a name for the same `publicKey` is
+ *     the same community.
+ */
+export declare const BALLOT_TYPES: {
+    readonly Community: readonly [{
+        readonly name: "name";
+        readonly type: "string";
+    }, {
+        readonly name: "publicKey";
+        readonly type: "string";
+    }];
+    readonly Vote: readonly [{
+        readonly name: "community";
+        readonly type: "Community";
+    }, {
+        readonly name: "vote";
+        readonly type: "int256";
+    }];
+    readonly Ballot: readonly [{
+        readonly name: "criteria";
+        readonly type: "bytes";
+    }, {
+        readonly name: "votes";
+        readonly type: "Vote[]";
+    }, {
+        readonly name: "blockNumber";
+        readonly type: "uint256";
+    }];
+};
+/** The EIP-712 typed-data object handed to viem to sign or to recover a signer from. */
+export interface BallotTypedData {
+    domain: {
+        name: string;
+        chainId: number;
+    };
+    types: typeof BALLOT_TYPES;
+    primaryType: "Ballot";
+    message: {
+        criteria: `0x${string}`;
+        votes: {
+            community: {
+                name: string;
+                publicKey: string;
+            };
+            vote: bigint;
+        }[];
+        blockNumber: bigint;
+    };
+}
+/**
+ * Build the EIP-712 ballot typed data for a bundle. Both the signer (to sign) and the
+ * verifier (to recover) call this with identical inputs, so the hashed structure matches.
+ * Integer fields are emitted as `bigint` (EIP-712 256-bit ints).
+ */
+export declare function ballotTypedData(args: {
+    /** The criteria CID's raw binary bytes (`(await criteriaCid(criteria)).bytes`). */
+    criteriaCid: Uint8Array;
+    /** The gating (`rule`) chain's numeric chainId (`criteria.requires.chains[chain].chainId`). */
+    chainId: number;
+    votes: Vote[];
+    blockNumber: number;
+}): BallotTypedData;

package/dist/signer/eip712.js

@@ -0,0 +1,85 @@
+/**
+ * EIP-712 ballot typed data.
+ *
+ * The voting wallet signs this structure, not the raw wire bytes: it is the single
+ * canonical artifact the signer produces and the verifier recovers against (via viem's
+ * `signTypedData` / `recoverTypedDataAddress`). It replaces the old cbor "signed
+ * property names" scheme. See DESIGN.md "Votes wire".
+ *
+ * The signature binds three things so a vote cannot be replayed onto another contest or
+ * app, and cannot be re-stamped to a different block:
+ *   - `criteria`: the criteria CID (equivalently the topic), carried as the raw binary
+ *     CID bytes (`cid.bytes`) so there is no multibase/version representation ambiguity —
+ *     every client hashes the same bytes. Different rules -> different CID -> a signature
+ *     gathered for one contest does not validate on another. (This is the CID of the whole
+ *     criteria document, distinct from the `criteria.contestId` slot-code field inside it.)
+ *   - `votes`: each community (`{ name, publicKey }`) + numeric vote.
+ *   - `blockNumber`: the LWW key and the bucketized block every verifier reads at.
+ *
+ * The `domain.chainId` is the gating (`rule`) chain, giving cross-chain/cross-app domain
+ * separation for free. This module is pure: no key material, no network, no viem import
+ * — it only shapes the object both sides feed to viem.
+ */
+/** EIP-712 domain name shared by every contest. */
+export const EIP712_DOMAIN_NAME = "bitsocial-votes";
+/** The `type` tag carried in a bundle's {@link Signature} for an EIP-712 ballot signature. */
+export const EIP712_SIGNATURE_TYPE = "eip712";
+/**
+ * The EIP-712 `types` struct — frozen for v1 (see DESIGN.md "Wire freeze (v1)"). Field
+ * names and order are part of the type hash, so any change here is a breaking wire change
+ * that must re-freeze the conformance vector in eip712.test.ts. The domain deliberately
+ * carries no `version` field — nothing ever version-negotiates the domain, so a layout
+ * change is just a new frozen vector, not a version bump.
+ *   - `criteria` is `bytes` (the raw binary CID, `cid.bytes`), not a string: hashing the
+ *     canonical bytes avoids the multibase/version ambiguity a stringified CID would bake
+ *     in, so independent clients recover identical signers.
+ *   - `vote` is `int256` (signed) so a future criteria can widen the range to downvotes
+ *     without a layout change; v1 is upvote-only.
+ *   - `community` is a `Community` struct (`{ name, publicKey }`). EIP-712 has no optional
+ *     fields, so `name` is always signed as a string — the empty string when the wire
+ *     vote carries no name. Community identity is `publicKey`; `name` is a display label and
+ *     does not affect the tally, so signing `""` vs. a name for the same `publicKey` is
+ *     the same community.
+ */
+export const BALLOT_TYPES = {
+    Community: [
+        { name: "name", type: "string" },
+        { name: "publicKey", type: "string" }
+    ],
+    Vote: [
+        { name: "community", type: "Community" },
+        { name: "vote", type: "int256" }
+    ],
+    Ballot: [
+        { name: "criteria", type: "bytes" },
+        { name: "votes", type: "Vote[]" },
+        { name: "blockNumber", type: "uint256" }
+    ]
+};
+/** Lowercase `0x`-hex encoding of raw bytes, for the EIP-712 `bytes` message field. */
+function bytesToHex(bytes) {
+    let hex = "";
+    for (const b of bytes)
+        hex += b.toString(16).padStart(2, "0");
+    return `0x${hex}`;
+}
+/**
+ * Build the EIP-712 ballot typed data for a bundle. Both the signer (to sign) and the
+ * verifier (to recover) call this with identical inputs, so the hashed structure matches.
+ * Integer fields are emitted as `bigint` (EIP-712 256-bit ints).
+ */
+export function ballotTypedData(args) {
+    return {
+        domain: { name: EIP712_DOMAIN_NAME, chainId: args.chainId },
+        types: BALLOT_TYPES,
+        primaryType: "Ballot",
+        message: {
+            criteria: bytesToHex(args.criteriaCid),
+            votes: args.votes.map((v) => ({
+                community: { name: v.community.name ?? "", publicKey: v.community.publicKey },
+                vote: BigInt(v.vote)
+            })),
+            blockNumber: BigInt(args.blockNumber)
+        }
+    };
+}

package/dist/signer/types.d.ts

@@ -0,0 +1,31 @@
+import type { Signature } from "../schema/common.js";
+import type { BallotTypedData } from "./eip712.js";
+/**
+ * Identity seam (net-new).
+ *
+ * This is the third host-injected dependency, alongside the `HeliaInstance` (network +
+ * blockstore) and `ChainClientFactory` (chain). It lets a host-agnostic core be driven by
+ * pkc-js, plebbit, or a raw key without the library ever holding key material: the
+ * library builds the EIP-712 ballot typed data and asks the host to sign it.
+ *
+ * The signer wraps the gating-chain wallet — the account that holds the Pass/ERC-20.
+ * There is no pkc-js author and no author->wallet binding: the address recovered from the
+ * ballot signature IS the voter (see DESIGN.md "Identity: the voting wallet, nothing
+ * else"). A voter constructed without a signer is read-only (renders tallies, cannot
+ * cast). See DESIGN.md "Votes wire".
+ */
+export interface VoteSigner {
+    /**
+     * The voting wallet's address (the gating-chain account holding the Pass/ERC-20).
+     * Embedded as `bundle.address`; the verifier independently recovers it from the
+     * signature, so a wrong value here fails verification rather than forging a vote.
+     */
+    address(): Promise<string> | string;
+    /**
+     * Sign the EIP-712 ballot typed data with the wallet key (e.g. viem
+     * `account.signTypedData(typedData)`). The library builds the typed data; the private
+     * key stays in the host. Returns the detached signature with its scheme tag
+     * ({@link EIP712_SIGNATURE_TYPE}).
+     */
+    signBallot(typedData: BallotTypedData): Promise<Signature> | Signature;
+}

package/dist/signer/types.js

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

package/dist/storage/browser.d.ts

@@ -0,0 +1,3 @@
+import type { StorageOptions, VoteStorage } from "./types.js";
+/** Build the browser {@link VoteStorage}: IndexedDB via localforage, or in-memory for `false`. */
+export declare function makeStorage(options: StorageOptions): VoteStorage;