@aztec/stdlib 0.0.1-commit.e558bd1c → 0.0.1-commit.e57c76e

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` }),
+    }),
+  ),
+);

package/src/logs/message_context.ts

@@ -1,9 +1,8 @@
 import { MAX_NOTE_HASHES_PER_TX } from '@aztec/constants';
+import { range } from '@aztec/foundation/array';
 import { Fr } from '@aztec/foundation/curves/bn254';
 
-import type { AztecAddress } from '../aztec-address/index.js';
-import type { TxEffect } from '../tx/tx_effect.js';
-import type { TxHash } from '../tx/tx_hash.js';
+import { TxHash } from '../tx/tx_hash.js';
 
 /**
  * Additional information needed to process a message.
@@ -19,7 +18,6 @@ export class MessageContext {
     public txHash: TxHash,
     public uniqueNoteHashesInTx: Fr[],
     public firstNullifierInTx: Fr,
-    public recipient: AztecAddress,
   ) {}
 
   toFields(): Fr[] {
@@ -27,7 +25,6 @@ export class MessageContext {
       this.txHash.hash,
       ...serializeBoundedVec(this.uniqueNoteHashesInTx, MAX_NOTE_HASHES_PER_TX),
       this.firstNullifierInTx,
-      this.recipient.toField(),
     ];
   }
 
@@ -37,13 +34,26 @@ export class MessageContext {
       tx_hash: this.txHash.hash,
       unique_note_hashes_in_tx: this.uniqueNoteHashesInTx,
       first_nullifier_in_tx: this.firstNullifierInTx,
-      recipient: this.recipient,
     };
     /* eslint-enable camelcase */
   }
 
-  static fromTxEffectAndRecipient(txEffect: TxEffect, recipient: AztecAddress): MessageContext {
-    return new MessageContext(txEffect.txHash, txEffect.noteHashes, txEffect.nullifiers[0], recipient);
+  static empty(): MessageContext {
+    return new MessageContext(TxHash.zero(), [], Fr.ZERO);
+  }
+
+  static toEmptyFields(): Fr[] {
+    const serializationLen =
+      1 /* txHash */ + MAX_NOTE_HASHES_PER_TX + 1 /* uniqueNoteHashesInTx BVec */ + 1; /* firstNullifierInTx */
+    return range(serializationLen).map(_ => Fr.zero());
+  }
+
+  static toSerializedOption(response: MessageContext | null): Fr[] {
+    if (response) {
+      return [new Fr(1), ...response.toFields()];
+    } else {
+      return [new Fr(0), ...MessageContext.toEmptyFields()];
+    }
   }
 }
 
@@ -55,6 +65,10 @@ export class MessageContext {
  * @dev Copied over from pending_tagged_log.ts.
  */
 function serializeBoundedVec(values: Fr[], maxLength: number): Fr[] {
+  if (values.length > maxLength) {
+    throw new Error(`Attempted to serialize ${values} values into a BoundedVec with max length ${maxLength}`);
+  }
+
   const lengthDiff = maxLength - values.length;
   const zeroPaddingArray = Array(lengthDiff).fill(Fr.ZERO);
   const storage = values.concat(zeroPaddingArray);

package/src/logs/pending_tagged_log.ts

@@ -1,7 +1,6 @@
 import { PRIVATE_LOG_SIZE_IN_FIELDS } from '@aztec/constants';
 import { Fr } from '@aztec/foundation/curves/bn254';
 
-import type { AztecAddress } from '../aztec-address/index.js';
 import type { TxHash } from '../tx/tx_hash.js';
 import { MessageContext } from './message_context.js';
 
@@ -17,9 +16,8 @@ export class PendingTaggedLog {
     txHash: TxHash,
     uniqueNoteHashesInTx: Fr[],
     firstNullifierInTx: Fr,
-    recipient: AztecAddress,
   ) {
-    this.context = new MessageContext(txHash, uniqueNoteHashesInTx, firstNullifierInTx, recipient);
+    this.context = new MessageContext(txHash, uniqueNoteHashesInTx, firstNullifierInTx);
   }
 
   toFields(): Fr[] {

package/src/logs/pre_tag.ts

@@ -2,10 +2,7 @@ import { schemas } from '@aztec/foundation/schemas';
 
 import { z } from 'zod';
 
-import {
-  type DirectionalAppTaggingSecret,
-  DirectionalAppTaggingSecretSchema,
-} from './directional_app_tagging_secret.js';
+import { type AppTaggingSecret, AppTaggingSecretSchema } from './app_tagging_secret.js';
 
 /**
  * Represents a preimage of a private log tag (see `Tag` in `pxe/src/tagging`).
@@ -15,11 +12,11 @@ import {
  * around this.
  */
 export type PreTag = {
-  secret: DirectionalAppTaggingSecret;
+  extendedSecret: AppTaggingSecret;
   index: number;
 };
 
 export const PreTagSchema = z.object({
-  secret: DirectionalAppTaggingSecretSchema,
+  extendedSecret: AppTaggingSecretSchema,
   index: schemas.Integer,
 });

package/src/logs/private_log.ts

@@ -5,10 +5,11 @@ import { Fr } from '@aztec/foundation/curves/bn254';
 import { schemas } from '@aztec/foundation/schemas';
 import {
   BufferReader,
+  BufferSink,
   FieldReader,
   type Tuple,
-  serializeToBuffer,
   serializeToFields,
+  serializeToSink,
 } from '@aztec/foundation/serialize';
 
 import { inspect } from 'util';
@@ -67,8 +68,13 @@ export class PrivateLog {
     return new PrivateLog(makeTuple(PRIVATE_LOG_SIZE_IN_FIELDS, Fr.zero), 0);
   }
 
-  toBuffer(): Buffer {
-    return serializeToBuffer(this.fields, this.emittedLength);
+  toBuffer(): Buffer;
+  toBuffer(sink: BufferSink): void;
+  toBuffer(sink?: BufferSink): Buffer | void {
+    if (!sink) {
+      return BufferSink.serialize(this);
+    }
+    serializeToSink(sink, this.fields, this.emittedLength);
   }
 
   static fromBuffer(buffer: Buffer | BufferReader) {

package/src/logs/public_log.ts

@@ -120,8 +120,8 @@ export class FlatPublicLogs {
 
 export class PublicLog {
   constructor(
-    public contractAddress: AztecAddress,
-    public fields: Fr[],
+    public readonly contractAddress: AztecAddress,
+    public readonly fields: Fr[],
   ) {}
 
   static from(fields: FieldsOf<PublicLog>) {
@@ -146,7 +146,9 @@ export class PublicLog {
     return this.fields.length + PUBLIC_LOG_HEADER_LENGTH;
   }
 
+  /** Returns the serialized log (field as in noir field and not a struct field). */
   getEmittedFields() {
+    // We slice from 0 to return a shallow copy.
     return this.fields.slice(0);
   }
 

package/src/logs/query_all_logs_by_tags.ts

@@ -0,0 +1,98 @@
+import { MAX_LOGS_PER_TAG } from '../interfaces/api_limit.js';
+import { LogCursor } from './log_cursor.js';
+import type { LogResult } from './log_result.js';
+import type { PrivateLogsQuery, PublicLogsQuery, TagQuery } from './logs_query.js';
+import type { SiloedTag } from './siloed_tag.js';
+import type { Tag } from './tag.js';
+
+/** Minimal node surface needed by {@link queryAllPrivateLogsByTags}. */
+export type PrivateLogsByTagsFetcher = {
+  getPrivateLogsByTags(query: PrivateLogsQuery): Promise<LogResult[][]>;
+};
+
+/** Minimal node surface needed by {@link queryAllPublicLogsByTags}. */
+export type PublicLogsByTagsFetcher = {
+  getPublicLogsByTags(query: PublicLogsQuery): Promise<LogResult[][]>;
+};
+
+/**
+ * Drives the per-tag `afterLog` cursor loop for {@link PrivateLogsByTagsFetcher.getPrivateLogsByTags}.
+ *
+ * Each round re-queries only the tags whose previous page was full (`length === effective limit`), passing
+ * the cursor of the last seen log. Tags drop out as soon as they return a short page. Results are stitched
+ * back into one inner array per input tag, preserving the original input order.
+ *
+ * Honors {@link PrivateLogsQuery.limitPerTag} when set (caller is responsible for keeping it `<=`
+ * {@link MAX_LOGS_PER_TAG}; the query schema enforces this on the RPC boundary).
+ */
+export function queryAllPrivateLogsByTags(
+  node: PrivateLogsByTagsFetcher,
+  query: PrivateLogsQuery,
+): Promise<LogResult[][]> {
+  return queryAllByTags(
+    query.tags,
+    tagQueries => node.getPrivateLogsByTags({ ...query, tags: tagQueries }),
+    query.limitPerTag,
+  );
+}
+
+/** {@inheritDoc queryAllPrivateLogsByTags} */
+export function queryAllPublicLogsByTags(
+  node: PublicLogsByTagsFetcher,
+  query: PublicLogsQuery,
+): Promise<LogResult[][]> {
+  return queryAllByTags(
+    query.tags,
+    tagQueries => node.getPublicLogsByTags({ ...query, tags: tagQueries }),
+    query.limitPerTag,
+  );
+}
+
+/**
+ * Generic per-tag pagination loop, abstracted over the query shape (private vs public). Caller supplies
+ * a `fetchPage` that runs one round against the node with the still-active subset of tag queries.
+ *
+ * @param tags - Input tag queries in original order. Returned outer array has the same length and order.
+ * @param fetchPage - Per-round fetch hook; receives the active subset and returns one page per active tag.
+ * @param limitPerTag - Effective page cap used to detect "full page" → keep paginating; defaults to
+ *   {@link MAX_LOGS_PER_TAG} (the server-side cap when the query doesn't override).
+ */
+async function queryAllByTags<T extends Tag | SiloedTag>(
+  tags: TagQuery<T>[],
+  fetchPage: (tagQueries: TagQuery<T>[]) => Promise<LogResult[][]>,
+  limitPerTag: number | undefined,
+): Promise<LogResult[][]> {
+  const effectiveLimit = limitPerTag ?? MAX_LOGS_PER_TAG;
+  const allResultsPerTag: LogResult[][] = tags.map(() => []);
+  let activeIndexes = tags.map((_, i) => i);
+  let nextQueries: TagQuery<T>[] = tags.slice();
+
+  while (activeIndexes.length > 0) {
+    const pageResults = await fetchPage(nextQueries);
+
+    const stillActive: number[] = [];
+    const followups: TagQuery<T>[] = [];
+    for (let i = 0; i < activeIndexes.length; i++) {
+      const originalIdx = activeIndexes[i];
+      const pageForTag = pageResults[i];
+      allResultsPerTag[originalIdx].push(...pageForTag);
+      if (pageForTag.length === effectiveLimit) {
+        const lastLog = pageForTag[pageForTag.length - 1];
+        stillActive.push(originalIdx);
+        followups.push({ tag: tagOf(tags[originalIdx]), afterLog: LogCursor.fromLog(lastLog) });
+      }
+    }
+    activeIndexes = stillActive;
+    nextQueries = followups;
+  }
+
+  return allResultsPerTag;
+}
+
+/** Unwraps a `TagQuery` to its underlying `Tag` / `SiloedTag` regardless of the bare-vs-object form. */
+function tagOf<T extends Tag | SiloedTag>(entry: TagQuery<T>): T {
+  if (typeof entry === 'object' && entry !== null && 'tag' in entry) {
+    return entry.tag;
+  }
+  return entry as T;
+}

package/src/logs/shared_secret_derivation.ts

@@ -1,26 +1,37 @@
+import { DomainSeparator } from '@aztec/constants';
 import { Grumpkin } from '@aztec/foundation/crypto/grumpkin';
-import type { GrumpkinScalar, Point } from '@aztec/foundation/curves/grumpkin';
+import { poseidon2HashWithSeparator } from '@aztec/foundation/crypto/poseidon';
+import type { Fr } from '@aztec/foundation/curves/bn254';
+import type { GrumpkinScalar } from '@aztec/foundation/curves/grumpkin';
 
+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.
+ * Derives an app-siloed ECDH shared secret.
+ *
+ * Computes the raw ECDH shared secret `S = secretKey * publicKey`, then app-silos it:
+ * `s_app = h(DOM_SEP__APP_SILOED_ECDH_SHARED_SECRET, S.x, S.y, contractAddress)`
  *
  * @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.
+ * @param contractAddress - The address of the calling contract, used for app-siloing.
+ * @returns The app-siloed shared secret as a Field.
  * @throws If the publicKey is zero.
- *
- * TODO(#12656): This function is kept around because of the utilityGetSharedSecret oracle. Nuke this once returning
- * the app-siloed secret.
  */
-export function deriveEcdhSharedSecret(secretKey: GrumpkinScalar, publicKey: PublicKey): Promise<Point> {
+export async function deriveAppSiloedSharedSecret(
+  secretKey: GrumpkinScalar,
+  publicKey: PublicKey,
+  contractAddress: AztecAddress,
+): Promise<Fr> {
   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.`,
     );
   }
-  return Grumpkin.mul(publicKey, secretKey);
+  const rawSharedSecret = await Grumpkin.mul(publicKey, secretKey);
+  return poseidon2HashWithSeparator(
+    [rawSharedSecret.x, rawSharedSecret.y, contractAddress],
+    DomainSeparator.APP_SILOED_ECDH_SHARED_SECRET,
+  );
 }

package/src/logs/siloed_tag.ts

@@ -1,29 +1,39 @@
-import { GeneratorIndex } from '@aztec/constants';
-import { poseidon2HashWithSeparator } from '@aztec/foundation/crypto/poseidon';
-import type { Fr } from '@aztec/foundation/curves/bn254';
+import { DomainSeparator } from '@aztec/constants';
+import { Fr } from '@aztec/foundation/curves/bn254';
 import type { ZodFor } from '@aztec/foundation/schemas';
 
 import type { AztecAddress } from '../aztec-address/index.js';
+import { computeLogTag, computeSiloedPrivateLogFirstField } from '../hash/hash.js';
 import { schemas } from '../schemas/schemas.js';
-import type { Tag } from './tag.js';
-
-/* eslint-disable @typescript-eslint/no-unsafe-declaration-merging */
-
-/** Branding to ensure fields are not interchangeable types. */
-export interface SiloedTag {
-  /** Brand. */
-  _branding: 'SiloedTag';
-}
+import { AppTaggingSecretKind } from './app_tagging_secret_kind.js';
+import type { PreTag } from './pre_tag.js';
+import { Tag } from './tag.js';
 
 /**
  * Represents a tag used in private log as it "appears on the chain" - that is the tag is siloed with a contract
  * address that emitted the log.
  */
 export class SiloedTag {
+  /** Branding for nominal typing. */
+  declare private readonly _branding: 'SiloedTag';
+
   constructor(public readonly value: Fr) {}
 
-  static async compute(tag: Tag, app: AztecAddress): Promise<SiloedTag> {
-    const siloedTag = await poseidon2HashWithSeparator([app, tag.value], GeneratorIndex.PRIVATE_LOG_FIRST_FIELD);
+  static async compute(preTag: PreTag): Promise<SiloedTag> {
+    const tag = await Tag.compute(preTag);
+    const domainSeparator =
+      preTag.extendedSecret.kind === AppTaggingSecretKind.CONSTRAINED
+        ? DomainSeparator.CONSTRAINED_MSG_LOG_TAG
+        : DomainSeparator.UNCONSTRAINED_MSG_LOG_TAG;
+    const logTag = await computeLogTag(tag.value, domainSeparator);
+    return SiloedTag.computeFromTagAndApp(new Tag(logTag), preTag.extendedSecret.app);
+  }
+
+  /**
+   * Unlike `compute`, this expects a tag whose value is already domain-separated.
+   */
+  static async computeFromTagAndApp(tag: Tag, app: AztecAddress): Promise<SiloedTag> {
+    const siloedTag = await computeSiloedPrivateLogFirstField(app, tag.value);
     return new SiloedTag(siloedTag);
   }
 
@@ -39,6 +49,10 @@ export class SiloedTag {
     return this.value.equals(other.value);
   }
 
+  static random(): SiloedTag {
+    return new SiloedTag(Fr.random());
+  }
+
   static get schema(): ZodFor<SiloedTag> {
     return schemas.Fr.transform((fr: Fr) => new SiloedTag(fr));
   }

package/src/logs/tag.ts

@@ -1,26 +1,22 @@
 import { poseidon2Hash } from '@aztec/foundation/crypto/poseidon';
-import type { Fr } from '@aztec/foundation/curves/bn254';
+import { Fr } from '@aztec/foundation/curves/bn254';
 import type { ZodFor } from '@aztec/foundation/schemas';
 
 import { schemas } from '../schemas/schemas.js';
 import type { PreTag } from './pre_tag.js';
 
-/* eslint-disable @typescript-eslint/no-unsafe-declaration-merging */
-
-export interface Tag {
-  /** Brand. */
-  _branding: 'Tag';
-}
-
 /**
  * Represents a tag of a private log. This is not the tag that "appears" on the chain as this tag is first siloed
  * with a contract address by kernels before being included in the final log.
  */
 export class Tag {
+  /** Branding for nominal typing. */
+  declare private readonly _branding: 'Tag';
+
   constructor(public readonly value: Fr) {}
 
   static async compute(preTag: PreTag): Promise<Tag> {
-    const tag = await poseidon2Hash([preTag.secret.value, preTag.index]);
+    const tag = await poseidon2Hash([preTag.extendedSecret.secret, preTag.index]);
     return new Tag(tag);
   }
 
@@ -36,6 +32,10 @@ export class Tag {
     return this.value.equals(other.value);
   }
 
+  static random(): Tag {
+    return new Tag(Fr.random());
+  }
+
   static get schema(): ZodFor<Tag> {
     return schemas.Fr.transform((fr: Fr) => new Tag(fr));
   }

package/src/logs/tagging_index_range.ts

@@ -0,0 +1,18 @@
+import { schemas } from '@aztec/foundation/schemas';
+
+import { z } from 'zod';
+
+import { type AppTaggingSecret, AppTaggingSecretSchema } from './app_tagging_secret.js';
+
+/** Represents a range of tagging indexes for a given app tagging secret. */
+export type TaggingIndexRange = {
+  extendedSecret: AppTaggingSecret;
+  lowestIndex: number;
+  highestIndex: number;
+};
+
+export const TaggingIndexRangeSchema = z.object({
+  extendedSecret: AppTaggingSecretSchema,
+  lowestIndex: schemas.Integer,
+  highestIndex: schemas.Integer,
+});

package/src/messaging/append_l1_to_l2_messages.ts

@@ -0,0 +1,21 @@
+import { NUMBER_OF_L1_L2_MESSAGES_PER_ROLLUP } from '@aztec/constants';
+import { padArrayEnd } from '@aztec/foundation/collection';
+import { Fr } from '@aztec/foundation/curves/bn254';
+
+import type { MerkleTreeWriteOperations } from '../interfaces/merkle_tree_operations.js';
+import { MerkleTreeId } from '../trees/merkle_tree_id.js';
+
+/**
+ * Pads `l1ToL2Messages` to `NUMBER_OF_L1_L2_MESSAGES_PER_ROLLUP` and appends them to the
+ * L1→L2 message tree of `db`. Use whenever a fork at "state before the first block of a
+ * checkpoint" needs to mirror what the world-state synchronizer inserts at sync time.
+ */
+export async function appendL1ToL2MessagesToTree(db: MerkleTreeWriteOperations, l1ToL2Messages: Fr[]): Promise<void> {
+  const padded = padArrayEnd<Fr, number>(
+    l1ToL2Messages,
+    Fr.ZERO,
+    NUMBER_OF_L1_L2_MESSAGES_PER_ROLLUP,
+    'Too many L1 to L2 messages',
+  );
+  await db.appendLeaves(MerkleTreeId.L1_TO_L2_MESSAGE_TREE, padded);
+}

package/src/messaging/index.ts

@@ -1,3 +1,4 @@
+export * from './append_l1_to_l2_messages.js';
 export * from './in_hash.js';
 export * from './inbox_leaf.js';
 export * from './l1_to_l2_message.js';

package/src/messaging/l1_to_l2_message.ts

@@ -6,6 +6,7 @@ import { bufferToHex } from '@aztec/foundation/string';
 import { SiblingPath } from '@aztec/foundation/trees';
 
 import type { AztecAddress } from '../aztec-address/index.js';
+import type { BlockParameter } from '../block/block_parameter.js';
 import { computeL1ToL2MessageNullifier } from '../hash/hash.js';
 import type { AztecNode } from '../interfaces/aztec-node.js';
 import { MerkleTreeId } from '../trees/merkle_tree_id.js';
@@ -79,20 +80,22 @@ export async function getNonNullifiedL1ToL2MessageWitness(
   contractAddress: AztecAddress,
   messageHash: Fr,
   secret: Fr,
+  referenceBlock: BlockParameter = 'latest',
 ): Promise<[bigint, SiblingPath<typeof L1_TO_L2_MSG_TREE_HEIGHT>]> {
-  const response = await node.getL1ToL2MessageMembershipWitness('latest', messageHash);
-  if (!response) {
-    throw new Error(`No L1 to L2 message found for message hash ${messageHash.toString()}`);
-  }
+  const messageNullifier = await computeL1ToL2MessageNullifier(contractAddress, messageHash, secret);
 
-  const [messageIndex, siblingPath] = response;
+  const [l1ToL2Response, nullifierResponse] = await Promise.all([
+    node.getL1ToL2MessageMembershipWitness(referenceBlock, messageHash),
+    node.findLeavesIndexes(referenceBlock, MerkleTreeId.NULLIFIER_TREE, [messageNullifier]),
+  ]);
 
-  const messageNullifier = await computeL1ToL2MessageNullifier(contractAddress, messageHash, secret);
+  if (!l1ToL2Response) {
+    throw new Error(`No L1 to L2 message found for message hash ${messageHash.toString()}`);
+  }
 
-  const [nullifierIndex] = await node.findLeavesIndexes('latest', MerkleTreeId.NULLIFIER_TREE, [messageNullifier]);
-  if (nullifierIndex !== undefined) {
+  if (nullifierResponse[0] !== undefined) {
     throw new Error(`No non-nullified L1 to L2 message found for message hash ${messageHash.toString()}`);
   }
 
-  return [messageIndex, siblingPath];
+  return l1ToL2Response;
 }

package/src/messaging/l1_to_l2_message_source.ts

@@ -10,7 +10,9 @@ export interface L1ToL2MessageSource {
   /**
    * Gets new L1 to L2 message (to be) included in a given checkpoint.
    * @param checkpointNumber - Checkpoint number to get messages for.
-   * @returns The L1 to L2 messages/leaves of the messages subtree (throws if not found).
+   * @returns The L1 to L2 messages/leaves of the messages subtree.
+   * @throws If the message tree for the given checkpoint has not yet been sealed on L1
+   * (i.e., checkpointNumber >= inbox treeInProgress).
    */
   getL1ToL2Messages(checkpointNumber: CheckpointNumber): Promise<Fr[]>;