feat(react): TTL-watermark invalidation delivery + chain-pinned reads

[alexshchur]

Stacked on #363 (→ #362 → #355 → #354 → #352 → #349). Two design findings from an external audit of the block-aware machinery, one commit each.

1. Invalidation contexts become TTL watermarks — deterministic delivery

The context store consumed each entry on the first fetch that resolved under its prefix. That delivered block-awareness reliably to the concurrent refetches an invalidation triggers (they all read the note synchronously in the same tick) — and by ordering luck to everything staggered: a query created only after the tx's outcome was known (a record read keyed by an id the tx just produced), an enabled flip, the second stage of an ids→batch read.

Now invalidateQueriesWithContext stores a watermark: until it expires (ttlMs option, default 60s) EVERY fetch under the prefix gates on the mined block — first, tenth, or one created seconds later. Entries expire by time, never by being read; expired entries are pruned lazily on store writes (fixing the leak where an undelivered note lived forever — createdAt existed but was only used for sort order). The store's prefix matching now mirrors react-query's partial-matching semantics (deep subset per segment), so an args-narrowed watermark like args: [id] reaches fn(id, seq)-shaped keys exactly like the invalidation itself does — previously the store's exact-JSON segment comparison silently missed them. consumeInvalidationContext leaves the public surface (nothing consumes on delivery any more). The repeated gate probe is near-free: once the node has caught up, eth_getBlockByHash resolves instantly in the same JSON-RPC batch as the read.

The old semantics were encoded in our own tests ("the invalidation context is one-shot… store empty afterwards") — those assertions are deliberately flipped, and the suite gains the staggered scenario that fails under the old design: invalidate, let the refetches fully settle, then enable a reader whose key was never fetched — and assert its first fetch probes the mined block like its concurrent siblings did.

2. Chain-pinned reads

useCofheReadContract / useCofheReadContracts accept chainId to pin a read (or a whole batch) to a specific chain instead of following the connected one. Three layers, all addressed:

• the key: the pinned id becomes the key's chain segment — pin the matching invalidates targets to the same chainId so they meet;
• the transport: the fetch routes through an app-supplied client for that chain, declared via CofheProvider's new publicClients?: Record<number, PublicClient> prop and resolved by useCofhePublicClient(chainId?). App-supplied on purpose — the app owns transport choices, and the block-aware gate depends on batching;
• the failure mode: without a client for the pinned chain the read stays disabled, rather than silently querying the wrong chain.

This closes a dual-chain footgun: in an app whose contracts live on a different chain than the wallet currently sits on, reads followed the wallet — eth_call hit a chain with no contract and every query decoded 0x.

Tests

Same no-mock house style. New scenarios in react-read-contracts.web.test.tsx:

• staggered watermark: fails on the pre-PR SDK by construction (the consumed note left the late reader un-gated); asserts one extra mined-block probe for a key first fetched after the invalidation settled;
• pinned routing: two recording transports — a pinned read fetches through the MAPPED client only (0 calls on the connected one) and its cache key carries the pinned chain id.

Full run: 9/9 integration (3 files), 29/29 unit, package tsc --noEmit clean, prettier clean.

Revision (c838686a): chain-pinned reads without the provider map

The first cut (13b59f0e, section 2 above) routed pinned reads through a publicClients map on CofheProvider. On review that map sent reads around the connection: only the two generic read hooks honored it, a requiresACP read pinned elsewhere was gated by the connected chain's ACP, pinned reads silently ran with no wallet, and every invalidation target had to be pinned by hand. It is replaced — in a new commit, so the history keeps both — by:

• chainId alone guards the read. It is the key's chain segment; the read runs only while the wallet is on that chain, otherwise it is disabled with a new disabledDueToWrongChain flag. Never a read of the wrong chain.
• publicClient (with chainId) serves it. Per call and explicit: the read goes through that client wherever the wallet sits, including with no wallet connected. A client whose own chain disagrees with chainId keeps the read disabled.
• ACP and decryption follow the read's chain. useCofheActiveACP(chainId?) looks up that chain's ACP (connected chain by default — the store was already per chain). useCofheDecrypt takes chainId and calls .setChainId(); useCofheReadContractAndDecrypt passes it through.
• Block-awareness stays on the write's chain. Invalidation targets on another chain get a plain refresh — that chain never sees the write's block, so gating on it could only time out.

The publicClients prop is gone; it never shipped.

Tests: the provider-map test is replaced by a chain-pinned reads suite (7 scenarios): the guard on and off chain; a per-call client serving the singular and batch hooks (one shared key); a client/chainId mismatch; a read with no wallet; ACP gating by the read's chain; a real mock decrypt that succeeds only through the pinned chain's ACP; and a cross-chain write target refreshed without a block probe. Mutation-checked: breaking the ACP lookup or the cross-chain rule fails exactly those three tests, and dropping .setChainId() fails exactly the decrypt test.

Full run: 15/15 integration (3 files), 29/29 unit, package and matrix tsc --noEmit clean, prettier + eslint clean.

[claude]

Claude Code Review

This repository is configured for manual code reviews. Comment @claude review for a one-time review, or @claude review always to subscribe this PR to a review on every future push.

_{Tip: disable this comment in your organization's Code Review settings.}

[changeset-bot]

🦋 Changeset detected

Latest commit: a21b72c

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 9 packages

Name	Type
@cofhe/react	Patch
@cofhe/example-react	Patch
@cofhe/abi	Patch
@cofhe/foundry-plugin	Patch
@cofhe/hardhat-3-plugin	Patch
@cofhe/hardhat-plugin	Patch
@cofhe/mock-contracts	Patch
@cofhe/sdk	Patch
@cofhe/site	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
cofhesdk-react	Ready	Preview	Sep 17, 2026 5:08am UTC

1 Skipped Deployment

Project	Deployment	Actions	Updated
cofhesdk-docs	Ignored		Sep 17, 2026 5:08am UTC

[github-actions]

Vercel previews (commit a21b72c)

Project	Deployment	Updated
docs	Visit Preview	Sep 17, 2026 05:10 UTC
react	Visit Preview	Sep 17, 2026 05:12 UTC

[architect-dev]

Couple small fix requests.

Also I got this during my audit but I'm not sure I understand it, maybe you'll have better luck:

Reorg/lagging-node case now amplifies to thousands of RPC calls — [invalidationContext.ts:76]
Because watermarks are no longer consumed, a block hash the node never learns (reorged away, or a lagging load-balanced backend) turns what used to be one bounded 60s stall into a 60s stall on every fetch under the prefix for the whole TTL — and maybeWaitUntilRpcAware issues both the probe and the full contract read once per second, discarding the read result each non-final iteration (~120 RPC calls per fetch). Two window refocuses over 10 covered reads ≈ 2,400 wasted calls in a minute. Also note the changeset's "resolves instantly in the same JSON-RPC batch" claim doesn't hold for non-batching transports like custom(window.ethereum). The code already has hooks for the fix: the unused onSuccess callback to memoize per-(client, blockHash) confirmation, probe-only inside the loop, and one shared in-flight probe per hash.

[architect-dev]

I think we can replace this with react querie's existing partialMatchKey

[architect-dev]

I think this needs the chanId as well?

[architect-dev]

This is failing open if onOtherChain is false here. An incorrect chain will be waiting for a blockHash from another chain (which it will never see). onOtherChain can be false if the parsed queryKey targetChainId doesn't resolve to a number or is undefined, which can happen if a request was created with an undefined connectedChainId.

[alexshchur]

Fixed: 4e65a4d, cb350d4, e9da0ca.

Now Instead of gating a fetch by the block hash unless we can prove the target is on another chain, we now gate only the targets we're sure are on the write tx's chain, and just invalidate the rest (plain refetch, no block-hash wait).

[alexshchur]

Also I got this during my audit but I'm not sure I understand it, maybe you'll have better luck:

Reorg/lagging-node case now amplifies to thousands of RPC calls — [invalidationContext.ts:76] Because watermarks are no longer consumed, a block hash the node never learns (reorged away, or a lagging load-balanced backend) turns what used to be one bounded 60s stall into a 60s stall on every fetch under the prefix for the whole TTL — and maybeWaitUntilRpcAware issues both the probe and the full contract read once per second, discarding the read result each non-final iteration (~120 RPC calls per fetch). Two window refocuses over 10 covered reads ≈ 2,400 wasted calls in a minute. Also note the changeset's "resolves instantly in the same JSON-RPC batch" claim doesn't hold for non-batching transports like custom(window.ethereum). The code already has hooks for the fix: the unused onSuccess callback to memoize per-(client, blockHash) confirmation, probe-only inside the loop, and one shared in-flight probe per hash.

@architect-dev , this is a real edge case, but the number is too high: a window refocus doesn't start a second fetch (react-query joins the one in flight, cancelRefetch: false), so it's ~1,200, not 2,400.

Worst case is a reorg indeed. Then each covered read polls for a minute, gives up, and returns the non-block-aware value. The watermark expires at the same moment, so that happens once per read.

My proposal: exponential backoff in the wait loop (1s doubling, capped at 10s), so a stalled read makes ~10 probes over the minute instead of 60.

For the audit's example (i.e. 10 covered reads, reorged block): ~10 ticks × 2 calls × 10 reads ≈ 200 calls over the minute, down from ~1,200.