@bitsocial/pubsub-voting 0.1.6 → 0.2.0

package/README.md

@@ -24,7 +24,7 @@ This library does not start its own node. It consumes the host's running Helia n
 
 - **Settings live in the topic.** `topic = "bitsocial-votes/" + CID(dag-cbor(criteria))`. Two peers on the same topic provably ran identical rules, so the network validates itself with no intermediary.
 - **Votes are a state-based grow-only CRDT.** A signed `Votes` bundle is a standalone dag-cbor block (no parent links); each wallet gossips its own bundle **inline as a live delta**, validated straight from the message bytes — no fetch toward the publisher. State is a last-write-wins set keyed by wallet, so aggregation is a monotonic union: a peer can omit a vote but can never subtract one that an honest peer serves. Cold start and gap-fill exchange a tiny **root record** (libp2p-fetch pull + a slow topic heartbeat) and pull the checkpoint blocks behind it via directed bitswap from its advertisers.
-- **The gate and weight are data, not code.** A fixed rule registry (mirroring pkc-js's challenge registry) maps a `type` string to a verifier. v1 ships exactly the NFT path — an `erc721-min-balance` gate `rule` (5chan Pass) and `constant` weight (1 pass = 1 vote). Balance-derived (token-weighted) voting is deferred; see [ROADMAP.md](./ROADMAP.md).
+- **The gate and weight are data, not code.** A fixed rule registry (mirroring pkc-js's challenge registry) maps a `type` string to a verifier. v1 ships exactly the soulbound-NFT path — an `erc5192-min-balance` gate `rule` (the 5chan Pass: `balanceOf` **plus** an on-chain assertion that the contract declares its tokens locked) and `constant` weight (1 pass = 1 vote). A gate on a *transferable* asset would let one Pass back several concurrent votes, so the plain `erc721-min-balance` rule ships unregistered; balance-derived (token-weighted) voting is deferred. See [DESIGN.md, Does one Pass mean one vote?](./DESIGN.md#does-one-pass-mean-one-vote) and [ROADMAP.md](./ROADMAP.md).
 
 See [DESIGN.md](./DESIGN.md) for the full rationale, including how this resists vote-dropping and how criteria upgrades fork cleanly.
 
@@ -196,9 +196,18 @@ Full, type-checked call patterns for a pkc-js host, a plebbit/seedit host, and a
 
 ### Custom rules
 
-The gate and weight are a single flat registry of rules, one `type` per file, mirroring the pkc-js challenge registry. Each rule owns its option schema and is evaluated at the bundle's bucket block. Chain-reading rules get `ctx.chain` — the viem `PublicClient` for their `options.chain` — and write their own reads (`readContract`, `getBalance`, ...), pinning each call to the sampled block with `blockNumber: BigInt(ctx.blockNumber)`. There is **one kind**: `evaluate → { score: bigint }`, a non-negative score where `0n` means "does not qualify" (a result object, not a bare `bigint`, so slot-specific fields can be added later). The criteria has two *slots* drawing from the one registry — the **rule** slot treats the score as a gate (`> 0n` admits), the **weight** slot as the vote's magnitude. A wallet's vote counts as `rule.score > 0n ? weight.score : 0n`. A rule that needs a threshold returns `0n` below it (so `erc721-min-balance`'s optional `min` gates), which lets the same rule serve either slot. A chain-reading rule may also implement the optional `evaluateMany(walletAddresses, ctx)` batch hook — its semantics MUST equal mapping `evaluate` — which the background verifier uses to batch a cold join's gate reads (`erc721-min-balance` implements it over multicall3; see [DESIGN.md, Background chain verification](./DESIGN.md#background-chain-verification)).
+The gate and weight are a single flat registry of rules, one `type` per file, mirroring the pkc-js challenge registry. Each rule owns its option schema and is evaluated at the bundle's bucket block. Chain-reading rules get `ctx.chain` — the viem `PublicClient` for their `options.chain` — and write their own reads (`readContract`, `getBalance`, ...), pinning each call to the sampled block with `blockNumber: BigInt(ctx.blockNumber)`. There is **one kind**: `evaluate → { score: bigint }`, a non-negative score where `0n` means "does not qualify" (a result object, not a bare `bigint`, so slot-specific fields can be added later). The criteria has two *slots* drawing from the one registry — the **rule** slot treats the score as a gate (`> 0n` admits), the **weight** slot as the vote's magnitude. A wallet's vote counts as `rule.score > 0n ? weight.score : 0n`. A rule that needs a threshold returns `0n` below it (so `erc5192-min-balance`'s optional `min` gates), which lets the same rule serve either slot. A chain-reading rule may also implement the optional `evaluateMany({ options, walletAddresses, ctx })` batch hook (same argument object as `evaluate`, with `walletAddresses` in place of `walletAddress`, returning one `RuleResult` per input wallet in order) — its semantics MUST equal mapping `evaluate` — which the background verifier uses to batch a cold join's gate reads (`erc5192-min-balance` implements it over multicall3, hoisting its one lock assertion out of the per-wallet reads; see [DESIGN.md, Background chain verification](./DESIGN.md#background-chain-verification)).
 
-Built-ins: `erc721-min-balance` (v1) and `constant` (v1). A host adds or shadows rules by `type` via the `rules` option — this is how clients like 5chan or seedit register custom rules without forking the library:
+Built-ins: `erc5192-min-balance` (v1) and `constant` (v1).
+
+Two chain-reading rules ship in the tree but are deliberately **not** built in, so a criteria naming either recuses via `UnknownRuleError` instead of silently gating on an asset that does not bound Sybils:
+
+- **`erc721-min-balance`** (exported) — a bare `balanceOf` on a *transferable* token. One token walked A → B → C inside one expiry window backs three concurrent live votes, since every bundle is verified at its own pinned block and the winner set is LWW-keyed per wallet. `erc5192-min-balance` is this rule plus `supportsInterface(0xb45a3c0e)`, which refuses a contract that does not declare its tokens locked.
+- **`erc20-balance`** (not exported) — the same amplification, reopened by fungibility, plus the open lazy-tally ceiling question for balance-derived weight.
+
+A host that wants a transferable gate anyway registers `erc721MinBalance` explicitly through the `rules` option below — the library stops blessing the configuration, it does not forbid it. `erc20-balance` is not exported at all, so a host that wants balance-weighting supplies its own rule of that `type`. See [DESIGN.md, Does one Pass mean one vote?](./DESIGN.md#does-one-pass-mean-one-vote).
+
+A host adds or shadows rules by `type` via the `rules` option — this is how clients like 5chan or seedit register custom rules without forking the library:
 
 ```ts
 import { PubsubVoter, type Rule } from "@bitsocial/pubsub-voting";
@@ -222,7 +231,7 @@ A custom `type` becomes part of `dag-cbor(criteria)`, so it is provably pinned t
 
 ### Weighted voting (deferred)
 
-v1 ships `constant` weight (one Pass, one vote) **on purpose** — it resists whale dominance and downvote weaponization. Balance-derived, token-weighted voting (Pass gate + BSO weight via `erc20-balance`) is a designed-but-unshipped capability: the rule path and result shape leave room for it with no engine change, but it is not in the v1 built-ins and carries open governance/abuse and lazy-tally questions. See [ROADMAP.md](./ROADMAP.md) and [DESIGN.md, Future improvements](./DESIGN.md#future-improvements).
+v1 ships `constant` weight (one Pass, one vote) **on purpose** — it resists whale dominance and downvote weaponization. Balance-derived, token-weighted voting (Pass gate + BSO weight via `erc20-balance`) is a designed-but-unshipped capability: the rule path and result shape leave room for it with no engine change, but it is not in the v1 built-ins and carries open governance/abuse and lazy-tally questions — plus the Sybil amplification a fungible gate reopens, which the soulbound gate's fix cannot close for a balance (it needs a hold-duration guard instead). See [ROADMAP.md](./ROADMAP.md), [DESIGN.md, Does one Pass mean one vote?](./DESIGN.md#does-one-pass-mean-one-vote), and [DESIGN.md, Future improvements](./DESIGN.md#future-improvements).
 
 ## Layout
 

package/dist/chain/ticker.d.ts

@@ -1,7 +1,7 @@
 import type { Criteria, RuleRef } from "../schema/criteria.js";
 /**
  * Resolve which chain a rule reads. A rule's parsed options may name a
- * `chain` ticker (e.g. `erc721-min-balance` -> "base"); a chainless rule (e.g.
+ * `chain` ticker (e.g. `erc5192-min-balance` -> "base"); a chainless rule (e.g.
  * `constant`) names none, so callers fall back to the first configured chain. Shared by the
  * verifier, the tally, and the facade so the fallback rule stays identical everywhere.
  */

package/dist/chain/ticker.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 /**
  * Resolve which chain a rule reads. A rule's parsed options may name a
- * `chain` ticker (e.g. `erc721-min-balance` -> "base"); a chainless rule (e.g.
+ * `chain` ticker (e.g. `erc5192-min-balance` -> "base"); a chainless rule (e.g.
  * `constant`) names none, so callers fall back to the first configured chain. Shared by the
  * verifier, the tally, and the facade so the fallback rule stays identical everywhere.
  */

package/dist/index.d.ts

@@ -15,6 +15,7 @@ export * from "./schema/common.js";
 export * from "./schema/votes.js";
 export * from "./schema/criteria.js";
 export * from "./schema/directory.js";
+export * from "./rules/erc5192-min-balance.js";
 export * from "./rules/erc721-min-balance.js";
 export * from "./rules/constant.js";
 export * from "./rules/registry.js";

package/dist/index.js

@@ -25,8 +25,12 @@ export * from "./schema/directory.js";
 // validation). The leaf rules read through the injected viem `PublicClient`
 // (`ctx.chain`). Rule composition (combining several into one slot) is a
 // documented future extension, not a built-in — see DESIGN.md "Future improvements".
-// v1 ships the NFT path only: `erc721-min-balance` + `constant`. `erc20-balance` stays in
-// the tree but is not registered or re-exported — see ROADMAP.md ("Deferred").
+// v1 ships the soulbound-NFT path only: `erc5192-min-balance` + `constant`.
+// `erc721-min-balance` is exported but NOT registered — a bare `balanceOf` gate admits the
+// transfer amplification `erc5192-min-balance`'s lock assertion closes (issue #27), so a host
+// that wants it must opt in explicitly through the `rules` override map. `erc20-balance` stays
+// in the tree and is neither registered nor re-exported — see ROADMAP.md ("Deferred") and #28.
+export * from "./rules/erc5192-min-balance.js";
 export * from "./rules/erc721-min-balance.js";
 export * from "./rules/constant.js";
 export * from "./rules/registry.js";

package/dist/rules/erc20-balance.d.ts

@@ -3,6 +3,13 @@ import type { Rule } from "./types.js";
 /**
  * Score by ERC-20 balance (for example BSO). Reserved for the pass + BSO combo path.
  *
+ * **NOT registered** in `builtinRegistry` — a criteria naming it recuses via
+ * `UnknownRuleError`. Two independent blockers: the design-open lazy-tally ceiling for a
+ * balance-derived weight, and the Sybil amplification a fungible gate reopens (one balance
+ * walked through several wallets inside one expiry window backs several concurrent votes;
+ * a balance can be neither non-transferable nor LWW-keyed by token id, so it needs a
+ * hold-duration guard instead). See registry.ts and issue #28 before re-registering it.
+ *
  * Score = the wallet's raw balance (base units) at the bucket block if it meets `min`,
  * else 0n. `min` (in whole tokens, default 0) is what lets this single rule serve
  * BOTH slots: in the weight slot leave `min` at 0 and the score is the magnitude; in the

package/dist/rules/erc20-balance.js

@@ -4,6 +4,13 @@ import { ChainTickerSchema } from "../schema/common.js";
 /**
  * Score by ERC-20 balance (for example BSO). Reserved for the pass + BSO combo path.
  *
+ * **NOT registered** in `builtinRegistry` — a criteria naming it recuses via
+ * `UnknownRuleError`. Two independent blockers: the design-open lazy-tally ceiling for a
+ * balance-derived weight, and the Sybil amplification a fungible gate reopens (one balance
+ * walked through several wallets inside one expiry window backs several concurrent votes;
+ * a balance can be neither non-transferable nor LWW-keyed by token id, so it needs a
+ * hold-duration guard instead). See registry.ts and issue #28 before re-registering it.
+ *
  * Score = the wallet's raw balance (base units) at the bucket block if it meets `min`,
  * else 0n. `min` (in whole tokens, default 0) is what lets this single rule serve
  * BOTH slots: in the weight slot leave `min` at 0 and the score is the magnitude; in the

package/dist/rules/erc5192-min-balance.d.ts

@@ -0,0 +1,41 @@
+import { z } from "zod";
+import type { Rule } from "./types.js";
+/**
+ * Hold at least `min` of a **soulbound** ERC-721 (the 5chan Pass). The v1 gate.
+ *
+ * Same `balanceOf` scoring as `erc721-min-balance` — the wallet's holding at the bucket block
+ * if it meets `min`, else `0n` — plus one assertion at the SAME pinned block: the contract must
+ * declare ERC-5192 (`supportsInterface(0xb45a3c0e)`). A contract that does not declare it scores
+ * `0n` for every wallet, so the contest admits nobody rather than gating on a transferable asset.
+ *
+ * **Why the assertion is the whole point.** The gate bounds Sybils only if the gating asset
+ * cannot move (DESIGN.md "Does one Pass mean one vote?"): every bundle is verified at its OWN
+ * pinned block, stays live for `voteExpiryBuckets`, and the winner set is LWW-keyed per wallet —
+ * so one transferable token walked A → B → C inside a single expiry window backs three
+ * concurrent live votes, each read true at its own block and none collapsed by LWW. Nothing in
+ * the verify pipeline can see that: every ballot is individually correct. Requiring the asset to
+ * be non-transferable AND to say so on-chain closes it with no wire change, no extra archive
+ * depth, and no second read per wallet. Pinned by `src/crdt/amplification.test.ts`.
+ *
+ * **What the assertion does and does not prove.** `supportsInterface(0xb45a3c0e)` asserts the
+ * contract *reports* lock state — ERC-5192's only function is `locked(uint256)`. ERC-5192
+ * permits unlockable tokens (it defines an `Unlocked` event), so this is not proof that a given
+ * token is locked; it refuses contracts that do not even claim the property. Per-token proof
+ * would need `locked(tokenId)`, i.e. token ids in the signed bundle — a re-pin of the frozen
+ * EIP-712 vector. The deployed gate closes the gap by being permanently locked with a constant
+ * `locked() == true`.
+ *
+ * ERC-5192 mandates ERC-721 conformance, so `balanceOf` stays valid. In the rule slot `> 0`
+ * admits the wallet; in the weight slot it weights by the number of Passes held. The body reads
+ * through the injected viem client (no libp2p/helia import), unit-testable against a stub.
+ */
+/** ERC-5192's interface id (its only function is `locked(uint256)`). */
+export declare const ERC5192_INTERFACE_ID: "0xb45a3c0e";
+export declare const Erc5192MinBalanceOptionsSchema: z.ZodObject<{
+    type: z.ZodLiteral<"erc5192-min-balance">;
+    chain: z.ZodString;
+    contract: z.ZodString;
+    min: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+export type Erc5192MinBalanceOptions = z.infer<typeof Erc5192MinBalanceOptionsSchema>;
+export declare const erc5192MinBalance: Rule<Erc5192MinBalanceOptions>;

package/dist/rules/erc5192-min-balance.js

@@ -0,0 +1,111 @@
+import { BaseError, ContractFunctionRevertedError, ContractFunctionZeroDataError, getAddress } from "viem";
+import { z } from "zod";
+import { ChainTickerSchema } from "../schema/common.js";
+import { balanceOf, balancesOfBatched, canBatch, scoreOf } from "./nft-balance.js";
+/**
+ * Hold at least `min` of a **soulbound** ERC-721 (the 5chan Pass). The v1 gate.
+ *
+ * Same `balanceOf` scoring as `erc721-min-balance` — the wallet's holding at the bucket block
+ * if it meets `min`, else `0n` — plus one assertion at the SAME pinned block: the contract must
+ * declare ERC-5192 (`supportsInterface(0xb45a3c0e)`). A contract that does not declare it scores
+ * `0n` for every wallet, so the contest admits nobody rather than gating on a transferable asset.
+ *
+ * **Why the assertion is the whole point.** The gate bounds Sybils only if the gating asset
+ * cannot move (DESIGN.md "Does one Pass mean one vote?"): every bundle is verified at its OWN
+ * pinned block, stays live for `voteExpiryBuckets`, and the winner set is LWW-keyed per wallet —
+ * so one transferable token walked A → B → C inside a single expiry window backs three
+ * concurrent live votes, each read true at its own block and none collapsed by LWW. Nothing in
+ * the verify pipeline can see that: every ballot is individually correct. Requiring the asset to
+ * be non-transferable AND to say so on-chain closes it with no wire change, no extra archive
+ * depth, and no second read per wallet. Pinned by `src/crdt/amplification.test.ts`.
+ *
+ * **What the assertion does and does not prove.** `supportsInterface(0xb45a3c0e)` asserts the
+ * contract *reports* lock state — ERC-5192's only function is `locked(uint256)`. ERC-5192
+ * permits unlockable tokens (it defines an `Unlocked` event), so this is not proof that a given
+ * token is locked; it refuses contracts that do not even claim the property. Per-token proof
+ * would need `locked(tokenId)`, i.e. token ids in the signed bundle — a re-pin of the frozen
+ * EIP-712 vector. The deployed gate closes the gap by being permanently locked with a constant
+ * `locked() == true`.
+ *
+ * ERC-5192 mandates ERC-721 conformance, so `balanceOf` stays valid. In the rule slot `> 0`
+ * admits the wallet; in the weight slot it weights by the number of Passes held. The body reads
+ * through the injected viem client (no libp2p/helia import), unit-testable against a stub.
+ */
+/** ERC-5192's interface id (its only function is `locked(uint256)`). */
+export const ERC5192_INTERFACE_ID = "0xb45a3c0e";
+const erc165Abi = [
+    {
+        type: "function",
+        name: "supportsInterface",
+        stateMutability: "view",
+        inputs: [{ name: "interfaceId", type: "bytes4" }],
+        outputs: [{ type: "bool" }]
+    }
+];
+export const Erc5192MinBalanceOptionsSchema = z.object({
+    type: z.literal("erc5192-min-balance"),
+    chain: ChainTickerSchema,
+    contract: z.string(),
+    min: z.number().int().positive().default(1)
+});
+/**
+ * Does the read prove "this contract does not answer `supportsInterface`", as opposed to "the
+ * gateway failed"? A contract with no ERC-165 at all reverts (or returns no data) — that is a
+ * chain FACT and means the gate must refuse, permanently and identically for every verifier. An
+ * RPC outage is not a fact about the chain, and DESIGN.md keeps a throwing read infra-class
+ * everywhere (gossip `ignore`, background retry) precisely so a flaky gateway never turns into a
+ * consensus `reject` that scores honest relayers down. So only viem's revert/zero-data errors
+ * map to "does not declare"; everything else (transport, timeout, rate limit) rethrows.
+ */
+function isContractRefusal(err) {
+    if (!(err instanceof BaseError))
+        return false;
+    return err.walk((cause) => cause instanceof ContractFunctionRevertedError || cause instanceof ContractFunctionZeroDataError) !== null;
+}
+/**
+ * One `supportsInterface(0xb45a3c0e)` at the sampled block. Identical calldata at the same block
+ * for every wallet in a batch, so the voter's read coalescer (src/chain/coalescer.ts) dedupes a
+ * whole checkpoint's worth of wallets — and every parallel contest on the same contract — onto a
+ * single extra read, folded into the same `aggregate3` as the balances.
+ */
+async function declaresErc5192(contract, ctx) {
+    try {
+        return await ctx.chain.readContract({
+            address: contract,
+            abi: erc165Abi,
+            functionName: "supportsInterface",
+            args: [ERC5192_INTERFACE_ID],
+            blockNumber: BigInt(ctx.blockNumber)
+        });
+    }
+    catch (err) {
+        if (isContractRefusal(err))
+            return false;
+        throw err;
+    }
+}
+export const erc5192MinBalance = {
+    type: "erc5192-min-balance",
+    optionsSchema: Erc5192MinBalanceOptionsSchema,
+    async evaluate({ options, walletAddress, ctx }) {
+        const contract = getAddress(options.contract);
+        // Issued together, not sequenced: same block, so the coalescer folds both into one
+        // aggregate3 — the lock assertion costs no extra round trip.
+        const [declares, balance] = await Promise.all([declaresErc5192(contract, ctx), balanceOf(contract, walletAddress, ctx)]);
+        return { score: declares ? scoreOf(balance, options.min) : 0n };
+    },
+    async evaluateMany({ options, walletAddresses, ctx }) {
+        const contract = getAddress(options.contract);
+        // ONE lock assertion for the whole batch (hoisted out of the per-wallet reads), in
+        // parallel with the balances so both share the coalescing window.
+        const [declares, balances] = await Promise.all([
+            declaresErc5192(contract, ctx),
+            canBatch(ctx)
+                ? balancesOfBatched(contract, walletAddresses, ctx)
+                : Promise.all(walletAddresses.map((wallet) => balanceOf(contract, wallet, ctx)))
+        ]);
+        if (!declares)
+            return walletAddresses.map(() => ({ score: 0n }));
+        return balances.map((balance) => ({ score: scoreOf(balance, options.min) }));
+    }
+};

package/dist/rules/erc721-min-balance.d.ts

@@ -1,12 +1,24 @@
 import { z } from "zod";
 import type { Rule } from "./types.js";
 /**
- * Hold at least `min` of an ERC-721 (the 5chan Pass). v1.
+ * Hold at least `min` of a **plain** ERC-721.
  *
- * Score = the wallet's holding at the bucket block if it meets `min`, else 0. In the
- * rule slot, `> 0` admits the wallet (it holds the Pass); in the weight slot it
- * weights by the number of Passes held. The body reads its own `balanceOf` via the
- * injected viem client (no libp2p/helia import), unit-testable against a stubbed client.
+ * **NOT registered** in `builtinRegistry` — a criteria naming it recuses via `UnknownRuleError`.
+ * It reads a bare `balanceOf` and asserts nothing about transferability, so it gates on an asset
+ * that can move: one token walked A → B → C inside a single expiry window backs three concurrent
+ * live votes, since every bundle is verified at its own pinned block and the winner set is
+ * LWW-keyed per wallet (DESIGN.md "Does one Pass mean one vote?"; pinned by
+ * `src/crdt/amplification.test.ts`). The v1 gate is `erc5192-min-balance`, which is this rule plus
+ * a `supportsInterface(0xb45a3c0e)` assertion that the contract declares its tokens locked.
+ *
+ * Kept in the tree, exported, and unit-tested: a host that genuinely wants a transferable gate
+ * can still register it through the `rules` override map. The library stops blessing the
+ * configuration; it does not forbid it. See registry.ts and issue #27.
+ *
+ * Score = the wallet's holding at the bucket block if it meets `min`, else 0. In the rule slot,
+ * `> 0` admits the wallet; in the weight slot it weights by the number of tokens held. The body
+ * reads its own `balanceOf` via the injected viem client (no libp2p/helia import), unit-testable
+ * against a stubbed client.
  */
 export declare const Erc721MinBalanceOptionsSchema: z.ZodObject<{
     type: z.ZodLiteral<"erc721-min-balance">;

package/dist/rules/erc721-min-balance.js

@@ -1,14 +1,26 @@
-import { erc721Abi, getAddress } from "viem";
+import { getAddress } from "viem";
 import { z } from "zod";
-import { CHAIN_CHUNK_RETRY_DELAY_MS, CHAIN_MULTICALL_CONCURRENCY, CHAIN_READS_PER_MULTICALL } from "../chain/coalescer.js";
 import { ChainTickerSchema } from "../schema/common.js";
+import { balanceOf, balancesOfBatched, canBatch, scoreOf } from "./nft-balance.js";
 /**
- * Hold at least `min` of an ERC-721 (the 5chan Pass). v1.
+ * Hold at least `min` of a **plain** ERC-721.
  *
- * Score = the wallet's holding at the bucket block if it meets `min`, else 0. In the
- * rule slot, `> 0` admits the wallet (it holds the Pass); in the weight slot it
- * weights by the number of Passes held. The body reads its own `balanceOf` via the
- * injected viem client (no libp2p/helia import), unit-testable against a stubbed client.
+ * **NOT registered** in `builtinRegistry` — a criteria naming it recuses via `UnknownRuleError`.
+ * It reads a bare `balanceOf` and asserts nothing about transferability, so it gates on an asset
+ * that can move: one token walked A → B → C inside a single expiry window backs three concurrent
+ * live votes, since every bundle is verified at its own pinned block and the winner set is
+ * LWW-keyed per wallet (DESIGN.md "Does one Pass mean one vote?"; pinned by
+ * `src/crdt/amplification.test.ts`). The v1 gate is `erc5192-min-balance`, which is this rule plus
+ * a `supportsInterface(0xb45a3c0e)` assertion that the contract declares its tokens locked.
+ *
+ * Kept in the tree, exported, and unit-tested: a host that genuinely wants a transferable gate
+ * can still register it through the `rules` override map. The library stops blessing the
+ * configuration; it does not forbid it. See registry.ts and issue #27.
+ *
+ * Score = the wallet's holding at the bucket block if it meets `min`, else 0. In the rule slot,
+ * `> 0` admits the wallet; in the weight slot it weights by the number of tokens held. The body
+ * reads its own `balanceOf` via the injected viem client (no libp2p/helia import), unit-testable
+ * against a stubbed client.
  */
 export const Erc721MinBalanceOptionsSchema = z.object({
     type: z.literal("erc721-min-balance"),
@@ -16,85 +28,21 @@ export const Erc721MinBalanceOptionsSchema = z.object({
     contract: z.string(),
     min: z.number().int().positive().default(1)
 });
-/** Score from one balance: the holding when it meets `min`, else `0n` (does not qualify). */
-function scoreOf(balance, min) {
-    return balance >= BigInt(min) ? balance : 0n;
-}
-/**
- * Chunking policy shared with the voter-level read coalescer (src/chain/coalescer.ts). viem's
- * own default chunking (1,024 bytes of calldata ≈ 27 `balanceOf`s) would split a 1000-wallet
- * batch into ~38 chunks and fire them ALL concurrently — a burst public RPC endpoints throttle
- * (measured against `mainnet.base.org`: 33/38 requests answered HTTP 429 `-32016 over rate
- * limit` and the batch never settled). 200 reads is ~45 KB of calldata and ~2–5M `eth_call`
- * gas — inside public request-size and gas caps — so a 1000-wallet batch is 5 round trips.
- * The in-flight bound here is per evaluateMany call; the coalescer additionally enforces the
- * same budget globally across parallel contests (its wrapped `multicall` is what this rule's
- * batched path runs through).
- */
-const READS_PER_MULTICALL = CHAIN_READS_PER_MULTICALL;
-const MULTICALL_CONCURRENCY = CHAIN_MULTICALL_CONCURRENCY;
-const CHUNK_RETRY_DELAY_MS = CHAIN_CHUNK_RETRY_DELAY_MS;
 export const erc721MinBalance = {
     type: "erc721-min-balance",
     optionsSchema: Erc721MinBalanceOptionsSchema,
     async evaluate({ options, walletAddress, ctx }) {
-        const balance = await ctx.chain.readContract({
-            address: getAddress(options.contract),
-            abi: erc721Abi,
-            functionName: "balanceOf",
-            args: [getAddress(walletAddress)],
-            blockNumber: BigInt(ctx.blockNumber)
-        });
+        const balance = await balanceOf(getAddress(options.contract), walletAddress, ctx);
         return { score: scoreOf(balance, options.min) };
     },
     async evaluateMany({ options, walletAddresses, ctx }) {
         const contract = getAddress(options.contract);
-        // Multicall3 `aggregate3` batching — the path the background chain verifier rides on a
-        // cold join. The wallets are chunked HERE (`READS_PER_MULTICALL` per aggregate3,
-        // `batchSize: 0` disables viem's own 1KB re-chunking) and the chunks are sent with
-        // bounded concurrency plus one in-rule retry each, so a big batch is a handful of
-        // polite round trips rather than a ~40-request burst a public endpoint throttles —
-        // and one failed chunk never discards the others' results. Needs the client to know
-        // its chain's multicall3 deployment; a client built without a `chain` (or on a chain
-        // without multicall3) takes the per-wallet fallback below.
-        if (typeof ctx.chain.multicall === "function" && ctx.chain.chain?.contracts?.multicall3) {
-            const chunks = [];
-            for (let at = 0; at < walletAddresses.length; at += READS_PER_MULTICALL) {
-                chunks.push(walletAddresses.slice(at, at + READS_PER_MULTICALL));
-            }
-            const results = new Array(walletAddresses.length);
-            const readChunk = async (chunk) => ctx.chain.multicall({
-                contracts: chunk.map((wallet) => ({
-                    address: contract,
-                    abi: erc721Abi,
-                    functionName: "balanceOf",
-                    args: [getAddress(wallet)]
-                })),
-                allowFailure: false,
-                batchSize: 0,
-                blockNumber: BigInt(ctx.blockNumber)
-            });
-            let nextChunk = 0;
-            const worker = async () => {
-                while (nextChunk < chunks.length) {
-                    const index = nextChunk++;
-                    const chunk = chunks[index];
-                    let balances;
-                    try {
-                        balances = await readChunk(chunk);
-                    }
-                    catch {
-                        await new Promise((resolve) => setTimeout(resolve, CHUNK_RETRY_DELAY_MS));
-                        balances = await readChunk(chunk);
-                    }
-                    for (let i = 0; i < chunk.length; i++) {
-                        results[index * READS_PER_MULTICALL + i] = { score: scoreOf(balances[i], options.min) };
-                    }
-                }
-            };
-            await Promise.all(Array.from({ length: Math.min(MULTICALL_CONCURRENCY, chunks.length) }, worker));
-            return results;
-        }
-        return Promise.all(walletAddresses.map((walletAddress) => this.evaluate({ options, walletAddress, ctx })));
+        // Multicall3 `aggregate3` batching (see nft-balance.ts for the chunking policy) — the
+        // path the background chain verifier rides on a cold join. A client that cannot batch
+        // takes the per-wallet fallback.
+        const balances = canBatch(ctx)
+            ? await balancesOfBatched(contract, walletAddresses, ctx)
+            : await Promise.all(walletAddresses.map((wallet) => balanceOf(contract, wallet, ctx)));
+        return balances.map((balance) => ({ score: scoreOf(balance, options.min) }));
     }
 };

package/dist/rules/nft-balance.d.ts

@@ -0,0 +1,23 @@
+import type { ChainReadContext } from "./types.js";
+/** Score from one balance: the holding when it meets `min`, else `0n` (does not qualify). */
+export declare function scoreOf(balance: bigint, min: number): bigint;
+/**
+ * True when the client can run multicall3 `aggregate3` batches — it needs both the action and
+ * its chain's multicall3 deployment. A client built without a `chain` (or on a chain without
+ * multicall3) takes the per-wallet path instead.
+ */
+export declare function canBatch(ctx: ChainReadContext): boolean;
+/** One wallet's `balanceOf` at the bundle's sampled block. */
+export declare function balanceOf(contract: `0x${string}`, walletAddress: string, ctx: ChainReadContext): Promise<bigint>;
+/**
+ * Many wallets' `balanceOf` at ONE sampled block — the path the background chain verifier rides
+ * on a cold join. Requires {@link canBatch}; callers fall back to mapping {@link balanceOf}.
+ *
+ * The wallets are chunked HERE (`READS_PER_MULTICALL` per aggregate3, `batchSize: 0` disables
+ * viem's own 1KB re-chunking) and the chunks are sent with bounded concurrency plus one retry
+ * each, so a big batch is a handful of polite round trips rather than a ~40-request burst a
+ * public endpoint throttles — and the retry re-reads only the chunk that failed, never a
+ * completed one (viem's own whole-batch retry re-fired the entire burst). A chunk that fails
+ * twice still fails the whole call: the caller gets one rejection, not partial results.
+ */
+export declare function balancesOfBatched(contract: `0x${string}`, walletAddresses: string[], ctx: ChainReadContext): Promise<bigint[]>;

package/dist/rules/nft-balance.js

@@ -0,0 +1,97 @@
+import { erc721Abi, getAddress } from "viem";
+import { CHAIN_CHUNK_RETRY_DELAY_MS, CHAIN_MULTICALL_CONCURRENCY, CHAIN_READS_PER_MULTICALL } from "../chain/coalescer.js";
+/**
+ * The shared `balanceOf` read path behind the two NFT gate rules (`erc5192-min-balance`, the
+ * registered v1 gate, and the unregistered `erc721-min-balance`). Internal — not exported from
+ * `src/index.ts`, not part of the public API.
+ *
+ * Both rules score the same way (`balance >= min ? balance : 0n`); they differ only in whether
+ * the contract must additionally declare ERC-5192. Keeping ONE copy of the chunking policy
+ * matters: the numbers below are tuned against real public endpoints (see below), and two
+ * drifting copies would silently reintroduce the burst this exists to prevent.
+ */
+/**
+ * Chunking policy shared with the voter-level read coalescer (src/chain/coalescer.ts). viem's
+ * own default chunking (1,024 bytes of calldata ≈ 27 `balanceOf`s) would split a 1000-wallet
+ * batch into ~38 chunks and fire them ALL concurrently — a burst public RPC endpoints throttle
+ * (measured against `mainnet.base.org`: 33/38 requests answered HTTP 429 `-32016 over rate
+ * limit` and the batch never settled). 200 reads is ~45 KB of calldata and ~2–5M `eth_call`
+ * gas — inside public request-size and gas caps — so a 1000-wallet batch is 5 round trips.
+ * The in-flight bound here is per batch call; the coalescer additionally enforces the
+ * same budget globally across parallel contests (its wrapped `multicall` is what the batched
+ * path below runs through).
+ */
+const READS_PER_MULTICALL = CHAIN_READS_PER_MULTICALL;
+const MULTICALL_CONCURRENCY = CHAIN_MULTICALL_CONCURRENCY;
+const CHUNK_RETRY_DELAY_MS = CHAIN_CHUNK_RETRY_DELAY_MS;
+/** Score from one balance: the holding when it meets `min`, else `0n` (does not qualify). */
+export function scoreOf(balance, min) {
+    return balance >= BigInt(min) ? balance : 0n;
+}
+/**
+ * True when the client can run multicall3 `aggregate3` batches — it needs both the action and
+ * its chain's multicall3 deployment. A client built without a `chain` (or on a chain without
+ * multicall3) takes the per-wallet path instead.
+ */
+export function canBatch(ctx) {
+    return typeof ctx.chain.multicall === "function" && Boolean(ctx.chain.chain?.contracts?.multicall3);
+}
+/** One wallet's `balanceOf` at the bundle's sampled block. */
+export function balanceOf(contract, walletAddress, ctx) {
+    return ctx.chain.readContract({
+        address: contract,
+        abi: erc721Abi,
+        functionName: "balanceOf",
+        args: [getAddress(walletAddress)],
+        blockNumber: BigInt(ctx.blockNumber)
+    });
+}
+/**
+ * Many wallets' `balanceOf` at ONE sampled block — the path the background chain verifier rides
+ * on a cold join. Requires {@link canBatch}; callers fall back to mapping {@link balanceOf}.
+ *
+ * The wallets are chunked HERE (`READS_PER_MULTICALL` per aggregate3, `batchSize: 0` disables
+ * viem's own 1KB re-chunking) and the chunks are sent with bounded concurrency plus one retry
+ * each, so a big batch is a handful of polite round trips rather than a ~40-request burst a
+ * public endpoint throttles — and the retry re-reads only the chunk that failed, never a
+ * completed one (viem's own whole-batch retry re-fired the entire burst). A chunk that fails
+ * twice still fails the whole call: the caller gets one rejection, not partial results.
+ */
+export async function balancesOfBatched(contract, walletAddresses, ctx) {
+    const chunks = [];
+    for (let at = 0; at < walletAddresses.length; at += READS_PER_MULTICALL) {
+        chunks.push(walletAddresses.slice(at, at + READS_PER_MULTICALL));
+    }
+    const balances = new Array(walletAddresses.length);
+    const readChunk = async (chunk) => ctx.chain.multicall({
+        contracts: chunk.map((wallet) => ({
+            address: contract,
+            abi: erc721Abi,
+            functionName: "balanceOf",
+            args: [getAddress(wallet)]
+        })),
+        allowFailure: false,
+        batchSize: 0,
+        blockNumber: BigInt(ctx.blockNumber)
+    });
+    let nextChunk = 0;
+    const worker = async () => {
+        while (nextChunk < chunks.length) {
+            const index = nextChunk++;
+            const chunk = chunks[index];
+            let read;
+            try {
+                read = await readChunk(chunk);
+            }
+            catch {
+                await new Promise((resolve) => setTimeout(resolve, CHUNK_RETRY_DELAY_MS));
+                read = await readChunk(chunk);
+            }
+            for (let i = 0; i < chunk.length; i++) {
+                balances[index * READS_PER_MULTICALL + i] = read[i];
+            }
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(MULTICALL_CONCURRENCY, chunks.length) }, worker));
+    return balances;
+}

package/dist/rules/registry.d.ts

@@ -14,15 +14,38 @@ import type { RuleRegistry } from "./types.js";
 /**
  * The library's built-in rules, before any host override.
  *
- * v1 ships exactly the NFT path: `erc721-min-balance` (Pass gate) + `constant` weight.
- * `erc20-balance` is intentionally NOT registered — it stays in the tree (`erc20-balance.ts`,
- * unit-tested) as the design-open weight path, but is unshipped so a criteria naming it
- * recuses via `UnknownRuleError` rather than silently enabling token-weighting. See
- * ROADMAP.md ("Deferred") for when it re-ships.
+ * v1 ships exactly the soulbound-NFT path: `erc5192-min-balance` (Pass gate) + `constant`
+ * weight. TWO chain-reading rules stay in the tree and unit-tested (only `erc721-min-balance` is
+ * re-exported from `src/index.ts`) but deliberately OUT of this map, so a criteria naming either
+ * recuses via `UnknownRuleError` instead of silently gating on an asset that does not bound
+ * Sybils. A host that wants one anyway can still register it through the override map below —
+ * the library declines to bless the configuration, it does not forbid it.
+ *
+ * **`erc721-min-balance`** — a bare `balanceOf` on a *transferable* token. The gate bounds
+ * Sybils only because the asset cannot move (DESIGN.md "Does one Pass mean one vote?"): every
+ * bundle is verified at its OWN pinned block, stays live for `voteExpiryBuckets`, and the
+ * winner set is LWW-keyed per wallet, so one token walked A → B → C inside a single expiry
+ * window backs three concurrent live votes — each read true at its own block, none collapsed by
+ * LWW, and not one of them individually invalid. `erc5192-min-balance` is the same rule plus an
+ * on-chain assertion that the contract declares its tokens locked (issue #27).
+ *
+ * **`erc20-balance`** — the same amplification, reopened by fungibility, plus a second blocker.
+ * Both must resolve before it re-ships:
+ *
+ *   1. the weight path is design-open — a balance-derived weight derives its magnitude from
+ *      the chain read, so it carries no free wire-side ceiling for the lazy tally (see
+ *      `RuleResult` in types.ts, ROADMAP.md "Deferred");
+ *   2. the ERC-5192 fix does not transfer to fungibles: a balance can be neither soulbound nor
+ *      LWW-keyed by token id. Closing it needs a hold-duration guard instead — require `min` at
+ *      the pinned block AND at `pinned - expiryWindow`, which forces two wallets to have held
+ *      the balance simultaneously. Tracked in issue #28.
+ *
+ * Both exclusions are pinned by tests: the amplification each one permits in
+ * `src/crdt/amplification.test.ts`, the absence from this map in `rules.test.ts`.
  */
 export declare const builtinRegistry: RuleRegistry;
 /** type ids the v1 implementation guarantees; checked against `requires.rules`. */
-export declare const V1_BUILTIN_RULE_TYPES: readonly ["erc721-min-balance", "constant"];
+export declare const V1_BUILTIN_RULE_TYPES: readonly ["erc5192-min-balance", "constant"];
 /**
  * Merge host overrides over the built-ins. Overrides shadow built-ins by `type`. The
  * override map is a plain `RuleRegistry` (a flat record already allows any subset

package/dist/rules/registry.js

@@ -1,5 +1,5 @@
 import { UnknownRuleError } from "../errors.js";
-import { erc721MinBalance } from "./erc721-min-balance.js";
+import { erc5192MinBalance } from "./erc5192-min-balance.js";
 import { constant } from "./constant.js";
 /**
  * The rule registry: builtins, the shadowing resolver, and criteria validation.
@@ -15,18 +15,41 @@ import { constant } from "./constant.js";
 /**
  * The library's built-in rules, before any host override.
  *
- * v1 ships exactly the NFT path: `erc721-min-balance` (Pass gate) + `constant` weight.
- * `erc20-balance` is intentionally NOT registered — it stays in the tree (`erc20-balance.ts`,
- * unit-tested) as the design-open weight path, but is unshipped so a criteria naming it
- * recuses via `UnknownRuleError` rather than silently enabling token-weighting. See
- * ROADMAP.md ("Deferred") for when it re-ships.
+ * v1 ships exactly the soulbound-NFT path: `erc5192-min-balance` (Pass gate) + `constant`
+ * weight. TWO chain-reading rules stay in the tree and unit-tested (only `erc721-min-balance` is
+ * re-exported from `src/index.ts`) but deliberately OUT of this map, so a criteria naming either
+ * recuses via `UnknownRuleError` instead of silently gating on an asset that does not bound
+ * Sybils. A host that wants one anyway can still register it through the override map below —
+ * the library declines to bless the configuration, it does not forbid it.
+ *
+ * **`erc721-min-balance`** — a bare `balanceOf` on a *transferable* token. The gate bounds
+ * Sybils only because the asset cannot move (DESIGN.md "Does one Pass mean one vote?"): every
+ * bundle is verified at its OWN pinned block, stays live for `voteExpiryBuckets`, and the
+ * winner set is LWW-keyed per wallet, so one token walked A → B → C inside a single expiry
+ * window backs three concurrent live votes — each read true at its own block, none collapsed by
+ * LWW, and not one of them individually invalid. `erc5192-min-balance` is the same rule plus an
+ * on-chain assertion that the contract declares its tokens locked (issue #27).
+ *
+ * **`erc20-balance`** — the same amplification, reopened by fungibility, plus a second blocker.
+ * Both must resolve before it re-ships:
+ *
+ *   1. the weight path is design-open — a balance-derived weight derives its magnitude from
+ *      the chain read, so it carries no free wire-side ceiling for the lazy tally (see
+ *      `RuleResult` in types.ts, ROADMAP.md "Deferred");
+ *   2. the ERC-5192 fix does not transfer to fungibles: a balance can be neither soulbound nor
+ *      LWW-keyed by token id. Closing it needs a hold-duration guard instead — require `min` at
+ *      the pinned block AND at `pinned - expiryWindow`, which forces two wallets to have held
+ *      the balance simultaneously. Tracked in issue #28.
+ *
+ * Both exclusions are pinned by tests: the amplification each one permits in
+ * `src/crdt/amplification.test.ts`, the absence from this map in `rules.test.ts`.
  */
 export const builtinRegistry = {
-    [erc721MinBalance.type]: erc721MinBalance,
+    [erc5192MinBalance.type]: erc5192MinBalance,
     [constant.type]: constant
 };
 /** type ids the v1 implementation guarantees; checked against `requires.rules`. */
-export const V1_BUILTIN_RULE_TYPES = ["erc721-min-balance", "constant"];
+export const V1_BUILTIN_RULE_TYPES = ["erc5192-min-balance", "constant"];
 /**
  * Merge host overrides over the built-ins. Overrides shadow built-ins by `type`. The
  * override map is a plain `RuleRegistry` (a flat record already allows any subset

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bitsocial/pubsub-voting",
-  "version": "0.1.6",
+  "version": "0.2.0",
   "description": "Trustless pubsub voting over a shared libp2p/Helia node.",
   "type": "module",
   "license": "GPL-3.0-or-later",