@aztec-labs/stdlib 6.0.0-nightly.20260829

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

@@ -0,0 +1,70 @@
+import { DomainSeparator } from '@aztec-labs/constants';
+import { Grumpkin } from '@aztec-labs/foundation/crypto/grumpkin';
+import { poseidon2HashWithSeparator } from '@aztec-labs/foundation/crypto/poseidon';
+import type { Fr } from '@aztec-labs/foundation/curves/bn254';
+import { GrumpkinScalar, type Point } from '@aztec-labs/foundation/curves/grumpkin';
+
+import type { AztecAddress } from '../aztec-address/index.js';
+import type { PublicKey } from '../keys/public_key.js';
+
+/**
+ * Derives the raw ECDH shared secret point `S = secretKey * publicKey`.
+ *
+ * @throws If the publicKey is zero.
+ */
+export function deriveEcdhSharedSecretPoint(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.`,
+    );
+  }
+  return Grumpkin.mul(publicKey, secretKey);
+}
+
+/**
+ * Derives an app-siloed ECDH shared secret from keys: ECDHs `S = secretKey * publicKey` via
+ * {@link deriveEcdhSharedSecretPoint}, then app-silos it via {@link appSiloEcdhSharedSecretPoint}.
+ *
+ * @param secretKey - The secret key used to derive shared secret.
+ * @param publicKey - The public key used to derive 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.
+ */
+export async function appSiloEcdhSharedSecret(
+  secretKey: GrumpkinScalar,
+  publicKey: PublicKey,
+  contractAddress: AztecAddress,
+): Promise<Fr> {
+  const rawSharedSecret = await deriveEcdhSharedSecretPoint(secretKey, publicKey);
+  return appSiloEcdhSharedSecretPoint(rawSharedSecret, contractAddress);
+}
+
+/**
+ * App-silos a shared secret point: `s_app = h(DOM_SEP__APP_SILOED_ECDH_SHARED_SECRET, S.x, S.y, app)`.
+ *
+ * Mirrors `compute_app_siloed_shared_secret` in aztec-nr.
+ *
+ * @param point - The raw shared secret point `S`.
+ * @param app - The contract address to silo to.
+ */
+export function appSiloEcdhSharedSecretPoint(point: Point, app: AztecAddress): Promise<Fr> {
+  return poseidon2HashWithSeparator([point.x, point.y, app], DomainSeparator.APP_SILOED_ECDH_SHARED_SECRET);
+}
+
+/**
+ * Protects a handshake's shared secret from being forged by the recipient: `S' = hash(ephPk, recipientPoint) * S`.
+ *
+ * Mirrors aztec-nr's `protect_from_forgery` and must stay byte-compatible with it.
+ *
+ * @param secret - The raw shared secret `S` to protect.
+ * @param ephPk - The handshake's ephemeral public key.
+ * @param recipientPoint - The recipient's address point.
+ */
+export async function protectFromForgery(secret: Point, ephPk: Point, recipientPoint: Point): Promise<Point> {
+  const scalar = await poseidon2HashWithSeparator(
+    [ephPk.x, ephPk.y, recipientPoint.x, recipientPoint.y],
+    DomainSeparator.HANDSHAKE_FORGERY_PROTECTION,
+  );
+  return Grumpkin.mul(secret, new GrumpkinScalar(scalar.toBigInt()));
+}

package/src/logs/siloed_tag.ts

@@ -0,0 +1,59 @@
+import { DomainSeparator } from '@aztec-labs/constants';
+import { Fr } from '@aztec-labs/foundation/curves/bn254';
+import type { ZodFor } from '@aztec-labs/foundation/schemas';
+
+import type { AztecAddress } from '../aztec-address/index.js';
+import { computeLogTag, computeSiloedPrivateLogFirstField } from '../hash/hash.js';
+import { schemas } from '../schemas/schemas.js';
+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(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);
+  }
+
+  toString(): string {
+    return this.value.toString();
+  }
+
+  toJSON(): string {
+    return this.value.toString();
+  }
+
+  equals(other: SiloedTag): boolean {
+    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

@@ -0,0 +1,42 @@
+import { poseidon2Hash } from '@aztec-labs/foundation/crypto/poseidon';
+import { Fr } from '@aztec-labs/foundation/curves/bn254';
+import type { ZodFor } from '@aztec-labs/foundation/schemas';
+
+import { schemas } from '../schemas/schemas.js';
+import type { PreTag } from './pre_tag.js';
+
+/**
+ * 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.extendedSecret.secret, preTag.index]);
+    return new Tag(tag);
+  }
+
+  toString(): string {
+    return this.value.toString();
+  }
+
+  toJSON(): string {
+    return this.value.toString();
+  }
+
+  equals(other: Tag): boolean {
+    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,17 @@
+import { schemas } from '@aztec-labs/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,13 @@
+import type { Fr } from '@aztec-labs/foundation/curves/bn254';
+
+import type { MerkleTreeWriteOperations } from '../interfaces/merkle_tree_operations.js';
+import { MerkleTreeId } from '../trees/merkle_tree_id.js';
+
+/**
+ * Appends a block's real L1→L2 message leaves (unpadded, at compact indices) to the L1→L2 message tree of `db`.
+ * Use whenever a fork at "state before a block" needs to mirror what the world-state
+ * synchronizer inserts at sync time.
+ */
+export async function appendL1ToL2MessagesToTree(db: MerkleTreeWriteOperations, l1ToL2Messages: Fr[]): Promise<void> {
+  await db.appendLeaves(MerkleTreeId.L1_TO_L2_MESSAGE_TREE, l1ToL2Messages);
+}

package/src/messaging/inbox_bucket.ts

@@ -0,0 +1,124 @@
+import { Fr } from '@aztec-labs/foundation/curves/bn254';
+import { type ZodFor, schemas } from '@aztec-labs/foundation/schemas';
+import { BufferReader, bigintToUInt64BE, serializeToBuffer } from '@aztec-labs/foundation/serialize';
+import type { FieldsOf } from '@aztec-labs/foundation/types';
+import { z } from 'zod';
+
+/**
+ * Snapshot of an Inbox rolling-hash bucket as tracked by the archiver.
+ *
+ * A bucket accumulates the message leaves inserted into the Inbox within a single L1 block (up to a per-bucket
+ * maximum, after which further messages in the same block spill into the next bucket). Buckets are identified by
+ * a dense, monotonically increasing sequence number and keyed for recency lookups by the L1 block timestamp at
+ * which they were opened. Mirrors the on-chain `InboxBucket` struct plus the fields the archiver derives while
+ * syncing.
+ */
+export type InboxBucket = {
+  /** Dense, monotonically increasing sequence number of this bucket in the Inbox ring. */
+  seq: bigint;
+  /** Consensus rolling hash (truncated sha256 chain) after the last message absorbed into this bucket. */
+  inboxRollingHash: Fr;
+  /** Cumulative number of messages inserted into the Inbox up to and including this bucket. */
+  totalMsgCount: bigint;
+  /** L1 block timestamp at which this bucket was opened; the recency key for lag/cutoff comparisons, in seconds. */
+  timestamp: bigint;
+  /** Number of messages absorbed into this bucket. */
+  msgCount: number;
+  /** Global leaf index of the last message absorbed into this bucket. */
+  lastMessageIndex: bigint;
+};
+
+export const InboxBucketSchema = z.object({
+  seq: schemas.BigInt,
+  inboxRollingHash: Fr.schema,
+  totalMsgCount: schemas.BigInt,
+  timestamp: schemas.BigInt,
+  msgCount: schemas.Integer,
+  lastMessageIndex: schemas.BigInt,
+}) satisfies z.ZodType<InboxBucket>;
+
+/**
+ * Reference to a settled Inbox rolling-hash bucket, carried alongside a block proposal so a
+ * validator can look the bucket up in its own Inbox view and derive the consumed-message bundle itself, rather than
+ * trusting a proposer-supplied message list. Pins the bucket by its dense sequence number and recency-key timestamp
+ * and asserts the expected consensus rolling hash. A wrong reference can only cause a lookup miss or hash mismatch; it
+ * can never change what a validator accepts, because the checkpoint header's `inboxRollingHash` remains the signed
+ * consensus commitment (mirrors the unsigned bucket hint on L1's `Rollup.propose`).
+ */
+export class InboxBucketRef {
+  constructor(
+    /** Dense, monotonically increasing sequence number of the referenced bucket in the Inbox ring. */
+    public readonly bucketSeq: bigint,
+    /** L1 block timestamp (in seconds) at which the referenced bucket was opened; its recency key. */
+    public readonly bucketTimestamp: bigint,
+    /** Consensus rolling hash (truncated sha256 chain) after the last message absorbed into the referenced bucket. */
+    public readonly inboxRollingHash: Fr,
+  ) {}
+
+  /** Serialized size in bytes: two uint64 fields plus one field element. */
+  static readonly SIZE = 8 + 8 + Fr.SIZE_IN_BYTES;
+
+  static get schema(): ZodFor<InboxBucketRef> {
+    return z
+      .object({
+        bucketSeq: schemas.BigInt,
+        bucketTimestamp: schemas.BigInt,
+        inboxRollingHash: Fr.schema,
+      })
+      .transform(InboxBucketRef.from);
+  }
+
+  static from(fields: FieldsOf<InboxBucketRef>): InboxBucketRef {
+    return new InboxBucketRef(fields.bucketSeq, fields.bucketTimestamp, fields.inboxRollingHash);
+  }
+
+  /** Derives a wire reference from a bucket snapshot as tracked by the archiver. */
+  static fromBucket(bucket: InboxBucket): InboxBucketRef {
+    return new InboxBucketRef(bucket.seq, bucket.timestamp, bucket.inboxRollingHash);
+  }
+
+  toBuffer(): Buffer {
+    return serializeToBuffer([
+      bigintToUInt64BE(this.bucketSeq),
+      bigintToUInt64BE(this.bucketTimestamp),
+      this.inboxRollingHash,
+    ]);
+  }
+
+  static fromBuffer(buffer: Buffer | BufferReader): InboxBucketRef {
+    const reader = BufferReader.asReader(buffer);
+    return new InboxBucketRef(reader.readUInt64(), reader.readUInt64(), reader.readObject(Fr));
+  }
+
+  getSize(): number {
+    return InboxBucketRef.SIZE;
+  }
+
+  equals(other: InboxBucketRef): boolean {
+    return (
+      this.bucketSeq === other.bucketSeq &&
+      this.bucketTimestamp === other.bucketTimestamp &&
+      this.inboxRollingHash.equals(other.inboxRollingHash)
+    );
+  }
+
+  static empty(): InboxBucketRef {
+    return new InboxBucketRef(0n, 0n, Fr.ZERO);
+  }
+
+  static random(): InboxBucketRef {
+    return new InboxBucketRef(
+      BigInt(Math.floor(Math.random() * 1000)),
+      BigInt(Math.floor(Math.random() * 1_000_000)),
+      Fr.random(),
+    );
+  }
+
+  toInspect() {
+    return {
+      bucketSeq: this.bucketSeq.toString(),
+      bucketTimestamp: this.bucketTimestamp.toString(),
+      inboxRollingHash: this.inboxRollingHash.toString(),
+    };
+  }
+}

package/src/messaging/inbox_consumption.ts

@@ -0,0 +1,74 @@
+import { MAX_L1_TO_L2_MSGS_PER_BLOCK, MAX_L1_TO_L2_MSGS_PER_CHECKPOINT } from '@aztec-labs/constants';
+import { SlotNumber } from '@aztec-labs/foundation/branded-types';
+
+import { type L1RollupConstants, getTimestampForSlot } from '../epoch-helpers/index.js';
+import type { InboxBucket } from './inbox_bucket.js';
+
+/**
+ * Censorship cutoff timestamp for a checkpoint proposed in `slot`, mirroring the cutoff in
+ * `ProposeLib.validateInboxConsumption`, which is `TimeLib.getBuildFrameStart(slot)`. A checkpoint proposed in slot
+ * `S` is built during slot `S - 1`, and the build frame opens one Ethereum slot before that slot starts, since the
+ * builder works from the L1 state as of the preceding L1 block: `cutoff(S) = toTimestamp(S - 1) - E`. Buckets opened
+ * at or before the cutoff were visible to every node for the whole build frame and are mandatory to consume by the
+ * checkpoint's last block; the strict `>` on the L1 "past cutoff" test (see {@link isInboxConsumptionSufficient})
+ * makes a bucket opened exactly at the cutoff mandatory.
+ *
+ * This is the single source of truth for the cutoff formula shared by the sequencer's streaming bucket selection and
+ * the validator's last-block censorship check.
+ */
+export function getInboxCutoffTimestamp(
+  slot: SlotNumber,
+  l1Constants: Pick<L1RollupConstants, 'l1GenesisTime' | 'slotDuration' | 'ethereumSlotDuration'>,
+): bigint {
+  return getTimestampForSlot(SlotNumber(slot - 1), l1Constants) - BigInt(l1Constants.ethereumSlotDuration);
+}
+
+/**
+ * Smallest number of blocks a checkpoint must be able to build for the streaming Inbox to be guaranteed to clear any
+ * mandatory backlog, and therefore the floor on a network's `maxBlocksPerCheckpoint`.
+ *
+ * Blocks consume whole buckets — a bucket is never split — so a block can only consume a bucket prefix whose message
+ * count fits `MAX_L1_TO_L2_MSGS_PER_BLOCK`. The worst case alternates a one-message bucket with a full
+ * `MAX_L1_TO_L2_MSGS_PER_BLOCK`-message bucket: each such pair needs two blocks (the pair's `cap + 1` messages
+ * overflow one block), and the backlog only stops being mandatory once consuming the next bucket would exceed
+ * `MAX_L1_TO_L2_MSGS_PER_CHECKPOINT` (the cap-escape). That bounds the backlog at `cap + 1` messages per block-pair
+ * and yields `2 * ceil((MAX_L1_TO_L2_MSGS_PER_CHECKPOINT + 1) / (MAX_L1_TO_L2_MSGS_PER_BLOCK + 1)) - 1` blocks (the
+ * final pair needs only its first block).
+ *
+ * A network configured below this floor can be halted permanently: an adversary posts that bucket pattern, no
+ * checkpoint can reach the censorship floor within its block budget, every checkpoint is rejected, and because a
+ * rejected checkpoint never advances the consumed position the next checkpoint faces the identical backlog.
+ */
+export const MIN_BLOCKS_FOR_INBOX_CATCHUP =
+  2 * Math.ceil((MAX_L1_TO_L2_MSGS_PER_CHECKPOINT + 1) / (MAX_L1_TO_L2_MSGS_PER_BLOCK + 1)) - 1;
+
+/**
+ * Whether a checkpoint whose last-consumed bucket is immediately followed by `nextBucket` meets the censorship floor,
+ * mirroring the mandatory-consumption assert in `ProposeLib.validateInboxConsumption`.
+ * Consumption is sufficient when the first unconsumed bucket:
+ *  - does not exist (the checkpoint consumed everything the Inbox has), or
+ *  - was opened strictly after the cutoff (`timestamp > cutoffTimestamp`), or
+ *  - consuming through it would exceed the per-checkpoint cap (the cap-escape).
+ *
+ * The strict `>` matches L1: a bucket opened exactly at the cutoff must be consumed. This is the single source of
+ * truth for the minimum-consumption / cap-escape rule shared by the sequencer's selection floor and the validator.
+ */
+export function isInboxConsumptionSufficient(input: {
+  /** The first unconsumed bucket (the one after the checkpoint's last-consumed bucket), or undefined if none exists. */
+  nextBucket: Pick<InboxBucket, 'timestamp' | 'totalMsgCount'> | undefined;
+  /** Censorship cutoff timestamp from {@link getInboxCutoffTimestamp}. */
+  cutoffTimestamp: bigint;
+  /** Cumulative Inbox message count consumed as of the parent checkpoint; the per-checkpoint cap origin. */
+  checkpointStartTotalMsgCount: bigint;
+  /** Maximum number of messages the checkpoint may consume in total (`MAX_L1_TO_L2_MSGS_PER_CHECKPOINT`). */
+  perCheckpointCap: number;
+}): boolean {
+  const { nextBucket, cutoffTimestamp, checkpointStartTotalMsgCount, perCheckpointCap } = input;
+  if (nextBucket === undefined) {
+    return true;
+  }
+  if (nextBucket.timestamp > cutoffTimestamp) {
+    return true;
+  }
+  return nextBucket.totalMsgCount - checkpointStartTotalMsgCount > BigInt(perCheckpointCap);
+}

package/src/messaging/inbox_rolling_hash.ts

@@ -0,0 +1,24 @@
+import { DomainSeparator } from '@aztec-labs/constants';
+import { sha256ToField } from '@aztec-labs/foundation/crypto/sha256';
+import { Fr } from '@aztec-labs/foundation/curves/bn254';
+import { numToUInt32BE } from '@aztec-labs/foundation/serialize';
+
+/**
+ * Extends the Inbox rolling-hash chain by a single message leaf, returning the new rolling hash.
+ *
+ * Each link is `sha256ToField(DOM_SEP__INBOX_ROLLING_HASH || prev || leaf)` over the 4-byte big-endian domain
+ * separator followed by the two 32-byte big-endian values, matching the truncated-to-field sha256 the L1 Inbox
+ * accumulates and the noir `accumulate_inbox_rolling_hash` helper. The separator distinguishes a chain link from the
+ * untagged `outHash` merkle node hash, which absorbs the same two-field preimage shape.
+ */
+export function updateInboxRollingHash(prev: Fr, leaf: Fr): Fr {
+  return sha256ToField([numToUInt32BE(DomainSeparator.INBOX_ROLLING_HASH), prev.toBuffer(), leaf.toBuffer()]);
+}
+
+/**
+ * Extends the Inbox rolling-hash chain by a list of message leaves, in order, returning the new rolling hash.
+ * The genesis rolling hash is `Fr.ZERO`, and an empty list returns `start` unchanged.
+ */
+export function accumulateInboxRollingHash(start: Fr, leaves: Fr[]): Fr {
+  return leaves.reduce(updateInboxRollingHash, start);
+}

package/src/messaging/index.ts

@@ -0,0 +1,13 @@
+export * from './append_l1_to_l2_messages.js';
+export * from './inbox_bucket.js';
+export * from './inbox_consumption.js';
+export * from './inbox_rolling_hash.js';
+export * from './l1_to_l2_message_bundle.js';
+export * from './l1_to_l2_message_sponge.js';
+export * from './l1_to_l2_message.js';
+export * from './l1_to_l2_message_source.js';
+export * from './l1_actor.js';
+export * from './l2_actor.js';
+export * from './l2_to_l1_message.js';
+export * from './l2_to_l1_membership.js';
+export * from './out_hash.js';

package/src/messaging/l1_actor.ts

@@ -0,0 +1,43 @@
+import { randomInt } from '@aztec-labs/foundation/crypto/random';
+import { Fr } from '@aztec-labs/foundation/curves/bn254';
+import { EthAddress } from '@aztec-labs/foundation/eth-address';
+import { BufferReader, serializeToBuffer } from '@aztec-labs/foundation/serialize';
+
+/**
+ * The sender of an L1 to L2 message or recipient of an L2 to L1 message.
+ */
+export class L1Actor {
+  constructor(
+    /**
+     * The sender of the message.
+     */
+    public readonly sender: EthAddress,
+    /**
+     * The chain id on which the message was sent (L1 -> L2) or on which the message will be received (L2 -> L1).
+     */
+    public readonly chainId: number,
+  ) {}
+
+  static empty() {
+    return new L1Actor(EthAddress.ZERO, 0);
+  }
+
+  toFields(): Fr[] {
+    return [this.sender.toField(), new Fr(BigInt(this.chainId))];
+  }
+
+  toBuffer(): Buffer {
+    return serializeToBuffer(this.sender, this.chainId);
+  }
+
+  static fromBuffer(buffer: Buffer | BufferReader): L1Actor {
+    const reader = BufferReader.asReader(buffer);
+    const ethAddr = reader.readObject(EthAddress);
+    const chainId = reader.readNumber();
+    return new L1Actor(ethAddr, chainId);
+  }
+
+  static random(): L1Actor {
+    return new L1Actor(EthAddress.random(), randomInt(1000));
+  }
+}