@aztec/aztec.js 3.0.0-nightly.20251208 → 3.0.0-nightly.20251210

package/src/wallet/wallet.ts

@@ -1,6 +1,8 @@
 import type { ChainInfo } from '@aztec/entrypoints/interfaces';
-import type { Fr } from '@aztec/foundation/fields';
+import { BlockNumber, BlockNumberPositiveSchema } from '@aztec/foundation/branded-types';
+import type { Fr } from '@aztec/foundation/curves/bn254';
 import {
+  type AbiDecoded,
   AbiTypeSchema,
   type ContractArtifact,
   ContractArtifactSchema,
@@ -27,8 +29,9 @@ import {
   TxReceipt,
   TxSimulationResult,
   UtilitySimulationResult,
+  inTxSchema,
 } from '@aztec/stdlib/tx';
-import type { ExecutionPayload } from '@aztec/stdlib/tx';
+import type { ExecutionPayload, InTx } from '@aztec/stdlib/tx';
 
 import { z } from 'zod';
 
@@ -129,6 +132,38 @@ export type BatchResults<T extends readonly BatchedMethod<keyof BatchableMethods
   [K in keyof T]: BatchedMethodResultWrapper<T[K]>;
 };
 
+/**
+ * Filter options when querying private events.
+ */
+export type PrivateEventFilter = {
+  /** The address of the contract that emitted the events. */
+  contractAddress: AztecAddress;
+  /** Addresses of accounts that are in scope for this filter. */
+  scopes: AztecAddress[];
+  /** Transaction in which the events were emitted. */
+  txHash?: TxHash;
+  /** The block number from which to start fetching events (inclusive).
+   * Optional. If provided, it must be greater or equal than 1.
+   * Defaults to the initial L2 block number (INITIAL_L2_BLOCK_NUM).
+   * */
+  fromBlock?: BlockNumber;
+  /** The block number until which to fetch logs (not inclusive).
+   * Optional. If provided, it must be greater than fromBlock.
+   * Defaults to the latest known block to PXE + 1.
+   */
+  toBlock?: BlockNumber;
+};
+
+/**
+ * An ABI decoded private event with associated metadata.
+ */
+export type PrivateEvent<T> = {
+  /** The ABI decoded event */
+  event: T;
+  /** Metadata describing event context information such as tx and block */
+  metadata: InTx;
+};
+
 /**
  * The wallet interface.
  */
@@ -136,12 +171,9 @@ export type Wallet = {
   getContractClassMetadata(id: Fr, includeArtifact?: boolean): Promise<ContractClassMetadata>;
   getContractMetadata(address: AztecAddress): Promise<ContractMetadata>;
   getPrivateEvents<T>(
-    contractAddress: AztecAddress,
     eventMetadata: EventMetadataDefinition,
-    from: number,
-    numBlocks: number,
-    recipients: AztecAddress[],
-  ): Promise<T[]>;
+    eventFilter: PrivateEventFilter,
+  ): Promise<PrivateEvent<T>[]>;
   getChainInfo(): Promise<ChainInfo>;
   getTxReceipt(txHash: TxHash): Promise<TxReceipt>;
   registerSender(address: AztecAddress, alias?: string): Promise<AztecAddress>;
@@ -267,6 +299,19 @@ export const EventMetadataDefinitionSchema = z.object({
   fieldNames: z.array(z.string()),
 });
 
+export const PrivateEventSchema: ZodFor<PrivateEvent<AbiDecoded>> = z.object({
+  event: AbiDecodedSchema,
+  metadata: inTxSchema(),
+});
+
+export const PrivateEventFilterSchema = z.object({
+  contractAddress: schemas.AztecAddress,
+  scopes: z.array(schemas.AztecAddress),
+  txHash: optional(TxHash.schema),
+  fromBlock: optional(BlockNumberPositiveSchema),
+  toBlock: optional(BlockNumberPositiveSchema),
+});
+
 export const WalletSchema: ApiSchemaFor<Wallet> = {
   getChainInfo: z
     .function()
@@ -277,8 +322,8 @@ export const WalletSchema: ApiSchemaFor<Wallet> = {
   getTxReceipt: z.function().args(TxHash.schema).returns(TxReceipt.schema),
   getPrivateEvents: z
     .function()
-    .args(schemas.AztecAddress, EventMetadataDefinitionSchema, z.number(), z.number(), z.array(schemas.AztecAddress))
-    .returns(z.array(AbiDecodedSchema)),
+    .args(EventMetadataDefinitionSchema, PrivateEventFilterSchema)
+    .returns(z.array(PrivateEventSchema)),
   registerSender: z.function().args(schemas.AztecAddress, optional(z.string())).returns(schemas.AztecAddress),
   getAddressBook: z
     .function()