@aztec/stdlib 0.0.1-commit.9b94fc1 → 0.0.1-commit.d3ec352c

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/block_parameter.ts

@@ -0,0 +1,8 @@
+import { BlockNumberSchema } from '@aztec/foundation/branded-types';
+
+import { z } from 'zod';
+
+export const BlockParameterSchema = z.union([BlockNumberSchema, z.literal('latest')]);
+
+/** Block parameter - either a specific BlockNumber or 'latest' */
+export type BlockParameter = z.infer<typeof BlockParameterSchema>;

package/src/block/in_block.ts

@@ -1,25 +1,29 @@
+import { BlockNumber, BlockNumberSchema } from '@aztec/foundation/branded-types';
+
 import { type ZodTypeAny, z } from 'zod';
 
-import { schemas } from '../schemas/index.js';
 import { L2BlockHash } from './block_hash.js';
 import type { L2Block } from './l2_block.js';
 
-// Note: If you expand this type with indexInBlock, then delete `IndexedTxEffect` and use this type instead.
-export type InBlock<T> = {
-  l2BlockNumber: number;
+export type InBlock = {
+  l2BlockNumber: BlockNumber;
   l2BlockHash: L2BlockHash;
-  data: T;
 };
 
-export function randomInBlock<T>(data: T): InBlock<T> {
+// Note: If you expand this type with indexInBlock, then delete `IndexedTxEffect` and use this type instead.
+export type DataInBlock<T> = {
+  data: T;
+} & InBlock;
+
+export function randomInBlock<T>(data: T): DataInBlock<T> {
   return {
     data,
-    l2BlockNumber: Math.floor(Math.random() * 1000),
+    l2BlockNumber: BlockNumber(Math.floor(Math.random() * 1000)),
     l2BlockHash: L2BlockHash.random(),
   };
 }
 
-export async function wrapInBlock<T>(data: T, block: L2Block): Promise<InBlock<T>> {
+export async function wrapInBlock<T>(data: T, block: L2Block): Promise<DataInBlock<T>> {
   return {
     data,
     l2BlockNumber: block.number,
@@ -30,7 +34,7 @@ export async function wrapInBlock<T>(data: T, block: L2Block): Promise<InBlock<T
 export function inBlockSchemaFor<T extends ZodTypeAny>(schema: T) {
   return z.object({
     data: schema,
-    l2BlockNumber: schemas.Integer,
+    l2BlockNumber: BlockNumberSchema,
     l2BlockHash: L2BlockHash.schema,
   });
 }

package/src/block/index.ts

@@ -4,7 +4,7 @@ export * from './l2_block_header.js';
 export * from './l2_block_stream/index.js';
 export * from './in_block.js';
 export * from './body.js';
-export * from './l2_block_number.js';
+export * from './block_parameter.js';
 export * from './l2_block_source.js';
 export * from './block_hash.js';
 export * from './published_l2_block.js';

package/src/block/l2_block.ts

@@ -1,5 +1,5 @@
 import { type BlockBlobData, encodeBlockBlobData, encodeCheckpointBlobDataFromBlocks } from '@aztec/blob-lib/encoding';
-import { SlotNumber } from '@aztec/foundation/branded-types';
+import { BlockNumber, CheckpointNumber, SlotNumber } from '@aztec/foundation/branded-types';
 import { Fr } from '@aztec/foundation/fields';
 import { BufferReader, serializeToBuffer } from '@aztec/foundation/serialize';
 import { bufferToHex, hexToBuffer } from '@aztec/foundation/string';
@@ -89,7 +89,7 @@ export class L2Block {
    * @returns The L2 block.
    */
   static async random(
-    l2BlockNum: number,
+    l2BlockNum: BlockNumber,
     txsPerBlock = 4,
     numPublicCallsPerTx = 3,
     numPublicLogsPerCall = 1,
@@ -114,7 +114,7 @@ export class L2Block {
     return new L2Block(AppendOnlyTreeSnapshot.empty(), L2BlockHeader.empty(), Body.empty());
   }
 
-  get number(): number {
+  get number(): BlockNumber {
     return this.header.getBlockNumber();
   }
 
@@ -156,7 +156,12 @@ export class L2Block {
   }
 
   public toCheckpoint() {
-    return new Checkpoint(this.archive, this.getCheckpointHeader(), [this.toL2Block()], this.number);
+    return new Checkpoint(
+      this.archive,
+      this.getCheckpointHeader(),
+      [this.toL2Block()],
+      CheckpointNumber.fromBlockNumber(this.number),
+    );
   }
 
   static fromCheckpoint(checkpoint: Checkpoint) {
@@ -246,7 +251,7 @@ export class L2Block {
       archive: this.archive.root,
       lastArchive: this.header.lastArchive.root,
       blockNumber: this.number,
-      slotNumber: Number(this.header.getSlot()),
+      slotNumber: this.header.getSlot(),
       txCount: this.body.txEffects.length,
       timestamp: this.header.globalVariables.timestamp,
     };

package/src/block/l2_block_code_to_purge.ts

@@ -1,4 +1,4 @@
-import { SlotNumber } from '@aztec/foundation/branded-types';
+import { BlockNumber, SlotNumber } from '@aztec/foundation/branded-types';
 import { compact } from '@aztec/foundation/collection';
 import { EthAddress } from '@aztec/foundation/eth-address';
 import { Fr } from '@aztec/foundation/fields';
@@ -25,7 +25,7 @@ export function makeL2BlockHeader(
     overrides?.contentCommitment ?? makeContentCommitment(seed + 0x200, inHash),
     overrides?.state ?? makeStateReference(seed + 0x600),
     makeGlobalVariables((seed += 0x700), {
-      ...(blockNumber ? { blockNumber } : {}),
+      ...(blockNumber ? { blockNumber: BlockNumber(blockNumber) } : {}),
       ...(slotNumber ? { slotNumber: SlotNumber(slotNumber) } : {}),
     }),
     new Fr(seed + 0x300),
@@ -77,7 +77,7 @@ function makeGlobalVariables(seed = 1, overrides: Partial<FieldsOf<GlobalVariabl
   return GlobalVariables.from({
     chainId: new Fr(seed),
     version: new Fr(seed + 1),
-    blockNumber: seed + 2,
+    blockNumber: BlockNumber(seed + 2),
     slotNumber: SlotNumber(seed + 3),
     timestamp: BigInt(seed + 4),
     coinbase: EthAddress.fromField(new Fr(seed + 5)),

package/src/block/l2_block_info.ts

@@ -1,3 +1,4 @@
+import { BlockNumber, BlockNumberSchema, SlotNumber, SlotNumberSchema } from '@aztec/foundation/branded-types';
 import { Fr } from '@aztec/foundation/fields';
 import { schemas } from '@aztec/foundation/schemas';
 import { BufferReader, serializeToBuffer } from '@aztec/foundation/serialize';
@@ -8,19 +9,19 @@ export type L2BlockInfo = {
   blockHash?: Fr;
   archive: Fr;
   lastArchive: Fr;
-  blockNumber: number;
-  slotNumber: number;
+  blockNumber: BlockNumber;
+  slotNumber: SlotNumber;
   txCount: number;
   timestamp: bigint;
 };
 
-export function randomBlockInfo(blockNumber?: number): L2BlockInfo {
+export function randomBlockInfo(blockNumber?: BlockNumber | number): L2BlockInfo {
   return {
     blockHash: Fr.random(),
     archive: Fr.random(),
     lastArchive: Fr.random(),
-    blockNumber: blockNumber ?? Math.floor(Math.random() * 100000) + 1,
-    slotNumber: Math.floor(Math.random() * 100000) + 1,
+    blockNumber: BlockNumber(blockNumber ?? Math.floor(Math.random() * 100000) + 1),
+    slotNumber: SlotNumber(Math.floor(Math.random() * 100000) + 1),
     txCount: Math.floor(Math.random() * 100),
     timestamp: BigInt(Math.floor(Date.now() / 1000)),
   };
@@ -30,8 +31,8 @@ export const BlockInfoSchema = z.object({
   blockHash: schemas.Fr.optional(),
   archive: schemas.Fr,
   lastArchive: schemas.Fr,
-  blockNumber: z.number(),
-  slotNumber: z.number(),
+  blockNumber: BlockNumberSchema,
+  slotNumber: SlotNumberSchema,
   txCount: z.number(),
   timestamp: schemas.BigInt,
 });
@@ -55,8 +56,8 @@ export function deserializeBlockInfo(buffer: Buffer | BufferReader): L2BlockInfo
     blockHash: blockHash.equals(Fr.ZERO) ? undefined : blockHash,
     archive: reader.readObject(Fr),
     lastArchive: reader.readObject(Fr),
-    blockNumber: reader.readNumber(),
-    slotNumber: reader.readNumber(),
+    blockNumber: BlockNumber(reader.readNumber()),
+    slotNumber: SlotNumber(reader.readNumber()),
     txCount: reader.readNumber(),
     timestamp: reader.readBigInt(),
   };

package/src/block/l2_block_new.ts

@@ -1,4 +1,5 @@
 import { type BlockBlobData, encodeBlockBlobData } from '@aztec/blob-lib/encoding';
+import { BlockNumber } from '@aztec/foundation/branded-types';
 import { Fr } from '@aztec/foundation/fields';
 import { BufferReader, serializeToBuffer } from '@aztec/foundation/serialize';
 
@@ -24,7 +25,7 @@ export class L2BlockNew {
     private blockHash: Fr | undefined = undefined,
   ) {}
 
-  get number(): number {
+  get number(): BlockNumber {
     return this.header.globalVariables.blockNumber;
   }
 
@@ -102,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.
@@ -112,7 +117,7 @@ export class L2BlockNew {
    * @returns The L2 block.
    */
   static async random(
-    blockNumber: number,
+    blockNumber: BlockNumber,
     {
       txsPerBlock = 1,
       txOptions = {},
@@ -163,7 +168,7 @@ export class L2BlockNew {
       archive: this.archive.root,
       lastArchive: this.header.lastArchive.root,
       blockNumber: this.number,
-      slotNumber: Number(this.header.getSlot()),
+      slotNumber: this.header.getSlot(),
       txCount: this.body.txEffects.length,
       timestamp: this.header.globalVariables.timestamp,
     };