@aztec/archiver 0.0.1-commit.d3ec352c → 0.0.1-commit.d58ff9d0

package/dest/store/log_store.js

@@ -0,0 +1,310 @@
+import { INITIAL_L2_BLOCK_NUM } from '@aztec/constants';
+import { createLogger } from '@aztec/foundation/log';
+import { MAX_LOGS_PER_TAG } from '@aztec/stdlib/interfaces/api-limit';
+import { decodeKeyTail, decodeValue, encodeKey, encodePublicPrefix, encodeValue, endOfTagRange, endOfTxRange, fieldHex, incKey, tagHexForLog } from './log_store_codec.js';
+/**
+ * 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;
+    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;
+    /**
+   * @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.#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');
+    }
+    /**
+   * 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.
+   *
+   * 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++;
+                    }
+                }
+                for(let i = 0; i < privateKeys.length; i++){
+                    await this.#privateLogs.set(privateKeys[i], privateValues[i]);
+                }
+                for(let i = 0; i < publicKeys.length; i++){
+                    await this.#publicLogs.set(publicKeys[i], publicValues[i]);
+                }
+                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
+                });
+            }
+            return true;
+        });
+    }
+    /**
+   * 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 ()=>{
+            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);
+                }
+                if (publicKeys) {
+                    for (const key of publicKeys){
+                        await this.#publicLogs.delete(key);
+                    }
+                    await this.#publicKeysByBlock.delete(blockNumber);
+                }
+            }
+            return true;
+        });
+    }
+    /** 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));
+    }
+    /** 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)));
+    }
+    static #validateQuery(query) {
+        if (query.txHash !== undefined && (query.fromBlock !== undefined || query.toBlock !== undefined)) {
+            throw new Error('`txHash` is mutually exclusive with `fromBlock`/`toBlock`');
+        }
+    }
+    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;
+        }
+        if (referenceBlockNumber !== undefined) {
+            const refExclusive = referenceBlockNumber + 1;
+            upperExclusive = upperExclusive === undefined ? refExclusive : Math.min(upperExclusive, refExclusive);
+        }
+        // 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 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);
+        }
+        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);
+                }
+            }
+            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 perTagResults;
+    }
+    /**
+   * 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));
+    }
+    /** {@inheritDoc LogStore.getPrivateLogsForBlock} */ getPublicLogsForBlock(blockNumber) {
+        return this.db.transactionAsync(()=>this.#readBlockLogs(this.#publicKeysByBlock, this.#publicLogs, blockNumber));
+    }
+    async #readBlockLogs(keysByBlock, primaryMap, blockNumber) {
+        const keys = await keysByBlock.getAsync(blockNumber);
+        if (!keys || keys.length === 0) {
+            return [];
+        }
+        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 {
+            tagHex: fieldHex(entry.tag.value),
+            afterLog: entry.afterLog
+        };
+    }
+    return {
+        tagHex: fieldHex(entry.value),
+        afterLog: undefined
+    };
+}

package/dest/store/log_store_codec.d.ts

@@ -0,0 +1,78 @@
+import { BlockNumber } from '@aztec/foundation/branded-types';
+import { Fr } from '@aztec/foundation/curves/bn254';
+import { BlockHash } from '@aztec/stdlib/block';
+import { TxHash } from '@aztec/stdlib/tx';
+export declare const NUMERIC_HEX_LEN = 8;
+export declare const SEP = "-";
+/**
+ * Sentinel appended after a numeric hex segment to build an end bound strictly greater than any
+ * real key for that namespace. `'g'` sorts lexicographically after every hex digit (`0`-`9`, `a`-`f`),
+ * so `prefix + '-g'` is a clean exclusive upper bound.
+ */
+export declare const HEX_SENTINEL = "g";
+export type ParsedKeyTail = {
+    blockNumber: BlockNumber;
+    txIndexWithinBlock: number;
+    logIndexWithinTx: number;
+};
+/**
+ * Per-kind stored value layout (no msgpackr):
+ *   txHash(32) ++ blockHash(32) ++ blockTimestamp(u64 BE = 8) ++ logDataLen(u32 BE = 4) ++ logData[i].toBuffer()...
+ * `blockNumber`, `txIndexWithinBlock`, and `logIndexWithinTx` are decoded from the composite key.
+ */
+export type StoredLogValue = {
+    txHash: TxHash;
+    blockHash: BlockHash;
+    blockTimestamp: bigint;
+    logData: Fr[];
+};
+/** Returns the 64-char lowercase hex representation of a field, stripping the `0x` prefix. */
+export declare function fieldHex(value: Fr | {
+    toString: () => string;
+}): string;
+/**
+ * Tag prefix for a log: the hex of its first field, or the empty string when the log carries no fields.
+ * A protocol-valid public log can have zero fields (e.g. a raw AVM `EMITPUBLICLOG` with `logSize = 0`),
+ * which has no tag to index by. Encoding it under the empty tag keeps it retrievable via the per-block
+ * read (and droppable on reorg) while never matching a real 64-hex-char tag query — instead of reading
+ * `fields[0]` off an empty array and aborting the whole block-ingestion transaction.
+ */
+export declare function tagHexForLog(fields: Fr[]): string;
+/** Encodes a number as 8-char zero-padded lowercase hex (matches a u32 big-endian byte buffer's lex order). */
+export declare function u32Hex(n: number): string;
+/**
+ * Encodes the composite primary key as `prefix-block-txIdx-logIdx` where `prefix` is the leading
+ * segment (`tag` for private; `contract-tag` for public) and the trailing triple is fixed-width
+ * 8-char zero-padded hex so byte-order matches `(blockNumber, txIndexWithinBlock, logIndexWithinTx)`.
+ */
+export declare function encodeKey(prefix: string, blockNumber: number, txIndex: number, logIndex: number): string;
+/**
+ * Decodes the trailing `(blockNumber, txIndexWithinBlock, logIndexWithinTx)` triple from a composite
+ * key. The leading prefix segments are ignored — we only ever read them off the input query, never
+ * back off the key.
+ */
+export declare function decodeKeyTail(key: string): ParsedKeyTail;
+/**
+ * Exclusive end bound for a `(contract, tag)`-prefix scan. With an `upperBlockExclusive` we cut at
+ * `(prefix, upper, 0, 0)`. With no bound we use `prefix + '-' + HEX_SENTINEL`, which sorts strictly
+ * after every real key under `prefix` (`g` is greater than any hex digit).
+ */
+export declare function endOfTagRange(prefix: string, upperBlockExclusive: number | undefined): string;
+/**
+ * Exclusive end bound for a tx-strict scan: every key strictly inside `(prefix, txBlk, txIdx, *)`.
+ * `prefix-block-txIdx-` followed by the hex sentinel is the first key past every real logIndex for
+ * this tx and strictly less than the next tx's first key.
+ */
+export declare function endOfTxRange(prefix: string, txBlk: number, txIdx: number): string;
+/**
+ * Returns the smallest string strictly greater than a fully-encoded composite key. The encoded key
+ * ends in a hex digit, and `'g'` sorts strictly after any hex digit, so appending `'g'` is the
+ * smallest possible successor in our key alphabet. Used to turn an inclusive cursor into an
+ * exclusive `start`.
+ */
+export declare function incKey(key: string): string;
+export declare function encodeValue(value: StoredLogValue): Buffer;
+export declare function decodeValue(buffer: Buffer | Uint8Array): StoredLogValue;
+/** Encodes the public-log key prefix as `contractHex-tagHex`. */
+export declare function encodePublicPrefix(contractHex: string, tagHex: string): string;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoibG9nX3N0b3JlX2NvZGVjLmQudHMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvc3RvcmUvbG9nX3N0b3JlX2NvZGVjLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sRUFBRSxXQUFXLEVBQUUsTUFBTSxpQ0FBaUMsQ0FBQztBQUM5RCxPQUFPLEVBQUUsRUFBRSxFQUFFLE1BQU0sZ0NBQWdDLENBQUM7QUFDcEQsT0FBTyxFQUFFLFNBQVMsRUFBRSxNQUFNLHFCQUFxQixDQUFDO0FBQ2hELE9BQU8sRUFBRSxNQUFNLEVBQUUsTUFBTSxrQkFBa0IsQ0FBQztBQUUxQyxlQUFPLE1BQU0sZUFBZSxJQUFJLENBQUM7QUFDakMsZUFBTyxNQUFNLEdBQUcsTUFBTSxDQUFDO0FBRXZCOzs7O0dBSUc7QUFDSCxlQUFPLE1BQU0sWUFBWSxNQUFNLENBQUM7QUFFaEMsTUFBTSxNQUFNLGFBQWEsR0FBRztJQUMxQixXQUFXLEVBQUUsV0FBVyxDQUFDO0lBQ3pCLGtCQUFrQixFQUFFLE1BQU0sQ0FBQztJQUMzQixnQkFBZ0IsRUFBRSxNQUFNLENBQUM7Q0FDMUIsQ0FBQztBQUVGOzs7O0dBSUc7QUFDSCxNQUFNLE1BQU0sY0FBYyxHQUFHO0lBQzNCLE1BQU0sRUFBRSxNQUFNLENBQUM7SUFDZixTQUFTLEVBQUUsU0FBUyxDQUFDO0lBQ3JCLGNBQWMsRUFBRSxNQUFNLENBQUM7SUFDdkIsT0FBTyxFQUFFLEVBQUUsRUFBRSxDQUFDO0NBQ2YsQ0FBQztBQUVGLDhGQUE4RjtBQUM5Rix3QkFBZ0IsUUFBUSxDQUFDLEtBQUssRUFBRSxFQUFFLEdBQUc7SUFBRSxRQUFRLEVBQUUsTUFBTSxNQUFNLENBQUE7Q0FBRSxHQUFHLE1BQU0sQ0FHdkU7QUFFRDs7Ozs7O0dBTUc7QUFDSCx3QkFBZ0IsWUFBWSxDQUFDLE1BQU0sRUFBRSxFQUFFLEVBQUUsR0FBRyxNQUFNLENBRWpEO0FBRUQsK0dBQStHO0FBQy9HLHdCQUFnQixNQUFNLENBQUMsQ0FBQyxFQUFFLE1BQU0sR0FBRyxNQUFNLENBRXhDO0FBRUQ7Ozs7R0FJRztBQUNILHdCQUFnQixTQUFTLENBQUMsTUFBTSxFQUFFLE1BQU0sRUFBRSxXQUFXLEVBQUUsTUFBTSxFQUFFLE9BQU8sRUFBRSxNQUFNLEVBQUUsUUFBUSxFQUFFLE1BQU0sR0FBRyxNQUFNLENBRXhHO0FBRUQ7Ozs7R0FJRztBQUNILHdCQUFnQixhQUFhLENBQUMsR0FBRyxFQUFFLE1BQU0sR0FBRyxhQUFhLENBUXhEO0FBRUQ7Ozs7R0FJRztBQUNILHdCQUFnQixhQUFhLENBQUMsTUFBTSxFQUFFLE1BQU0sRUFBRSxtQkFBbUIsRUFBRSxNQUFNLEdBQUcsU0FBUyxHQUFHLE1BQU0sQ0FLN0Y7QUFFRDs7OztHQUlHO0FBQ0gsd0JBQWdCLFlBQVksQ0FBQyxNQUFNLEVBQUUsTUFBTSxFQUFFLEtBQUssRUFBRSxNQUFNLEVBQUUsS0FBSyxFQUFFLE1BQU0sR0FBRyxNQUFNLENBRWpGO0FBRUQ7Ozs7O0dBS0c7QUFDSCx3QkFBZ0IsTUFBTSxDQUFDLEdBQUcsRUFBRSxNQUFNLEdBQUcsTUFBTSxDQUUxQztBQUVELHdCQUFnQixXQUFXLENBQUMsS0FBSyxFQUFFLGNBQWMsR0FBRyxNQUFNLENBUXpEO0FBRUQsd0JBQWdCLFdBQVcsQ0FBQyxNQUFNLEVBQUUsTUFBTSxHQUFHLFVBQVUsR0FBRyxjQUFjLENBaUJ2RTtBQUVELGlFQUFpRTtBQUNqRSx3QkFBZ0Isa0JBQWtCLENBQUMsV0FBVyxFQUFFLE1BQU0sRUFBRSxNQUFNLEVBQUUsTUFBTSxHQUFHLE1BQU0sQ0FFOUUifQ==

package/dest/store/log_store_codec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"log_store_codec.d.ts","sourceRoot":"","sources":["../../src/store/log_store_codec.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,iCAAiC,CAAC;AAC9D,OAAO,EAAE,EAAE,EAAE,MAAM,gCAAgC,CAAC;AACpD,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAChD,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAE1C,eAAO,MAAM,eAAe,IAAI,CAAC;AACjC,eAAO,MAAM,GAAG,MAAM,CAAC;AAEvB;;;;GAIG;AACH,eAAO,MAAM,YAAY,MAAM,CAAC;AAEhC,MAAM,MAAM,aAAa,GAAG;IAC1B,WAAW,EAAE,WAAW,CAAC;IACzB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,gBAAgB,EAAE,MAAM,CAAC;CAC1B,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,SAAS,CAAC;IACrB,cAAc,EAAE,MAAM,CAAC;IACvB,OAAO,EAAE,EAAE,EAAE,CAAC;CACf,CAAC;AAEF,8FAA8F;AAC9F,wBAAgB,QAAQ,CAAC,KAAK,EAAE,EAAE,GAAG;IAAE,QAAQ,EAAE,MAAM,MAAM,CAAA;CAAE,GAAG,MAAM,CAGvE;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,EAAE,EAAE,GAAG,MAAM,CAEjD;AAED,+GAA+G;AAC/G,wBAAgB,MAAM,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAExC;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAExG;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa,CAQxD;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,mBAAmB,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAK7F;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAEjF;AAED;;;;;GAKG;AACH,wBAAgB,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE1C;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,cAAc,GAAG,MAAM,CAQzD;AAED,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,GAAG,cAAc,CAiBvE;AAED,iEAAiE;AACjE,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAE9E"}

package/dest/store/log_store_codec.js

@@ -0,0 +1,110 @@
+import { BlockNumber } from '@aztec/foundation/branded-types';
+import { Fr } from '@aztec/foundation/curves/bn254';
+import { BlockHash } from '@aztec/stdlib/block';
+import { TxHash } from '@aztec/stdlib/tx';
+export const NUMERIC_HEX_LEN = 8;
+export const SEP = '-';
+/**
+ * Sentinel appended after a numeric hex segment to build an end bound strictly greater than any
+ * real key for that namespace. `'g'` sorts lexicographically after every hex digit (`0`-`9`, `a`-`f`),
+ * so `prefix + '-g'` is a clean exclusive upper bound.
+ */ export const HEX_SENTINEL = 'g';
+/** Returns the 64-char lowercase hex representation of a field, stripping the `0x` prefix. */ export function fieldHex(value) {
+    // Fr.toString() and AztecAddress.toString() both return `0x` + 64 lowercase hex chars.
+    return value.toString().slice(2);
+}
+/**
+ * Tag prefix for a log: the hex of its first field, or the empty string when the log carries no fields.
+ * A protocol-valid public log can have zero fields (e.g. a raw AVM `EMITPUBLICLOG` with `logSize = 0`),
+ * which has no tag to index by. Encoding it under the empty tag keeps it retrievable via the per-block
+ * read (and droppable on reorg) while never matching a real 64-hex-char tag query — instead of reading
+ * `fields[0]` off an empty array and aborting the whole block-ingestion transaction.
+ */ export function tagHexForLog(fields) {
+    return fields.length > 0 ? fieldHex(fields[0]) : '';
+}
+/** Encodes a number as 8-char zero-padded lowercase hex (matches a u32 big-endian byte buffer's lex order). */ export function u32Hex(n) {
+    return n.toString(16).padStart(NUMERIC_HEX_LEN, '0');
+}
+/**
+ * Encodes the composite primary key as `prefix-block-txIdx-logIdx` where `prefix` is the leading
+ * segment (`tag` for private; `contract-tag` for public) and the trailing triple is fixed-width
+ * 8-char zero-padded hex so byte-order matches `(blockNumber, txIndexWithinBlock, logIndexWithinTx)`.
+ */ export function encodeKey(prefix, blockNumber, txIndex, logIndex) {
+    return `${prefix}${SEP}${u32Hex(blockNumber)}${SEP}${u32Hex(txIndex)}${SEP}${u32Hex(logIndex)}`;
+}
+/**
+ * Decodes the trailing `(blockNumber, txIndexWithinBlock, logIndexWithinTx)` triple from a composite
+ * key. The leading prefix segments are ignored — we only ever read them off the input query, never
+ * back off the key.
+ */ export function decodeKeyTail(key) {
+    const parts = key.split(SEP);
+    const len = parts.length;
+    return {
+        blockNumber: BlockNumber(parseInt(parts[len - 3], 16)),
+        txIndexWithinBlock: parseInt(parts[len - 2], 16),
+        logIndexWithinTx: parseInt(parts[len - 1], 16)
+    };
+}
+/**
+ * Exclusive end bound for a `(contract, tag)`-prefix scan. With an `upperBlockExclusive` we cut at
+ * `(prefix, upper, 0, 0)`. With no bound we use `prefix + '-' + HEX_SENTINEL`, which sorts strictly
+ * after every real key under `prefix` (`g` is greater than any hex digit).
+ */ export function endOfTagRange(prefix, upperBlockExclusive) {
+    if (upperBlockExclusive === undefined) {
+        return `${prefix}${SEP}${HEX_SENTINEL}`;
+    }
+    return encodeKey(prefix, upperBlockExclusive, 0, 0);
+}
+/**
+ * Exclusive end bound for a tx-strict scan: every key strictly inside `(prefix, txBlk, txIdx, *)`.
+ * `prefix-block-txIdx-` followed by the hex sentinel is the first key past every real logIndex for
+ * this tx and strictly less than the next tx's first key.
+ */ export function endOfTxRange(prefix, txBlk, txIdx) {
+    return `${prefix}${SEP}${u32Hex(txBlk)}${SEP}${u32Hex(txIdx)}${SEP}${HEX_SENTINEL}`;
+}
+/**
+ * Returns the smallest string strictly greater than a fully-encoded composite key. The encoded key
+ * ends in a hex digit, and `'g'` sorts strictly after any hex digit, so appending `'g'` is the
+ * smallest possible successor in our key alphabet. Used to turn an inclusive cursor into an
+ * exclusive `start`.
+ */ export function incKey(key) {
+    return key + HEX_SENTINEL;
+}
+export function encodeValue(value) {
+    const head = Buffer.allocUnsafe(32 + 32 + 8 + 4);
+    value.txHash.toBuffer().copy(head, 0);
+    value.blockHash.toBuffer().copy(head, 32);
+    head.writeBigUInt64BE(value.blockTimestamp, 64);
+    head.writeUInt32BE(value.logData.length, 72);
+    const fieldBufs = value.logData.map((f)=>f.toBuffer());
+    return Buffer.concat([
+        head,
+        ...fieldBufs
+    ]);
+}
+export function decodeValue(buffer) {
+    const buf = Buffer.isBuffer(buffer) ? buffer : Buffer.from(buffer.buffer, buffer.byteOffset, buffer.byteLength);
+    let off = 0;
+    const txHash = TxHash.fromBuffer(buf.subarray(off, off + 32));
+    off += 32;
+    const blockHash = BlockHash.fromBuffer(buf.subarray(off, off + 32));
+    off += 32;
+    const blockTimestamp = buf.readBigUInt64BE(off);
+    off += 8;
+    const logDataLen = buf.readUInt32BE(off);
+    off += 4;
+    const logData = new Array(logDataLen);
+    for(let i = 0; i < logDataLen; i++){
+        logData[i] = Fr.fromBuffer(buf.subarray(off, off + 32));
+        off += 32;
+    }
+    return {
+        txHash,
+        blockHash,
+        blockTimestamp,
+        logData
+    };
+}
+/** Encodes the public-log key prefix as `contractHex-tagHex`. */ export function encodePublicPrefix(contractHex, tagHex) {
+    return `${contractHex}${SEP}${tagHex}`;
+}

package/dest/store/message_store.d.ts

@@ -0,0 +1,50 @@
+import type { L1BlockId } from '@aztec/ethereum/l1-types';
+import { CheckpointNumber } from '@aztec/foundation/branded-types';
+import { Fr } from '@aztec/foundation/curves/bn254';
+import { type AztecAsyncKVStore, type CustomRange } from '@aztec/kv-store';
+import { type InboxMessage } from '../structs/inbox_message.js';
+export declare class MessageStoreError extends Error {
+    readonly inboxMessage: InboxMessage;
+    constructor(message: string, inboxMessage: InboxMessage);
+}
+export declare class MessageStore {
+    #private;
+    private db;
+    constructor(db: AztecAsyncKVStore);
+    getTotalL1ToL2MessageCount(): Promise<bigint>;
+    /** Gets the last L1 block synced. */
+    getSynchedL1Block(): Promise<L1BlockId | undefined>;
+    /** Sets the last L1 block synced */
+    setSynchedL1Block(l1Block: L1BlockId): Promise<void>;
+    /** Gets the L1 finalized block as of the last successful message sync. */
+    getMessagesFinalizedL1Block(): Promise<L1BlockId | undefined>;
+    private maybeAdvanceFinalizedL1Block;
+    /**
+     * Append L1 to L2 messages to the store.
+     * Requires new messages to be in order and strictly after the last message added.
+     * Throws if out of order messages are added or if the rolling hash is invalid.
+     */
+    addL1ToL2Messages(messages: InboxMessage[]): Promise<void>;
+    /**
+     * Gets the L1 to L2 message index in the L1 to L2 message tree.
+     * @param l1ToL2Message - The L1 to L2 message.
+     * @returns The index of the L1 to L2 message in the L1 to L2 message tree (undefined if not found).
+     */
+    getL1ToL2MessageIndex(l1ToL2Message: Fr): Promise<bigint | undefined>;
+    getLastMessage(): Promise<InboxMessage | undefined>;
+    /** Returns the inbox tree-in-progress checkpoint number from L1, or undefined if not yet set. */
+    getInboxTreeInProgress(): Promise<bigint | undefined>;
+    /**
+     * Atomically updates the message sync state: the L1 sync point, the inbox tree-in-progress marker, and
+     * (optionally) the L1 finalized block as of this sync. The finalized block is advanced monotonically.
+     */
+    setMessageSyncState(l1Block: L1BlockId, treeInProgress: bigint | undefined, finalizedL1Block?: L1BlockId): Promise<void>;
+    getL1ToL2Messages(checkpointNumber: CheckpointNumber): Promise<Fr[]>;
+    iterateL1ToL2Messages(range?: CustomRange<bigint>): AsyncIterableIterator<InboxMessage>;
+    removeL1ToL2Messages(startIndex: bigint): Promise<void>;
+    rollbackL1ToL2MessagesToCheckpoint(targetCheckpointNumber: CheckpointNumber): Promise<void>;
+    private indexToKey;
+    private leafToIndexKey;
+    private increaseTotalMessageCount;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoibWVzc2FnZV9zdG9yZS5kLnRzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vc3JjL3N0b3JlL21lc3NhZ2Vfc3RvcmUudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxLQUFLLEVBQUUsU0FBUyxFQUFFLE1BQU0sMEJBQTBCLENBQUM7QUFDMUQsT0FBTyxFQUFFLGdCQUFnQixFQUFFLE1BQU0saUNBQWlDLENBQUM7QUFFbkUsT0FBTyxFQUFFLEVBQUUsRUFBRSxNQUFNLGdDQUFnQyxDQUFDO0FBSXBELE9BQU8sRUFDTCxLQUFLLGlCQUFpQixFQUd0QixLQUFLLFdBQVcsRUFFakIsTUFBTSxpQkFBaUIsQ0FBQztBQUl6QixPQUFPLEVBQ0wsS0FBSyxZQUFZLEVBSWxCLE1BQU0sNkJBQTZCLENBQUM7QUFFckMscUJBQWEsaUJBQWtCLFNBQVEsS0FBSzthQUd4QixZQUFZLEVBQUUsWUFBWTtJQUY1QyxZQUNFLE9BQU8sRUFBRSxNQUFNLEVBQ0MsWUFBWSxFQUFFLFlBQVksRUFJM0M7Q0FDRjtBQUVELHFCQUFhLFlBQVk7O0lBZ0JYLE9BQU8sQ0FBQyxFQUFFO0lBQXRCLFlBQW9CLEVBQUUsRUFBRSxpQkFBaUIsRUFPeEM7SUFFWSwwQkFBMEIsSUFBSSxPQUFPLENBQUMsTUFBTSxDQUFDLENBRXpEO0lBRUQscUNBQXFDO0lBQ3hCLGlCQUFpQixJQUFJLE9BQU8sQ0FBQyxTQUFTLEdBQUcsU0FBUyxDQUFDLENBUS9EO0lBRUQsb0NBQW9DO0lBQ3ZCLGlCQUFpQixDQUFDLE9BQU8sRUFBRSxTQUFTLEdBQUcsT0FBTyxDQUFDLElBQUksQ0FBQyxDQUdoRTtJQUVELDBFQUEwRTtJQUM3RCwyQkFBMkIsSUFBSSxPQUFPLENBQUMsU0FBUyxHQUFHLFNBQVMsQ0FBQyxDQU96RTtZQUdhLDRCQUE0QjtJQVMxQzs7OztPQUlHO0lBQ0ksaUJBQWlCLENBQUMsUUFBUSxFQUFFLFlBQVksRUFBRSxHQUFHLE9BQU8sQ0FBQyxJQUFJLENBQUMsQ0FvRmhFO0lBRUQ7Ozs7T0FJRztJQUNJLHFCQUFxQixDQUFDLGFBQWEsRUFBRSxFQUFFLEdBQUcsT0FBTyxDQUFDLE1BQU0sR0FBRyxTQUFTLENBQUMsQ0FFM0U7SUFFWSxjQUFjLElBQUksT0FBTyxDQUFDLFlBQVksR0FBRyxTQUFTLENBQUMsQ0FHL0Q7SUFFRCxpR0FBaUc7SUFDMUYsc0JBQXNCLElBQUksT0FBTyxDQUFDLE1BQU0sR0FBRyxTQUFTLENBQUMsQ0FFM0Q7SUFFRDs7O09BR0c7SUFDSSxtQkFBbUIsQ0FDeEIsT0FBTyxFQUFFLFNBQVMsRUFDbEIsY0FBYyxFQUFFLE1BQU0sR0FBRyxTQUFTLEVBQ2xDLGdCQUFnQixDQUFDLEVBQUUsU0FBUyxHQUMzQixPQUFPLENBQUMsSUFBSSxDQUFDLENBWWY7SUFFWSxpQkFBaUIsQ0FBQyxnQkFBZ0IsRUFBRSxnQkFBZ0IsR0FBRyxPQUFPLENBQUMsRUFBRSxFQUFFLENBQUMsQ0E0QmhGO0lBRWEscUJBQXFCLENBQUMsS0FBSyxHQUFFLFdBQVcsQ0FBQyxNQUFNLENBQU0sR0FBRyxxQkFBcUIsQ0FBQyxZQUFZLENBQUMsQ0FLeEc7SUFFTSxvQkFBb0IsQ0FBQyxVQUFVLEVBQUUsTUFBTSxHQUFHLE9BQU8sQ0FBQyxJQUFJLENBQUMsQ0FnQjdEO0lBRU0sa0NBQWtDLENBQUMsc0JBQXNCLEVBQUUsZ0JBQWdCLEdBQUcsT0FBTyxDQUFDLElBQUksQ0FBQyxDQUlqRztJQUVELE9BQU8sQ0FBQyxVQUFVO0lBSWxCLE9BQU8sQ0FBQyxjQUFjO1lBSVIseUJBQXlCO0NBU3hDIn0=

package/dest/store/message_store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"message_store.d.ts","sourceRoot":"","sources":["../../src/store/message_store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAC1D,OAAO,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AAEnE,OAAO,EAAE,EAAE,EAAE,MAAM,gCAAgC,CAAC;AAIpD,OAAO,EACL,KAAK,iBAAiB,EAGtB,KAAK,WAAW,EAEjB,MAAM,iBAAiB,CAAC;AAIzB,OAAO,EACL,KAAK,YAAY,EAIlB,MAAM,6BAA6B,CAAC;AAErC,qBAAa,iBAAkB,SAAQ,KAAK;aAGxB,YAAY,EAAE,YAAY;IAF5C,YACE,OAAO,EAAE,MAAM,EACC,YAAY,EAAE,YAAY,EAI3C;CACF;AAED,qBAAa,YAAY;;IAgBX,OAAO,CAAC,EAAE;IAAtB,YAAoB,EAAE,EAAE,iBAAiB,EAOxC;IAEY,0BAA0B,IAAI,OAAO,CAAC,MAAM,CAAC,CAEzD;IAED,qCAAqC;IACxB,iBAAiB,IAAI,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC,CAQ/D;IAED,oCAAoC;IACvB,iBAAiB,CAAC,OAAO,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAGhE;IAED,0EAA0E;IAC7D,2BAA2B,IAAI,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC,CAOzE;YAGa,4BAA4B;IAS1C;;;;OAIG;IACI,iBAAiB,CAAC,QAAQ,EAAE,YAAY,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAoFhE;IAED;;;;OAIG;IACI,qBAAqB,CAAC,aAAa,EAAE,EAAE,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAE3E;IAEY,cAAc,IAAI,OAAO,CAAC,YAAY,GAAG,SAAS,CAAC,CAG/D;IAED,iGAAiG;IAC1F,sBAAsB,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAE3D;IAED;;;OAGG;IACI,mBAAmB,CACxB,OAAO,EAAE,SAAS,EAClB,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,gBAAgB,CAAC,EAAE,SAAS,GAC3B,OAAO,CAAC,IAAI,CAAC,CAYf;IAEY,iBAAiB,CAAC,gBAAgB,EAAE,gBAAgB,GAAG,OAAO,CAAC,EAAE,EAAE,CAAC,CA4BhF;IAEa,qBAAqB,CAAC,KAAK,GAAE,WAAW,CAAC,MAAM,CAAM,GAAG,qBAAqB,CAAC,YAAY,CAAC,CAKxG;IAEM,oBAAoB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAgB7D;IAEM,kCAAkC,CAAC,sBAAsB,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAIjG;IAED,OAAO,CAAC,UAAU;IAIlB,OAAO,CAAC,cAAc;YAIR,yBAAyB;CASxC"}