@aztec/archiver 0.0.1-commit.9593d84 → 0.0.1-commit.96bb3f7

package/src/archiver/{data_retrieval.ts → l1/data_retrieval.ts}

@@ -1,3 +1,4 @@
+import type { BlobClientInterface } from '@aztec/blob-client/client';
 import {
   BlobDeserializationError,
   type CheckpointBlobData,
@@ -5,23 +6,17 @@ import {
   decodeCheckpointBlobDataFromBlobs,
   encodeBlockBlobData,
 } from '@aztec/blob-lib';
-import type { BlobSinkClientInterface } from '@aztec/blob-sink/client';
-import type {
-  EpochProofPublicInputArgs,
-  ViemClient,
-  ViemCommitteeAttestations,
-  ViemHeader,
-  ViemPublicClient,
-} from '@aztec/ethereum';
+import type { EpochProofPublicInputArgs } from '@aztec/ethereum/contracts';
+import type { ViemClient, ViemPublicClient, ViemPublicDebugClient } from '@aztec/ethereum/types';
 import { asyncPool } from '@aztec/foundation/async-pool';
+import { CheckpointNumber } from '@aztec/foundation/branded-types';
 import { Buffer16, Buffer32 } from '@aztec/foundation/buffer';
-import type { EthAddress } from '@aztec/foundation/eth-address';
-import type { ViemSignature } from '@aztec/foundation/eth-signature';
-import { Fr } from '@aztec/foundation/fields';
+import { Fr } from '@aztec/foundation/curves/bn254';
+import { EthAddress } from '@aztec/foundation/eth-address';
 import { type Logger, createLogger } from '@aztec/foundation/log';
 import { type InboxAbi, RollupAbi } from '@aztec/l1-artifacts';
 import { Body, CommitteeAttestation, L2BlockNew } from '@aztec/stdlib/block';
-import { Checkpoint, PublishedCheckpoint } from '@aztec/stdlib/checkpoint';
+import { Checkpoint, L1PublishedData, PublishedCheckpoint } from '@aztec/stdlib/checkpoint';
 import { Proof } from '@aztec/stdlib/proofs';
 import { CheckpointHeader } from '@aztec/stdlib/rollup';
 import { AppendOnlyTreeSnapshot } from '@aztec/stdlib/trees';
@@ -34,16 +29,16 @@ import {
   decodeFunctionData,
   getAbiItem,
   hexToBytes,
-  multicall3Abi,
 } from 'viem';
 
-import { NoBlobBodiesFoundError } from './errors.js';
-import type { DataRetrieval } from './structs/data_retrieval.js';
-import type { InboxMessage } from './structs/inbox_message.js';
-import type { L1PublishedData } from './structs/published.js';
+import { NoBlobBodiesFoundError } from '../errors.js';
+import type { ArchiverInstrumentation } from '../instrumentation.js';
+import type { DataRetrieval } from '../structs/data_retrieval.js';
+import type { InboxMessage } from '../structs/inbox_message.js';
+import { CalldataRetriever } from './calldata_retriever.js';
 
 export type RetrievedCheckpoint = {
-  checkpointNumber: number;
+  checkpointNumber: CheckpointNumber;
   archiveRoot: Fr;
   header: CheckpointHeader;
   checkpointBlobData: CheckpointBlobData;
@@ -71,8 +66,8 @@ export async function retrievedToPublishedCheckpoint({
     .slice(1)
     .concat([archiveRoot]);
 
-  // `blocksBlobData` is created from `decodeCheckpointBlobDataFromBlobs`. An error will be thrown if it can't read a
-  // field for the `l1ToL2MessageRoot` of the first block. So below we can safely assume it exists:
+  // An error will be thrown from `decodeCheckpointBlobDataFromBlobs` if it can't read a field for the
+  // `l1ToL2MessageRoot` of the first block. So below we can safely assume it exists:
   const l1toL2MessageTreeRoot = blocksBlobData[0].l1ToL2MessageRoot!;
 
   const spongeBlob = SpongeBlob.init();
@@ -126,7 +121,7 @@ export async function retrievedToPublishedCheckpoint({
 
     const newArchive = new AppendOnlyTreeSnapshot(newArchiveRoots[i], l2BlockNumber + 1);
 
-    l2Blocks.push(new L2BlockNew(newArchive, header, body));
+    l2Blocks.push(new L2BlockNew(newArchive, header, body, checkpointNumber, i));
   }
 
   const lastBlock = l2Blocks.at(-1)!;
@@ -142,20 +137,33 @@ export async function retrievedToPublishedCheckpoint({
 
 /**
  * Fetches new checkpoints.
+ * @param rollup - The rollup contract instance.
  * @param publicClient - The viem public client to use for transaction retrieval.
- * @param rollupAddress - The address of the rollup contract.
+ * @param debugClient - The viem debug client to use for trace/debug RPC methods (optional).
+ * @param blobClient - The blob client client for fetching blob data.
  * @param searchStartBlock - The block number to use for starting the search.
  * @param searchEndBlock - The highest block number that we should search up to.
- * @param expectedNextL2BlockNum - The next L2 block number that we expect to find.
- * @returns An array of block; as well as the next eth block to search from.
+ * @param contractAddresses - The contract addresses (governanceProposerAddress, slashFactoryAddress, slashingProposerAddress).
+ * @param instrumentation - The archiver instrumentation instance.
+ * @param logger - The logger instance.
+ * @param isHistoricalSync - Whether this is a historical sync.
+ * @returns An array of retrieved checkpoints.
  */
 export async function retrieveCheckpointsFromRollup(
   rollup: GetContractReturnType<typeof RollupAbi, ViemPublicClient>,
   publicClient: ViemPublicClient,
-  blobSinkClient: BlobSinkClientInterface,
+  debugClient: ViemPublicDebugClient,
+  blobClient: BlobClientInterface,
   searchStartBlock: bigint,
   searchEndBlock: bigint,
+  contractAddresses: {
+    governanceProposerAddress: EthAddress;
+    slashFactoryAddress?: EthAddress;
+    slashingProposerAddress: EthAddress;
+  },
+  instrumentation: ArchiverInstrumentation,
   logger: Logger = createLogger('archiver'),
+  isHistoricalSync: boolean = false,
 ): Promise<RetrievedCheckpoint[]> {
   const retrievedCheckpoints: RetrievedCheckpoint[] = [];
 
@@ -200,10 +208,14 @@ export async function retrieveCheckpointsFromRollup(
     const newCheckpoints = await processCheckpointProposedLogs(
       rollup,
       publicClient,
-      blobSinkClient,
+      debugClient,
+      blobClient,
       checkpointProposedLogs,
       rollupConstants,
+      contractAddresses,
+      instrumentation,
       logger,
+      isHistoricalSync,
     );
     retrievedCheckpoints.push(...newCheckpoints);
     searchStartBlock = lastLog.blockNumber! + 1n;
@@ -215,46 +227,80 @@ export async function retrieveCheckpointsFromRollup(
 
 /**
  * Processes newly received CheckpointProposed logs.
- * @param rollup - The rollup contract
+ * @param rollup - The rollup contract instance.
  * @param publicClient - The viem public client to use for transaction retrieval.
+ * @param debugClient - The viem debug client to use for trace/debug RPC methods (optional).
+ * @param blobClient - The blob client client for fetching blob data.
  * @param logs - CheckpointProposed logs.
- * @returns - An array of checkpoints.
+ * @param rollupConstants - The rollup constants (chainId, version, targetCommitteeSize).
+ * @param contractAddresses - The contract addresses (governanceProposerAddress, slashFactoryAddress, slashingProposerAddress).
+ * @param instrumentation - The archiver instrumentation instance.
+ * @param logger - The logger instance.
+ * @param isHistoricalSync - Whether this is a historical sync.
+ * @returns An array of retrieved checkpoints.
  */
 async function processCheckpointProposedLogs(
   rollup: GetContractReturnType<typeof RollupAbi, ViemPublicClient>,
   publicClient: ViemPublicClient,
-  blobSinkClient: BlobSinkClientInterface,
+  debugClient: ViemPublicDebugClient,
+  blobClient: BlobClientInterface,
   logs: GetContractEventsReturnType<typeof RollupAbi, 'CheckpointProposed'>,
   { chainId, version, targetCommitteeSize }: { chainId: Fr; version: Fr; targetCommitteeSize: number },
+  contractAddresses: {
+    governanceProposerAddress: EthAddress;
+    slashFactoryAddress?: EthAddress;
+    slashingProposerAddress: EthAddress;
+  },
+  instrumentation: ArchiverInstrumentation,
   logger: Logger,
+  isHistoricalSync: boolean,
 ): Promise<RetrievedCheckpoint[]> {
   const retrievedCheckpoints: RetrievedCheckpoint[] = [];
+  const calldataRetriever = new CalldataRetriever(
+    publicClient,
+    debugClient,
+    targetCommitteeSize,
+    instrumentation,
+    logger,
+    { ...contractAddresses, rollupAddress: EthAddress.fromString(rollup.address) },
+  );
+
   await asyncPool(10, logs, async log => {
-    const checkpointNumber = Number(log.args.checkpointNumber!);
+    const checkpointNumber = CheckpointNumber.fromBigInt(log.args.checkpointNumber!);
     const archive = log.args.archive!;
     const archiveFromChain = await rollup.read.archiveAt([BigInt(checkpointNumber)]);
     const blobHashes = log.args.versionedBlobHashes!.map(blobHash => Buffer.from(blobHash.slice(2), 'hex'));
 
     // The value from the event and contract will match only if the checkpoint is in the chain.
     if (archive === archiveFromChain) {
-      const checkpoint = await getCheckpointFromRollupTx(
-        publicClient,
-        blobSinkClient,
+      // Build expected hashes object (fields may be undefined for backwards compatibility with older events)
+      const expectedHashes = {
+        attestationsHash: log.args.attestationsHash,
+        payloadDigest: log.args.payloadDigest,
+      };
+
+      const checkpoint = await calldataRetriever.getCheckpointFromRollupTx(
         log.transactionHash!,
         blobHashes,
         checkpointNumber,
-        rollup.address,
-        targetCommitteeSize,
+        expectedHashes,
+      );
+      const checkpointBlobData = await getCheckpointBlobDataFromBlobs(
+        blobClient,
+        checkpoint.blockHash,
+        blobHashes,
+        checkpointNumber,
         logger,
+        isHistoricalSync,
       );
 
-      const l1: L1PublishedData = {
-        blockNumber: log.blockNumber,
-        blockHash: log.blockHash,
-        timestamp: await getL1BlockTime(publicClient, log.blockNumber),
-      };
+      const l1 = new L1PublishedData(
+        log.blockNumber,
+        await getL1BlockTime(publicClient, log.blockNumber),
+        log.blockHash,
+      );
 
-      retrievedCheckpoints.push({ ...checkpoint, l1, chainId, version });
+      retrievedCheckpoints.push({ ...checkpoint, checkpointBlobData, l1, chainId, version });
       logger.trace(`Retrieved checkpoint ${checkpointNumber} from L1 tx ${log.transactionHash}`, {
         l1BlockNumber: log.blockNumber,
         checkpointNumber,
@@ -277,118 +323,15 @@ export async function getL1BlockTime(publicClient: ViemPublicClient, blockNumber
   return block.timestamp;
 }
 
-/**
- * Extracts the first 'propose' method calldata from a multicall3 transaction's data.
- * @param multicall3Data - The multicall3 transaction input data
- * @param rollupAddress - The address of the rollup contract
- * @returns The calldata for the first 'propose' method call to the rollup contract
- */
-function extractRollupProposeCalldata(multicall3Data: Hex, rollupAddress: Hex): Hex {
-  const { functionName: multicall3FunctionName, args: multicall3Args } = decodeFunctionData({
-    abi: multicall3Abi,
-    data: multicall3Data,
-  });
-
-  if (multicall3FunctionName !== 'aggregate3') {
-    throw new Error(`Unexpected multicall3 method called ${multicall3FunctionName}`);
-  }
-
-  if (multicall3Args.length !== 1) {
-    throw new Error(`Unexpected number of arguments for multicall3`);
-  }
-
-  const [calls] = multicall3Args;
-
-  // Find all rollup calls
-  const rollupAddressLower = rollupAddress.toLowerCase();
-
-  for (let i = 0; i < calls.length; i++) {
-    const addr = calls[i].target;
-    if (addr.toLowerCase() !== rollupAddressLower) {
-      continue;
-    }
-    const callData = calls[i].callData;
-
-    try {
-      const { functionName: rollupFunctionName } = decodeFunctionData({
-        abi: RollupAbi,
-        data: callData,
-      });
-
-      if (rollupFunctionName === 'propose') {
-        return callData;
-      }
-    } catch {
-      // Skip invalid function data
-      continue;
-    }
-  }
-
-  throw new Error(`Rollup address not found in multicall3 args`);
-}
-
-/**
- * Gets checkpoint from the calldata of an L1 transaction.
- * Assumes that the checkpoint was published from an EOA.
- * TODO: Add retries and error management.
- * @param publicClient - The viem public client to use for transaction retrieval.
- * @param txHash - Hash of the tx that published it.
- * @param checkpointNumber - Checkpoint number.
- * @returns Checkpoint from the calldata, deserialized
- */
-async function getCheckpointFromRollupTx(
-  publicClient: ViemPublicClient,
-  blobSinkClient: BlobSinkClientInterface,
-  txHash: `0x${string}`,
-  blobHashes: Buffer[], // TODO(md): buffer32?
-  checkpointNumber: number,
-  rollupAddress: Hex,
-  targetCommitteeSize: number,
+export async function getCheckpointBlobDataFromBlobs(
+  blobClient: BlobClientInterface,
+  blockHash: string,
+  blobHashes: Buffer<ArrayBufferLike>[],
+  checkpointNumber: CheckpointNumber,
   logger: Logger,
-): Promise<Omit<RetrievedCheckpoint, 'l1' | 'chainId' | 'version'>> {
-  logger.trace(`Fetching checkpoint ${checkpointNumber} from rollup tx ${txHash}`);
-  const { input: forwarderData, blockHash } = await publicClient.getTransaction({ hash: txHash });
-
-  const rollupData = extractRollupProposeCalldata(forwarderData, rollupAddress);
-  const { functionName: rollupFunctionName, args: rollupArgs } = decodeFunctionData({
-    abi: RollupAbi,
-    data: rollupData,
-  });
-
-  if (rollupFunctionName !== 'propose') {
-    throw new Error(`Unexpected rollup method called ${rollupFunctionName}`);
-  }
-
-  const [decodedArgs, packedAttestations, _signers, _blobInput] = rollupArgs! as readonly [
-    {
-      archive: Hex;
-      oracleInput: {
-        feeAssetPriceModifier: bigint;
-      };
-      header: ViemHeader;
-      txHashes: readonly Hex[];
-    },
-    ViemCommitteeAttestations,
-    Hex[],
-    ViemSignature,
-    Hex,
-  ];
-
-  const attestations = CommitteeAttestation.fromPacked(packedAttestations, targetCommitteeSize);
-
-  logger.trace(`Recovered propose calldata from tx ${txHash}`, {
-    checkpointNumber,
-    archive: decodedArgs.archive,
-    header: decodedArgs.header,
-    l1BlockHash: blockHash,
-    blobHashes,
-    attestations,
-    packedAttestations,
-    targetCommitteeSize,
-  });
-
-  const header = CheckpointHeader.fromViem(decodedArgs.header);
-  const blobBodies = await blobSinkClient.getBlobSidecar(blockHash, blobHashes);
+  isHistoricalSync: boolean,
+): Promise<CheckpointBlobData> {
+  const blobBodies = await blobClient.getBlobSidecar(blockHash, blobHashes, { isHistoricalSync });
   if (blobBodies.length === 0) {
     throw new NoBlobBodiesFoundError(checkpointNumber);
   }
@@ -396,25 +339,18 @@ async function getCheckpointFromRollupTx(
   let checkpointBlobData: CheckpointBlobData;
   try {
     // Attempt to decode the checkpoint blob data.
-    checkpointBlobData = decodeCheckpointBlobDataFromBlobs(blobBodies.map(b => b.blob));
+    checkpointBlobData = decodeCheckpointBlobDataFromBlobs(blobBodies);
   } catch (err: any) {
     if (err instanceof BlobDeserializationError) {
       logger.fatal(err.message);
     } else {
       logger.fatal('Unable to sync: failed to decode fetched blob, this blob was likely not created by us');
     }
+    // Throwing an error since this is most likely caused by a bug.
     throw err;
   }
 
-  const archiveRoot = new Fr(Buffer.from(hexToBytes(decodedArgs.archive)));
-
-  return {
-    checkpointNumber,
-    archiveRoot,
-    header,
-    checkpointBlobData,
-    attestations,
-  };
+  return checkpointBlobData;
 }
 
 /** Given an L1 to L2 message, retrieves its corresponding event from the Inbox within a specific block range. */
@@ -469,7 +405,7 @@ function mapLogsInboxMessage(logs: GetContractEventsReturnType<typeof InboxAbi,
       leaf: Fr.fromHexString(hash!),
       l1BlockNumber: log.blockNumber,
       l1BlockHash: Buffer32.fromString(log.blockHash),
-      l2BlockNumber: Number(checkpointNumber!),
+      checkpointNumber: CheckpointNumber.fromBigInt(checkpointNumber!),
       rollingHash: Buffer16.fromString(rollingHash!),
     };
   });
@@ -481,7 +417,7 @@ export async function retrieveL2ProofVerifiedEvents(
   rollupAddress: EthAddress,
   searchStartBlock: bigint,
   searchEndBlock?: bigint,
-): Promise<{ l1BlockNumber: bigint; checkpointNumber: number; proverId: Fr; txHash: Hex }[]> {
+): Promise<{ l1BlockNumber: bigint; checkpointNumber: CheckpointNumber; proverId: Fr; txHash: Hex }[]> {
   const logs = await publicClient.getLogs({
     address: rollupAddress.toString(),
     fromBlock: searchStartBlock,
@@ -492,7 +428,7 @@ export async function retrieveL2ProofVerifiedEvents(
 
   return logs.map(log => ({
     l1BlockNumber: log.blockNumber,
-    checkpointNumber: Number(log.args.checkpointNumber),
+    checkpointNumber: CheckpointNumber.fromBigInt(log.args.checkpointNumber),
     proverId: Fr.fromHexString(log.args.proverId),
     txHash: log.transactionHash,
   }));

package/src/archiver/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/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;
+  }
+}