@aztec/archiver 0.0.0-test.1 → 0.0.1-commit.017a351

package/dest/test/mock_l2_block_source.js

@@ -1,34 +1,152 @@
-import { DefaultL1ContractsConfig } from '@aztec/ethereum';
+import { GENESIS_ARCHIVE_ROOT } from '@aztec/constants';
+import { DefaultL1ContractsConfig } from '@aztec/ethereum/config';
+import { BlockNumber, CheckpointNumber, IndexWithinCheckpoint, SlotNumber } from '@aztec/foundation/branded-types';
+import { Buffer32 } from '@aztec/foundation/buffer';
+import { Fr } from '@aztec/foundation/curves/bn254';
 import { EthAddress } from '@aztec/foundation/eth-address';
 import { createLogger } from '@aztec/foundation/log';
-import { L2Block, L2BlockHash } from '@aztec/stdlib/block';
-import { getSlotRangeForEpoch } from '@aztec/stdlib/epoch-helpers';
-import { TxReceipt, TxStatus } from '@aztec/stdlib/tx';
+import { Body, GENESIS_BLOCK_HEADER_HASH, GENESIS_CHECKPOINT_HEADER_HASH, L2Block } from '@aztec/stdlib/block';
+import { Checkpoint, L1PublishedData, PublishedCheckpoint } from '@aztec/stdlib/checkpoint';
+import { EmptyL1RollupConstants, getSlotRangeForEpoch } from '@aztec/stdlib/epoch-helpers';
+import { computeCheckpointOutHash } from '@aztec/stdlib/messaging';
+import { CheckpointHeader } from '@aztec/stdlib/rollup';
+import { AppendOnlyTreeSnapshot } from '@aztec/stdlib/trees';
+import { BlockHeader } from '@aztec/stdlib/tx';
 /**
  * A mocked implementation of L2BlockSource to be used in tests.
  */ export class MockL2BlockSource {
     l2Blocks = [];
+    checkpointList = [];
     provenBlockNumber = 0;
+    finalizedBlockNumber = 0;
+    checkpointedBlockNumber = 0;
+    proposedCheckpointBlockNumber = 0;
+    initialHeader = BlockHeader.empty();
+    initialHeaderHash = GENESIS_BLOCK_HEADER_HASH;
+    genesisArchiveRoot;
+    genesisBlock;
     log = createLogger('archiver:mock_l2_block_source');
-    async createBlocks(numBlocks) {
-        for(let i = 0; i < numBlocks; i++){
-            const blockNum = this.l2Blocks.length + 1;
-            const block = await L2Block.random(blockNum);
-            this.l2Blocks.push(block);
+    /** Returns the initial header used to synthesize block 0. */ getInitialHeader() {
+        return this.initialHeader;
+    }
+    /**
+   * Sets the initial header used to synthesize block 0. Tests that wire up a real
+   * world-state should call this with `worldState.getInitialHeader()` so the L2BlockStream
+   * agrees on the genesis hash on both sides. Precomputes and caches the header hash so
+   * `getGenesisBlockHash()` can return synchronously.
+   */ async setInitialHeader(header) {
+        this.initialHeader = header;
+        this.initialHeaderHash = await header.hash();
+        this.genesisBlock = undefined;
+    }
+    /**
+   * Returns the precomputed hash of the genesis block header. Defaults to the static
+   * {@link GENESIS_BLOCK_HEADER_HASH} unless {@link setInitialHeader} has been called with a
+   * custom header.
+   */ getGenesisBlockHash() {
+        return this.initialHeaderHash;
+    }
+    /**
+   * Sets the post-genesis archive root used to synthesize block 0. Mirrors the real archiver,
+   * whose synthetic block 0 carries `new AppendOnlyTreeSnapshot(genesisArchiveRoot, 1)` rather
+   * than `AppendOnlyTreeSnapshot.empty()`. Tests wiring up a real world-state should set this so
+   * archive-based block lookups against the mock match production semantics.
+   */ setGenesisArchiveRoot(root) {
+        this.genesisArchiveRoot = root;
+        this.genesisBlock = undefined;
+    }
+    getGenesisBlock() {
+        if (this.genesisBlock) {
+            return this.genesisBlock;
         }
-        this.log.verbose(`Created ${numBlocks} blocks in the mock L2 block source`);
+        const archive = this.genesisArchiveRoot ? new AppendOnlyTreeSnapshot(this.genesisArchiveRoot, 1) : AppendOnlyTreeSnapshot.empty();
+        return this.genesisBlock = new L2Block(archive, this.initialHeader, Body.empty(), CheckpointNumber.ZERO, IndexWithinCheckpoint(0));
     }
-    addBlocks(blocks) {
+    /** Creates blocks grouped into single-block checkpoints. */ async createBlocks(numBlocks) {
+        await this.createCheckpoints(numBlocks, 1);
+    }
+    getCheckpointNumber() {
+        return Promise.resolve(this.checkpointList.length === 0 ? CheckpointNumber.ZERO : CheckpointNumber(this.checkpointList.length));
+    }
+    /** Creates checkpoints, each containing `blocksPerCheckpoint` blocks. */ async createCheckpoints(numCheckpoints, blocksPerCheckpoint = 1) {
+        for(let c = 0; c < numCheckpoints; c++){
+            const checkpointNum = CheckpointNumber(this.checkpointList.length + 1);
+            const startBlockNum = this.l2Blocks.length + 1;
+            const slotNumber = SlotNumber(Number(checkpointNum));
+            const checkpoint = await Checkpoint.random(checkpointNum, {
+                numBlocks: blocksPerCheckpoint,
+                startBlockNumber: startBlockNum,
+                slotNumber,
+                checkpointNumber: checkpointNum
+            });
+            this.checkpointList.push(checkpoint);
+            this.l2Blocks.push(...checkpoint.blocks);
+        }
+        this.log.verbose(`Created ${numCheckpoints} checkpoints with ${blocksPerCheckpoint} blocks each in the mock L2 block source`);
+    }
+    addProposedBlocks(blocks) {
         this.l2Blocks.push(...blocks);
-        this.log.verbose(`Added ${blocks.length} blocks to the mock L2 block source`);
+        this.log.verbose(`Added ${blocks.length} proposed blocks to the mock L2 block source`);
     }
     removeBlocks(numBlocks) {
         this.l2Blocks = this.l2Blocks.slice(0, -numBlocks);
+        const maxBlockNum = this.l2Blocks.length;
+        // Remove any checkpoint whose last block is beyond the remaining blocks.
+        this.checkpointList = this.checkpointList.filter((c)=>{
+            const lastBlockNum = c.blocks[0].number + c.blocks.length - 1;
+            return lastBlockNum <= maxBlockNum;
+        });
+        // Keep tip numbers consistent with remaining blocks.
+        this.checkpointedBlockNumber = Math.min(this.checkpointedBlockNumber, maxBlockNum);
+        this.proposedCheckpointBlockNumber = Math.min(this.proposedCheckpointBlockNumber, maxBlockNum);
+        this.provenBlockNumber = Math.min(this.provenBlockNumber, maxBlockNum);
+        this.finalizedBlockNumber = Math.min(this.finalizedBlockNumber, maxBlockNum);
         this.log.verbose(`Removed ${numBlocks} blocks from the mock L2 block source`);
     }
     setProvenBlockNumber(provenBlockNumber) {
         this.provenBlockNumber = provenBlockNumber;
     }
+    setFinalizedBlockNumber(finalizedBlockNumber) {
+        if (finalizedBlockNumber > this.provenBlockNumber) {
+            this.provenBlockNumber = finalizedBlockNumber;
+        }
+        this.finalizedBlockNumber = finalizedBlockNumber;
+    }
+    setProposedCheckpointBlockNumber(blockNumber) {
+        this.proposedCheckpointBlockNumber = blockNumber;
+    }
+    setCheckpointedBlockNumber(checkpointedBlockNumber) {
+        const prevCheckpointed = this.checkpointedBlockNumber;
+        this.checkpointedBlockNumber = checkpointedBlockNumber;
+        // Proposed checkpoint is always at least as advanced as checkpointed
+        if (this.proposedCheckpointBlockNumber < checkpointedBlockNumber) {
+            this.proposedCheckpointBlockNumber = checkpointedBlockNumber;
+        }
+        // Auto-create single-block checkpoints for newly checkpointed blocks that don't have one yet.
+        // This handles blocks added via addProposedBlocks that are now being marked as checkpointed.
+        const newCheckpoints = [];
+        for(let blockNum = prevCheckpointed + 1; blockNum <= checkpointedBlockNumber; blockNum++){
+            const block = this.l2Blocks[blockNum - 1];
+            if (!block) {
+                continue;
+            }
+            if (this.checkpointList.some((c)=>c.blocks.some((b)=>b.number === block.number))) {
+                continue;
+            }
+            const checkpointNum = CheckpointNumber(this.checkpointList.length + newCheckpoints.length + 1);
+            const checkpoint = new Checkpoint(block.archive, CheckpointHeader.random({
+                slotNumber: block.header.globalVariables.slotNumber
+            }), [
+                block
+            ], checkpointNum);
+            newCheckpoints.push(checkpoint);
+        }
+        // Insert new checkpoints in order by number.
+        if (newCheckpoints.length > 0) {
+            this.checkpointList.push(...newCheckpoints);
+            this.checkpointList.sort((a, b)=>a.number - b.number);
+        }
+    }
     /**
    * Method to fetch the rollup contract address at the base-layer.
    * @returns The rollup address.
@@ -41,48 +159,97 @@ import { TxReceipt, TxStatus } from '@aztec/stdlib/tx';
    */ getRegistryAddress() {
         return Promise.resolve(EthAddress.random());
     }
-    /**
-   * Gets the number of the latest L2 block processed by the block source implementation.
-   * @returns In this mock instance, returns the number of L2 blocks that we've mocked.
-   */ getBlockNumber() {
-        return Promise.resolve(this.l2Blocks.length);
+    async getBlockNumber(query) {
+        if (!query) {
+            return BlockNumber(this.l2Blocks.length);
+        }
+        if ('number' in query) {
+            return query.number;
+        }
+        if ('tag' in query) {
+            return BlockNumber(this.resolveBlockTag(query.tag));
+        }
+        const block = await this.getBlock(query);
+        return block ? block.header.globalVariables.blockNumber : undefined;
     }
-    getProvenBlockNumber() {
-        return Promise.resolve(this.provenBlockNumber);
+    getProposedCheckpointL2BlockNumber() {
+        return Promise.resolve(BlockNumber(this.proposedCheckpointBlockNumber));
     }
-    /**
-   * Gets an l2 block.
-   * @param number - The block number to return (inclusive).
-   * @returns The requested L2 block.
-   */ getBlock(number) {
-        return Promise.resolve(this.l2Blocks[number - 1]);
+    getCheckpoint(query) {
+        const checkpoint = this.resolveCheckpointQuery(query);
+        if (!checkpoint) {
+            return Promise.resolve(undefined);
+        }
+        return Promise.resolve(new PublishedCheckpoint(checkpoint, this.mockL1DataForCheckpoint(checkpoint), []));
     }
-    /**
-   * Gets up to `limit` amount of L2 blocks starting from `from`.
-   * @param from - Number of the first block to return (inclusive).
-   * @param limit - The maximum number of blocks to return.
-   * @returns The requested mocked L2 blocks.
-   */ getBlocks(from, limit, proven) {
-        return Promise.resolve(this.l2Blocks.slice(from - 1, from - 1 + limit).filter((b)=>!proven || this.provenBlockNumber === undefined || b.number <= this.provenBlockNumber));
+    getCheckpoints(query) {
+        const checkpoints = this.resolveCheckpointsQuery(query);
+        return Promise.resolve(checkpoints.map((checkpoint)=>new PublishedCheckpoint(checkpoint, this.mockL1DataForCheckpoint(checkpoint), [])));
     }
-    getBlockHeader(number) {
-        return Promise.resolve(this.l2Blocks.at(typeof number === 'number' ? number - 1 : -1)?.header);
+    getCheckpointByArchive(archive) {
+        const checkpoint = this.checkpointList.find((c)=>c.archive.root.equals(archive));
+        return Promise.resolve(checkpoint);
     }
-    getBlocksForEpoch(epochNumber) {
-        const epochDuration = DefaultL1ContractsConfig.aztecEpochDuration;
-        const [start, end] = getSlotRangeForEpoch(epochNumber, {
-            epochDuration
-        });
-        const blocks = this.l2Blocks.filter((b)=>{
-            const slot = b.header.globalVariables.slotNumber.toBigInt();
-            return slot >= start && slot <= end;
-        });
+    getCheckpointData(query) {
+        const checkpoint = this.resolveCheckpointQuery(query);
+        if (!checkpoint) {
+            return Promise.resolve(undefined);
+        }
+        return Promise.resolve(this.checkpointToData(checkpoint));
+    }
+    getCheckpointsData(query) {
+        const checkpoints = this.resolveCheckpointsQuery(query);
+        return Promise.resolve(checkpoints.map((c)=>this.checkpointToData(c)));
+    }
+    checkpointToData(checkpoint) {
+        return {
+            checkpointNumber: checkpoint.number,
+            header: checkpoint.header,
+            archive: checkpoint.archive,
+            checkpointOutHash: computeCheckpointOutHash(checkpoint.blocks.map((b)=>b.body.txEffects.map((tx)=>tx.l2ToL1Msgs))),
+            startBlock: checkpoint.blocks[0].number,
+            blockCount: checkpoint.blocks.length,
+            feeAssetPriceModifier: checkpoint.feeAssetPriceModifier,
+            attestations: [],
+            l1: this.mockL1DataForCheckpoint(checkpoint)
+        };
+    }
+    resolveCheckpointQuery(query) {
+        if ('number' in query) {
+            return this.checkpointList[query.number - 1];
+        }
+        if ('slot' in query) {
+            return this.checkpointList.find((c)=>c.header.slotNumber === query.slot);
+        }
+        switch(query.tag){
+            case 'checkpointed':
+                return this.checkpointList[this.checkpointList.length - 1];
+            case 'proven':
+                {
+                    const provenCheckpoint = this.checkpointList.filter((c)=>c.blocks.some((b)=>b.number <= this.provenBlockNumber));
+                    return provenCheckpoint.at(-1);
+                }
+            case 'finalized':
+                {
+                    const finalizedCheckpoint = this.checkpointList.filter((c)=>c.blocks.some((b)=>b.number <= this.finalizedBlockNumber));
+                    return finalizedCheckpoint.at(-1);
+                }
+        }
+    }
+    resolveCheckpointsQuery(query) {
+        if ('from' in query) {
+            return this.checkpointList.slice(query.from - 1, query.from - 1 + query.limit);
+        }
+        return this.getCheckpointsInEpoch(query.epoch);
+    }
+    getBlocksForSlot(slotNumber) {
+        const blocks = this.l2Blocks.filter((b)=>b.header.globalVariables.slotNumber === slotNumber);
         return Promise.resolve(blocks);
     }
     /**
    * Gets a tx effect.
-   * @param txHash - The hash of a transaction which resulted in the returned tx effect.
-   * @returns The requested tx effect.
+   * @param txHash - The hash of the tx corresponding to the tx effect.
+   * @returns The requested tx effect with block info (or undefined if not found).
    */ async getTxEffect(txHash) {
         const match = this.l2Blocks.flatMap((b)=>b.body.txEffects.map((tx)=>[
                     tx,
@@ -95,69 +262,242 @@ import { TxReceipt, TxStatus } from '@aztec/stdlib/tx';
         return {
             data: txEffect,
             l2BlockNumber: block.number,
-            l2BlockHash: (await block.hash()).toString()
+            l2BlockHash: await block.hash(),
+            txIndexInBlock: block.body.txEffects.findIndex((t)=>t.txHash.equals(txHash)),
+            slotNumber: block.header.globalVariables.slotNumber
         };
     }
-    /**
-   * Gets a receipt of a settled tx.
-   * @param txHash - The hash of a tx we try to get the receipt for.
-   * @returns The requested tx receipt (or undefined if not found).
-   */ async getSettledTxReceipt(txHash) {
-        for (const block of this.l2Blocks){
-            for (const txEffect of block.body.txEffects){
-                if (txEffect.txHash.equals(txHash)) {
-                    return new TxReceipt(txHash, TxStatus.SUCCESS, '', txEffect.transactionFee.toBigInt(), L2BlockHash.fromField(await block.hash()), block.number);
-                }
-            }
-        }
-        return undefined;
+    getL2ToL1MembershipWitness() {
+        // Mock does not back the L2-to-L1 message witness flow.
+        return Promise.resolve(undefined);
     }
     async getL2Tips() {
-        const [latest, proven, finalized] = [
+        const [latest, proven, finalized, checkpointed, proposedCheckpoint] = [
             await this.getBlockNumber(),
-            await this.getProvenBlockNumber(),
-            await this.getProvenBlockNumber()
+            this.provenBlockNumber,
+            this.finalizedBlockNumber,
+            this.checkpointedBlockNumber,
+            await this.getProposedCheckpointL2BlockNumber()
         ];
         const latestBlock = this.l2Blocks[latest - 1];
         const provenBlock = this.l2Blocks[proven - 1];
         const finalizedBlock = this.l2Blocks[finalized - 1];
-        return {
-            latest: {
-                number: latest,
-                hash: (await latestBlock?.hash())?.toString()
-            },
-            proven: {
-                number: proven,
-                hash: (await provenBlock?.hash())?.toString()
-            },
-            finalized: {
-                number: finalized,
-                hash: (await finalizedBlock?.hash())?.toString()
+        const checkpointedBlock = this.l2Blocks[checkpointed - 1];
+        const proposedCheckpointBlock = this.l2Blocks[proposedCheckpoint - 1];
+        // For genesis tips (block number 0) report the dynamic initial header hash so consumers
+        // running L2BlockStream against this mock agree at block 0 with their local tip store.
+        const genesisHash = (await this.initialHeader.hash()).toString();
+        const tipHash = async (block, number)=>{
+            if (block) {
+                return (await block.hash()).toString();
             }
+            return number === 0 ? genesisHash : '';
+        };
+        const latestBlockId = {
+            number: BlockNumber(latest),
+            hash: await tipHash(latestBlock, latest)
+        };
+        const provenBlockId = {
+            number: BlockNumber(proven),
+            hash: await tipHash(provenBlock, proven)
+        };
+        const finalizedBlockId = {
+            number: BlockNumber(finalized),
+            hash: await tipHash(finalizedBlock, finalized)
+        };
+        const checkpointedBlockId = {
+            number: BlockNumber(checkpointed),
+            hash: await tipHash(checkpointedBlock, checkpointed)
+        };
+        const proposedCheckpointBlockId = {
+            number: BlockNumber(proposedCheckpoint),
+            hash: await tipHash(proposedCheckpointBlock, proposedCheckpoint)
+        };
+        const makeTipId = (blockId)=>{
+            const checkpointNumber = this.findCheckpointNumberForBlock(blockId.number) ?? CheckpointNumber(0);
+            // Match production semantics: checkpoint 0 is fully synthetic (no real checkpoint header
+            // exists at 0), so its hash stays at the protocol constant `GENESIS_CHECKPOINT_HEADER_HASH`
+            // even though the block-0 hash is dynamic. See L2TipsCache for the production path.
+            const hash = checkpointNumber === 0 ? GENESIS_CHECKPOINT_HEADER_HASH.toString() : blockId.hash;
+            return {
+                block: blockId,
+                checkpoint: {
+                    number: checkpointNumber,
+                    hash
+                }
+            };
+        };
+        return {
+            proposed: latestBlockId,
+            checkpointed: makeTipId(checkpointedBlockId),
+            proven: makeTipId(provenBlockId),
+            finalized: makeTipId(finalizedBlockId),
+            proposedCheckpoint: makeTipId(proposedCheckpointBlockId)
         };
     }
-    getL2EpochNumber() {
+    getSyncedL2EpochNumber() {
         throw new Error('Method not implemented.');
     }
-    getL2SlotNumber() {
+    getSyncedL2SlotNumber() {
         throw new Error('Method not implemented.');
     }
     isEpochComplete(_epochNumber) {
         throw new Error('Method not implemented.');
     }
     getL1Constants() {
+        return Promise.resolve(EmptyL1RollupConstants);
+    }
+    isPruneDueAtSlot(_slot) {
+        return Promise.resolve(false);
+    }
+    getGenesisValues() {
+        return Promise.resolve({
+            genesisArchiveRoot: this.genesisArchiveRoot ?? new Fr(GENESIS_ARCHIVE_ROOT)
+        });
+    }
+    getL1Timestamp() {
         throw new Error('Method not implemented.');
     }
     /**
    * Starts the block source. In this mock implementation, this is a noop.
    * @returns A promise that signals the initialization of the l2 block source on completion.
    */ start() {
+        this.log.verbose('Starting mock L2 block source');
         return Promise.resolve();
     }
     /**
    * Stops the block source. In this mock implementation, this is a noop.
    * @returns A promise that signals the l2 block source is now stopped.
    */ stop() {
+        this.log.verbose('Stopping mock L2 block source');
         return Promise.resolve();
     }
+    getContractClass(_id) {
+        return Promise.resolve(undefined);
+    }
+    getBytecodeCommitment(_id) {
+        return Promise.resolve(undefined);
+    }
+    getContract(_address, _timestamp) {
+        return Promise.resolve(undefined);
+    }
+    getContractClassIds() {
+        return Promise.resolve([]);
+    }
+    getDebugFunctionName(_address, _selector) {
+        return Promise.resolve(undefined);
+    }
+    registerContractFunctionSignatures(_signatures) {
+        return Promise.resolve();
+    }
+    syncImmediate() {
+        return Promise.resolve();
+    }
+    async getBlock(query) {
+        if ('number' in query) {
+            if (query.number === 0) {
+                return this.getGenesisBlock();
+            }
+            return this.l2Blocks[query.number - 1];
+        }
+        if ('hash' in query) {
+            const genesis = this.getGenesisBlock();
+            if ((await genesis.hash()).equals(query.hash)) {
+                return genesis;
+            }
+            for (const b of this.l2Blocks){
+                const hash = await b.hash();
+                if (hash.equals(query.hash)) {
+                    return b;
+                }
+            }
+            return undefined;
+        }
+        if ('archive' in query) {
+            const genesis = this.getGenesisBlock();
+            if (genesis.archive.root.equals(query.archive)) {
+                return genesis;
+            }
+            return this.l2Blocks.find((b)=>b.archive.root.equals(query.archive));
+        }
+        const number = this.resolveBlockTag(query.tag);
+        if (number === 0) {
+            return this.getGenesisBlock();
+        }
+        return this.l2Blocks[number - 1];
+    }
+    resolveBlockTag(tag) {
+        switch(tag){
+            case 'latest':
+            case 'proposed':
+                return this.l2Blocks.length;
+            case 'checkpointed':
+                return this.checkpointedBlockNumber;
+            case 'proven':
+                return this.provenBlockNumber;
+            case 'finalized':
+                return this.finalizedBlockNumber;
+        }
+    }
+    getBlocks(query) {
+        let blocks;
+        if ('from' in query) {
+            blocks = this.l2Blocks.slice(query.from - 1, query.from - 1 + query.limit);
+        } else {
+            const epochCheckpoints = this.getCheckpointsInEpoch(query.epoch);
+            blocks = epochCheckpoints.flatMap((c)=>c.blocks);
+        }
+        if (query.onlyCheckpointed) {
+            blocks = blocks.filter((b)=>b.header.globalVariables.blockNumber <= this.checkpointedBlockNumber);
+        }
+        return Promise.resolve(blocks);
+    }
+    async getBlockData(query) {
+        const block = await this.getBlock(query);
+        if (!block) {
+            return undefined;
+        }
+        return {
+            header: block.header,
+            archive: block.archive,
+            blockHash: await block.hash(),
+            checkpointNumber: block.checkpointNumber,
+            indexWithinCheckpoint: block.indexWithinCheckpoint
+        };
+    }
+    async getBlocksData(query) {
+        const blocks = await this.getBlocks(query);
+        return Promise.all(blocks.map(async (block)=>({
+                header: block.header,
+                archive: block.archive,
+                blockHash: await block.hash(),
+                checkpointNumber: block.checkpointNumber,
+                indexWithinCheckpoint: block.indexWithinCheckpoint
+            })));
+    }
+    isPendingChainInvalid() {
+        return Promise.resolve(false);
+    }
+    getPendingChainValidationStatus() {
+        return Promise.resolve({
+            valid: true
+        });
+    }
+    getProposedCheckpointData(_query) {
+        return Promise.resolve(undefined);
+    }
+    /** Returns checkpoints whose slot falls within the given epoch. */ getCheckpointsInEpoch(epochNumber) {
+        const epochDuration = DefaultL1ContractsConfig.aztecEpochDuration;
+        const [start, end] = getSlotRangeForEpoch(epochNumber, {
+            epochDuration
+        });
+        return this.checkpointList.filter((c)=>c.header.slotNumber >= start && c.header.slotNumber <= end);
+    }
+    /** Creates a mock L1PublishedData for a checkpoint. */ mockL1DataForCheckpoint(checkpoint) {
+        return new L1PublishedData(BigInt(checkpoint.number), BigInt(checkpoint.number), Buffer32.random().toString());
+    }
+    /** Finds the checkpoint number for a block, or undefined if the block is not in any checkpoint. */ findCheckpointNumberForBlock(blockNumber) {
+        const checkpoint = this.checkpointList.find((c)=>c.blocks.some((b)=>b.number === blockNumber));
+        return checkpoint?.number;
+    }
 }

package/dest/test/mock_structs.d.ts

@@ -0,0 +1,88 @@
+import { CheckpointNumber } from '@aztec/foundation/branded-types';
+import { Buffer16 } from '@aztec/foundation/buffer';
+import type { Secp256k1Signer } from '@aztec/foundation/crypto/secp256k1-signer';
+import { EthAddress } from '@aztec/foundation/eth-address';
+import { AztecAddress } from '@aztec/stdlib/aztec-address';
+import { L2Block } from '@aztec/stdlib/block';
+import { Checkpoint, L1PublishedData, PublishedCheckpoint } from '@aztec/stdlib/checkpoint';
+import { PrivateLog, PublicLog, SiloedTag, Tag } from '@aztec/stdlib/logs';
+import { AppendOnlyTreeSnapshot } from '@aztec/stdlib/trees';
+import { StateReference } from '@aztec/stdlib/tx';
+import { type InboxMessage } from '../structs/inbox_message.js';
+export declare function makeInboxMessage(previousRollingHash?: Buffer16, overrides?: Partial<InboxMessage>): InboxMessage;
+export declare function makeInboxMessages(totalCount: number, opts?: {
+    initialHash?: Buffer16;
+    initialCheckpointNumber?: CheckpointNumber;
+    messagesPerCheckpoint?: number;
+    overrideFn?: (msg: InboxMessage, index: number) => InboxMessage;
+}): InboxMessage[];
+/** Creates inbox messages distributed across multiple blocks with proper checkpoint numbering. */
+export declare function makeInboxMessagesWithFullBlocks(blockCount: number, opts?: {
+    initialCheckpointNumber?: CheckpointNumber;
+}): InboxMessage[];
+/** Creates a deterministic block hash from a block number. */
+export declare function makeBlockHash(blockNumber: number): `0x${string}`;
+/**
+ * Creates a StateReference with properly calculated noteHashTree.nextAvailableLeafIndex.
+ * This ensures LogStore's dataStartIndexForBlock calculation doesn't produce negative values.
+ */
+export declare function makeStateForBlock(blockNumber: number, txsPerBlock: number): StateReference;
+/** Creates L1PublishedData with deterministic values based on l1BlockNumber. */
+export declare function makeL1PublishedData(l1BlockNumber: number): L1PublishedData;
+/** Creates a Checkpoint from a list of blocks with a header that matches the blocks' structure. */
+export declare function makeCheckpoint(blocks: L2Block[], checkpointNumber?: CheckpointNumber): Checkpoint;
+/** Wraps a Checkpoint with L1 published data and random attestations. */
+export declare function makePublishedCheckpoint(checkpoint: Checkpoint, l1BlockNumber: number, attestationCount?: number): PublishedCheckpoint;
+export interface MakeChainedCheckpointsOptions {
+    /** Number of L2 blocks per checkpoint. Default: 1 */
+    blocksPerCheckpoint?: number;
+    /** Number of transactions per block. Default: 4 */
+    txsPerBlock?: number;
+    /** Starting checkpoint number. Default: CheckpointNumber(1) */
+    startCheckpointNumber?: CheckpointNumber;
+    /** Starting block number. Default: 1 */
+    startBlockNumber?: number;
+    /** Starting L1 block number. Default: 10 */
+    startL1BlockNumber?: number;
+    /** Previous archive to chain from. Default: undefined */
+    previousArchive?: AppendOnlyTreeSnapshot;
+    /** Optional function to provide per-checkpoint overrides */
+    makeCheckpointOptions?: (cpNumber: CheckpointNumber) => Partial<Parameters<typeof Checkpoint.random>[1]>;
+}
+/**
+ * Creates multiple checkpoints with properly chained archives.
+ * Each checkpoint's blocks have their lastArchive set to the previous block's archive,
+ * ensuring archive chain continuity for testing.
+ */
+export declare function makeChainedCheckpoints(count: number, options?: MakeChainedCheckpointsOptions): Promise<PublishedCheckpoint[]>;
+/**
+ * Creates a PublishedCheckpoint with attestations signed by the provided signers.
+ * Useful for testing attestation validation.
+ */
+export declare function makeSignedPublishedCheckpoint(checkpoint: Checkpoint, signers: Secp256k1Signer[], committee: EthAddress[], l1BlockNumber?: number): PublishedCheckpoint;
+/** Creates a deterministic SiloedTag for private log testing. */
+export declare function makePrivateLogTag(blockNumber: number, txIndex: number, logIndex: number): SiloedTag;
+/** Creates a PrivateLog with fields derived from the tag. */
+export declare function makePrivateLog(tag: SiloedTag): PrivateLog;
+/** Creates multiple private logs for a transaction. */
+export declare function mockPrivateLogs(blockNumber: number, txIndex: number, numLogsPerTx: number): PrivateLog[];
+/** Creates a deterministic Tag for public log testing. */
+export declare function makePublicLogTag(blockNumber: number, txIndex: number, logIndex: number): Tag;
+/** Creates a PublicLog with fields derived from the tag. */
+export declare function makePublicLog(tag: Tag, contractAddress?: AztecAddress): PublicLog;
+/** Creates multiple public logs for a transaction. */
+export declare function makePublicLogs(blockNumber: number, txIndex: number, numLogsPerTx: number, contractAddress?: AztecAddress): PublicLog[];
+export interface MockCheckpointWithLogsOptions {
+    previousArchive?: AppendOnlyTreeSnapshot;
+    numTxsPerBlock?: number;
+    privateLogs?: {
+        numLogsPerTx: number;
+    };
+    publicLogs?: {
+        numLogsPerTx: number;
+        contractAddress?: AztecAddress;
+    };
+}
+/** Creates a checkpoint with specified logs on each tx effect. */
+export declare function makeCheckpointWithLogs(blockNumber: number, options?: MockCheckpointWithLogsOptions): Promise<PublishedCheckpoint>;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoibW9ja19zdHJ1Y3RzLmQudHMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvdGVzdC9tb2NrX3N0cnVjdHMudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBTUEsT0FBTyxFQUFlLGdCQUFnQixFQUF5QixNQUFNLGlDQUFpQyxDQUFDO0FBQ3ZHLE9BQU8sRUFBRSxRQUFRLEVBQVksTUFBTSwwQkFBMEIsQ0FBQztBQUc5RCxPQUFPLEtBQUssRUFBRSxlQUFlLEVBQUUsTUFBTSwyQ0FBMkMsQ0FBQztBQUVqRixPQUFPLEVBQUUsVUFBVSxFQUFFLE1BQU0sK0JBQStCLENBQUM7QUFDM0QsT0FBTyxFQUFFLFlBQVksRUFBRSxNQUFNLDZCQUE2QixDQUFDO0FBQzNELE9BQU8sRUFBd0IsT0FBTyxFQUFFLE1BQU0scUJBQXFCLENBQUM7QUFDcEUsT0FBTyxFQUFFLFVBQVUsRUFBRSxlQUFlLEVBQUUsbUJBQW1CLEVBQUUsTUFBTSwwQkFBMEIsQ0FBQztBQUM1RixPQUFPLEVBQUUsVUFBVSxFQUFFLFNBQVMsRUFBRSxTQUFTLEVBQUUsR0FBRyxFQUFFLE1BQU0sb0JBQW9CLENBQUM7QUFLM0UsT0FBTyxFQUFFLHNCQUFzQixFQUFFLE1BQU0scUJBQXFCLENBQUM7QUFDN0QsT0FBTyxFQUF5QixjQUFjLEVBQVksTUFBTSxrQkFBa0IsQ0FBQztBQUVuRixPQUFPLEVBQUUsS0FBSyxZQUFZLEVBQXFCLE1BQU0sNkJBQTZCLENBQUM7QUFFbkYsd0JBQWdCLGdCQUFnQixDQUM5QixtQkFBbUIsV0FBZ0IsRUFDbkMsU0FBUyxHQUFFLE9BQU8sQ0FBQyxZQUFZLENBQU0sR0FDcEMsWUFBWSxDQWdCZDtBQUVELHdCQUFnQixpQkFBaUIsQ0FDL0IsVUFBVSxFQUFFLE1BQU0sRUFDbEIsSUFBSSxHQUFFO0lBQ0osV0FBVyxDQUFDLEVBQUUsUUFBUSxDQUFDO0lBQ3ZCLHVCQUF1QixDQUFDLEVBQUUsZ0JBQWdCLENBQUM7SUFDM0MscUJBQXFCLENBQUMsRUFB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