@aztec/archiver 0.0.1-commit.b655e406 → 0.0.1-commit.c0b82b2

package/dest/l1/data_retrieval.js

@@ -0,0 +1,314 @@
+import { BlobDeserializationError, SpongeBlob, decodeCheckpointBlobDataFromBlobs, encodeBlockBlobData } from '@aztec/blob-lib';
+import { asyncPool } from '@aztec/foundation/async-pool';
+import { CheckpointNumber, IndexWithinCheckpoint } from '@aztec/foundation/branded-types';
+import { Fr } from '@aztec/foundation/curves/bn254';
+import { EthAddress } from '@aztec/foundation/eth-address';
+import { createLogger } from '@aztec/foundation/log';
+import { RollupAbi } from '@aztec/l1-artifacts';
+import { Body, L2Block } from '@aztec/stdlib/block';
+import { Checkpoint, L1PublishedData, PublishedCheckpoint } from '@aztec/stdlib/checkpoint';
+import { Proof } from '@aztec/stdlib/proofs';
+import { AppendOnlyTreeSnapshot } from '@aztec/stdlib/trees';
+import { BlockHeader, GlobalVariables, PartialStateReference, StateReference } from '@aztec/stdlib/tx';
+import { decodeFunctionData, getAbiItem, hexToBytes } from 'viem';
+import { NoBlobBodiesFoundError } from '../errors.js';
+import { CalldataRetriever } from './calldata_retriever.js';
+export async function retrievedToPublishedCheckpoint({ checkpointNumber, archiveRoot, feeAssetPriceModifier, header: checkpointHeader, checkpointBlobData, l1, chainId, version, attestations }) {
+    const { blocks: blocksBlobData } = checkpointBlobData;
+    // The lastArchiveRoot of a block is the new archive for the previous block.
+    const newArchiveRoots = blocksBlobData.map((b)=>b.lastArchiveRoot).slice(1).concat([
+        archiveRoot
+    ]);
+    // 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();
+    const l2Blocks = [];
+    for(let i = 0; i < blocksBlobData.length; i++){
+        const blockBlobData = blocksBlobData[i];
+        const { blockEndMarker, blockEndStateField, lastArchiveRoot, noteHashRoot, nullifierRoot, publicDataRoot } = blockBlobData;
+        const l2BlockNumber = blockEndMarker.blockNumber;
+        const globalVariables = GlobalVariables.from({
+            chainId,
+            version,
+            blockNumber: l2BlockNumber,
+            slotNumber: checkpointHeader.slotNumber,
+            timestamp: blockEndMarker.timestamp,
+            coinbase: checkpointHeader.coinbase,
+            feeRecipient: checkpointHeader.feeRecipient,
+            gasFees: checkpointHeader.gasFees
+        });
+        const state = StateReference.from({
+            l1ToL2MessageTree: new AppendOnlyTreeSnapshot(l1toL2MessageTreeRoot, blockEndStateField.l1ToL2MessageNextAvailableLeafIndex),
+            partial: PartialStateReference.from({
+                noteHashTree: new AppendOnlyTreeSnapshot(noteHashRoot, blockEndStateField.noteHashNextAvailableLeafIndex),
+                nullifierTree: new AppendOnlyTreeSnapshot(nullifierRoot, blockEndStateField.nullifierNextAvailableLeafIndex),
+                publicDataTree: new AppendOnlyTreeSnapshot(publicDataRoot, blockEndStateField.publicDataNextAvailableLeafIndex)
+            })
+        });
+        const body = Body.fromTxBlobData(blockBlobData.txs);
+        const blobFields = encodeBlockBlobData(blockBlobData);
+        await spongeBlob.absorb(blobFields);
+        const clonedSpongeBlob = spongeBlob.clone();
+        const spongeBlobHash = await clonedSpongeBlob.squeeze();
+        const header = BlockHeader.from({
+            lastArchive: new AppendOnlyTreeSnapshot(lastArchiveRoot, l2BlockNumber),
+            state,
+            spongeBlobHash,
+            globalVariables,
+            totalFees: body.txEffects.reduce((accum, txEffect)=>accum.add(txEffect.transactionFee), Fr.ZERO),
+            totalManaUsed: new Fr(blockEndStateField.totalManaUsed)
+        });
+        const newArchive = new AppendOnlyTreeSnapshot(newArchiveRoots[i], l2BlockNumber + 1);
+        l2Blocks.push(new L2Block(newArchive, header, body, checkpointNumber, IndexWithinCheckpoint(i)));
+    }
+    const lastBlock = l2Blocks.at(-1);
+    const checkpoint = Checkpoint.from({
+        archive: new AppendOnlyTreeSnapshot(archiveRoot, lastBlock.number + 1),
+        header: checkpointHeader,
+        blocks: l2Blocks,
+        number: checkpointNumber,
+        feeAssetPriceModifier: feeAssetPriceModifier
+    });
+    return PublishedCheckpoint.from({
+        checkpoint,
+        l1,
+        attestations
+    });
+}
+/**
+ * Fetches new checkpoints.
+ * @param rollup - The rollup contract wrapper.
+ * @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 searchStartBlock - The block number to use for starting the search.
+ * @param searchEndBlock - The highest block number that we should search up to.
+ * @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, publicClient, debugClient, blobClient, searchStartBlock, searchEndBlock, instrumentation, logger = createLogger('archiver'), isHistoricalSync = false) {
+    const retrievedCheckpoints = [];
+    let rollupConstants;
+    do {
+        if (searchStartBlock > searchEndBlock) {
+            break;
+        }
+        const checkpointProposedLogs = await rollup.getCheckpointProposedEvents(searchStartBlock, searchEndBlock);
+        if (checkpointProposedLogs.length === 0) {
+            break;
+        }
+        const lastLog = checkpointProposedLogs.at(-1);
+        logger.debug(`Got ${checkpointProposedLogs.length} processed logs for checkpoints ${checkpointProposedLogs[0].args.checkpointNumber}-${lastLog.args.checkpointNumber} between L1 blocks ${searchStartBlock}-${searchEndBlock}`);
+        if (rollupConstants === undefined) {
+            const [chainId, version, targetCommitteeSize] = await Promise.all([
+                publicClient.getChainId(),
+                rollup.getVersion(),
+                rollup.getTargetCommitteeSize()
+            ]);
+            rollupConstants = {
+                chainId: new Fr(chainId),
+                version: new Fr(version),
+                targetCommitteeSize
+            };
+        }
+        const newCheckpoints = await processCheckpointProposedLogs(rollup, publicClient, debugClient, blobClient, checkpointProposedLogs, rollupConstants, instrumentation, logger, isHistoricalSync);
+        retrievedCheckpoints.push(...newCheckpoints);
+        searchStartBlock = lastLog.l1BlockNumber + 1n;
+    }while (searchStartBlock <= searchEndBlock)
+    // The asyncPool from processCheckpointProposedLogs will not necessarily return the checkpoints in order, so we sort them before returning.
+    return retrievedCheckpoints.sort((a, b)=>Number(a.l1.blockNumber - b.l1.blockNumber));
+}
+/**
+ * Processes newly received CheckpointProposed logs.
+ * @param rollup - The rollup contract wrapper.
+ * @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.
+ * @param rollupConstants - The rollup constants (chainId, version, targetCommitteeSize).
+ * @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, publicClient, debugClient, blobClient, logs, { chainId, version, targetCommitteeSize }, instrumentation, logger, isHistoricalSync) {
+    const retrievedCheckpoints = [];
+    const calldataRetriever = new CalldataRetriever(publicClient, debugClient, targetCommitteeSize, instrumentation, logger, EthAddress.fromString(rollup.address));
+    await asyncPool(10, logs, async (log)=>{
+        const checkpointNumber = log.args.checkpointNumber;
+        const archive = log.args.archive;
+        const archiveFromChain = await rollup.archiveAt(checkpointNumber);
+        const blobHashes = log.args.versionedBlobHashes;
+        // The value from the event and contract will match only if the checkpoint is in the chain.
+        if (archive.equals(archiveFromChain)) {
+            const expectedHashes = {
+                attestationsHash: log.args.attestationsHash.toString(),
+                payloadDigest: log.args.payloadDigest.toString()
+            };
+            const checkpoint = await calldataRetriever.getCheckpointFromRollupTx(log.l1TransactionHash, blobHashes, checkpointNumber, expectedHashes);
+            const { timestamp, parentBeaconBlockRoot } = await getL1Block(publicClient, log.l1BlockNumber);
+            const l1 = new L1PublishedData(log.l1BlockNumber, timestamp, log.l1BlockHash.toString());
+            const checkpointBlobData = await getCheckpointBlobDataFromBlobs(blobClient, checkpoint.blockHash, blobHashes, checkpointNumber, logger, isHistoricalSync, parentBeaconBlockRoot, timestamp);
+            retrievedCheckpoints.push({
+                ...checkpoint,
+                checkpointBlobData,
+                l1,
+                chainId,
+                version
+            });
+            logger.trace(`Retrieved checkpoint ${checkpointNumber} from L1 tx ${log.l1TransactionHash}`, {
+                l1BlockNumber: log.l1BlockNumber,
+                checkpointNumber,
+                archive: archive.toString(),
+                attestations: checkpoint.attestations
+            });
+        } else {
+            logger.warn(`Ignoring checkpoint ${checkpointNumber} due to archive root mismatch`, {
+                actual: archive.toString(),
+                expected: archiveFromChain.toString()
+            });
+        }
+    });
+    return retrievedCheckpoints;
+}
+export async function getL1Block(publicClient, blockNumber) {
+    const block = await publicClient.getBlock({
+        blockNumber,
+        includeTransactions: false
+    });
+    return {
+        timestamp: block.timestamp,
+        parentBeaconBlockRoot: block.parentBeaconBlockRoot
+    };
+}
+export async function getCheckpointBlobDataFromBlobs(blobClient, blockHash, blobHashes, checkpointNumber, logger, isHistoricalSync, parentBeaconBlockRoot, l1BlockTimestamp) {
+    const blobBodies = await blobClient.getBlobSidecar(blockHash, blobHashes, {
+        isHistoricalSync,
+        parentBeaconBlockRoot,
+        l1BlockTimestamp
+    });
+    if (blobBodies.length === 0) {
+        throw new NoBlobBodiesFoundError(checkpointNumber);
+    }
+    let checkpointBlobData;
+    try {
+        // Attempt to decode the checkpoint blob data.
+        checkpointBlobData = decodeCheckpointBlobDataFromBlobs(blobBodies);
+    } catch (err) {
+        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;
+    }
+    return checkpointBlobData;
+}
+/** Given an L1 to L2 message, retrieves its corresponding event from the Inbox within a specific block range. */ export async function retrieveL1ToL2Message(inbox, leaf, fromBlock, toBlock) {
+    const logs = await inbox.getMessageSentEventByHash(leaf.toString(), fromBlock, toBlock);
+    const messages = mapLogsInboxMessage(logs);
+    return messages.length > 0 ? messages[0] : undefined;
+}
+/**
+ * Fetch L1 to L2 messages.
+ * @param inbox - The inbox contract wrapper.
+ * @param searchStartBlock - The block number to use for starting the search.
+ * @param searchEndBlock - The highest block number that we should search up to.
+ * @returns An array of InboxLeaf and next eth block to search from.
+ */ export async function retrieveL1ToL2Messages(inbox, searchStartBlock, searchEndBlock) {
+    const retrievedL1ToL2Messages = [];
+    while(searchStartBlock <= searchEndBlock){
+        const messageSentLogs = await inbox.getMessageSentEvents(searchStartBlock, searchEndBlock);
+        if (messageSentLogs.length === 0) {
+            break;
+        }
+        retrievedL1ToL2Messages.push(...mapLogsInboxMessage(messageSentLogs));
+        searchStartBlock = messageSentLogs.at(-1).l1BlockNumber + 1n;
+    }
+    return retrievedL1ToL2Messages;
+}
+function mapLogsInboxMessage(logs) {
+    return logs.map((log)=>({
+            index: log.args.index,
+            leaf: log.args.leaf,
+            l1BlockNumber: log.l1BlockNumber,
+            l1BlockHash: log.l1BlockHash,
+            checkpointNumber: log.args.checkpointNumber,
+            rollingHash: log.args.rollingHash
+        }));
+}
+/** Retrieves L2ProofVerified events from the rollup contract. */ export async function retrieveL2ProofVerifiedEvents(publicClient, rollupAddress, searchStartBlock, searchEndBlock) {
+    const logs = await publicClient.getLogs({
+        address: rollupAddress.toString(),
+        fromBlock: searchStartBlock,
+        toBlock: searchEndBlock ? searchEndBlock : undefined,
+        strict: true,
+        event: getAbiItem({
+            abi: RollupAbi,
+            name: 'L2ProofVerified'
+        })
+    });
+    return logs.map((log)=>({
+            l1BlockNumber: log.blockNumber,
+            checkpointNumber: CheckpointNumber.fromBigInt(log.args.checkpointNumber),
+            proverId: Fr.fromHexString(log.args.proverId),
+            txHash: log.transactionHash
+        }));
+}
+/** Retrieve submitted proofs from the rollup contract */ export async function retrieveL2ProofsFromRollup(publicClient, rollupAddress, searchStartBlock, searchEndBlock) {
+    const logs = await retrieveL2ProofVerifiedEvents(publicClient, rollupAddress, searchStartBlock, searchEndBlock);
+    const retrievedData = [];
+    const lastProcessedL1BlockNumber = logs.length > 0 ? logs.at(-1).l1BlockNumber : searchStartBlock - 1n;
+    for (const { txHash, proverId, checkpointNumber } of logs){
+        const proofData = await getProofFromSubmitProofTx(publicClient, txHash, proverId);
+        retrievedData.push({
+            proof: proofData.proof,
+            proverId: proofData.proverId,
+            checkpointNumber,
+            txHash
+        });
+    }
+    return {
+        retrievedData,
+        lastProcessedL1BlockNumber
+    };
+}
+/**
+ * Gets epoch proof metadata (archive root and proof) from the calldata of an L1 transaction.
+ * Assumes that the block 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 expectedProverId - Expected prover ID.
+ * @returns Epoch proof metadata from the calldata, deserialized.
+ */ export async function getProofFromSubmitProofTx(publicClient, txHash, expectedProverId) {
+    const { input: data } = await publicClient.getTransaction({
+        hash: txHash
+    });
+    const { functionName, args } = decodeFunctionData({
+        abi: RollupAbi,
+        data
+    });
+    let proverId;
+    let archiveRoot;
+    let proof;
+    if (functionName === 'submitEpochRootProof') {
+        const [decodedArgs] = args;
+        proverId = Fr.fromHexString(decodedArgs.args.proverId);
+        archiveRoot = Fr.fromHexString(decodedArgs.args.endArchive);
+        proof = Proof.fromBuffer(Buffer.from(hexToBytes(decodedArgs.proof)));
+    } else {
+        throw new Error(`Unexpected proof method called ${functionName}`);
+    }
+    if (!proverId.equals(expectedProverId)) {
+        throw new Error(`Prover ID mismatch: expected ${expectedProverId} but got ${proverId}`);
+    }
+    return {
+        proverId,
+        archiveRoot,
+        proof
+    };
+}

package/dest/l1/debug_tx.d.ts

@@ -0,0 +1,19 @@
+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 } from '@aztec/foundation/schemas';
+import type { Hex } from 'viem';
+import type { CallInfo } from './types.js';
+/** Zod schema for validating call trace from debug_traceTransaction */
+export declare const callTraceSchema: ZodFor<DebugCallTrace>;
+/**
+ * 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 declare function getSuccessfulCallsFromDebug(client: ViemPublicDebugClient, txHash: Hex, targetAddress: EthAddress, functionSelector: string, logger?: Logger): Promise<CallInfo[]>;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZGVidWdfdHguZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy9sMS9kZWJ1Z190eC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEtBQUssRUFBRSxjQUFjLEVBQUUscUJBQXFCLEVBQUUsTUFBTSx1QkFBdUIsQ0FBQztBQUNuRixPQUFPLEVBQUUsVUFBVSxFQUFFLE1BQU0sK0JBQStCLENBQUM7QUFDM0QsT0FBTyxLQUFLLEVBQUUsTUFBTSxFQUFFLE1BQU0sdUJBQXVCLENBQUM7QUFDcEQsT0FBTyxFQUFFLEtBQUssTUFBTSxFQUFXLE1BQU0sMkJBQTJCLENBQUM7QUFHakUsT0FBTyxLQUFLLEVBQUUsR0FBRyxFQUFFLE1BQU0sTUFBTSxDQUFDO0FBR2hDLE9BQU8sS0FBSyxFQUFFLFFBQVEsRUFBRSxNQUFNLFlBQVksQ0FBQztBQUUzQyx1RUFBdUU7QUFDdkUsZUFBTyxNQUFNLGVBQWUsRUFBRSxNQUFNLENBQUMsY0FBYyxDQWFsRCxDQUFDO0FBRUY7Ozs7Ozs7O0dBUUc7QUFDSCx3QkFBc0IsMkJBQTJCLENBQy9DLE1BQU0sRUFBRSxxQkFBcUIsRUFDN0IsTUFBTSxFQUFFLEdBQUcsRUFDWCxhQUFhLEVBQUUsVUFBVSxFQUN6QixnQkFBZ0IsRUFBRSxNQUFNLEVBQ3hCLE1BQU0sQ0FBQyxFQUFFLE1BQU0sR0FDZCxPQUFPLENBQUMsUUFBUSxFQUFFLENBQUMsQ0F3RHJCIn0=

package/dest/l1/debug_tx.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug_tx.d.ts","sourceRoot":"","sources":["../../src/l1/debug_tx.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AACnF,OAAO,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAC3D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AACpD,OAAO,EAAE,KAAK,MAAM,EAAW,MAAM,2BAA2B,CAAC;AAGjE,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,MAAM,CAAC;AAGhC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C,uEAAuE;AACvE,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,cAAc,CAalD,CAAC;AAEF;;;;;;;;GAQG;AACH,wBAAsB,2BAA2B,CAC/C,MAAM,EAAE,qBAAqB,EAC7B,MAAM,EAAE,GAAG,EACX,aAAa,EAAE,UAAU,EACzB,gBAAgB,EAAE,MAAM,EACxB,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,QAAQ,EAAE,CAAC,CAwDrB"}

package/dest/l1/debug_tx.js

@@ -0,0 +1,73 @@
+import { EthAddress } from '@aztec/foundation/eth-address';
+import { schemas } from '@aztec/foundation/schemas';
+import { withHexPrefix } from '@aztec/foundation/string';
+import { z } from 'zod';
+/** Zod schema for validating call trace from debug_traceTransaction */ export const callTraceSchema = 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, txHash, targetAddress, functionSelector, logger) {
+    // 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 = [];
+    /**
+   * Recursively traverse the call trace tree
+   */ function traverseCalls(callTrace) {
+        // 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/dest/l1/spire_proposer.d.ts

@@ -0,0 +1,70 @@
+import type { Logger } from '@aztec/foundation/log';
+import { type Hex, type Transaction } from 'viem';
+export declare const SPIRE_PROPOSER_ADDRESS = "0x9ccc2f3ecde026230e11a5c8799ac7524f2bb294";
+export declare const SPIRE_PROPOSER_EXPECTED_IMPLEMENTATION = "0x7d38d47e7c82195e6e607d3b0f1c20c615c7bf42";
+export declare const EIP1967_IMPLEMENTATION_SLOT: "0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc";
+export declare const SpireProposerAbi: readonly [{
+    readonly inputs: readonly [{
+        readonly components: readonly [{
+            readonly internalType: "address";
+            readonly name: "proposer";
+            readonly type: "address";
+        }, {
+            readonly internalType: "address";
+            readonly name: "target";
+            readonly type: "address";
+        }, {
+            readonly internalType: "bytes";
+            readonly name: "data";
+            readonly type: "bytes";
+        }, {
+            readonly internalType: "uint256";
+            readonly name: "value";
+            readonly type: "uint256";
+        }, {
+            readonly internalType: "uint256";
+            readonly name: "gasLimit";
+            readonly type: "uint256";
+        }];
+        readonly internalType: "struct IProposerMulticall.Call[]";
+        readonly name: "_calls";
+        readonly type: "tuple[]";
+    }];
+    readonly name: "multicall";
+    readonly outputs: readonly [];
+    readonly stateMutability: "nonpayable";
+    readonly type: "function";
+}];
+/**
+ * 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 declare function verifyProxyImplementation(publicClient: {
+    getStorageAt: (params: {
+        address: Hex;
+        slot: Hex;
+    }) => Promise<Hex | undefined>;
+}, proxyAddress: Hex, expectedImplementation: Hex, logger: Logger): Promise<boolean>;
+/**
+ * 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 declare function getCallsFromSpireProposer(tx: Transaction, publicClient: {
+    getStorageAt: (params: {
+        address: Hex;
+        slot: Hex;
+    }) => Promise<Hex | undefined>;
+}, logger: Logger): Promise<{
+    to: Hex;
+    data: Hex;
+}[] | undefined>;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic3BpcmVfcHJvcG9zZXIuZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy9sMS9zcGlyZV9wcm9wb3Nlci50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFDQSxPQUFPLEtBQUssRUFBRSxNQUFNLEVBQUUsTUFBTSx1QkFBdUIsQ0FBQztBQUVwRCxPQUFPLEVBQUUsS0FBSyxHQUFHLEVBQUUsS0FBSyxXQUFXLEVBQXdDLE1BQU0sTUFBTSxDQUFDO0FBR3hGLGVBQU8sTUFBTSxzQkFBc0IsK0NBQStDLENBQUM7QUFDbkYsZUFBTyxNQUFNLHNDQUFzQywrQ0FBK0MsQ0FBQztBQUluRyxlQUFPLE1BQU0sMkJBQTJCLHNFQUN1QyxDQUFDO0FBR2hGLGVBQU8sTUFBTSxnQkFBZ0I7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7RUFxQm5CLENBQUM7QUFFWDs7Ozs7OztHQU9HO0FBQ0gsd0JBQXNCLHlCQUF5QixDQUM3QyxZQUFZLEVBQUU7SUFBRSxZQUFZLEVBQUUsQ0FBQyxNQUFNLEVBQUU7UUFBRSxPQUFPLEVBQUUsR0FBRyxDQUFDO1FBQUMsSUFBSSxFQUFFLEdBQUcsQ0FBQTtLQUFFLEtBQUssT0FBTyxDQUFDLEdBQUcsR0FBRyxTQUFTLENBQUMsQ0FBQTtDQUFFLEVBQ2pHLFlBQVksRUFBRSxHQUFHLEVBQ2pCLHNCQUFzQixFQUFFLEdBQUcsRUFDM0IsTUFBTSxFQUFFLE1BQU0sR0FDYixPQUFPLENBQUMsT0FBTyxDQUFDLENBaUNsQjtBQUVEOzs7Ozs7OztHQVFHO0FBQ0gsd0JBQXNCLHlCQUF5QixDQUM3QyxFQUFFLEVBQUUsV0FBVyxFQUNmLFlBQVksRUFBRTtJQUFFLFlBQVksRUFBRSxDQUFDLE1BQU0sRUFBRTtRQUFFLE9BQU8sRUFBRSxHQUFHLENBQUM7UUFBQyxJQUFJLEVBQUUsR0FBRyxDQUFBO0tBQUUsS0FBSyxPQUFPLENBQUMsR0FBRyxHQUFHLFNBQVMsQ0FBQyxDQUFBO0NBQUUsRUFDakcsTUFBTSxFQUFFLE1BQU0sR0FDYixPQUFPLENBQUM7SUFBRSxFQUFFLEVBQUUsR0FBRyxDQUFDO0lBQUMsSUFBSSxFQUFFLEdBQUcsQ0FBQTtDQUFFLEVBQUUsR0FBRyxTQUFTLENBQUMsQ0FvRC9DIn0=

package/dest/l1/spire_proposer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spire_proposer.d.ts","sourceRoot":"","sources":["../../src/l1/spire_proposer.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAEpD,OAAO,EAAE,KAAK,GAAG,EAAE,KAAK,WAAW,EAAwC,MAAM,MAAM,CAAC;AAGxF,eAAO,MAAM,sBAAsB,+CAA+C,CAAC;AACnF,eAAO,MAAM,sCAAsC,+CAA+C,CAAC;AAInG,eAAO,MAAM,2BAA2B,sEACuC,CAAC;AAGhF,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAqBnB,CAAC;AAEX;;;;;;;GAOG;AACH,wBAAsB,yBAAyB,CAC7C,YAAY,EAAE;IAAE,YAAY,EAAE,CAAC,MAAM,EAAE;QAAE,OAAO,EAAE,GAAG,CAAC;QAAC,IAAI,EAAE,GAAG,CAAA;KAAE,KAAK,OAAO,CAAC,GAAG,GAAG,SAAS,CAAC,CAAA;CAAE,EACjG,YAAY,EAAE,GAAG,EACjB,sBAAsB,EAAE,GAAG,EAC3B,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,OAAO,CAAC,CAiClB;AAED;;;;;;;;GAQG;AACH,wBAAsB,yBAAyB,CAC7C,EAAE,EAAE,WAAW,EACf,YAAY,EAAE;IAAE,YAAY,EAAE,CAAC,MAAM,EAAE;QAAE,OAAO,EAAE,GAAG,CAAC;QAAC,IAAI,EAAE,GAAG,CAAA;KAAE,KAAK,OAAO,CAAC,GAAG,GAAG,SAAS,CAAC,CAAA;CAAE,EACjG,MAAM,EAAE,MAAM,GACb,OAAO,CAAC;IAAE,EAAE,EAAE,GAAG,CAAC;IAAC,IAAI,EAAE,GAAG,CAAA;CAAE,EAAE,GAAG,SAAS,CAAC,CAoD/C"}

package/dest/l1/spire_proposer.js

@@ -0,0 +1,149 @@
+import { EthAddress } from '@aztec/foundation/eth-address';
+import { 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';
+// 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'
+    }
+];
+/**
+ * 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, proxyAddress, expectedImplementation, logger) {
+    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, publicClient, logger) {
+    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, SPIRE_PROPOSER_EXPECTED_IMPLEMENTATION, 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;
+    }
+}