@aztec/archiver 4.0.0-nightly.20260114 → 4.0.0-nightly.20260115

package/src/factory.ts

@@ -1,15 +1,30 @@
+import { EpochCache } from '@aztec/epoch-cache';
+import { createEthereumChain } from '@aztec/ethereum/chain';
+import { InboxContract, RollupContract } from '@aztec/ethereum/contracts';
+import type { ViemPublicDebugClient } from '@aztec/ethereum/types';
 import { BlockNumber } from '@aztec/foundation/branded-types';
+import { Buffer32 } from '@aztec/foundation/buffer';
+import { merge } from '@aztec/foundation/collection';
+import { Fr } from '@aztec/foundation/curves/bn254';
 import { createLogger } from '@aztec/foundation/log';
+import { DateProvider } from '@aztec/foundation/timer';
 import type { DataStoreConfig } from '@aztec/kv-store/config';
 import { createStore } from '@aztec/kv-store/lmdb-v2';
 import { protocolContractNames } from '@aztec/protocol-contracts';
 import { BundledProtocolContractsProvider } from '@aztec/protocol-contracts/providers/bundle';
 import { FunctionType, decodeFunctionSignature } from '@aztec/stdlib/abi';
+import type { ArchiverEmitter } from '@aztec/stdlib/block';
 import { type ContractClassPublic, computePublicBytecodeCommitment } from '@aztec/stdlib/contract';
+import { getTelemetryClient } from '@aztec/telemetry-client';
 
-import { Archiver, type ArchiverDeps } from './archiver/archiver.js';
-import type { ArchiverConfig } from './archiver/config.js';
-import { ARCHIVER_DB_VERSION, KVArchiverDataStore } from './archiver/kv_archiver_store/kv_archiver_store.js';
+import { EventEmitter } from 'events';
+import { createPublicClient, fallback, http } from 'viem';
+
+import { Archiver, type ArchiverDeps } from './archiver.js';
+import { type ArchiverConfig, mapArchiverConfig } from './config.js';
+import { ArchiverInstrumentation } from './modules/instrumentation.js';
+import { ArchiverL1Synchronizer } from './modules/l1_synchronizer.js';
+import { ARCHIVER_DB_VERSION, KVArchiverDataStore } from './store/kv_archiver_store.js';
 
 export const ARCHIVER_STORE_NAME = 'archiver';
 
@@ -28,9 +43,8 @@ export async function createArchiverStore(
 /**
  * Creates a local archiver.
  * @param config - The archiver configuration.
- * @param blobClient - The blob client client.
+ * @param deps - The archiver dependencies (blobClient, epochCache, dateProvider, telemetry).
  * @param opts - The options.
- * @param telemetry - The telemetry client.
  * @returns The local archiver.
  */
 export async function createArchiver(
@@ -40,7 +54,105 @@ export async function createArchiver(
 ): Promise<Archiver> {
   const archiverStore = await createArchiverStore(config);
   await registerProtocolContracts(archiverStore);
-  return Archiver.createAndSync(config, archiverStore, deps, opts.blockUntilSync);
+
+  // Create Ethereum clients
+  const chain = createEthereumChain(config.l1RpcUrls, config.l1ChainId);
+  const publicClient = createPublicClient({
+    chain: chain.chainInfo,
+    transport: fallback(config.l1RpcUrls.map(url => http(url, { batch: false }))),
+    pollingInterval: config.viemPollingIntervalMS,
+  });
+
+  // Create debug client using debug RPC URLs if available, otherwise fall back to regular RPC URLs
+  const debugRpcUrls = config.l1DebugRpcUrls.length > 0 ? config.l1DebugRpcUrls : config.l1RpcUrls;
+  const debugClient = createPublicClient({
+    chain: chain.chainInfo,
+    transport: fallback(debugRpcUrls.map(url => http(url, { batch: false }))),
+    pollingInterval: config.viemPollingIntervalMS,
+  }) as ViemPublicDebugClient;
+
+  // Create L1 contract instances
+  const rollup = new RollupContract(publicClient, config.l1Contracts.rollupAddress);
+  const inbox = new InboxContract(publicClient, config.l1Contracts.inboxAddress);
+
+  // Fetch L1 constants from rollup contract
+  const [l1StartBlock, l1GenesisTime, proofSubmissionEpochs, genesisArchiveRoot, slashingProposerAddress] =
+    await Promise.all([
+      rollup.getL1StartBlock(),
+      rollup.getL1GenesisTime(),
+      rollup.getProofSubmissionEpochs(),
+      rollup.getGenesisArchiveTreeRoot(),
+      rollup.getSlashingProposerAddress(),
+    ] as const);
+
+  const l1StartBlockHash = await publicClient
+    .getBlock({ blockNumber: l1StartBlock, includeTransactions: false })
+    .then(block => Buffer32.fromString(block.hash));
+
+  const { aztecEpochDuration: epochDuration, aztecSlotDuration: slotDuration, ethereumSlotDuration } = config;
+
+  const l1Constants = {
+    l1StartBlockHash,
+    l1StartBlock,
+    l1GenesisTime,
+    epochDuration,
+    slotDuration,
+    ethereumSlotDuration,
+    proofSubmissionEpochs: Number(proofSubmissionEpochs),
+    genesisArchiveRoot: Fr.fromString(genesisArchiveRoot.toString()),
+  };
+
+  const archiverConfig = merge(
+    {
+      pollingIntervalMs: 10_000,
+      batchSize: 100,
+      maxAllowedEthClientDriftSeconds: 300,
+      ethereumAllowNoDebugHosts: false,
+    },
+    mapArchiverConfig(config),
+  );
+
+  const epochCache = deps.epochCache ?? (await EpochCache.create(config.l1Contracts.rollupAddress, config, deps));
+  const telemetry = deps.telemetry ?? getTelemetryClient();
+  const instrumentation = await ArchiverInstrumentation.new(telemetry, () => archiverStore.estimateSize());
+
+  // Create the event emitter that will be shared by archiver and synchronizer
+  const events = new EventEmitter() as ArchiverEmitter;
+
+  // Create the L1 synchronizer
+  const synchronizer = new ArchiverL1Synchronizer(
+    publicClient,
+    debugClient,
+    rollup,
+    inbox,
+    { ...config.l1Contracts, slashingProposerAddress },
+    archiverStore,
+    archiverConfig,
+    deps.blobClient,
+    epochCache,
+    deps.dateProvider ?? new DateProvider(),
+    instrumentation,
+    l1Constants,
+    events,
+    instrumentation.tracer,
+  );
+
+  const archiver = new Archiver(
+    publicClient,
+    debugClient,
+    rollup,
+    { ...config.l1Contracts, slashingProposerAddress },
+    archiverStore,
+    archiverConfig,
+    deps.blobClient,
+    instrumentation,
+    l1Constants,
+    synchronizer,
+    events,
+  );
+
+  await archiver.start(opts.blockUntilSync);
+  return archiver;
 }
 
 async function registerProtocolContracts(store: KVArchiverDataStore) {

package/src/index.ts

@@ -1,5 +1,12 @@
-export * from './archiver/index.js';
 export * from './factory.js';
-export * from './rpc/index.js';
+export * from './interfaces.js';
+export * from './archiver.js';
+export * from './modules/data_source_base.js';
+export * from './modules/data_store_updater.js';
+export * from './config.js';
 
-export { retrieveCheckpointsFromRollup, retrieveL2ProofVerifiedEvents } from './archiver/l1/data_retrieval.js';
+export { type L1PublishedData } from './structs/published.js';
+export { KVArchiverDataStore, ARCHIVER_DB_VERSION } from './store/kv_archiver_store.js';
+export { ContractInstanceStore } from './store/contract_instance_store.js';
+
+export { retrieveCheckpointsFromRollup, retrieveL2ProofVerifiedEvents } from './l1/data_retrieval.js';

package/src/interfaces.ts

@@ -0,0 +1,9 @@
+import type { L2BlockSource } from '@aztec/stdlib/block';
+import type { ContractDataSource } from '@aztec/stdlib/contract';
+import type { L2LogsSource } from '@aztec/stdlib/interfaces/server';
+import type { L1ToL2MessageSource } from '@aztec/stdlib/messaging';
+
+/**
+ * Helper interface to combine all sources this archiver implementation provides.
+ */
+export type ArchiverDataSource = L2BlockSource & L2LogsSource & ContractDataSource & L1ToL2MessageSource;

package/src/{archiver/l1 → l1}/calldata_retriever.ts

@@ -28,7 +28,7 @@ import {
   toFunctionSelector,
 } from 'viem';
 
-import type { ArchiverInstrumentation } from '../instrumentation.js';
+import type { ArchiverInstrumentation } from '../modules/instrumentation.js';
 import { getSuccessfulCallsFromDebug } from './debug_tx.js';
 import { getCallFromSpireProposer } from './spire_proposer.js';
 import { getSuccessfulCallsFromTrace } from './trace_tx.js';

package/src/{archiver/l1 → l1}/data_retrieval.ts

@@ -30,7 +30,7 @@ import { BlockHeader, GlobalVariables, PartialStateReference, StateReference } f
 import { type Hex, decodeFunctionData, getAbiItem, hexToBytes } from 'viem';
 
 import { NoBlobBodiesFoundError } from '../errors.js';
-import type { ArchiverInstrumentation } from '../instrumentation.js';
+import type { ArchiverInstrumentation } from '../modules/instrumentation.js';
 import type { DataRetrieval } from '../structs/data_retrieval.js';
 import type { InboxMessage } from '../structs/inbox_message.js';
 import { CalldataRetriever } from './calldata_retriever.js';

package/src/{archiver/archive_source_base.ts → modules/data_source_base.ts}

@@ -14,33 +14,32 @@ import {
 } from '@aztec/stdlib/block';
 import { Checkpoint, PublishedCheckpoint } from '@aztec/stdlib/checkpoint';
 import type { ContractClassPublic, ContractDataSource, ContractInstanceWithAddress } from '@aztec/stdlib/contract';
-import type { L1RollupConstants } from '@aztec/stdlib/epoch-helpers';
+import { type L1RollupConstants, getSlotRangeForEpoch } from '@aztec/stdlib/epoch-helpers';
 import type { GetContractClassLogsResponse, GetPublicLogsResponse } from '@aztec/stdlib/interfaces/client';
 import type { L2LogsSource } from '@aztec/stdlib/interfaces/server';
 import type { LogFilter, SiloedTag, Tag, TxScopedL2Log } from '@aztec/stdlib/logs';
 import type { L1ToL2MessageSource } from '@aztec/stdlib/messaging';
+import type { CheckpointHeader } from '@aztec/stdlib/rollup';
 import type { BlockHeader, IndexedTxEffect, TxHash, TxReceipt } from '@aztec/stdlib/tx';
 import type { UInt64 } from '@aztec/stdlib/types';
 
-import type { ArchiveSource } from './archiver.js';
-import type { KVArchiverDataStore } from './kv_archiver_store/kv_archiver_store.js';
+import type { ArchiverDataSource } from '../interfaces.js';
+import type { CheckpointData } from '../store/block_store.js';
+import type { KVArchiverDataStore } from '../store/kv_archiver_store.js';
 import type { ValidateCheckpointResult } from './validation.js';
 
 /**
- * Abstract base class implementing ArchiveSource using a KVArchiverDataStore.
+ * Abstract base class implementing ArchiverDataSource using a KVArchiverDataStore.
  * Provides implementations for all store-delegating methods and declares abstract methods
  * for L1-dependent functionality that subclasses must implement.
  */
-export abstract class ArchiveSourceBase
-  implements ArchiveSource, L2LogsSource, ContractDataSource, L1ToL2MessageSource
+export abstract class ArchiverDataSourceBase
+  implements ArchiverDataSource, L2LogsSource, ContractDataSource, L1ToL2MessageSource
 {
-  protected readonly store: KVArchiverDataStore;
-
-  constructor(store: KVArchiverDataStore) {
-    this.store = store;
-  }
-
-  // Abstract methods that require L1 dependencies
+  constructor(
+    protected readonly store: KVArchiverDataStore,
+    protected readonly l1Constants?: L1RollupConstants,
+  ) {}
 
   abstract getRollupAddress(): Promise<EthAddress>;
 
@@ -58,17 +57,21 @@ export abstract class ArchiveSourceBase
 
   abstract getL2EpochNumber(): Promise<EpochNumber | undefined>;
 
-  abstract getCheckpointsForEpoch(epochNumber: EpochNumber): Promise<Checkpoint[]>;
-
-  abstract getBlocksForEpoch(epochNumber: EpochNumber): Promise<L2Block[]>;
-
-  abstract getBlockHeadersForEpoch(epochNumber: EpochNumber): Promise<BlockHeader[]>;
-
   abstract isEpochComplete(epochNumber: EpochNumber): Promise<boolean>;
 
   abstract syncImmediate(): Promise<void>;
 
-  // Store-delegating methods
+  public getCheckpointNumber(): Promise<CheckpointNumber> {
+    return this.store.getSynchedCheckpointNumber();
+  }
+
+  public getSynchedCheckpointNumber(): Promise<CheckpointNumber> {
+    return this.store.getSynchedCheckpointNumber();
+  }
+
+  public getProvenCheckpointNumber(): Promise<CheckpointNumber> {
+    return this.store.getProvenCheckpointNumber();
+  }
 
   public getBlockNumber(): Promise<BlockNumber> {
     return this.store.getLatestBlockNumber();
@@ -91,6 +94,32 @@ export abstract class ArchiveSourceBase
     return this.store.getCheckpointedBlock(number);
   }
 
+  public getCheckpointedBlockNumber(): Promise<BlockNumber> {
+    return this.store.getCheckpointedL2BlockNumber();
+  }
+
+  public async getCheckpointHeader(number: CheckpointNumber | 'latest'): Promise<CheckpointHeader | undefined> {
+    if (number === 'latest') {
+      number = await this.store.getSynchedCheckpointNumber();
+    }
+    if (number === 0) {
+      return undefined;
+    }
+    const checkpoint = await this.store.getCheckpointData(number);
+    if (!checkpoint) {
+      return undefined;
+    }
+    return checkpoint.header;
+  }
+
+  public async getLastBlockNumberInCheckpoint(checkpointNumber: CheckpointNumber): Promise<BlockNumber | undefined> {
+    const checkpointData = await this.store.getCheckpointData(checkpointNumber);
+    if (!checkpointData) {
+      return undefined;
+    }
+    return BlockNumber(checkpointData.startBlock + checkpointData.numBlocks - 1);
+  }
+
   public async getCheckpointedBlocks(
     from: BlockNumber,
     limit: number,
@@ -151,8 +180,6 @@ export abstract class ArchiveSourceBase
     return blocks;
   }
 
-  // L2LogsSource methods
-
   public getPrivateLogsByTags(tags: SiloedTag[]): Promise<TxScopedL2Log[][]> {
     return this.store.getPrivateLogsByTags(tags);
   }
@@ -169,8 +196,6 @@ export abstract class ArchiveSourceBase
     return this.store.getContractClassLogs(filter);
   }
 
-  // ContractDataSource methods
-
   public getContractClass(id: Fr): Promise<ContractClassPublic | undefined> {
     return this.store.getContractClass(id);
   }
@@ -207,8 +232,6 @@ export abstract class ArchiveSourceBase
     return this.store.registerContractFunctionSignatures(signatures);
   }
 
-  // L1ToL2MessageSource methods
-
   public getL1ToL2Messages(checkpointNumber: CheckpointNumber): Promise<Fr[]> {
     return this.store.getL1ToL2Messages(checkpointNumber);
   }
@@ -217,8 +240,6 @@ export abstract class ArchiveSourceBase
     return this.store.getL1ToL2MessageIndex(l1ToL2Message);
   }
 
-  // Published checkpoint methods
-
   public async getPublishedCheckpoints(
     checkpointNumber: CheckpointNumber,
     limit: number,
@@ -248,6 +269,87 @@ export abstract class ArchiveSourceBase
     return fullCheckpoints;
   }
 
+  public async getBlocksForEpoch(epochNumber: EpochNumber): Promise<L2Block[]> {
+    if (!this.l1Constants) {
+      throw new Error('L1 constants not set');
+    }
+
+    const [start, end] = getSlotRangeForEpoch(epochNumber, this.l1Constants);
+    const blocks: L2Block[] = [];
+
+    // Walk the list of checkpoints backwards and filter by slots matching the requested epoch.
+    // We'll typically ask for checkpoints for a very recent epoch, so we shouldn't need an index here.
+    let checkpoint = await this.store.getCheckpointData(await this.store.getSynchedCheckpointNumber());
+    const slot = (b: CheckpointData) => b.header.slotNumber;
+    while (checkpoint && slot(checkpoint) >= start) {
+      if (slot(checkpoint) <= end) {
+        // push the blocks on backwards
+        const endBlock = checkpoint.startBlock + checkpoint.numBlocks - 1;
+        for (let i = endBlock; i >= checkpoint.startBlock; i--) {
+          const block = await this.getBlock(BlockNumber(i));
+          if (block) {
+            blocks.push(block);
+          }
+        }
+      }
+      checkpoint = await this.store.getCheckpointData(CheckpointNumber(checkpoint.checkpointNumber - 1));
+    }
+
+    return blocks.reverse();
+  }
+
+  public async getBlockHeadersForEpoch(epochNumber: EpochNumber): Promise<BlockHeader[]> {
+    if (!this.l1Constants) {
+      throw new Error('L1 constants not set');
+    }
+
+    const [start, end] = getSlotRangeForEpoch(epochNumber, this.l1Constants);
+    const blocks: BlockHeader[] = [];
+
+    // Walk the list of checkpoints backwards and filter by slots matching the requested epoch.
+    // We'll typically ask for checkpoints for a very recent epoch, so we shouldn't need an index here.
+    let checkpoint = await this.store.getCheckpointData(await this.store.getSynchedCheckpointNumber());
+    const slot = (b: CheckpointData) => b.header.slotNumber;
+    while (checkpoint && slot(checkpoint) >= start) {
+      if (slot(checkpoint) <= end) {
+        // push the blocks on backwards
+        const endBlock = checkpoint.startBlock + checkpoint.numBlocks - 1;
+        for (let i = endBlock; i >= checkpoint.startBlock; i--) {
+          const block = await this.getBlockHeader(BlockNumber(i));
+          if (block) {
+            blocks.push(block);
+          }
+        }
+      }
+      checkpoint = await this.store.getCheckpointData(CheckpointNumber(checkpoint.checkpointNumber - 1));
+    }
+    return blocks.reverse();
+  }
+
+  public async getCheckpointsForEpoch(epochNumber: EpochNumber): Promise<Checkpoint[]> {
+    if (!this.l1Constants) {
+      throw new Error('L1 constants not set');
+    }
+
+    const [start, end] = getSlotRangeForEpoch(epochNumber, this.l1Constants);
+    const checkpoints: Checkpoint[] = [];
+
+    // Walk the list of checkpoints backwards and filter by slots matching the requested epoch.
+    // We'll typically ask for checkpoints for a very recent epoch, so we shouldn't need an index here.
+    let checkpointData = await this.store.getCheckpointData(await this.store.getSynchedCheckpointNumber());
+    const slot = (b: CheckpointData) => b.header.slotNumber;
+    while (checkpointData && slot(checkpointData) >= start) {
+      if (slot(checkpointData) <= end) {
+        // push the checkpoints on backwards
+        const [checkpoint] = await this.getPublishedCheckpoints(checkpointData.checkpointNumber, 1);
+        checkpoints.push(checkpoint.checkpoint);
+      }
+      checkpointData = await this.store.getCheckpointData(CheckpointNumber(checkpointData.checkpointNumber - 1));
+    }
+
+    return checkpoints.reverse();
+  }
+
   public async getPublishedBlocks(from: BlockNumber, limit: number, proven?: boolean): Promise<PublishedL2Block[]> {
     const checkpoints = await this.store.getRangeOfCheckpoints(CheckpointNumber(from), limit);
     const provenCheckpointNumber = await this.store.getProvenCheckpointNumber();
@@ -280,8 +382,6 @@ export abstract class ArchiveSourceBase
     return olbBlocks;
   }
 
-  // Legacy APIs
-
   public async getBlock(number: BlockNumber): Promise<L2Block | undefined> {
     // If the number provided is -ve, then return the latest block.
     if (number < 0) {