@aztec/aztec-node 5.3.0-nightly.20260821 → 5.3.0-nightly.20260823

package/dest/modules/unseen_block_hold_off.js

@@ -0,0 +1,150 @@
+import { createLogger } from '@aztec/foundation/log';
+import { InterruptibleSleep } from '@aztec/foundation/sleep';
+import { Timer } from '@aztec/foundation/timer';
+import { L2BlockSourceEvents, getBlockSourceEmitter, inspectBlockParameter } from '@aztec/stdlib/block';
+/**
+ * Longest a held request sleeps before re-reading the block source anyway. Held requests are woken by the source
+ * reporting an update, so this only bounds how long one waits when it misses the update that added its block: the
+ * source can commit between a request's read and its sleep, and a request that is not sleeping yet is not woken.
+ */ const MAX_SLEEP_MS = 1000;
+/** Max requests held simultaneously. Beyond this, misses fail fast as if the hold-off were disabled. */ export const MAX_CONCURRENT_HOLDS = 100;
+/**
+ * Resolves RPC block anchors against the block source, briefly holding a request whose anchor the node is about to
+ * see instead of failing it immediately.
+ *
+ * Behind a load balancer a client can sync to block N+1 through one node and then anchor follow-up queries against
+ * another node that is still at block N. Failing those queries aborts a whole client flow over a skew that resolves
+ * in under a block time, so a miss on an anchor that plausibly lies just ahead of the tip is retried for a bounded
+ * budget. Everything else — a tag, a number far past the tip, a budget of zero, or too many requests already held —
+ * resolves exactly as the bare block source would.
+ *
+ * Held requests do not poll at a rate of their own choosing: they all sleep on one wake-up that the block source
+ * triggers when it reports it moved, so the source is read when there is something new to read and, failing that, at
+ * most once per {@link MAX_SLEEP_MS}. A source that reports no updates cannot wake them, so it never holds anything
+ * off.
+ */ export class UnseenBlockHoldOff {
+    blockSource;
+    config;
+    activeHolds;
+    log;
+    /** Shared by every held request; interrupted on a source update. Undefined for a source that reports none. */ wakeup;
+    constructor(blockSource, config, log){
+        this.blockSource = blockSource;
+        this.config = config;
+        this.activeHolds = 0;
+        this.log = log ?? createLogger('node:unseen-block-hold-off');
+        const emitter = getBlockSourceEmitter(blockSource);
+        if (emitter === undefined) {
+            this.log.verbose(`Block source reports no updates, queries for unseen blocks will not be held off`);
+        } else {
+            const wakeup = new InterruptibleSleep();
+            this.wakeup = wakeup;
+            emitter.on(L2BlockSourceEvents.L2BlockSourceUpdated, ()=>wakeup.interrupt());
+        }
+    }
+    /** Number of requests currently held waiting for their anchor block. Exposed for tests and diagnostics. */ get holds() {
+        return this.activeHolds;
+    }
+    /**
+   * Resolves `query` to block metadata, holding off briefly when it references a block the node is about to see.
+   * Returns undefined on a miss, so callers keep whatever behavior they had before (throwing or returning
+   * undefined) — the hold-off only delays that outcome.
+   */ getBlockData(query, opts = {}) {
+        return this.#readWithHoldOff(query, (q)=>this.blockSource.getBlockData(q), opts);
+    }
+    /** Resolves `query` to a full block with its transactions, holding off as {@link getBlockData} does. */ getBlock(query, opts = {}) {
+        return this.#readWithHoldOff(query, (q)=>this.blockSource.getBlock(q), opts);
+    }
+    /**
+   * Reads `query` through `read`, and on a miss waits for the block it names before reading once more. Subject to the
+   * concurrent-hold cap: once it is saturated a miss resolves without waiting, as it would with the hold-off
+   * disabled.
+   */ async #readWithHoldOff(query, read, opts) {
+        const value = await read(query);
+        if (value !== undefined || opts.holdOff === false) {
+            return value;
+        }
+        const arrived = await this.#waitForBlock(query, await this.#resolveWaitBudgetMs(query));
+        return arrived ? await read(query) : undefined;
+    }
+    /**
+   * Waits for the block `query` names to show up on the block source, for at most `waitMs`, and reports whether it
+   * did. Returns false without waiting when the source reports no updates, when the budget is empty, or when the
+   * concurrent-hold cap is saturated, so a miss fails as fast as it would with the hold-off disabled.
+   *
+   * Arrival is checked on block metadata rather than through the caller's read, so a held request costs a metadata
+   * read per wake-up whatever it asked for: a held `getBlock` would otherwise reconstruct a whole block with its
+   * transactions on every wake-up only to find it is not the one it is waiting for.
+   *
+   * A budget is approximate: the deadline is only re-checked after a sleep, so the actual wait can exceed it by the
+   * read's own latency.
+   */ async #waitForBlock(query, waitMs) {
+        const wakeup = this.wakeup;
+        if (wakeup === undefined || !Number.isFinite(waitMs) || waitMs <= 0) {
+            return false;
+        }
+        const blockParameter = inspectBlockParameter(query);
+        if (this.activeHolds >= MAX_CONCURRENT_HOLDS) {
+            this.log.verbose(`Not holding off query for unseen block, too many requests already held`, {
+                blockParameter,
+                holds: this.activeHolds
+            });
+            return false;
+        }
+        this.activeHolds++;
+        const timer = new Timer();
+        try {
+            this.log.verbose(`Holding off query for unseen block`, {
+                blockParameter,
+                waitMs,
+                holds: this.activeHolds
+            });
+            while(timer.ms() < waitMs){
+                await wakeup.sleep(Math.min(waitMs - timer.ms(), MAX_SLEEP_MS));
+                const data = await this.blockSource.getBlockData(query);
+                if (data !== undefined) {
+                    this.log.verbose(`Unseen block arrived after ${timer.ms()}ms`, {
+                        blockParameter,
+                        blockNumber: data.header.getBlockNumber(),
+                        elapsedMs: timer.ms()
+                    });
+                    return true;
+                }
+            }
+            this.log.verbose(`Gave up waiting for unseen block after ${timer.ms()}ms`, {
+                blockParameter,
+                waitMs,
+                elapsedMs: timer.ms()
+            });
+            return false;
+        } finally{
+            this.activeHolds--;
+        }
+    }
+    /**
+   * Budget for waiting on a missing anchor, decided once on entry rather than per wake-up. A tag always resolves
+   * against the current tip, so a tag miss is never a skew. A number is only worth waiting on when it is the very
+   * next block: further ahead the client is not merely one block in front, and at or below the tip the block was
+   * pruned or reorged away. A hash or archive root carries no height, so "one ahead" and "reorged away" are
+   * indistinguishable and both get the shorter hash budget.
+   *
+   * The genesis block hash is the one hash never worth waiting on: a client anchors on it before it has synced any
+   * block (as a PXE does for its first tagged-log queries), and the block is synthetic, so a source that does not
+   * answer for it now never will.
+   */ async #resolveWaitBudgetMs(query) {
+        if ('tag' in query) {
+            return 0;
+        }
+        if ('number' in query) {
+            const tip = await this.blockSource.getBlockNumber();
+            return query.number === tip + 1 ? this.config.byNumberWaitMs : 0;
+        }
+        if ('hash' in query && this.#isGenesisBlockHash(query.hash)) {
+            return 0;
+        }
+        return this.config.byHashWaitMs;
+    }
+    /** True when `hash` names the synthetic genesis block, which never arrives and so is never waited for. */ #isGenesisBlockHash(hash) {
+        return hash.equals(this.blockSource.getGenesisBlockHash());
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aztec/aztec-node",
-  "version": "5.3.0-nightly.20260821",
+  "version": "5.3.0-nightly.20260823",
   "main": "dest/index.js",
   "type": "module",
   "exports": {
@@ -65,33 +65,33 @@
     ]
   },
   "dependencies": {
-    "@aztec/archiver": "5.3.0-nightly.20260821",
-    "@aztec/bb-prover": "5.3.0-nightly.20260821",
-    "@aztec/bb.js": "5.3.0-nightly.20260821",
-    "@aztec/blob-client": "5.3.0-nightly.20260821",
-    "@aztec/blob-lib": "5.3.0-nightly.20260821",
-    "@aztec/constants": "5.3.0-nightly.20260821",
-    "@aztec/epoch-cache": "5.3.0-nightly.20260821",
-    "@aztec/ethereum": "5.3.0-nightly.20260821",
-    "@aztec/foundation": "5.3.0-nightly.20260821",
-    "@aztec/kv-store": "5.3.0-nightly.20260821",
-    "@aztec/l1-artifacts": "5.3.0-nightly.20260821",
-    "@aztec/node-keystore": "5.3.0-nightly.20260821",
-    "@aztec/node-lib": "5.3.0-nightly.20260821",
-    "@aztec/noir-protocol-circuits-types": "5.3.0-nightly.20260821",
-    "@aztec/p2p": "5.3.0-nightly.20260821",
-    "@aztec/protocol-contracts": "5.3.0-nightly.20260821",
-    "@aztec/prover-client": "5.3.0-nightly.20260821",
-    "@aztec/prover-node": "5.3.0-nightly.20260821",
-    "@aztec/sequencer-client": "5.3.0-nightly.20260821",
-    "@aztec/simulator": "5.3.0-nightly.20260821",
-    "@aztec/slasher": "5.3.0-nightly.20260821",
-    "@aztec/standard-contracts": "5.3.0-nightly.20260821",
-    "@aztec/stdlib": "5.3.0-nightly.20260821",
-    "@aztec/telemetry-client": "5.3.0-nightly.20260821",
-    "@aztec/validator-client": "5.3.0-nightly.20260821",
-    "@aztec/validator-ha-signer": "5.3.0-nightly.20260821",
-    "@aztec/world-state": "5.3.0-nightly.20260821",
+    "@aztec/archiver": "5.3.0-nightly.20260823",
+    "@aztec/bb-prover": "5.3.0-nightly.20260823",
+    "@aztec/bb.js": "5.3.0-nightly.20260823",
+    "@aztec/blob-client": "5.3.0-nightly.20260823",
+    "@aztec/blob-lib": "5.3.0-nightly.20260823",
+    "@aztec/constants": "5.3.0-nightly.20260823",
+    "@aztec/epoch-cache": "5.3.0-nightly.20260823",
+    "@aztec/ethereum": "5.3.0-nightly.20260823",
+    "@aztec/foundation": "5.3.0-nightly.20260823",
+    "@aztec/kv-store": "5.3.0-nightly.20260823",
+    "@aztec/l1-artifacts": "5.3.0-nightly.20260823",
+    "@aztec/node-keystore": "5.3.0-nightly.20260823",
+    "@aztec/node-lib": "5.3.0-nightly.20260823",
+    "@aztec/noir-protocol-circuits-types": "5.3.0-nightly.20260823",
+    "@aztec/p2p": "5.3.0-nightly.20260823",
+    "@aztec/protocol-contracts": "5.3.0-nightly.20260823",
+    "@aztec/prover-client": "5.3.0-nightly.20260823",
+    "@aztec/prover-node": "5.3.0-nightly.20260823",
+    "@aztec/sequencer-client": "5.3.0-nightly.20260823",
+    "@aztec/simulator": "5.3.0-nightly.20260823",
+    "@aztec/slasher": "5.3.0-nightly.20260823",
+    "@aztec/standard-contracts": "5.3.0-nightly.20260823",
+    "@aztec/stdlib": "5.3.0-nightly.20260823",
+    "@aztec/telemetry-client": "5.3.0-nightly.20260823",
+    "@aztec/validator-client": "5.3.0-nightly.20260823",
+    "@aztec/validator-ha-signer": "5.3.0-nightly.20260823",
+    "@aztec/world-state": "5.3.0-nightly.20260823",
     "koa": "^2.16.1",
     "koa-router": "^13.1.1",
     "tslib": "^2.4.0",

package/src/aztec-node/server.ts

@@ -111,6 +111,7 @@ import { NodeKeystoreAdapter, ValidatorClient } from '@aztec/validator-client';
 import { NodeBlockProvider } from '../modules/node_block_provider.js';
 import { NodeTxReceiptBuilder } from '../modules/node_tx_receipt.js';
 import { NodeWorldStateQueries } from '../modules/node_world_state_queries.js';
+import { UnseenBlockHoldOff } from '../modules/unseen_block_hold_off.js';
 import { Sentinel } from '../sentinel/sentinel.js';
 import type { AztecNodeConfig } from './config.js';
 import { NodeMetrics } from './node_metrics.js';
@@ -164,6 +165,7 @@ export class AztecNodeService implements AztecNode, AztecNodeAdmin, AztecNodeDeb
   private readonly nodePublicCallsSimulator: NodePublicCallsSimulator;
   private readonly worldStateQueries: NodeWorldStateQueries;
   private readonly blockProvider: NodeBlockProvider;
+  private readonly unseenBlockHoldOff: UnseenBlockHoldOff;
   private readonly txReceiptBuilder: NodeTxReceiptBuilder;
 
   public readonly tracer: Tracer;
@@ -246,14 +248,25 @@ export class AztecNodeService implements AztecNode, AztecNodeAdmin, AztecNodeDeb
       log: this.log.createChild('public-calls-simulator'),
     });
 
+    // Shared by every block-anchored read so the concurrent-hold cap applies across all of them.
+    this.unseenBlockHoldOff = new UnseenBlockHoldOff(
+      this.blockSource,
+      {
+        byNumberWaitMs: this.config.rpcUnseenBlockByNumberWaitMs ?? 2 * this.config.blockDurationMs,
+        byHashWaitMs: this.config.rpcUnseenBlockByHashWaitMs,
+      },
+      this.log.createChild('unseen-block-hold-off'),
+    );
+
     this.worldStateQueries = new NodeWorldStateQueries({
       worldStateSynchronizer: this.worldStateSynchronizer,
       blockSource: this.blockSource,
       l1ToL2MessageSource: this.l1ToL2MessageSource,
+      holdOff: this.unseenBlockHoldOff,
       log: this.log.createChild('world-state-queries'),
     });
 
-    this.blockProvider = new NodeBlockProvider(this.blockSource);
+    this.blockProvider = new NodeBlockProvider(this.blockSource, this.unseenBlockHoldOff);
 
     this.txReceiptBuilder = new NodeTxReceiptBuilder({
       p2pClient: this.p2pClient,
@@ -501,12 +514,26 @@ export class AztecNodeService implements AztecNode, AztecNodeAdmin, AztecNodeDeb
     return this.contractDataSource.getContract(address, blockData.header.globalVariables.timestamp);
   }
 
-  public getPrivateLogsByTags(query: PrivateLogsQuery): Promise<LogResult[][]> {
-    return this.logsSource.getPrivateLogsByTags(query);
+  public async getPrivateLogsByTags(query: PrivateLogsQuery): Promise<LogResult[][]> {
+    await this.#awaitLogsReferenceBlock(query.referenceBlock);
+    return await this.logsSource.getPrivateLogsByTags(query);
   }
 
-  public getPublicLogsByTags(query: PublicLogsQuery): Promise<LogResult[][]> {
-    return this.logsSource.getPublicLogsByTags(query);
+  public async getPublicLogsByTags(query: PublicLogsQuery): Promise<LogResult[][]> {
+    await this.#awaitLogsReferenceBlock(query.referenceBlock);
+    return await this.logsSource.getPublicLogsByTags(query);
+  }
+
+  /**
+   * Waits briefly for a logs query's reorg-safety anchor when the node has not seen that block yet, so a client
+   * that synced one block ahead through another node is not failed over a transient skew. The result is discarded:
+   * the log store's own in-transaction anchor check stays authoritative and throws as before if the block never
+   * arrives.
+   */
+  async #awaitLogsReferenceBlock(referenceBlock: BlockHash | undefined): Promise<void> {
+    if (referenceBlock !== undefined) {
+      await this.unseenBlockHoldOff.getBlockData({ hash: referenceBlock });
+    }
   }
 
   /**
@@ -571,6 +598,7 @@ export class AztecNodeService implements AztecNode, AztecNodeAdmin, AztecNodeDeb
     await tryStop(this.automineSequencer);
     await tryStop(this.proverNode);
     await tryStop(this.p2pClient);
+    await tryStop(this.feeProvider);
     await tryStop(this.worldStateSynchronizer);
     await tryStop(this.blockSource);
     await tryStop(this.blobClient);

package/src/factory.ts

@@ -251,6 +251,8 @@ export async function createAztecNodeService(
 
     const globalVariableBuilder = new GlobalVariableBuilder(publicClient, globalVariableBuilderConfig);
     const feeProvider = new FeeProviderImpl(dateProvider, publicClient, globalVariableBuilderConfig);
+    await feeProvider.start();
+    started.push(feeProvider);
 
     const collectOffenses = !config.disableValidator || config.enableOffenseCollection;
 

package/src/modules/node_block_provider.ts

@@ -19,6 +19,7 @@ import {
   projectProposedToCheckpointResponse,
 } from '../aztec-node/block_response_helpers.js';
 import { normalizeBlockParameter, resolveCheckpointParameter } from './block_parameter.js';
+import type { UnseenBlockHoldOff } from './unseen_block_hold_off.js';
 
 /**
  * Serves the node's block and checkpoint read queries, assembling RPC responses (optionally including
@@ -26,7 +27,10 @@ import { normalizeBlockParameter, resolveCheckpointParameter } from './block_par
  * `AztecNodeService` to keep `server.ts` smaller.
  */
 export class NodeBlockProvider {
-  constructor(private readonly blockSource: L2BlockSource) {}
+  constructor(
+    private readonly blockSource: L2BlockSource,
+    private readonly holdOff: UnseenBlockHoldOff,
+  ) {}
 
   public async getBlock<Opts extends BlockIncludeOptions = {}>(
     param: BlockParameter,
@@ -37,14 +41,14 @@ export class NodeBlockProvider {
     const wantContext = !!options.includeL1PublishInfo || !!options.includeAttestations;
 
     if (wantTxs) {
-      const block = await this.blockSource.getBlock(query);
+      const block = await this.holdOff.getBlock(query);
       if (!block) {
         return undefined;
       }
       const ctx = wantContext ? await this.#getCheckpointContext(block.checkpointNumber) : undefined;
       return (await blockResponseFromL2Block(block, options, ctx)) as BlockResponse<Opts>;
     }
-    const data = await this.blockSource.getBlockData(query);
+    const data = await this.holdOff.getBlockData(query);
     if (!data) {
       return undefined;
     }
@@ -54,7 +58,7 @@ export class NodeBlockProvider {
 
   public getBlockData(param: BlockParameter): Promise<BlockData | undefined> {
     const query = normalizeBlockParameter(param);
-    return this.blockSource.getBlockData(query);
+    return this.holdOff.getBlockData(query);
   }
 
   public async getBlocks<Opts extends BlocksIncludeOptions = {}>(

package/src/modules/node_world_state_queries.ts

@@ -28,6 +28,7 @@ import type { TxHash } from '@aztec/stdlib/tx';
 import { WorldStateSynchronizerError } from '@aztec/world-state';
 
 import { normalizeBlockParameter } from './block_parameter.js';
+import type { UnseenBlockHoldOff, UnseenBlockHoldOffOptions } from './unseen_block_hold_off.js';
 
 /** Attempts at resolving a query and syncing world state to it before giving up (see {@link NodeWorldStateQueries.getWorldState}). */
 const WORLD_STATE_SYNC_ATTEMPTS = 3;
@@ -40,6 +41,7 @@ export interface NodeWorldStateQueriesDeps {
   worldStateSynchronizer: WorldStateSynchronizer;
   blockSource: L2BlockSource;
   l1ToL2MessageSource: L1ToL2MessageSource;
+  holdOff: UnseenBlockHoldOff;
   log?: Logger;
 }
 
@@ -52,12 +54,14 @@ export class NodeWorldStateQueries {
   private readonly worldStateSynchronizer: WorldStateSynchronizer;
   private readonly blockSource: L2BlockSource;
   private readonly l1ToL2MessageSource: L1ToL2MessageSource;
+  private readonly holdOff: UnseenBlockHoldOff;
   private readonly log: Logger;
 
   constructor(deps: NodeWorldStateQueriesDeps) {
     this.worldStateSynchronizer = deps.worldStateSynchronizer;
     this.blockSource = deps.blockSource;
     this.l1ToL2MessageSource = deps.l1ToL2MessageSource;
+    this.holdOff = deps.holdOff;
     this.log = deps.log ?? createLogger('node:world-state-queries');
   }
 
@@ -137,7 +141,9 @@ export class NodeWorldStateQueries {
     // The Noir circuit checks the archive membership proof against `anchor_block_header.last_archive.root`,
     // which is the archive tree root BEFORE the anchor block was added (i.e. the state after block N-1).
     // So we need the world state at block N-1, not block N, to produce a sibling path matching that root.
-    const referenceBlockNumber = await this.#resolveBlockNumber(referenceBlock);
+    const { blockNumber: referenceBlockNumber } = await this.#resolveBlockNumberAndHash(
+      normalizeBlockParameter(referenceBlock),
+    );
     if (referenceBlockNumber === BlockNumber.ZERO) {
       // Block 0 (the initial block) has an empty archive, so no membership witness can exist.
       return undefined;
@@ -282,9 +288,9 @@ export class NodeWorldStateQueries {
    * Returns an instance of MerkleTreeOperations having first ensured the world state is synced to the requested
    * block on the correct fork. Every query variant is resolved to a concrete (block number, block hash), which is
    * threaded through both the sync and the snapshot read so a reorg that replaced the block at that height is
-   * detected rather than served silently. Transient failures — a prune landing between resolution and sync, or a
-   * fork flip caught at either the sync or the snapshot stage — are retried a few times, re-resolving the query
-   * against the updated chain each time; terminal failures — an unknown block hash at resolution, or a block whose
+   * detected rather than served silently. Transient sync failures — a prune landing between resolution and sync, or
+   * a fork flip caught at either the sync or the snapshot stage — are retried a few times, re-resolving the query
+   * against the updated chain each time; terminal failures — a query that resolves to no block, or a block whose
    * history world state has pruned away — are thrown immediately.
    * @param block - The block parameter (block number, block hash, or tag) at which to get the data.
    * @returns An instance of a committed MerkleTreeOperations
@@ -292,9 +298,22 @@ export class NodeWorldStateQueries {
   public async getWorldState(block: BlockParameter) {
     const query = normalizeBlockParameter(block);
 
+    // User requests 'latest on the current fork', so the committed db is returned unverified
+    if ('tag' in query && query.tag === 'proposed') {
+      this.log.debug(`Using committed db for latest block`);
+      await this.worldStateSynchronizer.syncImmediate();
+      return this.worldStateSynchronizer.getCommitted();
+    }
+
+    // Resolve the query against the block source BEFORE syncing, so the sync can be driven to a concrete
+    // (number, hash). Resolving after the sync races the block source: the resolved tip can advance past what world
+    // state synced while the sync is in flight. Resolving here rather than inside the retry loop also keeps a
+    // retry from re-entering the hold-off, which would multiply the wait a client experiences by the attempt count.
+    let resolved = await this.#resolveBlockNumberAndHash(query);
+
     for (let attempt = 1; ; attempt++) {
       try {
-        return await this.#resolveWorldState(query);
+        return await this.#resolveWorldState(resolved);
       } catch (err) {
         if (attempt >= WORLD_STATE_SYNC_ATTEMPTS || !(err instanceof WorldStateSynchronizerError)) {
           throw err;
@@ -304,27 +323,17 @@ export class NodeWorldStateQueries {
           block: inspectBlockParameter(block),
         });
         await sleep(WORLD_STATE_SYNC_RETRY_DELAY_MS);
+        resolved = await this.#resolveBlockNumberAndHash(query, { holdOff: false });
       }
     }
   }
 
   /**
-   * Resolves `query` to a concrete (block number, block hash), syncs world state to that exact fork, and returns
-   * the committed db (for `proposed` queries) or the fork-verified snapshot at the resolved block.
+   * Syncs world state to the resolved fork and returns the fork-verified snapshot at that block. Passing the hash
+   * makes the sync reorg-aware — it barriers until the archive-tree commit for that block has landed and verifies
+   * it matches the requested fork, throwing otherwise.
    */
-  async #resolveWorldState(query: NormalizedBlockParameter) {
-    // User requests 'latest on the current fork', so the committed db is returned unverified
-    if ('tag' in query && query.tag === 'proposed') {
-      this.log.debug(`Using committed db for latest block`);
-      await this.worldStateSynchronizer.syncImmediate();
-      return this.worldStateSynchronizer.getCommitted();
-    }
-
-    // Resolve the query against the block source BEFORE syncing to a concrete (number, hash), and drive the sync to
-    // that exact fork. Resolving after the sync races the block source: the resolved tip can advance past what world
-    // state synced while the sync is in flight. Passing the hash makes the sync reorg-aware — it barriers until the
-    // archive-tree commit for that block has landed and verifies it matches the requested fork, throwing otherwise.
-    const { blockNumber, blockHash } = await this.#resolveBlockNumberAndHash(query);
+  async #resolveWorldState({ blockNumber, blockHash }: { blockNumber: BlockNumber; blockHash: BlockHash }) {
     const blockSyncedTo = await this.worldStateSynchronizer.syncImmediate(blockNumber, blockHash);
 
     // The fork could flip between it returning and the snapshot being read, so getVerifiedSnapshot pins the
@@ -333,32 +342,25 @@ export class NodeWorldStateQueries {
     return await this.worldStateSynchronizer.getVerifiedSnapshot(blockNumber, blockHash);
   }
 
-  /** Resolves any {@link BlockParameter} variant to its concrete `(blockNumber, blockHash)` via the block source. */
+  /**
+   * Resolves any {@link BlockParameter} variant to its concrete `(blockNumber, blockHash)`, holding the query
+   * briefly (unless the caller opts out) when it references a block the node is about to see.
+   */
   async #resolveBlockNumberAndHash(
     query: NormalizedBlockParameter,
+    opts: UnseenBlockHoldOffOptions = {},
   ): Promise<{ blockNumber: BlockNumber; blockHash: BlockHash }> {
-    const blockData = await this.blockSource.getBlockData(query);
+    const blockData = await this.holdOff.getBlockData(query, opts);
     if (blockData === undefined) {
       this.#throwOnUndefinedBlockData(query);
     }
     return { blockNumber: blockData.header.getBlockNumber(), blockHash: blockData.blockHash };
   }
 
-  /** Resolves any {@link BlockParameter} variant to a concrete block number. */
-  async #resolveBlockNumber(block: BlockParameter): Promise<BlockNumber> {
-    const blockQuery = normalizeBlockParameter(block);
-    const blockNumber = await this.blockSource.getBlockNumber(blockQuery);
-    if (blockNumber === undefined) {
-      this.#throwOnUndefinedBlockData(blockQuery);
-    }
-    return blockNumber;
-  }
-
   /**
-   * Hash and archive misses are terminal (an unknown block, likely a reorg); tag and number misses are transient —
-   * the block may have been pruned between the tag->number resolution and this data read, or may simply not have
-   * arrived yet — and surface as {@link WorldStateSynchronizerError} so the retry loop re-resolves against the
-   * current chain.
+   * Hash and archive misses report an unknown block (likely a reorg); tag and number misses report a transient
+   * condition — the block may have been pruned, or may simply not have arrived yet — and are distinguished to the
+   * caller as a {@link WorldStateSynchronizerError}.
    */
   #throwOnUndefinedBlockData(query: NormalizedBlockParameter): never {
     if ('hash' in query) {