@aztec/stdlib 0.84.0 → 0.85.0

package/src/block/{l2_block_downloader → l2_block_stream}/l2_block_stream.ts

@@ -2,8 +2,8 @@ import { AbortError } from '@aztec/foundation/error';
 import { createLogger } from '@aztec/foundation/log';
 import { RunningPromise } from '@aztec/foundation/running-promise';
 
-import type { L2BlockId, L2BlockSource, L2Tips } from '../l2_block_source.js';
-import type { PublishedL2Block } from '../published_l2_block.js';
+import { type L2BlockId, type L2BlockSource, makeL2BlockId } from '../l2_block_source.js';
+import type { L2BlockStreamEvent, L2BlockStreamEventHandler, L2BlockStreamLocalDataProvider } from './interfaces.js';
 
 /** Creates a stream of events for new blocks, chain tips updates, and reorgs, out of polling an archiver or a node. */
 export class L2BlockStream {
@@ -21,6 +21,8 @@ export class L2BlockStream {
       pollIntervalMS?: number;
       batchSize?: number;
       startingBlock?: number;
+      /** Instead of downloading all blocks, only fetch the smallest subset that results in reliable reorg detection. */
+      skipFinalized?: boolean;
     } = {},
   ) {
     this.runningPromise = new RunningPromise(() => this.work(), log, this.opts.pollIntervalMS ?? 1000);
@@ -72,14 +74,13 @@ export class L2BlockStream {
       }
 
       if (latestBlockNumber < localTips.latest.number) {
+        latestBlockNumber = Math.min(latestBlockNumber, sourceTips.latest.number); // see #13471
+        const hash = sourceCache.get(latestBlockNumber) ?? (await this.getBlockHashFromSource(latestBlockNumber));
+        if (latestBlockNumber !== 0 && !hash) {
+          throw new Error(`Block hash not found in block source for block number ${latestBlockNumber}`);
+        }
         this.log.verbose(`Reorg detected. Pruning blocks from ${latestBlockNumber + 1} to ${localTips.latest.number}.`);
-        await this.emitEvent({
-          type: 'chain-pruned',
-          block: {
-            number: latestBlockNumber,
-            hash: sourceCache.get(latestBlockNumber) ?? (await this.getBlockHashFromSource(latestBlockNumber))!,
-          },
-        });
+        await this.emitEvent({ type: 'chain-pruned', block: makeL2BlockId(latestBlockNumber, hash) });
       }
 
       // If we are just starting, use the starting block number from the options.
@@ -93,17 +94,26 @@ export class L2BlockStream {
         this.hasStarted = true;
       }
 
+      let nextBlockNumber = latestBlockNumber + 1;
+      if (this.opts.skipFinalized) {
+        // When skipping finalized blocks we need to provide reliable reorg detection while fetching as few blocks as
+        // possible. Finalized blocks cannot be reorged by definition, so we can skip most of them. We do need the very
+        // last finalized block however in order to guarantee that we will eventually find a block in which our local
+        // store matches the source.
+        // If the last finalized block is behind our local tip, there is nothing to skip.
+        nextBlockNumber = Math.max(sourceTips.finalized.number, nextBlockNumber);
+      }
+
       // Request new blocks from the source.
-      while (latestBlockNumber < sourceTips.latest.number) {
-        const from = latestBlockNumber + 1;
-        const limit = Math.min(this.opts.batchSize ?? 20, sourceTips.latest.number - from + 1);
-        this.log.trace(`Requesting blocks from ${from} limit ${limit} proven=${this.opts.proven}`);
-        const blocks = await this.l2BlockSource.getPublishedBlocks(from, limit, this.opts.proven);
+      while (nextBlockNumber <= sourceTips.latest.number) {
+        const limit = Math.min(this.opts.batchSize ?? 20, sourceTips.latest.number - nextBlockNumber + 1);
+        this.log.trace(`Requesting blocks from ${nextBlockNumber} limit ${limit} proven=${this.opts.proven}`);
+        const blocks = await this.l2BlockSource.getPublishedBlocks(nextBlockNumber, limit, this.opts.proven);
         if (blocks.length === 0) {
           break;
         }
         await this.emitEvent({ type: 'blocks-added', blocks });
-        latestBlockNumber = blocks.at(-1)!.block.number;
+        nextBlockNumber = blocks.at(-1)!.block.number + 1;
       }
 
       // Update the proven and finalized tips.
@@ -134,6 +144,15 @@ export class L2BlockStream {
       return true;
     }
     const localBlockHash = await this.localData.getL2BlockHash(blockNumber);
+    if (!localBlockHash && this.opts.skipFinalized) {
+      // Failing to find a block hash when skipping finalized blocks can be highly problematic as we'd potentially need
+      // to go all the way back to the genesis block to find a block in which we agree with the source (since we've
+      // potentially skipped all history). This means that stores that prune old blocks must be careful to leave no gaps
+      // when going back from latest block to the last finalized one.
+      this.log.error(`No local block hash for block number ${blockNumber}`);
+      throw new AbortError();
+    }
+
     const sourceBlockHashFromCache = args.sourceCache.get(blockNumber);
     const sourceBlockHash = args.sourceCache.get(blockNumber) ?? (await this.getBlockHashFromSource(blockNumber));
     if (!sourceBlockHashFromCache && sourceBlockHash) {
@@ -181,32 +200,3 @@ class BlockHashCache {
     return this.cache.get(blockNumber);
   }
 }
-
-/** Interface to the local view of the chain. Implemented by world-state and l2-tips-store. */
-export interface L2BlockStreamLocalDataProvider {
-  getL2BlockHash(number: number): Promise<string | undefined>;
-  getL2Tips(): Promise<L2Tips>;
-}
-
-/** Interface to a handler of events emitted. */
-export interface L2BlockStreamEventHandler {
-  handleBlockStreamEvent(event: L2BlockStreamEvent): Promise<void>;
-}
-
-export type L2BlockStreamEvent =
-  | /** Emits blocks added to the chain. */ {
-      type: 'blocks-added';
-      blocks: PublishedL2Block[];
-    }
-  | /** Reports last correct block (new tip of the unproven chain). */ {
-      type: 'chain-pruned';
-      block: L2BlockId;
-    }
-  | /** Reports new proven block. */ {
-      type: 'chain-proven';
-      block: L2BlockId;
-    }
-  | /** Reports new finalized block (proven and finalized on L1). */ {
-      type: 'chain-finalized';
-      block: L2BlockId;
-    };

package/src/block/l2_block_stream/l2_tips_memory_store.ts

@@ -0,0 +1,75 @@
+import type { L2Block } from '../l2_block.js';
+import type { L2BlockId, L2BlockTag, L2Tips } from '../l2_block_source.js';
+import type { L2BlockStreamEvent, L2BlockStreamEventHandler, L2BlockStreamLocalDataProvider } from './interfaces.js';
+
+/**
+ * Stores currently synced L2 tips and unfinalized block hashes.
+ * @dev tests in kv-store/src/stores/l2_tips_memory_store.test.ts
+ */
+export class L2TipsMemoryStore implements L2BlockStreamEventHandler, L2BlockStreamLocalDataProvider {
+  protected readonly l2TipsStore: Map<L2BlockTag, number> = new Map();
+  protected readonly l2BlockHashesStore: Map<number, string> = new Map();
+
+  public getL2BlockHash(number: number): Promise<string | undefined> {
+    return Promise.resolve(this.l2BlockHashesStore.get(number));
+  }
+
+  public getL2Tips(): Promise<L2Tips> {
+    return Promise.resolve({
+      latest: this.getL2Tip('latest'),
+      finalized: this.getL2Tip('finalized'),
+      proven: this.getL2Tip('proven'),
+    });
+  }
+
+  private getL2Tip(tag: L2BlockTag): L2BlockId {
+    const blockNumber = this.l2TipsStore.get(tag);
+    if (blockNumber === undefined || blockNumber === 0) {
+      return { number: 0, hash: undefined };
+    }
+    const blockHash = this.l2BlockHashesStore.get(blockNumber);
+    if (!blockHash) {
+      throw new Error(`Block hash not found for block number ${blockNumber}`);
+    }
+
+    return { number: blockNumber, hash: blockHash };
+  }
+
+  public async handleBlockStreamEvent(event: L2BlockStreamEvent): Promise<void> {
+    switch (event.type) {
+      case 'blocks-added': {
+        const blocks = event.blocks.map(b => b.block);
+        for (const block of blocks) {
+          this.l2BlockHashesStore.set(block.number, await this.computeBlockHash(block));
+        }
+        this.l2TipsStore.set('latest', blocks.at(-1)!.number);
+        break;
+      }
+      case 'chain-pruned':
+        this.saveTag('latest', event.block);
+        break;
+      case 'chain-proven':
+        this.saveTag('proven', event.block);
+        break;
+      case 'chain-finalized':
+        this.saveTag('finalized', event.block);
+        for (const key of this.l2BlockHashesStore.keys()) {
+          if (key < event.block.number) {
+            this.l2BlockHashesStore.delete(key);
+          }
+        }
+        break;
+    }
+  }
+
+  protected saveTag(name: L2BlockTag, block: L2BlockId) {
+    this.l2TipsStore.set(name, block.number);
+    if (block.hash) {
+      this.l2BlockHashesStore.set(block.number, block.hash);
+    }
+  }
+
+  protected computeBlockHash(block: L2Block) {
+    return block.header.hash().then(hash => hash.toString());
+  }
+}

package/src/block/test/index.ts

@@ -0,0 +1 @@
+export * from './l2_tips_store_test_suite.js';

package/src/block/test/l2_tips_store_test_suite.ts

@@ -0,0 +1,87 @@
+import { times } from '@aztec/foundation/collection';
+import { Fr } from '@aztec/foundation/fields';
+import type { L2Block, L2BlockId, PublishedL2Block } from '@aztec/stdlib/block';
+import type { BlockHeader } from '@aztec/stdlib/tx';
+
+import { jestExpect as expect } from '@jest/expect';
+
+import type { L2TipsStore } from '../l2_block_stream/index.js';
+
+export function testL2TipsStore(makeTipsStore: () => Promise<L2TipsStore>) {
+  let tipsStore: L2TipsStore;
+
+  beforeEach(async () => {
+    tipsStore = await makeTipsStore();
+  });
+
+  const makeBlock = (number: number): PublishedL2Block => ({
+    block: { number, header: { hash: () => Promise.resolve(new Fr(number)) } as BlockHeader } as L2Block,
+    l1: { blockNumber: BigInt(number), blockHash: `0x${number}`, timestamp: BigInt(number) },
+    signatures: [],
+  });
+
+  const makeBlockId = (number: number): L2BlockId => ({
+    number,
+    hash: new Fr(number).toString(),
+  });
+
+  const makeTip = (number: number) => ({ number, hash: number === 0 ? undefined : new Fr(number).toString() });
+
+  const makeTips = (latest: number, proven: number, finalized: number) => ({
+    latest: makeTip(latest),
+    proven: makeTip(proven),
+    finalized: makeTip(finalized),
+  });
+
+  it('returns zero if no tips are stored', async () => {
+    const tips = await tipsStore.getL2Tips();
+    expect(tips).toEqual(makeTips(0, 0, 0));
+  });
+
+  it('stores chain tips', async () => {
+    await tipsStore.handleBlockStreamEvent({ type: 'blocks-added', blocks: times(20, i => makeBlock(i + 1)) });
+
+    await tipsStore.handleBlockStreamEvent({ type: 'chain-finalized', block: makeBlockId(5) });
+    await tipsStore.handleBlockStreamEvent({ type: 'chain-proven', block: makeBlockId(8) });
+    await tipsStore.handleBlockStreamEvent({ type: 'chain-pruned', block: makeBlockId(10) });
+
+    const tips = await tipsStore.getL2Tips();
+    expect(tips).toEqual(makeTips(10, 8, 5));
+  });
+
+  it('sets latest tip from blocks added', async () => {
+    await tipsStore.handleBlockStreamEvent({ type: 'blocks-added', blocks: times(3, i => makeBlock(i + 1)) });
+
+    const tips = await tipsStore.getL2Tips();
+    expect(tips).toEqual(makeTips(3, 0, 0));
+
+    expect(await tipsStore.getL2BlockHash(1)).toEqual(new Fr(1).toString());
+    expect(await tipsStore.getL2BlockHash(2)).toEqual(new Fr(2).toString());
+    expect(await tipsStore.getL2BlockHash(3)).toEqual(new Fr(3).toString());
+  });
+
+  it('clears block hashes when setting finalized chain', async () => {
+    await tipsStore.handleBlockStreamEvent({ type: 'blocks-added', blocks: times(5, i => makeBlock(i + 1)) });
+    await tipsStore.handleBlockStreamEvent({ type: 'chain-proven', block: makeBlockId(3) });
+    await tipsStore.handleBlockStreamEvent({ type: 'chain-finalized', block: makeBlockId(3) });
+
+    const tips = await tipsStore.getL2Tips();
+    expect(tips).toEqual(makeTips(5, 3, 3));
+
+    expect(await tipsStore.getL2BlockHash(1)).toBeUndefined();
+    expect(await tipsStore.getL2BlockHash(2)).toBeUndefined();
+
+    expect(await tipsStore.getL2BlockHash(3)).toEqual(new Fr(3).toString());
+    expect(await tipsStore.getL2BlockHash(4)).toEqual(new Fr(4).toString());
+    expect(await tipsStore.getL2BlockHash(5)).toEqual(new Fr(5).toString());
+  });
+
+  // Regression test for #13142
+  it('does not blow up when setting proven chain on an unseen block number', async () => {
+    await tipsStore.handleBlockStreamEvent({ type: 'blocks-added', blocks: [makeBlock(5)] });
+    await tipsStore.handleBlockStreamEvent({ type: 'chain-proven', block: makeBlockId(3) });
+
+    const tips = await tipsStore.getL2Tips();
+    expect(tips).toEqual(makeTips(5, 3, 0));
+  });
+}

package/src/database-version/version_manager.ts

@@ -1,6 +1,6 @@
 import { EthAddress } from '@aztec/foundation/eth-address';
 import { jsonParseWithSchemaSync, jsonStringify } from '@aztec/foundation/json-rpc';
-import { createLogger } from '@aztec/foundation/log';
+import { type Logger, createLogger } from '@aztec/foundation/log';
 
 import fs from 'fs/promises';
 import { inspect } from 'node:util';
@@ -11,7 +11,12 @@ import { z } from 'zod';
  * Represents a version record for storing in a version file.
  */
 export class DatabaseVersion {
-  constructor(public readonly schemaVersion: number, public readonly rollupAddress: EthAddress) {}
+  constructor(
+    /** The version of the data on disk. Used to perform upgrades */
+    public readonly schemaVersion: number,
+    /** The rollup the data pertains to */
+    public readonly rollupAddress: EthAddress,
+  ) {}
 
   public toBuffer(): Buffer {
     return Buffer.from(jsonStringify(this));
@@ -66,7 +71,7 @@ export class DatabaseVersion {
   }
 
   public toString(): string {
-    return this.schemaVersion.toString();
+    return `DatabaseVersion{schemaVersion=${this.schemaVersion},rollupAddress=${this.rollupAddress}"}`;
   }
 
   /**
@@ -81,6 +86,16 @@ export type DatabaseVersionManagerFs = Pick<typeof fs, 'readFile' | 'writeFile'
 
 export const DATABASE_VERSION_FILE_NAME = 'db_version';
 
+export type DatabaseVersionManagerOptions<T> = {
+  schemaVersion: number;
+  rollupAddress: EthAddress;
+  dataDirectory: string;
+  onOpen: (dataDir: string) => Promise<T>;
+  onUpgrade?: (dataDir: string, currentVersion: number, latestVersion: number) => Promise<void>;
+  fileSystem?: DatabaseVersionManagerFs;
+  log?: Logger;
+};
+
 /**
  * A manager for handling database versioning and migrations.
  * This class will check the version of data in a directory and either
@@ -92,6 +107,12 @@ export class DatabaseVersionManager<T> {
   private readonly versionFile: string;
   private readonly currentVersion: DatabaseVersion;
 
+  private dataDirectory: string;
+  private onOpen: (dataDir: string) => Promise<T>;
+  private onUpgrade?: (dataDir: string, currentVersion: number, latestVersion: number) => Promise<void>;
+  private fileSystem: DatabaseVersionManagerFs;
+  private log: Logger;
+
   /**
    * Create a new version manager
    *
@@ -104,21 +125,27 @@ export class DatabaseVersionManager<T> {
    * @param log - Optional custom logger
    * @param options - Configuration options
    */
-  constructor(
-    schemaVersion: number,
-    rollupAddress: EthAddress,
-    private dataDirectory: string,
-    private onOpen: (dataDir: string) => Promise<T>,
-    private onUpgrade?: (dataDir: string, currentVersion: number, latestVersion: number) => Promise<void>,
-    private fileSystem: DatabaseVersionManagerFs = fs,
-    private log = createLogger(`foundation:version-manager`),
-  ) {
+  constructor({
+    schemaVersion,
+    rollupAddress,
+    dataDirectory,
+    onOpen,
+    onUpgrade,
+    fileSystem = fs,
+    log = createLogger(`foundation:version-manager`),
+  }: DatabaseVersionManagerOptions<T>) {
     if (schemaVersion < 1) {
       throw new TypeError(`Invalid schema version received: ${schemaVersion}`);
     }
 
-    this.versionFile = join(this.dataDirectory, DatabaseVersionManager.VERSION_FILE);
+    this.versionFile = join(dataDirectory, DatabaseVersionManager.VERSION_FILE);
     this.currentVersion = new DatabaseVersion(schemaVersion, rollupAddress);
+
+    this.dataDirectory = dataDirectory;
+    this.onOpen = onOpen;
+    this.onUpgrade = onUpgrade;
+    this.fileSystem = fileSystem;
+    this.log = log;
   }
 
   static async writeVersion(version: DatabaseVersion, dataDir: string, fileSystem: DatabaseVersionManagerFs = fs) {
@@ -137,6 +164,8 @@ export class DatabaseVersionManager<T> {
   public async open(): Promise<[T, boolean]> {
     // const storedVersion = await DatabaseVersion.readVersion(this.versionFile);
     let storedVersion: DatabaseVersion;
+    // a flag to suppress logs about 'resetting the data dir' when starting from an empty state
+    let shouldLogDataReset = true;
 
     try {
       const versionBuf = await this.fileSystem.readFile(this.versionFile);
@@ -144,6 +173,8 @@ export class DatabaseVersionManager<T> {
     } catch (err) {
       if (err && (err as Error & { code: string }).code === 'ENOENT') {
         storedVersion = DatabaseVersion.empty();
+        // only turn off these logs if the data dir didn't exist before
+        shouldLogDataReset = false;
       } else {
         this.log.warn(`Failed to read stored version information: ${err}. Defaulting to empty version`);
         storedVersion = DatabaseVersion.empty();
@@ -164,13 +195,21 @@ export class DatabaseVersionManager<T> {
           needsReset = true;
         }
       } else if (cmp !== 0) {
-        this.log.info(
-          `Can't upgrade from version ${storedVersion.schemaVersion} to ${this.currentVersion.schemaVersion}. Resetting database at ${this.dataDirectory}`,
-        );
+        if (shouldLogDataReset) {
+          this.log.info(
+            `Can't upgrade from version ${storedVersion} to ${this.currentVersion}. Resetting database at ${this.dataDirectory}`,
+          );
+        }
         needsReset = true;
       }
     } else {
-      this.log.warn('Rollup address changed, resetting data directory', { versionFile: this.versionFile });
+      if (shouldLogDataReset) {
+        this.log.warn('Rollup address has changed, resetting data directory', {
+          versionFile: this.versionFile,
+          storedVersion,
+          currentVersion: this.currentVersion,
+        });
+      }
       needsReset = true;
     }
 

package/src/epoch-helpers/index.ts

@@ -8,6 +8,7 @@ export type L1RollupConstants = {
   slotDuration: number;
   epochDuration: number;
   ethereumSlotDuration: number;
+  proofSubmissionWindow: number;
 };
 
 export const EmptyL1RollupConstants: L1RollupConstants = {
@@ -16,6 +17,7 @@ export const EmptyL1RollupConstants: L1RollupConstants = {
   epochDuration: 1, // Not 0 to pervent division by zero
   slotDuration: 1,
   ethereumSlotDuration: 1,
+  proofSubmissionWindow: 2,
 };
 
 export const L1RollupConstantsSchema = z.object({
@@ -24,6 +26,7 @@ export const L1RollupConstantsSchema = z.object({
   slotDuration: z.number(),
   epochDuration: z.number(),
   ethereumSlotDuration: z.number(),
+  proofSubmissionWindow: z.number(),
 }) satisfies ZodFor<L1RollupConstants>;
 
 /** Returns the timestamp for a given L2 slot. */
@@ -75,3 +78,19 @@ export function getTimestampRangeForEpoch(
       BigInt((ethereumSlotsPerL2Slot - 1) * constants.ethereumSlotDuration),
   ];
 }
+
+/**
+ * Returns the deadline timestamp (in seconds) for submitting a proof for a given epoch.
+ * Computed as the start of the given epoch plus the proof submission window.
+ */
+export function getProofSubmissionDeadlineTimestamp(
+  epochNumber: bigint,
+  constants: Pick<L1RollupConstants, 'l1GenesisTime' | 'slotDuration' | 'epochDuration' | 'proofSubmissionWindow'>,
+) {
+  // See l1-contracts/src/core/libraries/rollup/EpochProofLib.sol:
+  // Slot deadline = startEpoch.toSlots() + Slot.wrap(rollupStore.config.proofSubmissionWindow);
+  const [startSlot] = getSlotRangeForEpoch(epochNumber, constants);
+  const deadlineSlot = startSlot + BigInt(constants.proofSubmissionWindow);
+  const deadlineTimestamp = getTimestampForSlot(deadlineSlot, constants);
+  return deadlineTimestamp;
+}

package/src/interfaces/archiver.ts

@@ -2,7 +2,6 @@ import type { ApiSchemaFor } from '@aztec/foundation/schemas';
 
 import { z } from 'zod';
 
-import { inBlockSchemaFor } from '../block/in_block.js';
 import { L2Block } from '../block/l2_block.js';
 import { type L2BlockSource, L2TipsSchema } from '../block/l2_block_source.js';
 import { PublishedL2BlockSchema } from '../block/published_l2_block.js';
@@ -18,7 +17,7 @@ import { TxScopedL2Log } from '../logs/tx_scoped_l2_log.js';
 import type { L1ToL2MessageSource } from '../messaging/l1_to_l2_message_source.js';
 import { optional, schemas } from '../schemas/schemas.js';
 import { BlockHeader } from '../tx/block_header.js';
-import { TxEffect } from '../tx/tx_effect.js';
+import { indexedTxSchema } from '../tx/indexed_tx_effect.js';
 import { TxHash } from '../tx/tx_hash.js';
 import { TxReceipt } from '../tx/tx_receipt.js';
 import { GetContractClassLogsResponseSchema, GetPublicLogsResponseSchema } from './get_logs_response.js';
@@ -47,7 +46,7 @@ export const ArchiverApiSchema: ApiSchemaFor<ArchiverApi> = {
     .function()
     .args(schemas.Integer, schemas.Integer, optional(z.boolean()))
     .returns(z.array(PublishedL2BlockSchema)),
-  getTxEffect: z.function().args(TxHash.schema).returns(inBlockSchemaFor(TxEffect.schema).optional()),
+  getTxEffect: z.function().args(TxHash.schema).returns(indexedTxSchema().optional()),
   getSettledTxReceipt: z.function().args(TxHash.schema).returns(TxReceipt.schema.optional()),
   getL2SlotNumber: z.function().args().returns(schemas.BigInt),
   getL2EpochNumber: z.function().args().returns(schemas.BigInt),
@@ -74,4 +73,5 @@ export const ArchiverApiSchema: ApiSchemaFor<ArchiverApi> = {
   getL1ToL2MessageIndex: z.function().args(schemas.Fr).returns(schemas.BigInt.optional()),
   getDebugFunctionName: z.function().args(schemas.AztecAddress, schemas.FunctionSelector).returns(optional(z.string())),
   getL1Constants: z.function().args().returns(L1RollupConstantsSchema),
+  syncImmediate: z.function().args().returns(z.void()),
 };

package/src/interfaces/aztec-node.ts

@@ -38,14 +38,15 @@ import { NullifierMembershipWitness } from '../trees/nullifier_membership_witnes
 import { PublicDataWitness } from '../trees/public_data_witness.js';
 import {
   BlockHeader,
+  type IndexedTxEffect,
   PublicSimulationOutput,
   Tx,
   TxHash,
   TxReceipt,
   type TxValidationResult,
   TxValidationResultSchema,
+  indexedTxSchema,
 } from '../tx/index.js';
-import { TxEffect } from '../tx/tx_effect.js';
 import { ValidatorsStatsSchema } from '../validators/schemas.js';
 import type { ValidatorsStats } from '../validators/types.js';
 import { type ComponentsVersions, getVersioningResponseHandler } from '../versioning/index.js';
@@ -330,11 +331,11 @@ export interface AztecNode
   getTxReceipt(txHash: TxHash): Promise<TxReceipt>;
 
   /**
-   * Get a tx effect.
-   * @param txHash - The hash of a transaction which resulted in the returned tx effect.
-   * @returns The requested tx effect.
+   * Gets a tx effect.
+   * @param txHash - The hash of the tx corresponding to the tx effect.
+   * @returns The requested tx effect with block info (or undefined if not found).
    */
-  getTxEffect(txHash: TxHash): Promise<InBlock<TxEffect> | undefined>;
+  getTxEffect(txHash: TxHash): Promise<IndexedTxEffect | undefined>;
 
   /**
    * Method to retrieve pending txs.
@@ -516,7 +517,7 @@ export const AztecNodeApiSchema: ApiSchemaFor<AztecNode> = {
 
   getTxReceipt: z.function().args(TxHash.schema).returns(TxReceipt.schema),
 
-  getTxEffect: z.function().args(TxHash.schema).returns(inBlockSchemaFor(TxEffect.schema).optional()),
+  getTxEffect: z.function().args(TxHash.schema).returns(indexedTxSchema().optional()),
 
   getPendingTxs: z.function().returns(z.array(Tx.schema)),
 

package/src/interfaces/pxe.ts

@@ -10,7 +10,6 @@ import type { AbiDecoded } from '../abi/decoder.js';
 import type { EventSelector } from '../abi/event_selector.js';
 import { AuthWitness } from '../auth_witness/auth_witness.js';
 import type { AztecAddress } from '../aztec-address/index.js';
-import { type InBlock, inBlockSchemaFor } from '../block/in_block.js';
 import { L2Block } from '../block/l2_block.js';
 import {
   CompleteAddress,
@@ -29,10 +28,18 @@ import { type LogFilter, LogFilterSchema } from '../logs/log_filter.js';
 import { UniqueNote } from '../note/extended_note.js';
 import { type NotesFilter, NotesFilterSchema } from '../note/notes_filter.js';
 import { AbiDecodedSchema, optional, schemas } from '../schemas/schemas.js';
-import { PrivateExecutionResult, Tx, TxExecutionRequest, TxHash, TxReceipt, TxSimulationResult } from '../tx/index.js';
+import {
+  type IndexedTxEffect,
+  PrivateExecutionResult,
+  Tx,
+  TxExecutionRequest,
+  TxHash,
+  TxReceipt,
+  TxSimulationResult,
+  indexedTxSchema,
+} from '../tx/index.js';
 import { TxProfileResult } from '../tx/profiled_tx.js';
 import { TxProvingResult } from '../tx/proven_tx.js';
-import { TxEffect } from '../tx/tx_effect.js';
 import {
   type GetContractClassLogsResponse,
   GetContractClassLogsResponseSchema,
@@ -202,11 +209,11 @@ export interface PXE {
   getTxReceipt(txHash: TxHash): Promise<TxReceipt>;
 
   /**
-   * Get a tx effect.
-   * @param txHash - The hash of a transaction which resulted in the returned tx effect.
-   * @returns The requested tx effect.
+   * Gets a tx effect.
+   * @param txHash - The hash of the tx corresponding to the tx effect.
+   * @returns The requested tx effect with block info (or undefined if not found).
    */
-  getTxEffect(txHash: TxHash): Promise<InBlock<TxEffect> | undefined>;
+  getTxEffect(txHash: TxHash): Promise<IndexedTxEffect | undefined>;
 
   /**
    * Gets the storage value at the given contract storage slot.
@@ -470,10 +477,7 @@ export const PXESchema: ApiSchemaFor<PXE> = {
     .returns(TxSimulationResult.schema),
   sendTx: z.function().args(Tx.schema).returns(TxHash.schema),
   getTxReceipt: z.function().args(TxHash.schema).returns(TxReceipt.schema),
-  getTxEffect: z
-    .function()
-    .args(TxHash.schema)
-    .returns(z.union([inBlockSchemaFor(TxEffect.schema), z.undefined()])),
+  getTxEffect: z.function().args(TxHash.schema).returns(indexedTxSchema().optional()),
   getPublicStorageAt: z.function().args(schemas.AztecAddress, schemas.Fr).returns(schemas.Fr),
   getNotes: z.function().args(NotesFilterSchema).returns(z.array(UniqueNote.schema)),
   getL1ToL2MembershipWitness: z

package/src/interfaces/world_state.ts

@@ -68,10 +68,11 @@ export interface WorldStateSynchronizer extends ForkMerkleTreeOperations {
 
   /**
    * Forces an immediate sync to an optionally provided minimum block number
-   * @param minBlockNumber - The minimum block number that we must sync to (may sync further)
+   * @param targetBlockNumber - The target block number that we must sync to. Will download unproven blocks if needed to reach it.
+   * @param skipThrowIfTargetNotReached - Whether to skip throwing if the target block number is not reached.
    * @returns A promise that resolves with the block number the world state was synced to
    */
-  syncImmediate(minBlockNumber?: number): Promise<number>;
+  syncImmediate(minBlockNumber?: number, skipThrowIfTargetNotReached?: boolean): Promise<number>;
 
   /** Returns an instance of MerkleTreeAdminOperations that will not include uncommitted data. */
   getCommitted(): MerkleTreeReadOperations;

package/src/logs/log_with_tx_data.ts

@@ -1,12 +1,13 @@
 import { MAX_NOTE_HASHES_PER_TX, PUBLIC_LOG_DATA_SIZE_IN_FIELDS } from '@aztec/constants';
 import { Fr } from '@aztec/foundation/fields';
+import { TxHash } from '@aztec/stdlib/tx';
 
 // TypeScript representation of the Noir aztec::oracle::message_discovery::LogWithTxData struct. This is used as a
 // response for PXE's custom getLogByTag oracle.
 export class LogWithTxData {
   constructor(
     public logContent: Fr[],
-    public txHash: Fr,
+    public txHash: TxHash,
     public uniqueNoteHashesInTx: Fr[],
     public firstNullifierInTx: Fr,
   ) {}
@@ -14,14 +15,14 @@ export class LogWithTxData {
   toNoirSerialization(): (Fr | Fr[])[] {
     return [
       ...toBoundedVecSerialization(this.logContent, PUBLIC_LOG_DATA_SIZE_IN_FIELDS),
-      this.txHash,
+      this.txHash.hash,
       ...toBoundedVecSerialization(this.uniqueNoteHashesInTx, MAX_NOTE_HASHES_PER_TX),
       this.firstNullifierInTx,
     ];
   }
 
   static noirSerializationOfEmpty(): (Fr | Fr[])[] {
-    return new LogWithTxData([], new Fr(0), [], new Fr(0)).toNoirSerialization();
+    return new LogWithTxData([], TxHash.zero(), [], new Fr(0)).toNoirSerialization();
   }
 }