envio 3.5.0 → 3.5.1-svm-alpha.2

package/evm.schema.json

@@ -49,6 +49,13 @@
         }
       ]
     },
+    "disable_default_cross_chain": {
+      "description": "Make entities and effect caches per-chain instead of shared across every chain (recommended). Sharing then becomes explicit — add `@crossChain` to an entity in schema.graphql or `crossChain: true` to an effect. (default: false)",
+      "type": [
+        "boolean",
+        "null"
+      ]
+    },
     "ecosystem": {
       "description": "Ecosystem of the project.",
       "anyOf": [

package/fuel.schema.json

@@ -49,6 +49,13 @@
         }
       ]
     },
+    "disable_default_cross_chain": {
+      "description": "Make entities and effect caches per-chain instead of shared across every chain (recommended). Sharing then becomes explicit — add `@crossChain` to an entity in schema.graphql or `crossChain: true` to an effect. (default: false)",
+      "type": [
+        "boolean",
+        "null"
+      ]
+    },
     "ecosystem": {
       "description": "Ecosystem of the project.",
       "$ref": "#/$defs/EcosystemTag"

package/index.d.ts

@@ -48,8 +48,7 @@ export type EffectCaller = <I, O>(
   input: I extends undefined ? undefined : I
 ) => Promise<O>;
 
-/** The chain an Effect was called on. Available only on chain-scoped effects
- * (`crossChain: false`). */
+/** The chain an Effect was called on. Available only on chain-scoped effects. */
 export type EffectChain = {
   /** The chain id the effect handler was called on. */
   readonly id: number;
@@ -64,8 +63,8 @@ export type EffectContext = {
   /** Whether to cache this call's result. Defaults to the effect's `cache`
    * option; set to `false` to skip caching for this specific invocation. */
   cache: boolean;
-  /** The chain the effect was called on. Only available on effects created with
-   * `crossChain: false`; accessing it on a cross-chain effect throws. */
+  /** The chain the effect was called on. Only available on chain-scoped
+   * effects; accessing it on a cross-chain effect throws. */
   readonly chain: EffectChain;
 };
 
@@ -93,9 +92,10 @@ export type EffectOptions<Input, Output> = {
   /** Whether the effect should be cached. */
   readonly cache?: boolean;
   /** Whether the effect's cache is shared across all chains. Defaults to
-   * `true`. Set to `false` to isolate the cache and rate limiting per chain and
-   * enable `context.chain.id` inside the handler. Changing this changes the
-   * effect's cache identity. */
+   * `true`, or to `false` when config.yaml sets
+   * `disable_default_cross_chain: true`. Set to `false` to isolate the cache
+   * and rate limiting per chain and enable `context.chain.id` inside the
+   * handler. Changing this changes the effect's cache identity. */
   readonly crossChain?: boolean;
 };
 
@@ -225,8 +225,10 @@ export function createEffect<
     /** Whether the effect should be cached. */
     readonly cache?: boolean;
     /** Whether the effect's cache is shared across all chains. Defaults to
-     * `true`. Set to `false` to isolate the cache and rate limiting per chain
-     * and enable `context.chain.id` inside the handler. */
+     * `true`, or to `false` when config.yaml sets
+     * `disable_default_cross_chain: true`. Set to `false` to isolate the cache
+     * and rate limiting per chain and enable `context.chain.id` inside the
+     * handler. */
     readonly crossChain?: boolean;
   },
   handler: (args: EffectArgs<I>) => Promise<R>
@@ -502,6 +504,8 @@ type IndexerConfigTypes = {
   };
   svm?: { chains: Record<string, { id: number }> };
   entities?: Record<string, object>;
+  // Union of the entity names whose rows belong to a single chain, or `never`.
+  perChainEntities?: string;
   enums?: Record<string, string>;
 };
 
@@ -1529,6 +1533,21 @@ type AddressRegistration = {
 type ConfigEntities<Config extends IndexerConfigTypes = GlobalConfig> =
   Config["entities"] extends Record<string, object> ? Config["entities"] : {};
 
+/** Entity names whose rows belong to a single chain. */
+type PerChainEntityNames<Config extends IndexerConfigTypes = GlobalConfig> =
+  Config extends { perChainEntities: infer Names extends string } ? Names : never;
+
+/** The row shape the chain-agnostic test-indexer operations exchange. A
+ * per-chain entity's row is only identified together with its chain, so the
+ * chain id travels alongside the entity fields. */
+type TestIndexerEntityRow<
+  Config extends IndexerConfigTypes,
+  Name,
+  Entity
+> = Name extends PerChainEntityNames<Config>
+  ? Entity & { readonly chainId: number }
+  : Entity;
+
 /** Entity operations available on test indexer for direct entity manipulation. */
 type TestIndexerEntityOperations<Entity> = {
   /** Get an entity by ID. Returns undefined if not found. */
@@ -1537,6 +1556,10 @@ type TestIndexerEntityOperations<Entity> = {
   readonly getOrThrow: (id: EntityId<Entity>, message?: string) => Promise<Entity>;
   /** Get all entities. */
   readonly getAll: () => Promise<Entity[]>;
+  /** Get the entities matching a filter. For a per-chain entity the filter
+   * accepts `chainId`, which is how an id present on several chains is
+   * narrowed to one. */
+  readonly getWhere: (filter: GetWhereFilter<Entity>) => Promise<Entity[]>;
   /** Set (create or update) an entity. */
   readonly set: (entity: Entity) => void;
 };
@@ -1711,7 +1734,7 @@ export type TestIndexerFromConfig<Config extends IndexerConfigTypes = GlobalConf
 } & SingleEcosystemTestChains<Config> & {
   /** Entity operations for direct manipulation outside of handlers. */
   readonly [K in keyof ConfigEntities<Config>]: TestIndexerEntityOperations<
-    ConfigEntities<Config>[K]
+    TestIndexerEntityRow<Config, K, ConfigEntities<Config>[K]>
   >;
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "envio",
-  "version": "3.5.0",
+  "version": "3.5.1-svm-alpha.2",
   "type": "module",
   "description": "A latency and sync speed optimized, developer friendly blockchain data indexer.",
   "bin": "./bin.mjs",
@@ -69,10 +69,10 @@
     "tsx": "4.21.0"
   },
   "optionalDependencies": {
-    "envio-linux-x64": "3.5.0",
-    "envio-linux-x64-musl": "3.5.0",
-    "envio-linux-arm64": "3.5.0",
-    "envio-darwin-x64": "3.5.0",
-    "envio-darwin-arm64": "3.5.0"
+    "envio-linux-x64": "3.5.1-svm-alpha.2",
+    "envio-linux-x64-musl": "3.5.1-svm-alpha.2",
+    "envio-linux-arm64": "3.5.1-svm-alpha.2",
+    "envio-darwin-x64": "3.5.1-svm-alpha.2",
+    "envio-darwin-arm64": "3.5.1-svm-alpha.2"
   }
 }

package/src/ChainFetching.res

@@ -24,25 +24,15 @@ let runContractRegistersOrThrow = async (
     ~ecosystem=config.ecosystem.name,
   )
 
-  let itemsWithDcs = []
+  let registrations: array<AddressStore.registration> = []
 
   let onRegister = (~item: Internal.item, ~contractAddress, ~contractName) => {
     let eventItem = item->Internal.castUnsafeEventItem
-    let {blockNumber} = eventItem
-
-    let dc: Internal.indexingAddress = {
+    registrations->Array.push({
       address: contractAddress,
       contractName,
-      registrationBlock: blockNumber,
-    }
-
-    switch item->Internal.getItemDcs {
-    | None => {
-        item->Internal.setItemDcs([dc])
-        itemsWithDcs->Array.push(item)
-      }
-    | Some(dcs) => dcs->Array.push(dc)
-    }
+      registrationBlock: eventItem.blockNumber,
+    })
   }
 
   let promises = []
@@ -101,7 +91,7 @@ let runContractRegistersOrThrow = async (
     let _ = await Promise.all(promises)
   }
 
-  itemsWithDcs
+  registrations
 }
 
 let rec onQueryResponse = async (
@@ -226,13 +216,13 @@ let rec onQueryResponse = async (
 
       // Re-check staleness: contract registration is async, so the chain state
       // may have rolled back by the time we apply the fetched items.
-      let proceed = (~newItemsWithDcs) =>
+      let proceed = (~newRegistrations) =>
         if !(state->IndexerState.isStale(~stateId)) {
           applyQueryResponse(
             state,
             ~chainId,
             ~newItems,
-            ~newItemsWithDcs,
+            ~newRegistrations,
             ~knownHeight,
             ~latestFetchedBlock={
               FetchState.blockNumber: latestFetchedBlockNumber,
@@ -248,7 +238,7 @@ let rec onQueryResponse = async (
         }
 
       switch itemsWithContractRegister {
-      | [] => proceed(~newItemsWithDcs=[])
+      | [] => proceed(~newRegistrations=[])
       | _ =>
         switch await runContractRegistersOrThrow(
           ~itemsWithContractRegister,
@@ -257,7 +247,7 @@ let rec onQueryResponse = async (
           ~blockStore,
         ) {
         | exception exn => IndexerState.errorExit(state, exn->ErrorHandling.make)
-        | newItemsWithDcs => proceed(~newItemsWithDcs)
+        | newRegistrations => proceed(~newRegistrations)
         }
       }
     }
@@ -267,7 +257,7 @@ and applyQueryResponse = (
   state: IndexerState.t,
   ~chainId,
   ~newItems,
-  ~newItemsWithDcs,
+  ~newRegistrations,
   ~knownHeight,
   ~latestFetchedBlock,
   ~query,
@@ -281,7 +271,7 @@ and applyQueryResponse = (
     ~query,
     ~latestFetchedBlock,
     ~newItems,
-    ~newItemsWithDcs,
+    ~newRegistrations,
     ~knownHeight,
     ~transactionStore,
     ~blockStore,

package/src/ChainFetching.res.mjs

@@ -18,21 +18,13 @@ import * as ContractRegisterContext from "./ContractRegisterContext.res.mjs";
 
 async function runContractRegistersOrThrow(itemsWithContractRegister, config, transactionStore, blockStore) {
   await ChainState.materializePageItems(itemsWithContractRegister, transactionStore, blockStore, config.ecosystem.name);
-  let itemsWithDcs = [];
+  let registrations = [];
   let onRegister = (item, contractAddress, contractName) => {
-    let dc_registrationBlock = item.blockNumber;
-    let dc = {
+    registrations.push({
       address: contractAddress,
       contractName: contractName,
-      registrationBlock: dc_registrationBlock
-    };
-    let dcs = item.dcs;
-    if (dcs !== undefined) {
-      dcs.push(dc);
-    } else {
-      item.dcs = [dc];
-      itemsWithDcs.push(item);
-    }
+      registrationBlock: item.blockNumber
+    });
   };
   let promises = [];
   for (let idx = 0, idx_finish = itemsWithContractRegister.length; idx < idx_finish; ++idx) {
@@ -68,13 +60,13 @@ async function runContractRegistersOrThrow(itemsWithContractRegister, config, tr
   if (Utils.$$Array.notEmpty(promises)) {
     await Promise.all(promises);
   }
-  return itemsWithDcs;
+  return registrations;
 }
 
-function applyQueryResponse(state, chainId, newItems, newItemsWithDcs, knownHeight, latestFetchedBlock, query, transactionStore, blockStore) {
+function applyQueryResponse(state, chainId, newItems, newRegistrations, knownHeight, latestFetchedBlock, query, transactionStore, blockStore) {
   let chainState = IndexerState.getChainState(state, chainId);
   let wasFetchingAtHead = ChainState.isFetchingAtHead(chainState);
-  ChainState.handleQueryResult(chainState, query, newItems, newItemsWithDcs, latestFetchedBlock, knownHeight, transactionStore, blockStore);
+  ChainState.handleQueryResult(chainState, query, newItems, newRegistrations, latestFetchedBlock, knownHeight, transactionStore, blockStore);
   if (IndexerState.exitAfterFirstEventBlock(state) && newItems.length !== 0) {
     ChainState.setEndBlockToFirstEvent(chainState, newItems[0].blockNumber);
   }
@@ -152,9 +144,9 @@ async function onQueryResponse(state, param, stateId, scheduleFetch, schedulePro
       itemsWithContractRegister.push(item);
     }
   }
-  let proceed = newItemsWithDcs => {
+  let proceed = newRegistrations => {
     if (!IndexerState.isStale(state, stateId)) {
-      applyQueryResponse(state, chainId, parsedQueueItems, newItemsWithDcs, knownHeight, {
+      applyQueryResponse(state, chainId, parsedQueueItems, newRegistrations, knownHeight, {
         blockNumber: latestFetchedBlockNumber,
         blockTimestamp: latestFetchedBlockTimestamp
       }, query, transactionStore, blockStore);
@@ -166,14 +158,14 @@ async function onQueryResponse(state, param, stateId, scheduleFetch, schedulePro
   if (itemsWithContractRegister.length === 0) {
     return proceed([]);
   }
-  let newItemsWithDcs;
+  let newRegistrations;
   try {
-    newItemsWithDcs = await runContractRegistersOrThrow(itemsWithContractRegister, IndexerState.config(state), transactionStore, blockStore);
+    newRegistrations = await runContractRegistersOrThrow(itemsWithContractRegister, IndexerState.config(state), transactionStore, blockStore);
   } catch (raw_exn) {
     let exn = Primitive_exceptions.internalToException(raw_exn);
     return IndexerState.errorExit(state, ErrorHandling.make(exn, undefined, undefined));
   }
-  return proceed(newItemsWithDcs);
+  return proceed(newRegistrations);
 }
 
 function finishWaitingForNewBlock(state, chainId, knownHeight, stateId, scheduleFetch, scheduleProcessing) {

package/src/ChainState.res

@@ -31,6 +31,10 @@ type t = {
   // then smoothed with an EMA on every batch (see applyBatchProgress). None
   // until the chain has processed at least one event.
   mutable chainDensity: option<float>,
+  // In-memory tables for the entities whose rows belong to a single chain.
+  // Empty in the default cross-chain mode, where every entity's table lives on
+  // the indexer instead.
+  mutable entities: EntityTables.t,
   mutable reorgDetection: ReorgDetection.t,
   mutable safeCheckpointTracking: option<SafeCheckpointTracking.t>,
   // Holds this chain's transactions (kept in Rust) keyed by (blockNumber,
@@ -96,11 +100,13 @@ let make = (
   ~chainDensity=None,
   ~blockStore=BlockStore.make(~ecosystem=Ecosystem.Evm, ~shouldChecksum=false),
   ~reorgThresholdReadyTolerance=100,
+  ~perChainEntities: array<Internal.entityConfig>=[],
   ~logger: Pino.t,
 ): t => {
   validateOnEventRegistrations(~chainId=chainConfig.id, onEventRegistrations)
   {
     logger,
+    entities: EntityTables.make(perChainEntities),
     onEventRegistrations,
     fetchState,
     addressStore,
@@ -130,6 +136,19 @@ let make = (
   }
 }
 
+// Every chain's contracts, not just one chain's: `context.chain.X.add` accepts
+// any config contract, whichever chain declared it, so every chain's address
+// store has to hold the whole set.
+let configContractNames = (config: Config.t) => {
+  let names = Utils.Set.make()
+  config.chainMap
+  ->ChainMap.values
+  ->Array.forEach(chain =>
+    chain.contracts->Array.forEach(contract => names->Utils.Set.add(contract.name)->ignore)
+  )
+  names->Utils.Set.toArray
+}
+
 let makeInternal = (
   ~chainConfig: Config.chain,
   ~indexingAddresses: array<Internal.indexingAddress>,
@@ -174,7 +193,10 @@ let makeInternal = (
   let addressStore = AddressStore.make(
     ~ecosystem=config.ecosystem.name,
     ~shouldChecksum=!lowercaseAddresses,
-    ~contracts=AddressStore.contractsOf(~onEventRegistrations),
+    ~contracts=AddressStore.contractsOf(
+      ~onEventRegistrations,
+      ~configContractNames=config->configContractNames,
+    ),
   )
 
   let fetchState = FetchState.make(
@@ -302,6 +324,7 @@ let makeInternal = (
       ~chainReorgCheckpoints,
     ),
     ~committedProgressBlockNumber=progressBlockNumber,
+    ~perChainEntities=config.allEntities->EntityTables.perChain,
     ~timestampCaughtUpToHeadOrEndblock,
     ~numEventsProcessed,
     ~transactionStore=TransactionStore.make(
@@ -392,6 +415,11 @@ let makeFromDbState = (
 // --- Read accessors. ---
 
 let logger = (cs: t) => cs.logger
+let entities = (cs: t) => cs.entities
+
+// Rollback discards every uncommitted change, so this chain's partition is
+// rebuilt from scratch alongside the indexer's cross-chain one.
+let resetEntities = (cs: t, ~perChainEntities) => cs.entities = EntityTables.make(perChainEntities)
 let sourceManager = (cs: t) => cs.sourceManager
 let chainConfig = (cs: t) => cs.chainConfig
 let reorgDetection = (cs: t) => cs.reorgDetection
@@ -430,6 +458,15 @@ let setRollbackTargetBlock = (cs: t, ~blockNumber) => cs.rollbackTargetBlock = S
 let knownHeight = (cs: t) => cs.fetchState.knownHeight
 let contractAddresses = (cs: t, ~contractName) =>
   cs.addressStore->AddressStore.contractAddresses(contractName)
+
+// Hands over the dynamically registered addresses the database hasn't seen yet,
+// up to the block the caller is about to commit, each paired with the checkpoint
+// that owns its row. Destructive: the caller must persist them or take the
+// indexer down. Throws with nothing consumed when a registration's block has no
+// checkpoint in the batch.
+let drainAddressesForWrite = (cs: t, ~toBlockInclusive, ~checkpointBlockNumbers) =>
+  cs.addressStore->AddressStore.drainForWrite(toBlockInclusive, checkpointBlockNumbers)
+let hasAddressesToWrite = (cs: t) => cs.addressStore->AddressStore.pendingCount > 0
 let bufferSize = (cs: t) => cs.fetchState->FetchState.bufferSize
 let bufferReadyCount = (cs: t) => cs.fetchState->FetchState.bufferReadyCount
 let getProgressPercentage = (cs: t) => cs.fetchState->FetchState.getProgressPercentage
@@ -841,7 +878,7 @@ let handleQueryResult = (
   cs: t,
   ~query: FetchState.query,
   ~newItems,
-  ~newItemsWithDcs,
+  ~newRegistrations,
   ~latestFetchedBlock: FetchState.blockNumberAndTimestamp,
   ~knownHeight,
   ~transactionStore as txPage: option<TransactionStore.t>,
@@ -858,7 +895,7 @@ let handleQueryResult = (
   | None => ()
   }
 
-  let fs = switch newItemsWithDcs {
+  let fs = switch newRegistrations {
   | [] => cs.fetchState
   | _ =>
     cs.fetchState->FetchState.registerDynamicContracts(
@@ -868,7 +905,7 @@ let handleQueryResult = (
       // catch-up range — and an unbounded query can reach past the height that
       // was known when it went out.
       ~claimCeiling=Pervasives.max(knownHeight, latestFetchedBlock.blockNumber),
-      newItemsWithDcs,
+      newRegistrations,
     )
   }
 

package/src/ChainState.res.mjs

@@ -6,12 +6,14 @@ import * as Batch from "./Batch.res.mjs";
 import * as Utils from "./Utils.res.mjs";
 import * as ChainId from "./ChainId.res.mjs";
 import * as Logging from "./Logging.res.mjs";
+import * as ChainMap from "./ChainMap.res.mjs";
 import * as EvmChain from "./sources/EvmChain.res.mjs";
 import * as FieldMask from "./sources/FieldMask.res.mjs";
 import * as BlockStore from "./sources/BlockStore.res.mjs";
 import * as FetchState from "./FetchState.res.mjs";
 import * as Stdlib_Null from "@rescript/runtime/lib/es6/Stdlib_Null.js";
 import * as AddressStore from "./sources/AddressStore.res.mjs";
+import * as EntityTables from "./EntityTables.res.mjs";
 import * as Stdlib_Array from "@rescript/runtime/lib/es6/Stdlib_Array.js";
 import * as Primitive_int from "@rescript/runtime/lib/es6/Primitive_int.js";
 import * as SourceManager from "./sources/SourceManager.res.mjs";
@@ -48,7 +50,7 @@ function validateOnEventRegistrations(chainId, registrations) {
   });
 }
 
-function make(chainConfig, fetchState, onEventRegistrationsOpt, addressStore, sourceManager, reorgDetection, committedProgressBlockNumber, safeCheckpointTrackingOpt, numEventsProcessedOpt, timestampCaughtUpToHeadOrEndblockOpt, isProgressAtHeadOpt, transactionStoreOpt, chainDensityOpt, blockStoreOpt, reorgThresholdReadyToleranceOpt, logger) {
+function make(chainConfig, fetchState, onEventRegistrationsOpt, addressStore, sourceManager, reorgDetection, committedProgressBlockNumber, safeCheckpointTrackingOpt, numEventsProcessedOpt, timestampCaughtUpToHeadOrEndblockOpt, isProgressAtHeadOpt, transactionStoreOpt, chainDensityOpt, blockStoreOpt, reorgThresholdReadyToleranceOpt, perChainEntitiesOpt, logger) {
   let onEventRegistrations = onEventRegistrationsOpt !== undefined ? onEventRegistrationsOpt : [];
   let safeCheckpointTracking = safeCheckpointTrackingOpt !== undefined ? Primitive_option.valFromOption(safeCheckpointTrackingOpt) : undefined;
   let numEventsProcessed = numEventsProcessedOpt !== undefined ? numEventsProcessedOpt : 0;
@@ -58,6 +60,7 @@ function make(chainConfig, fetchState, onEventRegistrationsOpt, addressStore, so
   let chainDensity = chainDensityOpt !== undefined ? Primitive_option.valFromOption(chainDensityOpt) : undefined;
   let blockStore = blockStoreOpt !== undefined ? Primitive_option.valFromOption(blockStoreOpt) : BlockStore.make("evm", false);
   let reorgThresholdReadyTolerance = reorgThresholdReadyToleranceOpt !== undefined ? reorgThresholdReadyToleranceOpt : 100;
+  let perChainEntities = perChainEntitiesOpt !== undefined ? perChainEntitiesOpt : [];
   validateOnEventRegistrations(chainConfig.id, onEventRegistrations);
   return {
     logger: logger,
@@ -73,6 +76,7 @@ function make(chainConfig, fetchState, onEventRegistrationsOpt, addressStore, so
     numEventsProcessed: numEventsProcessed,
     pendingBudget: 0,
     chainDensity: chainDensity,
+    entities: EntityTables.make(perChainEntities),
     reorgDetection: reorgDetection,
     safeCheckpointTracking: safeCheckpointTracking,
     transactionStore: transactionStore,
@@ -90,6 +94,16 @@ function make(chainConfig, fetchState, onEventRegistrationsOpt, addressStore, so
   };
 }
 
+function configContractNames(config) {
+  let names = new Set();
+  ChainMap.values(config.chainMap).forEach(chain => {
+    chain.contracts.forEach(contract => {
+      names.add(contract.name);
+    });
+  });
+  return Array.from(names);
+}
+
 function makeInternal(chainConfig, indexingAddresses, startBlock, endBlock, firstEventBlockOpt, progressBlockNumber, config, registrationsByChainId, logger, timestampCaughtUpToHeadOrEndblock, numEventsProcessed, isInReorgThreshold, isRealtime, reorgCheckpoints, maxReorgDepth, knownHeightOpt, isResumedOpt, reducedPollingInterval) {
   let firstEventBlock = firstEventBlockOpt !== undefined ? Primitive_option.valFromOption(firstEventBlockOpt) : undefined;
   let knownHeight = knownHeightOpt !== undefined ? knownHeightOpt : 0;
@@ -106,7 +120,7 @@ function makeInternal(chainConfig, indexingAddresses, startBlock, endBlock, firs
     }
   });
   let lowercaseAddresses = config.lowercaseAddresses;
-  let addressStore = AddressStore.make(config.ecosystem.name, !lowercaseAddresses, AddressStore.contractsOf(onEventRegistrations));
+  let addressStore = AddressStore.make(config.ecosystem.name, !lowercaseAddresses, AddressStore.contractsOf(onEventRegistrations, configContractNames(config)));
   let match$1 = config.ecosystem.name;
   let tmp;
   switch (match$1) {
@@ -175,7 +189,7 @@ function makeInternal(chainConfig, indexingAddresses, startBlock, endBlock, firs
   }
   let firstEventBlock$1 = fetchState.firstEventBlock;
   let chainDensity = firstEventBlock$1 !== undefined && progressBlockNumber > firstEventBlock$1 && numEventsProcessed > 0 ? numEventsProcessed / (progressBlockNumber - firstEventBlock$1 | 0) : undefined;
-  return make(chainConfig, fetchState, onEventRegistrations, addressStore, SourceManager.make(sources$1, isRealtime, undefined, undefined, undefined, reducedPollingInterval, undefined, undefined), ReorgDetection.make(chainReorgCheckpoints, maxReorgDepth, config.shouldRollbackOnReorg), progressBlockNumber, Primitive_option.some(SafeCheckpointTracking.make(maxReorgDepth, config.shouldRollbackOnReorg, chainReorgCheckpoints)), numEventsProcessed, Primitive_option.some(timestampCaughtUpToHeadOrEndblock), undefined, Primitive_option.some(TransactionStore.make(config.ecosystem.name, !lowercaseAddresses)), Primitive_option.some(chainDensity), Primitive_option.some(BlockStore.make(config.ecosystem.name, !lowercaseAddresses)), config.reorgThresholdReadyTolerance, logger);
+  return make(chainConfig, fetchState, onEventRegistrations, addressStore, SourceManager.make(sources$1, isRealtime, undefined, undefined, undefined, reducedPollingInterval, undefined, undefined), ReorgDetection.make(chainReorgCheckpoints, maxReorgDepth, config.shouldRollbackOnReorg), progressBlockNumber, Primitive_option.some(SafeCheckpointTracking.make(maxReorgDepth, config.shouldRollbackOnReorg, chainReorgCheckpoints)), numEventsProcessed, Primitive_option.some(timestampCaughtUpToHeadOrEndblock), undefined, Primitive_option.some(TransactionStore.make(config.ecosystem.name, !lowercaseAddresses)), Primitive_option.some(chainDensity), Primitive_option.some(BlockStore.make(config.ecosystem.name, !lowercaseAddresses)), config.reorgThresholdReadyTolerance, EntityTables.perChain(config.allEntities), logger);
 }
 
 function makeFromConfig(chainConfig, config, registrationsByChainId, knownHeight) {
@@ -198,6 +212,14 @@ function logger(cs) {
   return cs.logger;
 }
 
+function entities(cs) {
+  return cs.entities;
+}
+
+function resetEntities(cs, perChainEntities) {
+  cs.entities = EntityTables.make(perChainEntities);
+}
+
 function sourceManager(cs) {
   return cs.sourceManager;
 }
@@ -259,6 +281,14 @@ function contractAddresses(cs, contractName) {
   return cs.addressStore.contractAddresses(contractName);
 }
 
+function drainAddressesForWrite(cs, toBlockInclusive, checkpointBlockNumbers) {
+  return cs.addressStore.drainForWrite(toBlockInclusive, checkpointBlockNumbers);
+}
+
+function hasAddressesToWrite(cs) {
+  return cs.addressStore.pendingCount() > 0;
+}
+
 function bufferSize(cs) {
   return FetchState.bufferSize(cs.fetchState);
 }
@@ -565,14 +595,14 @@ async function materializePageItems(items, transactionStore, blockStore, ecosyst
   ]);
 }
 
-function handleQueryResult(cs, query, newItems, newItemsWithDcs, latestFetchedBlock, knownHeight, txPage, blockPage) {
+function handleQueryResult(cs, query, newItems, newRegistrations, latestFetchedBlock, knownHeight, txPage, blockPage) {
   if (txPage !== undefined) {
     cs.transactionStore.merge(Primitive_option.valFromOption(txPage));
   }
   if (blockPage !== undefined) {
     cs.blockStore.merge(Primitive_option.valFromOption(blockPage));
   }
-  let fs = newItemsWithDcs.length !== 0 ? FetchState.registerDynamicContracts(cs.fetchState, cs.addressStore, Primitive_int.max(knownHeight, latestFetchedBlock.blockNumber), newItemsWithDcs) : cs.fetchState;
+  let fs = newRegistrations.length !== 0 ? FetchState.registerDynamicContracts(cs.fetchState, cs.addressStore, Primitive_int.max(knownHeight, latestFetchedBlock.blockNumber), newRegistrations) : cs.fetchState;
   cs.fetchState = FetchState.updateKnownHeight(FetchState.handleQueryResult(fs, query, latestFetchedBlock, newItems), knownHeight);
   cs.pendingBudget = Primitive_float.max(0, cs.pendingBudget - query.itemsEst);
 }
@@ -822,6 +852,8 @@ export {
   makeFromConfig,
   makeFromDbState,
   logger,
+  entities,
+  resetEntities,
   sourceManager,
   chainConfig,
   reorgDetection,
@@ -837,6 +869,8 @@ export {
   setRollbackTargetBlock,
   knownHeight,
   contractAddresses,
+  drainAddressesForWrite,
+  hasAddressesToWrite,
   bufferSize,
   bufferReadyCount,
   getProgressPercentage,

package/src/ChainState.resi

@@ -21,6 +21,7 @@ let make: (
   ~chainDensity: option<float>=?,
   ~blockStore: BlockStore.t=?,
   ~reorgThresholdReadyTolerance: int=?,
+  ~perChainEntities: array<Internal.entityConfig>=?,
   ~logger: Pino.t,
 ) => t
 
@@ -44,6 +45,8 @@ let makeFromDbState: (
 
 // Accessors.
 let logger: t => Pino.t
+let entities: t => EntityTables.t
+let resetEntities: (t, ~perChainEntities: array<Internal.entityConfig>) => unit
 let sourceManager: t => SourceManager.t
 let chainConfig: t => Config.chain
 let reorgDetection: t => ReorgDetection.t
@@ -69,6 +72,12 @@ let setRollbackTargetBlock: (t, ~blockNumber: int) => unit
 // Fetch-frontier reads.
 let knownHeight: t => int
 let contractAddresses: (t, ~contractName: string) => array<Address.t>
+let drainAddressesForWrite: (
+  t,
+  ~toBlockInclusive: int,
+  ~checkpointBlockNumbers: array<int>,
+) => array<AddressStore.drainedAddress>
+let hasAddressesToWrite: t => bool
 let bufferSize: t => int
 let bufferReadyCount: t => int
 let getProgressPercentage: t => float
@@ -110,7 +119,7 @@ let handleQueryResult: (
   t,
   ~query: FetchState.query,
   ~newItems: array<Internal.item>,
-  ~newItemsWithDcs: array<Internal.item>,
+  ~newRegistrations: array<AddressStore.registration>,
   ~latestFetchedBlock: FetchState.blockNumberAndTimestamp,
   ~knownHeight: int,
   ~transactionStore: option<TransactionStore.t>,