@aztec/stdlib 0.82.2 → 0.82.3-nightly.20250403

package/src/logs/pending_tagged_log.ts

@@ -0,0 +1,43 @@
+import { MAX_NOTE_HASHES_PER_TX, PRIVATE_LOG_SIZE_IN_FIELDS } from '@aztec/constants';
+import { Fr } from '@aztec/foundation/fields';
+
+import type { AztecAddress } from '../aztec-address/index.js';
+
+/**
+ * Represents a pending tagged log as it is stored in the pending tagged log array to which the syncNotes oracle
+ * inserts found private logs. A TS version of `pending_tagged_log.nr`.
+ */
+export class PendingTaggedLog {
+  constructor(
+    public log: Fr[],
+    public txHash: Fr,
+    public uniqueNoteHashesInTx: Fr[],
+    public firstNullifierInTx: Fr,
+    public recipient: AztecAddress,
+    public logIndexInTx: number,
+  ) {}
+
+  toFields(): Fr[] {
+    return [
+      ...serializeBoundedVec(this.log, PRIVATE_LOG_SIZE_IN_FIELDS),
+      this.txHash,
+      ...serializeBoundedVec(this.uniqueNoteHashesInTx, MAX_NOTE_HASHES_PER_TX),
+      this.firstNullifierInTx,
+      this.recipient.toField(),
+      new Fr(this.logIndexInTx),
+    ];
+  }
+}
+
+/**
+ * Helper function to serialize a bounded vector according to Noir's BoundedVec format
+ * @param values - The values to serialize
+ * @param maxLength - The maximum length of the bounded vector
+ * @returns The serialized bounded vector as Fr[]
+ */
+function serializeBoundedVec(values: Fr[], maxLength: number): Fr[] {
+  const lengthDiff = maxLength - values.length;
+  const zeroPaddingArray = Array(lengthDiff).fill(Fr.ZERO);
+  const storage = values.concat(zeroPaddingArray);
+  return [...storage, new Fr(values.length)];
+}

package/src/logs/{l1_payload/shared_secret_derivation.ts → shared_secret_derivation.ts}

@@ -1,8 +1,7 @@
 import { Grumpkin } from '@aztec/foundation/crypto';
 import type { GrumpkinScalar, Point } from '@aztec/foundation/fields';
 
-import type { AztecAddress } from '../../aztec-address/index.js';
-import type { PublicKey } from '../../keys/public_key.js';
+import type { PublicKey } from '../keys/public_key.js';
 
 /**
  * Derive an Elliptic Curve Diffie-Hellman (ECDH) Shared Secret.
@@ -13,6 +12,9 @@ import type { PublicKey } from '../../keys/public_key.js';
  * @param publicKey - The public key used to derive shared secret.
  * @returns A derived shared secret.
  * @throws If the publicKey is zero.
+ *
+ * TODO(#12656): This function is kept around because of the getSharedSecret oracle. Nuke this once returning
+ * the app-siloed secret.
  */
 export async function deriveEcdhSharedSecret(secretKey: GrumpkinScalar, publicKey: PublicKey): Promise<Point> {
   if (publicKey.isZero()) {
@@ -24,12 +26,3 @@ export async function deriveEcdhSharedSecret(secretKey: GrumpkinScalar, publicKe
   const sharedSecret = await curve.mul(publicKey, secretKey);
   return sharedSecret;
 }
-
-export async function deriveEcdhSharedSecretUsingAztecAddress(
-  secretKey: GrumpkinScalar,
-  address: AztecAddress,
-): Promise<Point> {
-  const addressPoint = await address.toAddressPoint();
-  const sharedSecret = await deriveEcdhSharedSecret(secretKey, addressPoint);
-  return sharedSecret;
-}

package/src/logs/tx_scoped_l2_log.ts

@@ -17,6 +17,11 @@ export class TxScopedL2Log {
      * with the log so the noteHashIndex can be reconstructed after decryption.
      */
     public dataStartIndexForTx: number,
+    /*
+     * The index of the log in the transaction. Note that public and private logs are in separate arrays in the tx
+     * effect and for this reason these indices are independent (a private and public log can have the same index).
+     */
+    public logIndexInTx: number,
     /*
      * The block this log is included in
      */
@@ -36,12 +41,13 @@ export class TxScopedL2Log {
       .object({
         txHash: TxHash.schema,
         dataStartIndexForTx: z.number(),
+        logIndexInTx: z.number(),
         blockNumber: z.number(),
         log: z.union([PrivateLog.schema, PublicLog.schema]),
       })
       .transform(
-        ({ txHash, dataStartIndexForTx, blockNumber, log }) =>
-          new TxScopedL2Log(txHash, dataStartIndexForTx, blockNumber, log),
+        ({ txHash, dataStartIndexForTx, logIndexInTx, blockNumber, log }) =>
+          new TxScopedL2Log(txHash, dataStartIndexForTx, logIndexInTx, blockNumber, log),
       );
   }
 
@@ -50,6 +56,7 @@ export class TxScopedL2Log {
     return Buffer.concat([
       this.txHash.toBuffer(),
       numToUInt32BE(this.dataStartIndexForTx),
+      numToUInt32BE(this.logIndexInTx),
       numToUInt32BE(this.blockNumber),
       boolToBuffer(isFromPublic),
       this.log.toBuffer(),
@@ -60,23 +67,25 @@ export class TxScopedL2Log {
     const reader = BufferReader.asReader(buffer);
     const txHash = reader.readObject(TxHash);
     const dataStartIndexForTx = reader.readNumber();
+    const logIndexInTx = reader.readNumber();
     const blockNumber = reader.readNumber();
     const isFromPublic = reader.readBoolean();
     const log = isFromPublic ? PublicLog.fromBuffer(reader) : PrivateLog.fromBuffer(reader);
 
-    return new TxScopedL2Log(txHash, dataStartIndexForTx, blockNumber, log);
+    return new TxScopedL2Log(txHash, dataStartIndexForTx, logIndexInTx, blockNumber, log);
   }
 
   static async random() {
     const isFromPublic = Math.random() < 0.5;
     const log = isFromPublic ? await PublicLog.random() : PrivateLog.random();
-    return new TxScopedL2Log(TxHash.random(), 1, 1, log);
+    return new TxScopedL2Log(TxHash.random(), 1, 1, 1, log);
   }
 
   equals(other: TxScopedL2Log) {
     return (
       this.txHash.equals(other.txHash) &&
       this.dataStartIndexForTx === other.dataStartIndexForTx &&
+      this.logIndexInTx === other.logIndexInTx &&
       this.blockNumber === other.blockNumber &&
       ((this.log instanceof PublicLog && other.log instanceof PublicLog) ||
         (this.log instanceof PrivateLog && other.log instanceof PrivateLog)) &&

package/src/note/note.ts

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

package/src/proofs/proof.ts

@@ -3,6 +3,8 @@ import { Fr } from '@aztec/foundation/fields';
 import { BufferReader, serializeToBuffer } from '@aztec/foundation/serialize';
 import { bufferToHex, hexToBuffer } from '@aztec/foundation/string';
 
+import { strict as assert } from 'assert';
+
 const EMPTY_PROOF_SIZE = 42;
 
 /**
@@ -17,6 +19,7 @@ export class Proof {
 
   // Honk proofs start with a 4 byte length prefix
   // the proof metadata starts immediately after
+  // TODO(https://github.com/AztecProtocol/barretenberg/issues/1312): Get rid of if possible.
   private readonly metadataOffset = 4;
 
   constructor(
@@ -62,19 +65,50 @@ export class Proof {
   }
 
   public withoutPublicInputs(): Buffer {
-    return Buffer.concat([this.buffer.subarray(this.metadataOffset + Fr.SIZE_IN_BYTES * this.numPublicInputs)]);
+    if (this.isEmpty()) {
+      return this.buffer;
+    }
+    // We are indexing to this particular size because we are assuming the proof buffer looks like:
+    // [4 bytes of metadata for public inputs, binary public inputs, 4 bytes of metadata for proof, binary proof]
+    const proofStart = this.metadataOffset + Fr.SIZE_IN_BYTES * this.numPublicInputs + this.metadataOffset;
+    assert(this.buffer.length >= proofStart, 'Proof buffer is not appropriately sized to call withoutPublicInputs()');
+    return this.buffer.subarray(proofStart);
   }
 
+  // This function assumes that the proof will contain an aggregation object and look something like:
+  // [4 bytes of metadata for public inputs, binary public inputs, 4 bytes of metadata for proof, aggregation object, rest of proof]
+  // We are extracting the binary public inputs and reading them as Frs, and also extracting the aggregation object.
   public extractPublicInputs(): Fr[] {
+    if (this.isEmpty()) {
+      // return array of this.numPublicInputs 0s
+      return new Array(this.numPublicInputs).fill(Fr.zero());
+    }
+    assert(this.numPublicInputs >= AGGREGATION_OBJECT_LENGTH, 'Proof does not contain an aggregation object');
+    const numInnerPublicInputs = this.numPublicInputs - AGGREGATION_OBJECT_LENGTH;
     const reader = BufferReader.asReader(
-      this.buffer.subarray(this.metadataOffset, this.metadataOffset + Fr.SIZE_IN_BYTES * this.numPublicInputs),
+      this.buffer.subarray(this.metadataOffset, this.metadataOffset + Fr.SIZE_IN_BYTES * numInnerPublicInputs),
     );
-    return reader.readArray(this.numPublicInputs, Fr);
+    let publicInputs = reader.readArray(numInnerPublicInputs, Fr);
+    // concatenate Fr[] with aggregation object
+    publicInputs = publicInputs.concat(this.extractAggregationObject());
+    return publicInputs;
   }
 
   public extractAggregationObject(): Fr[] {
-    const publicInputs = this.extractPublicInputs();
-    return publicInputs.slice(-1 * AGGREGATION_OBJECT_LENGTH);
+    if (this.isEmpty()) {
+      // return array of 16 0s
+      return new Array(16).fill(Fr.zero());
+    }
+    assert(this.numPublicInputs >= AGGREGATION_OBJECT_LENGTH, 'Proof does not contain an aggregation object');
+    const numInnerPublicInputs = this.numPublicInputs - AGGREGATION_OBJECT_LENGTH;
+    // The aggregation object is currently stored after the initial inner public inputs and after the 4 byte proof metadata.
+    const reader = BufferReader.asReader(
+      this.buffer.subarray(
+        this.metadataOffset + Fr.SIZE_IN_BYTES * numInnerPublicInputs + this.metadataOffset,
+        this.metadataOffset + Fr.SIZE_IN_BYTES * this.numPublicInputs + this.metadataOffset,
+      ),
+    );
+    return reader.readArray(AGGREGATION_OBJECT_LENGTH, Fr);
   }
 
   /**

package/src/snapshots/download.ts

@@ -0,0 +1,60 @@
+import { fromEntries, getEntries, maxBy } from '@aztec/foundation/collection';
+import { jsonParseWithSchemaSync } from '@aztec/foundation/json-rpc';
+import type { ReadOnlyFileStore } from '@aztec/stdlib/file-store';
+
+import { join } from 'path';
+
+import {
+  SnapshotDataKeys,
+  type SnapshotDataUrls,
+  type SnapshotMetadata,
+  type SnapshotsIndex,
+  type SnapshotsIndexMetadata,
+  SnapshotsIndexSchema,
+} from './types.js';
+
+export async function getSnapshotIndex(
+  metadata: SnapshotsIndexMetadata,
+  store: ReadOnlyFileStore,
+): Promise<SnapshotsIndex | undefined> {
+  const basePath = getBasePath(metadata);
+  const snapshotIndexPath = `${basePath}/index.json`;
+  try {
+    if (await store.exists(snapshotIndexPath)) {
+      const snapshotIndexData = await store.read(snapshotIndexPath);
+      return jsonParseWithSchemaSync(snapshotIndexData.toString(), SnapshotsIndexSchema);
+    } else {
+      return undefined;
+    }
+  } catch (err) {
+    throw new Error(`Error reading snapshot index from ${snapshotIndexPath}: ${err}`);
+  }
+}
+
+export async function getLatestSnapshotMetadata(
+  metadata: SnapshotsIndexMetadata,
+  store: ReadOnlyFileStore,
+): Promise<SnapshotMetadata | undefined> {
+  const snapshotsIndex = await getSnapshotIndex(metadata, store);
+  return snapshotsIndex?.snapshots && maxBy(snapshotsIndex?.snapshots, s => s.l1BlockNumber);
+}
+
+export function getBasePath(metadata: SnapshotsIndexMetadata): string {
+  return `aztec-${metadata.l1ChainId}-${metadata.rollupVersion}-${metadata.rollupAddress}`;
+}
+
+export function getSnapshotIndexPath(metadata: SnapshotsIndexMetadata): string {
+  return `${getBasePath(metadata)}/index.json`;
+}
+
+export function makeSnapshotLocalPaths(baseDir: string): SnapshotDataUrls {
+  return fromEntries(SnapshotDataKeys.map(key => [key, join(baseDir, `${key}.db`)]));
+}
+
+export async function downloadSnapshot(
+  snapshot: Pick<SnapshotMetadata, 'dataUrls'>,
+  localPaths: Record<SnapshotDataKeys, string>,
+  store: ReadOnlyFileStore,
+): Promise<void> {
+  await Promise.all(getEntries(localPaths).map(([key, path]) => store.download(snapshot.dataUrls[key], path)));
+}

package/src/snapshots/index.ts

@@ -0,0 +1,3 @@
+export * from './types.js';
+export * from './upload.js';
+export { downloadSnapshot, getLatestSnapshotMetadata, makeSnapshotLocalPaths } from './download.js';

package/src/snapshots/types.ts

@@ -0,0 +1,58 @@
+import type { EthAddress } from '@aztec/foundation/eth-address';
+import { type ZodFor, schemas } from '@aztec/foundation/schemas';
+
+import { z } from 'zod';
+
+export const SnapshotDataKeys = [
+  'archiver',
+  'nullifier-tree',
+  'public-data-tree',
+  'note-hash-tree',
+  'archive-tree',
+  'l1-to-l2-message-tree',
+] as const;
+
+export type SnapshotDataKeys = (typeof SnapshotDataKeys)[number];
+
+export type SnapshotDataUrls = Record<SnapshotDataKeys, string>;
+
+export type SnapshotMetadata = {
+  l2BlockNumber: number;
+  l2BlockHash: string;
+  l1BlockNumber: number;
+  timestamp: number;
+  dataUrls: SnapshotDataUrls;
+  schemaVersions: { archiver: number; worldState: number };
+};
+
+export type SnapshotsIndexMetadata = {
+  l1ChainId: number;
+  rollupVersion: number;
+  rollupAddress: EthAddress;
+};
+
+export type SnapshotsIndex = SnapshotsIndexMetadata & {
+  snapshots: SnapshotMetadata[];
+};
+
+export const SnapshotsIndexSchema = z.object({
+  l1ChainId: z.number(),
+  rollupVersion: z.number(),
+  rollupAddress: schemas.EthAddress,
+  snapshots: z.array(
+    z.object({
+      l2BlockNumber: z.number(),
+      l2BlockHash: z.string(),
+      l1BlockNumber: z.number(),
+      timestamp: z.number(),
+      schemaVersions: z.object({
+        archiver: z.number(),
+        worldState: z.number(),
+      }),
+      dataUrls: z
+        .record(z.enum(SnapshotDataKeys), z.string())
+        // See https://stackoverflow.com/questions/77958464/zod-record-with-required-keys
+        .refine((obj): obj is Required<typeof obj> => SnapshotDataKeys.every(key => !!obj[key])),
+    }),
+  ),
+}) satisfies ZodFor<SnapshotsIndex>;

package/src/snapshots/upload.ts

@@ -0,0 +1,55 @@
+import { fromEntries, getEntries, pick } from '@aztec/foundation/collection';
+import { jsonStringify } from '@aztec/foundation/json-rpc';
+import type { FileStore } from '@aztec/stdlib/file-store';
+
+import { getBasePath, getSnapshotIndex, getSnapshotIndexPath } from './download.js';
+import type { SnapshotDataKeys, SnapshotMetadata, SnapshotsIndex } from './types.js';
+
+export type UploadSnapshotMetadata = Pick<SnapshotMetadata, 'l2BlockNumber' | 'l2BlockHash' | 'l1BlockNumber'> &
+  Pick<SnapshotsIndex, 'l1ChainId' | 'rollupVersion' | 'rollupAddress'>;
+
+export async function uploadSnapshot(
+  localPaths: Record<SnapshotDataKeys, string>,
+  schemaVersions: SnapshotMetadata['schemaVersions'],
+  metadata: UploadSnapshotMetadata,
+  store: FileStore,
+): Promise<SnapshotMetadata> {
+  const timestamp = Date.now();
+  const date = new Date().toISOString().replace(/[-:T]/g, '').replace(/\..+$/, '');
+  const basePath = getBasePath(metadata);
+  const targetPathFor = (key: SnapshotDataKeys) => `${basePath}/${key}-${date}-${metadata.l2BlockHash}.db`;
+
+  const dataUrls = fromEntries(
+    await Promise.all(
+      getEntries(localPaths).map(
+        async ([key, path]) =>
+          [key, await store.upload(targetPathFor(key), path, { compress: true, public: true })] as const,
+      ),
+    ),
+  );
+
+  const snapshotsIndex = (await getSnapshotIndex(metadata, store)) ?? createEmptyIndex(metadata);
+
+  const newSnapshotMetadata: SnapshotMetadata = {
+    ...pick(metadata, 'l1BlockNumber', 'l2BlockHash', 'l2BlockNumber'),
+    schemaVersions,
+    timestamp,
+    dataUrls,
+  };
+  snapshotsIndex.snapshots.unshift(newSnapshotMetadata);
+
+  await store.save(getSnapshotIndexPath(metadata), Buffer.from(jsonStringify(snapshotsIndex, true)), {
+    public: true, // Make the index publicly accessible
+    metadata: { ['Cache-control']: 'no-store' }, // Do not cache object versions
+  });
+  return newSnapshotMetadata;
+}
+
+function createEmptyIndex(
+  metadata: Pick<SnapshotsIndex, 'l1ChainId' | 'rollupVersion' | 'rollupAddress'>,
+): SnapshotsIndex {
+  return {
+    ...pick(metadata, 'l1ChainId', 'rollupVersion', 'rollupAddress'),
+    snapshots: [],
+  };
+}