@aztec/archiver 3.0.0-nightly.20251210 → 3.0.0-nightly.20251211

package/src/archiver/config.ts

@@ -1,11 +1,7 @@
 import { type BlobSinkConfig, blobSinkConfigMapping } from '@aztec/blob-sink/client';
-import {
-  type L1ContractsConfig,
-  type L1ReaderConfig,
-  l1ContractAddressesMapping,
-  l1ContractsConfigMappings,
-  l1ReaderConfigMappings,
-} from '@aztec/ethereum';
+import { type L1ContractsConfig, l1ContractsConfigMappings } from '@aztec/ethereum/config';
+import { l1ContractAddressesMapping } from '@aztec/ethereum/l1-contract-addresses';
+import { type L1ReaderConfig, l1ReaderConfigMappings } from '@aztec/ethereum/l1-reader';
 import {
   type ConfigMappingsType,
   booleanConfigHelper,
@@ -55,6 +51,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/kv_archiver_store/kv_archiver_store.ts

@@ -1,5 +1,5 @@
-import type { L1BlockId } from '@aztec/ethereum';
-import { BlockNumber, CheckpointNumber } from '@aztec/foundation/branded-types';
+import type { L1BlockId } from '@aztec/ethereum/l1-types';
+import type { BlockNumber, CheckpointNumber } from '@aztec/foundation/branded-types';
 import type { Fr } from '@aztec/foundation/curves/bn254';
 import { toArray } from '@aztec/foundation/iterable';
 import { createLogger } from '@aztec/foundation/log';

package/src/archiver/kv_archiver_store/message_store.ts

@@ -1,4 +1,4 @@
-import type { L1BlockId } from '@aztec/ethereum';
+import type { L1BlockId } from '@aztec/ethereum/l1-types';
 import { CheckpointNumber } from '@aztec/foundation/branded-types';
 import { Buffer16, Buffer32 } from '@aztec/foundation/buffer';
 import { Fr } from '@aztec/foundation/curves/bn254';

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.

package/src/archiver/l1/bin/retrieve-calldata.ts

@@ -0,0 +1,182 @@
+#!/usr/bin/env node
+import type { ViemPublicClient, ViemPublicDebugClient } from '@aztec/ethereum/types';
+import { CheckpointNumber } from '@aztec/foundation/branded-types';
+import { EthAddress } from '@aztec/foundation/eth-address';
+import { createLogger } from '@aztec/foundation/log';
+
+import { type Hex, createPublicClient, http } from 'viem';
+import { mainnet } from 'viem/chains';
+
+import { CalldataRetriever } from '../calldata_retriever.js';
+
+const logger = createLogger('archiver:calldata-test');
+
+interface ScriptArgs {
+  rollupAddress: EthAddress;
+  txHash: Hex;
+  rpcUrl: string;
+  targetCommitteeSize: number;
+}
+
+function parseArgs(): ScriptArgs {
+  const args = process.argv.slice(2);
+
+  if (args.length < 2) {
+    // eslint-disable-next-line no-console
+    console.error('Usage: node index.js <rollup-address> <tx-hash> [target-committee-size]');
+    // eslint-disable-next-line no-console
+    console.error('');
+    // eslint-disable-next-line no-console
+    console.error('Environment variables:');
+    // eslint-disable-next-line no-console
+    console.error('  ETHEREUM_HOST or RPC_URL - Ethereum RPC endpoint');
+    // eslint-disable-next-line no-console
+    console.error('');
+    // eslint-disable-next-line no-console
+    console.error('Example:');
+    // eslint-disable-next-line no-console
+    console.error('  RPC_URL=https://eth-mainnet.g.alchemy.com/v2/YOUR-API-KEY \\');
+    // eslint-disable-next-line no-console
+    console.error('  node index.js 0x1234... 0xabcd... 32');
+    process.exit(1);
+  }
+
+  const rollupAddress = EthAddress.fromString(args[0]);
+  const txHash = args[1] as Hex;
+  const targetCommitteeSize = args[2] ? parseInt(args[2], 10) : 24;
+
+  const rpcUrl = process.env.ETHEREUM_HOST || process.env.RPC_URL;
+  if (!rpcUrl) {
+    // eslint-disable-next-line no-console
+    console.error('Error: ETHEREUM_HOST or RPC_URL environment variable must be set');
+    process.exit(1);
+  }
+
+  if (targetCommitteeSize <= 0 || targetCommitteeSize > 256) {
+    // eslint-disable-next-line no-console
+    console.error('Error: target-committee-size must be between 1 and 256');
+    process.exit(1);
+  }
+
+  return { rollupAddress, txHash, rpcUrl, targetCommitteeSize };
+}
+
+async function main() {
+  const { rollupAddress, txHash, rpcUrl, targetCommitteeSize } = parseArgs();
+
+  logger.info('Calldata Retriever Test Script');
+  logger.info('===============================');
+  logger.info(`Rollup Address: ${rollupAddress.toString()}`);
+  logger.info(`Transaction Hash: ${txHash}`);
+  logger.info(`RPC URL: ${rpcUrl}`);
+  logger.info(`Target Committee Size: ${targetCommitteeSize}`);
+  logger.info('');
+
+  try {
+    // Create viem public client
+    const publicClient = createPublicClient({
+      chain: mainnet,
+      transport: http(rpcUrl),
+    });
+
+    logger.info('Fetching transaction...');
+    const tx = await publicClient.getTransaction({ hash: txHash });
+
+    if (!tx) {
+      throw new Error(`Transaction ${txHash} not found`);
+    }
+
+    logger.info(`Transaction found in block ${tx.blockNumber}`);
+
+    // For simplicity, use zero addresses for optional contract addresses
+    // In production, these would be fetched from the rollup contract or configuration
+    const slashingProposerAddress = EthAddress.ZERO;
+    const governanceProposerAddress = EthAddress.ZERO;
+    const slashFactoryAddress = undefined;
+
+    logger.info('Using zero addresses for governance/slashing (can be configured if needed)');
+
+    // Create CalldataRetriever
+    const retriever = new CalldataRetriever(
+      publicClient as unknown as ViemPublicClient,
+      publicClient as unknown as ViemPublicDebugClient,
+      targetCommitteeSize,
+      undefined,
+      logger,
+      {
+        rollupAddress,
+        governanceProposerAddress,
+        slashingProposerAddress,
+        slashFactoryAddress,
+      },
+    );
+
+    // Extract L2 block number from transaction logs
+    logger.info('Decoding transaction to extract L2 block number...');
+    const receipt = await publicClient.getTransactionReceipt({ hash: txHash });
+    const l2BlockProposedEvent = receipt.logs.find(log => {
+      try {
+        // Try to match the L2BlockProposed event
+        return (
+          log.address.toLowerCase() === rollupAddress.toString().toLowerCase() &&
+          log.topics[0] === '0x2f1d0e696fa5186494a2f2f89a0e0bcbb15d607f6c5eac4637e07e1e5e7d3c00' // L2BlockProposed event signature
+        );
+      } catch {
+        return false;
+      }
+    });
+
+    let l2BlockNumber: number;
+    if (l2BlockProposedEvent && l2BlockProposedEvent.topics[1]) {
+      // L2 block number is typically the first indexed parameter
+      l2BlockNumber = Number(BigInt(l2BlockProposedEvent.topics[1]));
+      logger.info(`L2 Block Number (from event): ${l2BlockNumber}`);
+    } else {
+      // Fallback: try to extract from transaction data or use a default
+      logger.warn('Could not extract L2 block number from event, using block number as fallback');
+      l2BlockNumber = Number(tx.blockNumber);
+    }
+
+    logger.info('');
+    logger.info('Retrieving block header from rollup transaction...');
+    logger.info('');
+
+    // For this script, we don't have blob hashes, so pass empty array
+    const result = await retriever.getCheckpointFromRollupTx(txHash, [], CheckpointNumber(l2BlockNumber));
+
+    logger.info(' Successfully retrieved block header!');
+    logger.info('');
+    logger.info('Block Header Details:');
+    logger.info('====================');
+    logger.info(`Checkpoint Number: ${result.checkpointNumber}`);
+    logger.info(`Block Hash: ${result.blockHash}`);
+    logger.info(`Archive Root: ${result.archiveRoot.toString()}`);
+    logger.info('');
+    logger.info('Header:');
+    logger.info(`  Slot Number: ${result.header.slotNumber.toString()}`);
+    logger.info(`  Timestamp: ${result.header.timestamp.toString()}`);
+    logger.info(`  Coinbase: ${result.header.coinbase.toString()}`);
+    logger.info(`  Fee Recipient: ${result.header.feeRecipient.toString()}`);
+    logger.info(`  Total Mana Used: ${result.header.totalManaUsed.toString()}`);
+    logger.info('');
+    logger.info('Attestations:');
+    logger.info(`  Count: ${result.attestations.length}`);
+    logger.info(`  Non-empty attestations: ${result.attestations.filter((a: any) => !a.signature.isEmpty()).length}`);
+
+    process.exit(0);
+  } catch (error) {
+    logger.error('Error retrieving block header:');
+    logger.error(error instanceof Error ? error.message : String(error));
+
+    if (error instanceof Error && error.stack) {
+      logger.debug(error.stack);
+    }
+
+    process.exit(1);
+  }
+}
+
+// Only run if this is the main module
+if (import.meta.url === `file://${process.argv[1]}`) {
+  void main();
+}