@bitsocial/pubsub-voting 0.2.1 → 0.4.0

package/dist/rules/cache.js

@@ -0,0 +1,160 @@
+/** `${key}:${epoch}` — the epoch trails, so a purge can parse it back off the end. */
+const entryKey = (key, epoch) => `${key}:${epoch}`;
+/**
+ * An in-memory {@link RuleCache}, FIFO-bounded. Used on its own by unit tests and as the hot
+ * front of the persistent cache. Eviction is safe: an evicted entry costs a re-read, never a
+ * wrong answer — and without a bound, a flood of fresh wallets would be a memory-exhaustion
+ * vector (DESIGN.md "Can valid votes clog the topic?").
+ */
+export function makeMemoryRuleCache(args = {}) {
+    const maxEntries = args.maxEntries ?? 4096;
+    const byKey = new Map();
+    const order = [];
+    const cache = {
+        async get({ key, epoch }) {
+            return { value: byKey.get(entryKey(key, epoch)) };
+        },
+        set({ key, epoch, value }) {
+            const k = entryKey(key, epoch);
+            if (byKey.has(k))
+                return; // idempotent: never refresh position or overwrite
+            byKey.set(k, value);
+            order.push(k);
+            if (order.length > maxEntries) {
+                const evicted = order.shift();
+                if (evicted !== undefined)
+                    byKey.delete(evicted);
+            }
+        },
+        memoMany: (memoArgs) => memoManyOver(cache, memoArgs),
+        purgeBelow({ epoch, keyPrefix }) {
+            for (const k of [...byKey.keys()]) {
+                if (keyPrefix !== undefined && !k.startsWith(keyPrefix))
+                    continue;
+                const at = Number(k.slice(k.lastIndexOf(":") + 1));
+                if (Number.isFinite(at) && at < epoch) {
+                    byKey.delete(k);
+                    const i = order.indexOf(k);
+                    if (i >= 0)
+                        order.splice(i, 1);
+                }
+            }
+        }
+    };
+    return cache;
+}
+/**
+ * A {@link RuleCache} over the voter's persistent store: the in-memory FIFO front above, with
+ * read-through on a miss and fire-and-forget write-through. A broken store read or write
+ * degrades to a live chain read — never an error into the verify pipeline.
+ *
+ * `namespace` is the rule's keyspace (see {@link RuleCache}); the voter derives it from the
+ * canonical rule reference + chain id.
+ */
+export function makePersistentRuleCache(args) {
+    const { store, namespace } = args;
+    const mem = makeMemoryRuleCache(args.maxMemEntries === undefined ? {} : { maxEntries: args.maxMemEntries });
+    const storeKey = (key, epoch) => `${namespace}:${entryKey(key, epoch)}`;
+    /** The highest epoch already purged per prefix, so a steady head costs no key scan. */
+    const purged = new Map();
+    const cache = {
+        async get({ key, epoch }) {
+            const hit = await mem.get({ key, epoch });
+            if (hit.value !== undefined)
+                return hit;
+            let persisted;
+            try {
+                persisted = await store.getItem(storeKey(key, epoch));
+            }
+            catch {
+                return { value: undefined };
+            }
+            if (typeof persisted !== "string")
+                return { value: undefined };
+            mem.set({ key, epoch, value: persisted });
+            return { value: persisted };
+        },
+        set({ key, epoch, value }) {
+            mem.set({ key, epoch, value });
+            void store.setItem(storeKey(key, epoch), value).catch(() => {
+                // a failed persist costs a future re-read, never a wrong answer
+            });
+        },
+        memoMany: (memoArgs) => memoManyOver(cache, memoArgs),
+        purgeBelow({ epoch, keyPrefix }) {
+            const prefix = `${namespace}:${keyPrefix ?? ""}`;
+            if ((purged.get(prefix) ?? 0) >= epoch)
+                return;
+            purged.set(prefix, epoch);
+            mem.purgeBelow(keyPrefix === undefined ? { epoch } : { epoch, keyPrefix });
+            void (async () => {
+                try {
+                    for (const key of await store.keys()) {
+                        if (!key.startsWith(prefix))
+                            continue;
+                        const at = Number(key.slice(key.lastIndexOf(":") + 1));
+                        if (Number.isFinite(at) && at < epoch)
+                            await store.removeItem(key);
+                    }
+                }
+                catch {
+                    // purge is best-effort; the store's LRU bound is the correctness-free backstop
+                }
+            })();
+        }
+    };
+    return cache;
+}
+/**
+ * The shared {@link RuleCache.memoMany} body: read the misses once, in order, then memoize.
+ *
+ * The lookups are issued CONCURRENTLY, not one at a time. In the persistent cache a miss on the
+ * in-memory front falls through to a store round trip, so awaiting each key in turn would cost a
+ * cold join one serial store hit per wallet before its single batched chain read even starts —
+ * exactly the shape of the first `memoMany` after a restart, when the front is empty by
+ * definition. Order is preserved explicitly instead of by loop sequencing.
+ */
+async function memoManyOver(cache, args) {
+    const { keys, epoch, read } = args;
+    const values = new Array(keys.length);
+    const missing = [];
+    const missingAt = [];
+    // Unique keys first, each remembering every position it occupies, so a duplicate key is
+    // looked up once and read once.
+    const positions = new Map();
+    for (let i = 0; i < keys.length; i++) {
+        const key = keys[i];
+        const at = positions.get(key);
+        if (at)
+            at.push(i);
+        else
+            positions.set(key, [i]);
+    }
+    const unique = [...positions.keys()];
+    const hits = await Promise.all(unique.map((key) => cache.get({ key, epoch })));
+    for (let u = 0; u < unique.length; u++) {
+        const key = unique[u];
+        const at = positions.get(key);
+        const { value } = hits[u];
+        if (value !== undefined) {
+            for (const i of at)
+                values[i] = value;
+            continue;
+        }
+        missingAt.push(at);
+        missing.push(key);
+    }
+    if (missing.length > 0) {
+        const read_ = await read({ keys: missing });
+        if (read_.values.length !== missing.length) {
+            throw new Error(`RuleCache.memoMany: read returned ${read_.values.length} values for ${missing.length} keys`);
+        }
+        missing.forEach((key, i) => {
+            const value = read_.values[i];
+            cache.set({ key, epoch, value });
+            for (const at of missingAt[i])
+                values[at] = value;
+        });
+    }
+    return { values: values.map((value) => value) };
+}

package/dist/rules/constant.js

@@ -13,6 +13,8 @@ export const constant = {
     type: "constant",
     optionsSchema: ConstantOptionsSchema,
     async evaluate({ options }) {
-        return { score: BigInt(options.value) };
+        // `value` is schema-constrained positive, so this rule has no failing branch at all —
+        // in the rule slot it is the no-op gate that admits everyone.
+        return { success: true, score: BigInt(options.value) };
     }
 };

package/dist/rules/erc20-balance.js

@@ -1,4 +1,4 @@
-import { erc20Abi, getAddress, parseUnits } from "viem";
+import { erc20Abi, formatUnits, getAddress, parseUnits } from "viem";
 import { z } from "zod";
 import { ChainTickerSchema } from "../schema/common.js";
 /**
@@ -37,15 +37,25 @@ export const Erc20BalanceOptionsSchema = z.object({
 export const erc20Balance = {
     type: "erc20-balance",
     optionsSchema: Erc20BalanceOptionsSchema,
-    async evaluate({ options, walletAddress, ctx }) {
+    // Scores at the bundle's OWN pinned block: a fungible balance is the least stable score
+    // there is — it moves in both directions with every transfer — so it may not be read at the
+    // head, and a `0n` here is attributable (`penalize` stays at its default). See registry.ts
+    // for why this rule is unregistered regardless.
+    async evaluate({ options, wallet, ctx }) {
         const raw = await ctx.chain.readContract({
             address: getAddress(options.contract),
             abi: erc20Abi,
             functionName: "balanceOf",
-            args: [getAddress(walletAddress)],
-            blockNumber: BigInt(ctx.blockNumber)
+            args: [getAddress(wallet.address)],
+            blockNumber: BigInt(wallet.sampleBlock)
         });
         const minUnits = parseUnits(options.min.toString(), options.decimals);
-        return { score: raw >= minUnits ? raw : 0n };
+        if (raw >= minUnits)
+            return { success: true, score: raw };
+        return {
+            success: false,
+            error: `this wallet holds ${formatUnits(raw, options.decimals)} of the gate token ` +
+                `(${getAddress(options.contract)}), but ${options.min} is required`
+        };
     }
 };

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

@@ -3,19 +3,27 @@ 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
+ * Same `balanceOf` scoring as `erc721-min-balance` — the wallet's holding at the sampled block
+ * if it meets `min`, else `0n` — plus one assertion at the SAME 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.
  *
+ * Unlike the other rules in the tree, this one scores at the verifier's CURRENT head rather than
+ * at the bundle's bucket boundary, falling back to that boundary only when the head read refuses
+ * — so a freshly-acquired Pass counts immediately. See `evaluateMany` for why both legs exist,
+ * and rules/types.ts for what the pipeline does with `penalize: false`.
+ *
  * **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`.
+ * cannot move (DESIGN.md "Does one Pass mean one vote?"). A vote is verified ONCE, when it is
+ * merged, and then stays live for `voteExpiryBuckets` in a winner set 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 when it was checked and none collapsed by LWW. Nothing in the
+ * verify pipeline can see that: every ballot is individually correct. (Reading pinned blocks,
+ * the three reads land at three different historical blocks; reading the head, at three
+ * different verification times. Transferability defeats both.) Requiring the asset to be
+ * non-transferable AND to say so on-chain closes it with no wire change — and it is the same
+ * property that makes scoring at the head sound at all. 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

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

@@ -1,23 +1,31 @@
 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";
+import { balanceOf, balancesOfBatched, canBatch, scoreOf, shortfallError } 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
+ * Same `balanceOf` scoring as `erc721-min-balance` — the wallet's holding at the sampled block
+ * if it meets `min`, else `0n` — plus one assertion at the SAME 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.
  *
+ * Unlike the other rules in the tree, this one scores at the verifier's CURRENT head rather than
+ * at the bundle's bucket boundary, falling back to that boundary only when the head read refuses
+ * — so a freshly-acquired Pass counts immediately. See `evaluateMany` for why both legs exist,
+ * and rules/types.ts for what the pipeline does with `penalize: false`.
+ *
  * **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`.
+ * cannot move (DESIGN.md "Does one Pass mean one vote?"). A vote is verified ONCE, when it is
+ * merged, and then stays live for `voteExpiryBuckets` in a winner set 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 when it was checked and none collapsed by LWW. Nothing in the
+ * verify pipeline can see that: every ballot is individually correct. (Reading pinned blocks,
+ * the three reads land at three different historical blocks; reading the head, at three
+ * different verification times. Transferability defeats both.) Requiring the asset to be
+ * non-transferable AND to say so on-chain closes it with no wire change — and it is the same
+ * property that makes scoring at the head sound at all. 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
@@ -63,49 +71,195 @@ function isContractRefusal(err) {
     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.
+ * How coarsely a head-scored read is memoized, in blocks (~1 minute on Base's 2 s blocks).
+ *
+ * The read itself is at the freshest head this verifier has — that is the whole point, a Pass
+ * acquired seconds ago must count now. Only the cache EPOCH is quantized, and it has to be:
+ * an epoch that moved every block would never hit, and the memo is what stops an ineligible
+ * wallet from costing every peer one chain read per fresh-signed bundle (see rules/cache.ts).
+ *
+ * The number to reason about is what a stale NEGATIVE costs: a wallet already checked and failed
+ * stays failed on this verifier until the epoch rolls, even if it acquires the Pass in between —
+ * so it is deliberately short. A positive is unaffected in practice (a holding that cannot move
+ * cannot stop being true), and re-reading one when the epoch rolls is a wasted read, never a
+ * wrong answer. Local resource policy, NOT consensus: two peers may quantize differently and
+ * still agree on every verdict, which is why it lives here and not in the criteria.
  */
-async function declaresErc5192(contract, ctx) {
+const HEAD_EPOCH_BLOCKS = 30;
+/** Cache-key prefixes: head-scored entries expire with the head, pinned ones never do. */
+const HEAD_PREFIX = "head/";
+const PINNED_PREFIX = "pin/";
+/**
+ * The voter-facing wording for every way this rule reaches `0n` ({@link RuleResult.error}).
+ *
+ * Deliberately generic and self-contained: the rule knows a contract address and a threshold, not
+ * that the deployment calls this token a "5chan Pass". A client renders these verbatim, which is
+ * the point — it then needs to know nothing about which block the rule read or what `min` is.
+ */
+const undeclaredError = (contract) => `the gate contract ${contract} does not declare ERC-5192, so it gates nothing and no wallet can qualify ` +
+    `— this contest's criteria name a contract that is not soulbound`;
+/** One `supportsInterface(0xb45a3c0e)` at `block`. Revert/zero-data ⇒ "does not declare". */
+async function declaresErc5192(args) {
     try {
-        return await ctx.chain.readContract({
-            address: contract,
+        const declares = await args.ctx.chain.readContract({
+            address: args.contract,
             abi: erc165Abi,
             functionName: "supportsInterface",
             args: [ERC5192_INTERFACE_ID],
-            blockNumber: BigInt(ctx.blockNumber)
+            blockNumber: BigInt(args.block)
         });
+        return { declares };
     }
     catch (err) {
         if (isContractRefusal(err))
-            return false;
+            return { declares: false };
         throw err;
     }
 }
+/**
+ * Score every wallet at ONE block, memoized under one epoch — the whole rule body, run once per
+ * leg (see `evaluateMany`).
+ *
+ * Two memos, both through the rule's cache: the ERC-5192 declaration, keyed per CONTRACT (it is
+ * not a per-wallet fact, so a whole checkpoint's wallets share one probe — a key shape the old
+ * per-wallet gate cache could not express at all), and each wallet's raw balance. Balances are
+ * cached rather than scores so a change to `min` cannot be served a stale verdict; the batched
+ * read behind the misses is one multicall3 `aggregate3` per 200 wallets.
+ */
+async function scoreAt(args) {
+    const { contract, min, wallets, block, epoch, prefix, ctx } = args;
+    if (wallets.length === 0)
+        return { scores: [], errors: [] };
+    const [declared] = (await ctx.cache.memoMany({
+        keys: [`${prefix}lock/${contract.toLowerCase()}`],
+        epoch,
+        read: async () => {
+            const { declares } = await declaresErc5192({ contract, block, ctx });
+            return { values: [declares ? "1" : "0"] };
+        }
+    })).values;
+    // A contract that does not claim its tokens are locked gates nothing: admit nobody rather
+    // than gate on something transferable (see the rule doc above).
+    if (declared !== "1")
+        return { scores: wallets.map(() => 0n), errors: wallets.map(() => undeclaredError(contract)) };
+    const { values } = await ctx.cache.memoMany({
+        keys: wallets.map((wallet) => `${prefix}bal/${wallet.toLowerCase()}`),
+        epoch,
+        read: async ({ keys }) => {
+            const missing = keys.map((key) => key.slice(key.lastIndexOf("/") + 1));
+            const { balances } = canBatch({ ctx }).batchable
+                ? await balancesOfBatched({ contract, wallets: missing, block, ctx })
+                : {
+                    balances: await Promise.all(missing.map(async (wallet) => (await balanceOf({ contract, wallet, block, ctx })).balance))
+                };
+            return { values: balances.map((balance) => balance.toString()) };
+        }
+    });
+    const scores = values.map((balance) => scoreOf(BigInt(balance), min));
+    return {
+        scores,
+        errors: scores.map((score, i) => (score > 0n ? undefined : shortfallError(BigInt(values[i]), min, contract)))
+    };
+}
+/** `{ success: true, score }` when the leg admitted, else the failing branch with its reason. */
+function resultOf(score, error) {
+    // `penalize: false` on every failure: neither leg makes one attributable. The peer that
+    // forwarded a vote verified it against ITS head, and any peer ahead of us may legitimately
+    // see an acquisition we have not — and with burning possible, holding at neither block does
+    // not even prove the wallet never held.
+    return score > 0n ? { success: true, score } : { success: false, error: error ?? UNKNOWN_ERROR, penalize: false };
+}
+/** Unreachable: `scoreAt` pairs every non-positive score with a reason. Kept total, not thrown. */
+const UNKNOWN_ERROR = "this wallet does not qualify for this contest's gate";
 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 };
+    // One wallet is the batch of one: the two legs, the two epochs and the memos are identical,
+    // so there is one body. Called through `erc5192MinBalance.evaluateMany` rather than `this`,
+    // which a destructured or re-exported rule object would not carry (issue #29).
+    async evaluate({ options, wallet, ctx }) {
+        const { results } = await erc5192MinBalance.evaluateMany({ options, wallets: [wallet], ctx });
+        return results[0];
     },
-    async evaluateMany({ options, walletAddresses, ctx }) {
+    /**
+     * Score at the HEAD first, falling back to each wallet's own pinned block.
+     *
+     * **Head first** is what lets a wallet vote in the block it acquires the Pass. Scoring only
+     * at the bundle's bucket boundary — the block a ballot names, floored — meant waiting up to
+     * a full bucket (an hour on 5chan's live manifest) before a fresh holding was visible, which
+     * was never a chain requirement: a read pinned at block N already sees a mint that happened
+     * in N. It is sound because a soulbound holding cannot move, so a peer whose head lags can
+     * only be LATE to admit a vote, never in lasting disagreement about it.
+     *
+     * **The pinned fallback** covers what that reasoning does not: ERC-5192 requires transfers to
+     * revert while locked, but says nothing about BURNING (a burn does not go through
+     * `transferFrom`), so a compliant Pass may be burnable and this rule cannot check otherwise.
+     * Without the fallback, a burn would make a peer that verified earlier keep a vote its
+     * checkpoint still serves while a cold joiner rejects it — divergence for up to the expiry
+     * window — and would hand whoever can burn a retroactive veto over votes already cast.
+     * Reading the wallet's own `sampleBlock` when the head says `0n` restores agreement for any
+     * vote that was legitimately held when it was cast. It admits nothing the pinned-only v1 gate
+     * did not, so it opens no new amplification; a burn-and-remint to a fresh wallet is a
+     * transfer by another name and remains a property of the deployment, not something any read
+     * can close. Its cost is that a verifier still needs archive depth for that leg.
+     *
+     * **Two epochs**, which is why this caching lives in the rule: the head leg expires with the
+     * head (a stale `0n` must not outlive {@link HEAD_EPOCH_BLOCKS}), while the pinned leg is a
+     * historical read that is true forever and is keyed by the block itself.
+     *
+     * **`penalize: false`** on every failure: neither leg makes one attributable. The peer that
+     * forwarded a vote verified it against ITS head, and any peer ahead of us may legitimately
+     * see an acquisition we have not — and with burning possible, not holding at either block
+     * does not even prove the wallet never held.
+     *
+     * **Three distinct failures**, each with its own {@link RuleResult.error}: the contract does
+     * not declare ERC-5192 (so it gates nothing and no wallet can ever qualify), the wallet holds
+     * none, or it holds some but fewer than `min`. The fallback leg has the last word on a
+     * wallet's score, so it owns that wallet's reason too.
+     */
+    async evaluateMany({ options, wallets, 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) }));
+        const { block: head } = await ctx.head();
+        const epoch = Math.floor(head / HEAD_EPOCH_BLOCKS) * HEAD_EPOCH_BLOCKS;
+        // Everything behind the current window is unreachable — nothing will look it up again.
+        // Scoped to the head keys, so the permanently-valid pinned entries are left alone.
+        ctx.cache.purgeBelow({ epoch, keyPrefix: HEAD_PREFIX });
+        const { scores, errors } = await scoreAt({
+            contract,
+            min: options.min,
+            wallets: wallets.map((wallet) => wallet.address),
+            block: head,
+            epoch,
+            prefix: HEAD_PREFIX,
+            ctx
+        });
+        // Only wallets the head leg refused reach the fallback, so a holder costs one read path.
+        // Grouped by sample block: bundles from different buckets name different pinned blocks.
+        const byBlock = new Map();
+        scores.forEach((score, i) => {
+            if (score > 0n)
+                return;
+            const block = wallets[i].sampleBlock;
+            byBlock.set(block, [...(byBlock.get(block) ?? []), i]);
+        });
+        await Promise.all([...byBlock].map(async ([block, indexes]) => {
+            const fallback = await scoreAt({
+                contract,
+                min: options.min,
+                wallets: indexes.map((i) => wallets[i].address),
+                block,
+                epoch: block,
+                prefix: PINNED_PREFIX,
+                ctx
+            });
+            indexes.forEach((at, i) => {
+                scores[at] = fallback.scores[i];
+                // The fallback leg had the last word on the score, so it owns the reason too:
+                // a wallet that holds none at the head but held some at its ballot's block is
+                // admitted, and one that holds none at either gets the pinned leg's wording.
+                errors[at] = fallback.errors[i];
+            });
+        }));
+        return { results: scores.map((score, i) => resultOf(score, errors[i])) };
     }
 };

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

@@ -1,7 +1,7 @@
 import { getAddress } from "viem";
 import { z } from "zod";
 import { ChainTickerSchema } from "../schema/common.js";
-import { balanceOf, balancesOfBatched, canBatch, scoreOf } from "./nft-balance.js";
+import { balanceOf, balancesOfBatched, canBatch, scoreOf, shortfallError } from "./nft-balance.js";
 /**
  * Hold at least `min` of a **plain** ERC-721.
  *
@@ -28,21 +28,55 @@ export const Erc721MinBalanceOptionsSchema = z.object({
     contract: z.string(),
     min: z.number().int().positive().default(1)
 });
+/**
+ * One pinned-block balance as a {@link RuleResult}. `penalize` is left at its default `true`:
+ * this rule reads the block the bundle itself names, so every honest verifier computes the same
+ * answer forever and a failure IS attributable to whoever sent it.
+ */
+function pinnedResult(balance, min, contract) {
+    const score = scoreOf(balance, min);
+    return score > 0n ? { success: true, score } : { success: false, error: shortfallError(balance, min, contract) };
+}
 export const erc721MinBalance = {
     type: "erc721-min-balance",
     optionsSchema: Erc721MinBalanceOptionsSchema,
-    async evaluate({ options, walletAddress, ctx }) {
-        const balance = await balanceOf(getAddress(options.contract), walletAddress, ctx);
-        return { score: scoreOf(balance, options.min) };
+    // Scores at the bundle's OWN pinned block, and deliberately not at the head: a transferable
+    // balance can go DOWN, so a vote admitted today would silently become invalid the moment the
+    // token moved, and whether it still counted would depend on when each peer last looked. A
+    // pinned read is identical on every verifier forever, which is what leaves `penalize` at its
+    // default — a `0n` here IS attributable to the sender. That difference is a second,
+    // independent reason this rule stays out of `builtinRegistry`, on top of the Sybil
+    // amplification described in registry.ts.
+    async evaluate({ options, wallet, ctx }) {
+        const { balance } = await balanceOf({
+            contract: getAddress(options.contract),
+            wallet: wallet.address,
+            block: wallet.sampleBlock,
+            ctx
+        });
+        return pinnedResult(balance, options.min, getAddress(options.contract));
     },
-    async evaluateMany({ options, walletAddresses, ctx }) {
+    async evaluateMany({ options, wallets, ctx }) {
         const contract = getAddress(options.contract);
-        // 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) }));
+        // Grouped by sample block, because a batch is no longer guaranteed to share one: the
+        // pipeline hands over whatever is pending and each rule groups the way it reads. Within
+        // a group it is multicall3 `aggregate3` batching (chunking policy in nft-balance.ts) —
+        // the path the background chain verifier rides on a cold join; a client that cannot
+        // batch takes the per-wallet fallback.
+        const results = new Array(wallets.length);
+        const byBlock = new Map();
+        wallets.forEach((wallet, i) => byBlock.set(wallet.sampleBlock, [...(byBlock.get(wallet.sampleBlock) ?? []), i]));
+        await Promise.all([...byBlock].map(async ([block, indexes]) => {
+            const group = indexes.map((i) => wallets[i].address);
+            const { balances } = canBatch({ ctx }).batchable
+                ? await balancesOfBatched({ contract, wallets: group, block, ctx })
+                : {
+                    balances: await Promise.all(group.map(async (wallet) => (await balanceOf({ contract, wallet, block, ctx })).balance))
+                };
+            indexes.forEach((at, i) => {
+                results[at] = pinnedResult(balances[i], options.min, contract);
+            });
+        }));
+        return { results: results.map((result) => result) };
     }
 };

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

@@ -1,17 +1,37 @@
 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;
+/**
+ * The voter-facing wording for a token-count shortfall ({@link RuleResult.error}), shared by
+ * every balance-scored rule so they explain themselves identically.
+ *
+ * Deliberately generic: a rule knows a contract address and a threshold, not that the deployment
+ * calls this token a "5chan Pass". A client renders it verbatim, which is the point — it then
+ * needs to know nothing about which block the rule read or what `min` is.
+ */
+export declare function shortfallError(balance: bigint, min: number, contract: string): string;
 /**
  * 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>;
+export declare function canBatch(args: {
+    ctx: ChainReadContext;
+}): {
+    batchable: boolean;
+};
+/** One wallet's `balanceOf` at `block` (the caller's choice — a pinned block or the head). */
+export declare function balanceOf(args: {
+    contract: `0x${string}`;
+    wallet: string;
+    block: number;
+    ctx: ChainReadContext;
+}): Promise<{
+    balance: 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}.
+ * Many wallets' `balanceOf` at ONE 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
@@ -20,4 +40,11 @@ export declare function balanceOf(contract: `0x${string}`, walletAddress: string
  * 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[]>;
+export declare function balancesOfBatched(args: {
+    contract: `0x${string}`;
+    wallets: string[];
+    block: number;
+    ctx: ChainReadContext;
+}): Promise<{
+    balances: bigint[];
+}>;