@aztec/archiver 0.0.1-commit.b6e433891 → 0.0.1-commit.b8a057fa

package/dest/store/log_store.js

@@ -1,533 +1,310 @@
 import { INITIAL_L2_BLOCK_NUM } from '@aztec/constants';
-import { BlockNumber } from '@aztec/foundation/branded-types';
-import { compactArray, filterAsync } from '@aztec/foundation/collection';
-import { Fr } from '@aztec/foundation/curves/bn254';
 import { createLogger } from '@aztec/foundation/log';
-import { BufferReader, numToUInt32BE } from '@aztec/foundation/serialize';
-import { BlockHash } from '@aztec/stdlib/block';
 import { MAX_LOGS_PER_TAG } from '@aztec/stdlib/interfaces/api-limit';
-import { ContractClassLog, ExtendedContractClassLog, ExtendedPublicLog, LogId, PublicLog, TxScopedL2Log } from '@aztec/stdlib/logs';
-import { TxHash } from '@aztec/stdlib/tx';
-import { OutOfOrderLogInsertionError } from '../errors.js';
+import { decodeKeyTail, decodeValue, encodeKey, encodePublicPrefix, encodeValue, endOfTagRange, endOfTxRange, fieldHex, incKey, tagHexForLog } from './log_store_codec.js';
 /**
- * A store for logs
+ * Indexes every emitted private and public log under a composite hex-string key
+ * `[contractAddress (public only)]-tag-blockNumber-txIndexWithinBlock-logIndexWithinTx`,
+ * where each numeric segment is zero-padded to 8 lowercase hex digits (4 bytes BE) and
+ * `contractAddress` / `tag` are the bare 64-hex-char field representations (no `0x` prefix). The
+ * fixed-width zero-padded hex segments sort lexicographically in the same order as the canonical
+ * `(contract, tag, blockNumber, txIndexWithinBlock, logIndexWithinTx)` tuple, so a single ordered
+ * range scan answers every {@link PrivateLogsQuery} / {@link PublicLogsQuery}.
+ *
+ * Per-block secondary indices (`#privateKeysByBlock`, `#publicKeysByBlock`) record the exact primary
+ * keys written for each block so {@link deleteLogs} can drop them on reorg without having to range
+ * scan by block (block isn't the leading key segment).
+ *
+ * Contract-class logs are no longer stored or served by the log store.
  */ export class LogStore {
     db;
     blockStore;
-    // `tag` --> private logs
-    #privateLogsByTag;
-    // `{contractAddress}_${tag}` --> public logs
-    #publicLogsByContractAndTag;
-    #privateLogKeysByBlock;
-    #publicLogKeysByBlock;
-    #publicLogsByBlock;
-    #contractClassLogsByBlock;
-    #logsMaxPageSize;
+    genesisBlockHash;
+    /** Primary map: composite private key (tag + tail = 96 hex chars + separators) -> serialized {@link StoredLogValue}. */ #privateLogs;
+    /** Primary map: composite public key (contract + tag + tail) -> serialized {@link StoredLogValue}. */ #publicLogs;
+    /** Secondary deletion index: blockNumber -> the exact primary keys written for that block. */ #privateKeysByBlock;
+    #publicKeysByBlock;
     #log;
-    constructor(db, blockStore, logsMaxPageSize = 1000){
+    /**
+   * @param genesisBlockHash - Hash of the synthetic genesis block. During early sync the PXE anchors to
+   *   genesis and passes its hash as a query `referenceBlock`; since the archiver never indexes the
+   *   genesis block, the store recognizes this hash directly and resolves it to the genesis block number
+   *   rather than mistaking it for a reorg.
+   */ constructor(db, blockStore, genesisBlockHash){
         this.db = db;
         this.blockStore = blockStore;
+        this.genesisBlockHash = genesisBlockHash;
         this.#log = createLogger('archiver:log_store');
-        this.#privateLogsByTag = db.openMap('archiver_private_tagged_logs_by_tag');
-        this.#publicLogsByContractAndTag = db.openMap('archiver_public_tagged_logs_by_tag');
-        this.#privateLogKeysByBlock = db.openMap('archiver_private_log_keys_by_block');
-        this.#publicLogKeysByBlock = db.openMap('archiver_public_log_keys_by_block');
-        this.#publicLogsByBlock = db.openMap('archiver_public_logs_by_block');
-        this.#contractClassLogsByBlock = db.openMap('archiver_contract_class_logs_by_block');
-        this.#logsMaxPageSize = logsMaxPageSize;
+        this.#privateLogs = db.openMap('archiver_private_logs');
+        this.#publicLogs = db.openMap('archiver_public_logs');
+        this.#privateKeysByBlock = db.openMap('archiver_private_log_keys_by_block');
+        this.#publicKeysByBlock = db.openMap('archiver_public_log_keys_by_block');
     }
     /**
-   * Extracts tagged logs from a single block, grouping them into private and public maps.
+   * Indexes every emitted private and public log from the given blocks. Wraps the write in a single
+   * `db.transactionAsync` so the primary entries and the per-block secondary indices stay consistent.
    *
-   * @param block - The L2 block to extract logs from.
-   * @returns An object containing the private and public tagged logs for the block.
-   */ #extractTaggedLogsFromBlock(block) {
-        // SiloedTag (as string) -> array of log buffers.
-        const privateTaggedLogs = new Map();
-        // "{contractAddress}_{tag}" (as string) -> array of log buffers.
-        const publicTaggedLogs = new Map();
-        block.body.txEffects.forEach((txEffect)=>{
-            const txHash = txEffect.txHash;
-            txEffect.privateLogs.forEach((log)=>{
-                // Private logs use SiloedTag (already siloed by kernel)
-                const tag = log.fields[0];
-                this.#log.debug(`Found private log with tag ${tag.toString()} in block ${block.number}`);
-                const currentLogs = privateTaggedLogs.get(tag.toString()) ?? [];
-                currentLogs.push(new TxScopedL2Log(txHash, block.number, block.timestamp, log.getEmittedFields(), txEffect.noteHashes, txEffect.nullifiers[0]).toBuffer());
-                privateTaggedLogs.set(tag.toString(), currentLogs);
-            });
-            txEffect.publicLogs.forEach((log)=>{
-                // Public logs use Tag directly (not siloed) and are stored with contract address
-                const tag = log.fields[0];
-                const contractAddress = log.contractAddress;
-                const key = `${contractAddress.toString()}_${tag.toString()}`;
-                this.#log.debug(`Found public log with tag ${tag.toString()} from contract ${contractAddress.toString()} in block ${block.number}`);
-                const currentLogs = publicTaggedLogs.get(key) ?? [];
-                currentLogs.push(new TxScopedL2Log(txHash, block.number, block.timestamp, log.getEmittedFields(), txEffect.noteHashes, txEffect.nullifiers[0]).toBuffer());
-                publicTaggedLogs.set(key, currentLogs);
-            });
-        });
-        return {
-            privateTaggedLogs,
-            publicTaggedLogs
-        };
-    }
-    /**
-   * Extracts and aggregates tagged logs from a list of blocks.
-   * @param blocks - The blocks to extract logs from.
-   * @returns A map from tag (as string) to an array of serialized private logs belonging to that tag, and a map from
-   * "{contractAddress}_{tag}" (as string) to an array of serialized public logs belonging to that key.
-   */ #extractTaggedLogs(blocks) {
-        const taggedLogsInBlocks = blocks.map((block)=>this.#extractTaggedLogsFromBlock(block));
-        // Now we merge the maps from each block into a single map.
-        const privateTaggedLogs = taggedLogsInBlocks.reduce((acc, { privateTaggedLogs })=>{
-            for (const [tag, logs] of privateTaggedLogs.entries()){
-                const currentLogs = acc.get(tag) ?? [];
-                acc.set(tag, currentLogs.concat(logs));
-            }
-            return acc;
-        }, new Map());
-        const publicTaggedLogs = taggedLogsInBlocks.reduce((acc, { publicTaggedLogs })=>{
-            for (const [key, logs] of publicTaggedLogs.entries()){
-                const currentLogs = acc.get(key) ?? [];
-                acc.set(key, currentLogs.concat(logs));
-            }
-            return acc;
-        }, new Map());
-        return {
-            privateTaggedLogs,
-            publicTaggedLogs
-        };
-    }
-    async #addPrivateLogs(blocks) {
-        const newBlocks = await filterAsync(blocks, async (block)=>!await this.#privateLogKeysByBlock.hasAsync(block.number));
-        const { privateTaggedLogs } = this.#extractTaggedLogs(newBlocks);
-        const keysOfPrivateLogsToUpdate = Array.from(privateTaggedLogs.keys());
-        const currentPrivateTaggedLogs = await Promise.all(keysOfPrivateLogsToUpdate.map(async (key)=>({
-                tag: key,
-                logBuffers: await this.#privateLogsByTag.getAsync(key)
-            })));
-        for (const taggedLogBuffer of currentPrivateTaggedLogs){
-            if (taggedLogBuffer.logBuffers && taggedLogBuffer.logBuffers.length > 0) {
-                const newLogs = privateTaggedLogs.get(taggedLogBuffer.tag);
-                if (newLogs.length === 0) {
-                    continue;
-                }
-                const lastExisting = TxScopedL2Log.fromBuffer(taggedLogBuffer.logBuffers.at(-1));
-                const firstNew = TxScopedL2Log.fromBuffer(newLogs[0]);
-                if (lastExisting.blockNumber > firstNew.blockNumber) {
-                    throw new OutOfOrderLogInsertionError('private', taggedLogBuffer.tag, lastExisting.blockNumber, firstNew.blockNumber);
+   * A block is only ever added once; on reorg the archiver calls {@link deleteLogs} first, so we write
+   * the secondary index entries with a plain `set` (overwrite) rather than read-modify-append.
+   */ addLogs(blocks) {
+        return this.db.transactionAsync(async ()=>{
+            for (const block of blocks){
+                const blockHash = await block.hash();
+                const blockNumber = block.number;
+                const blockTimestamp = block.timestamp;
+                const privateKeys = [];
+                const privateValues = [];
+                const publicKeys = [];
+                const publicValues = [];
+                for(let txIndexWithinBlock = 0; txIndexWithinBlock < block.body.txEffects.length; txIndexWithinBlock++){
+                    const txEffect = block.body.txEffects[txIndexWithinBlock];
+                    const txHash = txEffect.txHash;
+                    // Private and public log indices are counted independently per tx, each starting at 0.
+                    let privateLogIndexWithinTx = 0;
+                    let publicLogIndexWithinTx = 0;
+                    for (const log of txEffect.privateLogs){
+                        const tagHex = tagHexForLog(log.fields);
+                        const key = encodeKey(tagHex, blockNumber, txIndexWithinBlock, privateLogIndexWithinTx);
+                        const value = encodeValue({
+                            txHash,
+                            blockHash,
+                            blockTimestamp,
+                            logData: log.getEmittedFields()
+                        });
+                        privateKeys.push(key);
+                        privateValues.push(value);
+                        privateLogIndexWithinTx++;
+                    }
+                    for (const log of txEffect.publicLogs){
+                        const contractHex = fieldHex(log.contractAddress);
+                        const tagHex = tagHexForLog(log.fields);
+                        const key = encodeKey(encodePublicPrefix(contractHex, tagHex), blockNumber, txIndexWithinBlock, publicLogIndexWithinTx);
+                        const value = encodeValue({
+                            txHash,
+                            blockHash,
+                            blockTimestamp,
+                            logData: log.getEmittedFields()
+                        });
+                        publicKeys.push(key);
+                        publicValues.push(value);
+                        publicLogIndexWithinTx++;
+                    }
                 }
-                privateTaggedLogs.set(taggedLogBuffer.tag, taggedLogBuffer.logBuffers.concat(newLogs));
-            }
-        }
-        for (const block of newBlocks){
-            const privateTagsInBlock = [];
-            for (const [tag, logs] of privateTaggedLogs.entries()){
-                await this.#privateLogsByTag.set(tag, logs);
-                privateTagsInBlock.push(tag);
-            }
-            await this.#privateLogKeysByBlock.set(block.number, privateTagsInBlock);
-        }
-    }
-    async #addPublicLogs(blocks) {
-        const newBlocks = await filterAsync(blocks, async (block)=>!await this.#publicLogKeysByBlock.hasAsync(block.number));
-        const { publicTaggedLogs } = this.#extractTaggedLogs(newBlocks);
-        const keysOfPublicLogsToUpdate = Array.from(publicTaggedLogs.keys());
-        const currentPublicTaggedLogs = await Promise.all(keysOfPublicLogsToUpdate.map(async (key)=>({
-                tag: key,
-                logBuffers: await this.#publicLogsByContractAndTag.getAsync(key)
-            })));
-        for (const taggedLogBuffer of currentPublicTaggedLogs){
-            if (taggedLogBuffer.logBuffers && taggedLogBuffer.logBuffers.length > 0) {
-                const newLogs = publicTaggedLogs.get(taggedLogBuffer.tag);
-                if (newLogs.length === 0) {
-                    continue;
+                for(let i = 0; i < privateKeys.length; i++){
+                    await this.#privateLogs.set(privateKeys[i], privateValues[i]);
                 }
-                const lastExisting = TxScopedL2Log.fromBuffer(taggedLogBuffer.logBuffers.at(-1));
-                const firstNew = TxScopedL2Log.fromBuffer(newLogs[0]);
-                if (lastExisting.blockNumber > firstNew.blockNumber) {
-                    throw new OutOfOrderLogInsertionError('public', taggedLogBuffer.tag, lastExisting.blockNumber, firstNew.blockNumber);
+                for(let i = 0; i < publicKeys.length; i++){
+                    await this.#publicLogs.set(publicKeys[i], publicValues[i]);
                 }
-                publicTaggedLogs.set(taggedLogBuffer.tag, taggedLogBuffer.logBuffers.concat(newLogs));
+                await this.#privateKeysByBlock.set(blockNumber, privateKeys);
+                await this.#publicKeysByBlock.set(blockNumber, publicKeys);
+                this.#log.debug(`Indexed logs for block ${blockNumber}`, {
+                    blockNumber,
+                    privateCount: privateKeys.length,
+                    publicCount: publicKeys.length
+                });
             }
-        }
-        for (const block of newBlocks){
-            const blockHash = await block.hash();
-            const publicTagsInBlock = [];
-            for (const [tag, logs] of publicTaggedLogs.entries()){
-                await this.#publicLogsByContractAndTag.set(tag, logs);
-                publicTagsInBlock.push(tag);
-            }
-            await this.#publicLogKeysByBlock.set(block.number, publicTagsInBlock);
-            const publicLogsInBlock = block.body.txEffects.map((txEffect, txIndex)=>[
-                    numToUInt32BE(txIndex),
-                    txEffect.txHash.toBuffer(),
-                    numToUInt32BE(txEffect.publicLogs.length),
-                    txEffect.publicLogs.map((log)=>log.toBuffer())
-                ].flat()).flat();
-            await this.#publicLogsByBlock.set(block.number, this.#packWithBlockHash(blockHash, publicLogsInBlock));
-        }
-    }
-    async #addContractClassLogs(blocks) {
-        const newBlocks = await filterAsync(blocks, async (block)=>!await this.#contractClassLogsByBlock.hasAsync(block.number));
-        for (const block of newBlocks){
-            const blockHash = await block.hash();
-            const contractClassLogsInBlock = block.body.txEffects.map((txEffect, txIndex)=>[
-                    numToUInt32BE(txIndex),
-                    txEffect.txHash.toBuffer(),
-                    numToUInt32BE(txEffect.contractClassLogs.length),
-                    txEffect.contractClassLogs.map((log)=>log.toBuffer())
-                ].flat()).flat();
-            await this.#contractClassLogsByBlock.set(block.number, this.#packWithBlockHash(blockHash, contractClassLogsInBlock));
-        }
-    }
-    /**
-   * Append new logs to the store's list.
-   * @param blocks - The blocks for which to add the logs.
-   * @returns True if the operation is successful.
-   */ addLogs(blocks) {
-        return this.db.transactionAsync(async ()=>{
-            await Promise.all([
-                this.#addPrivateLogs(blocks),
-                this.#addPublicLogs(blocks),
-                this.#addContractClassLogs(blocks)
-            ]);
             return true;
         });
     }
-    #packWithBlockHash(blockHash, data) {
-        return Buffer.concat([
-            blockHash.toBuffer(),
-            ...data
-        ]);
-    }
-    #unpackBlockHash(reader) {
-        const blockHash = reader.remainingBytes() > 0 ? reader.readObject(Fr) : undefined;
-        if (!blockHash) {
-            throw new Error('Failed to read block hash from log entry buffer');
-        }
-        return new BlockHash(blockHash);
-    }
-    deleteLogs(blocks) {
+    /**
+   * Deletes every log indexed under any of the given blocks. Secondary-index driven, so it doesn't
+   * have to range-scan the primary maps.
+   */ deleteLogs(blocks) {
         return this.db.transactionAsync(async ()=>{
-            const blockNumbers = new Set(blocks.map((block)=>block.number));
-            const firstBlockToDelete = Math.min(...blockNumbers);
-            // Collect all unique private tags across all blocks being deleted
-            const allPrivateTags = new Set(compactArray(await Promise.all(blocks.map((block)=>this.#privateLogKeysByBlock.getAsync(block.number)))).flat());
-            // Trim private logs: for each tag, delete all instances including and after the first block being deleted.
-            // This hinges on the invariant that logs for a given tag are always inserted in order of block number, which is enforced in #addPrivateLogs.
-            for (const tag of allPrivateTags){
-                const existing = await this.#privateLogsByTag.getAsync(tag);
-                if (existing === undefined || existing.length === 0) {
-                    continue;
+            for (const block of blocks){
+                const blockNumber = block.number;
+                const [privateKeys, publicKeys] = await Promise.all([
+                    this.#privateKeysByBlock.getAsync(blockNumber),
+                    this.#publicKeysByBlock.getAsync(blockNumber)
+                ]);
+                if (privateKeys) {
+                    for (const key of privateKeys){
+                        await this.#privateLogs.delete(key);
+                    }
+                    await this.#privateKeysByBlock.delete(blockNumber);
                 }
-                const lastIndexToKeep = existing.findLastIndex((buf)=>TxScopedL2Log.getBlockNumberFromBuffer(buf) < firstBlockToDelete);
-                const remaining = existing.slice(0, lastIndexToKeep + 1);
-                await (remaining.length > 0 ? this.#privateLogsByTag.set(tag, remaining) : this.#privateLogsByTag.delete(tag));
-            }
-            // Collect all unique public keys across all blocks being deleted
-            const allPublicKeys = new Set(compactArray(await Promise.all(blocks.map((block)=>this.#publicLogKeysByBlock.getAsync(block.number)))).flat());
-            // And do the same as we did with private logs
-            for (const key of allPublicKeys){
-                const existing = await this.#publicLogsByContractAndTag.getAsync(key);
-                if (existing === undefined || existing.length === 0) {
-                    continue;
+                if (publicKeys) {
+                    for (const key of publicKeys){
+                        await this.#publicLogs.delete(key);
+                    }
+                    await this.#publicKeysByBlock.delete(blockNumber);
                 }
-                const lastIndexToKeep = existing.findLastIndex((buf)=>TxScopedL2Log.getBlockNumberFromBuffer(buf) < firstBlockToDelete);
-                const remaining = existing.slice(0, lastIndexToKeep + 1);
-                await (remaining.length > 0 ? this.#publicLogsByContractAndTag.set(key, remaining) : this.#publicLogsByContractAndTag.delete(key));
             }
-            // After trimming the tagged logs, we can delete the block-level keys that track which tags are in which blocks.
-            await Promise.all(blocks.map((block)=>Promise.all([
-                    this.#publicLogsByBlock.delete(block.number),
-                    this.#privateLogKeysByBlock.delete(block.number),
-                    this.#publicLogKeysByBlock.delete(block.number),
-                    this.#contractClassLogsByBlock.delete(block.number)
-                ])));
             return true;
         });
     }
-    /**
-   * Gets private logs that match any of the `tags`. For each tag, an array of matching logs is returned. An empty
-   * array implies no logs match that tag.
-   * @param tags - The tags to search for.
-   * @param page - The page number (0-indexed) for pagination.
-   * @param upToBlockNumber - If set, only return logs from blocks up to and including this block number.
-   * @returns An array of log arrays, one per tag. Returns at most MAX_LOGS_PER_TAG logs per tag per page. If
-   * MAX_LOGS_PER_TAG logs are returned for a tag, the caller should fetch the next page to check for more logs.
-   */ async getPrivateLogsByTags(tags, page = 0, upToBlockNumber) {
-        const logs = await Promise.all(tags.map((tag)=>this.#privateLogsByTag.getAsync(tag.toString())));
-        const start = page * MAX_LOGS_PER_TAG;
-        const end = start + MAX_LOGS_PER_TAG;
-        return logs.map((logBuffers)=>{
-            const deserialized = logBuffers?.slice(start, end).map((buf)=>TxScopedL2Log.fromBuffer(buf)) ?? [];
-            if (upToBlockNumber !== undefined) {
-                const cutoff = deserialized.findIndex((log)=>log.blockNumber > upToBlockNumber);
-                if (cutoff !== -1) {
-                    return deserialized.slice(0, cutoff);
-                }
-            }
-            return deserialized;
-        });
+    /** Returns one inner array per element of `query.tags`, in input order. */ getPrivateLogsByTags(query) {
+        LogStore.#validateQuery(query);
+        return this.db.transactionAsync(()=>this.#runQuery(query, /* contractHex */ undefined));
     }
-    /**
-   * Gets public logs that match any of the `tags` from the specified contract. For each tag, an array of matching
-   * logs is returned. An empty array implies no logs match that tag.
-   * @param contractAddress - The contract address to search logs for.
-   * @param tags - The tags to search for.
-   * @param page - The page number (0-indexed) for pagination.
-   * @param upToBlockNumber - If set, only return logs from blocks up to and including this block number.
-   * @returns An array of log arrays, one per tag. Returns at most MAX_LOGS_PER_TAG logs per tag per page. If
-   * MAX_LOGS_PER_TAG logs are returned for a tag, the caller should fetch the next page to check for more logs.
-   */ async getPublicLogsByTagsFromContract(contractAddress, tags, page = 0, upToBlockNumber) {
-        const logs = await Promise.all(tags.map((tag)=>{
-            const key = `${contractAddress.toString()}_${tag.value.toString()}`;
-            return this.#publicLogsByContractAndTag.getAsync(key);
-        }));
-        const start = page * MAX_LOGS_PER_TAG;
-        const end = start + MAX_LOGS_PER_TAG;
-        return logs.map((logBuffers)=>{
-            const deserialized = logBuffers?.slice(start, end).map((buf)=>TxScopedL2Log.fromBuffer(buf)) ?? [];
-            if (upToBlockNumber !== undefined) {
-                const cutoff = deserialized.findIndex((log)=>log.blockNumber > upToBlockNumber);
-                if (cutoff !== -1) {
-                    return deserialized.slice(0, cutoff);
-                }
-            }
-            return deserialized;
-        });
+    /** Returns one inner array per element of `query.tags`, in input order. */ getPublicLogsByTags(query) {
+        LogStore.#validateQuery(query);
+        return this.db.transactionAsync(()=>this.#runQuery(query, fieldHex(query.contractAddress)));
     }
-    /**
-   * Gets public logs based on the provided filter.
-   * @param filter - The filter to apply to the logs.
-   * @returns The requested logs.
-   */ getPublicLogs(filter) {
-        if (filter.afterLog) {
-            return this.#filterPublicLogsBetweenBlocks(filter);
-        } else if (filter.txHash) {
-            return this.#filterPublicLogsOfTx(filter);
-        } else {
-            return this.#filterPublicLogsBetweenBlocks(filter);
+    static #validateQuery(query) {
+        if (query.txHash !== undefined && (query.fromBlock !== undefined || query.toBlock !== undefined)) {
+            throw new Error('`txHash` is mutually exclusive with `fromBlock`/`toBlock`');
         }
     }
-    async #filterPublicLogsOfTx(filter) {
-        if (!filter.txHash) {
-            throw new Error('Missing txHash');
+    async #runQuery(query, contractHex) {
+        const isPublic = contractHex !== undefined;
+        const tags = query.tags ?? [];
+        const primaryMap = isPublic ? this.#publicLogs : this.#privateLogs;
+        // referenceBlock reorg check, in-transaction, against the same db the log primary maps live on. The
+        // genesis block is a valid anchor during early sync but is synthetic and never indexed in the block
+        // store, so resolve it directly to the genesis block number rather than mistaking it for a reorg.
+        let referenceBlockNumber;
+        if (query.referenceBlock) {
+            if (query.referenceBlock.equals(this.genesisBlockHash)) {
+                referenceBlockNumber = INITIAL_L2_BLOCK_NUM - 1;
+            } else {
+                const refBlk = await this.blockStore.getBlockData({
+                    hash: query.referenceBlock
+                });
+                if (!refBlk) {
+                    throw new Error(`Reference block ${query.referenceBlock.toString()} not found in the node. This might indicate a reorg has occurred.`);
+                }
+                referenceBlockNumber = refBlk.header.globalVariables.blockNumber;
+            }
+        }
+        // Compute the exclusive upper-block bound across `toBlock` and `referenceBlock`.
+        // `toBlock` is already exclusive; `referenceBlock` caps inclusively, so its exclusive form is +1.
+        let upperExclusive;
+        if (query.toBlock !== undefined) {
+            upperExclusive = query.toBlock;
         }
-        const [blockNumber, txIndex] = await this.blockStore.getTxLocation(filter.txHash) ?? [];
-        if (typeof blockNumber !== 'number' || typeof txIndex !== 'number') {
-            return {
-                logs: [],
-                maxLogsHit: false
-            };
+        if (referenceBlockNumber !== undefined) {
+            const refExclusive = referenceBlockNumber + 1;
+            upperExclusive = upperExclusive === undefined ? refExclusive : Math.min(upperExclusive, refExclusive);
         }
-        const buffer = await this.#publicLogsByBlock.getAsync(blockNumber) ?? Buffer.alloc(0);
-        const publicLogsInBlock = [];
-        const reader = new BufferReader(buffer);
-        const blockHash = this.#unpackBlockHash(reader);
-        while(reader.remainingBytes() > 0){
-            const indexOfTx = reader.readNumber();
-            const txHash = reader.readObject(TxHash);
-            const numLogsInTx = reader.readNumber();
-            publicLogsInBlock[indexOfTx] = {
-                txHash,
-                logs: []
-            };
-            for(let i = 0; i < numLogsInTx; i++){
-                publicLogsInBlock[indexOfTx].logs.push(reader.readObject(PublicLog));
+        // Resolve txHash -> (blockNumber, txIndexInBlock) once for the whole query.
+        let txLocation;
+        if (query.txHash) {
+            const loc = await this.blockStore.getTxLocation(query.txHash);
+            if (!loc) {
+                return tags.map(()=>[]);
+            }
+            txLocation = loc;
+            if (upperExclusive !== undefined && txLocation[0] >= upperExclusive) {
+                return tags.map(()=>[]);
             }
         }
-        const txData = publicLogsInBlock[txIndex];
-        const logs = [];
-        const maxLogsHit = this.#accumulatePublicLogs(logs, blockNumber, blockHash, txIndex, txData.txHash, txData.logs, filter);
-        return {
-            logs,
-            maxLogsHit
-        };
-    }
-    async #filterPublicLogsBetweenBlocks(filter) {
-        const start = filter.afterLog?.blockNumber ?? Math.max(filter.fromBlock ?? INITIAL_L2_BLOCK_NUM, INITIAL_L2_BLOCK_NUM);
-        const end = filter.toBlock;
-        if (typeof end === 'number' && end < start) {
-            return {
-                logs: [],
-                maxLogsHit: true
-            };
+        const fromBlock = query.fromBlock ?? INITIAL_L2_BLOCK_NUM;
+        const includeEffects = query.includeEffects === true;
+        const perTagResults = [];
+        for (const tagEntry of tags){
+            const { tagHex, afterLog } = normalizeTagEntry(tagEntry);
+            const prefix = contractHex !== undefined ? encodePublicPrefix(contractHex, tagHex) : tagHex;
+            const end = txLocation ? endOfTxRange(prefix, txLocation[0], txLocation[1]) : endOfTagRange(prefix, upperExclusive);
+            let start;
+            if (afterLog) {
+                // Cursor wins as the start; `fromBlock` is ignored (fine if the cursor sits below it). The cursor
+                // carries `(blockNumber, txIndexWithinBlock, logIndexWithinTx)`, which slot directly into the
+                // composite key — no tx-hash lookup needed.
+                start = incKey(encodeKey(prefix, afterLog.blockNumber, afterLog.txIndexWithinBlock, afterLog.logIndexWithinTx));
+            } else if (txLocation) {
+                start = encodeKey(prefix, txLocation[0], txLocation[1], 0);
+            } else {
+                start = encodeKey(prefix, fromBlock, 0, 0);
+            }
+            const limit = query.limitPerTag ?? MAX_LOGS_PER_TAG;
+            const out = [];
+            for await (const [rawKey, rawVal] of primaryMap.entriesAsync({
+                start,
+                end,
+                limit
+            })){
+                const tail = decodeKeyTail(rawKey);
+                const value = decodeValue(rawVal);
+                out.push({
+                    logData: value.logData,
+                    blockNumber: tail.blockNumber,
+                    blockHash: value.blockHash,
+                    blockTimestamp: value.blockTimestamp,
+                    txHash: value.txHash,
+                    txIndexWithinBlock: tail.txIndexWithinBlock,
+                    logIndexWithinTx: tail.logIndexWithinTx
+                });
+            }
+            perTagResults.push(out);
         }
-        const logs = [];
-        let maxLogsHit = false;
-        loopOverBlocks: for await (const [blockNumber, logBuffer] of this.#publicLogsByBlock.entriesAsync({
-            start,
-            end
-        })){
-            const publicLogsInBlock = [];
-            const reader = new BufferReader(logBuffer);
-            const blockHash = this.#unpackBlockHash(reader);
-            while(reader.remainingBytes() > 0){
-                const indexOfTx = reader.readNumber();
-                const txHash = reader.readObject(TxHash);
-                const numLogsInTx = reader.readNumber();
-                publicLogsInBlock[indexOfTx] = {
-                    txHash,
-                    logs: []
-                };
-                for(let i = 0; i < numLogsInTx; i++){
-                    publicLogsInBlock[indexOfTx].logs.push(reader.readObject(PublicLog));
+        if (includeEffects) {
+            // Dedupe by txHash across the entire page so a tx with many tagged logs costs one fetch.
+            const txHashByKey = new Map();
+            for (const arr of perTagResults){
+                for (const log of arr){
+                    txHashByKey.set(log.txHash.toString(), log.txHash);
                 }
             }
-            for(let txIndex = filter.afterLog?.txIndex ?? 0; txIndex < publicLogsInBlock.length; txIndex++){
-                const txData = publicLogsInBlock[txIndex];
-                maxLogsHit = this.#accumulatePublicLogs(logs, blockNumber, blockHash, txIndex, txData.txHash, txData.logs, filter);
-                if (maxLogsHit) {
-                    this.#log.debug(`Max logs hit at block ${blockNumber}`);
-                    break loopOverBlocks;
+            const uniqueTxs = Array.from(txHashByKey.values());
+            if (uniqueTxs.length > 0) {
+                const effects = await this.blockStore.getNoteHashesAndNullifiers(uniqueTxs);
+                const byTxHash = new Map();
+                uniqueTxs.forEach((tx, i)=>byTxHash.set(tx.toString(), effects[i]));
+                for(let i = 0; i < perTagResults.length; i++){
+                    perTagResults[i] = perTagResults[i].map((log)=>{
+                        const [noteHashes, nullifiers] = byTxHash.get(log.txHash.toString()) ?? [
+                            [],
+                            []
+                        ];
+                        return {
+                            ...log,
+                            noteHashes,
+                            nullifiers
+                        };
+                    });
                 }
             }
         }
-        return {
-            logs,
-            maxLogsHit
-        };
+        return perTagResults;
     }
     /**
-   * Gets contract class logs based on the provided filter.
-   * @param filter - The filter to apply to the logs.
-   * @returns The requested logs.
-   */ getContractClassLogs(filter) {
-        if (filter.afterLog) {
-            return this.#filterContractClassLogsBetweenBlocks(filter);
-        } else if (filter.txHash) {
-            return this.#filterContractClassLogsOfTx(filter);
-        } else {
-            return this.#filterContractClassLogsBetweenBlocks(filter);
-        }
+   * Reads back every private log indexed for the given block via the per-block secondary index. Order
+   * matches the canonical composite-key order (`tag`, `blockNumber`, `txIndexWithinBlock`,
+   * `logIndexWithinTx`). Used by the data-store-updater test suite to verify the indexed-vs-block-body
+   * counts without depending on the removed `getPublicLogs(LogFilter)` API.
+   */ getPrivateLogsForBlock(blockNumber) {
+        return this.db.transactionAsync(()=>this.#readBlockLogs(this.#privateKeysByBlock, this.#privateLogs, blockNumber));
     }
-    async #filterContractClassLogsOfTx(filter) {
-        if (!filter.txHash) {
-            throw new Error('Missing txHash');
-        }
-        const [blockNumber, txIndex] = await this.blockStore.getTxLocation(filter.txHash) ?? [];
-        if (typeof blockNumber !== 'number' || typeof txIndex !== 'number') {
-            return {
-                logs: [],
-                maxLogsHit: false
-            };
-        }
-        const contractClassLogsBuffer = await this.#contractClassLogsByBlock.getAsync(blockNumber) ?? Buffer.alloc(0);
-        const contractClassLogsInBlock = [];
-        const reader = new BufferReader(contractClassLogsBuffer);
-        const blockHash = this.#unpackBlockHash(reader);
-        while(reader.remainingBytes() > 0){
-            const indexOfTx = reader.readNumber();
-            const txHash = reader.readObject(TxHash);
-            const numLogsInTx = reader.readNumber();
-            contractClassLogsInBlock[indexOfTx] = {
-                txHash,
-                logs: []
-            };
-            for(let i = 0; i < numLogsInTx; i++){
-                contractClassLogsInBlock[indexOfTx].logs.push(reader.readObject(ContractClassLog));
-            }
-        }
-        const txData = contractClassLogsInBlock[txIndex];
-        const logs = [];
-        const maxLogsHit = this.#accumulateContractClassLogs(logs, blockNumber, blockHash, txIndex, txData.txHash, txData.logs, filter);
-        return {
-            logs,
-            maxLogsHit
-        };
+    /** {@inheritDoc LogStore.getPrivateLogsForBlock} */ getPublicLogsForBlock(blockNumber) {
+        return this.db.transactionAsync(()=>this.#readBlockLogs(this.#publicKeysByBlock, this.#publicLogs, blockNumber));
     }
-    async #filterContractClassLogsBetweenBlocks(filter) {
-        const start = filter.afterLog?.blockNumber ?? Math.max(filter.fromBlock ?? INITIAL_L2_BLOCK_NUM, INITIAL_L2_BLOCK_NUM);
-        const end = filter.toBlock;
-        if (typeof end === 'number' && end < start) {
-            return {
-                logs: [],
-                maxLogsHit: true
-            };
+    async #readBlockLogs(keysByBlock, primaryMap, blockNumber) {
+        const keys = await keysByBlock.getAsync(blockNumber);
+        if (!keys || keys.length === 0) {
+            return [];
         }
-        const logs = [];
-        let maxLogsHit = false;
-        loopOverBlocks: for await (const [blockNumber, logBuffer] of this.#contractClassLogsByBlock.entriesAsync({
-            start,
-            end
-        })){
-            const contractClassLogsInBlock = [];
-            const reader = new BufferReader(logBuffer);
-            const blockHash = this.#unpackBlockHash(reader);
-            while(reader.remainingBytes() > 0){
-                const indexOfTx = reader.readNumber();
-                const txHash = reader.readObject(TxHash);
-                const numLogsInTx = reader.readNumber();
-                contractClassLogsInBlock[indexOfTx] = {
-                    txHash,
-                    logs: []
-                };
-                for(let i = 0; i < numLogsInTx; i++){
-                    contractClassLogsInBlock[indexOfTx].logs.push(reader.readObject(ContractClassLog));
-                }
-            }
-            for(let txIndex = filter.afterLog?.txIndex ?? 0; txIndex < contractClassLogsInBlock.length; txIndex++){
-                const txData = contractClassLogsInBlock[txIndex];
-                maxLogsHit = this.#accumulateContractClassLogs(logs, blockNumber, blockHash, txIndex, txData.txHash, txData.logs, filter);
-                if (maxLogsHit) {
-                    this.#log.debug(`Max logs hit at block ${blockNumber}`);
-                    break loopOverBlocks;
-                }
+        const results = [];
+        for (const key of keys){
+            const raw = await primaryMap.getAsync(key);
+            if (!raw) {
+                continue;
             }
+            const tail = decodeKeyTail(key);
+            const value = decodeValue(raw);
+            results.push({
+                logData: value.logData,
+                blockNumber: tail.blockNumber,
+                blockHash: value.blockHash,
+                blockTimestamp: value.blockTimestamp,
+                txHash: value.txHash,
+                txIndexWithinBlock: tail.txIndexWithinBlock,
+                logIndexWithinTx: tail.logIndexWithinTx
+            });
         }
+        return results;
+    }
+}
+/** Pulls `{ tagHex, afterLog }` out of a {@link TagQuery}, normalizing the bare-tag form. */ function normalizeTagEntry(entry) {
+    if (typeof entry === 'object' && entry !== null && 'tag' in entry) {
         return {
-            logs,
-            maxLogsHit
+            tagHex: fieldHex(entry.tag.value),
+            afterLog: entry.afterLog
         };
     }
-    #accumulatePublicLogs(results, blockNumber, blockHash, txIndex, txHash, txLogs, filter = {}) {
-        if (filter.fromBlock && blockNumber < filter.fromBlock) {
-            return false;
-        }
-        if (filter.toBlock && blockNumber >= filter.toBlock) {
-            return false;
-        }
-        if (filter.txHash && !txHash.equals(filter.txHash)) {
-            return false;
-        }
-        let maxLogsHit = false;
-        let logIndex = typeof filter.afterLog?.logIndex === 'number' ? filter.afterLog.logIndex + 1 : 0;
-        for(; logIndex < txLogs.length; logIndex++){
-            const log = txLogs[logIndex];
-            if ((!filter.contractAddress || log.contractAddress.equals(filter.contractAddress)) && (!filter.tag || log.fields[0]?.equals(filter.tag))) {
-                results.push(new ExtendedPublicLog(new LogId(BlockNumber(blockNumber), blockHash, txHash, txIndex, logIndex), log));
-                if (results.length >= this.#logsMaxPageSize) {
-                    maxLogsHit = true;
-                    break;
-                }
-            }
-        }
-        return maxLogsHit;
-    }
-    #accumulateContractClassLogs(results, blockNumber, blockHash, txIndex, txHash, txLogs, filter = {}) {
-        if (filter.fromBlock && blockNumber < filter.fromBlock) {
-            return false;
-        }
-        if (filter.toBlock && blockNumber >= filter.toBlock) {
-            return false;
-        }
-        if (filter.txHash && !txHash.equals(filter.txHash)) {
-            return false;
-        }
-        let maxLogsHit = false;
-        let logIndex = typeof filter.afterLog?.logIndex === 'number' ? filter.afterLog.logIndex + 1 : 0;
-        for(; logIndex < txLogs.length; logIndex++){
-            const log = txLogs[logIndex];
-            if (!filter.contractAddress || log.contractAddress.equals(filter.contractAddress)) {
-                results.push(new ExtendedContractClassLog(new LogId(BlockNumber(blockNumber), blockHash, txHash, txIndex, logIndex), log));
-                if (results.length >= this.#logsMaxPageSize) {
-                    maxLogsHit = true;
-                    break;
-                }
-            }
-        }
-        return maxLogsHit;
-    }
+    return {
+        tagHex: fieldHex(entry.value),
+        afterLog: undefined
+    };
 }