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

package/src/l1/debug_tx.ts

@@ -0,0 +1,99 @@
+import type { DebugCallTrace, ViemPublicDebugClient } from '@aztec/ethereum/types';
+import { EthAddress } from '@aztec/foundation/eth-address';
+import type { Logger } from '@aztec/foundation/log';
+import { type ZodFor, schemas } from '@aztec/foundation/schemas';
+import { withHexPrefix } from '@aztec/foundation/string';
+
+import type { Hex } from 'viem';
+import { z } from 'zod';
+
+import type { CallInfo } from './types.js';
+
+/** Zod schema for validating call trace from debug_traceTransaction */
+export const callTraceSchema: ZodFor<DebugCallTrace> = z.lazy(() =>
+  z.object({
+    from: schemas.HexStringWith0x,
+    to: schemas.HexStringWith0x.optional(),
+    type: z.string(),
+    input: schemas.HexStringWith0x.optional(),
+    output: schemas.HexStringWith0x.optional(),
+    gas: schemas.HexStringWith0x.optional(),
+    gasUsed: schemas.HexStringWith0x.optional(),
+    value: schemas.HexStringWith0x.optional(),
+    error: z.string().optional(),
+    calls: z.array(callTraceSchema).optional(),
+  }),
+);
+
+/**
+ * Traces a transaction and extracts all CALL operations to a specific contract and function selector.
+ *
+ * @param client - The Viem public client
+ * @param txHash - The transaction hash to trace
+ * @param targetAddress - The contract address to filter for
+ * @param functionSelector - The 4-byte function selector to filter for (with or without 0x prefix)
+ * @returns Array of CallInfo objects containing from, gasUsed, input, and value for matching calls
+ */
+export async function getSuccessfulCallsFromDebug(
+  client: ViemPublicDebugClient,
+  txHash: Hex,
+  targetAddress: EthAddress,
+  functionSelector: string,
+  logger?: Logger,
+): Promise<CallInfo[]> {
+  // Normalize inputs for comparison
+  const normalizedTarget = targetAddress.toString().toLowerCase();
+  const normalizedSelector = withHexPrefix(functionSelector.toLowerCase());
+
+  // Call debug_traceTransaction with callTracer
+  // Using 'any' here because debug_traceTransaction is not in viem's standard RPC types
+  const rawTrace = await client.request({
+    method: 'debug_traceTransaction',
+    params: [txHash, { tracer: 'callTracer' }],
+  });
+
+  if (rawTrace === null || rawTrace === undefined) {
+    throw new Error(`Failed to retrieve debug_traceTransaction for ${txHash}`);
+  }
+
+  logger?.trace(`Retrieved debug_traceTransaction for ${txHash}`, { trace: rawTrace });
+
+  // Validate the response with zod
+  const trace = callTraceSchema.parse(rawTrace);
+
+  const results: CallInfo[] = [];
+
+  /**
+   * Recursively traverse the call trace tree
+   */
+  function traverseCalls(callTrace: DebugCallTrace) {
+    // Skip calls that have errors, and all its descendants
+    if (callTrace.error) {
+      return;
+    }
+
+    // Check if this is a CALL (not DELEGATECALL or STATICCALL) to the target address with matching selector
+    if (
+      callTrace.type.toUpperCase() === 'CALL' &&
+      callTrace.to?.toLowerCase() === normalizedTarget &&
+      callTrace.input?.toLowerCase().startsWith(normalizedSelector)
+    ) {
+      results.push({
+        from: EthAddress.fromString(callTrace.from),
+        gasUsed: callTrace.gasUsed === undefined ? undefined : BigInt(callTrace.gasUsed),
+        input: callTrace.input,
+        value: callTrace.value ? BigInt(callTrace.value) : 0n,
+      });
+    }
+
+    // Recursively process nested calls
+    for (const nestedCall of callTrace.calls ?? []) {
+      traverseCalls(nestedCall);
+    }
+  }
+
+  // Start traversal from the root trace
+  traverseCalls(trace);
+
+  return results;
+}

package/src/l1/spire_proposer.ts

@@ -0,0 +1,152 @@
+import { EthAddress } from '@aztec/foundation/eth-address';
+import type { Logger } from '@aztec/foundation/log';
+
+import { type Hex, type Transaction, decodeFunctionData, getAddress, trim } from 'viem';
+
+// Spire Proposer Multicall constants
+export const SPIRE_PROPOSER_ADDRESS = '0x9ccc2f3ecde026230e11a5c8799ac7524f2bb294';
+export const SPIRE_PROPOSER_EXPECTED_IMPLEMENTATION = '0x7d38d47e7c82195e6e607d3b0f1c20c615c7bf42';
+
+// EIP-1967 storage slot for implementation address
+// keccak256("eip1967.proxy.implementation") - 1 = 0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc
+export const EIP1967_IMPLEMENTATION_SLOT =
+  '0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc' as const;
+
+// Spire Proposer Multicall ABI
+export const SpireProposerAbi = [
+  {
+    inputs: [
+      {
+        components: [
+          { internalType: 'address', name: 'proposer', type: 'address' },
+          { internalType: 'address', name: 'target', type: 'address' },
+          { internalType: 'bytes', name: 'data', type: 'bytes' },
+          { internalType: 'uint256', name: 'value', type: 'uint256' },
+          { internalType: 'uint256', name: 'gasLimit', type: 'uint256' },
+        ],
+        internalType: 'struct IProposerMulticall.Call[]',
+        name: '_calls',
+        type: 'tuple[]',
+      },
+    ],
+    name: 'multicall',
+    outputs: [],
+    stateMutability: 'nonpayable',
+    type: 'function',
+  },
+] as const;
+
+/**
+ * Verifies that a proxy contract points to the expected implementation using EIP-1967.
+ * @param publicClient - The viem public client
+ * @param proxyAddress - The proxy contract address
+ * @param expectedImplementation - The expected implementation address
+ * @param logger - Logger instance
+ * @returns True if the proxy points to the expected implementation
+ */
+export async function verifyProxyImplementation(
+  publicClient: { getStorageAt: (params: { address: Hex; slot: Hex }) => Promise<Hex | undefined> },
+  proxyAddress: Hex,
+  expectedImplementation: Hex,
+  logger: Logger,
+): Promise<boolean> {
+  try {
+    // Read the EIP-1967 implementation slot
+    const implementationData = await publicClient.getStorageAt({
+      address: proxyAddress,
+      slot: EIP1967_IMPLEMENTATION_SLOT,
+    });
+
+    if (!implementationData) {
+      logger.warn(`No implementation found in EIP-1967 slot for proxy ${proxyAddress}`);
+      return false;
+    }
+
+    // The implementation address is stored in the last 20 bytes of the slot
+    // We need to extract and normalize it for comparison
+    const implementationAddress = getAddress(trim(implementationData));
+    const expectedAddress = getAddress(expectedImplementation);
+
+    const matches = implementationAddress.toLowerCase() === expectedAddress.toLowerCase();
+
+    if (!matches) {
+      logger.warn(`Proxy implementation mismatch: expected ${expectedAddress}, got ${implementationAddress}`, {
+        proxyAddress,
+        expectedImplementation,
+        actualImplementation: implementationAddress,
+      });
+    }
+
+    return matches;
+  } catch (err) {
+    logger.warn(`Failed to verify proxy implementation for ${proxyAddress}: ${err}`);
+    return false;
+  }
+}
+
+/**
+ * Attempts to decode transaction as a Spire Proposer Multicall.
+ * Spire Proposer is a proxy contract that wraps multiple calls.
+ * Returns all wrapped calls if validation succeeds (caller handles hash matching to find the propose call).
+ * @param tx - The transaction to decode
+ * @param publicClient - The viem public client for proxy verification
+ * @param logger - Logger instance
+ * @returns Array of wrapped calls with 'to' and 'data', or undefined if not a valid Spire Proposer tx
+ */
+export async function getCallsFromSpireProposer(
+  tx: Transaction,
+  publicClient: { getStorageAt: (params: { address: Hex; slot: Hex }) => Promise<Hex | undefined> },
+  logger: Logger,
+): Promise<{ to: Hex; data: Hex }[] | undefined> {
+  const txHash = tx.hash;
+
+  try {
+    // Check if transaction is to the Spire Proposer address
+    if (!tx.to || !EthAddress.areEqual(tx.to, SPIRE_PROPOSER_ADDRESS)) {
+      logger.debug(`Transaction is not to Spire Proposer address (to: ${tx.to})`, { txHash });
+      return undefined;
+    }
+
+    // Verify the proxy points to the expected implementation
+    const isValidProxy = await verifyProxyImplementation(
+      publicClient,
+      tx.to as Hex,
+      SPIRE_PROPOSER_EXPECTED_IMPLEMENTATION as Hex,
+      logger,
+    );
+
+    if (!isValidProxy) {
+      logger.warn(`Spire Proposer proxy implementation verification failed`, { txHash, to: tx.to });
+      return undefined;
+    }
+
+    // Try to decode as Spire Proposer multicall
+    const { functionName: spireFunctionName, args: spireArgs } = decodeFunctionData({
+      abi: SpireProposerAbi,
+      data: tx.input,
+    });
+
+    // If not multicall, return undefined
+    if (spireFunctionName !== 'multicall') {
+      logger.warn(`Transaction to Spire Proposer is not multicall (got ${spireFunctionName})`, { txHash });
+      return undefined;
+    }
+
+    if (spireArgs.length !== 1) {
+      logger.warn(`Unexpected number of arguments for Spire Proposer multicall (got ${spireArgs.length})`, {
+        txHash,
+      });
+      return undefined;
+    }
+
+    const [calls] = spireArgs;
+
+    // Return all wrapped calls (hash matching in the caller determines which is the propose call)
+    logger.trace(`Decoded Spire Proposer with ${calls.length} call(s)`, { txHash });
+    return calls.map(call => ({ to: call.target, data: call.data }));
+  } catch (err) {
+    // Any decoding error triggers fallback to trace
+    logger.warn(`Failed to decode Spire Proposer: ${err}`, { txHash });
+    return undefined;
+  }
+}

package/src/l1/trace_tx.ts

@@ -0,0 +1,128 @@
+import type { ViemPublicDebugClient } from '@aztec/ethereum/types';
+import { EthAddress } from '@aztec/foundation/eth-address';
+import type { Logger } from '@aztec/foundation/log';
+import { type ZodFor, schemas } from '@aztec/foundation/schemas';
+import { withHexPrefix } from '@aztec/foundation/string';
+
+import type { Hex } from 'viem';
+import { z } from 'zod';
+
+import type { CallInfo } from './types.js';
+
+/** Zod schema for trace action from trace_transaction */
+const traceActionSchema = z.object({
+  from: schemas.HexStringWith0x,
+  to: schemas.HexStringWith0x.optional(),
+  callType: z.string(),
+  gas: schemas.HexStringWith0x.optional(),
+  input: schemas.HexStringWith0x.optional(),
+  value: schemas.HexStringWith0x.optional(),
+});
+
+/** Zod schema for trace result from trace_transaction */
+const traceResultSchema = z.object({
+  gasUsed: schemas.HexStringWith0x.optional(),
+  output: schemas.HexStringWith0x.optional(),
+});
+
+/** Zod schema for a single trace from trace_transaction */
+export const traceSchema = z.object({
+  action: traceActionSchema,
+  result: traceResultSchema.optional(),
+  error: z.string().optional(),
+  subtraces: z.number(),
+  traceAddress: z.array(z.number()),
+  type: z.string(),
+});
+
+/** Type for trace_transaction response */
+type TraceTransaction = z.infer<typeof traceSchema>;
+
+/** Zod schema for the full trace_transaction response (array of traces) */
+export const traceTransactionResponseSchema: ZodFor<TraceTransaction[]> = z.array(traceSchema);
+
+/**
+ * Traces a transaction and extracts all CALL operations to a specific contract and function selector.
+ * Uses the trace_transaction RPC method which returns a flat array of traces.
+ *
+ * @param client - The Viem public debug client
+ * @param txHash - The transaction hash to trace
+ * @param targetAddress - The contract address to filter for
+ * @param functionSelector - The 4-byte function selector to filter for (with or without 0x prefix)
+ * @returns Array of CallInfo objects containing from, gasUsed, input, and value for matching calls
+ */
+export async function getSuccessfulCallsFromTrace(
+  client: ViemPublicDebugClient,
+  txHash: Hex,
+  targetAddress: EthAddress,
+  functionSelector: string,
+  logger?: Logger,
+): Promise<CallInfo[]> {
+  // Normalize inputs for comparison
+  const normalizedTarget = targetAddress.toString().toLowerCase();
+  const normalizedSelector = withHexPrefix(functionSelector.toLowerCase());
+
+  // Call trace_transaction (no options needed)
+  const rawTrace = await client.request({
+    method: 'trace_transaction',
+    params: [txHash],
+  });
+
+  if (rawTrace === null || rawTrace === undefined) {
+    throw new Error(`Failed to retrieve trace_transaction for ${txHash}`);
+  }
+
+  logger?.trace(`Retrieved trace_transaction for ${txHash}`, { trace: rawTrace });
+
+  // Validate the response with zod
+  const traces = traceTransactionResponseSchema.parse(rawTrace);
+
+  const results: CallInfo[] = [];
+
+  // Build a set of trace addresses that errored - we should skip their descendants
+  // A trace address is the path in the trace tree, represented as an array of indices
+  const erroredTraceAddresses = new Set<string>();
+  for (const trace of traces) {
+    if (trace.error) {
+      erroredTraceAddresses.add(JSON.stringify(trace.traceAddress));
+    }
+  }
+
+  // Helper to check if a trace is a descendant of an errored trace
+  function isDescendantOfError(traceAddress: number[]): boolean {
+    // Check all possible ancestor paths
+    for (let i = 1; i < traceAddress.length; i++) {
+      const ancestorAddress = traceAddress.slice(0, i);
+      if (erroredTraceAddresses.has(JSON.stringify(ancestorAddress))) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  // Process each trace
+  for (const trace of traces) {
+    // Skip if this has an error or is a descendant of an errored trace
+    if (trace.error || isDescendantOfError(trace.traceAddress)) {
+      continue;
+    }
+
+    // Check if this is a CALL type trace to the target address with matching selector and result
+    if (
+      trace.type === 'call' &&
+      trace.action.callType.toLowerCase() === 'call' &&
+      trace.action.to?.toLowerCase() === normalizedTarget &&
+      trace.action.input?.toLowerCase().startsWith(normalizedSelector) &&
+      trace.result
+    ) {
+      results.push({
+        from: EthAddress.fromString(trace.action.from),
+        gasUsed: trace.result.gasUsed === undefined ? undefined : BigInt(trace.result.gasUsed),
+        input: trace.action.input,
+        value: trace.action.value ? BigInt(trace.action.value) : 0n,
+      });
+    }
+  }
+
+  return results;
+}

package/src/l1/types.ts

@@ -0,0 +1,13 @@
+import { EthAddress } from '@aztec/foundation/eth-address';
+
+import type { Hex } from 'viem';
+
+/**
+ * Information about a matching CALL
+ */
+export interface CallInfo {
+  from: EthAddress;
+  gasUsed?: bigint;
+  input: Hex;
+  value: bigint;
+}

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);
+}