@bitsocial/pubsub-voting 0.2.1 → 0.3.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 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).
+- **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, read at the verifier's head so a freshly-acquired Pass votes immediately) 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.
 
@@ -35,7 +35,7 @@ The library never starts a node and never takes a host SDK (there is no `pkc` ar
 | Seam | Type | Required | Purpose |
 |---|---|---|---|
 | `helia` | `HeliaInstance` | yes | the host's running Helia node; must carry a gossipsub service at `libp2p.services.pubsub` (else `MissingPubsubError`), a `blockstore` (else `MissingBlockstoreError`), and a libp2p fetch service at `libp2p.services.fetch` (else `MissingFetchError`) |
-| `chains` | `ChainClientFactory` | yes | resolves each chain a contest's criteria requires (`{ chain, chainId }`) to a viem `PublicClient`; rules read through it for the gate and weight. **RPC endpoints are this client's own settings, never part of the criteria document** — return one shared (memoized) client per chain, pointed at a gateway that serves historical state at least `voteExpiryBuckets × blocksPerBucket` blocks behind head and carries a multicall3 deployment in its viem `chain` config; return `undefined` for a chain with no RPC configured, and `createContest`/`createContestVote` throws `MissingChainClientError` (recuse, don't miscount) |
+| `chains` | `ChainClientFactory` | yes | resolves each chain a contest's criteria requires (`{ chain, chainId }`) to a viem `PublicClient`; rules read through it for the gate and weight. **RPC endpoints are this client's own settings, never part of the criteria document** — return one shared (memoized) client per chain, pointed at a gateway that carries a multicall3 deployment in its viem `chain` config and serves **historical state at least `voteExpiryBuckets × blocksPerBucket` blocks behind head** (the v1 gate reads the head first, but falls back to the block a ballot names — see [Custom rules](#custom-rules)); return `undefined` for a chain with no RPC configured, and `createContest`/`createContestVote` throws `MissingChainClientError` (recuse, don't miscount) |
 | `signer` | `VoteSigner` | no | the voting wallet's address + EIP-712 ballot signing; omit for a read-only voter |
 | `nameResolvers` | `NameResolver[]` | no | community-name resolvers (same interface and instances as pkc-js's `nameResolvers`, e.g. `@bitsocial/bso-resolver` for `name.bso`); each vote's `community.name` claim is verified through them — inline at the forward-gate for live votes, in the background verifier for cold-join admits — and a bundle whose name resolves to a different `publicKey` than claimed is dropped/evicted |
 | `dataPath` | `string \| false` | no | directory for the voter's persistent state (gate-result + name-resolution caches, and each joined contest's **checkpoint snapshot** — its last fully-verified winner-set, reloaded at join so a restart with no other peer online keeps the tally), the pkc-js `dataPath` equivalent. Node default: `{cwd}/.bitsocial-pubsub-voting` (better-sqlite3 under `{dataPath}/lru-storage/` + `{dataPath}/checkpoints.db`); in the browser the path is ignored and everything lives in IndexedDB. Pass `false` for in-memory-only (the pkc-js `noData` equivalent). A restart re-serves settled gate reads and fresh name resolutions from the store instead of the RPC, and restores each contest's checkpoint before the cold-start pull. A seeder should always set a stable path |
@@ -196,13 +196,13 @@ 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 `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)).
+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, its own reads (`readContract`, `getBalance`, ... through `ctx.chain`, the viem `PublicClient` for its `options.chain`), which block it reads at, and what it memoizes — see [What a rule owns](#what-a-rule-owns-its-block-and-its-cache) below. 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, wallets, ctx })` batch hook (`wallets` in place of `wallet`, returning `{ results }` — one per input wallet, in order) — its semantics MUST equal mapping `evaluate` — which the background verifier uses to batch a cold join's gate reads. The batch is simply everything pending, so its wallets need not share a `sampleBlock`: a rule reading the head scores them all at once, a rule reading pinned blocks groups them itself. (`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: `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.
+- **`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 each bundle is verified once, when it is merged, 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).
@@ -216,8 +216,8 @@ import { z } from "zod";
 const seeditModAllowlist: Rule<{ type: "seedit-mod-allowlist"; allow: string[] }> = {
   type: "seedit-mod-allowlist",
   optionsSchema: z.object({ type: z.literal("seedit-mod-allowlist"), allow: z.array(z.string()) }),
-  async evaluate({ options, walletAddress }) {
-    return { score: options.allow.includes(walletAddress) ? 1n : 0n }; // gate: 1n admits, 0n rejects
+  async evaluate({ options, wallet }) {
+    return { score: options.allow.includes(wallet.address) ? 1n : 0n }; // gate: 1n admits, 0n rejects
   }
 };
 
@@ -229,6 +229,42 @@ const voter = new PubsubVoter({
 
 A custom `type` becomes part of `dag-cbor(criteria)`, so it is provably pinned to the topic it runs on, and a client that does not implement a `type` named in `criteria.requires.rules` throws `UnknownRuleError` and recuses itself rather than miscounting.
 
+#### What a rule owns: its block, and its cache
+
+A rule is handed the pinned block its ballot names, a lazy head reader, and its own memo, and decides for itself which to read and what to remember:
+
+```ts
+evaluate(args: { options: O; wallet: { address: string; sampleBlock: number }; ctx: ChainReadContext }): Promise<RuleResult>
+
+interface ChainReadContext {
+  chain: ChainClient;                        // the viem PublicClient for options.chain
+  head: () => Promise<{ block: number }>;    // this verifier's current block — lazy, coalesced
+  cache: RuleCache;                          // this rule's memo, persistent and shared across contests
+}
+```
+
+- **`wallet.sampleBlock`** is the bundle's bucketized block, already floored — the historical block every verifier agrees the ballot names. Read there and your score is identical on every verifier forever. It is *not* a claim about when the ballot was signed (it trails by up to `blocksPerBucket`).
+- **`ctx.head()`** is this verifier's current block. Read there and a wallet qualifies the moment it acquires the gating asset, instead of waiting for the next bucket boundary. Resolve it once per evaluation and pin your reads to that number — always pass an explicit `blockNumber: BigInt(...)`, or the read coalescer cannot batch you.
+- **`ctx.cache`** memoizes under a `key` you choose and an `epoch` that says when the answer stops being true (a moved epoch is how an entry expires; `purgeBelow` drops what is behind). **Chain-reading rules must use it** — it is what turns "one chain read per unique bundle" into "one read per key per epoch", so without it an ineligible wallet can make every peer on the topic pay an RPC round trip per fresh-signed bundle. `memoMany` reads only the misses, in one batched call.
+
+```ts
+const { values } = await ctx.cache.memoMany({
+  keys: wallets.map((w) => `bal/${w.toLowerCase()}`),
+  epoch: block,                                   // e.g. the pinned block, or a coarse head window
+  read: async ({ keys }) => ({ values: await readOnChain(keys) })
+});
+```
+
+`RuleResult` carries one field beyond the score:
+
+```ts
+interface RuleResult { score: bigint; penalize?: boolean }   // default true
+```
+
+**`penalize`** answers the one thing the library cannot: may a `0n` be blamed on the sender? `true` (the default) says every honest verifier computes this same `0n` — true of a read pinned to the block the bundle names — so the forward gate `reject`s the message (penalizing the delivering peer in gossipsub's scoring) and the verdict is cached as terminal. `false` says an honest peer could legitimately disagree, so the bundle is dropped `ignore`-class instead: no penalty, verdict uncached, and the background verifier re-examines it for a grace window before giving up.
+
+`erc5192-min-balance` reads the head first — so a freshly-acquired Pass counts immediately — falls back to `wallet.sampleBlock` when the head refuses (ERC-5192 does not forbid burning, and without the fallback a burn would erase votes retroactively for peers that had not verified them yet), memoizes each leg under its own epoch, and returns `penalize: false`, because at validation time it cannot attribute a `0n` to anyone: the peer that forwarded the vote verified it against *its* head. Every other rule in the tree reads `wallet.sampleBlock` and leaves `penalize` at its default — a transferable or fungible balance can decrease, so reading it at the head would silently invalidate votes already counted. See [DESIGN.md, What a rule owns](./DESIGN.md#what-a-rule-owns-and-what-the-pipeline-owns).
+
 ### 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 — 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).

package/dist/client/voter.js

@@ -14,9 +14,9 @@ import { makeRootChaser, toChaseSession } from "../transport/chase.js";
 import { encodeBundle, decodeBundle, bundleCidForBytes } from "../crdt/codec.js";
 import { resolveRegistry, validateCriteriaRules } from "../rules/registry.js";
 import { makeVoteCrdt } from "../crdt/crdt.js";
+import { makePersistentRuleCache } from "../rules/cache.js";
 import { makeBundleVerifier } from "../verify/bundle.js";
 import { makeVerdictCache } from "../verify/cache.js";
-import { makePersistentGateResultCache, purgeExpiredGateResults } from "../verify/gate-result-cache.js";
 import { makeNameResolutionCache } from "../verify/name-resolution-cache.js";
 import { makeStorage } from "../storage/node.js";
 import { makeAnnouncer } from "../transport/announce/node.js";
@@ -631,14 +631,31 @@ class ContestEngine {
             voteExpiryBuckets: criteria.voteExpiryBuckets,
             isProvisional: (cid) => this.#isPending(cid)
         });
-        // One gate-result cache shared between the inline forward-gate verifier and the
-        // background chain verifier, so neither re-reads a (wallet, sampleBlock) the other
-        // settled — layered over the voter's persistent store, keyed under this contest's rule
-        // hash: the gate score is a pure function of (rule, chainId, wallet, sampleBlock), so
-        // hashing the canonical rule document + chainId is exactly the sharing boundary (two
-        // contests over one gate share reads; different gates cannot collide).
+        // The gate rule's memo (rules/cache.ts), shared between the inline forward-gate verifier
+        // and the background chain verifier so neither re-reads what the other settled — layered
+        // over the voter's persistent store and namespaced by the hash of the canonical rule
+        // reference + chainId. That hash is exactly the sharing boundary: two contests over one
+        // gate (a directory of boards on the same Pass) share each other's reads, while
+        // different gates, or one gate on different options, can never collide. What is stored
+        // under it, and for how long, is the rule's business, not the engine's.
         this.#ruleHash = sha256(encodeDagCbor({ chainId: this.#chainId, rule: criteria.rule }));
-        const gateResultCache = makePersistentGateResultCache({ store: deps.gateStore, ruleHash: this.#ruleHash });
+        const gateCache = makePersistentRuleCache({ store: deps.gateStore, namespace: this.#ruleHash });
+        // The weight rule gets its own namespace on the SAME terms — its canonical reference plus
+        // the id of the chain IT reads, which is not necessarily the gating chain. A ticker is
+        // just a name local to the criteria document, so two contests can spell the same weight
+        // ref while `requires.chains` binds that ticker to different chains; keying on the gate's
+        // chainId would let one serve the other's scores from the wrong chain.
+        const weight = deps.registry[criteria.weight.type];
+        if (!weight)
+            throw new UnknownRuleError("weight", criteria.weight.type);
+        const weightTicker = tickerForRef(criteria, criteria.weight, weight.optionsSchema.parse(criteria.weight));
+        const weightChainId = criteria.requires.chains[weightTicker]?.chainId;
+        if (weightChainId === undefined)
+            throw new Error(`no chain client for weight chain "${weightTicker}"`);
+        const weightCache = makePersistentRuleCache({
+            store: deps.gateStore,
+            namespace: sha256(encodeDagCbor({ chainId: weightChainId, rule: criteria.weight }))
+        });
         const verifier = makeBundleVerifier({
             criteria,
             criteriaCid: criteriaCidBytes,
@@ -647,8 +664,9 @@ class ContestEngine {
             chainFor: (ticker) => this.#chainFor(ticker),
             bucketMath: this.#bucketMath,
             nameResolvers: deps.nameResolvers,
-            gateResultCache,
-            nameResolutionCache: deps.nameResolutionCache
+            ruleCache: gateCache,
+            nameResolutionCache: deps.nameResolutionCache,
+            readHead: ({ chain }) => this.#readHead({ chain })
         });
         // The gate/transport are (re)built on join(); the store, crdt, caches, verifier, and
         // background verifier are stable per contest, so they survive re-joins of the topic.
@@ -662,8 +680,9 @@ class ContestEngine {
             chainFor: (ticker) => this.#chainFor(ticker),
             bucketMath: this.#bucketMath,
             nameResolvers: deps.nameResolvers,
-            gateResultCache,
+            ruleCache: gateCache,
             nameResolutionCache: deps.nameResolutionCache,
+            readHead: ({ chain }) => this.#readHead({ chain }),
             cache: this.#cache,
             onGateVerified: (cid) => this.#settleCheck(cid, "chainVerified"),
             onNameResolved: (cid) => this.#settleCheck(cid, "nameResolved"),
@@ -676,6 +695,8 @@ class ContestEngine {
             registry: deps.registry,
             chainFor: (ticker) => this.#chainFor(ticker),
             bucketMath: this.#bucketMath,
+            readHead: ({ chain }) => this.#readHead({ chain }),
+            ruleCache: weightCache,
             current: () => this.#crdt
                 .currentEntries(this.#currentBucketCache)
                 .map(({ cid, bundle }) => ({ bundle, checks: this.#checksFor(cid, bundle) })),
@@ -808,35 +829,27 @@ class ContestEngine {
         const head = await this.#deps.readHead(this.#ruleChain);
         this.#currentBucketCache = this.#bucketMath.bucketForBlock(Number(head));
         this.#headReadMs = Date.now();
-        this.#maybePurgeGateResults();
         return this.#currentBucketCache;
     }
-    /** The last purge's expiry boundary (oldest admissible sample block); 0 = never purged. */
-    #purgedSampleBlock = 0;
     /**
-     * Drop this rule's persisted gate results older than the oldest admissible sample block —
-     * provably dead: a score at bucket B is only ever consulted while bundles from B are within
-     * `voteExpiryBuckets` of head (see verify/gate-result-cache.ts `purgeExpiredGateResults`).
-     * Piggybacks on the head reads the engine does anyway (join-with-state, publish, tally)
-     * and re-runs only when the boundary advances past the last purged one — so an idle
-     * engine costs no chain read and no purge, and a steady head costs no key scan, but a
-     * long-lived engine still sheds entries as they expire instead of leaving them to the
-     * LRU backstop. Fire-and-forget by design.
+     * The current head on `chain`, handed to every rule as `ctx.head` (verify/bundle.ts,
+     * verify/background.ts, tally/tally.ts all take this seam). It goes through the voter-wide
+     * {@link ResolvedDeps.readHead} coalescer for the same reason {@link #refreshBucket} does:
+     * a rule that scores current state puts this on the verify path, so a directory-wide gossip
+     * burst would otherwise fire one `eth_blockNumber` per contest per message instead of
+     * sharing one in-flight read per chain.
      */
-    #maybePurgeGateResults() {
-        const oldestBucket = this.#currentBucketCache - this.criteria.voteExpiryBuckets;
-        if (oldestBucket <= 0)
-            return;
-        const oldestSampleBlock = this.#bucketMath.sampleBlockForBucket(oldestBucket);
-        if (oldestSampleBlock <= this.#purgedSampleBlock)
-            return;
-        this.#purgedSampleBlock = oldestSampleBlock;
-        void purgeExpiredGateResults({
-            store: this.#deps.gateStore,
-            ruleHash: this.#ruleHash,
-            oldestSampleBlock
-        });
+    async #readHead(args) {
+        return { block: Number(await this.#deps.readHead(args.chain)) };
     }
+    /**
+     * PURGE REMOVED — kept as a note because the old behaviour was load-bearing and its
+     * replacement lives elsewhere. Persisted gate entries used to be purged here, at the oldest
+     * admissible bucket sample block, because the engine knew every entry was keyed by one. It
+     * no longer knows: a rule chooses its own keys and epochs (rules/cache.ts), so only the rule
+     * can say what is dead — `erc5192-min-balance` purges its head-keyed entries as the head
+     * window rolls, and its pinned entries stay valid until the store's LRU bound reclaims them.
+     */
     /** `Date.now()` of the last gating-chain head read, memoizing {@link #nowBucket}. */
     #headReadMs = 0;
     /** The current gating-chain head bucket, memoized for {@link HEAD_BUCKET_TTL_MS}. */

package/dist/index.d.ts

@@ -19,6 +19,7 @@ export * from "./rules/erc5192-min-balance.js";
 export * from "./rules/erc721-min-balance.js";
 export * from "./rules/constant.js";
 export * from "./rules/registry.js";
+export { makeMemoryRuleCache, makePersistentRuleCache, type RuleCache } from "./rules/cache.js";
 export * from "./encoding/canonical.js";
 export * from "./topic.js";
 export * from "./errors.js";

package/dist/index.js

@@ -34,6 +34,10 @@ export * from "./rules/erc5192-min-balance.js";
 export * from "./rules/erc721-min-balance.js";
 export * from "./rules/constant.js";
 export * from "./rules/registry.js";
+// The cache a rule computes through (`ctx.cache`): a rule owns its keys and epochs, the library
+// owns the store, the bound and the purge. A custom chain-reading rule MUST memoize through it —
+// see rules/cache.ts and README "Custom rules".
+export { makeMemoryRuleCache, makePersistentRuleCache } from "./rules/cache.js";
 // Implemented runtime: encoding, topic, errors, identity seam, facade.
 export * from "./encoding/canonical.js";
 export * from "./topic.js";

package/dist/rules/cache.d.ts

@@ -0,0 +1,107 @@
+import type { LruStorage } from "../storage/types.js";
+/**
+ * The cache a rule computes through.
+ *
+ * A rule decides *what* it reads and *when* the answer stops being true; the library decides
+ * where that answer is stored, how it is bounded, and how it is shared. This seam is that split.
+ * It exists because cache validity is the thing that genuinely differs between rules and cannot
+ * be expressed generically:
+ *
+ *   - a score read at a pinned historical block is true forever, so it should never expire;
+ *   - a score read at the chain head stops being true almost immediately — a wallet that failed
+ *     a moment ago may hold the gate asset now — so it must expire, and how fast is a judgement
+ *     only the rule can make;
+ *   - some reads are not per-wallet at all (`erc5192-min-balance` probes `supportsInterface`
+ *     once per contract), which no per-wallet key can express.
+ *
+ * The library still owns the mechanics, because they are not rule-specific and are easy to get
+ * wrong: persistence under the voter's `dataPath`, the bounded in-memory front, and the
+ * namespace. Every rule instance gets its own keyspace, namespaced by the rule's `type`, its
+ * canonical options and the id of the chain IT reads (which for the weight rule need not be the
+ * gating chain) — so two contests running the same gate share each other's reads (a 5chan-style
+ * directory of 63 boards on one Pass is one read per wallet, not 63), while two different gates,
+ * or the same gate on a different contract or chain, can never collide.
+ *
+ * **Caching is not optional for a chain-reading rule.** It is what bounds the "one chain read per
+ * unique bundle" amplifier: without it, an ineligible wallet can mint fresh-signed bundles and
+ * make every peer on the topic pay an RPC round trip for each one (DESIGN.md "Can valid votes
+ * clog the topic?"). {@link RuleCache.memoMany} exists so the correct behaviour is one call.
+ *
+ * Values are strings because the persistent tier is JSON-backed — a `bigint` score travels as a
+ * decimal string, a boolean as `"1"`/`"0"`.
+ */
+export interface RuleCache {
+    /** The memoized value for `key` within `epoch`, or `{ value: undefined }` on a miss. */
+    get(args: {
+        key: string;
+        epoch: number;
+    }): Promise<{
+        value: string | undefined;
+    }>;
+    /**
+     * Memoize `value` for `key` within `epoch`. Idempotent: an existing entry is never
+     * overwritten, so a score cannot be silently replaced under a key that still applies.
+     * Returns immediately — any persistence settles in the background, so the verify hot path
+     * never waits on a cache write.
+     */
+    set(args: {
+        key: string;
+        epoch: number;
+        value: string;
+    }): void;
+    /**
+     * Look up many keys at once and read only the misses — the batched path a rule should use
+     * for a cold join's wallets, where `read` becomes one multicall instead of N round trips.
+     * `read` is called at most once, with the missing keys in order, and MUST return one value
+     * per key it was given. Skipped entirely when everything hits.
+     */
+    memoMany(args: {
+        keys: string[];
+        epoch: number;
+        read: (args: {
+            keys: string[];
+        }) => Promise<{
+            values: string[];
+        }>;
+    }): Promise<{
+        values: string[];
+    }>;
+    /**
+     * Drop persisted entries below `epoch` — the rule's own statement that they are dead.
+     *
+     * This is on the rule because only the rule knows what an epoch means. A rule keying by the
+     * chain head knows everything behind the current window is unreachable; a rule keying by a
+     * bundle's pinned block knows nothing expires until the vote itself does. Optionally
+     * restricted to keys starting with `keyPrefix`, so a rule that mixes both — as the v1 gate
+     * does — can purge its head-keyed entries without touching its permanently-valid ones.
+     *
+     * Best-effort and fire-and-forget: the store's LRU bound is the backstop for a rule that
+     * never calls it. Repeat calls at or below the last purged epoch are free.
+     */
+    purgeBelow(args: {
+        epoch: number;
+        keyPrefix?: string;
+    }): void;
+}
+/**
+ * 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 declare function makeMemoryRuleCache(args?: {
+    maxEntries?: number;
+}): RuleCache;
+/**
+ * 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 declare function makePersistentRuleCache(args: {
+    store: LruStorage;
+    namespace: string;
+    maxMemEntries?: number;
+}): RuleCache;

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/erc20-balance.js

@@ -37,13 +37,17 @@ 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 };

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