envio 3.15.0 → 3.16.0

package/README.md

@@ -1,6 +1,6 @@
 <div align="center">
-  <h1>HyperIndex: Ultra-Fast Multichain Indexer</h1>
-  <p><strong>The fastest independently benchmarked multichain blockchain indexer.</strong></p>
+  <h1>HyperIndex</h1>
+  <p><strong>Build custom blockchain APIs and analytics. Real-time, with enterprise SLAs.</strong></p>
   <p>
     <a href="https://github.com/enviodev/hyperindex/releases"><img src="https://img.shields.io/github/release/enviodev/hyperindex.svg" alt="GitHub release" /></a>
     <a href="https://github.com/enviodev/hyperindex/issues"><img src="https://img.shields.io/github/issues/enviodev/hyperindex.svg" alt="GitHub issues" /></a>
@@ -10,18 +10,20 @@
   </p>
   <p>
     <a href="https://docs.envio.dev">Documentation</a> ·
-    <a href="https://envio.dev">Hosted Service</a> ·
+    <a href="https://envio.dev">Envio Cloud</a> ·
+    <a href="https://github.com/enviodev/open-indexer-benchmark">Benchmark</a> ·
+    <a href="https://docs.envio.dev/docs/HyperIndex/quickstart-with-ai">Build with AI</a> ·
     <a href="https://discord.gg/DhfFhzuJQh">Discord</a> ·
-    <a href="https://docs.envio.dev/blog/best-blockchain-indexers-2026">Benchmarks</a>
+    <a href="https://envio.dev/pricing">Contact sales</a>
   </p>
 </div>
 
 ---
 ## What is HyperIndex?
 
-HyperIndex is Envio's full-featured blockchain indexing framework. It transforms onchain events into structured, queryable databases with GraphQL APIs, built for developers who care about performance and a clean local experience.
+HyperIndex is Envio's blockchain indexing framework. Choose the contracts and events to track, write TypeScript handlers that shape the data, and HyperIndex keeps it up to date across EVM chains, Solana and Fuel, handles chain reorgs, and serves the result as a GraphQL API or direct Postgres/ClickHouse SQL.
 
-Powered by [HyperSync](https://docs.envio.dev/docs/HyperSync/overview), Envio's proprietary data engine, HyperIndex delivers up to 2000x faster data access than traditional RPC endpoints. That's the difference between syncing in minutes instead of days.
+It reads chain data through [HyperSync](https://docs.envio.dev/docs/HyperSync/overview), Envio's blockchain data API, which is up to 2,000x faster than JSON-RPC. Run it yourself with Docker, or deploy to [Envio Cloud](https://docs.envio.dev/docs/HyperIndex/hosted-service). Cloud starts with a free development plan and scales with your project up to Dedicated infrastructure with a 99.99% uptime SLA.
 
 ![Envio Sync](sync.gif)
 
@@ -31,12 +33,9 @@ Powered by [HyperSync](https://docs.envio.dev/docs/HyperSync/overview), Envio's
 
 Most blockchain indexers are bottlenecked by RPC. HyperIndex isn't. HyperSync, the data engine underneath, is a purpose-built, Rust-based query layer that retrieves multiple blocks per round trip, cuts out the overhead, and makes historical backfills genuinely fast.
 
-Independent benchmarks run by Sentio confirm it:
+The [open indexer benchmark](https://github.com/enviodev/open-indexer-benchmark) tracks current speed results across scenarios, and HyperIndex passes every reliability check. Every number there comes from code in the repository, so you can run it yourself.
 
-- **Uniswap V2 Factory** (May 2025): HyperIndex completed in 1 minute. 15x faster than the nearest competitor (Subsquid), 143x faster than The Graph, 158x faster than Ponder
-- **LBTC Token with RPC calls** (April 2025): HyperIndex completed in 3 minutes vs 3 hours 9 minutes for The Graph
-
-[View full benchmark results →](https://docs.envio.dev/docs/HyperIndex/benchmarks)
+[How the benchmarks work →](https://docs.envio.dev/docs/HyperIndex/benchmarks)
 
 ---
 
@@ -44,15 +43,14 @@ Independent benchmarks run by Sentio confirm it:
  
 HyperIndex and HyperSync are the data layer for DeFi dashboards, protocol analytics, block explorers, stablecoin monitors, liquidation trackers, oracle comparisons, NFT explorers, and any application that needs fast, structured onchain data.
  
-A few things already running in production:
+A few apps built with them, from the showcase:
  
-- [v4.xyz](https://v4.xyz): the hub for Uniswap V4 data and analytics, indexing across 10 chains in real-time
-- [Stable Volume](https://www.stablevolume.com/): real-time stablecoin transaction monitoring across 10+ chains
+- [v4.xyz](https://v4.xyz): the hub for Uniswap V4 data and analytics, indexed in real time across chains
+- [Stable Volume](https://www.stablevolume.com/): real-time stablecoin transaction monitoring across chains
 - [Stable Radar](https://stable-radar.com): real-time USDC transaction dashboard across multiple chains
 - [Liqo](https://liqo.xyz): multichain liquidation tracking for DeFi lending protocols
-- [Safe Stats](https://safe-stats.vercel.app/): real-time analytics for Safe multisig activity across all chains
 - [Oracle Wars](https://oraclewars.xyz/): real-time oracle price comparison across multiple oracles
-- [Chain Density](https://chaindensity.xyz/): transaction and event density analysis for any address across 70+ chains
+- [Chain Density](https://chaindensity.xyz/): transaction and event density analysis for any address across chains
 - [LogTUI](https://www.npmjs.com/package/logtui): terminal UI for monitoring blockchain events in real-time
  
 [See the full showcase →](https://docs.envio.dev/showcase)
@@ -62,34 +60,33 @@ A few things already running in production:
 ## Key Features
 
 **Performance**
-- Historical backfills at 25,000+ events per second
-- Up to 2000x faster than traditional RPC via HyperSync (enabled by default, no config required)
-- Sync times reduced from days to minutes
+- Historical backfills at 100,000+ events per second ([benchmarking](https://docs.envio.dev/docs/HyperIndex/benchmarking))
+- Up to 2,000x faster than JSON-RPC via HyperSync (on by default, no config required)
 - Fallback RPC support for reliability without touching your indexer code
 
 **Multichain indexing**
 - Index EVM, SVM, and Fuel blockchains from a single indexer
-- 79+ EVM chains with first-class HyperSync support, plus any EVM chain via RPC
+- Every chain on the [HyperSync network list](https://docs.envio.dev/docs/HyperSync/hypersync-supported-networks), plus any EVM chain via RPC
 - Real-time indexing with reorg handling built in
 
 **Developer experience**
 - Auto-generate an indexer directly from a smart contract address or ABI, no manual setup required
-- Write handlers in TypeScript, JavaScript, or ReScript
+- Write handlers in TypeScript or ReScript, and plain JavaScript handler files load too
 - Full local development environment with Docker
 - GraphQL API generated automatically from your schema
 - Wildcard topic indexing: index by event signatures across any contract, not just specified addresses
-- Factory contract support for 1M+ dynamically registered contracts
+- Factory contract support for dynamically registered contracts
 - Onchain and off-chain data integration
 - External API actions triggered by blockchain events
 - Detailed logging and error reporting
 
 **Deployment**
-- Managed [hosted service](https://docs.envio.dev/docs/HyperIndex/hosted-service) with static endpoints, built-in alerts, and production-ready infrastructure
+- [Envio Cloud](https://docs.envio.dev/docs/HyperIndex/hosted-service), managed hosting with static endpoints and built-in alerts, from a free development plan up to Dedicated deployments with an SLA of up to 99.99% uptime
 - Self-hosted via Docker
 - No vendor lock-in. Switch between HyperSync and RPC at any time
 
 **Agentic development**
-- HyperIndex is the default indexing framework for AI-assisted and agentic workflows via Envio's hosted service CLI (`envio-cloud`) and Claude skills
+- Build and deploy with an AI agent using the Envio Cloud CLI (`envio-cloud`) and the [HyperIndex skills](https://github.com/enviodev/hyperindex/tree/main/packages/cli/templates/static/shared/.claude/skills) that `envio init` adds to every project
 - An agent can scaffold, configure, and deploy a production-ready indexer without touching a config file. [400,000 events indexed in ~20 seconds](https://docs.envio.dev/blog/agentic-blockchain-indexing-envio-hyperindex)
 - Powerful built-in testing framework purpose-built for AI-driven development. Agents can write, run, and iterate on handler tests in a tight feedback loop, catching regressions before deploy
 
@@ -97,7 +94,7 @@ A few things already running in production:
 
 ## Getting started
 
-**Requirements**: Node.js, Docker (only needed for local development)
+**Requirements**: Node.js 22.15 or newer, and Docker for local development. pnpm is recommended.
 
 ```bash
 pnpx envio init
@@ -119,7 +116,7 @@ From there, three files define your indexer:
 
 HyperSync is the data engine that makes HyperIndex fast. It's active by default for all supported networks, no configuration needed.
 
-Instead of making individual RPC calls per block, HyperSync retrieves multiple data points per round trip with advanced filtering. The result: sync speeds up to 2000x faster than standard RPC, dramatically lower infrastructure costs, and no rate limit headaches on supported networks.
+Instead of making individual RPC calls per block, HyperSync retrieves multiple data points per round trip with advanced filtering. The result is sync speeds up to 2,000x faster than JSON-RPC, lower infrastructure costs, and no rate limits to work around on supported networks.
 
 HyperSync can also be used directly for custom data pipelines in Python, Rust, Node.js, and Go, independent of HyperIndex.
 
@@ -129,19 +126,17 @@ HyperSync can also be used directly for custom data pipelines in Python, Rust, N
 
 ## Supported networks
 
-HyperIndex supports any EVM-compatible L1, L2, or L3, plus Fuel and Solana (beta). 79+ chains have first-class HyperSync support for maximum speed. For any EVM chain not on the HyperSync list, RPC-based indexing works out of the box. Solana indexing runs on HyperSync for Solana, with instruction-level handlers and IDL-aware decoding.
+HyperIndex supports any EVM-compatible L1, L2, or L3, plus Fuel and Solana. Chains on the [HyperSync network list](https://docs.envio.dev/docs/HyperSync/hypersync-supported-networks) get first-class HyperSync support. For any EVM chain not on the HyperSync list, RPC-based indexing works out of the box. Solana indexing runs on HyperSync for Solana, with instruction-level handlers and IDL-aware decoding.
 
 [Full network list →](https://docs.envio.dev/docs/HyperIndex/supported-networks)
 
 ---
 
-## Migrating from The Graph, Ponder, or Subsquid
-
-HyperIndex has a dedicated migration guide that covers config conversion, schema mapping, and query differences in 3 steps. Envio also offers white-glove migration support. Reach out on Discord and the team will help you get set up.
+## Migrating an existing indexer
 
-Teams migrating from The Graph can access 2 months of free hosting and full migration support.
+The migration guides cover config conversion, schema mapping and query differences, and you can [migrate with an AI agent](https://docs.envio.dev/docs/HyperIndex/migrate-with-ai). If you run subgraphs, Envio can also migrate and host them for you with Subgraph Hosting, while your applications keep querying a subgraph-compatible endpoint. For hands-on help, see [services](https://envio.dev/pricing/services) or ask on Discord.
 
-[Migration guide →](https://docs.envio.dev/docs/HyperIndex/migration-guide)
+[Migration guides →](https://docs.envio.dev/docs/HyperIndex/migration-guide)
 
 ---
 
@@ -155,16 +150,27 @@ Key sections:
 - [Multichain Indexing](https://docs.envio.dev/docs/HyperIndex/multichain-indexing)
 - [Wildcard Indexing](https://docs.envio.dev/docs/HyperIndex/wildcard-indexing)
 - [Reorg Support](https://docs.envio.dev/docs/HyperIndex/reorgs-support)
-- [Hosted Service](https://docs.envio.dev/docs/HyperIndex/hosted-service)
+- [Envio Cloud](https://docs.envio.dev/docs/HyperIndex/hosted-service)
 - [HyperSync as Data Source](https://docs.envio.dev/docs/HyperIndex/hypersync)
 - [Migration Guide](https://docs.envio.dev/docs/HyperIndex/migration-guide)
 
 ---
 
+## Build with an AI agent
+
+HyperIndex works with Claude Code, Cursor, Codex and other coding agents.
+
+- **Docs for agents.** Point your agent at [llms.txt](https://docs.envio.dev/llms.txt), or the full text at [llms-full.txt](https://docs.envio.dev/llms-full.txt).
+- **Docs MCP server.** Add `https://docs.envio.dev/mcp` to your agent for `docs_search` and `docs_fetch`. See the [MCP server guide](https://docs.envio.dev/docs/HyperIndex/mcp-server).
+- **Skills.** `pnpx envio init` adds the [HyperIndex skills](https://github.com/enviodev/hyperindex/tree/main/packages/cli/templates/static/shared/.claude/skills) to every new project. After upgrading `envio`, run `pnpm envio skills update` to refresh them.
+- **Quickstart.** Follow [Quickstart with AI](https://docs.envio.dev/docs/HyperIndex/quickstart-with-ai) to go from a contract address to a deployed GraphQL API.
+
+---
+
 ## Community and support
 
 - Follow us on [X](https://twitter.com/envio_indexer)
-- Join the [Discord](https://discord.gg/DhfFhzuJQh), fastest way to get help
+- Join the [Discord](https://discord.gg/DhfFhzuJQh) or [Telegram](https://t.me/+BeS5ihVUFONjNGFk), the fastest ways to get help
 - Open an issue on [GitHub](https://github.com/enviodev/hyperindex/issues/new/choose)
 - Browse [common issues](https://docs.envio.dev/docs/common-issues) for quick troubleshooting
 

package/evm.schema.json

@@ -289,7 +289,7 @@
           "type": "string"
         },
         "name": {
-          "description": "Name of the event in the HyperIndex generated code. When ommitted, the event field will be used. Should be unique per contract",
+          "description": "Name of the event in the generated types. When ommitted, the event field will be used. Should be unique per contract",
           "type": [
             "string",
             "null"
@@ -421,7 +421,7 @@
           ]
         },
         "rpc": {
-          "description": "RPC configuration for your indexer. If not specified otherwise, for chains supported by HyperSync, RPC serves as a fallback for added reliability. For others, it acts as the primary data-source. HyperSync offers significant performance improvements, up to a 1000x faster than traditional RPC.",
+          "description": "RPC configuration for your indexer. If not specified otherwise, for chains supported by HyperSync, RPC serves as a fallback for added reliability. For others, it acts as the primary data-source. HyperSync offers significant performance improvements, up to 2000x faster than traditional RPC.",
           "anyOf": [
             {
               "$ref": "#/$defs/RpcSelection"
@@ -460,6 +460,15 @@
           "format": "uint32",
           "minimum": 0
         },
+        "block_throttle": {
+          "description": "Once caught up, wait for this many new blocks before fetching them. Delays new events by up to as many blocks.",
+          "type": [
+            "integer",
+            "null"
+          ],
+          "format": "uint32",
+          "minimum": 0
+        },
         "start_block": {
           "description": "The block at which the indexer should start ingesting data, or \"latest\" to start from the chain's current head block when the indexer is first deployed. Once resolved, the concrete block is persisted and reused every time the indexer resumes normally (for example recovering from a crash), so downtime is backfilled instead of skipped. Running `envio start`/`dev` with -r (--restart) resets this like any other config change: \"latest\" resolves again, against the head at that time.",
           "$ref": "#/$defs/StartBlock"

package/fuel.schema.json

@@ -241,7 +241,7 @@
       "type": "object",
       "properties": {
         "name": {
-          "description": "Name of the event in the HyperIndex generated code",
+          "description": "Name of the event in the generated types",
           "type": "string"
         },
         "type": {
@@ -336,6 +336,15 @@
           "format": "uint32",
           "minimum": 0
         },
+        "block_throttle": {
+          "description": "Once caught up, wait for this many new blocks before fetching them. Delays new events by up to as many blocks.",
+          "type": [
+            "integer",
+            "null"
+          ],
+          "format": "uint32",
+          "minimum": 0
+        },
         "contracts": {
           "description": "All the contracts that should be indexed on the given chain",
           "type": [

package/index.d.ts

@@ -398,6 +398,8 @@ type EvmChainConfig<Id extends number = number> = {
   readonly maxReorgDepth?: number;
   /** Number of blocks behind the chain head to lag (default: 0). */
   readonly blockLag?: number;
+  /** Once caught up, wait for this many new blocks before fetching them. Delays new events (default: 0). */
+  readonly blockThrottle?: number;
 };
 
 /** EVM chain value (for runtime Indexer). */
@@ -454,6 +456,8 @@ type FuelChainConfig<Id extends number = number> = {
   readonly maxReorgDepth?: number;
   /** Number of blocks behind the chain head to lag (default: 0). */
   readonly blockLag?: number;
+  /** Once caught up, wait for this many new blocks before fetching them. Delays new events (default: 0). */
+  readonly blockThrottle?: number;
 };
 
 /** Fuel chain value (for runtime Indexer). */
@@ -490,6 +494,8 @@ type SvmChainConfig<Id extends number = number> = {
   readonly maxReorgDepth?: number;
   /** Number of blocks behind the chain head to lag (default: 0). */
   readonly blockLag?: number;
+  /** Once caught up, wait for this many new slots before fetching them. Delays new instructions (default: 0). */
+  readonly blockThrottle?: number;
 };
 
 /** SVM chain value (for runtime Indexer). */

package/licenses/README.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-Envio's licensing reflects open source ethos but is not OSI recognized. Developers can use Envio's services without vendor lock-in, either by self-hosting or specifying an RPC URL. The generated code is open and public and so is this repository that generates the generated code.
+Envio's licensing reflects open source ethos but is not OSI recognized. Developers can use Envio's services without vendor lock-in, either by self-hosting or specifying an RPC URL. The code in this repository is public.
 
 Our licenses allows self-hosting but restricts third-party hosting with Envio's hosted service. Envio may consider open-sourcing in the future but prioritizes stakeholder interests and market traction. Please reach out to us on discord if you would like to explore hosting indexers as a third-party.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "envio",
-  "version": "3.15.0",
+  "version": "3.16.0",
   "type": "module",
   "description": "A latency and sync speed optimized, developer friendly blockchain data indexer.",
   "bin": "./bin.mjs",
@@ -43,16 +43,16 @@
   "dependencies": {
     "bignumber.js": "9.3.1",
     "eventsource": "4.1.0",
-    "express": "4.19.2",
-    "@rescript/runtime": "12.2.0",
+    "express": "4.22.3",
+    "@rescript/runtime": "12.3.1",
     "rescript-schema": "9.5.1",
     "dotenv": "16.4.5"
   },
   "optionalDependencies": {
-    "envio-linux-x64": "3.15.0",
-    "envio-linux-x64-musl": "3.15.0",
-    "envio-linux-arm64": "3.15.0",
-    "envio-darwin-x64": "3.15.0",
-    "envio-darwin-arm64": "3.15.0"
+    "envio-linux-x64": "3.16.0",
+    "envio-linux-x64-musl": "3.16.0",
+    "envio-linux-arm64": "3.16.0",
+    "envio-darwin-x64": "3.16.0",
+    "envio-darwin-arm64": "3.16.0"
   }
 }

package/src/Batch.res.mjs

@@ -109,9 +109,9 @@ function make(sequence, frontier, chainsBeforeBatch, batchSizeTarget, history) {
           chainEventsProcessed = chainEventsProcessed + 1;
         }
         if (blockNumber !== prevBlockNumber) {
-          let chainId = fetchState.chainId;
-          let fromBlockExclusive = prevBlockNumber;
           let scannedHashes = chainBeforeBatch.scannedHashes;
+          let fromBlockExclusive = prevBlockNumber;
+          let chainId = fetchState.chainId;
           if (chainBeforeBatch.shouldRollbackOnReorg) {
             let blockNumbers = scannedHashes.blockNumbers;
             let length = blockNumbers.length;
@@ -154,10 +154,10 @@ function make(sequence, frontier, chainsBeforeBatch, batchSizeTarget, history) {
       };
     }
     let progressBlockNumberAfterBatch = FetchState.getProgressBlockNumberAt(fetchState, chainBatchSize);
-    let chainId$1 = fetchState.chainId;
-    let toBlockExclusive = progressBlockNumberAfterBatch + 1;
-    let fromBlockExclusive$1 = prevBlockNumber;
     let scannedHashes$1 = chainBeforeBatch.scannedHashes;
+    let fromBlockExclusive$1 = prevBlockNumber;
+    let toBlockExclusive = progressBlockNumberAfterBatch + 1;
+    let chainId$1 = fetchState.chainId;
     if (chainBeforeBatch.shouldRollbackOnReorg) {
       let blockNumbers$1 = scannedHashes$1.blockNumbers;
       let length$1 = blockNumbers$1.length;

package/src/BatchProcessing.res

@@ -51,6 +51,7 @@ let rec startProcessing = async (
       }
     }
     state->IndexerState.endProcessing
+    state->IndexerState.reportArrivalAtHead
 
     // A reorg detected mid-batch parks the rollback until the loop is idle.
     // Hand off now that no batch is in flight.

package/src/BatchProcessing.res.mjs

@@ -108,6 +108,7 @@ async function startProcessing(state, runtime, scheduleFetch, scheduleRollback)
     }
   };
   IndexerState.endProcessing(state);
+  IndexerState.reportArrivalAtHead(state);
   if (IndexerState.isResolvingReorg(state)) {
     return scheduleRollback();
   } else if (!IndexerState.isStopped(state) && !Object.values(IndexerState.chainStates(state)).every(ChainState.isFetchingAtHead)) {

package/src/ChainState.res

@@ -308,11 +308,16 @@ let makeInternal = (
     // FIXME: Shouldn't set with full history
     // The resumed depth, not the config one: the pre-threshold lag must match
     // the window reorg detection compares, or a reduced config depth would let
-    // fetching enter the stored rollback window without history.
+    // fetching enter the stored rollback window without history. One block
+    // more than the window, so the last pre-threshold page ends below it and
+    // the window's first block is read by a page that knows it is reorgable.
     ~blockLag=Pervasives.max(
-      !config.shouldRollbackOnReorg || isInReorgThreshold ? 0 : maxReorgDepth,
+      !config.shouldRollbackOnReorg || isInReorgThreshold || maxReorgDepth == 0
+        ? 0
+        : maxReorgDepth + 1,
       chainConfig.blockLag,
     ),
+    ~blockThrottle=chainConfig.blockThrottle,
     ~onBlockRegistrations,
     ~firstEventBlock,
     // Fuel and SVM route through the address store like EVM does, so the
@@ -349,6 +354,7 @@ let makeInternal = (
     ~blockStore,
     ~transactionStore,
     ~logger,
+    ~maxAddressesPerRequest=config.maxAddrInPartition,
   )
 
   // Seed the stored reorg checkpoints (hash-only rows) so detection resumes
@@ -776,10 +782,10 @@ let takeFinished = (cs: t) =>
     }
   }
 
-let getHighestBlockBelowThreshold = (cs: t): int => {
-  let highestBlockBelowThreshold = cs.fetchState.knownHeight - cs.maxReorgDepth
-  highestBlockBelowThreshold < 0 ? 0 : highestBlockBelowThreshold
-}
+// The block reorg detection compares from is itself in the window, so the
+// highest block below it is the one before, where catch-up stops.
+let getHighestBlockBelowThreshold = (cs: t): int =>
+  Pervasives.max(cs.fetchState.knownHeight - cs.maxReorgDepth - 1, 0)
 
 // True once the fetch frontier has reached the head/endBlock for this chain.
 let isFetchingAtHead = (cs: t) => cs.fetchState->FetchState.isFetchingAtHead
@@ -977,6 +983,34 @@ let materializePageItems = async (
   ))
 }
 
+// Near the head: each new block in as few queries as possible, of a shape that
+// stays the same while contracts keep being registered. Once every partition is
+// close enough, the chain's dynamic contracts leave the server-side address
+// filter for the rest of the run.
+//
+// Judged only when the chain learns a newer head. An RPC response repeats the
+// height its query went out with, which can be hours old by the end of a
+// backfill: judged against it, every block produced since would be fetched
+// address-free.
+let switchDynamicContractsToClientSideFilteringNearHead = (cs: t) =>
+  if (
+    !cs.fetchState.clientFilterPolicy.allDynamicContracts &&
+    cs.fetchState->FetchState.isWithinHeadClientFilteringDistance
+  ) {
+    cs.fetchState =
+      cs.fetchState->FetchState.switchDynamicContractsToClientSideFiltering(
+        ~addressStore=cs.addressStore,
+      )
+    if cs.onEventRegistrations->Array.some(registration => registration.contractRegister !== None) {
+      cs.logger->Logger.trace(
+        "Near the head: dynamic contracts are fetched without their addresses for the rest of the run, and filtered on our side.",
+        ~params={
+          "contractNames": cs.fetchState.optimizedPartitions.dynamicContracts->Utils.Set.toArray,
+        },
+      )
+    }
+  }
+
 let handleQueryResult = (
   cs: t,
   ~query: FetchState.query,
@@ -1000,6 +1034,7 @@ let handleQueryResult = (
     )
   }
 
+  let previousKnownHeight = cs.fetchState.knownHeight
   cs.fetchState =
     fs
     ->FetchState.handleQueryResult(~query, ~latestFetchedBlock, ~newItems)
@@ -1007,6 +1042,9 @@ let handleQueryResult = (
 
   // The query is no longer in flight, so release its reservation.
   cs.pendingBudget = Pervasives.max(0., cs.pendingBudget -. query.itemsEst->Int.toFloat)
+  if cs.fetchState.knownHeight > previousKnownHeight {
+    cs->switchDynamicContractsToClientSideFilteringNearHead
+  }
 }
 
 // Run reorg detection against a fetch response by merging its block-store page
@@ -1041,8 +1079,11 @@ let prepareReorg = (cs: t, ~eventsProcessedDiff) => {
   cs->resetPendingQueries
 }
 
-let updateKnownHeight = (cs: t, ~knownHeight) =>
+// A chain waiting at its head goes address-free before querying the new block.
+let updateKnownHeight = (cs: t, ~knownHeight) => {
   cs.fetchState = cs.fetchState->FetchState.updateKnownHeight(~knownHeight)
+  cs->switchDynamicContractsToClientSideFilteringNearHead
+}
 
 // In auto-exit mode, pin the endBlock to the earliest observed event block.
 let setEndBlockToFirstEvent = (cs: t, ~blockNumber) =>

package/src/ChainState.res.mjs

@@ -188,7 +188,7 @@ function makeFromDbState(chainConfig, resumedChainState, reorgCheckpoints, isInR
       tmp = undefined;
       break;
   }
-  let fetchState = FetchState.make(startBlock, endBlock, onEventRegistrations, addressStore, addressRows, config.maxAddrInPartition, chainConfig.id, notice => logFetchStateNotice(logger$1, notice), (config.batchSize << 1), knownHeight, progressBlockNumber, onBlockRegistrations, Primitive_int.max(!config.shouldRollbackOnReorg || isInReorgThreshold ? 0 : maxReorgDepth, chainConfig.blockLag), Primitive_option.some(firstEventBlock), Primitive_option.some(tmp), isResumed);
+  let fetchState = FetchState.make(startBlock, endBlock, onEventRegistrations, addressStore, addressRows, config.maxAddrInPartition, chainConfig.id, notice => logFetchStateNotice(logger$1, notice), (config.batchSize << 1), knownHeight, progressBlockNumber, onBlockRegistrations, Primitive_int.max(!config.shouldRollbackOnReorg || isInReorgThreshold || maxReorgDepth === 0 ? 0 : maxReorgDepth + 1 | 0, chainConfig.blockLag), chainConfig.blockThrottle, Primitive_option.some(firstEventBlock), Primitive_option.some(tmp), isResumed);
   let chainReorgCheckpoints = Stdlib_Array.filterMap(reorgCheckpoints, reorgCheckpoint => {
     if (reorgCheckpoint.chain_id === chainConfig.id) {
       return reorgCheckpoint;
@@ -196,7 +196,7 @@ function makeFromDbState(chainConfig, resumedChainState, reorgCheckpoints, isInR
   });
   let blockStore = BlockStore.make(config.ecosystem.name);
   let transactionStore = TransactionStore.make(config.ecosystem.name);
-  let sources = ChainSources.make(chainConfig, onEventRegistrations, onBlockRegistrations, addressStore, lowercaseAddresses, blockStore, transactionStore, logger$1);
+  let sources = ChainSources.make(chainConfig, onEventRegistrations, onBlockRegistrations, addressStore, lowercaseAddresses, blockStore, transactionStore, logger$1, config.maxAddrInPartition);
   if (Utils.$$Array.notEmpty(chainReorgCheckpoints)) {
     let seedPage = BlockStore.fromJs(chainReorgCheckpoints.map(cp => ({
       blockNumber: cp.block_number,
@@ -494,12 +494,7 @@ function takeFinished(cs) {
 }
 
 function getHighestBlockBelowThreshold(cs) {
-  let highestBlockBelowThreshold = cs.fetchState.knownHeight - cs.maxReorgDepth | 0;
-  if (highestBlockBelowThreshold < 0) {
-    return 0;
-  } else {
-    return highestBlockBelowThreshold;
-  }
+  return Primitive_int.max((cs.fetchState.knownHeight - cs.maxReorgDepth | 0) - 1 | 0, 0);
 }
 
 function isFetchingAtHead(cs) {
@@ -647,10 +642,27 @@ async function materializePageItems(items, transactionStore, blockStore, shouldC
   ]);
 }
 
+function switchDynamicContractsToClientSideFilteringNearHead(cs) {
+  if (!cs.fetchState.clientFilterPolicy.allDynamicContracts && FetchState.isWithinHeadClientFilteringDistance(cs.fetchState)) {
+    cs.fetchState = FetchState.switchDynamicContractsToClientSideFiltering(cs.fetchState, cs.addressStore);
+    if (cs.onEventRegistrations.some(registration => registration.contractRegister !== undefined)) {
+      return Logger.trace(cs.logger, "Near the head: dynamic contracts are fetched without their addresses for the rest of the run, and filtered on our side.", {
+        contractNames: Array.from(cs.fetchState.optimizedPartitions.dynamicContracts)
+      });
+    } else {
+      return;
+    }
+  }
+}
+
 function handleQueryResult(cs, query, newItems, newRegistrations, latestFetchedBlock, knownHeight) {
   let fs = newRegistrations.length !== 0 ? FetchState.registerDynamicContracts(cs.fetchState, cs.addressStore, notice => logFetchStateNotice(cs.logger, notice), Primitive_int.max(knownHeight, latestFetchedBlock), newRegistrations) : cs.fetchState;
+  let previousKnownHeight = cs.fetchState.knownHeight;
   cs.fetchState = FetchState.updateKnownHeight(FetchState.handleQueryResult(fs, query, latestFetchedBlock, newItems), knownHeight);
   cs.pendingBudget = Primitive_float.max(0, cs.pendingBudget - query.itemsEst);
+  if (cs.fetchState.knownHeight > previousKnownHeight) {
+    return switchDynamicContractsToClientSideFilteringNearHead(cs);
+  }
 }
 
 function registerReorgGuard(cs, blockStore, knownHeight) {
@@ -683,6 +695,7 @@ function prepareReorg(cs, eventsProcessedDiff) {
 
 function updateKnownHeight(cs, knownHeight) {
   cs.fetchState = FetchState.updateKnownHeight(cs.fetchState, knownHeight);
+  switchDynamicContractsToClientSideFilteringNearHead(cs);
 }
 
 function setEndBlockToFirstEvent(cs, blockNumber) {
@@ -700,12 +713,13 @@ function setEndBlockToFirstEvent(cs, blockNumber) {
       chainId: init.chainId,
       latestOnBlockBlockNumber: init.latestOnBlockBlockNumber,
       blockLag: init.blockLag,
+      blockThrottle: init.blockThrottle,
       buffer: init.buffer,
       maxOnBlockBufferSize: init.maxOnBlockBufferSize,
       onBlockRegistrations: init.onBlockRegistrations,
       knownHeight: init.knownHeight,
       firstEventBlock: init.firstEventBlock,
-      clientFilterAddressThreshold: init.clientFilterAddressThreshold
+      clientFilterPolicy: init.clientFilterPolicy
     };
     return;
   }
@@ -718,12 +732,13 @@ function setEndBlockToFirstEvent(cs, blockNumber) {
     chainId: init$1.chainId,
     latestOnBlockBlockNumber: init$1.latestOnBlockBlockNumber,
     blockLag: init$1.blockLag,
+    blockThrottle: init$1.blockThrottle,
     buffer: init$1.buffer,
     maxOnBlockBufferSize: init$1.maxOnBlockBufferSize,
     onBlockRegistrations: init$1.onBlockRegistrations,
     knownHeight: init$1.knownHeight,
     firstEventBlock: init$1.firstEventBlock,
-    clientFilterAddressThreshold: init$1.clientFilterAddressThreshold
+    clientFilterPolicy: init$1.clientFilterPolicy
   };
 }
 
@@ -881,12 +896,13 @@ function applyBatchProgress(cs, batch, blockTimestampName) {
         chainId: init.chainId,
         latestOnBlockBlockNumber: init.latestOnBlockBlockNumber,
         blockLag: init.blockLag,
+        blockThrottle: init.blockThrottle,
         buffer: init.buffer,
         maxOnBlockBufferSize: init.maxOnBlockBufferSize,
         onBlockRegistrations: init.onBlockRegistrations,
         knownHeight: init.knownHeight,
         firstEventBlock: firstEventBlock,
-        clientFilterAddressThreshold: init.clientFilterAddressThreshold
+        clientFilterPolicy: init.clientFilterPolicy
       };
     }
   }

package/src/Clock.res

@@ -0,0 +1,57 @@
+// What the source layer reads time from and arms its timers on. A test can hand
+// it a clock that only moves when the test moves it, which takes the scheduler
+// out of every race between a timer and the step a test is taking. The label
+// names a timer in that clock's timeline; the real clock ignores it.
+type timer
+
+type t = {
+  now: unit => float,
+  setTimeout: (~label: string, unit => unit, int) => timer,
+  clearTimeout: timer => unit,
+  random: unit => float,
+}
+
+// Test-only. Set while a test drives a run on virtual time, so code that reaches
+// past the clock it was given fails where it does, instead of arming a timer
+// the test can neither see nor move.
+let refuseReal = ref(false)
+
+let refused = what =>
+  JsError.throwWithMessage(
+    `Clock.real ${what} on virtual time. Use the clock the code was given, so advanceTime can see and move it.`,
+  )
+
+// Monotonic: every reading is only ever compared with another, and a wall
+// clock corrected mid-run would make a connection look like it served for
+// minutes, or a benched source look recovered.
+let real: t = {
+  now: () => refuseReal.contents ? refused("read the time") : Performance.now(),
+  // A zero delay is a turn of the event loop on either clock.
+  setTimeout: (~label, callback, millis) =>
+    refuseReal.contents && millis > 0
+      ? refused(`armed "${label}"`)
+      : setTimeout(callback, millis)->(Utils.magic: timeoutId => timer),
+  clearTimeout: timer => clearTimeout(timer->(Utils.magic: timer => timeoutId)),
+  random: Math.random,
+}
+
+let delay = (clock: t, ~label, millis) =>
+  Promise.make((resolve, _reject) => clock.setTimeout(~label, () => resolve(), millis)->ignore)
+
+// Half the delay fixed, half spread across it. Every indexer pointed at one
+// provider loses its stream, or gives up on a quiet chain, in the same instant
+// that provider blinks, and putting them all back on the same schedule is how a
+// blip becomes a stampede.
+let jitter = (clock: t, delay) =>
+  delay / 2 + (clock.random() *. (delay / 2)->Int.toFloat)->Float.toInt
+
+// Clearing a pending timer and forgetting it are one action. A ref left holding
+// a spent timer reads as one still pending, and the next clear looks like it
+// did something.
+let clearRef = (clock: t, timer: ref<option<timer>>) => {
+  switch timer.contents {
+  | Some(timer) => clock.clearTimeout(timer)
+  | None => ()
+  }
+  timer := None
+}