@bitsocial/pubsub-voting 0.2.0 → 0.3.0

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

@@ -5,19 +5,27 @@ import { balanceOf, balancesOfBatched, canBatch, scoreOf } from "./nft-balance.j
 /**
  * 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,163 @@ 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/";
+/** 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: [] };
+    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) };
+    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()) };
+        }
+    });
+    return { scores: values.map((balance) => scoreOf(BigInt(balance), min)) };
+}
 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 result: neither leg makes a `0n` 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.
+     */
+    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 } = 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];
+            });
+        }));
+        return { results: scores.map((score) => ({ score, penalize: false })) };
     }
 };

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

@@ -31,18 +31,43 @@ export const Erc721MinBalanceOptionsSchema = z.object({
 export const erc721MinBalance = {
     type: "erc721-min-balance",
     optionsSchema: Erc721MinBalanceOptionsSchema,
-    async evaluate({ options, walletAddress, ctx }) {
-        const balance = await balanceOf(getAddress(options.contract), walletAddress, ctx);
+    // 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 { score: scoreOf(balance, options.min) };
     },
-    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 scores = 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) => {
+                scores[at] = scoreOf(balances[i], options.min);
+            });
+        }));
+        return { results: scores.map((score) => ({ score })) };
     }
 };

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

@@ -6,12 +6,23 @@ export declare function scoreOf(balance: bigint, min: number): bigint;
  * 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 +31,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[];
+}>;

package/dist/rules/nft-balance.js

@@ -33,22 +33,24 @@ export function scoreOf(balance, min) {
  * 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);
+export function canBatch(args) {
+    const { ctx } = args;
+    return { batchable: 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,
+/** One wallet's `balanceOf` at `block` (the caller's choice — a pinned block or the head). */
+export async function balanceOf(args) {
+    const balance = await args.ctx.chain.readContract({
+        address: args.contract,
         abi: erc721Abi,
         functionName: "balanceOf",
-        args: [getAddress(walletAddress)],
-        blockNumber: BigInt(ctx.blockNumber)
+        args: [getAddress(args.wallet)],
+        blockNumber: BigInt(args.block)
     });
+    return { balance };
 }
 /**
- * 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
@@ -57,7 +59,8 @@ export function balanceOf(contract, walletAddress, ctx) {
  * 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) {
+export async function balancesOfBatched(args) {
+    const { contract, wallets: walletAddresses, block, ctx } = args;
     const chunks = [];
     for (let at = 0; at < walletAddresses.length; at += READS_PER_MULTICALL) {
         chunks.push(walletAddresses.slice(at, at + READS_PER_MULTICALL));
@@ -72,7 +75,7 @@ export async function balancesOfBatched(contract, walletAddresses, ctx) {
         })),
         allowFailure: false,
         batchSize: 0,
-        blockNumber: BigInt(ctx.blockNumber)
+        blockNumber: BigInt(block)
     });
     let nextChunk = 0;
     const worker = async () => {
@@ -93,5 +96,5 @@ export async function balancesOfBatched(contract, walletAddresses, ctx) {
         }
     };
     await Promise.all(Array.from({ length: Math.min(MULTICALL_CONCURRENCY, chunks.length) }, worker));
-    return balances;
+    return { balances };
 }

package/dist/rules/types.d.ts

@@ -1,10 +1,13 @@
 import type { z } from "zod";
 import type { ChainClient } from "../chain/types.js";
+import type { RuleCache } from "./cache.js";
 /**
  * Rule interface, design + leaves implemented.
  *
  * A rule turns a criteria `{ type, ...options }` reference into a non-negative
- * score for one wallet, evaluated at the bundle's bucket block. There is a SINGLE kind
+ * score for one wallet, at whichever block the rule itself decides to read — the pinned block
+ * the bundle names ({@link RuleWallet.sampleBlock}) or this verifier's current head
+ * ({@link ChainReadContext.head}). There is a SINGLE kind
  * (mirroring the flat pkc-js challenge registry: `Record<string, rule>`, user
  * entries shadow builtins). The criteria still has two slots that draw from this one
  * registry:
@@ -27,17 +30,74 @@ import type { ChainClient } from "../chain/types.js";
  */
 export interface RuleResult {
     score: bigint;
+    /**
+     * May a `0n` be blamed on the sender? Default `true`.
+     *
+     * The pipeline has two decisions to make about a `0n` that the rule cannot make for it —
+     * whether the gossip forward-gate `reject`s the message (which penalizes the delivering peer
+     * through gossipsub's invalid-message score, eventually pruning and graylisting it) or
+     * merely `ignore`s it, and whether the background verifier evicts the bundle at once or
+     * holds it for a grace window. Both hinge on one thing only the rule knows: is this `0n`
+     * attributable?
+     *
+     * `true` (the default) says every honest verifier necessarily computes this same `0n` — true
+     * of a read pinned to a historical block, since the block is named by the bundle and the
+     * chain's history does not move. The bundle is dropped, the sender penalized, the verdict
+     * cached as terminal.
+     *
+     * `false` says an honest peer could legitimately disagree, so nobody may be blamed. The
+     * bundle is still dropped, but `ignore`-class — no penalty, verdict uncached, and the
+     * background verifier re-examines it for a grace window before giving up. This is what a
+     * rule scoring the chain head must return: the peer that forwarded the vote verified it
+     * against ITS head, and any peer ahead of us can legitimately see an acquisition we have
+     * not. Penalizing there punishes honest relayers for being current — and does so exactly
+     * when a wallet has just acquired the gate asset, which is when peer heads straddle.
+     */
+    penalize?: boolean;
 }
-/** Everything a rule needs to read chain state for one evaluation. */
+/** Everything a rule needs to read chain state and remember what it read. */
 export interface ChainReadContext {
     /**
-     * The viem `PublicClient` for the rule's `options.chain`. Use the full viem
-     * read surface directly (`readContract`, `getBalance`, ...), pinning every call to
-     * the sampled block with `blockNumber: BigInt(ctx.blockNumber)`.
+     * The viem `PublicClient` for the rule's `options.chain`. Use the full viem read surface
+     * directly (`readContract`, `getBalance`, ...). ALWAYS pin each call to an explicit
+     * `blockNumber: BigInt(...)`: the read coalescer (src/chain/coalescer.ts) only folds reads
+     * carrying an explicit block into one multicall3, so a `blockTag` or an omitted block
+     * silently drops out of batching and back to one HTTP round trip per read.
      */
     chain: ChainClient;
-    /** The single sampled block for the bundle's bucket. */
-    blockNumber: number;
+    /**
+     * This verifier's current head on {@link chain}. A rule scoring historical state never calls
+     * it and never pays for it; a rule scoring "now" resolves it ONCE per evaluation and pins
+     * its reads to that number, so a batch still lands in a single multicall.
+     *
+     * Shared and coalesced by the voter, because the gate runs on the verify path — one call per
+     * incoming vote — so an unshared head read would be one `eth_blockNumber` per bundle per
+     * contest.
+     */
+    head: () => Promise<{
+        block: number;
+    }>;
+    /**
+     * This rule's memo (see rules/cache.ts). A chain-reading rule MUST compute through it: it is
+     * what turns "one chain read per unique bundle" into "one read per key per epoch", which is
+     * the bound that stops an ineligible wallet from making every peer on the topic pay an RPC
+     * round trip per fresh-signed bundle.
+     */
+    cache: RuleCache;
+}
+/** One wallet to score, and the pinned block the bundle it came from names. */
+export interface RuleWallet {
+    /** The voting wallet (the address recovered from the bundle's signature). */
+    address: string;
+    /**
+     * The bundle's bucketized sample block, already floored to the bucket boundary — the
+     * historical block every verifier agrees this ballot names. A rule scoring pinned state
+     * reads here (and its answer is then identical on every verifier, forever); a rule scoring
+     * current state ignores it and uses {@link ChainReadContext.head} instead. It is NOT a
+     * claim about when the ballot was signed: it is floored to the bucket, so it can trail the
+     * actual signing moment by up to `blocksPerBucket`.
+     */
+    sampleBlock: number;
 }
 /**
  * The one rule kind. `O` is the validated options type (from its `optionsSchema`).
@@ -49,22 +109,28 @@ export interface Rule<O = unknown> {
     readonly optionsSchema: z.ZodType<O>;
     evaluate(args: {
         options: O;
-        walletAddress: string;
+        wallet: RuleWallet;
         ctx: ChainReadContext;
     }): Promise<RuleResult>;
     /**
-     * Optional batched form of {@link evaluate}: score many wallets at the SAME sampled block in
-     * as few RPC round trips as the rule can manage (e.g. one multicall3 `aggregate3` for a whole
-     * checkpoint's wallets). Returns one result per input wallet, in order. Semantics MUST equal
-     * mapping `evaluate` over the wallets — this is a transport optimization, never a different
-     * answer. The background chain verifier prefers it when present and falls back to per-wallet
-     * `evaluate` calls otherwise (see verify/background.ts).
+     * Optional batched form of {@link evaluate}: score many wallets in as few RPC round trips as
+     * the rule can manage (e.g. one multicall3 `aggregate3` for a whole checkpoint's wallets).
+     * Returns one result per input wallet, in order. Semantics MUST equal mapping `evaluate` over
+     * the wallets — this is a transport optimization, never a different answer. The background
+     * chain verifier prefers it when present and falls back to per-wallet `evaluate` otherwise.
+     *
+     * The wallets are NOT guaranteed to share a `sampleBlock`: the pipeline no longer groups them
+     * (it cannot, since which block a rule reads at is the rule's own business), so a batch is
+     * whatever was pending. A rule scoring the head reads once for the whole batch; a rule
+     * scoring pinned state groups by `sampleBlock` itself.
      */
     evaluateMany?(args: {
         options: O;
-        walletAddresses: string[];
+        wallets: RuleWallet[];
         ctx: ChainReadContext;
-    }): Promise<RuleResult[]>;
+    }): Promise<{
+        results: RuleResult[];
+    }>;
 }
 /**
  * The registry: a flat `type -> rule` map. Built-ins are provided by this

package/dist/tally/tally.d.ts

@@ -3,6 +3,7 @@ import type { VotesBundle } from "../schema/votes.js";
 import type { RuleRegistry } from "../rules/types.js";
 import type { ChainClient, BucketMath } from "../chain/types.js";
 import type { BundleChecks } from "../verify/types.js";
+import { type RuleCache } from "../rules/cache.js";
 import type { Tally } from "./types.js";
 /**
  * Deterministic per-contest aggregation over the CRDT's current bundles. Every aggregated
@@ -34,6 +35,19 @@ export interface TallyDeps {
         bundle: VotesBundle;
         checks: BundleChecks;
     }>;
+    /**
+     * This verifier's current head, handed to the weight rule as `ctx.head`. Never called by a
+     * weight rule that scores pinned historical state — including `constant`, which reads no
+     * chain at all — so the "an idle contest does zero chain reads" property is untouched.
+     * Defaults to the weight chain's own `getBlockNumber()`.
+     */
+    readHead?: (args: {
+        chain: ChainClient;
+    }) => Promise<{
+        block: number;
+    }>;
+    /** The weight rule's memo, handed to it as `ctx.cache` (rules/cache.ts). */
+    ruleCache?: RuleCache;
     /**
      * Hash of the current bucket boundary block on the criteria's chain, for the rolling tie
      * seed. Invoked at most once per `compute`, and only when a tie must actually be broken —

package/dist/tally/tally.js

@@ -1,6 +1,7 @@
 import { base58btc } from "multiformats/bases/base58";
 import { sha256 } from "multiformats/hashes/sha2";
 import { tickerForRef } from "../chain/ticker.js";
+import { makeMemoryRuleCache } from "../rules/cache.js";
 import { UnknownRuleError } from "../errors.js";
 /** Byte-lexicographic compare of two byte arrays (returns <0, 0, >0). */
 function compareBytes(x, y) {
@@ -15,18 +16,31 @@ function compareBytes(x, y) {
 }
 export function makeTally(deps) {
     const { criteria, registry, chainFor, bucketMath, current, bucketBlockHash } = deps;
+    const readHead = deps.readHead ?? (async ({ chain }) => ({ block: Number(await chain.getBlockNumber()) }));
     // Resolve the weight rule, its options, and its chain once (see verify/bundle.ts).
     const weight = registry[criteria.weight.type];
     if (!weight)
         throw new UnknownRuleError("weight", criteria.weight.type);
     const weightOptions = weight.optionsSchema.parse(criteria.weight);
     const weightChain = chainFor(tickerForRef(criteria, criteria.weight, weightOptions));
+    // The weight rule picks its own block exactly as the gate rule does (see rules/types.ts):
+    // it is handed the bundle's pinned sample block and this verifier's head, and reads whichever
+    // it needs. The tally never asks what kind of rule it is holding.
+    //
+    // `deps.ruleCache` MUST be namespaced by the weight rule's OWN chain, not the gating chain —
+    // `weightChain` here resolves through `criteria.weight`'s ticker, which may name a different
+    // entry of `requires.chains` (the voter derives it that way; see client/voter.ts).
+    const weightCtx = {
+        chain: weightChain,
+        head: () => readHead({ chain: weightChain }),
+        cache: deps.ruleCache ?? makeMemoryRuleCache()
+    };
     const weightFor = async (wallet, blockNumber) => {
         const sampleBlock = bucketMath.sampleBlockForBucket(bucketMath.bucketForBlock(blockNumber));
         const { score } = await weight.evaluate({
             options: weightOptions,
-            walletAddress: wallet,
-            ctx: { chain: weightChain, blockNumber: sampleBlock }
+            wallet: { address: wallet, sampleBlock },
+            ctx: weightCtx
         });
         return score;
     };