@aztec/archiver 2.1.8 → 2.1.9

package/dest/archiver/l1/validate_trace.js

@@ -0,0 +1,150 @@
+import { createLogger } from '@aztec/foundation/log';
+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, txHash, schema, method, blockType) {
+    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;
+    }
+}
+/**
+ * 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) {
+    const result = {
+        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];
+        // 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];
+        // 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) {
+    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, ethereumAllowNoDebugHosts) {
+    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 = [];
+        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 = [];
+        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/dest/index.d.ts

@@ -1,5 +1,5 @@
 export * from './archiver/index.js';
 export * from './factory.js';
 export * from './rpc/index.js';
-export { retrieveBlocksFromRollup, retrieveL2ProofVerifiedEvents } from './archiver/data_retrieval.js';
+export { retrieveBlocksFromRollup, retrieveL2ProofVerifiedEvents } from './archiver/l1/data_retrieval.js';
 //# sourceMappingURL=index.d.ts.map

package/dest/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAC;AACpC,cAAc,cAAc,CAAC;AAC7B,cAAc,gBAAgB,CAAC;AAE/B,OAAO,EAAE,wBAAwB,EAAE,6BAA6B,EAAE,MAAM,8BAA8B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAC;AACpC,cAAc,cAAc,CAAC;AAC7B,cAAc,gBAAgB,CAAC;AAE/B,OAAO,EAAE,wBAAwB,EAAE,6BAA6B,EAAE,MAAM,iCAAiC,CAAC"}

package/dest/index.js

@@ -1,4 +1,4 @@
 export * from './archiver/index.js';
 export * from './factory.js';
 export * from './rpc/index.js';
-export { retrieveBlocksFromRollup, retrieveL2ProofVerifiedEvents } from './archiver/data_retrieval.js';
+export { retrieveBlocksFromRollup, retrieveL2ProofVerifiedEvents } from './archiver/l1/data_retrieval.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aztec/archiver",
-  "version": "2.1.8",
+  "version": "2.1.9",
   "type": "module",
   "exports": {
     ".": "./dest/index.js",
@@ -66,23 +66,24 @@
     ]
   },
   "dependencies": {
-    "@aztec/blob-lib": "2.1.8",
-    "@aztec/blob-sink": "2.1.8",
-    "@aztec/constants": "2.1.8",
-    "@aztec/epoch-cache": "2.1.8",
-    "@aztec/ethereum": "2.1.8",
-    "@aztec/foundation": "2.1.8",
-    "@aztec/kv-store": "2.1.8",
-    "@aztec/l1-artifacts": "2.1.8",
-    "@aztec/noir-protocol-circuits-types": "2.1.8",
-    "@aztec/protocol-contracts": "2.1.8",
-    "@aztec/stdlib": "2.1.8",
-    "@aztec/telemetry-client": "2.1.8",
+    "@aztec/blob-lib": "2.1.9",
+    "@aztec/blob-sink": "2.1.9",
+    "@aztec/constants": "2.1.9",
+    "@aztec/epoch-cache": "2.1.9",
+    "@aztec/ethereum": "2.1.9",
+    "@aztec/foundation": "2.1.9",
+    "@aztec/kv-store": "2.1.9",
+    "@aztec/l1-artifacts": "2.1.9",
+    "@aztec/noir-protocol-circuits-types": "2.1.9",
+    "@aztec/protocol-contracts": "2.1.9",
+    "@aztec/stdlib": "2.1.9",
+    "@aztec/telemetry-client": "2.1.9",
     "lodash.groupby": "^4.6.0",
     "lodash.omit": "^4.5.0",
     "tsc-watch": "^6.0.0",
     "tslib": "^2.5.0",
-    "viem": "npm:@aztec/viem@2.38.2"
+    "viem": "npm:@aztec/viem@2.38.2",
+    "zod": "^3.23.8"
   },
   "devDependencies": {
     "@jest/globals": "^30.0.0",

package/src/archiver/archiver.ts

@@ -4,8 +4,10 @@ import {
   BlockTagTooOldError,
   InboxContract,
   type L1BlockId,
+  type L1ContractAddresses,
   RollupContract,
   type ViemPublicClient,
+  type ViemPublicDebugClient,
   createEthereumChain,
 } from '@aztec/ethereum';
 import { maxBigint } from '@aztec/foundation/bigint';
@@ -77,14 +79,15 @@ import { type GetContractReturnType, type Hex, createPublicClient, fallback, htt
 
 import type { ArchiverDataStore, ArchiverL1SynchPoint } from './archiver_store.js';
 import type { ArchiverConfig } from './config.js';
+import { InitialBlockNumberNotSequentialError, NoBlobBodiesFoundError } from './errors.js';
+import { ArchiverInstrumentation } from './instrumentation.js';
 import {
   retrieveBlocksFromRollup,
   retrieveL1ToL2Message,
   retrieveL1ToL2Messages,
   retrievedBlockToPublishedL2Block,
-} from './data_retrieval.js';
-import { InitialBlockNumberNotSequentialError, NoBlobBodiesFoundError } from './errors.js';
-import { ArchiverInstrumentation } from './instrumentation.js';
+} from './l1/data_retrieval.js';
+import { validateAndLogTraceAvailability } from './l1/validate_trace.js';
 import type { InboxMessage } from './structs/inbox_message.js';
 import type { PublishedL2Block } from './structs/published.js';
 import { type ValidateBlockResult, validateBlockAttestations } from './validation.js';
@@ -107,6 +110,7 @@ function mapArchiverConfig(config: Partial<ArchiverConfig>) {
     batchSize: config.archiverBatchSize,
     skipValidateBlockAttestations: config.skipValidateBlockAttestations,
     maxAllowedEthClientDriftSeconds: config.maxAllowedEthClientDriftSeconds,
+    ethereumAllowNoDebugHosts: config.ethereumAllowNoDebugHosts,
   };
 }
 
@@ -144,6 +148,7 @@ export class Archiver extends (EventEmitter as new () => ArchiverEmitter) implem
   /**
    * Creates a new instance of the Archiver.
    * @param publicClient - A client for interacting with the Ethereum node.
+   * @param debugClient - A client for interacting with the Ethereum node for debug/trace methods.
    * @param rollupAddress - Ethereum address of the rollup contract.
    * @param inboxAddress - Ethereum address of the inbox contract.
    * @param registryAddress - Ethereum address of the registry contract.
@@ -153,13 +158,18 @@ export class Archiver extends (EventEmitter as new () => ArchiverEmitter) implem
    */
   constructor(
     private readonly publicClient: ViemPublicClient,
-    private readonly l1Addresses: { rollupAddress: EthAddress; inboxAddress: EthAddress; registryAddress: EthAddress },
+    private readonly debugClient: ViemPublicDebugClient,
+    private readonly l1Addresses: Pick<
+      L1ContractAddresses,
+      'rollupAddress' | 'inboxAddress' | 'registryAddress' | 'governanceProposerAddress' | 'slashFactoryAddress'
+    > & { slashingProposerAddress: EthAddress },
     readonly dataStore: ArchiverDataStore,
     private config: {
       pollingIntervalMs: number;
       batchSize: number;
       skipValidateBlockAttestations?: boolean;
       maxAllowedEthClientDriftSeconds: number;
+      ethereumAllowNoDebugHosts?: boolean;
     },
     private readonly blobSinkClient: BlobSinkClientInterface,
     private readonly epochCache: EpochCache,
@@ -207,14 +217,24 @@ export class Archiver extends (EventEmitter as new () => ArchiverEmitter) implem
       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))),
+      pollingInterval: config.viemPollingIntervalMS,
+    }) as ViemPublicDebugClient;
+
     const rollup = new RollupContract(publicClient, config.l1Contracts.rollupAddress);
 
-    const [l1StartBlock, l1GenesisTime, proofSubmissionEpochs, genesisArchiveRoot] = await Promise.all([
-      rollup.getL1StartBlock(),
-      rollup.getL1GenesisTime(),
-      rollup.getProofSubmissionEpochs(),
-      rollup.getGenesisArchiveTreeRoot(),
-    ] as const);
+    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 })
@@ -234,7 +254,12 @@ export class Archiver extends (EventEmitter as new () => ArchiverEmitter) implem
     };
 
     const opts = merge(
-      { pollingIntervalMs: 10_000, batchSize: 100, maxAllowedEthClientDriftSeconds: 300 },
+      {
+        pollingIntervalMs: 10_000,
+        batchSize: 100,
+        maxAllowedEthClientDriftSeconds: 300,
+        ethereumAllowNoDebugHosts: false,
+      },
       mapArchiverConfig(config),
     );
 
@@ -243,7 +268,8 @@ export class Archiver extends (EventEmitter as new () => ArchiverEmitter) implem
 
     const archiver = new Archiver(
       publicClient,
-      config.l1Contracts,
+      debugClient,
+      { ...config.l1Contracts, slashingProposerAddress },
       archiverStore,
       opts,
       deps.blobSinkClient,
@@ -272,6 +298,7 @@ export class Archiver extends (EventEmitter as new () => ArchiverEmitter) implem
 
     await this.blobSinkClient.testSources();
     await this.testEthereumNodeSynced();
+    await validateAndLogTraceAvailability(this.debugClient, this.config.ethereumAllowNoDebugHosts ?? false);
 
     // Log initial state for the archiver
     const { l1StartBlock } = this.l1constants;
@@ -832,9 +859,12 @@ export class Archiver extends (EventEmitter as new () => ArchiverEmitter) implem
       const retrievedBlocks = await retrieveBlocksFromRollup(
         this.rollup.getContract() as GetContractReturnType<typeof RollupAbi, ViemPublicClient>,
         this.publicClient,
+        this.debugClient,
         this.blobSinkClient,
         searchStartBlock, // TODO(palla/reorg): If the L2 reorg was due to an L1 reorg, we need to start search earlier
         searchEndBlock,
+        this.l1Addresses,
+        this.instrumentation,
         this.log,
       );
 

package/src/archiver/config.ts

@@ -55,6 +55,11 @@ export const archiverConfigMappings: ConfigMappingsType<ArchiverConfig> = {
     description: 'Maximum allowed drift in seconds between the Ethereum client and current time.',
     ...numberConfigHelper(300),
   },
+  ethereumAllowNoDebugHosts: {
+    env: 'ETHEREUM_ALLOW_NO_DEBUG_HOSTS',
+    description: 'Whether to allow starting the archiver without debug/trace method support on Ethereum hosts',
+    ...booleanConfigHelper(true),
+  },
   ...chainConfigMappings,
   ...l1ReaderConfigMappings,
   viemPollingIntervalMS: {

package/src/archiver/instrumentation.ts

@@ -34,6 +34,8 @@ export class ArchiverInstrumentation {
   private syncDurationPerMessage: Histogram;
   private syncMessageCount: UpDownCounter;
 
+  private blockProposalTxTargetCount: UpDownCounter;
+
   private log = createLogger('archiver:instrumentation');
 
   private constructor(
@@ -114,6 +116,11 @@ export class ArchiverInstrumentation {
       valueType: ValueType.INT,
     });
 
+    this.blockProposalTxTargetCount = meter.createUpDownCounter(Metrics.ARCHIVER_BLOCK_PROPOSAL_TX_TARGET_COUNT, {
+      description: 'Number of block proposals by tx target',
+      valueType: ValueType.INT,
+    });
+
     this.dbMetrics = new LmdbMetrics(
       meter,
       {
@@ -184,4 +191,11 @@ export class ArchiverInstrumentation {
   public updateL1BlockHeight(blockNumber: bigint) {
     this.l1BlockHeight.record(Number(blockNumber));
   }
+
+  public recordBlockProposalTxTarget(target: string, usedTrace: boolean) {
+    this.blockProposalTxTargetCount.add(1, {
+      [Attributes.L1_BLOCK_PROPOSAL_TX_TARGET]: target.toLowerCase(),
+      [Attributes.L1_BLOCK_PROPOSAL_USED_TRACE]: usedTrace,
+    });
+  }
 }

package/src/archiver/l1/README.md

@@ -0,0 +1,98 @@
+# Archiver L1 Data Retrieval
+
+Modules and classes to handle data retrieval from L1 for the archiver.
+
+## Calldata Retriever
+
+The sequencer publisher bundles multiple operations into a single multicall3 transaction for gas
+efficiency. A typical transaction includes:
+
+1. Attestation invalidations (if needed): `invalidateBadAttestation`, `invalidateInsufficientAttestations`
+2. Block proposal: `propose` (exactly one per transaction to the rollup contract)
+3. Governance and slashing (if needed): votes, payload creation/execution
+
+The archiver needs to extract the `propose` calldata from these bundled transactions to reconstruct
+L2 blocks. This class needs to handle scenarios where the transaction was submitted via multicall3,
+as well as alternative ways for submitting the `propose` call that other clients might use.
+
+### Multicall3 Validation and Decoding
+
+First attempt to decode the transaction as a multicall3 `aggregate3` call with validation:
+
+- Check if transaction is to multicall3 address (`0xcA11bde05977b3631167028862bE2a173976CA11`)
+- Decode as `aggregate3(Call3[] calldata calls)`
+- Allow calls to known addresses and methods (rollup, governance, slashing contracts, etc.)
+- Find the single `propose` call to the rollup contract
+- Verify exactly one `propose` call exists
+- Extract and return the propose calldata
+
+This step handles the common case efficiently without requiring expensive trace or debug RPC calls.
+Any validation failure triggers fallback to the next step.
+
+### Direct Propose Call
+
+Second attempt to decode the transaction as a direct `propose` call to the rollup contract:
+
+- Check if transaction is to the rollup address
+- Decode as `propose` function call
+- Verify the function is indeed `propose`
+- Return the transaction input as the propose calldata
+
+This handles scenarios where clients submit transactions directly to the rollup contract without
+using multicall3 for bundling. Any validation failure triggers fallback to the next step.
+
+### Spire Proposer Call
+
+Given existing attempts to route the call via the Spire proposer, we also check if the tx is `to` the 
+proposer known address, and if so, we try decoding it as either a multicall3 or a direct call to the
+rollup contract.
+
+Similar as with the multicall3 check, we check that there are no other calls in the Spire proposer, so
+we are absolutely sure that the only call is the successful one to the rollup. Any extraneous call would
+imply an unexpected path to calling `propose` in the rollup contract, and since we cannot verify if the
+calldata arguments we extracted are the correct ones (see the section below), we cannot know for sure which
+one is the call that succeeded, so we don't know which calldata to process.
+
+Furthermore, since the Spire proposer is upgradeable, we check if the implementation has not changed in
+order to decode. As usual, any validation failure triggers fallback to the next step.
+
+### Verifying Multicall3 Arguments
+
+**This is NOT implemented for simplicity's sake**
+
+If the checks above don't hold, such as when there are multiple calls to `propose`, then we cannot
+reliably extract the `propose` calldata from the multicall3 arguments alone. We can try a best-effort
+where we try all `propose` calls we see and validate them against on-chain data. Note that we can use these
+same strategies if we were to obtain the calldata from another source.
+
+#### TempBlockLog Verification
+
+Read the stored `TempBlockLog` for the L2 block number from L1 and verify it matches our decoded header hash,
+since the `TempBlockLog` stores the hash of the proposed block header, the payload commitment, and the attestations.
+
+However, `TempBlockLog` is only stored temporarily and deleted after proven, so this method only works for recent
+blocks, not for historical data syncing.
+
+#### Archive Verification
+
+Verify that the archive root in the decoded propose is correct with regard to the block header. This requires
+hashing the block header we have retrieved, inserting it into the archive tree, and checking the resulting root
+against the one we got from L1.
+
+However, this requires that the archive keeps a reference to world-state, which is not the case in the current
+system.
+
+#### Emit Commitments in Rollup Contract
+
+Modify rollup contract to emit commitments to the block header in the `L2BlockProposed` event, allowing us to easily
+verify the calldata we obtained vs the emitted event.
+
+However, modifying the rollup contract is out of scope for this change. But we can implement this approach in `v2`.
+
+### Debug and Trace Transaction Fallback
+
+Last, we use L1 node's trace/debug RPC methods to definitively identify the one successful `propose` call within the tx.
+We can then extract the exact calldata that hit the `propose` function in the rollup contract.
+
+This approach requires access to a debug-enabled L1 node, which may be more resource-intensive, so we only
+use it as a fallback when the first step fails, which should be rare in practice.