@aztec/stdlib 0.0.1-commit.e2b2873ed → 0.0.1-commit.e304674f1

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/{directional_app_tagging_secret.ts → extended_directional_app_tagging_secret.ts}

@@ -5,26 +5,32 @@ import type { Point } from '@aztec/foundation/curves/grumpkin';
 
 import { z } from 'zod';
 
-import type { AztecAddress } from '../aztec-address/index.js';
+import { AztecAddress } from '../aztec-address/index.js';
 import type { CompleteAddress } from '../contract/complete_address.js';
 import { computeAddressSecret, computePreaddress } from '../keys/derivation.js';
 
 /**
- * Directional application tagging secret used for log tagging.
+ * Extended directional application tagging secret used for log tagging.
  *
- * "Directional" because the derived secret is bound to the recipient
- * address: A→B differs from B→A even with the same participants and app.
+ * "Extended" because it bundles the directional app tagging secret with the app (contract) address. This bundling was
+ * done because where this type is used we commonly need access to both the secret and the address.
  *
- * Note: It's a bit unfortunate that this type resides in `stdlib` as the rest of the tagging functionality resides
- * in `pxe/src/tagging`. We need to use this type in `PreTag` that in turn is used by other types
- * in stdlib hence there doesn't seem to be a good way around this.
+ * "Directional" because the derived secret is bound to the recipient address: A→B differs from B→A even with the same
+ * participants and app.
+ *
+ * Note: It's a bit unfortunate that this type resides in `stdlib` as the rest of the tagging functionality resides in
+ * `pxe/src/tagging`. We need to use this type in `PreTag` that in turn is used by other types in stdlib hence there
+ * doesn't seem to be a good way around this.
  */
-export class DirectionalAppTaggingSecret {
-  private constructor(public readonly value: Fr) {}
+export class ExtendedDirectionalAppTaggingSecret {
+  constructor(
+    public readonly secret: Fr,
+    public readonly app: AztecAddress,
+  ) {}
 
   /**
    * Derives shared tagging secret and from that, the app address and recipient derives the directional app tagging
-   * secret.
+   * 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
@@ -39,41 +45,54 @@ export class DirectionalAppTaggingSecret {
     externalAddress: AztecAddress,
     app: AztecAddress,
     recipient: AztecAddress,
-  ): Promise<DirectionalAppTaggingSecret> {
+  ): Promise<ExtendedDirectionalAppTaggingSecret | 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 DirectionalAppTaggingSecret(directionalAppTaggingSecret);
+    return new ExtendedDirectionalAppTaggingSecret(directionalAppTaggingSecret, app);
   }
 
   toString(): string {
-    return this.value.toString();
+    return `${this.secret.toString()}:${this.app.toString()}`;
   }
 
-  static fromString(str: string): DirectionalAppTaggingSecret {
-    return new DirectionalAppTaggingSecret(Fr.fromString(str));
+  static fromString(str: string): ExtendedDirectionalAppTaggingSecret {
+    const [secretStr, appStr] = str.split(':');
+    return new ExtendedDirectionalAppTaggingSecret(Fr.fromString(secretStr), AztecAddress.fromString(appStr));
   }
 }
 
-// Returns shared tagging secret computed with Diffie-Hellman key exchange.
+// 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> {
-  const knownPreaddress = await computePreaddress(await localAddress.publicKeys.hash(), localAddress.partialAddress);
-  // TODO: #8970 - Computation of address point from x coordinate might fail
-  const externalAddressPoint = await externalAddress.toAddressPoint();
+): 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));
 }
 
-export const DirectionalAppTaggingSecretSchema = z.object({
-  value: Fr.schema,
+export const ExtendedDirectionalAppTaggingSecretSchema = z.object({
+  secret: Fr.schema,
+  app: AztecAddress.schema,
 });

package/src/logs/index.ts

@@ -1,5 +1,6 @@
-export * from './directional_app_tagging_secret.js';
+export * from './extended_directional_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';
@@ -12,5 +13,6 @@ 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_filter.ts

@@ -1,3 +1,5 @@
+import type { Fr } from '@aztec/foundation/curves/bn254';
+
 import { z } from 'zod';
 
 import type { AztecAddress } from '../aztec-address/index.js';
@@ -20,6 +22,8 @@ export type LogFilter = {
   afterLog?: LogId;
   /** The contract address to filter logs by. */
   contractAddress?: AztecAddress;
+  /** The tag (first field of the log) to filter logs by. */
+  tag?: Fr;
 };
 
 export const LogFilterSchema: ZodFor<LogFilter> = z.object({
@@ -28,4 +32,5 @@ export const LogFilterSchema: ZodFor<LogFilter> = z.object({
   toBlock: schemas.Integer.optional(),
   afterLog: LogId.schema.optional(),
   contractAddress: schemas.AztecAddress.optional(),
+  tag: schemas.Fr.optional(),
 });

package/src/logs/message_context.ts

@@ -1,8 +1,7 @@
 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';
 
 /**
@@ -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,22 @@ 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 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 +61,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

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

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/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,11 +1,12 @@
-import { GeneratorIndex } from '@aztec/constants';
-import { poseidon2HashWithSeparator } from '@aztec/foundation/crypto/poseidon';
+import { DomainSeparator } from '@aztec/constants';
 import type { 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';
+import type { PreTag } from './pre_tag.js';
+import { Tag } from './tag.js';
 
 /* eslint-disable @typescript-eslint/no-unsafe-declaration-merging */
 
@@ -22,8 +23,17 @@ export interface SiloedTag {
 export class 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 logTag = await computeLogTag(tag.value, DomainSeparator.UNCONSTRAINED_MSG_LOG_TAG);
+    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);
   }
 

package/src/logs/tag.ts

@@ -20,7 +20,7 @@ export class 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);
   }
 

package/src/logs/tagging_index_range.ts

@@ -0,0 +1,24 @@
+import { schemas } from '@aztec/foundation/schemas';
+
+import { z } from 'zod';
+
+import {
+  type ExtendedDirectionalAppTaggingSecret,
+  ExtendedDirectionalAppTaggingSecretSchema,
+} from './extended_directional_app_tagging_secret.js';
+
+/**
+ * Represents a range of tagging indexes for a given extended directional app tagging secret. Used to track the lowest
+ * and highest indexes used in a transaction for a given (sender, recipient, app/contract) tuple.
+ */
+export type TaggingIndexRange = {
+  extendedSecret: ExtendedDirectionalAppTaggingSecret;
+  lowestIndex: number;
+  highestIndex: number;
+};
+
+export const TaggingIndexRangeSchema = z.object({
+  extendedSecret: ExtendedDirectionalAppTaggingSecretSchema,
+  lowestIndex: schemas.Integer,
+  highestIndex: schemas.Integer,
+});

package/src/logs/tx_scoped_l2_log.ts

@@ -1,4 +1,5 @@
 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 {
@@ -83,6 +84,21 @@ export class TxScopedL2Log {
     return new TxScopedL2Log(txHash, blockNumber, blockTimestamp, logData, noteHashes, firstNullifier);
   }
 
+  static getBlockNumberFromBuffer(buffer: Buffer) {
+    return BlockNumber(buffer.readUint32BE(Fr.SIZE_IN_BYTES));
+  }
+
+  static random() {
+    return new TxScopedL2Log(
+      TxHash.fromField(Fr.random()),
+      BlockNumber(Math.floor(Math.random() * 100000) + 1),
+      BigInt(Math.floor(Date.now() / 1000)),
+      times(3, Fr.random),
+      times(3, Fr.random),
+      Fr.random(),
+    );
+  }
+
   equals(other: TxScopedL2Log) {
     return (
       this.txHash.equals(other.txHash) &&

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[]>;