@aztec/archiver 0.0.1-commit.fce3e4f → 0.0.1-commit.ff7989d6c

package/dest/l1/calldata_retriever.d.ts

@@ -0,0 +1,118 @@
+import type { ViemPublicClient, ViemPublicDebugClient } from '@aztec/ethereum/types';
+import { CheckpointNumber } from '@aztec/foundation/branded-types';
+import { Fr } from '@aztec/foundation/curves/bn254';
+import { EthAddress } from '@aztec/foundation/eth-address';
+import type { Logger } from '@aztec/foundation/log';
+import { CommitteeAttestation } from '@aztec/stdlib/block';
+import { CheckpointHeader } from '@aztec/stdlib/rollup';
+import { type Hex, type Transaction } from 'viem';
+import type { ArchiverInstrumentation } from '../modules/instrumentation.js';
+/**
+ * Extracts calldata to the `propose` method of the rollup contract from an L1 transaction
+ * in order to reconstruct an L2 block header.
+ */
+export declare class CalldataRetriever {
+    private readonly publicClient;
+    private readonly debugClient;
+    private readonly targetCommitteeSize;
+    private readonly instrumentation;
+    private readonly logger;
+    /** Tx hashes we've already logged for trace+debug failure (log once per tx per process). */
+    private static readonly traceFailureWarnedTxHashes;
+    /** Clears the trace-failure warned set. For testing only. */
+    static resetTraceFailureWarnedForTesting(): void;
+    /** Pre-computed valid contract calls for validation */
+    private readonly validContractCalls;
+    private readonly rollupAddress;
+    constructor(publicClient: ViemPublicClient, debugClient: ViemPublicDebugClient, targetCommitteeSize: number, instrumentation: ArchiverInstrumentation | undefined, logger: Logger, contractAddresses: {
+        rollupAddress: EthAddress;
+        governanceProposerAddress: EthAddress;
+        slashingProposerAddress: EthAddress;
+        slashFactoryAddress?: EthAddress;
+    });
+    /**
+     * Gets checkpoint header and metadata from the calldata of an L1 transaction.
+     * Tries multicall3 decoding, falls back to trace-based extraction.
+     * @param txHash - Hash of the tx that published it.
+     * @param blobHashes - Blob hashes for the checkpoint.
+     * @param checkpointNumber - Checkpoint number.
+     * @param expectedHashes - Optional expected hashes from the CheckpointProposed event for validation
+     * @returns Checkpoint header and metadata from the calldata, deserialized
+     */
+    getCheckpointFromRollupTx(txHash: `0x${string}`, _blobHashes: Buffer[], checkpointNumber: CheckpointNumber, expectedHashes: {
+        attestationsHash?: Hex;
+        payloadDigest?: Hex;
+    }): Promise<{
+        checkpointNumber: CheckpointNumber;
+        archiveRoot: Fr;
+        header: CheckpointHeader;
+        attestations: CommitteeAttestation[];
+        blockHash: string;
+        feeAssetPriceModifier: bigint;
+    }>;
+    /** Gets rollup propose calldata from a transaction */
+    protected getProposeCallData(tx: Transaction, checkpointNumber: CheckpointNumber): Promise<Hex>;
+    /**
+     * Attempts to decode a transaction as a Spire Proposer multicall wrapper.
+     * If successful, extracts the wrapped call and validates it as either multicall3 or direct propose.
+     * @param tx - The transaction to decode
+     * @returns The propose calldata if successfully decoded and validated, undefined otherwise
+     */
+    protected tryDecodeSpireProposer(tx: Transaction): Promise<Hex | undefined>;
+    /**
+     * Attempts to decode transaction input as multicall3 and extract propose calldata.
+     * Returns undefined if validation fails.
+     * @param tx - The transaction-like object with to, input, and hash
+     * @returns The propose calldata if successfully validated, undefined otherwise
+     */
+    protected tryDecodeMulticall3(tx: {
+        to: Hex | null | undefined;
+        input: Hex;
+        hash: Hex;
+    }): Hex | undefined;
+    /**
+     * Attempts to decode transaction as a direct propose call to the rollup contract.
+     * Returns undefined if validation fails.
+     * @param tx - The transaction-like object with to, input, and hash
+     * @returns The propose calldata if successfully validated, undefined otherwise
+     */
+    protected tryDecodeDirectPropose(tx: {
+        to: Hex | null | undefined;
+        input: Hex;
+        hash: Hex;
+    }): Hex | undefined;
+    /**
+     * Uses debug/trace RPC to extract the actual calldata from the successful propose call.
+     * This is the definitive fallback that works for any transaction pattern.
+     * Tries trace_transaction first, then falls back to debug_traceTransaction.
+     * @param txHash - The transaction hash to trace
+     * @returns The propose calldata from the successful call
+     */
+    protected extractCalldataViaTrace(txHash: Hex): Promise<Hex>;
+    /**
+     * Extracts the CommitteeAttestations struct definition from RollupAbi.
+     * Finds the _attestations parameter by name in the propose function.
+     * Lazy-loaded to avoid issues during module initialization.
+     */
+    private getCommitteeAttestationsStructDef;
+    /**
+     * Decodes propose calldata and builds the checkpoint header structure.
+     * @param proposeCalldata - The propose function calldata
+     * @param blockHash - The L1 block hash containing this transaction
+     * @param checkpointNumber - The checkpoint number
+     * @param expectedHashes - Optional expected hashes from the CheckpointProposed event for validation
+     * @returns The decoded checkpoint header and metadata
+     */
+    protected decodeAndBuildCheckpoint(proposeCalldata: Hex, blockHash: Hex, checkpointNumber: CheckpointNumber, expectedHashes: {
+        attestationsHash?: Hex;
+        payloadDigest?: Hex;
+    }): {
+        checkpointNumber: CheckpointNumber;
+        archiveRoot: Fr;
+        header: CheckpointHeader;
+        attestations: CommitteeAttestation[];
+        blockHash: string;
+        feeAssetPriceModifier: bigint;
+    };
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2FsbGRhdGFfcmV0cmlldmVyLmQudHMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvbDEvY2FsbGRhdGFfcmV0cmlldmVyLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUNBLE9BQU8sS0FBSyxFQUFFLGdCQUFnQixFQUFFLHFCQUFxQixFQUFFLE1BQU0sdUJBQXVCLENBQUM7QUFDckYsT0FBTyxFQUFFLGdCQUFnQixFQUFFLE1BQU0saUNBQWlDLENBQUM7QUFDbkUsT0FBTyxFQUFFLEVBQUUsRUFBRSxNQUFNLGdDQUFnQyxDQUFDO0FBQ3BELE9BQU8sRUFBRSxVQUFVLEVBQUUsTUFBTSwrQkFBK0IsQ0FBQztBQUUzRCxPQUFPLEtBQUssRUFBRSxNQUFNLEVBQUUsTUFBTSx1QkFBdUIsQ0FBQztBQVFwRCxPQUFPLEVBQUUsb0JBQW9CLEVBQUUsTUFBTSxxQkFBcUIsQ0FBQztBQUUzRCxPQUFPLEVBQUUsZ0JBQWdCLEVBQUUsTUFBTSxzQkFBc0IsQ0FBQztBQUV4RCxPQUFPLEVBRUwsS0FBSyxHQUFHLEVBQ1IsS0FBSyxXQUFXLEVBT2pCLE1BQU0sTUFBTSxDQUFDO0FBRWQsT0FBTyxLQUFLLEVBQUUsdUJBQXVCLEVBQUUsTUFBTSwrQkFBK0IsQ0FBQztBQU03RTs7O0dBR0c7QUFDSCxxQkFBYSxpQkFBaUI7SUFlMUIsT0FBTyxDQUFDLFFBQVEsQ0FBQyxZQUFZO0lBQzdCLE9BQU8sQ0FBQyxRQUFRLENBQUMsV0FBVztJQUM1QixPQUFPLENBQUMsUUFBUSxDQUFDLG1CQUFtQjtJQUNwQyxPQUFPLENBQUMsUUFBUSxDQUFDLGVBQWU7SUFDaEMsT0FBTyxDQUFDLFFBQVEsQ0FBQyxNQUFNO0lBbEJ6Qiw0RkFBNEY7SUFDNUYsT0FBTyxDQUFDLE1BQU0sQ0FBQyxRQUFRLENBQUMsMEJBQTBCLENBQXFCO0lBRXZFLDZEQUE2RDtJQUM3RCxNQUFNLENBQUMsaUNBQWlDLElBQUksSUFBSSxDQUUvQztJQUVELHVEQUF1RDtJQUN2RCxPQUFP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

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

@@ -0,0 +1 @@
+{"version":3,"file":"calldata_retriever.d.ts","sourceRoot":"","sources":["../../src/l1/calldata_retriever.ts"],"names":[],"mappings":"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"}

package/dest/l1/calldata_retriever.js

@@ -0,0 +1,484 @@
+import { MULTI_CALL_3_ADDRESS } from '@aztec/ethereum/contracts';
+import { Fr } from '@aztec/foundation/curves/bn254';
+import { EthAddress } from '@aztec/foundation/eth-address';
+import { EmpireSlashingProposerAbi, GovernanceProposerAbi, RollupAbi, SlashFactoryAbi, TallySlashingProposerAbi } from '@aztec/l1-artifacts';
+import { CommitteeAttestation } from '@aztec/stdlib/block';
+import { ConsensusPayload, SignatureDomainSeparator } from '@aztec/stdlib/p2p';
+import { CheckpointHeader } from '@aztec/stdlib/rollup';
+import { decodeFunctionData, encodeAbiParameters, hexToBytes, keccak256, multicall3Abi, toFunctionSelector } from 'viem';
+import { getSuccessfulCallsFromDebug } from './debug_tx.js';
+import { getCallFromSpireProposer } from './spire_proposer.js';
+import { getSuccessfulCallsFromTrace } from './trace_tx.js';
+/**
+ * Extracts calldata to the `propose` method of the rollup contract from an L1 transaction
+ * in order to reconstruct an L2 block header.
+ */ export class CalldataRetriever {
+    publicClient;
+    debugClient;
+    targetCommitteeSize;
+    instrumentation;
+    logger;
+    /** Tx hashes we've already logged for trace+debug failure (log once per tx per process). */ static traceFailureWarnedTxHashes = new Set();
+    /** Clears the trace-failure warned set. For testing only. */ static resetTraceFailureWarnedForTesting() {
+        CalldataRetriever.traceFailureWarnedTxHashes.clear();
+    }
+    /** Pre-computed valid contract calls for validation */ validContractCalls;
+    rollupAddress;
+    constructor(publicClient, debugClient, targetCommitteeSize, instrumentation, logger, contractAddresses){
+        this.publicClient = publicClient;
+        this.debugClient = debugClient;
+        this.targetCommitteeSize = targetCommitteeSize;
+        this.instrumentation = instrumentation;
+        this.logger = logger;
+        this.rollupAddress = contractAddresses.rollupAddress;
+        this.validContractCalls = computeValidContractCalls(contractAddresses);
+    }
+    /**
+   * Gets checkpoint header and metadata from the calldata of an L1 transaction.
+   * Tries multicall3 decoding, falls back to trace-based extraction.
+   * @param txHash - Hash of the tx that published it.
+   * @param blobHashes - Blob hashes for the checkpoint.
+   * @param checkpointNumber - Checkpoint number.
+   * @param expectedHashes - Optional expected hashes from the CheckpointProposed event for validation
+   * @returns Checkpoint header and metadata from the calldata, deserialized
+   */ async getCheckpointFromRollupTx(txHash, _blobHashes, checkpointNumber, expectedHashes) {
+        this.logger.trace(`Fetching checkpoint ${checkpointNumber} from rollup tx ${txHash}`, {
+            willValidateHashes: !!expectedHashes.attestationsHash || !!expectedHashes.payloadDigest,
+            hasAttestationsHash: !!expectedHashes.attestationsHash,
+            hasPayloadDigest: !!expectedHashes.payloadDigest
+        });
+        const tx = await this.publicClient.getTransaction({
+            hash: txHash
+        });
+        const proposeCalldata = await this.getProposeCallData(tx, checkpointNumber);
+        return this.decodeAndBuildCheckpoint(proposeCalldata, tx.blockHash, checkpointNumber, expectedHashes);
+    }
+    /** Gets rollup propose calldata from a transaction */ async getProposeCallData(tx, checkpointNumber) {
+        // Try to decode as multicall3 with validation
+        const proposeCalldata = this.tryDecodeMulticall3(tx);
+        if (proposeCalldata) {
+            this.logger.trace(`Decoded propose calldata from multicall3 for tx ${tx.hash}`);
+            this.instrumentation?.recordBlockProposalTxTarget(tx.to, false);
+            return proposeCalldata;
+        }
+        // Try to decode as direct propose call
+        const directProposeCalldata = this.tryDecodeDirectPropose(tx);
+        if (directProposeCalldata) {
+            this.logger.trace(`Decoded propose calldata from direct call for tx ${tx.hash}`);
+            this.instrumentation?.recordBlockProposalTxTarget(tx.to, false);
+            return directProposeCalldata;
+        }
+        // Try to decode as Spire Proposer multicall wrapper
+        const spireProposeCalldata = await this.tryDecodeSpireProposer(tx);
+        if (spireProposeCalldata) {
+            this.logger.trace(`Decoded propose calldata from Spire Proposer for tx ${tx.hash}`);
+            this.instrumentation?.recordBlockProposalTxTarget(tx.to, false);
+            return spireProposeCalldata;
+        }
+        // Fall back to trace-based extraction
+        this.logger.warn(`Failed to decode multicall3, direct propose, or Spire proposer for L1 tx ${tx.hash}, falling back to trace for checkpoint ${checkpointNumber}`);
+        this.instrumentation?.recordBlockProposalTxTarget(tx.to ?? EthAddress.ZERO.toString(), true);
+        return await this.extractCalldataViaTrace(tx.hash);
+    }
+    /**
+   * Attempts to decode a transaction as a Spire Proposer multicall wrapper.
+   * If successful, extracts the wrapped call and validates it as either multicall3 or direct propose.
+   * @param tx - The transaction to decode
+   * @returns The propose calldata if successfully decoded and validated, undefined otherwise
+   */ async tryDecodeSpireProposer(tx) {
+        // Try to decode as Spire Proposer multicall (extracts the wrapped call)
+        const spireWrappedCall = await getCallFromSpireProposer(tx, this.publicClient, this.logger);
+        if (!spireWrappedCall) {
+            return undefined;
+        }
+        this.logger.trace(`Decoded Spire Proposer wrapping for tx ${tx.hash}, inner call to ${spireWrappedCall.to}`);
+        // Now try to decode the wrapped call as either multicall3 or direct propose
+        const wrappedTx = {
+            to: spireWrappedCall.to,
+            input: spireWrappedCall.data,
+            hash: tx.hash
+        };
+        const multicall3Calldata = this.tryDecodeMulticall3(wrappedTx);
+        if (multicall3Calldata) {
+            this.logger.trace(`Decoded propose calldata from Spire Proposer to multicall3 for tx ${tx.hash}`);
+            return multicall3Calldata;
+        }
+        const directProposeCalldata = this.tryDecodeDirectPropose(wrappedTx);
+        if (directProposeCalldata) {
+            this.logger.trace(`Decoded propose calldata from Spire Proposer to direct propose for tx ${tx.hash}`);
+            return directProposeCalldata;
+        }
+        this.logger.warn(`Spire Proposer wrapped call could not be decoded as multicall3 or direct propose for tx ${tx.hash}`);
+        return undefined;
+    }
+    /**
+   * Attempts to decode transaction input as multicall3 and extract propose calldata.
+   * Returns undefined if validation fails.
+   * @param tx - The transaction-like object with to, input, and hash
+   * @returns The propose calldata if successfully validated, undefined otherwise
+   */ tryDecodeMulticall3(tx) {
+        const txHash = tx.hash;
+        try {
+            // Check if transaction is to Multicall3 address
+            if (!tx.to || !EthAddress.areEqual(tx.to, MULTI_CALL_3_ADDRESS)) {
+                this.logger.debug(`Transaction is not to Multicall3 address (to: ${tx.to})`, {
+                    txHash,
+                    to: tx.to
+                });
+                return undefined;
+            }
+            // Try to decode as multicall3 aggregate3 call
+            const { functionName: multicall3Fn, args: multicall3Args } = decodeFunctionData({
+                abi: multicall3Abi,
+                data: tx.input
+            });
+            // If not aggregate3, return undefined (not a multicall3 transaction)
+            if (multicall3Fn !== 'aggregate3') {
+                this.logger.warn(`Transaction is not multicall3 aggregate3 (got ${multicall3Fn})`, {
+                    txHash
+                });
+                return undefined;
+            }
+            if (multicall3Args.length !== 1) {
+                this.logger.warn(`Unexpected number of arguments for multicall3 (got ${multicall3Args.length})`, {
+                    txHash
+                });
+                return undefined;
+            }
+            const [calls] = multicall3Args;
+            // Validate all calls and find propose calls
+            const rollupAddressLower = this.rollupAddress.toString().toLowerCase();
+            const proposeCalls = [];
+            for(let i = 0; i < calls.length; i++){
+                const addr = calls[i].target.toLowerCase();
+                const callData = calls[i].callData;
+                // Extract function selector (first 4 bytes)
+                if (callData.length < 10) {
+                    // "0x" + 8 hex chars = 10 chars minimum for a valid function call
+                    this.logger.warn(`Invalid calldata length at index ${i} (${callData.length})`, {
+                        txHash
+                    });
+                    return undefined;
+                }
+                const functionSelector = callData.slice(0, 10);
+                // Validate this call is allowed by searching through valid calls
+                const validCall = this.validContractCalls.find((vc)=>vc.address === addr && vc.functionSelector === functionSelector);
+                if (!validCall) {
+                    this.logger.warn(`Invalid contract call detected in multicall3`, {
+                        index: i,
+                        targetAddress: addr,
+                        functionSelector,
+                        validCalls: this.validContractCalls.map((c)=>({
+                                address: c.address,
+                                selector: c.functionSelector
+                            })),
+                        txHash
+                    });
+                    return undefined;
+                }
+                this.logger.trace(`Valid call found to ${addr}`, {
+                    validCall
+                });
+                // Collect propose calls specifically
+                if (addr === rollupAddressLower && validCall.functionName === 'propose') {
+                    proposeCalls.push(callData);
+                }
+            }
+            // Validate exactly ONE propose call
+            if (proposeCalls.length === 0) {
+                this.logger.warn(`No propose calls found in multicall3`, {
+                    txHash
+                });
+                return undefined;
+            }
+            if (proposeCalls.length > 1) {
+                this.logger.warn(`Multiple propose calls found in multicall3 (${proposeCalls.length})`, {
+                    txHash
+                });
+                return undefined;
+            }
+            // Successfully extracted single propose call
+            return proposeCalls[0];
+        } catch (err) {
+            // Any decoding error triggers fallback to trace
+            this.logger.warn(`Failed to decode multicall3: ${err}`, {
+                txHash
+            });
+            return undefined;
+        }
+    }
+    /**
+   * Attempts to decode transaction as a direct propose call to the rollup contract.
+   * Returns undefined if validation fails.
+   * @param tx - The transaction-like object with to, input, and hash
+   * @returns The propose calldata if successfully validated, undefined otherwise
+   */ tryDecodeDirectPropose(tx) {
+        const txHash = tx.hash;
+        try {
+            // Check if transaction is to the rollup address
+            if (!tx.to || !EthAddress.areEqual(tx.to, this.rollupAddress)) {
+                this.logger.debug(`Transaction is not to rollup address (to: ${tx.to})`, {
+                    txHash
+                });
+                return undefined;
+            }
+            // Try to decode as propose call
+            const { functionName } = decodeFunctionData({
+                abi: RollupAbi,
+                data: tx.input
+            });
+            // If not propose, return undefined
+            if (functionName !== 'propose') {
+                this.logger.warn(`Transaction to rollup is not propose (got ${functionName})`, {
+                    txHash
+                });
+                return undefined;
+            }
+            // Successfully validated direct propose call
+            this.logger.trace(`Validated direct propose call to rollup`, {
+                txHash
+            });
+            return tx.input;
+        } catch (err) {
+            // Any decoding error means it's not a valid propose call
+            this.logger.warn(`Failed to decode as direct propose: ${err}`, {
+                txHash
+            });
+            return undefined;
+        }
+    }
+    /**
+   * Uses debug/trace RPC to extract the actual calldata from the successful propose call.
+   * This is the definitive fallback that works for any transaction pattern.
+   * Tries trace_transaction first, then falls back to debug_traceTransaction.
+   * @param txHash - The transaction hash to trace
+   * @returns The propose calldata from the successful call
+   */ async extractCalldataViaTrace(txHash) {
+        const rollupAddress = this.rollupAddress;
+        const selector = PROPOSE_SELECTOR;
+        let calls;
+        try {
+            // Try trace_transaction first (using Parity/OpenEthereum/Erigon RPC)
+            this.logger.debug(`Attempting to trace transaction ${txHash} using trace_transaction`);
+            calls = await getSuccessfulCallsFromTrace(this.debugClient, txHash, rollupAddress, selector, this.logger);
+            this.logger.debug(`Successfully traced using trace_transaction, found ${calls.length} calls`);
+        } catch (err) {
+            const traceError = err instanceof Error ? err : new Error(String(err));
+            this.logger.verbose(`Failed trace_transaction for ${txHash}: ${traceError.message}`);
+            this.logger.debug(`Trace failure details for ${txHash}`, {
+                traceError
+            });
+            try {
+                // Fall back to debug_traceTransaction (Geth RPC)
+                this.logger.debug(`Attempting to trace transaction ${txHash} using debug_traceTransaction`);
+                calls = await getSuccessfulCallsFromDebug(this.debugClient, txHash, rollupAddress, selector, this.logger);
+                this.logger.debug(`Successfully traced using debug_traceTransaction, found ${calls.length} calls`);
+            } catch (debugErr) {
+                const debugError = debugErr instanceof Error ? debugErr : new Error(String(debugErr));
+                // Log once per tx so we don't spam on every sync cycle when sync point doesn't advance
+                if (!CalldataRetriever.traceFailureWarnedTxHashes.has(txHash)) {
+                    CalldataRetriever.traceFailureWarnedTxHashes.add(txHash);
+                    this.logger.warn(`Cannot decode L1 tx ${txHash}: trace and debug RPC failed or unavailable. ` + `trace_transaction: ${traceError.message}; debug_traceTransaction: ${debugError.message}`);
+                }
+                // Full error objects can be very long; keep at debug only
+                this.logger.debug(`Trace/debug failure details for tx ${txHash}`, {
+                    traceError,
+                    debugError,
+                    txHash
+                });
+                throw new Error(`Failed to trace transaction ${txHash} to extract propose calldata`);
+            }
+        }
+        // Validate exactly ONE successful propose call
+        if (calls.length === 0) {
+            throw new Error(`No successful propose calls found in transaction ${txHash}`);
+        }
+        if (calls.length > 1) {
+            throw new Error(`Multiple successful propose calls found in transaction ${txHash} (${calls.length})`);
+        }
+        // Return the calldata from the single successful propose call
+        return calls[0].input;
+    }
+    /**
+   * Extracts the CommitteeAttestations struct definition from RollupAbi.
+   * Finds the _attestations parameter by name in the propose function.
+   * Lazy-loaded to avoid issues during module initialization.
+   */ getCommitteeAttestationsStructDef() {
+        const proposeFunction = RollupAbi.find((item)=>item.type === 'function' && item.name === 'propose');
+        if (!proposeFunction) {
+            throw new Error('propose function not found in RollupAbi');
+        }
+        // Find the _attestations parameter by name, not by index
+        const attestationsParam = proposeFunction.inputs.find((param)=>param.name === '_attestations');
+        if (!attestationsParam) {
+            throw new Error('_attestations parameter not found in propose function');
+        }
+        if (attestationsParam.type !== 'tuple') {
+            throw new Error(`Expected _attestations parameter to be a tuple, got ${attestationsParam.type}`);
+        }
+        // Extract the tuple components (struct fields)
+        const tupleParam = attestationsParam;
+        return {
+            type: 'tuple',
+            components: tupleParam.components || []
+        };
+    }
+    /**
+   * Decodes propose calldata and builds the checkpoint header structure.
+   * @param proposeCalldata - The propose function calldata
+   * @param blockHash - The L1 block hash containing this transaction
+   * @param checkpointNumber - The checkpoint number
+   * @param expectedHashes - Optional expected hashes from the CheckpointProposed event for validation
+   * @returns The decoded checkpoint header and metadata
+   */ decodeAndBuildCheckpoint(proposeCalldata, blockHash, checkpointNumber, expectedHashes) {
+        const { functionName: rollupFunctionName, args: rollupArgs } = decodeFunctionData({
+            abi: RollupAbi,
+            data: proposeCalldata
+        });
+        if (rollupFunctionName !== 'propose') {
+            throw new Error(`Unexpected rollup method called ${rollupFunctionName}`);
+        }
+        const [decodedArgs, packedAttestations, _signers, _attestationsAndSignersSignature, _blobInput] = rollupArgs;
+        const attestations = CommitteeAttestation.fromPacked(packedAttestations, this.targetCommitteeSize);
+        const header = CheckpointHeader.fromViem(decodedArgs.header);
+        const archiveRoot = new Fr(Buffer.from(hexToBytes(decodedArgs.archive)));
+        // Validate attestationsHash if provided (skip for backwards compatibility with older events)
+        if (expectedHashes.attestationsHash) {
+            // Compute attestationsHash: keccak256(abi.encode(CommitteeAttestations))
+            const computedAttestationsHash = keccak256(encodeAbiParameters([
+                this.getCommitteeAttestationsStructDef()
+            ], [
+                packedAttestations
+            ]));
+            // Compare as buffers to avoid case-sensitivity and string comparison issues
+            const computedBuffer = Buffer.from(hexToBytes(computedAttestationsHash));
+            const expectedBuffer = Buffer.from(hexToBytes(expectedHashes.attestationsHash));
+            if (!computedBuffer.equals(expectedBuffer)) {
+                throw new Error(`Attestations hash mismatch for checkpoint ${checkpointNumber}: ` + `computed=${computedAttestationsHash}, expected=${expectedHashes.attestationsHash}`);
+            }
+            this.logger.trace(`Validated attestationsHash for checkpoint ${checkpointNumber}`, {
+                computedAttestationsHash,
+                expectedAttestationsHash: expectedHashes.attestationsHash
+            });
+        }
+        // Validate payloadDigest if provided (skip for backwards compatibility with older events)
+        if (expectedHashes.payloadDigest) {
+            // Use ConsensusPayload to compute the digest - this ensures we match the exact logic
+            // used by the network for signing and verification
+            const feeAssetPriceModifier = decodedArgs.oracleInput.feeAssetPriceModifier;
+            const consensusPayload = new ConsensusPayload(header, archiveRoot, feeAssetPriceModifier);
+            const payloadToSign = consensusPayload.getPayloadToSign(SignatureDomainSeparator.checkpointAttestation);
+            const computedPayloadDigest = keccak256(payloadToSign);
+            // Compare as buffers to avoid case-sensitivity and string comparison issues
+            const computedBuffer = Buffer.from(hexToBytes(computedPayloadDigest));
+            const expectedBuffer = Buffer.from(hexToBytes(expectedHashes.payloadDigest));
+            if (!computedBuffer.equals(expectedBuffer)) {
+                throw new Error(`Payload digest mismatch for checkpoint ${checkpointNumber}: ` + `computed=${computedPayloadDigest}, expected=${expectedHashes.payloadDigest}`);
+            }
+            this.logger.trace(`Validated payloadDigest for checkpoint ${checkpointNumber}`, {
+                computedPayloadDigest,
+                expectedPayloadDigest: expectedHashes.payloadDigest
+            });
+        }
+        this.logger.trace(`Decoded propose calldata`, {
+            checkpointNumber,
+            archive: decodedArgs.archive,
+            header: decodedArgs.header,
+            l1BlockHash: blockHash,
+            attestations,
+            packedAttestations,
+            targetCommitteeSize: this.targetCommitteeSize
+        });
+        return {
+            checkpointNumber,
+            archiveRoot,
+            header,
+            attestations,
+            blockHash,
+            feeAssetPriceModifier: decodedArgs.oracleInput.feeAssetPriceModifier
+        };
+    }
+}
+/**
+ * Pre-computed function selectors for all valid contract calls.
+ * These are computed once at module load time from the ABIs.
+ * Based on analysis of sequencer-client/src/publisher/sequencer-publisher.ts
+ */ // Rollup contract function selectors (always valid)
+const PROPOSE_SELECTOR = toFunctionSelector(RollupAbi.find((x)=>x.type === 'function' && x.name === 'propose'));
+const INVALIDATE_BAD_ATTESTATION_SELECTOR = toFunctionSelector(RollupAbi.find((x)=>x.type === 'function' && x.name === 'invalidateBadAttestation'));
+const INVALIDATE_INSUFFICIENT_ATTESTATIONS_SELECTOR = toFunctionSelector(RollupAbi.find((x)=>x.type === 'function' && x.name === 'invalidateInsufficientAttestations'));
+// Governance proposer function selectors
+const GOVERNANCE_SIGNAL_WITH_SIG_SELECTOR = toFunctionSelector(GovernanceProposerAbi.find((x)=>x.type === 'function' && x.name === 'signalWithSig'));
+// Slash factory function selectors
+const CREATE_SLASH_PAYLOAD_SELECTOR = toFunctionSelector(SlashFactoryAbi.find((x)=>x.type === 'function' && x.name === 'createSlashPayload'));
+// Empire slashing proposer function selectors
+const EMPIRE_SIGNAL_WITH_SIG_SELECTOR = toFunctionSelector(EmpireSlashingProposerAbi.find((x)=>x.type === 'function' && x.name === 'signalWithSig'));
+const EMPIRE_SUBMIT_ROUND_WINNER_SELECTOR = toFunctionSelector(EmpireSlashingProposerAbi.find((x)=>x.type === 'function' && x.name === 'submitRoundWinner'));
+// Tally slashing proposer function selectors
+const TALLY_VOTE_SELECTOR = toFunctionSelector(TallySlashingProposerAbi.find((x)=>x.type === 'function' && x.name === 'vote'));
+const TALLY_EXECUTE_ROUND_SELECTOR = toFunctionSelector(TallySlashingProposerAbi.find((x)=>x.type === 'function' && x.name === 'executeRound'));
+/**
+ * All valid contract calls that the sequencer publisher can make.
+ * Builds the list of valid (address, selector) pairs for validation.
+ *
+ * Alternatively, if we are absolutely sure that no code path from any of these
+ * contracts can eventually land on another call to `propose`, we can remove the
+ * function selectors.
+ */ function computeValidContractCalls(addresses) {
+    const { rollupAddress, governanceProposerAddress, slashFactoryAddress, slashingProposerAddress } = addresses;
+    const calls = [];
+    // Rollup contract calls (always present)
+    calls.push({
+        address: rollupAddress.toString().toLowerCase(),
+        functionSelector: PROPOSE_SELECTOR,
+        functionName: 'propose'
+    }, {
+        address: rollupAddress.toString().toLowerCase(),
+        functionSelector: INVALIDATE_BAD_ATTESTATION_SELECTOR,
+        functionName: 'invalidateBadAttestation'
+    }, {
+        address: rollupAddress.toString().toLowerCase(),
+        functionSelector: INVALIDATE_INSUFFICIENT_ATTESTATIONS_SELECTOR,
+        functionName: 'invalidateInsufficientAttestations'
+    });
+    // Governance proposer calls (optional)
+    if (governanceProposerAddress && !governanceProposerAddress.isZero()) {
+        calls.push({
+            address: governanceProposerAddress.toString().toLowerCase(),
+            functionSelector: GOVERNANCE_SIGNAL_WITH_SIG_SELECTOR,
+            functionName: 'signalWithSig'
+        });
+    }
+    // Slash factory calls (optional)
+    if (slashFactoryAddress && !slashFactoryAddress.isZero()) {
+        calls.push({
+            address: slashFactoryAddress.toString().toLowerCase(),
+            functionSelector: CREATE_SLASH_PAYLOAD_SELECTOR,
+            functionName: 'createSlashPayload'
+        });
+    }
+    // Slashing proposer calls (optional, can be either Empire or Tally)
+    if (slashingProposerAddress && !slashingProposerAddress.isZero()) {
+        // Empire calls
+        calls.push({
+            address: slashingProposerAddress.toString().toLowerCase(),
+            functionSelector: EMPIRE_SIGNAL_WITH_SIG_SELECTOR,
+            functionName: 'signalWithSig (empire)'
+        }, {
+            address: slashingProposerAddress.toString().toLowerCase(),
+            functionSelector: EMPIRE_SUBMIT_ROUND_WINNER_SELECTOR,
+            functionName: 'submitRoundWinner'
+        });
+        // Tally calls
+        calls.push({
+            address: slashingProposerAddress.toString().toLowerCase(),
+            functionSelector: TALLY_VOTE_SELECTOR,
+            functionName: 'vote'
+        }, {
+            address: slashingProposerAddress.toString().toLowerCase(),
+            functionSelector: TALLY_EXECUTE_ROUND_SELECTOR,
+            functionName: 'executeRound'
+        });
+    }
+    return calls;
+}