@aztec/archiver 0.0.1-commit.5daedc8 → 0.0.1-commit.6201a7b05

package/src/l1/validate_trace.ts

@@ -0,0 +1,229 @@
+import type { ViemPublicDebugClient } from '@aztec/ethereum/types';
+import { type Logger, type LoggerBindings, createLogger } from '@aztec/foundation/log';
+
+import type { Hex } from 'viem';
+import type { ZodSchema } from 'zod';
+
+import { callTraceSchema } from './debug_tx.js';
+import { traceTransactionResponseSchema } from './trace_tx.js';
+
+/**
+ * Helper function to test a trace method with validation
+ *
+ * @param client - The Viem public debug client
+ * @param txHash - Transaction hash to trace
+ * @param schema - Zod schema to validate the response
+ * @param method - Name of the RPC method ('debug_traceTransaction' or 'trace_transaction')
+ * @param blockType - Type of block being tested ('recent' or 'old')
+ * @param logger - Logger instance
+ * @returns true if the method works and validation passes, false otherwise
+ */
+async function testTraceMethod(
+  client: ViemPublicDebugClient,
+  txHash: Hex,
+  schema: ZodSchema,
+  method: 'debug_traceTransaction' | 'trace_transaction',
+  blockType: string,
+  logger: Logger,
+): Promise<boolean> {
+  try {
+    // Make request with appropriate params based on method name
+    const result = await client.request(
+      method === 'debug_traceTransaction'
+        ? { method, params: [txHash, { tracer: 'callTracer' }] }
+        : { method, params: [txHash] },
+    );
+
+    schema.parse(result);
+    logger.debug(`${method} works for ${blockType} blocks`);
+    return true;
+  } catch (error) {
+    logger.warn(`${method} failed for ${blockType} blocks: ${error}`);
+    return false;
+  }
+}
+
+/** Result of trace availability checks */
+export interface TraceAvailability {
+  /** Whether debug_traceTransaction works for recent blocks */
+  debugTraceRecent: boolean;
+  /** Whether trace_transaction works for recent blocks */
+  traceTransactionRecent: boolean;
+  /** Whether debug_traceTransaction works for old blocks (512 blocks ago) */
+  debugTraceOld: boolean;
+  /** Whether trace_transaction works for old blocks (512 blocks ago) */
+  traceTransactionOld: boolean;
+}
+
+/**
+ * Validates the availability of debug/trace methods on the Ethereum client.
+ *
+ * @param client - The Viem public debug client
+ * @param bindings - Optional logger bindings for context
+ * @returns Object indicating which trace methods are available for recent and old blocks
+ */
+export async function validateTraceAvailability(
+  client: ViemPublicDebugClient,
+  bindings?: LoggerBindings,
+): Promise<TraceAvailability> {
+  const logger = createLogger('archiver:validate_trace', bindings);
+  const result: TraceAvailability = {
+    debugTraceRecent: false,
+    traceTransactionRecent: false,
+    debugTraceOld: false,
+    traceTransactionOld: false,
+  };
+
+  try {
+    // Get the latest block
+    let latestBlock = await client.getBlock({ blockTag: 'latest' });
+    let attempts = 10;
+
+    // Loop back to find a block with transactions (handles dev/test scenarios)
+    while (!hasTxs(latestBlock) && latestBlock.number && latestBlock.number > 0n && --attempts > 0) {
+      logger.debug(`Block ${latestBlock.number} has no transactions, checking previous block`);
+      latestBlock = await client.getBlock({ blockNumber: latestBlock.number - 1n });
+    }
+
+    if (!hasTxs(latestBlock)) {
+      logger.warn('No blocks with transactions found from latest back to genesis, cannot validate trace availability');
+      return result;
+    }
+
+    // Get a transaction from the found block
+    const recentTxHash = latestBlock.transactions[0] as Hex;
+
+    // Test debug_traceTransaction with recent block
+    result.debugTraceRecent = await testTraceMethod(
+      client,
+      recentTxHash,
+      callTraceSchema,
+      'debug_traceTransaction',
+      'recent',
+      logger,
+    );
+
+    // Test trace_transaction with recent block
+    result.traceTransactionRecent = await testTraceMethod(
+      client,
+      recentTxHash,
+      traceTransactionResponseSchema,
+      'trace_transaction',
+      'recent',
+      logger,
+    );
+
+    // Get a block from 512 blocks ago
+    const oldBlockNumber = latestBlock.number ? latestBlock.number - 512n : null;
+    if (!oldBlockNumber || oldBlockNumber < 0n) {
+      logger.debug('Cannot test old blocks, blockchain too short');
+      return result;
+    }
+
+    let oldBlock = await client.getBlock({ blockNumber: oldBlockNumber });
+    attempts = 10;
+
+    // Loop back to find a block with transactions (handles dev/test scenarios)
+    while (!hasTxs(oldBlock) && oldBlock.number && oldBlock.number > 0n && --attempts > 0) {
+      logger.debug(`Block ${oldBlock.number} has no transactions, checking previous block`);
+      oldBlock = await client.getBlock({ blockNumber: oldBlock.number - 1n });
+    }
+
+    if (!hasTxs(oldBlock)) {
+      logger.debug(
+        'No blocks with transactions found from old block back to genesis, cannot validate trace availability for old blocks',
+      );
+      return result;
+    }
+
+    const oldTxHash = oldBlock.transactions[0] as Hex;
+
+    // Test debug_traceTransaction with old block
+    result.debugTraceOld = await testTraceMethod(
+      client,
+      oldTxHash,
+      callTraceSchema,
+      'debug_traceTransaction',
+      'old',
+      logger,
+    );
+
+    // Test trace_transaction with old block
+    result.traceTransactionOld = await testTraceMethod(
+      client,
+      oldTxHash,
+      traceTransactionResponseSchema,
+      'trace_transaction',
+      'old',
+      logger,
+    );
+  } catch (error) {
+    logger.warn(`Error validating debug_traceTransaction and trace_transaction availability: ${error}`);
+  }
+
+  return result;
+}
+
+function hasTxs(block: { transactions?: Hex[] }): boolean {
+  return Array.isArray(block.transactions) && block.transactions.length > 0;
+}
+
+/**
+ * Validates trace availability and logs appropriate messages based on the results.
+ * Optionally throws an error if no trace methods are available and ethereumAllowNoDebugHosts is false.
+ *
+ * @param client - The Viem public debug client
+ * @param ethereumAllowNoDebugHosts - If false, throws an error when no trace methods are available
+ * @param bindings - Optional logger bindings for context
+ * @throws Error if ethereumAllowNoDebugHosts is false and no trace methods are available
+ */
+export async function validateAndLogTraceAvailability(
+  client: ViemPublicDebugClient,
+  ethereumAllowNoDebugHosts: boolean,
+  bindings?: LoggerBindings,
+): Promise<void> {
+  const logger = createLogger('archiver:validate_trace', bindings);
+  logger.debug('Validating trace/debug method availability...');
+
+  const availability = await validateTraceAvailability(client, bindings);
+
+  // Check if we have support for old blocks (either debug or trace)
+  const hasOldBlockSupport = availability.debugTraceOld || availability.traceTransactionOld;
+
+  if (hasOldBlockSupport) {
+    // Ideal case: we have trace support for old blocks
+    const methods: string[] = [];
+    if (availability.debugTraceOld) {
+      methods.push('debug_traceTransaction');
+    }
+    if (availability.traceTransactionOld) {
+      methods.push('trace_transaction');
+    }
+    logger.info(
+      `Ethereum client supports trace methods for old blocks (${methods.join(', ')}). Archiver can retrieve historical transaction traces.`,
+    );
+  } else if (availability.debugTraceRecent || availability.traceTransactionRecent) {
+    // Warning case: only recent block support
+    const methods: string[] = [];
+    if (availability.debugTraceRecent) {
+      methods.push('debug_traceTransaction');
+    }
+    if (availability.traceTransactionRecent) {
+      methods.push('trace_transaction');
+    }
+    logger.warn(
+      `Ethereum client only supports trace methods for recent blocks (${methods.join(', ')}). Historical transaction traces may not be available.`,
+    );
+  } else {
+    // Error case: no support at all
+    const errorMessage =
+      'Ethereum debug client does not support debug_traceTransaction or trace_transaction methods. Transaction tracing will not be available. This may impact archiver syncing.';
+
+    if (ethereumAllowNoDebugHosts) {
+      logger.warn(`${errorMessage} Continuing because ETHEREUM_ALLOW_NO_DEBUG_HOSTS is set to true.`);
+    } else {
+      logger.error(errorMessage);
+      throw new Error(`${errorMessage} Set ETHEREUM_ALLOW_NO_DEBUG_HOSTS=true to bypass this check.`);
+    }
+  }
+}

package/src/modules/data_source_base.ts

@@ -0,0 +1,364 @@
+import { range } from '@aztec/foundation/array';
+import { BlockNumber, CheckpointNumber, type EpochNumber, type SlotNumber } from '@aztec/foundation/branded-types';
+import type { Fr } from '@aztec/foundation/curves/bn254';
+import type { EthAddress } from '@aztec/foundation/eth-address';
+import { isDefined } from '@aztec/foundation/types';
+import type { FunctionSelector } from '@aztec/stdlib/abi';
+import type { AztecAddress } from '@aztec/stdlib/aztec-address';
+import { type BlockData, type BlockHash, CheckpointedL2Block, L2Block, type L2Tips } from '@aztec/stdlib/block';
+import {
+  Checkpoint,
+  type CheckpointData,
+  type CommonCheckpointData,
+  type ProposedCheckpointData,
+  PublishedCheckpoint,
+} from '@aztec/stdlib/checkpoint';
+import type { ContractClassPublic, ContractDataSource, ContractInstanceWithAddress } from '@aztec/stdlib/contract';
+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 { ArchiverDataSource } from '../interfaces.js';
+import type { KVArchiverDataStore } from '../store/kv_archiver_store.js';
+import type { ValidateCheckpointResult } from './validation.js';
+
+/**
+ * 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 ArchiverDataSourceBase
+  implements ArchiverDataSource, L2LogsSource, ContractDataSource, L1ToL2MessageSource
+{
+  constructor(
+    protected readonly store: KVArchiverDataStore,
+    protected readonly l1Constants?: L1RollupConstants,
+  ) {}
+
+  abstract getRollupAddress(): Promise<EthAddress>;
+
+  abstract getRegistryAddress(): Promise<EthAddress>;
+
+  abstract getL1Constants(): Promise<L1RollupConstants>;
+
+  abstract getGenesisValues(): Promise<{ genesisArchiveRoot: Fr }>;
+
+  abstract getL1Timestamp(): Promise<bigint | undefined>;
+
+  abstract getL2Tips(): Promise<L2Tips>;
+
+  abstract getSyncedL2SlotNumber(): Promise<SlotNumber | undefined>;
+
+  abstract getSyncedL2EpochNumber(): Promise<EpochNumber | undefined>;
+
+  abstract isEpochComplete(epochNumber: EpochNumber): Promise<boolean>;
+
+  abstract syncImmediate(): Promise<void>;
+
+  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();
+  }
+
+  public getProvenBlockNumber(): Promise<BlockNumber> {
+    return this.store.getProvenBlockNumber();
+  }
+
+  public async getBlockHeader(number: BlockNumber | 'latest'): Promise<BlockHeader | undefined> {
+    const blockNumber = number === 'latest' ? await this.store.getLatestBlockNumber() : number;
+    if (blockNumber === 0) {
+      return undefined;
+    }
+    const headers = await this.store.getBlockHeaders(blockNumber, 1);
+    return headers.length === 0 ? undefined : headers[0];
+  }
+
+  public getCheckpointedBlock(number: BlockNumber): Promise<CheckpointedL2Block | undefined> {
+    return this.store.getCheckpointedBlock(number);
+  }
+
+  public getCheckpointedL2BlockNumber(): Promise<BlockNumber> {
+    return this.store.getCheckpointedL2BlockNumber();
+  }
+
+  public getFinalizedL2BlockNumber(): Promise<BlockNumber> {
+    return this.store.getFinalizedL2BlockNumber();
+  }
+
+  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.blockCount - 1);
+  }
+
+  public getCheckpointedBlocks(from: BlockNumber, limit: number): Promise<CheckpointedL2Block[]> {
+    return this.store.getCheckpointedBlocks(from, limit);
+  }
+
+  public getCheckpointData(checkpointNumber: CheckpointNumber): Promise<CheckpointData | undefined> {
+    return this.store.getCheckpointData(checkpointNumber);
+  }
+
+  public getCheckpointDataRange(from: CheckpointNumber, limit: number): Promise<CheckpointData[]> {
+    return this.store.getCheckpointDataRange(from, limit);
+  }
+
+  public getCheckpointNumberBySlot(slot: SlotNumber): Promise<CheckpointNumber | undefined> {
+    return this.store.getCheckpointNumberBySlot(slot);
+  }
+
+  public getBlockDataWithCheckpointContext(blockNumber: BlockNumber) {
+    return this.store.getBlockDataWithCheckpointContext(blockNumber);
+  }
+
+  public getBlockHeaderByHash(blockHash: BlockHash): Promise<BlockHeader | undefined> {
+    return this.store.getBlockHeaderByHash(blockHash);
+  }
+
+  public getBlockHeaderByArchive(archive: Fr): Promise<BlockHeader | undefined> {
+    return this.store.getBlockHeaderByArchive(archive);
+  }
+
+  public getBlockData(number: BlockNumber): Promise<BlockData | undefined> {
+    return this.store.getBlockData(number);
+  }
+
+  public getBlockDataByArchive(archive: Fr): Promise<BlockData | undefined> {
+    return this.store.getBlockDataByArchive(archive);
+  }
+
+  public async getL2Block(number: BlockNumber): Promise<L2Block | undefined> {
+    // If the number provided is -ve, then return the latest block.
+    if (number < 0) {
+      number = await this.store.getLatestBlockNumber();
+    }
+    if (number === 0) {
+      return undefined;
+    }
+    const publishedBlock = await this.store.getBlock(number);
+    return publishedBlock;
+  }
+
+  public getTxEffect(txHash: TxHash): Promise<IndexedTxEffect | undefined> {
+    return this.store.getTxEffect(txHash);
+  }
+
+  public getSettledTxReceipt(txHash: TxHash): Promise<TxReceipt | undefined> {
+    return this.store.getSettledTxReceipt(txHash, this.l1Constants);
+  }
+
+  public getLastCheckpoint(): Promise<CommonCheckpointData | undefined> {
+    return this.store.getLastCheckpoint();
+  }
+
+  public getLastProposedCheckpoint(): Promise<ProposedCheckpointData | undefined> {
+    return this.store.getLastProposedCheckpoint();
+  }
+
+  public isPendingChainInvalid(): Promise<boolean> {
+    return this.getPendingChainValidationStatus().then(status => !status.valid);
+  }
+
+  public async getPendingChainValidationStatus(): Promise<ValidateCheckpointResult> {
+    return (await this.store.getPendingChainValidationStatus()) ?? { valid: true };
+  }
+
+  public getPrivateLogsByTags(
+    tags: SiloedTag[],
+    page?: number,
+    upToBlockNumber?: BlockNumber,
+  ): Promise<TxScopedL2Log[][]> {
+    return this.store.getPrivateLogsByTags(tags, page, upToBlockNumber);
+  }
+
+  public getPublicLogsByTagsFromContract(
+    contractAddress: AztecAddress,
+    tags: Tag[],
+    page?: number,
+    upToBlockNumber?: BlockNumber,
+  ): Promise<TxScopedL2Log[][]> {
+    return this.store.getPublicLogsByTagsFromContract(contractAddress, tags, page, upToBlockNumber);
+  }
+
+  public getPublicLogs(filter: LogFilter): Promise<GetPublicLogsResponse> {
+    return this.store.getPublicLogs(filter);
+  }
+
+  public getContractClassLogs(filter: LogFilter): Promise<GetContractClassLogsResponse> {
+    return this.store.getContractClassLogs(filter);
+  }
+
+  public getContractClass(id: Fr): Promise<ContractClassPublic | undefined> {
+    return this.store.getContractClass(id);
+  }
+
+  public getBytecodeCommitment(id: Fr): Promise<Fr | undefined> {
+    return this.store.getBytecodeCommitment(id);
+  }
+
+  public async getContract(
+    address: AztecAddress,
+    maybeTimestamp?: UInt64,
+  ): Promise<ContractInstanceWithAddress | undefined> {
+    let timestamp;
+    if (maybeTimestamp === undefined) {
+      const latestBlockHeader = await this.getBlockHeader('latest');
+      // If we get undefined block header, it means that the archiver has not yet synced any block so we default to 0.
+      timestamp = latestBlockHeader ? latestBlockHeader.globalVariables.timestamp : 0n;
+    } else {
+      timestamp = maybeTimestamp;
+    }
+
+    return this.store.getContractInstance(address, timestamp);
+  }
+
+  public getContractClassIds(): Promise<Fr[]> {
+    return this.store.getContractClassIds();
+  }
+
+  public getDebugFunctionName(address: AztecAddress, selector: FunctionSelector): Promise<string | undefined> {
+    return this.store.getDebugFunctionName(address, selector);
+  }
+
+  public registerContractFunctionSignatures(signatures: string[]): Promise<void> {
+    return this.store.registerContractFunctionSignatures(signatures);
+  }
+
+  public getL1ToL2Messages(checkpointNumber: CheckpointNumber): Promise<Fr[]> {
+    return this.store.getL1ToL2Messages(checkpointNumber);
+  }
+
+  public getL1ToL2MessageIndex(l1ToL2Message: Fr): Promise<bigint | undefined> {
+    return this.store.getL1ToL2MessageIndex(l1ToL2Message);
+  }
+
+  public async getCheckpoints(checkpointNumber: CheckpointNumber, limit: number): Promise<PublishedCheckpoint[]> {
+    const checkpoints = await this.store.getRangeOfCheckpoints(checkpointNumber, limit);
+    return Promise.all(checkpoints.map(ch => this.getPublishedCheckpointFromCheckpointData(ch)));
+  }
+
+  private async getPublishedCheckpointFromCheckpointData(checkpoint: CheckpointData): Promise<PublishedCheckpoint> {
+    const blocksForCheckpoint = await this.store.getBlocksForCheckpoint(checkpoint.checkpointNumber);
+    if (!blocksForCheckpoint) {
+      throw new Error(`Blocks for checkpoint ${checkpoint.checkpointNumber} not found`);
+    }
+    const fullCheckpoint = new Checkpoint(
+      checkpoint.archive,
+      checkpoint.header,
+      blocksForCheckpoint,
+      checkpoint.checkpointNumber,
+      checkpoint.feeAssetPriceModifier,
+    );
+    return new PublishedCheckpoint(fullCheckpoint, checkpoint.l1, checkpoint.attestations);
+  }
+
+  public getBlocksForSlot(slotNumber: SlotNumber): Promise<L2Block[]> {
+    return this.store.getBlocksForSlot(slotNumber);
+  }
+
+  public async getCheckpointedBlocksForEpoch(epochNumber: EpochNumber): Promise<CheckpointedL2Block[]> {
+    const checkpointsData = await this.getCheckpointsDataForEpoch(epochNumber);
+    const blocks = await Promise.all(
+      checkpointsData.flatMap(checkpoint =>
+        range(checkpoint.blockCount, checkpoint.startBlock).map(blockNumber =>
+          this.getCheckpointedBlock(BlockNumber(blockNumber)),
+        ),
+      ),
+    );
+    return blocks.filter(isDefined);
+  }
+
+  public async getCheckpointedBlockHeadersForEpoch(epochNumber: EpochNumber): Promise<BlockHeader[]> {
+    const checkpointsData = await this.getCheckpointsDataForEpoch(epochNumber);
+    const blocks = await Promise.all(
+      checkpointsData.flatMap(checkpoint =>
+        range(checkpoint.blockCount, checkpoint.startBlock).map(blockNumber =>
+          this.getBlockHeader(BlockNumber(blockNumber)),
+        ),
+      ),
+    );
+    return blocks.filter(isDefined);
+  }
+
+  public async getCheckpointsForEpoch(epochNumber: EpochNumber): Promise<Checkpoint[]> {
+    const checkpointsData = await this.getCheckpointsDataForEpoch(epochNumber);
+    return Promise.all(
+      checkpointsData.map(data => this.getPublishedCheckpointFromCheckpointData(data).then(p => p.checkpoint)),
+    );
+  }
+
+  /** Returns checkpoint data for all checkpoints whose slot falls within the given epoch. */
+  public getCheckpointsDataForEpoch(epochNumber: EpochNumber): Promise<CheckpointData[]> {
+    if (!this.l1Constants) {
+      throw new Error('L1 constants not set');
+    }
+
+    const [start, end] = getSlotRangeForEpoch(epochNumber, this.l1Constants);
+    return this.store.getCheckpointDataForSlotRange(start, end);
+  }
+
+  public async getBlock(number: BlockNumber): Promise<L2Block | undefined> {
+    // If the number provided is -ve, then return the latest block.
+    if (number < 0) {
+      number = await this.store.getLatestBlockNumber();
+    }
+    if (number === 0) {
+      return undefined;
+    }
+    return this.store.getBlock(number);
+  }
+
+  public getBlocks(from: BlockNumber, limit: number): Promise<L2Block[]> {
+    return this.store.getBlocks(from, limit);
+  }
+
+  public getCheckpointedBlockByHash(blockHash: BlockHash): Promise<CheckpointedL2Block | undefined> {
+    return this.store.getCheckpointedBlockByHash(blockHash);
+  }
+
+  public getCheckpointedBlockByArchive(archive: Fr): Promise<CheckpointedL2Block | undefined> {
+    return this.store.getCheckpointedBlockByArchive(archive);
+  }
+
+  public async getL2BlockByHash(blockHash: BlockHash): Promise<L2Block | undefined> {
+    const checkpointedBlock = await this.store.getCheckpointedBlockByHash(blockHash);
+    return checkpointedBlock?.block;
+  }
+
+  public async getL2BlockByArchive(archive: Fr): Promise<L2Block | undefined> {
+    const checkpointedBlock = await this.store.getCheckpointedBlockByArchive(archive);
+    return checkpointedBlock?.block;
+  }
+}