@aztec/native 3.0.0-nightly.20251104 → 3.0.0-nightly.20251105

package/dest/native_module.d.ts

@@ -4,6 +4,68 @@ interface NativeClassCtor {
 }
 export declare const NativeWorldState: NativeClassCtor;
 export declare const NativeLMDBStore: NativeClassCtor;
+/**
+ * Contract provider interface for callbacks to fetch contract data.
+ * These callbacks are invoked by C++ during simulation when contract data is needed.
+ */
+export interface ContractProvider {
+    /**
+     * Fetch a contract instance by address.
+     * @param address - The contract address as a string (hex format)
+     * @returns Promise resolving to msgpack-serialized ContractInstanceHint buffer, or undefined if not found
+     */
+    getContractInstance(address: string): Promise<Buffer | undefined>;
+    /**
+     * Fetch a contract class by class ID.
+     * @param classId - The contract class ID as a string (hex format)
+     * @returns Promise resolving to msgpack-serialized ContractClassHint buffer, or undefined if not found
+     */
+    getContractClass(classId: string): Promise<Buffer | undefined>;
+    /**
+     * Add contracts from deployment data.
+     * @param contractDeploymentData - Msgpack-serialized ContractDeploymentData buffer
+     * @returns Promise that resolves when contracts are added
+     */
+    addContracts(contractDeploymentData: Buffer): Promise<void>;
+    /**
+     * Fetch the bytecode commitment for a contract class.
+     * @param classId - The contract class ID as a string (hex format)
+     * @returns Promise resolving to msgpack-serialized Fr buffer, or undefined if not found
+     */
+    getBytecodeCommitment(classId: string): Promise<Buffer | undefined>;
+    /**
+     * Fetch the debug function name for a contract function.
+     * @param address - The contract address as a string (hex format)
+     * @param selector - The function selector as a string (hex format)
+     * @returns Promise resolving to function name string, or undefined if not found
+     */
+    getDebugFunctionName(address: string, selector: string): Promise<string | undefined>;
+    /**
+     * Create a new checkpoint for the contract database state.
+     * Enables rollback to current state in case of a revert.
+     * @returns Promise that resolves when checkpoint is created
+     */
+    createCheckpoint(): Promise<void>;
+    /**
+     * Commit the current checkpoint, accepting its state as latest.
+     * @returns Promise that resolves when checkpoint is committed
+     */
+    commitCheckpoint(): Promise<void>;
+    /**
+     * Revert the current checkpoint, discarding its state and rolling back.
+     * @returns Promise that resolves when checkpoint is reverted
+     */
+    revertCheckpoint(): Promise<void>;
+}
+/**
+ * AVM simulation function that takes serialized inputs and a contract provider.
+ * The contract provider enables C++ to callback to TypeScript for contract data during simulation.
+ * @param inputs - Msgpack-serialized AvmFastSimulationInputs buffer
+ * @param contractProvider - Object with callbacks for fetching contract instances and classes
+ * @param worldStateHandle - Native handle to WorldState instance
+ * @returns Promise resolving to msgpack-serialized AvmCircuitPublicInputs buffer
+ */
+export declare const avmSimulate: (inputs: Buffer, contractProvider: ContractProvider, worldStateHandle: any) => Promise<Buffer>;
 /**
  * AVM simulation function that uses pre-collected hints from TypeScript simulation.
  * All contract data and merkle tree hints are included in the AvmCircuitInputs, so no runtime

package/dest/native_module.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"native_module.d.ts","sourceRoot":"","sources":["../src/native_module.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAE5D,UAAU,eAAe;IACvB,KAAK,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,eAAe,CAAC;CAC3C;AA2BD,eAAO,MAAM,gBAAgB,EAAE,eAA4D,CAAC;AAC5F,eAAO,MAAM,eAAe,EAAE,eAA2D,CAAC;AAE1F;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAErD,CAAC"}
+{"version":3,"file":"native_module.d.ts","sourceRoot":"","sources":["../src/native_module.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAE5D,UAAU,eAAe;IACvB,KAAK,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,eAAe,CAAC;CAC3C;AA2BD,eAAO,MAAM,gBAAgB,EAAE,eAA4D,CAAC;AAC5F,eAAO,MAAM,eAAe,EAAE,eAA2D,CAAC;AAE1F;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IAClE;;;;OAIG;IACH,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IAE/D;;;;OAIG;IACH,YAAY,CAAC,sBAAsB,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE5D;;;;OAIG;IACH,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IAEpE;;;;;OAKG;IACH,oBAAoB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IAErF;;;;OAIG;IACH,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAElC;;;OAGG;IACH,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAElC;;;OAGG;IACH,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACnC;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,WAAW,EAAE,CACxB,MAAM,EAAE,MAAM,EACd,gBAAgB,EAAE,gBAAgB,EAClC,gBAAgB,EAAE,GAAG,KAClB,OAAO,CAAC,MAAM,CAIC,CAAC;AACrB;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAErD,CAAC"}

package/dest/native_module.js

@@ -19,6 +19,14 @@ function loadNativeModule() {
 const nativeModule = loadNativeModule();
 export const NativeWorldState = nativeModule.WorldState;
 export const NativeLMDBStore = nativeModule.LMDBStore;
+/**
+ * AVM simulation function that takes serialized inputs and a contract provider.
+ * The contract provider enables C++ to callback to TypeScript for contract data during simulation.
+ * @param inputs - Msgpack-serialized AvmFastSimulationInputs buffer
+ * @param contractProvider - Object with callbacks for fetching contract instances and classes
+ * @param worldStateHandle - Native handle to WorldState instance
+ * @returns Promise resolving to msgpack-serialized AvmCircuitPublicInputs buffer
+ */ export const avmSimulate = nativeModule.avmSimulate;
 /**
  * AVM simulation function that uses pre-collected hints from TypeScript simulation.
  * All contract data and merkle tree hints are included in the AvmCircuitInputs, so no runtime

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aztec/native",
-  "version": "3.0.0-nightly.20251104",
+  "version": "3.0.0-nightly.20251105",
   "type": "module",
   "exports": {
     ".": "./dest/index.js"
@@ -19,7 +19,7 @@
     "./package.local.json"
   ],
   "dependencies": {
-    "@aztec/foundation": "3.0.0-nightly.20251104",
+    "@aztec/foundation": "3.0.0-nightly.20251105",
     "msgpackr": "^1.11.2"
   },
   "devDependencies": {

package/src/native_module.ts

@@ -36,6 +36,83 @@ const nativeModule: Record<string, NativeClassCtor | Function> = loadNativeModul
 export const NativeWorldState: NativeClassCtor = nativeModule.WorldState as NativeClassCtor;
 export const NativeLMDBStore: NativeClassCtor = nativeModule.LMDBStore as NativeClassCtor;
 
+/**
+ * Contract provider interface for callbacks to fetch contract data.
+ * These callbacks are invoked by C++ during simulation when contract data is needed.
+ */
+export interface ContractProvider {
+  /**
+   * Fetch a contract instance by address.
+   * @param address - The contract address as a string (hex format)
+   * @returns Promise resolving to msgpack-serialized ContractInstanceHint buffer, or undefined if not found
+   */
+  getContractInstance(address: string): Promise<Buffer | undefined>;
+  /**
+   * Fetch a contract class by class ID.
+   * @param classId - The contract class ID as a string (hex format)
+   * @returns Promise resolving to msgpack-serialized ContractClassHint buffer, or undefined if not found
+   */
+  getContractClass(classId: string): Promise<Buffer | undefined>;
+
+  /**
+   * Add contracts from deployment data.
+   * @param contractDeploymentData - Msgpack-serialized ContractDeploymentData buffer
+   * @returns Promise that resolves when contracts are added
+   */
+  addContracts(contractDeploymentData: Buffer): Promise<void>;
+
+  /**
+   * Fetch the bytecode commitment for a contract class.
+   * @param classId - The contract class ID as a string (hex format)
+   * @returns Promise resolving to msgpack-serialized Fr buffer, or undefined if not found
+   */
+  getBytecodeCommitment(classId: string): Promise<Buffer | undefined>;
+
+  /**
+   * Fetch the debug function name for a contract function.
+   * @param address - The contract address as a string (hex format)
+   * @param selector - The function selector as a string (hex format)
+   * @returns Promise resolving to function name string, or undefined if not found
+   */
+  getDebugFunctionName(address: string, selector: string): Promise<string | undefined>;
+
+  /**
+   * Create a new checkpoint for the contract database state.
+   * Enables rollback to current state in case of a revert.
+   * @returns Promise that resolves when checkpoint is created
+   */
+  createCheckpoint(): Promise<void>;
+
+  /**
+   * Commit the current checkpoint, accepting its state as latest.
+   * @returns Promise that resolves when checkpoint is committed
+   */
+  commitCheckpoint(): Promise<void>;
+
+  /**
+   * Revert the current checkpoint, discarding its state and rolling back.
+   * @returns Promise that resolves when checkpoint is reverted
+   */
+  revertCheckpoint(): Promise<void>;
+}
+
+/**
+ * AVM simulation function that takes serialized inputs and a contract provider.
+ * The contract provider enables C++ to callback to TypeScript for contract data during simulation.
+ * @param inputs - Msgpack-serialized AvmFastSimulationInputs buffer
+ * @param contractProvider - Object with callbacks for fetching contract instances and classes
+ * @param worldStateHandle - Native handle to WorldState instance
+ * @returns Promise resolving to msgpack-serialized AvmCircuitPublicInputs buffer
+ */
+export const avmSimulate: (
+  inputs: Buffer,
+  contractProvider: ContractProvider,
+  worldStateHandle: any,
+) => Promise<Buffer> = nativeModule.avmSimulate as (
+  inputs: Buffer,
+  contractProvider: ContractProvider,
+  worldStateHandle: any,
+) => Promise<Buffer>;
 /**
  * AVM simulation function that uses pre-collected hints from TypeScript simulation.
  * All contract data and merkle tree hints are included in the AvmCircuitInputs, so no runtime