@aztec/stdlib 0.0.1-commit.86469d5 → 0.0.1-commit.8655d4a

package/src/keys/utils.ts

@@ -1,13 +1,13 @@
-import { GeneratorIndex } from '@aztec/constants';
+import { DomainSeparator } from '@aztec/constants';
 
 import type { KeyGenerator, KeyPrefix } from './key_types.js';
 
 export function getKeyGenerator(prefix: KeyPrefix): KeyGenerator {
   const map: Record<KeyPrefix, KeyGenerator> = {
-    n: GeneratorIndex.NHK_M,
-    iv: GeneratorIndex.IVSK_M,
-    ov: GeneratorIndex.OVSK_M,
-    t: GeneratorIndex.TSK_M,
+    n: DomainSeparator.NHK_M,
+    iv: DomainSeparator.IVSK_M,
+    ov: DomainSeparator.OVSK_M,
+    t: DomainSeparator.TSK_M,
   };
   return map[prefix];
 }

package/src/kv-store/config.ts

@@ -0,0 +1,29 @@
+import { type L1ContractAddresses, pickL1ContractAddressMappings } from '@aztec/ethereum/l1-contract-addresses';
+import { type ConfigMappingsType, getConfigFromMappings, numberConfigHelper } from '@aztec/foundation/config';
+
+export type DataStoreConfig = {
+  dataDirectory?: string;
+  dataStoreMapSizeKb: number;
+} & Partial<Pick<L1ContractAddresses, 'rollupAddress'>>;
+
+export const dataConfigMappings: ConfigMappingsType<DataStoreConfig> = {
+  dataDirectory: {
+    env: 'DATA_DIRECTORY',
+    description: 'Optional dir to store data. If omitted will store in memory.',
+  },
+  dataStoreMapSizeKb: {
+    env: 'DATA_STORE_MAP_SIZE_KB',
+    description: 'The maximum possible size of a data store DB in KB. Can be overridden by component-specific options.',
+    ...numberConfigHelper(128 * 1_024 * 1_024), // Defaulted to 128 GB
+  },
+  ...pickL1ContractAddressMappings('rollupAddress'),
+};
+
+/**
+ * Returns the archiver configuration from the environment variables.
+ * Note: If an environment variable is not set, the default value is used.
+ * @returns The archiver configuration.
+ */
+export function getDataConfigFromEnv(): DataStoreConfig {
+  return getConfigFromMappings<DataStoreConfig>(dataConfigMappings);
+}

package/src/kv-store/index.ts

@@ -0,0 +1 @@
+export * from './config.js';

package/src/l1-contracts/index.ts

@@ -1 +1 @@
-export * from './slash_factory.js';
+// No exports.

package/src/logs/app_tagging_secret.ts

@@ -0,0 +1,137 @@
+import { Grumpkin } from '@aztec/foundation/crypto/grumpkin';
+import { poseidon2Hash } from '@aztec/foundation/crypto/poseidon';
+import { type Fq, Fr } from '@aztec/foundation/curves/bn254';
+import type { Point } from '@aztec/foundation/curves/grumpkin';
+
+import { z } from 'zod';
+
+import { AztecAddress } from '../aztec-address/index.js';
+import type { CompleteAddress } from '../contract/complete_address.js';
+import { computeAddressSecret, computePreaddress } from '../keys/derivation.js';
+import { AppTaggingSecretKind } from './app_tagging_secret_kind.js';
+
+const AppTaggingSecretKindSchema = z.union([
+  z.literal(AppTaggingSecretKind.UNCONSTRAINED),
+  z.literal(AppTaggingSecretKind.CONSTRAINED),
+]);
+
+/**
+ * Application tagging secret used for log tagging.
+ *
+ * It bundles a tagging secret with the app contract address. Unconstrained secrets are derived by the simulator from
+ * `(sender, recipient, app)` via ECDH. Constrained secrets are supplied to the simulator by the caller as an
+ * app-siloed shared secret retrieved from a handshake registry.
+ */
+export class AppTaggingSecret {
+  constructor(
+    public readonly secret: Fr,
+    public readonly app: AztecAddress,
+    public readonly kind: AppTaggingSecretKind = AppTaggingSecretKind.UNCONSTRAINED,
+  ) {}
+
+  /**
+   * Derives shared tagging secret and from that, the app address and recipient derives the directional app tagging
+   * secret. Returns undefined if `externalAddress` is an invalid address.
+   *
+   * @param localAddress - The complete address of entity A in the shared tagging secret derivation scheme
+   * @param localIvsk - The incoming viewing secret key of entity A
+   * @param externalAddress - The address of entity B in the shared tagging secret derivation scheme
+   * @param app - Contract address to silo the secret to
+   * @param recipient - Recipient of the log. Defines the "direction of the secret".
+   * @returns The secret that can be used along with an index to compute a tag to be included in a log.
+   */
+  static async computeUnconstrained(
+    localAddress: CompleteAddress,
+    localIvsk: Fq,
+    externalAddress: AztecAddress,
+    app: AztecAddress,
+    recipient: AztecAddress,
+  ): Promise<AppTaggingSecret | undefined> {
+    const taggingSecretPoint = await computeSharedTaggingSecret(localAddress, localIvsk, externalAddress);
+    if (!taggingSecretPoint) {
+      return undefined;
+    }
+
+    const appTaggingSecret = await poseidon2Hash([taggingSecretPoint.x, taggingSecretPoint.y, app]);
+    const directionalAppTaggingSecret = await poseidon2Hash([appTaggingSecret, recipient]);
+
+    return new AppTaggingSecret(directionalAppTaggingSecret, app);
+  }
+
+  toString(): string {
+    // TODO(F-680): Migrate stored tagging keys and remove the legacy unconstrained format.
+    if (this.kind === AppTaggingSecretKind.UNCONSTRAINED) {
+      return `${this.secret.toString()}:${this.app.toString()}`;
+    }
+    return `${this.kind}:${this.secret.toString()}:${this.app.toString()}`;
+  }
+
+  static fromString(str: string): AppTaggingSecret {
+    const parts = str.split(':');
+    if (parts.length === 2) {
+      // TODO(F-680): Remove legacy two-part parsing after stored tagging keys are migrated.
+      const [secretStr, appStr] = parts;
+      return new AppTaggingSecret(Fr.fromString(secretStr), AztecAddress.fromString(appStr));
+    }
+    if (parts.length === 3) {
+      const [kindStr, secretStr, appStr] = parts;
+      return new AppTaggingSecret(
+        Fr.fromString(secretStr),
+        AztecAddress.fromString(appStr),
+        appTaggingSecretKindFromString(kindStr),
+      );
+    }
+    throw new Error(`Invalid AppTaggingSecret string: ${str}`);
+  }
+}
+
+/**
+ * Parses a stored `AppTaggingSecret` string key.
+ */
+export function appTaggingSecretFromString(str: string): AppTaggingSecret {
+  return AppTaggingSecret.fromString(str);
+}
+
+export const AppTaggingSecretSchema = z
+  .object({
+    kind: AppTaggingSecretKindSchema.default(AppTaggingSecretKind.UNCONSTRAINED),
+    secret: Fr.schema,
+    app: AztecAddress.schema,
+  })
+  .transform(({ kind, secret, app }) => new AppTaggingSecret(secret, app, kind));
+
+function appTaggingSecretKindFromString(kind: string): AppTaggingSecretKind {
+  switch (kind) {
+    case AppTaggingSecretKind.CONSTRAINED:
+      return AppTaggingSecretKind.CONSTRAINED;
+    case AppTaggingSecretKind.UNCONSTRAINED:
+      return AppTaggingSecretKind.UNCONSTRAINED;
+    default:
+      throw new Error(`Invalid AppTaggingSecret kind: ${kind}`);
+  }
+}
+
+// Returns shared tagging secret computed with Diffie-Hellman key exchange, or undefined if `externalAddress` is an
+// invalid address.
+async function computeSharedTaggingSecret(
+  localAddress: CompleteAddress,
+  localIvsk: Fq,
+  externalAddress: AztecAddress,
+): Promise<Point | undefined> {
+  // Given A (local complete address) -> B (external address) and h == preaddress
+  // Compute shared secret as S = (h_A + local_ivsk_A) * Addr_Point_B
+
+  const knownPreaddress = await computePreaddress(await localAddress.publicKeys.hash(), localAddress.partialAddress);
+
+  // An invalid address has no corresponding address point
+  if (!(await externalAddress.isValid())) {
+    return undefined;
+  }
+
+  const externalAddressPoint = await externalAddress.toAddressPoint();
+
+  // Beware! h_a + local_ivsk_a (also known as the address secret) can lead to an address point with a negative
+  // y-coordinate, since there's two possible candidates computeAddressSecret takes care of selecting the one that
+  // leads to a positive y-coordinate, which is the only valid address point
+  return Grumpkin.mul(externalAddressPoint, await computeAddressSecret(knownPreaddress, localIvsk));
+}

package/src/logs/app_tagging_secret_kind.ts

@@ -0,0 +1,6 @@
+export const AppTaggingSecretKind = {
+  UNCONSTRAINED: 'unconstrained',
+  CONSTRAINED: 'constrained',
+} as const;
+
+export type AppTaggingSecretKind = (typeof AppTaggingSecretKind)[keyof typeof AppTaggingSecretKind];

package/src/logs/contract_class_log.ts

@@ -2,7 +2,7 @@ import { CONTRACT_CLASS_LOG_LENGTH, CONTRACT_CLASS_LOG_SIZE_IN_FIELDS } from '@a
 import { poseidon2Hash } from '@aztec/foundation/crypto/poseidon';
 import { Fr } from '@aztec/foundation/curves/bn254';
 import { schemas } from '@aztec/foundation/schemas';
-import { BufferReader, FieldReader, serializeToBuffer, serializeToFields } from '@aztec/foundation/serialize';
+import { BufferReader, BufferSink, FieldReader, serializeToFields, serializeToSink } from '@aztec/foundation/serialize';
 import type { FieldsOf } from '@aztec/foundation/types';
 
 import { inspect } from 'util';
@@ -56,8 +56,13 @@ export class ContractClassLogFields {
     );
   }
 
-  toBuffer() {
-    return serializeToBuffer(this.fields);
+  toBuffer(): Buffer;
+  toBuffer(sink: BufferSink): void;
+  toBuffer(sink?: BufferSink): Buffer | void {
+    if (!sink) {
+      return BufferSink.serialize(this);
+    }
+    serializeToSink(sink, this.fields);
   }
 
   static fromBuffer(buffer: Buffer | BufferReader) {
@@ -169,8 +174,13 @@ export class ContractClassLog {
     return new ContractClassLog(AztecAddress.ZERO, ContractClassLogFields.empty(), 0);
   }
 
-  toBuffer(): Buffer {
-    return serializeToBuffer([this.contractAddress, this.fields, this.emittedLength]);
+  toBuffer(): Buffer;
+  toBuffer(sink: BufferSink): void;
+  toBuffer(sink?: BufferSink): Buffer | void {
+    if (!sink) {
+      return BufferSink.serialize(this);
+    }
+    serializeToSink(sink, this.contractAddress, this.fields, this.emittedLength);
   }
 
   static fromBuffer(buffer: Buffer | BufferReader) {

package/src/logs/debug_log_store.ts

@@ -0,0 +1,54 @@
+import type { TxReceipt } from '../tx/tx_receipt.js';
+import type { DebugLog } from './debug_log.js';
+
+/**
+ * Store for debug logs emitted by public functions during transaction execution.
+ *
+ * Uses the Null Object pattern: production code uses NullDebugLogStore (no-op), while test mode uses
+ * InMemoryDebugLogStore (stores and serves logs).
+ */
+export interface DebugLogStore {
+  /** Store debug logs for a processed transaction. */
+  storeLogs(txHash: string, logs: DebugLog[]): void;
+  /** Decorate a TxReceipt with any stored debug logs for the given tx. */
+  decorateReceiptWithLogs(txHash: string, receipt: TxReceipt): void;
+  /** Whether debug log collection is enabled. */
+  readonly isEnabled: boolean;
+}
+
+/** No-op implementation for production mode. */
+export class NullDebugLogStore implements DebugLogStore {
+  storeLogs(_txHash: string, _logs: DebugLog[]): void {
+    return;
+  }
+  decorateReceiptWithLogs(_txHash: string, _receipt: TxReceipt): void {
+    return;
+  }
+  get isEnabled(): boolean {
+    return false;
+  }
+}
+
+/** In-memory implementation for test mode that stores and serves debug logs. */
+export class InMemoryDebugLogStore implements DebugLogStore {
+  private map = new Map<string, DebugLog[]>();
+
+  storeLogs(txHash: string, logs: DebugLog[]): void {
+    if (logs.length > 0) {
+      this.map.set(txHash, logs);
+    }
+  }
+
+  decorateReceiptWithLogs(txHash: string, receipt: TxReceipt): void {
+    if (receipt.isMined()) {
+      const debugLogs = this.map.get(txHash);
+      if (debugLogs) {
+        receipt.debugLogs = debugLogs;
+      }
+    }
+  }
+
+  get isEnabled(): boolean {
+    return true;
+  }
+}

package/src/logs/index.ts

@@ -1,16 +1,18 @@
-export * from './directional_app_tagging_secret.js';
+export * from './app_tagging_secret_kind.js';
+export * from './app_tagging_secret.js';
 export * from './pre_tag.js';
+export * from './tagging_index_range.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 './log_result.js';
+export * from './log_cursor.js';
+export * from './logs_query.js';
+export * from './query_all_logs_by_tags.js';
 export * from './shared_secret_derivation.js';
-export * from './tx_scoped_l2_log.js';
 export * from './message_context.js';
 export * from './debug_log.js';
+export * from './debug_log_store.js';
 export * from './tag.js';
 export * from './siloed_tag.js';

package/src/logs/log_cursor.ts

@@ -0,0 +1,110 @@
+import { BlockNumber, BlockNumberSchema } from '@aztec/foundation/branded-types';
+import { BufferReader, numToUInt32BE } from '@aztec/foundation/serialize';
+
+import { z } from 'zod';
+
+import { schemas } from '../schemas/schemas.js';
+import type { LogResultBase } from './log_result.js';
+
+/**
+ * Cursor identifying a position in a tag's ordered log stream. Used as `afterLog` on `TagQuery` to resume
+ * pagination strictly after a previously-seen log.
+ *
+ * `(blockNumber, txIndexWithinBlock, logIndexWithinTx)` is sufficient to uniquely identify a position
+ * and matches the composite-key ordering of the archiver's log index, so the cursor maps directly to a
+ * key without a tx-hash lookup. All three fields are always present on {@link LogResult}, so a cursor is
+ * constructible from any returned log.
+ */
+export class LogCursor {
+  constructor(
+    /** The block the cursor points to. */
+    public readonly blockNumber: BlockNumber,
+    /** The tx index within the block the cursor points to. */
+    public readonly txIndexWithinBlock: number,
+    /** The log index within the tx the cursor points to. */
+    public readonly logIndexWithinTx: number,
+  ) {}
+
+  static get schema() {
+    return z
+      .object({
+        blockNumber: BlockNumberSchema,
+        txIndexWithinBlock: schemas.Integer,
+        logIndexWithinTx: schemas.Integer,
+      })
+      .transform(
+        ({ blockNumber, txIndexWithinBlock, logIndexWithinTx }) =>
+          new LogCursor(blockNumber, txIndexWithinBlock, logIndexWithinTx),
+      );
+  }
+
+  /** Builds a cursor that points at the given log. Pagination resumes strictly after this position. */
+  static fromLog(log: Pick<LogResultBase, 'blockNumber' | 'txIndexWithinBlock' | 'logIndexWithinTx'>): LogCursor {
+    return new LogCursor(log.blockNumber, log.txIndexWithinBlock, log.logIndexWithinTx);
+  }
+
+  static random(): LogCursor {
+    return new LogCursor(
+      BlockNumber(Math.floor(Math.random() * 100000) + 1),
+      Math.floor(Math.random() * 100),
+      Math.floor(Math.random() * 100),
+    );
+  }
+
+  toBuffer(): Buffer {
+    return Buffer.concat([
+      numToUInt32BE(this.blockNumber),
+      numToUInt32BE(this.txIndexWithinBlock),
+      numToUInt32BE(this.logIndexWithinTx),
+    ]);
+  }
+
+  static fromBuffer(buffer: Buffer | BufferReader): LogCursor {
+    const reader = BufferReader.asReader(buffer);
+    const blockNumber = BlockNumber(reader.readNumber());
+    const txIndexWithinBlock = reader.readNumber();
+    const logIndexWithinTx = reader.readNumber();
+    return new LogCursor(blockNumber, txIndexWithinBlock, logIndexWithinTx);
+  }
+
+  equals(other: LogCursor): boolean {
+    return (
+      this.blockNumber === other.blockNumber &&
+      this.txIndexWithinBlock === other.txIndexWithinBlock &&
+      this.logIndexWithinTx === other.logIndexWithinTx
+    );
+  }
+
+  toString(): string {
+    return `${this.blockNumber}-${this.txIndexWithinBlock}-${this.logIndexWithinTx}`;
+  }
+
+  /**
+   * Parses a `<blockNumber>-<txIndexWithinBlock>-<logIndexWithinTx>` triple into a {@link LogCursor}.
+   * Throws on malformed input. Returns `undefined` for an empty / missing value so callers can use
+   * this directly as an optional CLI option parser.
+   */
+  static parseOptional(value: string): LogCursor | undefined {
+    if (!value) {
+      return undefined;
+    }
+    const parts = value.split('-');
+    if (parts.length !== 3) {
+      throw new Error(`Invalid log cursor "${value}". Expected <blockNumber>-<txIndexWithinBlock>-<logIndexWithinTx>.`);
+    }
+    const [blockNumberStr, txIndexStr, logIndexStr] = parts;
+    const blockNumber = Number(blockNumberStr);
+    const txIndexWithinBlock = Number(txIndexStr);
+    const logIndexWithinTx = Number(logIndexStr);
+    if (!Number.isInteger(blockNumber) || blockNumber < 1) {
+      throw new Error(`Invalid log cursor block number: ${blockNumberStr}`);
+    }
+    if (!Number.isInteger(txIndexWithinBlock) || txIndexWithinBlock < 0) {
+      throw new Error(`Invalid log cursor tx index: ${txIndexStr}`);
+    }
+    if (!Number.isInteger(logIndexWithinTx) || logIndexWithinTx < 0) {
+      throw new Error(`Invalid log cursor log index: ${logIndexStr}`);
+    }
+    return new LogCursor(BlockNumber(blockNumber), txIndexWithinBlock, logIndexWithinTx);
+  }
+}

package/src/logs/log_result.ts

@@ -0,0 +1,104 @@
+import { BlockNumber, BlockNumberSchema } from '@aztec/foundation/branded-types';
+import { times } from '@aztec/foundation/collection';
+import { Fr } from '@aztec/foundation/curves/bn254';
+import { schemas as foundationSchemas } from '@aztec/foundation/schemas';
+import type { IfFlag, Prettify } from '@aztec/foundation/types';
+
+import { z } from 'zod';
+
+import { BlockHash } from '../block/block_hash.js';
+import { schemas } from '../schemas/schemas.js';
+import { TxHash } from '../tx/tx_hash.js';
+import type { UInt64 } from '../types/shared.js';
+
+/** Options for narrowing the shape of a {@link LogResult}. */
+export type LogIncludeOptions = {
+  /** When set, the log carries `noteHashes` + all `nullifiers` from its tx effect. Off by default. */
+  includeEffects?: boolean;
+};
+
+export const LogIncludeOptionsSchema: z.ZodType<LogIncludeOptions> = z.object({
+  includeEffects: z.boolean().optional(),
+});
+
+/** Required metadata always present on a {@link LogResult}. */
+export type LogResultBase = {
+  /** The data contents of the log, with the tag as the first field. */
+  logData: Fr[];
+  /** The block this log was emitted in. */
+  blockNumber: BlockNumber;
+  /** The hash of the block this log was emitted in. */
+  blockHash: BlockHash;
+  /** The timestamp of the block this log was emitted in. */
+  blockTimestamp: UInt64;
+  /** The hash of the tx this log was emitted in. */
+  txHash: TxHash;
+  /** The 0-based index of this log's tx within its block. */
+  txIndexWithinBlock: number;
+  /** The 0-based index of this log within its tx (across both private and public logs for the tx). */
+  logIndexWithinTx: number;
+};
+
+/**
+ * A single log returned from {@link L2LogsSource.getPrivateLogsByTags} or {@link L2LogsSource.getPublicLogsByTags}.
+ *
+ * Generic over the include-options so that flagged fields become required when the caller passes a
+ * literal `true`. The default type argument ({@link LogIncludeOptions}) yields the widest shape
+ * (all include-fields optional) — this is what the JSON-RPC wire layer validates against.
+ *
+ * `logData` is the raw field-element payload, with the tag in field 0 (consumers slice it off).
+ *
+ * @example
+ * const l: LogResult<{ includeEffects: true }> = (await node.getPrivateLogsByTags({ tags, includeEffects: true }))[0][0];
+ * l.nullifiers; // required, not optional
+ */
+export type LogResult<Opts extends LogIncludeOptions = LogIncludeOptions> = Prettify<
+  LogResultBase & IfFlag<LogIncludeOptions, Opts, 'includeEffects', { noteHashes: Fr[]; nullifiers: Fr[] }>
+>;
+
+/** Zod schema for the widest {@link LogResult} shape (all include-gated fields optional). */
+export const LogResultSchema: z.ZodType<LogResult> = z.object({
+  logData: z.array(foundationSchemas.Fr),
+  blockNumber: BlockNumberSchema,
+  blockHash: BlockHash.schema,
+  blockTimestamp: schemas.UInt64,
+  txHash: TxHash.schema,
+  txIndexWithinBlock: schemas.Integer,
+  logIndexWithinTx: schemas.Integer,
+  noteHashes: z.array(foundationSchemas.Fr).optional(),
+  nullifiers: z.array(foundationSchemas.Fr).optional(),
+});
+
+/** Builds a random {@link LogResult} for tests. `includeEffects` populates `noteHashes` + `nullifiers`. */
+export function randomLogResult(includeEffects = false): LogResult {
+  const base: LogResultBase = {
+    logData: times(3, Fr.random),
+    blockNumber: BlockNumber(Math.floor(Math.random() * 100000) + 1),
+    blockHash: BlockHash.random(),
+    blockTimestamp: BigInt(Math.floor(Date.now() / 1000)),
+    txHash: TxHash.random(),
+    txIndexWithinBlock: Math.floor(Math.random() * 100),
+    logIndexWithinTx: Math.floor(Math.random() * 100),
+  };
+  if (includeEffects) {
+    return { ...base, noteHashes: times(3, Fr.random), nullifiers: times(3, Fr.random) };
+  }
+  return base;
+}
+
+/** Human-readable single-line representation, primarily for the CLI `get-logs` command. */
+export function logResultToHumanReadable(log: LogResult): string {
+  const head =
+    `block ${log.blockNumber} (${log.blockHash.toString()}) ` +
+    `tx ${log.txHash.toString()} txIndex ${log.txIndexWithinBlock} logIndex ${log.logIndexWithinTx} ` +
+    `ts ${log.blockTimestamp}`;
+  const data = `data [${log.logData.map(f => f.toString()).join(', ')}]`;
+  const parts = [head, data];
+  if (log.noteHashes !== undefined) {
+    parts.push(`noteHashes [${log.noteHashes.map(f => f.toString()).join(', ')}]`);
+  }
+  if (log.nullifiers !== undefined) {
+    parts.push(`nullifiers [${log.nullifiers.map(f => f.toString()).join(', ')}]`);
+  }
+  return parts.join(' | ');
+}

package/src/logs/logs_query.ts

@@ -0,0 +1,138 @@
+import { BlockNumberSchema } from '@aztec/foundation/branded-types';
+import type { BlockNumber } from '@aztec/foundation/branded-types';
+
+import { z } from 'zod';
+
+import type { AztecAddress } from '../aztec-address/index.js';
+import { BlockHash } from '../block/block_hash.js';
+import { MAX_LOGS_PER_TAG, MAX_RPC_LEN } from '../interfaces/api_limit.js';
+import { type ZodFor, schemas, zodFor } from '../schemas/index.js';
+import { TxHash } from '../tx/tx_hash.js';
+import { LogCursor } from './log_cursor.js';
+import { SiloedTag } from './siloed_tag.js';
+import { Tag } from './tag.js';
+
+/**
+ * A tag to query in {@link PrivateLogsQuery} / {@link PublicLogsQuery}, optionally resuming strictly
+ * after a previously-seen log via `afterLog`. The bare `T` form means "from the beginning".
+ */
+export type TagQuery<T extends Tag | SiloedTag> = T | { tag: T; afterLog?: LogCursor };
+
+/**
+ * Shared fields for {@link PrivateLogsQuery} and {@link PublicLogsQuery}.
+ */
+export type LogsQueryBase = {
+  /** Lower block bound, inclusive. */
+  fromBlock?: BlockNumber;
+  /** Upper block bound, exclusive. */
+  toBlock?: BlockNumber;
+  /**
+   * Restrict results to logs emitted in this transaction. Mutually exclusive with `fromBlock`/`toBlock`
+   * (a txHash already pins a block). `txHash` + `afterLog` is allowed and paginates within the tx's logs
+   * for that tag.
+   */
+  txHash?: TxHash;
+  /**
+   * Reorg-safety anchor: the latest block hash the caller has synced to. If set and the block is no
+   * longer present, the call throws. Distinct from `toBlock`, which is a filter, not a safety check.
+   */
+  referenceBlock?: BlockHash;
+  /** When set, each log also carries `noteHashes` and all `nullifiers` for note-nonce discovery. */
+  includeEffects?: boolean;
+  /**
+   * Maximum number of logs returned per tag. Capped at {@link MAX_LOGS_PER_TAG} (rejected if higher).
+   * Defaults to {@link MAX_LOGS_PER_TAG} when unset. Mainly useful for tests that need to force
+   * pagination at a small page size.
+   */
+  limitPerTag?: number;
+};
+
+/**
+ * Query for {@link L2LogsSource.getPrivateLogsByTags}. Returns one inner array per element of `tags`,
+ * in input order.
+ */
+export type PrivateLogsQuery = LogsQueryBase & {
+  /** Tags to query. Between 1 and {@link MAX_RPC_LEN} entries (inclusive). */
+  tags: TagQuery<SiloedTag>[];
+};
+
+/**
+ * Query for {@link L2LogsSource.getPublicLogsByTags}. Returns one inner array per element of `tags`,
+ * in input order.
+ */
+export type PublicLogsQuery = LogsQueryBase & {
+  /** Contract address that emitted the logs. Required for public queries. */
+  contractAddress: AztecAddress;
+  /** Tags to query. Between 1 and {@link MAX_RPC_LEN} entries (inclusive). */
+  tags: TagQuery<Tag>[];
+};
+
+function tagQuerySchema<T extends Tag | SiloedTag>(tagSchema: ZodFor<T>) {
+  return z.union([
+    tagSchema,
+    z.object({
+      tag: tagSchema,
+      afterLog: LogCursor.schema.optional(),
+    }),
+  ]) as ZodFor<TagQuery<T>>;
+}
+
+const logsQueryBaseShape = {
+  fromBlock: BlockNumberSchema.optional(),
+  toBlock: BlockNumberSchema.optional(),
+  txHash: TxHash.schema.optional(),
+  referenceBlock: BlockHash.schema.optional(),
+  includeEffects: z.boolean().optional(),
+  limitPerTag: z
+    .number()
+    .int()
+    .positive()
+    .max(MAX_LOGS_PER_TAG, { message: `limitPerTag must be <= ${MAX_LOGS_PER_TAG}` })
+    .optional(),
+};
+
+/** Minimal shape required by {@link refineTxHashAndRange}. */
+type TxHashAndRangeFields = {
+  /** Tx hash filter. */
+  txHash?: TxHash;
+  /** Lower block bound. */
+  fromBlock?: BlockNumber;
+  /** Upper block bound (exclusive). */
+  toBlock?: BlockNumber;
+};
+
+/**
+ * Refinement: a `txHash` already pins a block, so combining it with a block range is contradictory.
+ * (`txHash` + `afterLog` is still allowed and is enforced per-tag inside `TagQuery`.) Exported so
+ * `aztec.js`'s wallet event-filter schemas can reuse the same rule.
+ */
+export function refineTxHashAndRange<T extends TxHashAndRangeFields>(schema: z.ZodType<T>) {
+  return schema.refine(q => !(q.txHash !== undefined && (q.fromBlock !== undefined || q.toBlock !== undefined)), {
+    message: '`txHash` is mutually exclusive with `fromBlock`/`toBlock`',
+  });
+}
+
+export const PrivateLogsQuerySchema: ZodFor<PrivateLogsQuery> = refineTxHashAndRange(
+  zodFor<PrivateLogsQuery>()(
+    z.object({
+      ...logsQueryBaseShape,
+      tags: z
+        .array(tagQuerySchema(SiloedTag.schema))
+        .min(1)
+        .max(MAX_RPC_LEN, { message: `tags must have at most ${MAX_RPC_LEN} entries` }),
+    }),
+  ),
+);
+
+export const PublicLogsQuerySchema: ZodFor<PublicLogsQuery> = refineTxHashAndRange(
+  zodFor<PublicLogsQuery>()(
+    z.object({
+      ...logsQueryBaseShape,
+      contractAddress: schemas.AztecAddress,
+      tags: z
+        .array(tagQuerySchema(Tag.schema))
+        .min(1)
+        .max(MAX_RPC_LEN, { message: `tags must have at most ${MAX_RPC_LEN} entries` }),
+    }),
+  ),
+);