@aztec/archiver 4.0.0-nightly.20250907 → 4.0.0-nightly.20260108

package/src/archiver/l1/spire_proposer.ts

@@ -0,0 +1,160 @@
+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 the target address and calldata of the wrapped call if validation succeeds and there is a single call.
+ * @param tx - The transaction to decode
+ * @param publicClient - The viem public client for proxy verification
+ * @param logger - Logger instance
+ * @returns Object with 'to' and 'data' of the wrapped call, or undefined if validation fails
+ */
+export async function getCallFromSpireProposer(
+  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;
+
+    // Validate exactly ONE call (see ./README.md for rationale)
+    if (calls.length !== 1) {
+      logger.warn(`Spire Proposer multicall must contain exactly one call (got ${calls.length})`, { txHash });
+      return undefined;
+    }
+
+    const call = calls[0];
+
+    // Successfully extracted the single wrapped call
+    logger.trace(`Decoded Spire Proposer with single call to ${call.target}`, { txHash });
+    return { 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/archiver/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/archiver/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/archiver/l1/validate_trace.ts

@@ -0,0 +1,211 @@
+import type { ViemPublicDebugClient } from '@aztec/ethereum/types';
+import { 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';
+
+const logger = createLogger('aztec:archiver:validate_trace');
+
+/**
+ * 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')
+ * @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,
+): 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
+ * @returns Object indicating which trace methods are available for recent and old blocks
+ */
+export async function validateTraceAvailability(client: ViemPublicDebugClient): Promise<TraceAvailability> {
+  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',
+    );
+
+    // Test trace_transaction with recent block
+    result.traceTransactionRecent = await testTraceMethod(
+      client,
+      recentTxHash,
+      traceTransactionResponseSchema,
+      'trace_transaction',
+      'recent',
+    );
+
+    // 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');
+
+    // Test trace_transaction with old block
+    result.traceTransactionOld = await testTraceMethod(
+      client,
+      oldTxHash,
+      traceTransactionResponseSchema,
+      'trace_transaction',
+      'old',
+    );
+  } 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
+ * @throws Error if ethereumAllowNoDebugHosts is false and no trace methods are available
+ */
+export async function validateAndLogTraceAvailability(
+  client: ViemPublicDebugClient,
+  ethereumAllowNoDebugHosts: boolean,
+): Promise<void> {
+  logger.info('Validating trace/debug method availability...');
+
+  const availability = await validateTraceAvailability(client);
+
+  // 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/archiver/structs/inbox_message.ts

@@ -1,14 +1,14 @@
+import { CheckpointNumber } from '@aztec/foundation/branded-types';
 import { Buffer16, Buffer32 } from '@aztec/foundation/buffer';
-import { keccak256 } from '@aztec/foundation/crypto';
-import { Fr } from '@aztec/foundation/fields';
+import { keccak256 } from '@aztec/foundation/crypto/keccak';
+import { Fr } from '@aztec/foundation/curves/bn254';
 import { BufferReader, bigintToUInt64BE, numToUInt32BE, serializeToBuffer } from '@aztec/foundation/serialize';
-import type { UInt32 } from '@aztec/stdlib/types';
 
 export type InboxMessage = {
   index: bigint;
   leaf: Fr;
-  l2BlockNumber: UInt32;
-  l1BlockNumber: bigint;
+  checkpointNumber: CheckpointNumber;
+  l1BlockNumber: bigint; // L1 block number - NOT Aztec L2
   l1BlockHash: Buffer32;
   rollingHash: Buffer16;
 };
@@ -24,7 +24,7 @@ export function serializeInboxMessage(message: InboxMessage): Buffer {
     message.leaf,
     message.l1BlockHash,
     numToUInt32BE(Number(message.l1BlockNumber)),
-    numToUInt32BE(message.l2BlockNumber),
+    numToUInt32BE(message.checkpointNumber),
     message.rollingHash,
   ]);
 }
@@ -35,7 +35,7 @@ export function deserializeInboxMessage(buffer: Buffer): InboxMessage {
   const leaf = reader.readObject(Fr);
   const l1BlockHash = reader.readObject(Buffer32);
   const l1BlockNumber = BigInt(reader.readNumber());
-  const l2BlockNumber = reader.readNumber();
+  const checkpointNumber = CheckpointNumber(reader.readNumber());
   const rollingHash = reader.readObject(Buffer16);
-  return { index, leaf, l1BlockHash, l1BlockNumber, l2BlockNumber, rollingHash };
+  return { index, leaf, l1BlockHash, l1BlockNumber, checkpointNumber, rollingHash };
 }

package/src/archiver/structs/published.ts

@@ -1 +1 @@
-export type { PublishedL2Block, L1PublishedData } from '@aztec/stdlib/block';
+export type { L1PublishedData, PublishedCheckpoint } from '@aztec/stdlib/checkpoint';