@aztec/archiver 0.0.1-commit.f5d02921e → 0.0.1-commit.f7ea82942

package/src/l1/validate_historical_logs.ts

@@ -0,0 +1,140 @@
+import { getPublicClient, getRpcUrlsFromClient } from '@aztec/ethereum/client';
+import { RollupContract } from '@aztec/ethereum/contracts';
+import type { L1ContractAddresses } from '@aztec/ethereum/l1-contract-addresses';
+import type { ViemPublicClient } from '@aztec/ethereum/types';
+import { type Logger, type LoggerBindings, createLogger } from '@aztec/foundation/log';
+
+/** Subset of L1 contract addresses whose historical logs the Aztec node relies on. */
+export type HistoricalLogsContractAddresses = Pick<
+  L1ContractAddresses,
+  'rollupAddress' | 'inboxAddress' | 'registryAddress' | 'governanceProposerAddress'
+>;
+
+/** Result of probing a single RPC URL. */
+type ProbeResult = { ok: true } | { ok: false; reason: string; clientVersion: string | undefined };
+
+/**
+ * Validates that every configured L1 RPC URL returns historical logs for the Rollup contract.
+ *
+ * Some RPC providers prune old logs, which would cause L1 syncing to silently fail. To detect this,
+ * we query for the `OwnershipTransferred` event which every Rollup emits in its constructor (via
+ * Ownable) on the block it was deployed (`l1StartBlock`). The `client` is typically a viem fallback
+ * transport over several user-configured RPC URLs — checking only the first URL would miss a bad
+ * secondary, so we probe each URL independently. The first URL that fails aborts startup, unless
+ * the operator has explicitly opted out.
+ *
+ * @param client - The L1 public client built from the user-configured RPC URLs.
+ * @param addresses - The subset of L1 contract addresses we rely on for historical log retrieval.
+ * @param skipCheck - If true, log warnings instead of throwing.
+ * @param bindings - Optional logger bindings for context.
+ * @throws Error if any URL fails the probe and skipCheck is false.
+ */
+export async function validateAndLogHistoricalLogsAvailability(
+  client: ViemPublicClient,
+  addresses: HistoricalLogsContractAddresses,
+  skipCheck: boolean,
+  bindings?: LoggerBindings,
+): Promise<void> {
+  const logger = createLogger('archiver:validate_historical_logs', bindings);
+  logger.debug('Validating historical log availability on L1 RPCs');
+
+  const urls = getRpcUrlsFromClient(client);
+  if (urls.length === 0) {
+    logger.warn('Could not determine L1 RPC URLs from the public client; skipping historical logs check.');
+    return;
+  }
+
+  const chainId = client.chain?.id;
+  if (chainId === undefined) {
+    logger.warn('Could not determine L1 chain ID from the public client; skipping historical logs check.');
+    return;
+  }
+
+  for (const url of urls) {
+    const probeClient = getPublicClient({ l1RpcUrls: [url], l1ChainId: chainId });
+    const rollup = new RollupContract(probeClient, addresses.rollupAddress.toString());
+    const result = await probeRpcUrl(rollup, probeClient, logger);
+
+    if (result.ok) {
+      logger.debug(`L1 RPC ${url} returned historical OwnershipTransferred log for the Rollup contract.`);
+      continue;
+    }
+
+    const errorMessage = buildErrorMessage(url, result, addresses);
+    if (skipCheck) {
+      logger.warn(`${errorMessage}\nContinuing because ARCHIVER_SKIP_HISTORICAL_LOGS_CHECK is true.`);
+      continue;
+    }
+
+    logger.error(errorMessage);
+    throw new Error(errorMessage);
+  }
+}
+
+/** Runs the OwnershipTransferred probe against a single RPC and queries its client version. */
+async function probeRpcUrl(rollup: RollupContract, client: ViemPublicClient, logger: Logger): Promise<ProbeResult> {
+  let queryError: unknown;
+  try {
+    const logs = await rollup.getOwnershipTransferredEventsAtDeploy();
+    if (logs.length > 0) {
+      return { ok: true };
+    }
+  } catch (err) {
+    queryError = err;
+  }
+
+  const clientVersion = await getClientVersion(client, logger);
+
+  let reason: string;
+  if (queryError instanceof Error) {
+    reason = `Query for historical logs failed: ${queryError.message}`;
+  } else if (queryError !== undefined) {
+    reason = 'Query for historical logs failed with a non-Error value.';
+  } else {
+    reason = 'No OwnershipTransferred event was returned by the L1 RPC for the Rollup deploy block.';
+  }
+  return { ok: false, reason, clientVersion };
+}
+
+/** Builds the operator-facing error message for a failing RPC URL. */
+function buildErrorMessage(
+  url: string,
+  result: Extract<ProbeResult, { ok: false }>,
+  addresses: HistoricalLogsContractAddresses,
+): string {
+  return [
+    `L1 RPC at ${url} does not return historical logs for the Rollup contract. ${result.reason}`,
+    `This likely means this Ethereum RPC node prunes old logs, which would cause the archiver ` +
+      `to silently miss data during L1 sync.`,
+    result.clientVersion
+      ? `Detected L1 client version for ${url}: ${result.clientVersion}.`
+      : `Could not determine L1 client version for ${url}.`,
+    `The following L1 contract addresses must have their historical logs retained by the RPC node:`,
+    `  - Rollup:             ${addresses.rollupAddress.toString()}`,
+    `  - Inbox:              ${addresses.inboxAddress.toString()}`,
+    `  - Registry:           ${addresses.registryAddress.toString()}`,
+    `  - GovernanceProposer: ${addresses.governanceProposerAddress.toString()}`,
+    isReth(result.clientVersion)
+      ? `To retain logs for these contracts, configure reth with a ` +
+        `prune.segments.receipts_log_filter entry for each address above ` +
+        `so reth does not prune their receipts/logs. See https://reth.rs/run/pruning.html for details.`
+      : `Point this RPC endpoint at a node that retains full log history for the addresses above.`,
+    `Set ARCHIVER_SKIP_HISTORICAL_LOGS_CHECK=true to bypass this check at your own risk.`,
+  ].join('\n');
+}
+
+/** Queries `web3_clientVersion` on the L1 RPC. Returns undefined if the call fails or returns a non-string. */
+async function getClientVersion(client: ViemPublicClient, logger: Logger): Promise<string | undefined> {
+  try {
+    const result = await client.request({ method: 'web3_clientVersion' });
+    return typeof result === 'string' ? result : undefined;
+  } catch (err) {
+    logger.debug(`Failed to query web3_clientVersion: ${err instanceof Error ? err.message : err}`);
+    return undefined;
+  }
+}
+
+/** Heuristic check for reth based on the web3_clientVersion string (reth returns e.g. "reth/v1.0.0-..."). */
+function isReth(clientVersion: string | undefined): boolean {
+  return !!clientVersion && /reth/i.test(clientVersion);
+}

package/src/modules/data_store_updater.ts

@@ -6,8 +6,13 @@ import {
   ContractInstancePublishedEvent,
   ContractInstanceUpdatedEvent,
 } from '@aztec/protocol-contracts/instance-registry';
-import type { L2Block, ValidateCheckpointResult } from '@aztec/stdlib/block';
-import { type ProposedCheckpointInput, type PublishedCheckpoint, validateCheckpoint } from '@aztec/stdlib/checkpoint';
+import type { CommitteeAttestation, L2Block, ValidateCheckpointResult } from '@aztec/stdlib/block';
+import {
+  type L1PublishedData,
+  type ProposedCheckpointInput,
+  type PublishedCheckpoint,
+  validateCheckpoint,
+} from '@aztec/stdlib/checkpoint';
 import {
   type ContractClassPublicWithCommitment,
   computeContractAddressFromInstance,
@@ -79,18 +84,29 @@ export class ArchiverDataStoreUpdater {
    * Adds new checkpoints to the store with contract class/instance extraction from logs.
    * Prunes any local blocks that conflict with checkpoint data (by comparing archive roots).
    * Extracts ContractClassPublished, ContractInstancePublished, ContractInstanceUpdated events from the checkpoint block logs.
+   * If `promoteProposed` is supplied, the proposed-checkpoint promotion runs inside the same transaction
+   * as the added checkpoints so both updates are applied atomically.
    *
-   * @param checkpoints - The published checkpoints to add.
+   * @param checkpoints - The published checkpoints to add (excluding any being promoted from proposed).
    * @param pendingChainValidationStatus - Optional validation status to set.
+   * @param promoteProposed - Optional promotion of the current proposed checkpoint (fast path when blocks are already local).
    * @returns Result with information about any pruned blocks.
    */
   public async addCheckpoints(
     checkpoints: PublishedCheckpoint[],
     pendingChainValidationStatus?: ValidateCheckpointResult,
+    promoteProposed?: {
+      l1: L1PublishedData;
+      attestations: CommitteeAttestation[];
+      checkpoint: PublishedCheckpoint;
+    },
   ): Promise<ReconcileCheckpointsResult> {
     for (const checkpoint of checkpoints) {
       validateCheckpoint(checkpoint.checkpoint, { rollupManaLimit: this.opts?.rollupManaLimit });
     }
+    if (promoteProposed) {
+      validateCheckpoint(promoteProposed.checkpoint.checkpoint, { rollupManaLimit: this.opts?.rollupManaLimit });
+    }
 
     const result = await this.store.transactionAsync(async () => {
       // Before adding checkpoints, check for conflicts with local blocks if any
@@ -110,6 +126,14 @@ export class ArchiverDataStoreUpdater {
         this.store.addLogs(newBlocks),
         // Unroll all logs emitted during the retrieved blocks and extract any contract classes and instances from them
         ...newBlocks.map(block => this.addContractDataToDb(block)),
+        // Promote the proposed checkpoint if requested
+        promoteProposed
+          ? this.store.promoteProposedToCheckpointed(
+              promoteProposed.l1,
+              promoteProposed.attestations,
+              promoteProposed.checkpoint.checkpoint.archive.root,
+            )
+          : undefined,
       ]);
 
       await this.l2TipsCache?.refresh();

package/src/modules/instrumentation.ts

@@ -32,6 +32,7 @@ export class ArchiverInstrumentation {
   private pruneCount: UpDownCounter;
 
   private syncDurationPerBlock: Histogram;
+  private syncDurationPerCheckpoint: Histogram;
   private syncBlockCount: UpDownCounter;
   private manaPerBlock: Histogram;
   private txsPerBlock: Histogram;
@@ -42,6 +43,7 @@ export class ArchiverInstrumentation {
   private blockProposalTxTargetCount: UpDownCounter;
 
   private checkpointL1InclusionDelay: Histogram;
+  private checkpointPromotedCount: UpDownCounter;
 
   private log = createLogger('archiver:instrumentation');
 
@@ -68,6 +70,8 @@ export class ArchiverInstrumentation {
 
     this.syncDurationPerBlock = meter.createHistogram(Metrics.ARCHIVER_SYNC_PER_BLOCK);
 
+    this.syncDurationPerCheckpoint = meter.createHistogram(Metrics.ARCHIVER_SYNC_PER_CHECKPOINT);
+
     this.syncBlockCount = createUpDownCounterWithDefault(meter, Metrics.ARCHIVER_SYNC_BLOCK_COUNT);
 
     this.manaPerBlock = meter.createHistogram(Metrics.ARCHIVER_MANA_PER_BLOCK);
@@ -92,6 +96,8 @@ export class ArchiverInstrumentation {
 
     this.checkpointL1InclusionDelay = meter.createHistogram(Metrics.ARCHIVER_CHECKPOINT_L1_INCLUSION_DELAY);
 
+    this.checkpointPromotedCount = createUpDownCounterWithDefault(meter, Metrics.ARCHIVER_CHECKPOINT_PROMOTED_COUNT);
+
     this.dbMetrics = new LmdbMetrics(
       meter,
       {
@@ -113,17 +119,26 @@ export class ArchiverInstrumentation {
     return this.telemetry.isEnabled();
   }
 
-  public processNewBlocks(syncTimePerBlock: number, blocks: L2Block[]) {
+  public processNewProposedBlock(syncTimePerBlock: number, block: L2Block) {
+    const attrs = { [Attributes.STATUS]: 'proposed' };
+    this.blockHeight.record(block.number, attrs);
     this.syncDurationPerBlock.record(Math.ceil(syncTimePerBlock));
+
+    // Per block metrics
+    this.txCount.add(block.body.txEffects.length);
+    this.txsPerBlock.record(block.body.txEffects.length);
+    this.manaPerBlock.record(block.header.totalManaUsed.toNumber() / 1e6);
+  }
+
+  public processNewCheckpointedBlocks(syncTimePerCheckpoint: number, blocks: L2Block[]) {
+    if (blocks.length === 0) {
+      return;
+    }
+
+    this.syncDurationPerCheckpoint.record(Math.ceil(syncTimePerCheckpoint));
     this.blockHeight.record(Math.max(...blocks.map(b => b.number)));
     this.checkpointHeight.record(Math.max(...blocks.map(b => b.checkpointNumber)));
     this.syncBlockCount.add(blocks.length);
-
-    for (const block of blocks) {
-      this.txCount.add(block.body.txEffects.length);
-      this.txsPerBlock.record(block.body.txEffects.length);
-      this.manaPerBlock.record(block.header.totalManaUsed.toNumber() / 1e6);
-    }
   }
 
   public processNewMessages(count: number, syncPerMessageMs: number) {
@@ -169,6 +184,11 @@ export class ArchiverInstrumentation {
     });
   }
 
+  /** Records a checkpoint promoted from proposed (blob fetch skipped). */
+  public processCheckpointPromoted() {
+    this.checkpointPromotedCount.add(1);
+  }
+
   /**
    * Records L1 inclusion timing for a checkpoint observed on L1 (seconds into the L2 slot).
    */