@aztec/native 0.0.1-commit.b655e406 → 0.0.1-commit.fce3e4f

package/dest/index.d.ts

@@ -1,3 +1,3 @@
 export * from './native_module.js';
 export { type RoundtripDuration, MsgpackChannel } from './msgpack_channel.js';
-//# sourceMappingURL=index.d.ts.map
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3NyYy9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxjQUFjLG9CQUFvQixDQUFDO0FBQ25DLE9BQU8sRUFBRSxLQUFLLGlCQUFpQixFQUFFLGNBQWMsRUFBRSxNQUFNLHNCQUFzQixDQUFDIn0=

package/dest/msgpack_channel.d.ts

@@ -22,4 +22,4 @@ export declare class MsgpackChannel<M extends number = number, Req extends Messa
     }>;
 }
 export {};
-//# sourceMappingURL=msgpack_channel.d.ts.map
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoibXNncGFja19jaGFubmVsLmQudHMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9zcmMvbXNncGFja19jaGFubmVsLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQU1BLE1BQU0sV0FBVyxlQUFlO0lBQzlCLElBQUksQ0FBQyxHQUFHLEVBQUUsTUFBTSxHQUFHLFVBQVUsR0FBRyxPQUFPLENBQUMsTUFBTSxHQUFHLFVBQVUsQ0FBQyxDQUFDO0NBQzlEO0FBRUQsTUFBTSxNQUFNLGlCQUFpQixHQUFHO0lBQzlCLFVBQVUsRUFBRSxNQUFNLENBQUM7SUFDbkIsTUFBTSxFQUFFLE1BQU0sQ0FBQztJQUNmLFVBQVUsRUFBRSxNQUFNLENBQUM7SUFDbkIsT0FBTyxFQUFFLE1BQU0sQ0FBQztDQUNqQixDQUFDO0FBWUYsS0FBSyxXQUFXLENBQUMsQ0FBQyxTQUFTLE1BQU0sSUFBSTtLQUFHLENBQUMsSUFBSSxDQUFDLEdBQUcsTUFBTSxHQUFHLElBQUk7Q0FBRSxDQUFDO0FBRWpFLHFCQUFhLGNBQWMsQ0FDekIsQ0FBQyxTQUFTLE1BQU0sR0FBRyxNQUFNLEVBQ3pCLEdBQUcsU0FBUyxXQUFXLENBQUMsQ0FBQyxDQUFDLEdBQUcsR0FBRyxFQUNoQyxJQUFJLFNBQVMsV0FBVyxDQUFDLENBQUMsQ0FBQyxHQUFHLEdBQUc7SUFZZCxPQUFPLENBQUMsSUFBSTtJQVYvQixtQ0FBbUM7SUFDbkMsT0FBTyxDQUFDLE9BQU8sQ0FLWjtJQUVILE9BQU8sQ0FBQyxLQUFLLENBQUs7SUFFbEIsWUFBMkIsSUFBSSxFQUFFLGVBQWUsRUFBSTtJQUV2QyxXQUFXLENBQUMsQ0FBQyxTQUFTLENBQUMsRUFDbEMsT0FBTyxFQUFFLENBQUMsRUFDVixJQUFJLEVBQUUsR0FBRyxDQUFDLENBQUMsQ0FBQyxHQUNYLE9BQU8sQ0FBQztRQUFFLFFBQVEsRUFBRSxpQkFBaUIsQ0FBQztRQUFDLFFBQVEsRUFBRSxJQUFJLENBQUMsQ0FBQyxDQUFDLENBQUE7S0FBRSxDQUFDLENBMEQ3RDtDQUNGIn0=

package/dest/msgpack_channel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"msgpack_channel.d.ts","sourceRoot":"","sources":["../src/msgpack_channel.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,GAAG,OAAO,CAAC,MAAM,GAAG,UAAU,CAAC,CAAC;CAC9D;AAED,MAAM,MAAM,iBAAiB,GAAG;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAYF,KAAK,WAAW,CAAC,CAAC,SAAS,MAAM,IAAI;KAAG,CAAC,IAAI,CAAC,GAAG,MAAM,GAAG,IAAI;CAAE,CAAC;AAEjE,qBAAa,cAAc,CACzB,CAAC,SAAS,MAAM,GAAG,MAAM,EACzB,GAAG,SAAS,WAAW,CAAC,CAAC,CAAC,GAAG,GAAG,EAChC,IAAI,SAAS,WAAW,CAAC,CAAC,CAAC,GAAG,GAAG;IAYd,OAAO,CAAC,IAAI;IAV/B,mCAAmC;IACnC,OAAO,CAAC,OAAO,CAKZ;IAEH,OAAO,CAAC,KAAK,CAAK;gBAES,IAAI,EAAE,eAAe;IAEnC,WAAW,CAAC,CAAC,SAAS,CAAC,EAClC,OAAO,EAAE,CAAC,EACV,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC,GACX,OAAO,CAAC;QAAE,QAAQ,EAAE,iBAAiB,CAAC;QAAC,QAAQ,EAAE,IAAI,CAAC,CAAC,CAAC,CAAA;KAAE,CAAC;CA2D/D"}
+{"version":3,"file":"msgpack_channel.d.ts","sourceRoot":"","sources":["../src/msgpack_channel.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,GAAG,OAAO,CAAC,MAAM,GAAG,UAAU,CAAC,CAAC;CAC9D;AAED,MAAM,MAAM,iBAAiB,GAAG;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAYF,KAAK,WAAW,CAAC,CAAC,SAAS,MAAM,IAAI;KAAG,CAAC,IAAI,CAAC,GAAG,MAAM,GAAG,IAAI;CAAE,CAAC;AAEjE,qBAAa,cAAc,CACzB,CAAC,SAAS,MAAM,GAAG,MAAM,EACzB,GAAG,SAAS,WAAW,CAAC,CAAC,CAAC,GAAG,GAAG,EAChC,IAAI,SAAS,WAAW,CAAC,CAAC,CAAC,GAAG,GAAG;IAYd,OAAO,CAAC,IAAI;IAV/B,mCAAmC;IACnC,OAAO,CAAC,OAAO,CAKZ;IAEH,OAAO,CAAC,KAAK,CAAK;IAElB,YAA2B,IAAI,EAAE,eAAe,EAAI;IAEvC,WAAW,CAAC,CAAC,SAAS,CAAC,EAClC,OAAO,EAAE,CAAC,EACV,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC,GACX,OAAO,CAAC;QAAE,QAAQ,EAAE,iBAAiB,CAAC;QAAC,QAAQ,EAAE,IAAI,CAAC,CAAC,CAAC,CAAA;KAAE,CAAC,CA0D7D;CACF"}

package/dest/native_module.d.ts

@@ -4,6 +4,69 @@ 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
+ * TODO(MW): include generate_hints bool
+ * @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
@@ -13,4 +76,4 @@ export declare const NativeLMDBStore: NativeClassCtor;
  */
 export declare const avmSimulateWithHintedDbs: (inputs: Buffer) => Promise<Buffer>;
 export {};
-//# sourceMappingURL=native_module.d.ts.map
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoibmF0aXZlX21vZHVsZS5kLnRzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vc3JjL25hdGl2ZV9tb2R1bGUudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBSUEsT0FBTyxLQUFLLEVBQUUsZUFBZSxFQUFFLE1BQU0sc0JBQXNCLENBQUM7QUFFNUQsVUFBVSxlQUFlO0lBQ3ZCLEtBQUssR0FBRyxJQUFJLEVBQUUsT0FBTyxFQUFFLEdBQUcsZUFBZSxDQUFDO0NBQzNDO0FBYUQsZUFBTyxNQUFNLGdCQUFnQixFQUFFLGVBQTRELENBQUM7QUFDNUYsZUFBTyxNQUFNLGVBQWUsRUFBRSxlQUEyRCxDQUFDO0FBRTFGOzs7R0FHRztBQUNILE1BQU0sV0FBVyxnQkFBZ0I7SUFDL0I7Ozs7T0FJRztJQUNILG1CQUFtQixDQUFDLE9BQU8sRUFBRSxNQUFNLEdBQUcsT0FBTyxDQUFDLE1BQU0sR0FBRyxTQUFTLENBQUMsQ0FBQztJQUNsRTs7OztPQUlHO0lBQ0gsZ0JBQWdCLENBQUMsT0FBTyxFQUFFLE1BQU0sR0FBRyxPQUFPLENBQUMsTUFBTSxHQUFHLFNBQVMsQ0FBQyxDQUFDO0lBRS9EOzs7O09BSUc7SUFDSCxZQUFZLENBQUMsc0JBQXNCLEVBQUUsTUFBTSxHQUFHLE9BQU8sQ0FBQyxJQUFJLENBQUMsQ0FBQztJQUU1RDs7OztPQUlHO0lBQ0gscUJBQXFCLENBQUMsT0FBTyxFQUFFLE1BQU0sR0FBRyxPQUFPLENBQUMsTUFBTSxHQUFHLFNBQVMsQ0FBQyxDQUFDO0lBRXBFOzs7OztPQUtHO0lBQ0gsb0JBQW9CLENBQUMsT0FBTyxFQUFFLE1BQU0sRUFBRSxRQUFRLEVBQUUsTUFBTSxHQUFHLE9BQU8sQ0FBQyxNQUFNLEdBQUcsU0FBUyxDQUFDLENBQUM7SUFFckY7Ozs7T0FJRztJQUNILGdCQUFnQixJQUFJLE9BQU8sQ0FBQyxJQUFJLENBQUMsQ0FBQztJQUVsQzs7O09BR0c7SUFDSCxnQkFBZ0IsSUFBSSxPQUFPLENBQUMsSUFBSSxDQUFDLENBQUM7SUFFbEM7OztPQUdHO0lBQ0gsZ0JBQWdCLElBQUksT0FBTyxDQUFDLElBQUksQ0FBQyxDQUFDO0NBQ25DO0FBRUQ7Ozs7Ozs7O0dBUUc7QUFDSCxlQUFPLE1BQU0sV0FBVyxFQUFFLENBQ3hCLE1BQU0sRUFBRSxNQUFNLEVBQ2QsZ0JBQWdCLEVBQUUsZ0JBQWdCLEVBQ2xDLGdCQUFnQixFQUFFLEdBQUcsS0FDbEIsT0FBTyxDQUFDLE1BQU0sQ0FJQyxDQUFDO0FBQ3JCOzs7Ozs7R0FNRztBQUNILGVBQU8sTUFBTSx3QkFBd0IsRUFBRSxDQUFDLE1BQU0sRUFBRSxNQUFNLEtBQUssT0FBTyxDQUFDLE1BQU0sQ0FFckQsQ0FBQyJ9

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;AAaD,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;;;;;;;;GAQG;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

@@ -1,24 +1,25 @@
+import { findNapiBinary } from '@aztec/bb.js';
 import { createRequire } from 'module';
-import { dirname, join } from 'path';
-import { fileURLToPath } from 'url';
 function loadNativeModule() {
-    const __filename = fileURLToPath(import.meta.url);
-    const __dirname = dirname(__filename);
-    // Map Node.js platform/arch to build directory names
-    const arch = process.arch === 'x64' ? 'amd64' : process.arch;
-    const platform = process.platform === 'darwin' ? 'macos' : process.platform;
-    const variant = `${arch}-${platform}`;
-    const modulePath = join(__dirname, '..', 'build', variant, 'nodejs_module.node');
-    try {
-        const require = createRequire(import.meta.url);
-        return require(modulePath);
-    } catch (error) {
-        throw new Error(`Failed to load native module for ${variant} from ${modulePath}. ` + `Supported: amd64-linux, arm64-linux, amd64-macos, arm64-macos. ` + `Error: ${error}`);
+    const require = createRequire(import.meta.url);
+    const napiPath = findNapiBinary();
+    if (!napiPath) {
+        throw new Error('NAPI binary not found for current platform.');
     }
+    return require(napiPath);
 }
 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
+ * TODO(MW): include generate_hints bool
+ * @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,31 +1,29 @@
 {
   "name": "@aztec/native",
-  "version": "0.0.1-commit.b655e406",
+  "version": "0.0.1-commit.fce3e4f",
   "type": "module",
   "exports": {
     ".": "./dest/index.js"
   },
   "scripts": {
-    "build": "yarn clean && yarn generate && tsc -b",
-    "build:dev": "tsc -b --watch",
-    "build:cpp": "PROJECT=$(pwd); cd $(git rev-parse --show-toplevel)/barretenberg/cpp; cmake --preset ${PRESET:-clang16-pic} && cmake --build --preset ${PRESET:-clang16-pic} --target nodejs_module && cd $PROJECT && yarn generate",
-    "clean:cpp": "rm -rf $(git rev-parse --show-toplevel)/barretenberg/cpp/build-pic",
+    "build": "yarn clean && tsgo -b",
+    "build:dev": "tsgo -b --watch",
     "clean": "rm -rf ./dest .tsbuildinfo",
-    "test": "NODE_NO_WARNINGS=1 node --experimental-vm-modules ../node_modules/.bin/jest --passWithNoTests --maxWorkers=${JEST_MAX_WORKERS:-8}",
-    "generate": "bash scripts/copy_modules.sh"
+    "test": "NODE_NO_WARNINGS=1 node --experimental-vm-modules ../node_modules/.bin/jest --passWithNoTests --maxWorkers=${JEST_MAX_WORKERS:-8}"
   },
   "inherits": [
-    "../package.common.json",
-    "./package.local.json"
+    "../package.common.json"
   ],
   "dependencies": {
-    "@aztec/foundation": "0.0.1-commit.b655e406",
+    "@aztec/bb.js": "0.0.1-commit.fce3e4f",
+    "@aztec/foundation": "0.0.1-commit.fce3e4f",
     "msgpackr": "^1.11.2"
   },
   "devDependencies": {
     "@jest/globals": "^30.0.0",
     "@types/jest": "^30.0.0",
     "@types/node": "^22.15.17",
+    "@typescript/native-preview": "7.0.0-dev.20251126.1",
     "jest": "^30.0.0",
     "ts-node": "^10.9.1",
     "typescript": "^5.3.3"

package/src/native_module.ts

@@ -1,6 +1,6 @@
+import { findNapiBinary } from '@aztec/bb.js';
+
 import { createRequire } from 'module';
-import { dirname, join } from 'path';
-import { fileURLToPath } from 'url';
 
 import type { MessageReceiver } from './msgpack_channel.js';
 
@@ -9,26 +9,12 @@ interface NativeClassCtor {
 }
 
 function loadNativeModule(): Record<string, NativeClassCtor> {
-  const __filename = fileURLToPath(import.meta.url);
-  const __dirname = dirname(__filename);
-
-  // Map Node.js platform/arch to build directory names
-  const arch = process.arch === 'x64' ? 'amd64' : process.arch;
-  const platform = process.platform === 'darwin' ? 'macos' : process.platform;
-  const variant = `${arch}-${platform}`;
-
-  const modulePath = join(__dirname, '..', 'build', variant, 'nodejs_module.node');
-
-  try {
-    const require = createRequire(import.meta.url);
-    return require(modulePath);
-  } catch (error) {
-    throw new Error(
-      `Failed to load native module for ${variant} from ${modulePath}. ` +
-        `Supported: amd64-linux, arm64-linux, amd64-macos, arm64-macos. ` +
-        `Error: ${error}`,
-    );
+  const require = createRequire(import.meta.url);
+  const napiPath = findNapiBinary();
+  if (!napiPath) {
+    throw new Error('NAPI binary not found for current platform.');
   }
+  return require(napiPath);
 }
 
 const nativeModule: Record<string, NativeClassCtor | Function> = loadNativeModule();
@@ -36,6 +22,84 @@ 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
+ * TODO(MW): include generate_hints bool
+ * @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