@aztec/pxe 0.0.1-commit.9593d84 → 0.0.1-commit.96bb3f7

package/src/storage/{address_data_provider/address_data_provider.ts → address_store/address_store.ts}

@@ -3,7 +3,7 @@ import type { AztecAsyncArray, AztecAsyncKVStore, AztecAsyncMap } from '@aztec/k
 import type { AztecAddress } from '@aztec/stdlib/aztec-address';
 import { CompleteAddress } from '@aztec/stdlib/contract';
 
-export class AddressDataProvider {
+export class AddressStore {
   #store: AztecAsyncKVStore;
   #completeAddresses: AztecAsyncArray<Buffer>;
   #completeAddressIndex: AztecAsyncMap<string, number>;

package/src/storage/address_store/index.ts

@@ -0,0 +1 @@
+export { AddressStore } from './address_store.js';

package/src/storage/{sync_data_provider/sync_data_provider.ts → anchor_block_store/anchor_block_store.ts}

@@ -1,7 +1,7 @@
 import type { AztecAsyncKVStore, AztecAsyncSingleton } from '@aztec/kv-store';
 import { BlockHeader } from '@aztec/stdlib/tx';
 
-export class SyncDataProvider {
+export class AnchorBlockStore {
   #store: AztecAsyncKVStore;
   #synchronizedHeader: AztecAsyncSingleton<Buffer>;
 
@@ -14,19 +14,10 @@ export class SyncDataProvider {
     await this.#synchronizedHeader.set(header.toBuffer());
   }
 
-  async getBlockNumber(): Promise<number> {
-    const headerBuffer = await this.#synchronizedHeader.getAsync();
-    if (!headerBuffer) {
-      throw new Error(`Trying to get block number with a not-yet-synchronized PXE - this should never happen`);
-    }
-
-    return BlockHeader.fromBuffer(headerBuffer).globalVariables.blockNumber;
-  }
-
   async getBlockHeader(): Promise<BlockHeader> {
     const headerBuffer = await this.#synchronizedHeader.getAsync();
     if (!headerBuffer) {
-      throw new Error(`Header not set`);
+      throw new Error(`Trying to get block header with a not-yet-synchronized PXE - this should never happen`);
     }
 
     return BlockHeader.fromBuffer(headerBuffer);

package/src/storage/anchor_block_store/index.ts

@@ -0,0 +1 @@
+export { AnchorBlockStore } from './anchor_block_store.js';

package/src/storage/{capsule_data_provider/capsule_data_provider.ts → capsule_store/capsule_store.ts}

@@ -1,9 +1,9 @@
-import { Fr } from '@aztec/foundation/fields';
+import { Fr } from '@aztec/foundation/curves/bn254';
 import { type Logger, createLogger } from '@aztec/foundation/log';
 import type { AztecAsyncKVStore, AztecAsyncMap } from '@aztec/kv-store';
 import type { AztecAddress } from '@aztec/stdlib/aztec-address';
 
-export class CapsuleDataProvider {
+export class CapsuleStore {
   #store: AztecAsyncKVStore;
 
   // Arbitrary data stored by contracts. Key is computed as `${contractAddress}:${key}`
@@ -19,10 +19,26 @@ export class CapsuleDataProvider {
     this.logger = createLogger('pxe:capsule-data-provider');
   }
 
+  /**
+   * Stores arbitrary information in a per-contract non-volatile database, which can later be retrieved with `loadCapsule`.
+   * * If data was already stored at this slot, it is overwritten.
+   * @param contractAddress - The contract address to scope the data under.
+   * @param slot - The slot in the database in which to store the value. Slots need not be contiguous.
+   * @param capsule - An array of field elements representing the capsule.
+   * @remarks A capsule is a "blob" of data that is passed to the contract through an oracle. It works similarly
+   * to public contract storage in that it's indexed by the contract address and storage slot but instead of the global
+   * network state it's backed by local PXE db.
+   */
   async storeCapsule(contractAddress: AztecAddress, slot: Fr, capsule: Fr[]): Promise<void> {
     await this.#capsules.set(dbSlotToKey(contractAddress, slot), Buffer.concat(capsule.map(value => value.toBuffer())));
   }
 
+  /**
+   * Returns data previously stored via `storeCapsule` in the per-contract non-volatile database.
+   * @param contractAddress - The contract address under which the data is scoped.
+   * @param slot - The slot in the database to read.
+   * @returns The stored data or `null` if no data is stored under the slot.
+   */
   async loadCapsule(contractAddress: AztecAddress, slot: Fr): Promise<Fr[] | null> {
     const dataBuffer = await this.#capsules.getAsync(dbSlotToKey(contractAddress, slot));
     if (!dataBuffer) {
@@ -36,10 +52,26 @@ export class CapsuleDataProvider {
     return capsule;
   }
 
+  /**
+   * Deletes data in the per-contract non-volatile database. Does nothing if no data was present.
+   * @param contractAddress - The contract address under which the data is scoped.
+   * @param slot - The slot in the database to delete.
+   */
   async deleteCapsule(contractAddress: AztecAddress, slot: Fr): Promise<void> {
     await this.#capsules.delete(dbSlotToKey(contractAddress, slot));
   }
 
+  /**
+   * Copies a number of contiguous entries in the per-contract non-volatile database. This allows for efficient data
+   * structures by avoiding repeated calls to `loadCapsule` and `storeCapsule`.
+   * Supports overlapping source and destination regions (which will result in the overlapped source values being
+   * overwritten). All copied slots must exist in the database (i.e. have been stored and not deleted)
+   *
+   * @param contractAddress - The contract address under which the data is scoped.
+   * @param srcSlot - The first slot to copy from.
+   * @param dstSlot - The first slot to copy to.
+   * @param numEntries - The number of entries to copy.
+   */
   copyCapsule(contractAddress: AztecAddress, srcSlot: Fr, dstSlot: Fr, numEntries: number): Promise<void> {
     return this.#store.transactionAsync(async () => {
       // In order to support overlapping source and destination regions, we need to check the relative positions of source

package/src/storage/capsule_store/index.ts

@@ -0,0 +1 @@
+export { CapsuleStore } from './capsule_store.js';

package/src/storage/{contract_data_provider/contract_data_provider.ts → contract_store/contract_store.ts}

@@ -1,18 +1,21 @@
 import type { FUNCTION_TREE_HEIGHT } from '@aztec/constants';
-import type { Fr } from '@aztec/foundation/fields';
+import type { Fr } from '@aztec/foundation/curves/bn254';
 import { toArray } from '@aztec/foundation/iterable';
 import type { MembershipWitness } from '@aztec/foundation/trees';
 import type { AztecAsyncKVStore, AztecAsyncMap } from '@aztec/kv-store';
+import { isProtocolContract } from '@aztec/protocol-contracts';
 import {
   type ContractArtifact,
   type FunctionAbi,
   type FunctionArtifact,
   type FunctionArtifactWithContractName,
+  FunctionCall,
   type FunctionDebugMetadata,
   FunctionSelector,
   FunctionType,
   contractArtifactFromBuffer,
   contractArtifactToBuffer,
+  encodeArguments,
   getFunctionDebugMetadata,
 } from '@aztec/stdlib/abi';
 import { AztecAddress } from '@aztec/stdlib/aztec-address';
@@ -26,13 +29,13 @@ import {
 import { PrivateFunctionsTree } from './private_functions_tree.js';
 
 /**
- * ContractDataProvider serves as a data manager and retriever for Aztec.nr contracts.
+ * ContractStore serves as a data manager and retriever for Aztec.nr contracts.
  * It provides methods to obtain contract addresses, function ABI, bytecode, and membership witnesses
  * from a given contract address and function selector. The class maintains a cache of ContractTree instances
  * to efficiently serve the requested data. It interacts with the ContractDatabase and AztecNode to fetch
  * the required information and facilitate cryptographic proof generation.
  */
-export class ContractDataProvider {
+export class ContractStore {
   /** Map from contract class id to private function tree. */
   // TODO: Update it to be LRU cache so that it doesn't keep all the data all the time.
   #privateFunctionTrees: Map<string, PrivateFunctionsTree> = new Map();
@@ -176,6 +179,21 @@ export class ContractDataProvider {
     return fnArtifact && { ...fnArtifact, contractName: artifact.name };
   }
 
+  public async getFunctionArtifactWithDebugMetadata(
+    contractAddress: AztecAddress,
+    selector: FunctionSelector,
+  ): Promise<FunctionArtifactWithContractName> {
+    const artifact = await this.getFunctionArtifact(contractAddress, selector);
+    if (!artifact) {
+      throw new Error(`Function artifact not found for contract ${contractAddress} and selector ${selector}.`);
+    }
+    const debug = await this.getFunctionDebugMetadata(contractAddress, selector);
+    return {
+      ...artifact,
+      debug,
+    };
+  }
+
   public async getPublicFunctionArtifact(
     contractAddress: AztecAddress,
   ): Promise<FunctionArtifactWithContractName | undefined> {
@@ -274,4 +292,48 @@ export class ContractDataProvider {
       }
     }
   }
+
+  public async getFunctionCall(functionName: string, args: any[], to: AztecAddress): Promise<FunctionCall> {
+    const contract = await this.getContract(to);
+    if (!contract) {
+      throw new Error(
+        `Unknown contract ${to}: add it to PXE by calling server.addContracts(...).\nSee docs for context: https://docs.aztec.network/developers/resources/debugging/aztecnr-errors#unknown-contract-0x0-add-it-to-pxe-by-calling-serveraddcontracts`,
+      );
+    }
+
+    const functionDao = contract.functions.find(f => f.name === functionName);
+    if (!functionDao) {
+      throw new Error(`Unknown function ${functionName} in contract ${contract.name}.`);
+    }
+
+    return {
+      name: functionDao.name,
+      args: encodeArguments(functionDao, args),
+      selector: await FunctionSelector.fromNameAndParameters(functionDao.name, functionDao.parameters),
+      type: functionDao.functionType,
+      to,
+      hideMsgSender: false,
+      isStatic: functionDao.isStatic,
+      returnTypes: functionDao.returnTypes,
+    };
+  }
+
+  // Synchronize target contract data
+  public async syncPrivateState(
+    contractAddress: AztecAddress,
+    functionToInvokeAfterSync: FunctionSelector | null,
+    utilityExecutor: (privateSyncCall: FunctionCall) => Promise<any>,
+  ) {
+    // Protocol contracts don't have private state to sync
+    if (!isProtocolContract(contractAddress)) {
+      const syncPrivateStateFunctionCall = await this.getFunctionCall('sync_private_state', [], contractAddress);
+      if (functionToInvokeAfterSync && functionToInvokeAfterSync.equals(syncPrivateStateFunctionCall.selector)) {
+        throw new Error(
+          'Forbidden `sync_private_state` invocation. `sync_private_state` can only be invoked by PXE, manual execution can lead to inconsistencies.',
+        );
+      }
+
+      return utilityExecutor(syncPrivateStateFunctionCall);
+    }
+  }
 }

package/src/storage/contract_store/index.ts

@@ -0,0 +1 @@
+export { ContractStore } from './contract_store.js';

package/src/storage/{contract_data_provider → contract_store}/private_functions_tree.ts

@@ -1,5 +1,5 @@
 import { FUNCTION_TREE_HEIGHT } from '@aztec/constants';
-import { Fr } from '@aztec/foundation/fields';
+import { Fr } from '@aztec/foundation/curves/bn254';
 import { assertLength } from '@aztec/foundation/serialize';
 import { MembershipWitness, type MerkleTree } from '@aztec/foundation/trees';
 import { type ContractArtifact, FunctionSelector, FunctionType } from '@aztec/stdlib/abi';

package/src/storage/index.ts

@@ -1,8 +1,8 @@
-export * from './address_data_provider/index.js';
-export * from './capsule_data_provider/index.js';
-export * from './contract_data_provider/index.js';
-export * from './note_data_provider/index.js';
-export * from './sync_data_provider/index.js';
-export * from './tagging_data_provider/index.js';
+export * from './address_store/index.js';
+export * from './capsule_store/index.js';
+export * from './contract_store/index.js';
+export * from './note_store/index.js';
+export * from './anchor_block_store/index.js';
+export * from './tagging_store/index.js';
 export * from './metadata.js';
-export * from './private_event_data_provider/private_event_data_provider.js';
+export * from './private_event_store/private_event_store.js';

package/src/storage/note_store/index.ts

@@ -0,0 +1,2 @@
+export { NoteDao } from '@aztec/stdlib/note';
+export { NoteStore } from './note_store.js';

package/src/storage/{note_data_provider/note_data_provider.ts → note_store/note_store.ts}

@@ -1,19 +1,19 @@
 import { toBufferBE } from '@aztec/foundation/bigint-buffer';
-import type { Fr } from '@aztec/foundation/fields';
+import type { Fr } from '@aztec/foundation/curves/bn254';
 import { toArray } from '@aztec/foundation/iterable';
 import type { AztecAsyncKVStore, AztecAsyncMap, AztecAsyncMultiMap } from '@aztec/kv-store';
 import { AztecAddress } from '@aztec/stdlib/aztec-address';
-import type { InBlock } from '@aztec/stdlib/block';
+import type { DataInBlock } from '@aztec/stdlib/block';
 import { NoteStatus, type NotesFilter } from '@aztec/stdlib/note';
 import { NoteDao } from '@aztec/stdlib/note';
 
 /**
- * NoteDataProvider manages the storage and retrieval of notes.
+ * NoteStore manages the storage and retrieval of notes.
  *
  * Notes can be active or nullified. This class processes new notes, nullifications,
  * and performs rollback handling in the case of a reorg.
  **/
-export class NoteDataProvider {
+export class NoteStore {
   #store: AztecAsyncKVStore;
   #notes: AztecAsyncMap<string, Buffer>;
   #nullifiedNotes: AztecAsyncMap<string, Buffer>;
@@ -49,16 +49,16 @@ export class NoteDataProvider {
   }
 
   /**
-   * Creates and initializes a new NoteDataProvider instance.
+   * Creates and initializes a new NoteStore instance.
    *
-   * This factory method creates a NoteDataProvider and restores any existing
+   * This factory method creates a NoteStore and restores any existing
    * scope-specific indexes from the database.
    *
    * @param store - The key-value store to use for persistence
-   * @returns Promise resolving to a fully initialized NoteDataProvider instance
+   * @returns Promise resolving to a fully initialized NoteStore instance
    */
-  public static async create(store: AztecAsyncKVStore): Promise<NoteDataProvider> {
-    const pxeDB = new NoteDataProvider(store);
+  public static async create(store: AztecAsyncKVStore): Promise<NoteStore> {
+    const pxeDB = new NoteStore(store);
     for await (const scope of pxeDB.#scopes.keysAsync()) {
       pxeDB.#notesByContractAndScope.set(scope, store.openMultiMap(`${scope}:notes_by_contract`));
       pxeDB.#notesByStorageSlotAndScope.set(scope, store.openMultiMap(`${scope}:notes_by_storage_slot`));
@@ -224,8 +224,9 @@ export class NoteDataProvider {
    * parameters.
    *
    * @param filter - Filter criteria including contractAddress (required), and optional
-   *                 storageSlot, status, scopes and siloedNullifier.
-   * @returns Promise resolving to array of NoteDao objects matching the filter
+   *                 owner, storageSlot, status, scopes, and siloedNullifier.
+   * @returns Filtered and deduplicated notes (a note might be present in multiple scopes - we ensure it is only
+   * returned once if this is the case)
    * @throws If filtering by an empty scopes array. Scopes have to be set to undefined or to a non-empty array.
    */
   async getNotes(filter: NotesFilter): Promise<NoteDao[]> {
@@ -307,6 +308,10 @@ export class NoteDataProvider {
           continue;
         }
 
+        if (filter.owner && !note.owner.equals(filter.owner)) {
+          continue;
+        }
+
         if (filter.storageSlot && !note.storageSlot.equals(filter.storageSlot!)) {
           continue;
         }
@@ -319,7 +324,15 @@ export class NoteDataProvider {
       }
     }
 
-    return result;
+    // A note might be present in multiple scopes - we ensure it is only returned once
+    const deduplicated: NoteDao[] = [];
+    for (const note of result) {
+      if (!deduplicated.some(existing => existing.equals(note))) {
+        deduplicated.push(note);
+      }
+    }
+
+    return deduplicated;
   }
 
   /**
@@ -333,7 +346,7 @@ export class NoteDataProvider {
    * @returns Promise resolving to array of nullified NoteDao objects
    * @throws Error if any nullifier is not found in the active notes
    */
-  applyNullifiers(nullifiers: InBlock<Fr>[]): Promise<NoteDao[]> {
+  applyNullifiers(nullifiers: DataInBlock<Fr>[]): Promise<NoteDao[]> {
     if (nullifiers.length === 0) {
       return Promise.resolve([]);
     }

package/src/storage/private_event_store/private_event_store.ts

@@ -0,0 +1,216 @@
+import { BlockNumber } from '@aztec/foundation/branded-types';
+import { Fr } from '@aztec/foundation/curves/bn254';
+import { createLogger } from '@aztec/foundation/log';
+import { BufferReader, serializeToBuffer } from '@aztec/foundation/serialize';
+import type { AztecAsyncKVStore, AztecAsyncMap } from '@aztec/kv-store';
+import type { EventSelector } from '@aztec/stdlib/abi';
+import type { AztecAddress } from '@aztec/stdlib/aztec-address';
+import { L2BlockHash } from '@aztec/stdlib/block';
+import { type InTx, TxHash } from '@aztec/stdlib/tx';
+
+import type { PackedPrivateEvent } from '../../pxe.js';
+
+export type PrivateEventStoreFilter = {
+  contractAddress: AztecAddress;
+  fromBlock: number;
+  toBlock: number;
+  scopes: AztecAddress[];
+  txHash?: TxHash;
+};
+
+type PrivateEventEntry = {
+  randomness: Fr; // Note that this value is currently not being returned on queries and is therefore temporarily unused
+  msgContent: Buffer;
+  eventCommitmentIndex: number;
+  l2BlockNumber: number;
+  l2BlockHash: Buffer;
+  txHash: Buffer;
+  /** The lookup key for #eventsByContractScopeSelector, used for cleanup during rollback */
+  lookupKey: string;
+};
+
+type PrivateEventMetadata = InTx & {
+  contractAddress: AztecAddress;
+  scope: AztecAddress;
+};
+
+/**
+ * Stores decrypted private event logs.
+ */
+export class PrivateEventStore {
+  #store: AztecAsyncKVStore;
+  /** Map storing the actual private event log entries, keyed by eventCommitmentIndex */
+  #eventLogs: AztecAsyncMap<number, PrivateEventEntry>;
+  /** Map from contractAddress_scope_eventSelector to eventCommitmentIndex[] for efficient lookup */
+  #eventsByContractScopeSelector: AztecAsyncMap<string, number[]>;
+  /** Map from block number to eventCommitmentIndex[] for rollback support */
+  #eventsByBlockNumber: AztecAsyncMap<number, number[]>;
+  /** Map from eventCommitmentIndex to boolean indicating if log has been seen. */
+  #seenLogs: AztecAsyncMap<number, boolean>;
+
+  logger = createLogger('private_event_store');
+
+  constructor(store: AztecAsyncKVStore) {
+    this.#store = store;
+    this.#eventLogs = this.#store.openMap('private_event_logs');
+    this.#eventsByContractScopeSelector = this.#store.openMap('events_by_contract_scope_selector');
+    this.#seenLogs = this.#store.openMap('seen_logs');
+    this.#eventsByBlockNumber = this.#store.openMap('events_by_block_number');
+  }
+
+  #keyFor(contractAddress: AztecAddress, scope: AztecAddress, eventSelector: EventSelector): string {
+    return `${contractAddress.toString()}_${scope.toString()}_${eventSelector.toString()}`;
+  }
+
+  /**
+   * Store a private event log.
+   * @param eventSelector - The event selector of the event.
+   * @param msgContent - The content of the event.
+   * @param eventCommitmentIndex - The index of the event commitment in the nullifier tree.
+   * @param metadata
+   *  contractAddress - The address of the contract that emitted the event.
+   *  scope - The address to which the event is scoped.
+   *  txHash - The transaction hash of the event log.
+   *  blockNumber - The block number in which the event was emitted.
+   */
+  storePrivateEventLog(
+    eventSelector: EventSelector,
+    randomness: Fr,
+    msgContent: Fr[],
+    eventCommitmentIndex: number,
+    metadata: PrivateEventMetadata,
+  ): Promise<void> {
+    const { contractAddress, scope, txHash, l2BlockNumber, l2BlockHash } = metadata;
+
+    return this.#store.transactionAsync(async () => {
+      const key = this.#keyFor(contractAddress, scope, eventSelector);
+
+      // Check if this exact log has already been stored using eventCommitmentIndex as unique identifier
+      const hasBeenSeen = await this.#seenLogs.getAsync(eventCommitmentIndex);
+      if (hasBeenSeen) {
+        this.logger.verbose('Ignoring duplicate event log', { txHash: txHash.toString(), eventCommitmentIndex });
+        return;
+      }
+
+      this.logger.verbose('storing private event log', { contractAddress, scope, msgContent, l2BlockNumber });
+
+      await this.#eventLogs.set(eventCommitmentIndex, {
+        randomness,
+        msgContent: serializeToBuffer(msgContent),
+        l2BlockNumber,
+        l2BlockHash: l2BlockHash.toBuffer(),
+        eventCommitmentIndex,
+        txHash: txHash.toBuffer(),
+        lookupKey: key,
+      });
+
+      const existingIndices = (await this.#eventsByContractScopeSelector.getAsync(key)) || [];
+      await this.#eventsByContractScopeSelector.set(key, [...existingIndices, eventCommitmentIndex]);
+
+      const existingBlockIndices = (await this.#eventsByBlockNumber.getAsync(l2BlockNumber)) || [];
+      await this.#eventsByBlockNumber.set(l2BlockNumber, [...existingBlockIndices, eventCommitmentIndex]);
+
+      // Mark this log as seen using eventCommitmentIndex
+      await this.#seenLogs.set(eventCommitmentIndex, true);
+    });
+  }
+
+  /**
+   * Returns the private events given search parameters.
+   * @param eventSelector - The event selector to filter by.
+   * @param filter - Filtering criteria:
+   *  contractAddress: The address of the contract to get events from.
+   *  fromBlock: The block number to search from (inclusive).
+   *  toBlock: The block number to search upto (exclusive).
+   *  scope: - The addresses that decrypted the logs.
+   * @returns - The event log contents, augmented with metadata about
+   *  the transaction and block it the event was included in .
+   */
+  public async getPrivateEvents(
+    eventSelector: EventSelector,
+    filter: PrivateEventStoreFilter,
+  ): Promise<PackedPrivateEvent[]> {
+    const events: Array<{ eventCommitmentIndex: number; event: PackedPrivateEvent }> = [];
+
+    for (const scope of filter.scopes) {
+      const key = this.#keyFor(filter.contractAddress, scope, eventSelector);
+      const eventCommitmentIndices = (await this.#eventsByContractScopeSelector.getAsync(key)) || [];
+
+      for (const eventCommitmentIndex of eventCommitmentIndices) {
+        const entry = await this.#eventLogs.getAsync(eventCommitmentIndex);
+        if (!entry || entry.l2BlockNumber < filter.fromBlock || entry.l2BlockNumber >= filter.toBlock) {
+          continue;
+        }
+
+        // Convert buffer back to Fr array
+        const reader = BufferReader.asReader(entry.msgContent);
+        const numFields = entry.msgContent.length / Fr.SIZE_IN_BYTES;
+        const msgContent = reader.readArray(numFields, Fr);
+        const txHash = TxHash.fromBuffer(entry.txHash);
+        const l2BlockHash = L2BlockHash.fromBuffer(entry.l2BlockHash);
+
+        if (filter.txHash && !txHash.equals(filter.txHash)) {
+          continue;
+        }
+
+        events.push({
+          eventCommitmentIndex: entry.eventCommitmentIndex,
+          event: {
+            packedEvent: msgContent,
+            l2BlockNumber: BlockNumber(entry.l2BlockNumber),
+            txHash,
+            l2BlockHash,
+            eventSelector,
+          },
+        });
+      }
+    }
+
+    // Sort by eventCommitmentIndex only
+    events.sort((a, b) => a.eventCommitmentIndex - b.eventCommitmentIndex);
+    return events.map(ev => ev.event);
+  }
+
+  /**
+   * Rolls back private events that were stored after a given `blockNumber` and up to `synchedBlockNumber` (the block
+   * number up to which PXE managed to sync before the reorg happened).
+   */
+  public async rollbackEventsAfterBlock(blockNumber: number, synchedBlockNumber: number): Promise<void> {
+    await this.#store.transactionAsync(async () => {
+      let removedCount = 0;
+
+      for (let block = blockNumber + 1; block <= synchedBlockNumber; block++) {
+        const indices = await this.#eventsByBlockNumber.getAsync(block);
+        if (indices) {
+          await this.#eventsByBlockNumber.delete(block);
+
+          for (const eventCommitmentIndex of indices) {
+            const entry = await this.#eventLogs.getAsync(eventCommitmentIndex);
+            if (!entry) {
+              throw new Error(`Event log not found for eventCommitmentIndex ${eventCommitmentIndex}`);
+            }
+
+            await this.#eventLogs.delete(eventCommitmentIndex);
+            await this.#seenLogs.delete(eventCommitmentIndex);
+
+            // Update #eventsByContractScopeSelector using the stored lookupKey
+            const existingIndices = await this.#eventsByContractScopeSelector.getAsync(entry.lookupKey);
+            if (!existingIndices || existingIndices.length === 0) {
+              throw new Error(`No indices found in #eventsByContractScopeSelector for key ${entry.lookupKey}`);
+            }
+            const filteredIndices = existingIndices.filter(idx => idx !== eventCommitmentIndex);
+            if (filteredIndices.length === 0) {
+              await this.#eventsByContractScopeSelector.delete(entry.lookupKey);
+            } else {
+              await this.#eventsByContractScopeSelector.set(entry.lookupKey, filteredIndices);
+            }
+
+            removedCount++;
+          }
+        }
+      }
+
+      this.logger.verbose(`Rolled back ${removedCount} private events after block ${blockNumber}`);
+    });
+  }
+}

package/src/storage/tagging_store/index.ts

@@ -0,0 +1,3 @@
+export { SenderTaggingStore } from './sender_tagging_store.js';
+export { SenderAddressBookStore } from './sender_address_book_store.js';
+export { RecipientTaggingStore } from './recipient_tagging_store.js';

package/src/storage/tagging_store/recipient_tagging_store.ts

@@ -0,0 +1,53 @@
+import type { AztecAsyncKVStore, AztecAsyncMap } from '@aztec/kv-store';
+import type { DirectionalAppTaggingSecret } from '@aztec/stdlib/logs';
+
+/**
+ * Data provider of tagging data used when syncing the logs as a recipient. The sender counterpart of this class
+ * is called SenderTaggingStore. We have the providers separate for the sender and recipient because
+ * the algorithms are completely disjoint and there is not data reuse between the two.
+ *
+ * @dev Chain reorgs do not need to be handled here because both the finalized and aged indexes refer to finalized
+ * blocks, which by definition cannot be affected by reorgs.
+ *
+ * TODO(benesjan): Relocate to yarn-project/pxe/src/storage/tagging_store
+ */
+export class RecipientTaggingStore {
+  #store: AztecAsyncKVStore;
+
+  #highestAgedIndex: AztecAsyncMap<string, number>;
+  #highestFinalizedIndex: AztecAsyncMap<string, number>;
+
+  constructor(store: AztecAsyncKVStore) {
+    this.#store = store;
+
+    this.#highestAgedIndex = this.#store.openMap('highest_aged_index');
+    this.#highestFinalizedIndex = this.#store.openMap('highest_finalized_index');
+  }
+
+  getHighestAgedIndex(secret: DirectionalAppTaggingSecret): Promise<number | undefined> {
+    return this.#highestAgedIndex.getAsync(secret.toString());
+  }
+
+  async updateHighestAgedIndex(secret: DirectionalAppTaggingSecret, index: number): Promise<void> {
+    const currentIndex = await this.#highestAgedIndex.getAsync(secret.toString());
+    if (currentIndex !== undefined && index <= currentIndex) {
+      // Log sync should never set a lower highest aged index.
+      throw new Error(`New highest aged index (${index}) must be higher than the current one (${currentIndex})`);
+    }
+    await this.#highestAgedIndex.set(secret.toString(), index);
+  }
+
+  getHighestFinalizedIndex(secret: DirectionalAppTaggingSecret): Promise<number | undefined> {
+    return this.#highestFinalizedIndex.getAsync(secret.toString());
+  }
+
+  async updateHighestFinalizedIndex(secret: DirectionalAppTaggingSecret, index: number): Promise<void> {
+    const currentIndex = await this.#highestFinalizedIndex.getAsync(secret.toString());
+    if (currentIndex !== undefined && index < currentIndex) {
+      // Log sync should never set a lower highest finalized index but it can happen that it would try to set the same
+      // one because we are loading logs from highest aged index + 1 and not from the highest finalized index.
+      throw new Error(`New highest finalized index (${index}) must be higher than the current one (${currentIndex})`);
+    }
+    await this.#highestFinalizedIndex.set(secret.toString(), index);
+  }
+}

package/src/storage/tagging_store/sender_address_book_store.ts

@@ -0,0 +1,42 @@
+import { toArray } from '@aztec/foundation/iterable';
+import type { AztecAsyncKVStore, AztecAsyncMap } from '@aztec/kv-store';
+import { AztecAddress } from '@aztec/stdlib/aztec-address';
+
+/**
+ * Stores sender addresses. During recipient log synchronization, these senders are used, along with a given recipient,
+ * to derive directional app tagging secrets that are then used to sync the logs.
+ */
+export class SenderAddressBookStore {
+  #store: AztecAsyncKVStore;
+  #addressBook: AztecAsyncMap<string, true>;
+
+  constructor(store: AztecAsyncKVStore) {
+    this.#store = store;
+
+    this.#addressBook = this.#store.openMap('address_book');
+  }
+
+  async addSender(address: AztecAddress): Promise<boolean> {
+    if (await this.#addressBook.hasAsync(address.toString())) {
+      return false;
+    }
+
+    await this.#addressBook.set(address.toString(), true);
+
+    return true;
+  }
+
+  async getSenders(): Promise<AztecAddress[]> {
+    return (await toArray(this.#addressBook.keysAsync())).map(AztecAddress.fromString);
+  }
+
+  async removeSender(address: AztecAddress): Promise<boolean> {
+    if (!(await this.#addressBook.hasAsync(address.toString()))) {
+      return false;
+    }
+
+    await this.#addressBook.delete(address.toString());
+
+    return true;
+  }
+}