@aztec/stdlib 3.0.0-nightly.20251205 → 3.0.0-nightly.20251207

package/dest/tx/processed_tx.js

@@ -1,4 +1,5 @@
 import { RevertCode } from '../avm/revert_code.js';
+import { SimulationError } from '../errors/simulation_error.js';
 import { Gas } from '../gas/gas.js';
 import { computeL2ToL1MessageHash } from '../hash/hash.js';
 import { TxEffect } from './tx_effect.js';
@@ -54,6 +55,8 @@ export function makeProcessedTxFromTxWithPublicCalls(tx, avmProvingRequest, gasU
             rollupVersion: globalVariables.version,
             chainId: globalVariables.chainId
         })), publicDataWrites, privateLogs, avmPublicInputs.accumulatedData.publicLogs.toLogs(), contractClassLogs);
+    // Some callers expect a revert reason if the tx reverted.
+    const finalRevertReason = revertReason === undefined && !revertCode.isOK() ? new SimulationError('TX reverted', /*functionErrorStack=*/ [], /*revertData=*/ []) : revertReason;
     return {
         hash: txEffect.txHash,
         data: tx.data,
@@ -63,6 +66,6 @@ export function makeProcessedTxFromTxWithPublicCalls(tx, avmProvingRequest, gasU
         txEffect,
         gasUsed,
         revertCode,
-        revertReason
+        revertReason: finalRevertReason
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aztec/stdlib",
-  "version": "3.0.0-nightly.20251205",
+  "version": "3.0.0-nightly.20251207",
   "type": "module",
   "inherits": [
     "../package.common.json",
@@ -72,13 +72,13 @@
   },
   "dependencies": {
     "@aws-sdk/client-s3": "^3.892.0",
-    "@aztec/bb.js": "3.0.0-nightly.20251205",
-    "@aztec/blob-lib": "3.0.0-nightly.20251205",
-    "@aztec/constants": "3.0.0-nightly.20251205",
-    "@aztec/ethereum": "3.0.0-nightly.20251205",
-    "@aztec/foundation": "3.0.0-nightly.20251205",
-    "@aztec/l1-artifacts": "3.0.0-nightly.20251205",
-    "@aztec/noir-noirc_abi": "3.0.0-nightly.20251205",
+    "@aztec/bb.js": "3.0.0-nightly.20251207",
+    "@aztec/blob-lib": "3.0.0-nightly.20251207",
+    "@aztec/constants": "3.0.0-nightly.20251207",
+    "@aztec/ethereum": "3.0.0-nightly.20251207",
+    "@aztec/foundation": "3.0.0-nightly.20251207",
+    "@aztec/l1-artifacts": "3.0.0-nightly.20251207",
+    "@aztec/noir-noirc_abi": "3.0.0-nightly.20251207",
     "@google-cloud/storage": "^7.15.0",
     "axios": "^1.12.0",
     "json-stringify-deterministic": "1.0.12",

package/src/avm/avm.ts

@@ -4,6 +4,7 @@ import { jsonParseWithSchema, jsonStringify } from '@aztec/foundation/json-rpc';
 
 import { z } from 'zod';
 
+import { FunctionSelector } from '../abi/index.js';
 import { AztecAddress } from '../aztec-address/index.js';
 import { AllContractDeploymentData, ContractDeploymentData } from '../contract/index.js';
 import { SimulationError } from '../errors/simulation_error.js';
@@ -28,6 +29,7 @@ import {
   TreeSnapshots,
   type Tx,
 } from '../tx/index.js';
+import { TxExecutionPhase } from '../tx/processed_tx.js';
 import { WorldStateRevision } from '../world-state/world_state_revision.js';
 import { AvmCircuitPublicInputs } from './avm_circuit_public_inputs.js';
 import { serializeWithMessagePack } from './message_pack.js';
@@ -1042,17 +1044,146 @@ export class AvmCircuitInputs {
   }
 }
 
+// Metadata about a given (enqueued or external) call.
+export class CallStackMetadata {
+  constructor(
+    public phase: TxExecutionPhase,
+    public contractAddress: Fr,
+    public callerPc: number,
+    public calldata: Fr[],
+    public isStaticCall: boolean,
+    public gasLimit: Gas,
+    public output: Fr[], // returndata or revertdata.
+    public internalCallStackAtExit: number[], // At return/revert time. Last one is exit PC.
+    public haltingMessage: string | undefined,
+    public reverted: boolean,
+    public nested: CallStackMetadata[],
+    public numNestedCalls: number, // This will be different from the size of the nested vector if we went past some limit.
+  ) {}
+
+  static get schema(): ZodFor<CallStackMetadata> {
+    return z
+      .object({
+        phase: z.nativeEnum(TxExecutionPhase),
+        contractAddress: Fr.schema,
+        callerPc: z.number(),
+        calldata: Fr.schema.array(),
+        isStaticCall: z.boolean(),
+        gasLimit: Gas.schema,
+        output: Fr.schema.array(),
+        internalCallStackAtExit: z.number().array(),
+        haltingMessage: NullishToUndefined(z.string()),
+        reverted: z.boolean(),
+        nested: CallStackMetadata.schema.array(),
+        numNestedCalls: z.number(),
+      })
+      .transform(
+        ({
+          phase,
+          contractAddress,
+          callerPc,
+          calldata,
+          isStaticCall,
+          gasLimit,
+          output,
+          internalCallStackAtExit,
+          haltingMessage,
+          reverted,
+          nested,
+          numNestedCalls,
+        }) =>
+          new CallStackMetadata(
+            phase,
+            contractAddress,
+            callerPc,
+            calldata,
+            isStaticCall,
+            gasLimit,
+            output,
+            internalCallStackAtExit,
+            haltingMessage,
+            reverted,
+            nested,
+            numNestedCalls,
+          ),
+      );
+  }
+
+  /**
+   * Creates a CallStackMetadata from a plain object without Zod validation.
+   * This method is optimized for performance and skips validation, making it suitable
+   * for deserializing trusted data (e.g., from C++ via MessagePack).
+   * @param obj - Plain object containing CallStackMetadata fields
+   * @returns A CallStackMetadata instance
+   */
+  static fromPlainObject(obj: any): CallStackMetadata {
+    if (obj instanceof CallStackMetadata) {
+      return obj;
+    }
+    return new CallStackMetadata(
+      obj.phase,
+      Fr.fromPlainObject(obj.contractAddress),
+      obj.callerPc,
+      obj.calldata.map((f: any) => Fr.fromPlainObject(f)),
+      obj.isStaticCall,
+      Gas.fromPlainObject(obj.gasLimit),
+      obj.output.map((f: any) => Fr.fromPlainObject(f)),
+      obj.internalCallStackAtExit.map((p: any) => Number(p)),
+      obj.haltingMessage,
+      obj.reverted,
+      obj.nested.map((n: any) => CallStackMetadata.fromPlainObject(n)),
+      obj.numNestedCalls,
+    );
+  }
+
+  public getRevertReason(): SimulationError | undefined {
+    const failingCall = this.findDeepestRevert([this]);
+
+    if (!failingCall) {
+      return undefined;
+    }
+
+    const { stack, leaf } = failingCall;
+    const aztecCallStack = stack.map(call => ({
+      contractAddress: AztecAddress.fromField(call.contractAddress),
+      functionSelector: call.calldata.length > 0 ? FunctionSelector.fromField(call.calldata[0]) : undefined,
+    }));
+
+    // The Noir call stack is the internal call stack at exit of the failing call
+    const noirCallStack = leaf.internalCallStackAtExit.map(pc => `0.${pc}`);
+
+    return new SimulationError(
+      leaf.haltingMessage ?? 'Transaction reverted',
+      aztecCallStack,
+      leaf.output,
+      noirCallStack,
+    );
+  }
+
+  private findDeepestRevert(
+    calls: CallStackMetadata[],
+    parentStack: CallStackMetadata[] = [],
+  ): { stack: CallStackMetadata[]; leaf: CallStackMetadata } | undefined {
+    for (const call of calls) {
+      if (call.reverted) {
+        const nested = this.findDeepestRevert(call.nested, [...parentStack, call]);
+        return nested || { stack: [...parentStack, call], leaf: call };
+      }
+    }
+    return undefined;
+  }
+}
+
 export class PublicTxResult {
   constructor(
     // Simulation result.
     public gasUsed: GasUsed,
     public revertCode: RevertCode,
-    public revertReason: SimulationError | undefined, // Revert reason, if any
     // These are only guaranteed to be present if the simulator is configured to collect them.
-    // NOTE: This list will be populated with one NestedProcessReturnValues per app logic enqueued call.
-    // IMPORTANT: The nesting will only be 1 level deep! You will get one result per enqueued call
-    // but no information about nested calls. This can be added later.
-    public appLogicReturnValues: NestedProcessReturnValues[], // One per enqueued call.
+    // TODO(fcarreiro): Remove NestedProcessReturnValues[] once we migrate to the C++ simulator.
+    public callStackMetadata:
+      | CallStackMetadata[] // One per enqueued call. All phases.
+      | NestedProcessReturnValues[], // One per enqueued call. App logic only.
     public logs: DebugLog[] | undefined,
     // For the proving request.
     public hints: AvmExecutionHints | undefined,
@@ -1068,8 +1199,7 @@ export class PublicTxResult {
         billedGas: Gas.empty(),
       },
       RevertCode.OK,
-      /*revertReason=*/ undefined,
-      /*appLogicReturnValues=*/ [],
+      /*callStackMetadata=*/ [] as CallStackMetadata[],
       /*logs=*/ [],
       /*hints=*/ AvmExecutionHints.empty(),
       /*publicInputs=*/ AvmCircuitPublicInputs.empty(),
@@ -1082,37 +1212,122 @@ export class PublicTxResult {
         gasUsed: schemas.GasUsed,
         revertCode: RevertCode.schema,
         revertReason: NullishToUndefined(SimulationError.schema),
-        appLogicReturnValues: NestedProcessReturnValues.schema.array(),
+        callStackMetadata: z.union([CallStackMetadata.schema.array(), NestedProcessReturnValues.schema.array()]),
         logs: NullishToUndefined(DebugLog.schema.array()),
         // For the proving request.
         publicInputs: AvmCircuitPublicInputs.schema,
         hints: NullishToUndefined(AvmExecutionHints.schema),
       })
       .transform(
-        ({ gasUsed, revertCode, revertReason, appLogicReturnValues, logs, hints, publicInputs }) =>
-          new PublicTxResult(
-            gasUsed,
-            revertCode as RevertCode,
-            revertReason,
-            appLogicReturnValues,
-            logs,
-            hints,
-            publicInputs,
-          ),
+        ({ gasUsed, revertCode, callStackMetadata, logs, hints, publicInputs }) =>
+          new PublicTxResult(gasUsed, revertCode as RevertCode, callStackMetadata, logs, hints, publicInputs),
       );
   }
 
+  /**
+   * Creates a PublicTxResult from a plain object without Zod validation.
+   * This method is optimized for performance and skips validation, making it suitable
+   * for deserializing trusted data (e.g., from C++ via MessagePack).
+   * @param obj - Plain object containing PublicTxResult fields
+   * @returns A PublicTxResult instance
+   */
   static fromPlainObject(obj: any): PublicTxResult {
     return new PublicTxResult(
       GasUsed.fromPlainObject(obj.gasUsed),
       RevertCode.fromPlainObject(obj.revertCode),
-      /*revertReason=*/ undefined, // TODO(fcarreiro/mwood): add.
-      /*appLogicReturnValues=*/ obj.appLogicReturnValues.map(NestedProcessReturnValues.fromPlainObject),
+      obj.callStackMetadata.map(CallStackMetadata.fromPlainObject), // Always CallStackMetadata[] from MessagePack.
       obj.logs?.map(DebugLog.fromPlainObject),
       obj.hints ? AvmExecutionHints.fromPlainObject(obj.hints) : undefined,
       AvmCircuitPublicInputs.fromPlainObject(obj.publicInputs),
     );
   }
+
+  /** Returns one level of return values for the app logic phase, one per enqueued call. */
+  public getAppLogicReturnValues(): NestedProcessReturnValues[] {
+    if (this.callStackMetadata.every(metadata => metadata instanceof CallStackMetadata)) {
+      return this.callStackMetadata
+        .filter(metadata => metadata.phase === TxExecutionPhase.APP_LOGIC)
+        .map(metadata => new NestedProcessReturnValues(metadata.output));
+    } else {
+      return (this.callStackMetadata as NestedProcessReturnValues[]).map(
+        metadata => new NestedProcessReturnValues(metadata.values, metadata.nested),
+      );
+    }
+  }
+
+  public findRevertReason(): SimulationError | undefined {
+    if (this.revertCode.isOK()) {
+      return undefined;
+    }
+
+    const callStackMetadata = this.callStackMetadata;
+    // TODO(fcarreiro): Remove this after migration to the C++ simulator.
+    // If the "stack" comes from TS, it will have this field.
+    if ((callStackMetadata as any).revertReason !== undefined) {
+      return (callStackMetadata as any).revertReason;
+    }
+
+    // Handle CallStackMetadata[].
+    let revertReason: SimulationError | undefined = undefined;
+    for (const call of callStackMetadata) {
+      revertReason = (call as CallStackMetadata).getRevertReason();
+      if (revertReason) {
+        break;
+      }
+    }
+    return revertReason;
+  }
+}
+
+export class CollectionLimitsConfig {
+  constructor(
+    public readonly maxDebugLogMemoryReads: number,
+    public readonly maxCalldataSizeInFields: number,
+    public readonly maxReturndataSizeInFields: number,
+    public readonly maxCallStackDepth: number,
+    public readonly maxCallStackItems: number,
+  ) {}
+
+  static from(obj: Partial<CollectionLimitsConfig>): CollectionLimitsConfig {
+    return new CollectionLimitsConfig(
+      obj.maxDebugLogMemoryReads ?? DEFAULT_MAX_DEBUG_LOG_MEMORY_READS,
+      obj.maxCalldataSizeInFields ?? 300,
+      obj.maxReturndataSizeInFields ?? 300,
+      obj.maxCallStackDepth ?? 5,
+      obj.maxCallStackItems ?? 100,
+    );
+  }
+
+  static empty() {
+    return CollectionLimitsConfig.from({});
+  }
+
+  static get schema() {
+    return z
+      .object({
+        maxDebugLogMemoryReads: z.number(),
+        maxCalldataSizeInFields: z.number(),
+        maxReturndataSizeInFields: z.number(),
+        maxCallStackDepth: z.number(),
+        maxCallStackItems: z.number(),
+      })
+      .transform(
+        ({
+          maxDebugLogMemoryReads,
+          maxCalldataSizeInFields,
+          maxReturndataSizeInFields,
+          maxCallStackDepth,
+          maxCallStackItems,
+        }) =>
+          new CollectionLimitsConfig(
+            maxDebugLogMemoryReads,
+            maxCalldataSizeInFields,
+            maxReturndataSizeInFields,
+            maxCallStackDepth,
+            maxCallStackItems,
+          ),
+      );
+  }
 }
 
 export class PublicSimulatorConfig {
@@ -1122,8 +1337,8 @@ export class PublicSimulatorConfig {
     public readonly collectCallMetadata: boolean, // appLogicReturnValues.
     public readonly collectHints: boolean, // hints.
     public readonly collectDebugLogs: boolean, // logs.
-    public readonly maxDebugLogMemoryReads: number,
     public readonly collectStatistics: boolean, // timings etc.
+    public readonly collectionLimits: CollectionLimitsConfig,
   ) {}
 
   static from(obj: Partial<PublicSimulatorConfig>): PublicSimulatorConfig {
@@ -1133,8 +1348,8 @@ export class PublicSimulatorConfig {
       obj.collectCallMetadata ?? false,
       obj.collectHints ?? false,
       obj.collectDebugLogs ?? false,
-      obj.maxDebugLogMemoryReads ?? DEFAULT_MAX_DEBUG_LOG_MEMORY_READS,
       obj.collectStatistics ?? false,
+      obj.collectionLimits ?? CollectionLimitsConfig.empty(),
     );
   }
 
@@ -1150,8 +1365,8 @@ export class PublicSimulatorConfig {
         collectCallMetadata: z.boolean(),
         collectHints: z.boolean(),
         collectDebugLogs: z.boolean(),
-        maxDebugLogMemoryReads: z.number(),
         collectStatistics: z.boolean(),
+        collectionLimits: CollectionLimitsConfig.schema,
       })
       .transform(PublicSimulatorConfig.from);
   }

package/src/block/l2_block_new.ts

@@ -103,6 +103,10 @@ export class L2BlockNew {
     };
   }
 
+  static empty() {
+    return new L2BlockNew(AppendOnlyTreeSnapshot.empty(), BlockHeader.empty(), Body.empty());
+  }
+
   /**
    * Creates an L2 block containing random data.
    * @param l2BlockNum - The number of the L2 block.

package/src/block/l2_block_source.ts

@@ -1,4 +1,10 @@
-import { BlockNumber, BlockNumberSchema, type EpochNumber, type SlotNumber } from '@aztec/foundation/branded-types';
+import {
+  BlockNumber,
+  BlockNumberSchema,
+  type CheckpointNumber,
+  type EpochNumber,
+  type SlotNumber,
+} from '@aztec/foundation/branded-types';
 import type { EthAddress } from '@aztec/foundation/eth-address';
 import type { Fr } from '@aztec/foundation/fields';
 import type { TypedEventEmitter } from '@aztec/foundation/types';
@@ -67,7 +73,15 @@ export interface L2BlockSource {
    */
   getBlocks(from: BlockNumber, limit: number, proven?: boolean): Promise<L2Block[]>;
 
-  getPublishedCheckpoints(from: number, limit: number): Promise<PublishedCheckpoint[]>;
+  getPublishedCheckpoints(from: CheckpointNumber, limit: number): Promise<PublishedCheckpoint[]>;
+
+  /**
+   * Gets a checkpoint by the archive root, which should be the root of the archive tree after the requested checkpoint
+   * is applied.
+   * @param archive - The new archive root of the checkpoint.
+   * @returns The requested checkpoint (or undefined if not found).
+   */
+  getCheckpointByArchive(archive: Fr): Promise<Checkpoint | undefined>;
 
   /** Equivalent to getBlocks but includes publish data. */
   getPublishedBlocks(from: BlockNumber, limit: number, proven?: boolean): Promise<PublishedL2Block[]>;

package/src/checkpoint/checkpoint.ts

@@ -74,7 +74,7 @@ export class Checkpoint {
       numBlocks = 1,
       startBlockNumber = 1,
       ...options
-    }: { numBlocks?: number; startBlockNumber?: number } & Partial<FieldsOf<CheckpointHeader>> &
+    }: { numBlocks?: number; startBlockNumber?: number } & Partial<Parameters<typeof CheckpointHeader.random>[0]> &
       Partial<Parameters<typeof L2BlockNew.random>[1]> = {},
   ) {
     const header = CheckpointHeader.random(options);

package/src/interfaces/archiver.ts

@@ -88,8 +88,9 @@ export const ArchiverApiSchema: ApiSchemaFor<ArchiverApi> = {
     .returns(z.array(L2Block.schema)),
   getPublishedCheckpoints: z
     .function()
-    .args(schemas.Integer, schemas.Integer)
+    .args(CheckpointNumberSchema, schemas.Integer)
     .returns(z.array(PublishedCheckpoint.schema)),
+  getCheckpointByArchive: z.function().args(schemas.Fr).returns(Checkpoint.schema.optional()),
   getPublishedBlocks: z
     .function()
     .args(BlockNumberSchema, schemas.Integer, optional(z.boolean()))

package/src/rollup/checkpoint_header.ts

@@ -137,11 +137,13 @@ export class CheckpointHeader {
     });
   }
 
-  static random(overrides: Partial<FieldsOf<CheckpointHeader>> = {}): CheckpointHeader {
+  static random(
+    overrides: Partial<FieldsOf<CheckpointHeader>> & Partial<FieldsOf<ContentCommitment>> = {},
+  ): CheckpointHeader {
     return CheckpointHeader.from({
       lastArchiveRoot: Fr.random(),
       blockHeadersHash: Fr.random(),
-      contentCommitment: ContentCommitment.random(),
+      contentCommitment: ContentCommitment.random(overrides),
       slotNumber: SlotNumber(Math.floor(Math.random() * 1000) + 1),
       timestamp: BigInt(Math.floor(Date.now() / 1000)),
       coinbase: EthAddress.random(),

package/src/tx/content_commitment.ts

@@ -28,6 +28,10 @@ export class ContentCommitment {
     return [fields.blobsHash, fields.inHash, fields.outHash] as const;
   }
 
+  static from(fields: FieldsOf<ContentCommitment>) {
+    return new ContentCommitment(...ContentCommitment.getFields(fields));
+  }
+
   getSize() {
     return this.toBuffer().length;
   }
@@ -75,8 +79,13 @@ export class ContentCommitment {
     return new ContentCommitment(reader.readField(), reader.readField(), reader.readField());
   }
 
-  static random(): ContentCommitment {
-    return new ContentCommitment(Fr.random(), Fr.random(), Fr.random());
+  static random(overrides: Partial<FieldsOf<ContentCommitment>> = {}): ContentCommitment {
+    return ContentCommitment.from({
+      blobsHash: Fr.random(),
+      inHash: Fr.random(),
+      outHash: Fr.random(),
+      ...overrides,
+    });
   }
 
   static empty(): ContentCommitment {

package/src/tx/processed_tx.ts

@@ -3,7 +3,7 @@ import { Fr } from '@aztec/foundation/fields';
 import type { AvmProvingRequest } from '../avm/avm_proving_request.js';
 import type { PublicDataWrite } from '../avm/public_data_write.js';
 import { RevertCode } from '../avm/revert_code.js';
-import type { SimulationError } from '../errors/simulation_error.js';
+import { SimulationError } from '../errors/simulation_error.js';
 import { Gas } from '../gas/gas.js';
 import type { GasUsed } from '../gas/gas_used.js';
 import { computeL2ToL1MessageHash } from '../hash/hash.js';
@@ -173,6 +173,12 @@ export function makeProcessedTxFromTxWithPublicCalls(
     contractClassLogs,
   );
 
+  // Some callers expect a revert reason if the tx reverted.
+  const finalRevertReason =
+    revertReason === undefined && !revertCode.isOK()
+      ? new SimulationError('TX reverted', /*functionErrorStack=*/ [], /*revertData=*/ [])
+      : revertReason;
+
   return {
     hash: txEffect.txHash,
     data: tx.data,
@@ -182,6 +188,6 @@ export function makeProcessedTxFromTxWithPublicCalls(
     txEffect,
     gasUsed,
     revertCode,
-    revertReason,
+    revertReason: finalRevertReason,
   };
 }