@aztec/stdlib 0.82.3 → 0.83.0

package/dest/versioning/versioning.js

@@ -3,7 +3,7 @@ import { jsonStringify } from '@aztec/foundation/json-rpc';
     return {
         l1ChainId: config.l1ChainId,
         l1RollupAddress: config.l1Contracts?.rollupAddress,
-        l2ChainVersion: config.version,
+        rollupVersion: config.rollupVersion,
         l2ProtocolContractsTreeRoot: l2ProtocolContractsTreeRoot.toString(),
         l2CircuitsVkTreeRoot: l2CircuitsVkTreeRoot.toString()
     };
@@ -16,7 +16,7 @@ import { jsonStringify } from '@aztec/foundation/json-rpc';
         '00',
         versions.l1ChainId,
         versions.l1RollupAddress.toString().slice(2, 10),
-        versions.l2ChainVersion,
+        versions.rollupVersion,
         versions.l2ProtocolContractsTreeRoot.toString().slice(2, 10),
         versions.l2CircuitsVkTreeRoot.toString().slice(2, 10)
     ].join('-');
@@ -28,7 +28,7 @@ export class ComponentsVersionsError extends Error {
     }
 }
 /** Checks if the compressed string matches against the expected versions. Throws on mismatch. */ export function checkCompressedComponentVersion(compressed, expected) {
-    const [versionVersion, l1ChainId, l1RollupAddress, l2ChainVersion, l2ProtocolContractsTreeRoot, l2CircuitsVkTreeRoot] = compressed.split('-');
+    const [versionVersion, l1ChainId, l1RollupAddress, rollupVersion, l2ProtocolContractsTreeRoot, l2CircuitsVkTreeRoot] = compressed.split('-');
     if (versionVersion !== '00') {
         throw new ComponentsVersionsError('version', '00', versionVersion);
     }
@@ -38,8 +38,8 @@ export class ComponentsVersionsError extends Error {
     if (l1RollupAddress !== expected.l1RollupAddress.toString().slice(2, 10)) {
         throw new ComponentsVersionsError(`L1 address`, expected.l1RollupAddress.toString(), l1RollupAddress);
     }
-    if (l2ChainVersion !== expected.l2ChainVersion.toString()) {
-        throw new ComponentsVersionsError('L2 chain version', expected.l2ChainVersion.toString(), l2ChainVersion);
+    if (rollupVersion !== expected.rollupVersion.toString()) {
+        throw new ComponentsVersionsError('L2 chain version', expected.rollupVersion.toString(), rollupVersion);
     }
     if (l2ProtocolContractsTreeRoot !== expected.l2ProtocolContractsTreeRoot.toString().slice(2, 10)) {
         throw new ComponentsVersionsError(`L2 protocol contracts vk tree root`, expected.l2ProtocolContractsTreeRoot.toString(), l2ProtocolContractsTreeRoot);
@@ -54,7 +54,7 @@ export class ComponentsVersionsError extends Error {
         'l2ProtocolContractsTreeRoot',
         'l2CircuitsVkTreeRoot',
         'l1ChainId',
-        'l2ChainVersion'
+        'rollupVersion'
     ]){
         const actualValue = actual[key];
         const expectedValue = expected[key];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aztec/stdlib",
-  "version": "0.82.3",
+  "version": "0.83.0",
   "type": "module",
   "inherits": [
     "../package.common.json",
@@ -34,7 +34,6 @@
     "./tx": "./dest/tx/index.js",
     "./fees": "./dest/fees/index.js",
     "./note": "./dest/note/index.js",
-    "./event": "./dest/event/index.js",
     "./p2p": "./dest/p2p/index.js",
     "./errors": "./dest/errors/index.js",
     "./stats": "./dest/stats/index.js",
@@ -68,11 +67,11 @@
     "test": "NODE_NO_WARNINGS=1 node --experimental-vm-modules ../node_modules/.bin/jest --passWithNoTests --maxWorkers=${JEST_MAX_WORKERS:-8}"
   },
   "dependencies": {
-    "@aztec/bb.js": "0.82.3",
-    "@aztec/blob-lib": "0.82.3",
-    "@aztec/constants": "0.82.3",
-    "@aztec/ethereum": "0.82.3",
-    "@aztec/foundation": "0.82.3",
+    "@aztec/bb.js": "0.83.0",
+    "@aztec/blob-lib": "0.83.0",
+    "@aztec/constants": "0.83.0",
+    "@aztec/ethereum": "0.83.0",
+    "@aztec/foundation": "0.83.0",
     "@google-cloud/storage": "^7.15.0",
     "lodash.chunk": "^4.2.0",
     "lodash.isequal": "^4.5.0",

package/src/avm/avm.ts

@@ -1,16 +1,15 @@
 import { Fr } from '@aztec/foundation/fields';
 import { jsonParseWithSchema, jsonStringify } from '@aztec/foundation/json-rpc';
 import { schemas } from '@aztec/foundation/schemas';
-import type { IndexedTreeLeaf } from '@aztec/foundation/trees';
 
 import { z } from 'zod';
 
 import { AztecAddress } from '../aztec-address/index.js';
 import { PublicKeys } from '../keys/public_keys.js';
 import { AppendOnlyTreeSnapshot } from '../trees/append_only_tree_snapshot.js';
-import type { MerkleTreeId } from '../trees/merkle_tree_id.js';
-import { NullifierLeaf } from '../trees/nullifier_leaf.js';
-import { PublicDataTreeLeaf } from '../trees/public_data_leaf.js';
+import { MerkleTreeId } from '../trees/merkle_tree_id.js';
+import { NullifierLeafPreimage } from '../trees/nullifier_leaf.js';
+import { PublicDataTreeLeafPreimage } from '../trees/public_data_leaf.js';
 import { AvmCircuitPublicInputs } from './avm_circuit_public_inputs.js';
 import { serializeWithMessagePack } from './message_pack.js';
 
@@ -152,22 +151,20 @@ export class AvmGetPreviousValueIndexHint {
   }
 }
 
+type IndexedTreeLeafPreimages = NullifierLeafPreimage | PublicDataTreeLeafPreimage;
+type IndexedTreeLeafPreimagesClasses = typeof NullifierLeafPreimage | typeof PublicDataTreeLeafPreimage;
+
 // Hint for MerkleTreeDB.getLeafPreimage.
 // NOTE: I need this factory because in order to get hold of the schema, I need an actual instance of the class,
 // having the type doesn't suffice since TS does type erasure in the end.
-function AvmGetLeafPreimageHintFactory<T extends IndexedTreeLeaf>(klass: {
-  schema: z.ZodSchema;
-  new (...args: any[]): T;
-}) {
+function AvmGetLeafPreimageHintFactory(klass: IndexedTreeLeafPreimagesClasses) {
   return class AvmGetLeafPreimageHint {
     constructor(
       public readonly hintKey: AppendOnlyTreeSnapshot,
       // params (tree id will be implicit)
       public readonly index: bigint,
       // return
-      public readonly leaf: T,
-      public readonly nextIndex: bigint,
-      public readonly nextValue: Fr,
+      public readonly leafPreimage: IndexedTreeLeafPreimages,
     ) {}
 
     static get schema() {
@@ -175,21 +172,16 @@ function AvmGetLeafPreimageHintFactory<T extends IndexedTreeLeaf>(klass: {
         .object({
           hintKey: AppendOnlyTreeSnapshot.schema,
           index: schemas.BigInt,
-          leaf: klass.schema,
-          nextIndex: schemas.BigInt,
-          nextValue: schemas.Fr,
+          leafPreimage: klass.schema,
         })
-        .transform(
-          ({ hintKey, index, leaf, nextIndex, nextValue }) =>
-            new AvmGetLeafPreimageHint(hintKey, index, leaf, nextIndex, nextValue),
-        );
+        .transform(({ hintKey, index, leafPreimage }) => new AvmGetLeafPreimageHint(hintKey, index, leafPreimage));
     }
   };
 }
 
 // Note: only supported for PUBLIC_DATA_TREE and NULLIFIER_TREE.
-export class AvmGetLeafPreimageHintPublicDataTree extends AvmGetLeafPreimageHintFactory(PublicDataTreeLeaf) {}
-export class AvmGetLeafPreimageHintNullifierTree extends AvmGetLeafPreimageHintFactory(NullifierLeaf) {}
+export class AvmGetLeafPreimageHintPublicDataTree extends AvmGetLeafPreimageHintFactory(PublicDataTreeLeafPreimage) {}
+export class AvmGetLeafPreimageHintNullifierTree extends AvmGetLeafPreimageHintFactory(NullifierLeafPreimage) {}
 
 // Hint for MerkleTreeDB.getLeafValue.
 // Note: only supported for NOTE_HASH_TREE and L1_TO_L2_MESSAGE_TREE.
@@ -215,6 +207,60 @@ export class AvmGetLeafValueHint {
   }
 }
 
+// Hint for MerkleTreeDB.sequentialInsert.
+// NOTE: I need this factory because in order to get hold of the schema, I need an actual instance of the class,
+// having the type doesn't suffice since TS does type erasure in the end.
+function AvmSequentialInsertHintFactory(klass: IndexedTreeLeafPreimagesClasses) {
+  return class AvmSequentialInsertHint {
+    constructor(
+      public readonly hintKey: AppendOnlyTreeSnapshot,
+      public readonly stateAfter: AppendOnlyTreeSnapshot,
+      // params
+      public readonly treeId: MerkleTreeId,
+      public readonly leaf: InstanceType<IndexedTreeLeafPreimagesClasses>['leaf'],
+      // return
+      public readonly lowLeavesWitnessData: {
+        leaf: IndexedTreeLeafPreimages;
+        index: bigint;
+        path: Fr[];
+      },
+      public readonly insertionWitnessData: {
+        leaf: IndexedTreeLeafPreimages;
+        index: bigint;
+        path: Fr[];
+      },
+    ) {}
+
+    static get schema() {
+      return z
+        .object({
+          hintKey: AppendOnlyTreeSnapshot.schema,
+          stateAfter: AppendOnlyTreeSnapshot.schema,
+          treeId: z.number().int().nonnegative(),
+          leaf: klass.leafSchema,
+          lowLeavesWitnessData: z.object({
+            leaf: klass.schema,
+            index: schemas.BigInt,
+            path: schemas.Fr.array(),
+          }),
+          insertionWitnessData: z.object({
+            leaf: klass.schema,
+            index: schemas.BigInt,
+            path: schemas.Fr.array(),
+          }),
+        })
+        .transform(
+          ({ hintKey, stateAfter, treeId, leaf, lowLeavesWitnessData, insertionWitnessData }) =>
+            new AvmSequentialInsertHint(hintKey, stateAfter, treeId, leaf, lowLeavesWitnessData, insertionWitnessData),
+        );
+    }
+  };
+}
+
+// Note: only supported for PUBLIC_DATA_TREE and NULLIFIER_TREE.
+export class AvmSequentialInsertHintPublicDataTree extends AvmSequentialInsertHintFactory(PublicDataTreeLeafPreimage) {}
+export class AvmSequentialInsertHintNullifierTree extends AvmSequentialInsertHintFactory(NullifierLeafPreimage) {}
+
 ////////////////////////////////////////////////////////////////////////////
 // Hints (other)
 ////////////////////////////////////////////////////////////////////////////
@@ -254,6 +300,8 @@ export class AvmExecutionHints {
     public readonly getLeafPreimageHintsPublicDataTree: AvmGetLeafPreimageHintPublicDataTree[] = [],
     public readonly getLeafPreimageHintsNullifierTree: AvmGetLeafPreimageHintNullifierTree[] = [],
     public readonly getLeafValueHints: AvmGetLeafValueHint[] = [],
+    public readonly sequentialInsertHintsPublicDataTree: AvmSequentialInsertHintPublicDataTree[] = [],
+    public readonly sequentialInsertHintsNullifierTree: AvmSequentialInsertHintNullifierTree[] = [],
   ) {}
 
   static empty() {
@@ -272,6 +320,8 @@ export class AvmExecutionHints {
         getLeafPreimageHintsPublicDataTree: AvmGetLeafPreimageHintPublicDataTree.schema.array(),
         getLeafPreimageHintsNullifierTree: AvmGetLeafPreimageHintNullifierTree.schema.array(),
         getLeafValueHints: AvmGetLeafValueHint.schema.array(),
+        sequentialInsertHintsPublicDataTree: AvmSequentialInsertHintPublicDataTree.schema.array(),
+        sequentialInsertHintsNullifierTree: AvmSequentialInsertHintNullifierTree.schema.array(),
       })
       .transform(
         ({
@@ -284,6 +334,8 @@ export class AvmExecutionHints {
           getLeafPreimageHintsPublicDataTree,
           getLeafPreimageHintsNullifierTree,
           getLeafValueHints,
+          sequentialInsertHintsPublicDataTree,
+          sequentialInsertHintsNullifierTree,
         }) =>
           new AvmExecutionHints(
             enqueuedCalls,
@@ -295,6 +347,8 @@ export class AvmExecutionHints {
             getLeafPreimageHintsPublicDataTree,
             getLeafPreimageHintsNullifierTree,
             getLeafValueHints,
+            sequentialInsertHintsPublicDataTree,
+            sequentialInsertHintsNullifierTree,
           ),
       );
   }

package/src/block/l2_block_downloader/l2_block_stream.ts

@@ -66,12 +66,20 @@ export class L2BlockStream {
 
       // Check if there was a reorg and emit a chain-pruned event if so.
       let latestBlockNumber = localTips.latest.number;
-      while (!(await this.areBlockHashesEqualAt(latestBlockNumber, { sourceCache: [sourceTips.latest] }))) {
+      const sourceCache = new BlockHashCache([sourceTips.latest]);
+      while (!(await this.areBlockHashesEqualAt(latestBlockNumber, { sourceCache }))) {
         latestBlockNumber--;
       }
+
       if (latestBlockNumber < localTips.latest.number) {
         this.log.verbose(`Reorg detected. Pruning blocks from ${latestBlockNumber + 1} to ${localTips.latest.number}.`);
-        await this.emitEvent({ type: 'chain-pruned', blockNumber: latestBlockNumber });
+        await this.emitEvent({
+          type: 'chain-pruned',
+          block: {
+            number: latestBlockNumber,
+            hash: sourceCache.get(latestBlockNumber) ?? (await this.getBlockHashFromSource(latestBlockNumber))!,
+          },
+        });
       }
 
       // If we are just starting, use the starting block number from the options.
@@ -100,10 +108,13 @@ export class L2BlockStream {
 
       // Update the proven and finalized tips.
       if (localTips.proven !== undefined && sourceTips.proven.number !== localTips.proven.number) {
-        await this.emitEvent({ type: 'chain-proven', blockNumber: sourceTips.proven.number });
+        await this.emitEvent({
+          type: 'chain-proven',
+          block: sourceTips.proven,
+        });
       }
       if (localTips.finalized !== undefined && sourceTips.finalized.number !== localTips.finalized.number) {
-        await this.emitEvent({ type: 'chain-finalized', blockNumber: sourceTips.finalized.number });
+        await this.emitEvent({ type: 'chain-finalized', block: sourceTips.finalized });
       }
     } catch (err: any) {
       if (err.name === 'AbortError') {
@@ -118,29 +129,31 @@ export class L2BlockStream {
    * @param blockNumber - The block number to test.
    * @param args - A cache of data already requested from source, to avoid re-requesting it.
    */
-  private async areBlockHashesEqualAt(blockNumber: number, args: { sourceCache: L2BlockId[] }) {
+  private async areBlockHashesEqualAt(blockNumber: number, args: { sourceCache: BlockHashCache }) {
     if (blockNumber === 0) {
       return true;
     }
     const localBlockHash = await this.localData.getL2BlockHash(blockNumber);
-    const sourceBlockHash =
-      args.sourceCache.find(id => id.number === blockNumber && id.hash)?.hash ??
-      (await this.l2BlockSource
-        .getBlockHeader(blockNumber)
-        .then(h => h?.hash())
-        .then(hash => hash?.toString()));
-    this.log.trace(`Comparing block hashes for block ${blockNumber}`, {
-      localBlockHash,
-      sourceBlockHash,
-      sourceCacheNumber: args.sourceCache[0]?.number,
-      sourceCacheHash: args.sourceCache[0]?.hash,
-    });
+    const sourceBlockHashFromCache = args.sourceCache.get(blockNumber);
+    const sourceBlockHash = args.sourceCache.get(blockNumber) ?? (await this.getBlockHashFromSource(blockNumber));
+    if (!sourceBlockHashFromCache && sourceBlockHash) {
+      args.sourceCache.add({ number: blockNumber, hash: sourceBlockHash });
+    }
+
+    this.log.trace(`Comparing block hashes for block ${blockNumber}`, { localBlockHash, sourceBlockHash });
     return localBlockHash === sourceBlockHash;
   }
 
+  private getBlockHashFromSource(blockNumber: number) {
+    return this.l2BlockSource
+      .getBlockHeader(blockNumber)
+      .then(h => h?.hash())
+      .then(hash => hash?.toString());
+  }
+
   private async emitEvent(event: L2BlockStreamEvent) {
     this.log.debug(
-      `Emitting ${event.type} (${event.type === 'blocks-added' ? event.blocks.length : event.blockNumber})`,
+      `Emitting ${event.type} (${event.type === 'blocks-added' ? event.blocks.length : event.block.number})`,
     );
     await this.handler.handleBlockStreamEvent(event);
     if (!this.isRunning() && !this.isSyncing) {
@@ -149,6 +162,26 @@ export class L2BlockStream {
   }
 }
 
+class BlockHashCache {
+  private readonly cache: Map<number, string> = new Map();
+
+  constructor(initial: L2BlockId[] = []) {
+    for (const block of initial) {
+      this.add(block);
+    }
+  }
+
+  public add(block: L2BlockId) {
+    if (block.hash) {
+      this.cache.set(block.number, block.hash);
+    }
+  }
+
+  public get(blockNumber: number) {
+    return this.cache.get(blockNumber);
+  }
+}
+
 /** Interface to the local view of the chain. Implemented by world-state and l2-tips-store. */
 export interface L2BlockStreamLocalDataProvider {
   getL2BlockHash(number: number): Promise<string | undefined>;
@@ -161,23 +194,19 @@ export interface L2BlockStreamEventHandler {
 }
 
 export type L2BlockStreamEvent =
-  | {
+  | /** Emits blocks added to the chain. */ {
       type: 'blocks-added';
-      /** New blocks added to the chain. */
       blocks: PublishedL2Block[];
     }
-  | {
+  | /** Reports last correct block (new tip of the unproven chain). */ {
       type: 'chain-pruned';
-      /** Last correct block number (new tip of the unproven chain). */
-      blockNumber: number;
+      block: L2BlockId;
     }
-  | {
+  | /** Reports new proven block. */ {
       type: 'chain-proven';
-      /** New proven block number */
-      blockNumber: number;
+      block: L2BlockId;
     }
-  | {
+  | /** Reports new finalized block (proven and finalized on L1). */ {
       type: 'chain-finalized';
-      /** New finalized block number */
-      blockNumber: number;
+      block: L2BlockId;
     };

package/src/config/config.ts

@@ -1,5 +1,5 @@
 import { l1ContractAddressesMapping } from '@aztec/ethereum/l1-contract-addresses';
-import { type ConfigMappingsType, numberConfigHelper } from '@aztec/foundation/config';
+import type { ConfigMappingsType } from '@aztec/foundation/config';
 import { EthAddress } from '@aztec/foundation/eth-address';
 
 export { type AllowedElement, type SequencerConfig, SequencerConfigSchema } from '../interfaces/configs.js';
@@ -7,7 +7,7 @@ export { type AllowedElement, type SequencerConfig, SequencerConfigSchema } from
 export const emptyChainConfig: ChainConfig = {
   l1ChainId: 0,
   l1Contracts: { rollupAddress: EthAddress.ZERO },
-  version: 0,
+  rollupVersion: 0,
 };
 
 export const chainConfigMappings: ConfigMappingsType<ChainConfig> = {
@@ -17,10 +17,10 @@ export const chainConfigMappings: ConfigMappingsType<ChainConfig> = {
     defaultValue: 31337,
     description: 'The chain ID of the ethereum host.',
   },
-  version: {
-    env: 'VERSION',
+  rollupVersion: {
+    env: 'ROLLUP_VERSION',
     description: 'The version of the rollup.',
-    ...numberConfigHelper(1),
+    parseEnv: (val: string) => (Number.isSafeInteger(parseInt(val, 10)) ? parseInt(val, 10) : undefined),
   },
   l1Contracts: {
     description: 'The deployed L1 contract addresses',
@@ -33,7 +33,7 @@ export type ChainConfig = {
   /** The chain id of the ethereum host. */
   l1ChainId: number;
   /** The version of the rollup. */
-  version: number;
+  rollupVersion: number;
   /** The address to the L1 contracts. */
   l1Contracts: {
     /** The address to rollup */

package/src/contract/interfaces/node-info.ts

@@ -11,8 +11,8 @@ export interface NodeInfo {
   nodeVersion: string;
   /** L1 chain id. */
   l1ChainId: number;
-  /** Protocol version. */
-  protocolVersion: number;
+  /** Rollup version. */
+  rollupVersion: number;
   /** The node's ENR. */
   enr: string | undefined;
   /** The deployed l1 contract addresses */
@@ -25,7 +25,7 @@ export const NodeInfoSchema: ZodFor<NodeInfo> = z
   .object({
     nodeVersion: z.string(),
     l1ChainId: z.number().int().nonnegative(),
-    protocolVersion: z.number().int().nonnegative(),
+    rollupVersion: z.number().int().nonnegative(),
     enr: z.string().optional(),
     l1ContractAddresses: L1ContractAddressesSchema,
     protocolContractAddresses: ProtocolContractAddressesSchema,

package/src/interfaces/prover-client.ts

@@ -26,7 +26,7 @@ export type ProverConfig = ActualProverConfig & {
   /** The URL to the Aztec node to take proving jobs from */
   nodeUrl?: string;
   /** Identifier of the prover */
-  proverId: Fr;
+  proverId?: Fr;
   /** Number of proving agents to start within the prover. */
   proverAgentCount: number;
   /** Store for failed proof inputs. */
@@ -36,7 +36,7 @@ export type ProverConfig = ActualProverConfig & {
 export const ProverConfigSchema = z.object({
   nodeUrl: z.string().optional(),
   realProofs: z.boolean(),
-  proverId: schemas.Fr,
+  proverId: schemas.Fr.optional(),
   proverTestDelayType: z.enum(['fixed', 'realistic']),
   proverTestDelayMs: z.number(),
   proverTestDelayFactor: z.number(),
@@ -55,9 +55,8 @@ export const proverConfigMappings: ConfigMappingsType<ProverConfig> = {
   },
   proverId: {
     env: 'PROVER_ID',
-    parseEnv: (val: string) => parseProverId(val),
-    description: 'Identifier of the prover',
-    defaultValue: Fr.ZERO,
+    parseEnv: (val?: string) => parseProverId(val),
+    description: 'Hex value that identifies the prover. Defaults to the address used for submitting proofs if not set.',
   },
   proverTestDelayType: {
     env: 'PROVER_TEST_DELAY_TYPE',
@@ -85,8 +84,11 @@ export const proverConfigMappings: ConfigMappingsType<ProverConfig> = {
   },
 };
 
-function parseProverId(str: string) {
-  return Fr.fromHexString(str.startsWith('0x') ? str : Buffer.from(str, 'utf8').toString('hex'));
+function parseProverId(str?: string) {
+  if (!str) {
+    return undefined;
+  }
+  return Fr.fromHexString(str);
 }
 
 /**

package/src/interfaces/pxe.ts

@@ -1,5 +1,5 @@
 import { L1_TO_L2_MSG_TREE_HEIGHT } from '@aztec/constants';
-import type { Fr, Point } from '@aztec/foundation/fields';
+import type { Fr } from '@aztec/foundation/fields';
 import type { ApiSchemaFor, ZodFor } from '@aztec/foundation/schemas';
 import { SiblingPath } from '@aztec/foundation/trees';
 
@@ -129,7 +129,7 @@ export interface PXE {
 
   /**
    * Proves the private portion of a simulated transaction, ready to send to the network
-   * (where valiators prove the public portion).
+   * (where validators prove the public portion).
    *
    * @param txRequest - An authenticated tx request ready for proving
    * @param privateExecutionResult - The result of the private execution of the transaction
@@ -313,7 +313,7 @@ export interface PXE {
 
   /**
    * Returns the information about the server's node. Includes current Node version, compatible Noir version,
-   * L1 chain identifier, protocol version, and L1 address of the rollup contract.
+   * L1 chain identifier, rollup version, and L1 address of the rollup contract.
    * @returns - The node information.
    */
   getNodeInfo(): Promise<NodeInfo>;
@@ -354,13 +354,20 @@ export interface PXE {
 
   /**
    * Returns the private events given search parameters.
+   * @param contractAddress - The address of the contract to get events from.
    * @param eventMetadata - Metadata of the event. This should be the class generated from the contract. e.g. Contract.events.Event
    * @param from - The block number to search from.
-   * @param limit - The amount of blocks to search.
-   * @param vpks - The incoming viewing public keys that can decrypt the log.
+   * @param numBlocks - The amount of blocks to search.
+   * @param recipients - The addresses that decrypted the logs.
    * @returns - The deserialized events.
    */
-  getPrivateEvents<T>(eventMetadata: EventMetadataDefinition, from: number, limit: number, vpks: Point[]): Promise<T[]>;
+  getPrivateEvents<T>(
+    contractAddress: AztecAddress,
+    eventMetadata: EventMetadataDefinition,
+    from: number,
+    numBlocks: number,
+    recipients: AztecAddress[],
+  ): Promise<T[]>;
 
   /**
    * Returns the public events given search parameters.
@@ -505,7 +512,7 @@ export const PXESchema: ApiSchemaFor<PXE> = {
   getContractClassMetadata: z.function().args(schemas.Fr, optional(z.boolean())).returns(ContractClassMetadataSchema),
   getPrivateEvents: z
     .function()
-    .args(EventMetadataDefinitionSchema, z.number(), z.number(), z.array(schemas.Point))
+    .args(schemas.AztecAddress, EventMetadataDefinitionSchema, z.number(), z.number(), z.array(schemas.AztecAddress))
     .returns(z.array(AbiDecodedSchema)),
   getPublicEvents: z
     .function()

package/src/keys/derivation.ts

@@ -1,5 +1,5 @@
 import { GeneratorIndex } from '@aztec/constants';
-import { Grumpkin, poseidon2HashWithSeparator, sha512ToGrumpkinScalar } from '@aztec/foundation/crypto';
+import { Grumpkin, poseidon2Hash, poseidon2HashWithSeparator, sha512ToGrumpkinScalar } from '@aztec/foundation/crypto';
 import { Fq, Fr, GrumpkinScalar } from '@aztec/foundation/fields';
 
 import { AztecAddress } from '../aztec-address/index.js';
@@ -123,11 +123,7 @@ export async function deriveKeys(secretKey: Fr) {
 }
 
 // Returns shared tagging secret computed with Diffie-Hellman key exchange.
-export async function computeTaggingSecretPoint(
-  knownAddress: CompleteAddress,
-  ivsk: Fq,
-  externalAddress: AztecAddress,
-) {
+async function computeTaggingSecretPoint(knownAddress: CompleteAddress, ivsk: Fq, externalAddress: AztecAddress) {
   const knownPreaddress = await computePreaddress(await knownAddress.publicKeys.hash(), knownAddress.partialAddress);
   // TODO: #8970 - Computation of address point from x coordinate might fail
   const externalAddressPoint = await externalAddress.toAddressPoint();
@@ -139,3 +135,13 @@ export async function computeTaggingSecretPoint(
   // computeAddressSecret takes care of selecting the one that leads to a positive y-coordinate, which is the only valid address point
   return curve.mul(externalAddressPoint, await computeAddressSecret(knownPreaddress, ivsk));
 }
+
+export async function computeAppTaggingSecret(
+  knownAddress: CompleteAddress,
+  ivsk: Fq,
+  externalAddress: AztecAddress,
+  app: AztecAddress,
+) {
+  const taggingSecretPoint = await computeTaggingSecretPoint(knownAddress, ivsk, externalAddress);
+  return poseidon2Hash([taggingSecretPoint.x, taggingSecretPoint.y, app]);
+}

package/src/logs/index.ts

@@ -3,9 +3,10 @@ export * from './indexed_tagging_secret.js';
 export * from './contract_class_log.js';
 export * from './public_log.js';
 export * from './private_log.js';
+export * from './pending_tagged_log.js';
 export * from './log_id.js';
 export * from './log_filter.js';
 export * from './extended_public_log.js';
 export * from './extended_contract_class_log.js';
-export * from './l1_payload/index.js';
+export * from './shared_secret_derivation.js';
 export * from './tx_scoped_l2_log.js';

package/src/logs/pending_tagged_log.ts

@@ -0,0 +1,43 @@
+import { MAX_NOTE_HASHES_PER_TX, PRIVATE_LOG_SIZE_IN_FIELDS } from '@aztec/constants';
+import { Fr } from '@aztec/foundation/fields';
+
+import type { AztecAddress } from '../aztec-address/index.js';
+
+/**
+ * Represents a pending tagged log as it is stored in the pending tagged log array to which the syncNotes oracle
+ * inserts found private logs. A TS version of `pending_tagged_log.nr`.
+ */
+export class PendingTaggedLog {
+  constructor(
+    public log: Fr[],
+    public txHash: Fr,
+    public uniqueNoteHashesInTx: Fr[],
+    public firstNullifierInTx: Fr,
+    public recipient: AztecAddress,
+    public logIndexInTx: number,
+  ) {}
+
+  toFields(): Fr[] {
+    return [
+      ...serializeBoundedVec(this.log, PRIVATE_LOG_SIZE_IN_FIELDS),
+      this.txHash,
+      ...serializeBoundedVec(this.uniqueNoteHashesInTx, MAX_NOTE_HASHES_PER_TX),
+      this.firstNullifierInTx,
+      this.recipient.toField(),
+      new Fr(this.logIndexInTx),
+    ];
+  }
+}
+
+/**
+ * Helper function to serialize a bounded vector according to Noir's BoundedVec format
+ * @param values - The values to serialize
+ * @param maxLength - The maximum length of the bounded vector
+ * @returns The serialized bounded vector as Fr[]
+ */
+function serializeBoundedVec(values: Fr[], maxLength: number): Fr[] {
+  const lengthDiff = maxLength - values.length;
+  const zeroPaddingArray = Array(lengthDiff).fill(Fr.ZERO);
+  const storage = values.concat(zeroPaddingArray);
+  return [...storage, new Fr(values.length)];
+}