@aztec/stdlib 0.77.0-testnet-ignition.17

package/src/logs/l1_payload/encrypted_log_payload.ts

@@ -0,0 +1,202 @@
+import { PRIVATE_LOG_SIZE_IN_FIELDS } from '@aztec/constants';
+import { randomBytes } from '@aztec/foundation/crypto';
+import { Fr, type GrumpkinScalar, NotOnCurveError, Point } from '@aztec/foundation/fields';
+import { BufferReader, type Tuple, numToUInt16BE, serializeToBuffer } from '@aztec/foundation/serialize';
+
+import { AztecAddress } from '../../aztec-address/index.js';
+import { derivePublicKeyFromSecretKey } from '../../keys/derivation.js';
+import { PrivateLog } from '../private_log.js';
+import {
+  aes128Decrypt,
+  aes128Encrypt,
+  deriveAesSymmetricKeyAndIvFromEcdhSharedSecretUsingSha256,
+} from './encryption_util.js';
+import { deriveEcdhSharedSecret, deriveEcdhSharedSecretUsingAztecAddress } from './shared_secret_derivation.js';
+
+// Below constants should match the values defined in aztec-nr/aztec/src/encrypted_logs/log_assembly_strategies/default_aes128/note.nr.
+// Note: we will soon be 'abstracting' log processing: apps will process their own logs, instead of the PXE processing all apps' logs. Therefore, this file will imminently change considerably.
+
+const TAG_SIZE_IN_FIELDS = 1;
+const EPK_SIZE_IN_FIELDS = 1;
+
+const USABLE_PRIVATE_LOG_SIZE_IN_FIELDS = PRIVATE_LOG_SIZE_IN_FIELDS - TAG_SIZE_IN_FIELDS - EPK_SIZE_IN_FIELDS;
+const USABLE_PRIVATE_LOG_SIZE_IN_BYTES = ((USABLE_PRIVATE_LOG_SIZE_IN_FIELDS * 31) / 16) * 16;
+
+// The incoming header ciphertext is 48 bytes
+// 32 bytes for the address, and 16 bytes padding to follow PKCS#7
+const HEADER_CIPHERTEXT_SIZE_IN_BYTES = 48;
+const USABLE_PLAINTEXT_SIZE_IN_BYTES = USABLE_PRIVATE_LOG_SIZE_IN_BYTES - HEADER_CIPHERTEXT_SIZE_IN_BYTES;
+
+const CONTRACT_ADDRESS_SIZE_IN_BYTES = 32;
+
+const SIZE_OF_ENCODING_OF_CIPHERTEXT_SIZE_IN_BYTES = 2;
+
+function beBytes31ToFields(bytes: Buffer): Fr[] {
+  const fields = [];
+  const numFields = Math.ceil(bytes.length / 31);
+  for (let i = 0; i < numFields; i++) {
+    fields.push(new Fr(bytes.subarray(i * 31, (i + 1) * 31)));
+  }
+  return fields;
+}
+
+function fieldsToBEBytes31(fields: Fr[]) {
+  return Buffer.concat(fields.map(f => f.toBuffer().subarray(1)));
+}
+
+/**
+ * Encrypted log payload with a tag used for retrieval by clients.
+ */
+export class EncryptedLogPayload {
+  constructor(
+    /**
+     * Note discovery tag.
+     */
+    public readonly tag: Fr,
+    /**
+     * Address of a contract that emitted the log.
+     */
+    public readonly contractAddress: AztecAddress,
+    /**
+     * Decrypted incoming body.
+     */
+    public readonly incomingBodyPlaintext: Buffer,
+  ) {}
+
+  // NB: Only appears to be used in tests
+  // See noir-projects/aztec-nr/aztec/src/encrypted_logs/log_assembly_strategies/default_aes128/note.nr
+  public async generatePayload(
+    ephSk: GrumpkinScalar,
+    recipient: AztecAddress,
+    rand: (len: number) => Buffer = randomBytes,
+  ): Promise<PrivateLog> {
+    const ephPk = await derivePublicKeyFromSecretKey(ephSk);
+    const [ephPkX, ephPkSignBool] = ephPk.toXAndSign();
+    const ephPkSignU8 = Buffer.from([Number(ephPkSignBool)]);
+
+    const ciphertextSharedSecret = await deriveEcdhSharedSecretUsingAztecAddress(ephSk, recipient); // not to be confused with the tagging shared secret
+
+    const [symKey, iv] = deriveAesSymmetricKeyAndIvFromEcdhSharedSecretUsingSha256(ciphertextSharedSecret);
+
+    if (this.incomingBodyPlaintext.length > USABLE_PLAINTEXT_SIZE_IN_BYTES) {
+      throw new Error(`Incoming body plaintext cannot be more than ${USABLE_PLAINTEXT_SIZE_IN_BYTES} bytes.`);
+    }
+
+    const finalPlaintext = this.incomingBodyPlaintext;
+
+    const ciphertextBytes = await aes128Encrypt(finalPlaintext, iv, symKey);
+
+    const headerPlaintext = serializeToBuffer(this.contractAddress.toBuffer(), numToUInt16BE(ciphertextBytes.length));
+
+    // TODO: it is unsafe to re-use the same iv and symKey. We'll need to do something cleverer.
+    const headerCiphertextBytes = await aes128Encrypt(headerPlaintext, iv, symKey);
+
+    if (headerCiphertextBytes.length !== HEADER_CIPHERTEXT_SIZE_IN_BYTES) {
+      throw new Error(`Invalid header ciphertext size: ${headerCiphertextBytes.length}`);
+    }
+
+    const properLogBytesLength = 1 /* ephPkSignU8 */ + HEADER_CIPHERTEXT_SIZE_IN_BYTES + ciphertextBytes.length;
+
+    const logBytesPaddingToMult31 = rand(31 * Math.ceil(properLogBytesLength / 31) - properLogBytesLength);
+
+    const logBytes = serializeToBuffer(ephPkSignU8, headerCiphertextBytes, ciphertextBytes, logBytesPaddingToMult31);
+
+    if (logBytes.length % 31 !== 0) {
+      throw new Error(`logBytes.length should be divisible by 31, got: ${logBytes.length}`);
+    }
+
+    const fieldsPadding = Array.from({ length: USABLE_PRIVATE_LOG_SIZE_IN_FIELDS - logBytes.length / 31 }, () =>
+      Fr.fromBuffer(rand(32)),
+    ); // we use the randomBytes function instead of `Fr.random()`, so that we can use deterministic randomness in tests, through the rand() function.
+
+    const logFields = [this.tag, ephPkX, ...beBytes31ToFields(logBytes), ...fieldsPadding] as Tuple<
+      Fr,
+      typeof PRIVATE_LOG_SIZE_IN_FIELDS
+    >;
+
+    if (logFields.length !== PRIVATE_LOG_SIZE_IN_FIELDS) {
+      throw new Error(
+        `Expected private log payload to have ${PRIVATE_LOG_SIZE_IN_FIELDS} fields. Got ${logFields.length}.`,
+      );
+    }
+
+    return new PrivateLog(logFields);
+  }
+
+  /**
+   * Decrypts a ciphertext as an incoming log.
+   *
+   * This is executable by the recipient of the note, and uses the addressSecret to decrypt the payload.
+   *
+   * @param payload - The payload for the log
+   * @param addressSecret - The address secret, used to decrypt the logs
+   * @param ciphertextLength - Optionally supply the ciphertext length (see trimCiphertext())
+   * @returns The decrypted log payload
+   */
+  public static async decryptAsIncoming(
+    payload: Fr[],
+    addressSecret: GrumpkinScalar,
+  ): Promise<EncryptedLogPayload | undefined> {
+    try {
+      const logFields = payload;
+
+      const tag = logFields[0];
+      const ephPkX = logFields[1];
+
+      const reader = BufferReader.asReader(fieldsToBEBytes31(logFields.slice(TAG_SIZE_IN_FIELDS + EPK_SIZE_IN_FIELDS)));
+
+      const ephPkSigBuf = reader.readBytes(1);
+      const ephPkSignBool = !!ephPkSigBuf[0];
+      const ephPk = await Point.fromXAndSign(ephPkX, ephPkSignBool);
+
+      const headerCiphertextBytes = reader.readBytes(HEADER_CIPHERTEXT_SIZE_IN_BYTES);
+
+      let contractAddress = AztecAddress.ZERO;
+      if (!addressSecret) {
+        throw new Error('Cannot decrypt without an address secret.');
+      }
+
+      const ciphertextSharedSecret = await deriveEcdhSharedSecret(addressSecret, ephPk);
+
+      const [symKey, iv] = deriveAesSymmetricKeyAndIvFromEcdhSharedSecretUsingSha256(ciphertextSharedSecret);
+
+      const headerPlaintextBytes = await aes128Decrypt(headerCiphertextBytes, iv, symKey);
+
+      const headerReader = BufferReader.asReader(headerPlaintextBytes);
+
+      const contractAddressBuf = headerReader.readBytes(CONTRACT_ADDRESS_SIZE_IN_BYTES);
+      contractAddress = AztecAddress.fromBuffer(contractAddressBuf);
+
+      const ciphertextBytesLengthBuf = headerReader.readBytes(SIZE_OF_ENCODING_OF_CIPHERTEXT_SIZE_IN_BYTES);
+      const ciphertextBytesLength = (ciphertextBytesLengthBuf[0] << 8) + ciphertextBytesLengthBuf[1];
+
+      const ciphertextBytes = reader.readBytes(ciphertextBytesLength);
+
+      const plaintextBytes = await aes128Decrypt(ciphertextBytes, iv, symKey);
+
+      return new EncryptedLogPayload(tag, contractAddress, plaintextBytes);
+    } catch (e: any) {
+      // Following error messages are expected to occur when decryption fails
+      if (!this.isAcceptableError(e)) {
+        // If we encounter an unexpected error, we rethrow it
+        throw e;
+      }
+      return;
+    }
+  }
+
+  private static isAcceptableError(e: any) {
+    return (
+      e instanceof NotOnCurveError ||
+      e.message.endsWith('is greater or equal to field modulus.') ||
+      e.message.startsWith('Invalid AztecAddress length') ||
+      e.message.startsWith('Selector must fit in') ||
+      e.message.startsWith('Attempted to read beyond buffer length') ||
+      e.message.startsWith('RangeError [ERR_BUFFER_OUT_OF_BOUNDS]:')
+    );
+  }
+
+  public toBuffer() {
+    return serializeToBuffer(this.tag, this.contractAddress.toBuffer(), this.incomingBodyPlaintext);
+  }
+}

package/src/logs/l1_payload/encryption_util.ts

@@ -0,0 +1,54 @@
+import { GeneratorIndex } from '@aztec/constants';
+import { Aes128, sha256 } from '@aztec/foundation/crypto';
+import type { Point } from '@aztec/foundation/fields';
+import { numToUInt8 } from '@aztec/foundation/serialize';
+
+function extractCloseToUniformlyRandom256BitsFromEcdhSharedSecretUsingSha256(sharedSecret: Point): Buffer {
+  const secretBuffer = Buffer.concat([sharedSecret.toCompressedBuffer(), numToUInt8(GeneratorIndex.SYMMETRIC_KEY)]);
+  const hash = sha256(secretBuffer);
+  return hash;
+}
+
+function deriveAesSymmetricKeyAndIvFromEcdhSharedSecret(
+  sharedSecret: Point,
+  randomnessExtractionFunction: (sharedSecret: Point) => Buffer,
+): [Buffer, Buffer] {
+  const random256Bits = randomnessExtractionFunction(sharedSecret);
+  const symKey = random256Bits.subarray(0, 16);
+  const iv = random256Bits.subarray(16, 32);
+  return [symKey, iv];
+}
+
+export function deriveAesSymmetricKeyAndIvFromEcdhSharedSecretUsingSha256(sharedSecret: Point): [Buffer, Buffer] {
+  return deriveAesSymmetricKeyAndIvFromEcdhSharedSecret(
+    sharedSecret,
+    extractCloseToUniformlyRandom256BitsFromEcdhSharedSecretUsingSha256,
+  );
+}
+
+/**
+ * Encrypts the plaintext using the secret key and public key
+ *
+ * @param plaintext - The plaintext buffer
+ * @param secret - The secret key used to derive the AES secret
+ * @param publicKey - Public key used to derived the AES secret
+ * @param deriveSecret - Function to derive the AES secret from the ephemeral secret key and public key
+ * @returns The ciphertext
+ */
+export function aes128Encrypt(plaintext: Buffer, iv: Buffer, symKey: Buffer): Promise<Buffer> {
+  const aes128 = new Aes128();
+  return aes128.encryptBufferCBC(plaintext, iv, symKey);
+}
+
+/**
+ * Decrypts the ciphertext using the secret key and public key
+ * @param ciphertext - The ciphertext buffer
+ * @param secret - The secret key used to derive the AES secret
+ * @param publicKey - The public key used to derive the AES secret
+ * @param deriveSecret - Function to derive the AES secret from the ephemeral secret key and public key
+ * @returns
+ */
+export function aes128Decrypt(ciphertext: Buffer, iv: Buffer, symKey: Buffer): Promise<Buffer> {
+  const aes128 = new Aes128();
+  return aes128.decryptBufferCBC(ciphertext, iv, symKey);
+}

package/src/logs/l1_payload/index.ts

@@ -0,0 +1,2 @@
+export * from './encrypted_log_payload.js';
+export * from './l1_note_payload.js';

package/src/logs/l1_payload/l1_note_payload.ts

@@ -0,0 +1,182 @@
+import { randomInt } from '@aztec/foundation/crypto';
+import { type Fq, Fr } from '@aztec/foundation/fields';
+import { BufferReader, serializeToBuffer } from '@aztec/foundation/serialize';
+
+import { NoteSelector } from '../../abi/note_selector.js';
+import { AztecAddress } from '../../aztec-address/index.js';
+import { Vector } from '../../types/index.js';
+import type { PrivateLog } from '../private_log.js';
+import { PublicLog } from '../public_log.js';
+import { EncryptedLogPayload } from './encrypted_log_payload.js';
+
+/**
+ * A class which wraps note data which is pushed on L1.
+ * @remarks This data is required to compute a nullifier/to spend a note. Along with that this class contains
+ * the necessary functionality to encrypt and decrypt the data.
+ */
+export class L1NotePayload {
+  constructor(
+    /**
+     * Address of the contract this tx is interacting with.
+     */
+    public contractAddress: AztecAddress,
+    /**
+     * Storage slot of the underlying note.
+     */
+    public storageSlot: Fr,
+    /**
+     * Type identifier for the underlying note, required to determine how to compute its hash and nullifier.
+     */
+    public noteTypeId: NoteSelector,
+    /**
+     * Note values delivered encrypted.
+     * @dev Note that to recreate the correct note we need to merge privateNoteValues and publicNoteValues. To do that
+     * we need access to the contract ABI (that is done in the NoteProcessor).
+     */
+    public privateNoteValues: Fr[],
+    /**
+     * Note values delivered in plaintext.
+     * @dev Note that to recreate the correct note we need to merge privateNoteValues and publicNoteValues. To do that
+     * we need access to the contract ABI (that is done in the NoteProcessor).
+     */
+    public publicNoteValues: Fr[],
+  ) {}
+
+  static fromIncomingBodyPlaintextContractAndPublicValues(
+    plaintext: Buffer,
+    contractAddress: AztecAddress,
+    publicNoteValues: Fr[],
+  ): L1NotePayload | undefined {
+    try {
+      const reader = BufferReader.asReader(plaintext);
+      const fields = reader.readArray(plaintext.length / Fr.SIZE_IN_BYTES, Fr);
+
+      const storageSlot = fields[0];
+      const noteTypeId = NoteSelector.fromField(fields[1]);
+
+      const privateNoteValues = fields.slice(2);
+
+      return new L1NotePayload(contractAddress, storageSlot, noteTypeId, privateNoteValues, publicNoteValues);
+    } catch (e) {
+      return undefined;
+    }
+  }
+
+  static async decryptAsIncoming(log: PrivateLog, sk: Fq): Promise<L1NotePayload | undefined> {
+    const decryptedLog = await EncryptedLogPayload.decryptAsIncoming(log.fields, sk);
+    if (!decryptedLog) {
+      return undefined;
+    }
+
+    return this.fromIncomingBodyPlaintextContractAndPublicValues(
+      decryptedLog.incomingBodyPlaintext,
+      decryptedLog.contractAddress,
+      /* publicValues */ [],
+    );
+  }
+
+  static async decryptAsIncomingFromPublic(log: PublicLog, sk: Fq): Promise<L1NotePayload | undefined> {
+    const { privateValues, publicValues } = parseLogFromPublic(log);
+    if (!privateValues) {
+      return undefined;
+    }
+
+    const decryptedLog = await EncryptedLogPayload.decryptAsIncoming(privateValues, sk);
+    if (!decryptedLog) {
+      return undefined;
+    }
+
+    return this.fromIncomingBodyPlaintextContractAndPublicValues(
+      decryptedLog.incomingBodyPlaintext,
+      decryptedLog.contractAddress,
+      publicValues,
+    );
+  }
+
+  /**
+   * Serializes the L1NotePayload object into a Buffer.
+   * @returns Buffer representation of the L1NotePayload object.
+   */
+  toIncomingBodyPlaintext() {
+    const fields = [this.storageSlot, this.noteTypeId.toField(), ...this.privateNoteValues];
+    return serializeToBuffer(fields);
+  }
+
+  /**
+   * Create a random L1NotePayload object (useful for testing purposes).
+   * @param contract - The address of a contract the note was emitted from.
+   * @returns A random L1NotePayload object.
+   */
+  static async random(contract?: AztecAddress) {
+    const numPrivateNoteValues = randomInt(2) + 1;
+    const privateNoteValues = Array.from({ length: numPrivateNoteValues }, () => Fr.random());
+
+    const numPublicNoteValues = randomInt(2) + 1;
+    const publicNoteValues = Array.from({ length: numPublicNoteValues }, () => Fr.random());
+
+    return new L1NotePayload(
+      contract ?? (await AztecAddress.random()),
+      Fr.random(),
+      NoteSelector.random(),
+      privateNoteValues,
+      publicNoteValues,
+    );
+  }
+
+  public equals(other: L1NotePayload) {
+    return (
+      this.contractAddress.equals(other.contractAddress) &&
+      this.storageSlot.equals(other.storageSlot) &&
+      this.noteTypeId.equals(other.noteTypeId) &&
+      this.privateNoteValues.every((value, index) => value.equals(other.privateNoteValues[index])) &&
+      this.publicNoteValues.every((value, index) => value.equals(other.publicNoteValues[index]))
+    );
+  }
+
+  toBuffer() {
+    return serializeToBuffer(
+      this.contractAddress,
+      this.storageSlot,
+      this.noteTypeId,
+      new Vector(this.privateNoteValues),
+      new Vector(this.publicNoteValues),
+    );
+  }
+
+  static fromBuffer(buffer: Buffer | BufferReader) {
+    const reader = BufferReader.asReader(buffer);
+    return new L1NotePayload(
+      reader.readObject(AztecAddress),
+      reader.readObject(Fr),
+      reader.readObject(NoteSelector),
+      reader.readVector(Fr),
+      reader.readVector(Fr),
+    );
+  }
+}
+
+/**
+ * Parse the given log into an array of public values and an encrypted log.
+ *
+ * @param log - Log to be parsed.
+ * @returns An object containing the public values, encrypted log, and ciphertext length.
+ */
+function parseLogFromPublic(log: PublicLog) {
+  // Extract lengths from the log
+  // See aztec_nr/aztec/src/macros/note/mod.nr to see how the "finalization_log" is encoded.
+  // Each length is stored in 2 bytes with a 0 separator byte between them:
+  // [ publicLen[0], publicLen[1], 0, privateLen[0], privateLen[1] ]
+  // Search the codebase for "disgusting encoding" to see other hardcoded instances of this encoding, that you might need to change if you ever find yourself here.
+  const lengths = log.log[0].toBuffer().subarray(-5);
+  const publicValuesLength = lengths.readUint16BE();
+  const privateValuesLength = lengths.readUint16BE(3);
+
+  // Now we get the fields corresponding to the values generated from private.
+  // Note: +1 for the length values in position 0
+  const privateValues = log.log.slice(1, 1 + privateValuesLength);
+
+  // At last we load the public values
+  const publicValues = log.log.slice(1 + privateValuesLength, 1 + privateValuesLength + publicValuesLength);
+
+  return { publicValues, privateValues };
+}

package/src/logs/l1_payload/payload.ts

@@ -0,0 +1,73 @@
+import { randomInt } from '@aztec/foundation/crypto';
+import { Fr } from '@aztec/foundation/fields';
+import { BufferReader } from '@aztec/foundation/serialize';
+import { bufferToHex, hexToBuffer } from '@aztec/foundation/string';
+
+import { schemas } from '../../schemas/index.js';
+import { Vector } from '../../types/index.js';
+
+/**
+ * The Note class represents a Note emitted from a Noir contract as a vector of Fr (finite field) elements.
+ * This data also represents a preimage to a note hash. This class extends the Vector class, which allows for
+ * additional operations on the underlying field elements.
+ */
+export class Payload extends Vector<Fr> {
+  toJSON() {
+    return this.toBuffer();
+  }
+
+  static get schema() {
+    return schemas.Buffer.transform(Payload.fromBuffer);
+  }
+
+  /**
+   * Create a Note instance from a Buffer or BufferReader.
+   * The input 'buffer' can be either a Buffer containing the serialized Fr elements or a BufferReader instance.
+   * This function reads the Fr elements in the buffer and constructs a Note with them.
+   *
+   * @param buffer - The Buffer or BufferReader containing the serialized Fr elements.
+   * @returns A Note instance containing the deserialized Fr elements.
+   */
+  static fromBuffer(buffer: Buffer | BufferReader) {
+    const reader = BufferReader.asReader(buffer);
+    return new Payload(reader.readVector(Fr));
+  }
+
+  /**
+   * Generates a random Note instance with a variable number of items.
+   * The number of items is determined by a random value between 1 and 10 (inclusive).
+   * Each item in the Note is generated using the Fr.random() method.
+   *
+   * @returns A randomly generated Note instance.
+   */
+  static random() {
+    const numItems = randomInt(10) + 1;
+    const items = Array.from({ length: numItems }, () => Fr.random());
+    return new Payload(items);
+  }
+
+  /**
+   * Returns a hex representation of the note.
+   * @returns A hex string with the vector length as first element.
+   */
+  override toString() {
+    return bufferToHex(this.toBuffer());
+  }
+
+  /**
+   * Creates a new Note instance from a hex string.
+   * @param str - Hex representation.
+   * @returns A Note instance.
+   */
+  static fromString(str: string) {
+    return Payload.fromBuffer(hexToBuffer(str));
+  }
+
+  get length() {
+    return this.items.length;
+  }
+
+  equals(other: Payload) {
+    return this.items.every((item, index) => item.equals(other.items[index]));
+  }
+}

package/src/logs/l1_payload/shared_secret_derivation.ts

@@ -0,0 +1,35 @@
+import { Grumpkin } from '@aztec/foundation/crypto';
+import type { GrumpkinScalar, Point } from '@aztec/foundation/fields';
+
+import type { AztecAddress } from '../../aztec-address/index.js';
+import type { PublicKey } from '../../keys/public_key.js';
+
+/**
+ * Derive an Elliptic Curve Diffie-Hellman (ECDH) Shared Secret.
+ * The function takes in an ECDH public key, a private key, and a Grumpkin instance to compute
+ * the shared secret.
+ *
+ * @param secretKey - The secret key used to derive shared secret.
+ * @param publicKey - The public key used to derive shared secret.
+ * @returns A derived shared secret.
+ * @throws If the publicKey is zero.
+ */
+export async function deriveEcdhSharedSecret(secretKey: GrumpkinScalar, publicKey: PublicKey): Promise<Point> {
+  if (publicKey.isZero()) {
+    throw new Error(
+      `Attempting to derive a shared secret with a zero public key. You have probably passed a zero public key in your Noir code somewhere thinking that the note won't be broadcast... but it was.`,
+    );
+  }
+  const curve = new Grumpkin();
+  const sharedSecret = await curve.mul(publicKey, secretKey);
+  return sharedSecret;
+}
+
+export async function deriveEcdhSharedSecretUsingAztecAddress(
+  secretKey: GrumpkinScalar,
+  address: AztecAddress,
+): Promise<Point> {
+  const addressPoint = await address.toAddressPoint();
+  const sharedSecret = await deriveEcdhSharedSecret(secretKey, addressPoint);
+  return sharedSecret;
+}

package/src/logs/log_filter.ts

@@ -0,0 +1,31 @@
+import { z } from 'zod';
+
+import type { AztecAddress } from '../aztec-address/index.js';
+import { type ZodFor, schemas } from '../schemas/index.js';
+import { TxHash } from '../tx/tx_hash.js';
+import { LogId } from './log_id.js';
+
+/**
+ * Log filter used to fetch L2 logs.
+ * @remarks This filter is applied as an intersection of all it's params.
+ */
+export type LogFilter = {
+  /** Hash of a transaction from which to fetch the logs. */
+  txHash?: TxHash;
+  /** The block number from which to start fetching logs (inclusive). */
+  fromBlock?: number;
+  /** The block number until which to fetch logs (not inclusive). */
+  toBlock?: number;
+  /** Log id after which to start fetching logs. */
+  afterLog?: LogId;
+  /** The contract address to filter logs by. */
+  contractAddress?: AztecAddress;
+};
+
+export const LogFilterSchema: ZodFor<LogFilter> = z.object({
+  txHash: TxHash.schema.optional(),
+  fromBlock: schemas.Integer.optional(),
+  toBlock: schemas.Integer.optional(),
+  afterLog: LogId.schema.optional(),
+  contractAddress: schemas.AztecAddress.optional(),
+});

package/src/logs/log_id.ts

@@ -0,0 +1,110 @@
+import { INITIAL_L2_BLOCK_NUM } from '@aztec/constants';
+import { toBufferBE } from '@aztec/foundation/bigint-buffer';
+import { BufferReader } from '@aztec/foundation/serialize';
+
+import { z } from 'zod';
+
+import { schemas } from '../schemas/index.js';
+
+/** A globally unique log id. */
+export class LogId {
+  /**
+   * Parses a log id from a string.
+   * @param blockNumber - The block number.
+   * @param txIndex - The transaction index.
+   * @param logIndex - The log index.
+   */
+  constructor(
+    /** The block number the log was emitted in. */
+    public readonly blockNumber: number,
+    /** The index of a tx in a block the log was emitted in. */
+    public readonly txIndex: number,
+    /** The index of a log the tx was emitted in. */
+    public readonly logIndex: number,
+  ) {
+    if (!Number.isInteger(blockNumber) || blockNumber < INITIAL_L2_BLOCK_NUM) {
+      throw new Error(`Invalid block number: ${blockNumber}`);
+    }
+    if (!Number.isInteger(txIndex)) {
+      throw new Error(`Invalid tx index: ${txIndex}`);
+    }
+    if (!Number.isInteger(logIndex)) {
+      throw new Error(`Invalid log index: ${logIndex}`);
+    }
+  }
+
+  static random() {
+    return new LogId(
+      Math.floor(Math.random() * 1000) + 1,
+      Math.floor(Math.random() * 1000),
+      Math.floor(Math.random() * 100),
+    );
+  }
+
+  static get schema() {
+    return z
+      .object({
+        blockNumber: schemas.Integer,
+        txIndex: schemas.Integer,
+        logIndex: schemas.Integer,
+      })
+      .transform(({ blockNumber, txIndex, logIndex }) => new LogId(blockNumber, txIndex, logIndex));
+  }
+
+  /**
+   * Serializes log id to a buffer.
+   * @returns A buffer containing the serialized log id.
+   */
+  public toBuffer(): Buffer {
+    return Buffer.concat([
+      toBufferBE(BigInt(this.blockNumber), 4),
+      toBufferBE(BigInt(this.txIndex), 4),
+      toBufferBE(BigInt(this.logIndex), 4),
+    ]);
+  }
+
+  /**
+   * Creates a LogId from a buffer.
+   * @param buffer - A buffer containing the serialized log id.
+   * @returns A log id.
+   */
+  static fromBuffer(buffer: Buffer | BufferReader): LogId {
+    const reader = BufferReader.asReader(buffer);
+
+    const blockNumber = reader.readNumber();
+    const txIndex = reader.readNumber();
+    const logIndex = reader.readNumber();
+
+    return new LogId(blockNumber, txIndex, logIndex);
+  }
+
+  /**
+   * Converts the LogId instance to a string.
+   * @returns A string representation of the log id.
+   */
+  public toString(): string {
+    return `${this.blockNumber}-${this.txIndex}-${this.logIndex}`;
+  }
+
+  /**
+   * Creates a LogId from a string.
+   * @param data - A string representation of a log id.
+   * @returns A log id.
+   */
+  static fromString(data: string): LogId {
+    const [rawBlockNumber, rawTxIndex, rawLogIndex] = data.split('-');
+    const blockNumber = Number(rawBlockNumber);
+    const txIndex = Number(rawTxIndex);
+    const logIndex = Number(rawLogIndex);
+
+    return new LogId(blockNumber, txIndex, logIndex);
+  }
+
+  /**
+   * Serializes log id to a human readable string.
+   * @returns A human readable representation of the log id.
+   */
+  public toHumanReadable(): string {
+    return `logId: (blockNumber: ${this.blockNumber}, txIndex: ${this.txIndex}, logIndex: ${this.logIndex})`;
+  }
+}