@aztec/archiver 0.0.1-commit.96dac018d → 0.0.1-commit.993d240

package/dest/modules/data_source_base.js

@@ -1,216 +1,351 @@
-import { range } from '@aztec/foundation/array';
-import { BlockNumber } from '@aztec/foundation/branded-types';
-import { isDefined } from '@aztec/foundation/types';
+import { INITIAL_L2_BLOCK_NUM } from '@aztec/constants';
+import { BlockNumber, CheckpointNumber, IndexWithinCheckpoint } from '@aztec/foundation/branded-types';
+import { Body, L2Block } from '@aztec/stdlib/block';
 import { Checkpoint, PublishedCheckpoint } from '@aztec/stdlib/checkpoint';
-import { getSlotRangeForEpoch } from '@aztec/stdlib/epoch-helpers';
+import { getEpochAtSlot, getEpochNumberAtTimestamp, getLastL1SlotTimestampForL2Slot, getProofSubmissionDeadlineEpoch, getSlotRangeForEpoch } from '@aztec/stdlib/epoch-helpers';
+import { AppendOnlyTreeSnapshot } from '@aztec/stdlib/trees';
 /**
- * Abstract base class implementing ArchiverDataSource using a KVArchiverDataStore.
- * Provides implementations for all store-delegating methods and declares abstract methods
- * for L1-dependent functionality that subclasses must implement.
+ * Abstract base class implementing ArchiverDataSource using a bundle of archiver substores.
+ * Provides implementations for all read-side methods and declares abstract methods for
+ * L1-dependent functionality that subclasses must implement.
  */ export class ArchiverDataSourceBase {
-    store;
+    stores;
     l1Constants;
-    constructor(store, l1Constants){
-        this.store = store;
+    /** The injected genesis block header. */ initialHeader;
+    /** Precomputed hash of the initial header, exposed via {@link getGenesisBlockHash}. */ initialBlockHash;
+    /** Archive root after block 0 was appended — read from L1 (`Rollup.getGenesisArchiveTreeRoot`). */ genesisArchiveRoot;
+    /** Memoized synthetic genesis block — callers rely on referential identity for caching. */ genesisBlock;
+    /** Memoized synthetic genesis block data — kept consistent with {@link genesisBlock}. */ genesisBlockData;
+    constructor(stores, l1Constants, initialHeader, initialBlockHash, genesisArchiveRoot){
+        this.stores = stores;
         this.l1Constants = l1Constants;
+        this.initialHeader = initialHeader;
+        this.initialBlockHash = initialBlockHash;
+        this.genesisArchiveRoot = genesisArchiveRoot;
+        const genesisArchive = new AppendOnlyTreeSnapshot(genesisArchiveRoot, 1);
+        this.genesisBlock = new L2Block(genesisArchive, initialHeader, Body.empty(), CheckpointNumber.ZERO, IndexWithinCheckpoint(0));
+        this.genesisBlockData = {
+            header: initialHeader,
+            archive: genesisArchive,
+            blockHash: initialBlockHash,
+            checkpointNumber: CheckpointNumber.ZERO,
+            indexWithinCheckpoint: IndexWithinCheckpoint(0)
+        };
     }
-    getCheckpointNumber() {
-        return this.store.getSynchedCheckpointNumber();
-    }
-    getSynchedCheckpointNumber() {
-        return this.store.getSynchedCheckpointNumber();
+    /** Returns the precomputed hash of the genesis block header. */ getGenesisBlockHash() {
+        return this.initialBlockHash;
     }
-    getProvenCheckpointNumber() {
-        return this.store.getProvenCheckpointNumber();
+    /** Returns the synthetic genesis L2Block (memoized — same instance across calls). */ getGenesisBlock() {
+        return this.genesisBlock;
     }
-    getBlockNumber() {
-        return this.store.getLatestBlockNumber();
+    /** Returns genesis block data (memoized — same instance across calls). */ getGenesisBlockData() {
+        return this.genesisBlockData;
     }
-    getProvenBlockNumber() {
-        return this.store.getProvenBlockNumber();
+    /**
+   * Type guard distinguishing the genesis sentinel from a {@link ResolvedBlockQuery}.
+   * `resolveBlockQuery` already rewrites every genesis-matching shape to the sentinel,
+   * so callers only need this single sync check.
+   */ isGenesisBlockQuery(query) {
+        return 'genesis' in query;
     }
-    async getBlockHeader(number) {
-        const blockNumber = number === 'latest' ? await this.store.getLatestBlockNumber() : number;
-        if (blockNumber === 0) {
-            return undefined;
+    async isPruneDueAtSlot(slot) {
+        if (!this.l1Constants) {
+            throw new Error('isPruneDueAtSlot requires l1Constants');
         }
-        const headers = await this.store.getBlockHeaders(blockNumber, 1);
-        return headers.length === 0 ? undefined : headers[0];
-    }
-    getCheckpointedBlock(number) {
-        return this.store.getCheckpointedBlock(number);
+        const tips = await this.getL2Tips();
+        const proven = tips.proven.checkpoint.number;
+        const pending = tips.checkpointed.checkpoint.number;
+        if (pending === proven) {
+            return false;
+        }
+        const oldestUnproven = await this.getCheckpointData({
+            number: CheckpointNumber(Number(proven) + 1)
+        });
+        if (!oldestUnproven) {
+            return false;
+        }
+        const slotTs = getLastL1SlotTimestampForL2Slot(slot, this.l1Constants);
+        const slotEpoch = getEpochNumberAtTimestamp(slotTs, this.l1Constants);
+        const oldestUnprovenEpoch = getEpochAtSlot(oldestUnproven.header.slotNumber, this.l1Constants);
+        const deadlineEpoch = getProofSubmissionDeadlineEpoch(oldestUnprovenEpoch, this.l1Constants);
+        return slotEpoch >= deadlineEpoch;
     }
-    getCheckpointedL2BlockNumber() {
-        return this.store.getCheckpointedL2BlockNumber();
+    getCheckpointNumber() {
+        return this.stores.blocks.getLatestCheckpointNumber();
     }
-    getFinalizedL2BlockNumber() {
-        return this.store.getFinalizedL2BlockNumber();
+    getProvenCheckpointNumber() {
+        return this.stores.blocks.getProvenCheckpointNumber();
     }
-    async getCheckpointHeader(number) {
-        if (number === 'latest') {
-            number = await this.store.getSynchedCheckpointNumber();
+    async getBlockNumber(query) {
+        if (!query) {
+            return this.stores.blocks.getLatestL2BlockNumber();
         }
-        if (number === 0) {
+        const resolved = await this.resolveBlockQuery(query);
+        if (resolved === undefined) {
             return undefined;
         }
-        const checkpoint = await this.store.getCheckpointData(number);
-        if (!checkpoint) {
-            return undefined;
+        if (this.isGenesisBlockQuery(resolved)) {
+            return BlockNumber.ZERO;
+        }
+        return this.stores.blocks.getBlockNumber(resolved);
+    }
+    /**
+   * Resolves a {@link CheckpointQuery} to a concrete `CheckpointNumber`, or undefined when the
+   * query refers to a position that has no checkpoint yet (e.g. `{ slot }` not found).
+   */ resolveCheckpointQuery(query) {
+        if ('number' in query) {
+            return Promise.resolve(query.number);
+        }
+        if ('slot' in query) {
+            return this.stores.blocks.getCheckpointNumberBySlot(query.slot);
+        }
+        // tag variant
+        switch(query.tag){
+            case 'checkpointed':
+                return this.stores.blocks.getLatestCheckpointNumber();
+            case 'proven':
+                return this.stores.blocks.getProvenCheckpointNumber();
+            case 'finalized':
+                return this.stores.blocks.getFinalizedCheckpointNumber();
         }
-        return checkpoint.header;
     }
-    async getLastBlockNumberInCheckpoint(checkpointNumber) {
-        const checkpointData = await this.store.getCheckpointData(checkpointNumber);
-        if (!checkpointData) {
+    /**
+   * Resolves a {@link CheckpointsQuery} to a concrete `{from, limit}` pair used by BlockStore,
+   * or undefined when the epoch has no checkpoints.
+   */ async resolveCheckpointsQuery(query) {
+        if ('from' in query) {
+            return query;
+        }
+        const numbers = await this.getCheckpointNumbersForEpoch(query.epoch);
+        if (numbers.length === 0) {
             return undefined;
         }
-        return BlockNumber(checkpointData.startBlock + checkpointData.blockCount - 1);
-    }
-    getCheckpointedBlocks(from, limit) {
-        return this.store.getCheckpointedBlocks(from, limit);
+        return {
+            from: numbers[0],
+            limit: numbers.length
+        };
     }
-    getBlockHeaderByHash(blockHash) {
-        return this.store.getBlockHeaderByHash(blockHash);
+    async getCheckpoint(query) {
+        const number = await this.resolveCheckpointQuery(query);
+        if (number === undefined || number === 0) {
+            return undefined;
+        }
+        const data = await this.stores.blocks.getCheckpointData(number);
+        if (!data) {
+            return undefined;
+        }
+        return this.getPublishedCheckpointFromCheckpointData(data);
     }
-    getBlockHeaderByArchive(archive) {
-        return this.store.getBlockHeaderByArchive(archive);
+    async getCheckpoints(query) {
+        const resolved = await this.resolveCheckpointsQuery(query);
+        if (!resolved) {
+            return [];
+        }
+        const checkpoints = await this.stores.blocks.getRangeOfCheckpoints(resolved.from, resolved.limit);
+        return Promise.all(checkpoints.map((ch)=>this.getPublishedCheckpointFromCheckpointData(ch)));
     }
-    getBlockData(number) {
-        return this.store.getBlockData(number);
+    async getCheckpointData(query) {
+        const number = await this.resolveCheckpointQuery(query);
+        if (number === undefined || number === 0) {
+            return undefined;
+        }
+        return this.stores.blocks.getCheckpointData(number);
     }
-    getBlockDataByArchive(archive) {
-        return this.store.getBlockDataByArchive(archive);
+    async getCheckpointsData(query) {
+        const resolved = await this.resolveCheckpointsQuery(query);
+        if (!resolved) {
+            return [];
+        }
+        return this.stores.blocks.getRangeOfCheckpoints(resolved.from, resolved.limit);
     }
-    async getL2Block(number) {
-        // If the number provided is -ve, then return the latest block.
-        if (number < 0) {
-            number = await this.store.getLatestBlockNumber();
+    getProposedCheckpointData(query) {
+        if (!query || 'tag' in query) {
+            return this.stores.blocks.getLastProposedCheckpoint();
         }
-        if (number === 0) {
-            return undefined;
+        if ('number' in query) {
+            return this.stores.blocks.getProposedCheckpointByNumber(query.number);
         }
-        const publishedBlock = await this.store.getBlock(number);
-        return publishedBlock;
+        return this.stores.blocks.getProposedCheckpointBySlot(query.slot);
     }
     getTxEffect(txHash) {
-        return this.store.getTxEffect(txHash);
+        return this.stores.blocks.getTxEffect(txHash);
     }
     getSettledTxReceipt(txHash) {
-        return this.store.getSettledTxReceipt(txHash);
+        return this.stores.blocks.getSettledTxReceipt(txHash, this.l1Constants);
     }
     isPendingChainInvalid() {
         return this.getPendingChainValidationStatus().then((status)=>!status.valid);
     }
     async getPendingChainValidationStatus() {
-        return await this.store.getPendingChainValidationStatus() ?? {
+        return await this.stores.blocks.getPendingChainValidationStatus() ?? {
             valid: true
         };
     }
-    getPrivateLogsByTags(tags, page) {
-        return this.store.getPrivateLogsByTags(tags, page);
+    getPrivateLogsByTags(query) {
+        return this.stores.logs.getPrivateLogsByTags(query);
     }
-    getPublicLogsByTagsFromContract(contractAddress, tags, page) {
-        return this.store.getPublicLogsByTagsFromContract(contractAddress, tags, page);
-    }
-    getPublicLogs(filter) {
-        return this.store.getPublicLogs(filter);
-    }
-    getContractClassLogs(filter) {
-        return this.store.getContractClassLogs(filter);
+    getPublicLogsByTags(query) {
+        return this.stores.logs.getPublicLogsByTags(query);
     }
     getContractClass(id) {
-        return this.store.getContractClass(id);
+        return this.stores.contractClasses.getContractClass(id);
     }
     getBytecodeCommitment(id) {
-        return this.store.getBytecodeCommitment(id);
+        return this.stores.contractClasses.getBytecodeCommitment(id);
     }
     async getContract(address, maybeTimestamp) {
         let timestamp;
         if (maybeTimestamp === undefined) {
-            const latestBlockHeader = await this.getBlockHeader('latest');
-            // If we get undefined block header, it means that the archiver has not yet synced any block so we default to 0.
-            timestamp = latestBlockHeader ? latestBlockHeader.globalVariables.timestamp : 0n;
+            const latestBlockData = await this.getBlockData({
+                tag: 'proposed'
+            });
+            timestamp = latestBlockData ? latestBlockData.header.globalVariables.timestamp : 0n;
         } else {
             timestamp = maybeTimestamp;
         }
-        return this.store.getContractInstance(address, timestamp);
+        return this.stores.contractInstances.getContractInstance(address, timestamp);
     }
     getContractClassIds() {
-        return this.store.getContractClassIds();
+        return this.stores.contractClasses.getContractClassIds();
     }
-    getDebugFunctionName(address, selector) {
-        return this.store.getDebugFunctionName(address, selector);
+    /** Looks up a public function name given a selector. */ getDebugFunctionName(_address, selector) {
+        return Promise.resolve(this.stores.functionNames.get(selector));
     }
-    registerContractFunctionSignatures(signatures) {
-        return this.store.registerContractFunctionSignatures(signatures);
+    /** Register public function signatures so they can be looked up by selector. */ registerContractFunctionSignatures(signatures) {
+        return this.stores.functionNames.register(signatures);
     }
     getL1ToL2Messages(checkpointNumber) {
-        return this.store.getL1ToL2Messages(checkpointNumber);
+        return this.stores.messages.getL1ToL2Messages(checkpointNumber);
     }
     getL1ToL2MessageIndex(l1ToL2Message) {
-        return this.store.getL1ToL2MessageIndex(l1ToL2Message);
-    }
-    async getCheckpoints(checkpointNumber, limit) {
-        const checkpoints = await this.store.getRangeOfCheckpoints(checkpointNumber, limit);
-        return Promise.all(checkpoints.map((ch)=>this.getPublishedCheckpointFromCheckpointData(ch)));
+        return this.stores.messages.getL1ToL2MessageIndex(l1ToL2Message);
     }
     async getPublishedCheckpointFromCheckpointData(checkpoint) {
-        const blocksForCheckpoint = await this.store.getBlocksForCheckpoint(checkpoint.checkpointNumber);
+        const blocksForCheckpoint = await this.stores.blocks.getBlocksForCheckpoint(checkpoint.checkpointNumber);
         if (!blocksForCheckpoint) {
             throw new Error(`Blocks for checkpoint ${checkpoint.checkpointNumber} not found`);
         }
-        const fullCheckpoint = new Checkpoint(checkpoint.archive, checkpoint.header, blocksForCheckpoint, checkpoint.checkpointNumber);
+        const fullCheckpoint = new Checkpoint(checkpoint.archive, checkpoint.header, blocksForCheckpoint, checkpoint.checkpointNumber, checkpoint.feeAssetPriceModifier);
         return new PublishedCheckpoint(fullCheckpoint, checkpoint.l1, checkpoint.attestations);
     }
     getBlocksForSlot(slotNumber) {
-        return this.store.getBlocksForSlot(slotNumber);
-    }
-    async getCheckpointedBlocksForEpoch(epochNumber) {
-        const checkpointsData = await this.getCheckpointsDataForEpoch(epochNumber);
-        const blocks = await Promise.all(checkpointsData.flatMap((checkpoint)=>range(checkpoint.blockCount, checkpoint.startBlock).map((blockNumber)=>this.getCheckpointedBlock(BlockNumber(blockNumber)))));
-        return blocks.filter(isDefined);
-    }
-    async getCheckpointedBlockHeadersForEpoch(epochNumber) {
-        const checkpointsData = await this.getCheckpointsDataForEpoch(epochNumber);
-        const blocks = await Promise.all(checkpointsData.flatMap((checkpoint)=>range(checkpoint.blockCount, checkpoint.startBlock).map((blockNumber)=>this.getBlockHeader(BlockNumber(blockNumber)))));
-        return blocks.filter(isDefined);
-    }
-    async getCheckpointsForEpoch(epochNumber) {
-        const checkpointsData = await this.getCheckpointsDataForEpoch(epochNumber);
-        return Promise.all(checkpointsData.map((data)=>this.getPublishedCheckpointFromCheckpointData(data).then((p)=>p.checkpoint)));
+        return this.stores.blocks.getBlocksForSlot(slotNumber);
     }
-    /** Returns checkpoint data for all checkpoints whose slot falls within the given epoch. */ getCheckpointsDataForEpoch(epochNumber) {
+    /** Returns just the checkpoint numbers for all checkpoints whose slot falls within the given epoch. */ getCheckpointNumbersForEpoch(epochNumber) {
         if (!this.l1Constants) {
             throw new Error('L1 constants not set');
         }
         const [start, end] = getSlotRangeForEpoch(epochNumber, this.l1Constants);
-        return this.store.getCheckpointDataForSlotRange(start, end);
+        return this.stores.blocks.getCheckpointNumbersForSlotRange(start, end);
     }
-    async getBlock(number) {
-        // If the number provided is -ve, then return the latest block.
-        if (number < 0) {
-            number = await this.store.getLatestBlockNumber();
+    async getBlock(query) {
+        const resolved = await this.resolveBlockQuery(query);
+        if (resolved === undefined) {
+            return undefined;
+        }
+        if (this.isGenesisBlockQuery(resolved)) {
+            return this.getGenesisBlock();
         }
-        if (number === 0) {
+        return this.stores.blocks.getBlock(resolved);
+    }
+    /**
+   * Range queries iterate physical blocks only; the genesis block is NOT prepended.
+   * `L2BlockStream` consumers (`world-state.handleL2Blocks`, etc.) emit `blocks-added` events for
+   * real blocks and would be surprised by a synthetic block 0. Use {@link getBlock} or
+   * {@link getBlockData} for genesis-aware single-block lookups.
+   */ async getBlocks(query) {
+        const resolved = await this.resolveBlocksQuery(query);
+        return resolved ? this.stores.blocks.getBlocks(resolved) : [];
+    }
+    async getBlockData(query) {
+        const resolved = await this.resolveBlockQuery(query);
+        if (resolved === undefined) {
             return undefined;
         }
-        return this.store.getBlock(number);
-    }
-    getBlocks(from, limit) {
-        return this.store.getBlocks(from, limit);
-    }
-    getCheckpointedBlockByHash(blockHash) {
-        return this.store.getCheckpointedBlockByHash(blockHash);
-    }
-    getCheckpointedBlockByArchive(archive) {
-        return this.store.getCheckpointedBlockByArchive(archive);
+        if (this.isGenesisBlockQuery(resolved)) {
+            return this.getGenesisBlockData();
+        }
+        return this.stores.blocks.getBlockData(resolved);
+    }
+    /** See {@link getBlocks} — range queries do not prepend the genesis block. */ async getBlocksData(query) {
+        const resolved = await this.resolveBlocksQuery(query);
+        return resolved ? this.stores.blocks.getBlocksData(resolved) : [];
+    }
+    /**
+   * Resolves a {@link BlockQuery} to either the genesis sentinel or a {@link ResolvedBlockQuery}
+   * understood by BlockStore. Detects every shape that points at block 0 — `{number:0}`,
+   * `{hash}` matching the initial header, `{archive}` matching the post-genesis archive root,
+   * and `{tag}` resolving to 0 — and rewrites them to the sentinel so callers branch once.
+   */ async resolveBlockQuery(query) {
+        if ('number' in query) {
+            return query.number === BlockNumber.ZERO ? {
+                genesis: true
+            } : query;
+        }
+        if ('hash' in query) {
+            return query.hash.equals(this.initialBlockHash) ? {
+                genesis: true
+            } : query;
+        }
+        if ('archive' in query) {
+            return query.archive.equals(this.genesisArchiveRoot) ? {
+                genesis: true
+            } : query;
+        }
+        const number = await this.resolveBlockTag(query.tag);
+        if (number === BlockNumber.ZERO) {
+            return {
+                genesis: true
+            };
+        }
+        return {
+            number
+        };
     }
-    async getL2BlockByHash(blockHash) {
-        const checkpointedBlock = await this.store.getCheckpointedBlockByHash(blockHash);
-        return checkpointedBlock?.block;
+    /** Maps a {@link BlockTag} to the matching block number for the current chain state. */ resolveBlockTag(tag) {
+        switch(tag){
+            case 'latest':
+            case 'proposed':
+                return this.stores.blocks.getLatestL2BlockNumber();
+            case 'checkpointed':
+                return this.stores.blocks.getCheckpointedL2BlockNumber();
+            case 'proven':
+                return this.stores.blocks.getProvenBlockNumber();
+            case 'finalized':
+                return this.stores.blocks.getFinalizedL2BlockNumber();
+        }
     }
-    async getL2BlockByArchive(archive) {
-        const checkpointedBlock = await this.store.getCheckpointedBlockByArchive(archive);
-        return checkpointedBlock?.block;
+    /**
+   * Converts an epoch-based BlocksQuery to a from/limit query using l1Constants.
+   * Returns undefined when the epoch has no checkpoints, so callers can return [] without
+   * entering BlockStore. Reads only the two endpoint checkpoints rather than the whole epoch.
+   */ async resolveBlocksQuery(query) {
+        if (!('epoch' in query)) {
+            if (query.from < INITIAL_L2_BLOCK_NUM) {
+                throw new Error(`getBlocks/getBlocksData: 'from' must be >= ${INITIAL_L2_BLOCK_NUM}, got ${query.from}. ` + `Use getBlock({number:0})/getBlockData({number:0}) for genesis-aware single-block lookups.`);
+            }
+            return query;
+        }
+        const checkpointNumbers = await this.getCheckpointNumbersForEpoch(query.epoch);
+        if (checkpointNumbers.length === 0) {
+            return undefined;
+        }
+        const firstNumber = checkpointNumbers[0];
+        const lastNumber = checkpointNumbers[checkpointNumbers.length - 1];
+        const first = await this.stores.blocks.getCheckpointData(firstNumber);
+        if (!first) {
+            return undefined;
+        }
+        const last = firstNumber === lastNumber ? first : await this.stores.blocks.getCheckpointData(lastNumber);
+        if (!last) {
+            return undefined;
+        }
+        const from = BlockNumber(first.startBlock);
+        const limit = last.startBlock + last.blockCount - first.startBlock;
+        return {
+            from,
+            limit,
+            onlyCheckpointed: true
+        };
     }
 }

package/dest/modules/data_store_updater.d.ts

@@ -1,7 +1,7 @@
 import { BlockNumber, CheckpointNumber } from '@aztec/foundation/branded-types';
-import type { L2Block, ValidateCheckpointResult } from '@aztec/stdlib/block';
-import type { PublishedCheckpoint } from '@aztec/stdlib/checkpoint';
-import type { KVArchiverDataStore } from '../store/kv_archiver_store.js';
+import type { CommitteeAttestation, L2Block, ValidateCheckpointResult } from '@aztec/stdlib/block';
+import { type L1PublishedData, type ProposedCheckpointInput, type PublishedCheckpoint } from '@aztec/stdlib/checkpoint';
+import type { ArchiverDataStores } from '../store/data_stores.js';
 import type { L2TipsCache } from '../store/l2_tips_cache.js';
 /** Result of adding checkpoints with information about any pruned blocks. */
 type ReconcileCheckpointsResult = {
@@ -12,33 +12,42 @@ type ReconcileCheckpointsResult = {
 };
 /** Archiver helper module to handle updates to the data store. */
 export declare class ArchiverDataStoreUpdater {
-    private store;
+    private stores;
     private l2TipsCache?;
+    private opts;
     private readonly log;
-    constructor(store: KVArchiverDataStore, l2TipsCache?: L2TipsCache | undefined);
+    constructor(stores: ArchiverDataStores, l2TipsCache?: L2TipsCache | undefined, opts?: {
+        rollupManaLimit?: number;
+    });
     /**
-     * Adds proposed blocks to the store with contract class/instance extraction from logs.
-     * These are uncheckpointed blocks that have been proposed by the sequencer but not yet included in a checkpoint on L1.
-     * Extracts ContractClassPublished, ContractInstancePublished, ContractInstanceUpdated events,
-     * and individually broadcasted functions from the block logs.
+     * Adds a proposed block to the store with contract class/instance extraction from logs.
+     * This is an uncheckpointed block that has been proposed by the sequencer but not yet included in a checkpoint on L1.
+     * Extracts ContractClassPublished, ContractInstancePublished, ContractInstanceUpdated events from the block logs.
      *
-     * @param blocks - The proposed L2 blocks to add.
+     * @param block - The proposed L2 block to add.
      * @param pendingChainValidationStatus - Optional validation status to set.
      * @returns True if the operation is successful.
      */
-    addProposedBlocks(blocks: L2Block[], pendingChainValidationStatus?: ValidateCheckpointResult): Promise<boolean>;
+    addProposedBlock(block: L2Block, pendingChainValidationStatus?: ValidateCheckpointResult): Promise<boolean>;
     /**
      * Reconciles local blocks with incoming checkpoints from L1.
      * Adds new checkpoints to the store with contract class/instance extraction from logs.
      * Prunes any local blocks that conflict with checkpoint data (by comparing archive roots).
-     * Extracts ContractClassPublished, ContractInstancePublished, ContractInstanceUpdated events,
-     * and individually broadcasted functions from the checkpoint block logs.
+     * Extracts ContractClassPublished, ContractInstancePublished, ContractInstanceUpdated events from the checkpoint block logs.
+     * If `promoteProposed` is supplied, the proposed-checkpoint promotion runs inside the same transaction
+     * as the added checkpoints so both updates are applied atomically.
      *
-     * @param checkpoints - The published checkpoints to add.
+     * @param checkpoints - The published checkpoints to add (excluding any being promoted from proposed).
      * @param pendingChainValidationStatus - Optional validation status to set.
+     * @param promoteProposed - Optional promotion of the current proposed checkpoint (fast path when blocks are already local).
      * @returns Result with information about any pruned blocks.
      */
-    addCheckpoints(checkpoints: PublishedCheckpoint[], pendingChainValidationStatus?: ValidateCheckpointResult): Promise<ReconcileCheckpointsResult>;
+    addCheckpoints(checkpoints: PublishedCheckpoint[], pendingChainValidationStatus?: ValidateCheckpointResult, promoteProposed?: {
+        l1: L1PublishedData;
+        attestations: CommitteeAttestation[];
+        checkpoint: PublishedCheckpoint;
+    }, evictProposedFrom?: CheckpointNumber): Promise<ReconcileCheckpointsResult>;
+    addProposedCheckpoint(proposedCheckpoint: ProposedCheckpointInput): Promise<void>;
     private pruneMismatchingLocalBlocks;
     /**
      * Removes all uncheckpointed blocks strictly after the specified block number and cleans up associated contract data.
@@ -50,6 +59,18 @@ export declare class ArchiverDataStoreUpdater {
      * @throws Error if any block to be removed is checkpointed.
      */
     removeUncheckpointedBlocksAfter(blockNumber: BlockNumber): Promise<L2Block[]>;
+    /**
+     * Removes all blocks without a proposed checkpoint strictly after the specified block number and cleans up associated contract data.
+     * This handles removal of provisionally added blocks along with their contract classes/instances.
+     * Verifies that each block being removed is not part of a stored checkpoint (proposed or not).
+     * This differs from `removeUncheckpointedBlocksAfter` in that it also checks proposed checkpoints.
+     *
+     * @param blockNumber - Remove all blocks with number greater than this.
+     * @returns The removed blocks.
+     * @throws Error if any block to be removed is checkpointed.
+     */
+    removeBlocksWithoutProposedCheckpointAfter(blockNumber: BlockNumber): Promise<L2Block[]>;
+    private evictProposedCheckpointsForPrunedBlocks;
     private removeBlocksAfter;
     /**
      * Removes all checkpoints after the given checkpoint number.
@@ -66,6 +87,11 @@ export declare class ArchiverDataStoreUpdater {
      * @param checkpointNumber - The checkpoint number to set as proven.
      */
     setProvenCheckpointNumber(checkpointNumber: CheckpointNumber): Promise<void>;
+    /**
+     * Updates the finalized checkpoint number and refreshes the L2 tips cache.
+     * @param checkpointNumber - The checkpoint number to set as finalized.
+     */
+    setFinalizedCheckpointNumber(checkpointNumber: CheckpointNumber): Promise<void>;
     /** Extracts and stores contract data from a single block. */
     private addContractDataToDb;
     /** Removes contract data associated with a block. */
@@ -74,7 +100,6 @@ export declare class ArchiverDataStoreUpdater {
     private updatePublishedContractClasses;
     private updateDeployedContractInstances;
     private updateUpdatedContractInstances;
-    private storeBroadcastedIndividualFunctions;
 }
 export {};
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZGF0YV9zdG9yZV91cGRhdGVyLmQudHMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvbW9kdWxlcy9kYXRhX3N0b3JlX3VwZGF0ZXIudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxFQUFFLFdBQVcsRUFBRSxnQkFBZ0IsRUFBRSxNQUFNLGlDQUFpQyxDQUFDO0FBWWhGLE9BQU8sS0FBSyxFQUFFLE9BQU8sRUFBRSx3QkFBd0IsRUFBRSxNQUFNLHFCQUFxQixDQUFDO0FBQzdFLE9BQU8sS0FBSyxFQUFFLG1CQUFtQixFQUFFLE1BQU0sMEJBQTBCLENBQUM7QUFhcEUsT0FBTyxLQUFLLEVBQUUsbUJBQW1CLEVBQUUsTUFBTSwrQkFBK0IsQ0FBQztBQUN6RSxPQUFPLEtBQUssRUFBRSxXQUFXLEVBQUUsTUFBTSwyQkFBMkIsQ0FBQztBQVE3RCw2RUFBNkU7QUFDN0UsS0FBSywwQkFBMEIsR0FBRztJQUNoQyxtRUFBbUU7SUFDbkUsWUFBWSxFQUFFLE9BQU8sRUFBRSxHQUFHLFNBQVMsQ0FBQztJQUNwQyxpRkFBaUY7SUFDakYsOEJBQThCLEVBQUUsV0FBVyxHQUFHLFNBQVMsQ0FBQztDQUN6RCxDQUFDO0FBRUYsa0VBQWtFO0FBQ2xFLHFCQUFhLHdCQUF3QjtJQUlqQyxPQUFPLENBQUMsS0FBSztJQUNiLE9BQU8sQ0FBQyxXQUFXLENBQUM7SUFKdEIsT0FBTyxDQUFDLFFBQVEsQ0FBQyxHQUFHLENBQTBDO0lBRTlELFlBQ1UsS0FBSyxFQUFFLG1CQUFtQixFQUMxQixXQUFXLENBQUMseUJBQWEsRUFDL0I7SUFFSjs7Ozs7Ozs7O09BU0c7SUFDVSxpQkFBaUIsQ0FDNUIsTUFBTSxFQUFFLE9BQU8sRUFBRSxFQUNqQiw0QkFBNEIsQ0FBQyxFQUFFLHdCQUF3QixHQUN0RCxPQUFPLENBQUMsT0FBTyxDQUFDLENBaUJsQjtJQUVEOzs7Ozs7Ozs7O09BVUc7SUFDVSxjQUFjLENBQ3pCLFdBQVcsRUFBRSxtQkFBbUIsRUFBRSxFQUNsQyw0QkFBNEIsQ0FBQyxFQUFFLHdCQUF3QixHQUN0RCxPQUFPLENBQUMsMEJBQTBCLENBQUMsQ0F5QnJDO1lBUWEsMkJBQTJCO0lBbUV6Qzs7Ozs7Ozs7T0FRRztJQUNVLCtCQUErQixDQUFDLFdBQVcsRUFBRSxXQUFXLEdBQUcsT0FBTyxDQUFDLE9BQU8sRUFBRSxDQUFDLENBZXpGO1lBTWEsaUJBQWlCO0lBYS9COzs7Ozs7OztPQVFHO0lBQ1Usc0JBQXNCLENBQUMsZ0JBQWdCLEVBQUUsZ0JBQWdCLEdBQUcsT0FBTyxDQUFDLE9BQU8sQ0FBQyxDQWV4RjtJQUVEOzs7T0FHRztJQUNVLHlCQUF5QixDQUFDLGdCQUFnQixFQUFFLGdCQUFnQixHQUFHLE9BQU8sQ0FBQyxJQUFJLENBQUMsQ0FLeEY7SUFFRCw2REFBNkQ7SUFDN0QsT0FBTyxDQUFDLG1CQUFtQjtJQUkzQixxREFBcUQ7SUFDckQsT0FBTyxDQUFDLHdCQUF3QjtZQUtsQixzQkFBc0I7WUFvQnRCLDhCQUE4QjtZQTRCOUIsK0JBQStCO1lBeUIvQiw4QkFBOEI7WUE2QjlCLG1DQUFtQztDQXdEbEQifQ==
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZGF0YV9zdG9yZV91cGRhdGVyLmQudHMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvbW9kdWxlcy9kYXRhX3N0b3JlX3VwZGF0ZXIudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxFQUFFLFdBQVcsRUFBRSxnQkFBZ0IsRUFBRSxNQUFNLGlDQUFpQyxDQUFDO0FBUWhGLE9BQU8sS0FBSyxFQUFFLG9CQUFvQixFQUFFLE9BQU8sRUFBRSx3QkFBd0IsRUFBRSxNQUFNLHFCQUFxQixDQUFDO0FBQ25HLE9BQU8sRUFDTCxLQUFLLGVBQWUsRUFDcEIsS0FBSyx1QkFBdUIsRUFDNUIsS0FBSyxtQkFBbUIsRUFFekIsTUFBTSwwQkFBMEIsQ0FBQztBQVNsQyxPQUFPLEtBQUssRUFBRSxrQkFBa0IsRUFBRSxNQUFNLHlCQUF5QixDQUFDO0FBQ2xFLE9BQU8sS0FBSyxFQUFFLFdBQVcsRUFBRSxNQUFNLDJCQUEyQixDQUFDO0FBUTdELDZFQUE2RTtBQUM3RSxLQUFLLDBCQUEwQixHQUFHO0lBQ2hDLG1FQUFtRTtJQUNuRSxZQUFZLEVBQUUsT0FBTyxFQUFFLEdBQUcsU0FBUyxDQUFDO0lBQ3BDLGlGQUFpRjtJQUNqRiw4QkFBOEIsRUFBRSxXQUFXLEdBQUcsU0FBUyxDQUFDO0NBQ3pELENBQUM7QUFFRixrRUFBa0U7QUFDbEUscUJBQWEsd0JBQXdCO0lBSWpDLE9BQU8sQ0FBQyxNQUFNO0lBQ2QsT0FBTyxDQUFDLFdBQVcsQ0FBQztJQUNwQixPQUFPLENBQUMsSUFBSTtJQUxkLE9BQU8sQ0FBQyxRQUFRLENBQUMsR0FBRyxDQUEwQztJQUU5RCxZQUNVLE1BQU0sRUFBRSxrQkFBa0IsRUFDMUIsV0FBVyxDQUFDLHlCQUFhLEVBQ3pCLElBQUksR0FBRTtRQUFFLGVBQWUsQ0FBQyxFQUFFLE1BQU0sQ0FBQTtLQUFPLEVBQzdDO0lBRUo7Ozs7Ozs7O09BUUc7SUFDVSxnQkFBZ0IsQ0FDM0IsS0FBSyxFQUFFLE9BQU8sRUFDZCw0QkFBNEIsQ0FBQyxFQUFFLHdCQUF3QixHQUN0RCxPQUFPLENBQUMsT0FBTyxDQUFDLENBa0JsQjtJQUVEOzs7Ozs7Ozs7Ozs7T0FZRztJQUNVLGNBQWMsQ0FDekIsV0FBVyxFQUFFLG1CQUFtQixFQUFFLEVBQ2xDLDRCQUE0QixDQUFDLEVBQUUsd0JBQXdCLEVBQ3ZELGVBQWUsQ0FBQyxFQUFFO1FBQ2hCLEVBQUUsRUFBRSxlQUFlLENBQUM7UUFDcEIsWUFBWSxFQUFFLG9CQUFvQixFQUFFLENBQUM7UUFDckMsVUFBVSxFQUFFLG1CQUFtQixDQUFDO0tBQ2pDLEVBQ0QsaUJBQWlCLENBQUMsRUFBRSxnQkFBZ0IsR0FDbkMsT0FBTyxDQUFDLDBCQUEwQixDQUFDLENBOENyQztJQUVZLHFCQUFxQixDQUFDLGtCQUFrQixFQUFFLHVCQUF1QixpQkFNN0U7WUFnQmEsMkJBQTJCO0lBdUV6Qzs7Ozs7Ozs7T0FRRztJQUNVLCtCQUErQixDQUFDLFdBQVcsRUFBRSxXQUFXLEdBQUcsT0FBTyxDQUFDLE9BQU8sRUFBRSxDQUFDLENBaUJ6RjtJQUVEOzs7Ozs7Ozs7T0FTRztJQUNVLDBDQUEwQyxDQUFDLFdBQVcsRUFBRSxXQUFXLEdBQUcsT0FBTyxDQUFDLE9BQU8sRUFBRSxDQUFDLENBY3BHO1lBT2EsdUNBQXVDO1lBWXZDLGlCQUFpQjtJQWEvQjs7Ozs7Ozs7T0FRRztJQUNVLHNCQUFzQixDQUFDLGdCQUFnQixFQUFFLGdCQUFnQixHQUFHLE9BQU8sQ0FBQyxPQUFPLENBQUMsQ0FnQnhGO0lBRUQ7OztPQUdHO0lBQ1UseUJBQXlCLENBQUMsZ0JBQWdCLEVBQUUsZ0JBQWdCLEdBQUcsT0FBTyxDQUFDLElBQUksQ0FBQyxDQUt4RjtJQUVEOzs7T0FHRztJQUNVLDRCQUE0QixDQUFDLGdCQUFnQixFQUFFLGdCQUFnQixHQUFHLE9BQU8sQ0FBQyxJQUFJLENBQUMsQ0FLM0Y7SUFFRCw2REFBNkQ7SUFDN0QsT0FBTyxDQUFDLG1CQUFtQjtJQUkzQixxREFBcUQ7SUFDckQsT0FBTyxDQUFDLHdCQUF3QjtZQUtsQixzQkFBc0I7WUFpQnRCLDhCQUE4QjtZQStDOUIsK0JBQStCO1lBMEMvQiw4QkFBOEI7Q0FzQjdDIn0=

package/dest/modules/data_store_updater.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"data_store_updater.d.ts","sourceRoot":"","sources":["../../src/modules/data_store_updater.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AAYhF,OAAO,KAAK,EAAE,OAAO,EAAE,wBAAwB,EAAE,MAAM,qBAAqB,CAAC;AAC7E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAapE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AACzE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAQ7D,6EAA6E;AAC7E,KAAK,0BAA0B,GAAG;IAChC,mEAAmE;IACnE,YAAY,EAAE,OAAO,EAAE,GAAG,SAAS,CAAC;IACpC,iFAAiF;IACjF,8BAA8B,EAAE,WAAW,GAAG,SAAS,CAAC;CACzD,CAAC;AAEF,kEAAkE;AAClE,qBAAa,wBAAwB;IAIjC,OAAO,CAAC,KAAK;IACb,OAAO,CAAC,WAAW,CAAC;IAJtB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAA0C;IAE9D,YACU,KAAK,EAAE,mBAAmB,EAC1B,WAAW,CAAC,yBAAa,EAC/B;IAEJ;;;;;;;;;OASG;IACU,iBAAiB,CAC5B,MAAM,EAAE,OAAO,EAAE,EACjB,4BAA4B,CAAC,EAAE,wBAAwB,GACtD,OAAO,CAAC,OAAO,CAAC,CAiBlB;IAED;;;;;;;;;;OAUG;IACU,cAAc,CACzB,WAAW,EAAE,mBAAmB,EAAE,EAClC,4BAA4B,CAAC,EAAE,wBAAwB,GACtD,OAAO,CAAC,0BAA0B,CAAC,CAyBrC;YAQa,2BAA2B;IAmEzC;;;;;;;;OAQG;IACU,+BAA+B,CAAC,WAAW,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAezF;YAMa,iBAAiB;IAa/B;;;;;;;;OAQG;IACU,sBAAsB,CAAC,gBAAgB,EAAE,gBAAgB,GAAG,OAAO,CAAC,OAAO,CAAC,CAexF;IAED;;;OAGG;IACU,yBAAyB,CAAC,gBAAgB,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAKxF;IAED,6DAA6D;IAC7D,OAAO,CAAC,mBAAmB;IAI3B,qDAAqD;IACrD,OAAO,CAAC,wBAAwB;YAKlB,sBAAsB;YAoBtB,8BAA8B;YA4B9B,+BAA+B;YAyB/B,8BAA8B;YA6B9B,mCAAmC;CAwDlD"}
+{"version":3,"file":"data_store_updater.d.ts","sourceRoot":"","sources":["../../src/modules/data_store_updater.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AAQhF,OAAO,KAAK,EAAE,oBAAoB,EAAE,OAAO,EAAE,wBAAwB,EAAE,MAAM,qBAAqB,CAAC;AACnG,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,uBAAuB,EAC5B,KAAK,mBAAmB,EAEzB,MAAM,0BAA0B,CAAC;AASlC,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAClE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAQ7D,6EAA6E;AAC7E,KAAK,0BAA0B,GAAG;IAChC,mEAAmE;IACnE,YAAY,EAAE,OAAO,EAAE,GAAG,SAAS,CAAC;IACpC,iFAAiF;IACjF,8BAA8B,EAAE,WAAW,GAAG,SAAS,CAAC;CACzD,CAAC;AAEF,kEAAkE;AAClE,qBAAa,wBAAwB;IAIjC,OAAO,CAAC,MAAM;IACd,OAAO,CAAC,WAAW,CAAC;IACpB,OAAO,CAAC,IAAI;IALd,OAAO,CAAC,QAAQ,CAAC,GAAG,CAA0C;IAE9D,YACU,MAAM,EAAE,kBAAkB,EAC1B,WAAW,CAAC,yBAAa,EACzB,IAAI,GAAE;QAAE,eAAe,CAAC,EAAE,MAAM,CAAA;KAAO,EAC7C;IAEJ;;;;;;;;OAQG;IACU,gBAAgB,CAC3B,KAAK,EAAE,OAAO,EACd,4BAA4B,CAAC,EAAE,wBAAwB,GACtD,OAAO,CAAC,OAAO,CAAC,CAkBlB;IAED;;;;;;;;;;;;OAYG;IACU,cAAc,CACzB,WAAW,EAAE,mBAAmB,EAAE,EAClC,4BAA4B,CAAC,EAAE,wBAAwB,EACvD,eAAe,CAAC,EAAE;QAChB,EAAE,EAAE,eAAe,CAAC;QACpB,YAAY,EAAE,oBAAoB,EAAE,CAAC;QACrC,UAAU,EAAE,mBAAmB,CAAC;KACjC,EACD,iBAAiB,CAAC,EAAE,gBAAgB,GACnC,OAAO,CAAC,0BAA0B,CAAC,CA8CrC;IAEY,qBAAqB,CAAC,kBAAkB,EAAE,uBAAuB,iBAM7E;YAgBa,2BAA2B;IAuEzC;;;;;;;;OAQG;IACU,+BAA+B,CAAC,WAAW,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAiBzF;IAED;;;;;;;;;OASG;IACU,0CAA0C,CAAC,WAAW,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAcpG;YAOa,uCAAuC;YAYvC,iBAAiB;IAa/B;;;;;;;;OAQG;IACU,sBAAsB,CAAC,gBAAgB,EAAE,gBAAgB,GAAG,OAAO,CAAC,OAAO,CAAC,CAgBxF;IAED;;;OAGG;IACU,yBAAyB,CAAC,gBAAgB,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAKxF;IAED;;;OAGG;IACU,4BAA4B,CAAC,gBAAgB,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAK3F;IAED,6DAA6D;IAC7D,OAAO,CAAC,mBAAmB;IAI3B,qDAAqD;IACrD,OAAO,CAAC,wBAAwB;YAKlB,sBAAsB;YAiBtB,8BAA8B;YA+C9B,+BAA+B;YA0C/B,8BAA8B;CAsB7C"}