@aztec/simulator 0.0.1-commit.4d79d1f2d → 0.0.1-commit.4d9804df

package/dest/private/circuit_recording/simulator_recorder_wrapper.js

@@ -16,21 +16,18 @@
         return this.#simulate((wrappedCallback)=>this.simulator.executeUserCircuit(input, artifact, wrappedCallback), input, artifact.bytecode, artifact.contractName, artifact.name, callback);
     }
     async #simulate(simulateFn, input, bytecode, contractName, functionName, callback) {
-        // Start recording circuit execution
-        await this.recorder.start(input, bytecode, contractName, functionName);
-        // If callback was provided, we wrap it in a circuit recorder callback wrapper
+        // If a callback was provided, we wrap it so that its oracle calls are recorded. The wrapped callback reads the
+        // active recording lazily, so it picks up the recording opened by record() below.
         const wrappedCallback = this.recorder.wrapCallback(callback);
-        let result;
-        try {
-            result = await simulateFn(wrappedCallback);
-        } catch (error) {
-            // If an error occurs, we finalize the recording file with the error
-            await this.recorder.finishWithError(error);
-            throw error;
-        }
-        // Witness generation is complete so we finish the circuit recorder
-        const recording = await this.recorder.finish();
-        result.oracles = recording.oracleCalls?.reduce((acc, { time, name })=>{
+        // record() opens a recording for this circuit, runs the simulation within it, and finalizes it. A simulation
+        // failure is re-thrown unchanged, so recorder bookkeeping never masks the underlying error.
+        const { result, recording } = await this.recorder.record({
+            input,
+            bytecode,
+            circuitName: contractName,
+            functionName
+        }, ()=>simulateFn(wrappedCallback));
+        result.oracles = recording.oracleCalls.reduce((acc, { time, name })=>{
             if (!acc[name]) {
                 acc[name] = {
                     times: []

package/dest/public/avm/testing/account_proof_fetcher.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiYWNjb3VudF9wcm9vZl9mZXRjaGVyLmQudHMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi8uLi9zcmMvcHVibGljL2F2bS90ZXN0aW5nL2FjY291bnRfcHJvb2ZfZmV0Y2hlci50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiIn0=

package/dest/public/avm/testing/account_proof_fetcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"account_proof_fetcher.d.ts","sourceRoot":"","sources":["../../../../src/public/avm/testing/account_proof_fetcher.ts"],"names":[],"mappings":""}

package/dest/public/avm/{fixtures → testing}/base_avm_simulation_tester.d.ts

@@ -30,9 +30,10 @@ export declare abstract class BaseAvmSimulationTester {
     registerAndDeployContract(constructorArgs: any[], deployer: AztecAddress, contractArtifact: ContractArtifact, skipNullifierInsertion?: boolean, seed?: number, contractClassSeed?: number, originalContractClassId?: Fr): Promise<ContractInstanceWithAddress>;
     registerFeeJuiceContract(): Promise<ContractInstanceWithAddress>;
     registerAuthContract(): Promise<ContractInstanceWithAddress>;
+    registerClassRegistryContract(): Promise<ContractInstanceWithAddress>;
     registerInstanceRegistryContract(): Promise<ContractInstanceWithAddress>;
     addContractInstance(contractInstance: ContractInstanceWithAddress, skipNullifierInsertion?: boolean): Promise<void>;
     private insertContractAddressNullifier;
     insertNullifier(contractThatEmitted: AztecAddress, nullifier: Fr): Promise<void>;
 }
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiYmFzZV9hdm1fc2ltdWxhdGlvbl90ZXN0ZXIuZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uLy4uLy4uL3NyYy9wdWJsaWMvYXZtL2ZpeHR1cmVzL2Jhc2VfYXZtX3NpbXVsYXRpb25fdGVzdGVyLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUNBLE9BQU8sRUFBRSxFQUFFLEVBQUUsTUFBTSxnQ0FBZ0MsQ0FBQztBQU1wRCxPQUFPLEtBQUssRUFBRSxnQkFBZ0IsRUFBRSxNQUFNLG1CQUFtQixDQUFDO0FBRTFELE9BQU8sRUFBRSxZQUFZLEVBQUUsTUFBTSw2QkFBNkIsQ0FBQztBQUMzRCxPQUFPLEtBQUssRUFBRSwyQkFBMkIsRUFBRSxNQUFNLHdCQUF3QixDQUFDO0FBRTFFLE9BQU8sS0FBSyxFQUFFLHlCQUF5QixFQUFFLE1BQU0saUNBQWlDLENBQUM7QUFHakYsT0FBTyxLQUFLLEVBQUUsd0JBQXdCLEVBQUUsTUFBTSwrQ0FBK0MsQ0FBQztBQUc5Rjs7Ozs7Ozs7OztHQVVHO0FBQ0gsOEJBQXNCLHVCQUF1QjtJQUlsQyxrQkFBa0IsRUFBRSx3QkFBd0I7SUFDNUMsV0FBVyxFQUFFLHlCQUF5QjtJQUM3QyxPQUFPLENBQUMsc0JBQXNCO0lBTHpCLE1BQU0seUNBQXlDO0lBRXRELFlBQ1Msa0JBQWtCLEVBQUUsd0JBQXdCLEVBQzVDLFdBQVcsRUFBRSx5QkFBeUIsRUFDckMsc0JBQXNCLEtBQW1CLEVBQy9DO0lBRUUsa0JBQWtCLENBQUMsUUFBUSxFQUFFLFlBQVksRUFBRSxPQUFPLEtBQThCLGlCQUlyRjtJQUVLLGdCQUFnQixDQUFDLE9BQU8sRUFBRSxZQUFZLEVBQUUsSUFBSSxFQUFFLEVBQUUsRUFBRSxLQUFLLEVBQUUsRUFBRSxpQkFLaEU7SUFFRDs7O09BR0c7SUFDRyx5QkFBeUIsQ0FDN0IsZUFBZSxFQUFFLEdBQUcsRUFBRSxFQUN0QixRQUFRLEVBQUUsWUFBWSxFQUN0QixnQkFBZ0IsRUFBRSxnQkFBZ0IsRUFDbEMsc0JBQXNCLFVBQVEsRUFDOUIsSUFBSSxTQUFJLEVBQ1IsaUJBQWlCLFNBQU8sRUFDeEIsdUJBQXVCLENBQUMsRUFBRSxFQUFFLEdBQzNCLE9BQU8sQ0FBQywyQkFBMkIsQ0FBQyxDQWdCdEM7SUFFSyx3QkFBd0IsSUFBSSxPQUFPLENBQUMsMkJBQTJCLENBQUMsQ0FTckU7SUFFSyxvQkFBb0IsSUFBSSxPQUFPLENBQUMsMkJBQTJCLENBQUMsQ0FhakU7SUFFSyxnQ0FBZ0MsSUFBSSxPQUFPLENBQUMsMkJBQTJCLENBQUMsQ0FhN0U7SUFFSyxtQkFBbUIsQ0FBQyxnQkFBZ0IsRUFBRSwyQkFBMkIsRUFBRSxzQkFBc0IsVUFBUSxpQkFLdEc7WUFFYSw4QkFBOEI7SUFRdEMsZUFBZSxDQUFDLG1CQUFtQixFQUFFLFlBQVksRUFBRSxTQUFTLEVBQUUsRUFBRSxpQkFHckU7Q0FDRiJ9
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiYmFzZV9hdm1fc2ltdWxhdGlvbl90ZXN0ZXIuZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uLy4uLy4uL3NyYy9wdWJsaWMvYXZtL3Rlc3RpbmcvYmFzZV9hdm1fc2ltdWxhdGlvbl90ZXN0ZXIudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQ0EsT0FBTyxFQUFFLEVBQUUsRUFBRSxNQUFNLGdDQUFnQyxDQUFDO0FBT3BELE9BQU8sS0FBSyxFQUFFLGdCQUFnQixFQUFFLE1BQU0sbUJBQW1CLENBQUM7QUFFMUQsT0FBTyxFQUFFLFlBQVksRUFBRSxNQUFNLDZCQUE2QixDQUFDO0FBQzNELE9BQU8sS0FBSyxFQUFFLDJCQUEyQixFQUFFLE1BQU0sd0JBQXdCLENBQUM7QUFFMUUsT0FBTyxLQUFLLEVBQUUseUJBQXlCLEVBQUUsTUFBTSxpQ0FBaUMsQ0FBQztBQUdqRixPQUFPLEtBQUssRUFBRSx3QkFBd0IsRUFBRSxNQUFNLCtDQUErQyxDQUFDO0FBRzlGOzs7Ozs7Ozs7O0dBVUc7QUFDSCw4QkFBc0IsdUJBQXVCO0lBSWxDLGtCQUFrQixFQUFFLHdCQUF3QjtJQUM1QyxXQUFXLEVBQUUseUJBQXlCO0lBQzdDLE9BQU8sQ0FBQyxzQkFBc0I7SUFMekIsTUFBTSx5Q0FBeUM7SUFFdEQsWUFDUyxrQkFBa0IsRUFBRSx3QkFBd0IsRUFDNUMsV0FBVyxFQUFFLHlCQUF5QixFQUNyQyxzQkFBc0IsS0FBbUIsRUFDL0M7SUFFRSxrQkFBa0IsQ0FBQyxRQUFRLEVBQUUsWUFBWSxFQUFFLE9BQU8sS0FBOEIsaUJBSXJGO0lBRUssZ0JBQWdCLENBQUMsT0FBTyxFQUFFLFlBQVksRUFBRSxJQUFJLEVBQUUsRUFBRSxFQUFFLEtBQUssRUFBRSxFQUFFLGlCQUtoRTtJQUVEOzs7T0FHRztJQUNHLHlCQUF5QixDQUM3QixlQUFlLEVBQUUsR0FBRyxFQUFFLEVBQ3RCLFFBQVEsRUFBRSxZQUFZLEVBQ3RCLGdCQUFnQixFQUFFLGdCQUFnQixFQUNsQyxzQkFBc0IsVUFBUSxFQUM5QixJQUFJLFNBQUksRUFDUixpQkFBaUIsU0FBTyxFQUN4Qix1QkFBdUIsQ0FBQyxFQUFFLEVBQUUsR0FDM0IsT0FBTyxDQUFDLDJCQUEyQixDQUFDLENBZ0J0QztJQUVLLHdCQUF3QixJQUFJLE9BQU8sQ0FBQywyQkFBMkIsQ0FBQyxDQVNyRTtJQUVLLG9CQUFvQixJQUFJLE9BQU8sQ0FBQywyQkFBMkIsQ0FBQyxDQWlCakU7SUFFSyw2QkFBNkIsSUFBSSxPQUFPLENBQUMsMkJBQTJCLENBQUMsQ0FhMUU7SUFFSyxnQ0FBZ0MsSUFBSSxPQUFPLENBQUMsMkJBQTJCLENBQUMsQ0FhN0U7SUFFSyxtQkFBbUIsQ0FBQyxnQkFBZ0IsRUFBRSwyQkFBMkIsRUFBRSxzQkFBc0IsVUFBUSxpQkFLdEc7WUFFYSw4QkFBOEI7SUFRdEMsZUFBZSxDQUFDLG1CQUFtQixFQUFFLFlBQVksRUFBRSxTQUFTLEVBQUUsRUFBRSxpQkFHckU7Q0FDRiJ9

package/dest/public/avm/testing/base_avm_simulation_tester.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base_avm_simulation_tester.d.ts","sourceRoot":"","sources":["../../../../src/public/avm/testing/base_avm_simulation_tester.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,EAAE,EAAE,MAAM,gCAAgC,CAAC;AAOpD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAE1D,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAC3D,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,wBAAwB,CAAC;AAE1E,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,iCAAiC,CAAC;AAGjF,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,+CAA+C,CAAC;AAG9F;;;;;;;;;;GAUG;AACH,8BAAsB,uBAAuB;IAIlC,kBAAkB,EAAE,wBAAwB;IAC5C,WAAW,EAAE,yBAAyB;IAC7C,OAAO,CAAC,sBAAsB;IALzB,MAAM,yCAAyC;IAEtD,YACS,kBAAkB,EAAE,wBAAwB,EAC5C,WAAW,EAAE,yBAAyB,EACrC,sBAAsB,KAAmB,EAC/C;IAEE,kBAAkB,CAAC,QAAQ,EAAE,YAAY,EAAE,OAAO,KAA8B,iBAIrF;IAEK,gBAAgB,CAAC,OAAO,EAAE,YAAY,EAAE,IAAI,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,iBAKhE;IAED;;;OAGG;IACG,yBAAyB,CAC7B,eAAe,EAAE,GAAG,EAAE,EACtB,QAAQ,EAAE,YAAY,EACtB,gBAAgB,EAAE,gBAAgB,EAClC,sBAAsB,UAAQ,EAC9B,IAAI,SAAI,EACR,iBAAiB,SAAO,EACxB,uBAAuB,CAAC,EAAE,EAAE,GAC3B,OAAO,CAAC,2BAA2B,CAAC,CAgBtC;IAEK,wBAAwB,IAAI,OAAO,CAAC,2BAA2B,CAAC,CASrE;IAEK,oBAAoB,IAAI,OAAO,CAAC,2BAA2B,CAAC,CAiBjE;IAEK,6BAA6B,IAAI,OAAO,CAAC,2BAA2B,CAAC,CAa1E;IAEK,gCAAgC,IAAI,OAAO,CAAC,2BAA2B,CAAC,CAa7E;IAEK,mBAAmB,CAAC,gBAAgB,EAAE,2BAA2B,EAAE,sBAAsB,UAAQ,iBAKtG;YAEa,8BAA8B;IAQtC,eAAe,CAAC,mBAAmB,EAAE,YAAY,EAAE,SAAS,EAAE,EAAE,iBAGrE;CACF"}

package/dest/public/avm/{fixtures → testing}/base_avm_simulation_tester.js

@@ -2,9 +2,10 @@ import { CONTRACT_INSTANCE_REGISTRY_CONTRACT_ADDRESS } from '@aztec/constants';
 import { Fr } from '@aztec/foundation/curves/bn254';
 import { createLogger } from '@aztec/foundation/log';
 import { ProtocolContractAddress } from '@aztec/protocol-contracts';
-import { getCanonicalAuthRegistry } from '@aztec/protocol-contracts/auth-registry';
+import { getCanonicalClassRegistry } from '@aztec/protocol-contracts/class-registry';
 import { computeFeePayerBalanceStorageSlot, getCanonicalFeeJuice } from '@aztec/protocol-contracts/fee-juice';
 import { getCanonicalInstanceRegistry } from '@aztec/protocol-contracts/instance-registry';
+import { getStandardAuthRegistry } from '@aztec/standard-contracts/auth-registry';
 import { PublicDataWrite } from '@aztec/stdlib/avm';
 import { AztecAddress } from '@aztec/stdlib/aztec-address';
 import { computePublicDataTreeLeafSlot, siloNullifier } from '@aztec/stdlib/hash';
@@ -66,15 +67,29 @@ import { createContractClassAndInstance } from './utils.js';
         return feeJuice.instance;
     }
     async registerAuthContract() {
-        const authRegistry = await getCanonicalAuthRegistry();
+        const authRegistry = await getStandardAuthRegistry();
         const authRegistryContractClassPublic = {
             ...authRegistry.contractClass,
             privateFunctions: [],
             utilityFunctions: []
         };
         await this.contractDataSource.addNewContract(authRegistry.artifact, authRegistryContractClassPublic, authRegistry.instance);
+        // AuthRegistry is a standard contract (not a protocol contract), so the AVM enforces a
+        // deployment-nullifier check on every instance retrieval. Insert the nullifier here so
+        // calls to AuthRegistry don't EXCEPTIONAL_HALT during simulation.
+        await this.insertContractAddressNullifier(authRegistry.instance.address);
         return authRegistry.instance;
     }
+    async registerClassRegistryContract() {
+        const classRegistry = await getCanonicalClassRegistry();
+        const classRegistryContractClassPublic = {
+            ...classRegistry.contractClass,
+            privateFunctions: [],
+            utilityFunctions: []
+        };
+        await this.contractDataSource.addNewContract(classRegistry.artifact, classRegistryContractClassPublic, classRegistry.instance);
+        return classRegistry.instance;
+    }
     async registerInstanceRegistryContract() {
         const instanceRegistry = await getCanonicalInstanceRegistry();
         const instanceRegistryContractClassPublic = {
@@ -92,7 +107,7 @@ import { createContractClassAndInstance } from './utils.js';
         await this.contractDataSource.addContractInstance(contractInstance);
     }
     async insertContractAddressNullifier(contractAddress) {
-        const contractAddressNullifier = await siloNullifier(AztecAddress.fromNumber(CONTRACT_INSTANCE_REGISTRY_CONTRACT_ADDRESS), contractAddress.toField());
+        const contractAddressNullifier = await siloNullifier(AztecAddress.fromNumberUnsafe(CONTRACT_INSTANCE_REGISTRY_CONTRACT_ADDRESS), contractAddress.toField());
         await this.merkleTrees.sequentialInsert(MerkleTreeId.NULLIFIER_TREE, [
             contractAddressNullifier.toBuffer()
         ]);

package/dest/public/avm/testing/utils.d.ts

@@ -0,0 +1,32 @@
+import { BlockNumber } from '@aztec/foundation/branded-types';
+import { Fr } from '@aztec/foundation/curves/bn254';
+import { type ContractArtifact, type FunctionAbi, type FunctionArtifact, FunctionSelector } from '@aztec/stdlib/abi';
+import { AztecAddress } from '@aztec/stdlib/aztec-address';
+import { type ContractClassPublic, type ContractInstanceWithAddress } from '@aztec/stdlib/contract';
+import type { UInt64 } from '@aztec/stdlib/types';
+export declare const PUBLIC_DISPATCH_FN_NAME = "public_dispatch";
+export declare const DEFAULT_TIMESTAMP: UInt64;
+export declare const DEFAULT_BLOCK_NUMBER: BlockNumber;
+/**
+ * Create a new object with all the same properties as the original, except for the ones in the overrides object.
+ */
+export declare function allSameExcept(original: any, overrides: any): any;
+export declare function getFunctionSelector(functionName: string, contractArtifact: ContractArtifact): Promise<FunctionSelector>;
+export declare function getContractFunctionArtifact(functionName: string, contractArtifact: ContractArtifact): FunctionArtifact | undefined;
+export declare function getContractFunctionAbi(functionName: string, contractArtifact: ContractArtifact): FunctionAbi | undefined;
+/**
+ * Create a contract class and instance given constructor args, artifact, etc.
+ * NOTE: This is useful for testing real-ish contract class registration and instance deployment TXs (via logs)
+ * @param constructorArgs - The constructor arguments for the contract.
+ * @param deployer - The deployer of the contract.
+ * @param contractArtifact - The contract artifact for the contract.
+ * @param seed - The seed for the contract.
+ * @param originalContractClassId - The original contract class ID (if upgraded)
+ * @returns The contract class, instance, and contract address nullifier.
+ */
+export declare function createContractClassAndInstance(constructorArgs: any[], deployer: AztecAddress, contractArtifact: ContractArtifact, seed?: number, contractClassSeed?: number, originalContractClassId?: Fr): Promise<{
+    contractClass: ContractClassPublic;
+    contractInstance: ContractInstanceWithAddress;
+    contractAddressNullifier: Fr;
+}>;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidXRpbHMuZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uLy4uLy4uL3NyYy9wdWJsaWMvYXZtL3Rlc3RpbmcvdXRpbHMudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQ0EsT0FBTyxFQUFFLFdBQVcsRUFBRSxNQUFNLGlDQUFpQyxDQUFDO0FBQzlELE9BQU8sRUFBRSxFQUFFLEVBQUUsTUFBTSxnQ0FBZ0MsQ0FBQztBQUNwRCxPQUFPLEVBQ0wsS0FBSyxnQkFBZ0IsRUFDckIsS0FBSyxXQUFXLEVBQ2hCLEtBQUssZ0JBQWdCLEVBQ3JCLGdCQUFnQixFQUVqQixNQUFNLG1CQUFtQixDQUFDO0FBQzNCLE9BQU8sRUFBRSxZQUFZLEVBQUUsTUFBTSw2QkFBNkIsQ0FBQztBQUMzRCxPQUFPLEVBQ0wsS0FBSyxtQkFBbUIsRUFDeEIsS0FBSywyQkFBMkIsRUFFakMsTUFBTSx3QkFBd0IsQ0FBQztBQUloQyxPQUFPLEtBQUssRUFBRSxNQUFNLEVBQUUsTUFBTSxxQkFBcUIsQ0FBQztBQUtsRCxlQUFPLE1BQU0sdUJBQXVCLG9CQUFvQixDQUFDO0FBQ3pELGVBQU8sTUFBTSxpQkFBaUIsRUFBRSxNQUFlLENBQUM7QUFDaEQsZUFBTyxNQUFNLG9CQUFvQixhQUFrQixDQUFDO0FBRXBEOztHQUVHO0FBQ0gsd0JBQWdCLGFBQWEsQ0FBQyxRQUFRLEVBQUUsR0FBRyxFQUFFLFNBQVMsRUFBRSxHQUFHLEdBQUcsR0FBRyxDQUVoRTtBQUVELHdCQUFnQixtQkFBbUIsQ0FDakMsWUFBWSxFQUFFLE1BQU0sRUFDcEIsZ0JBQWdCLEVBQUUsZ0JBQWdCLEdBQ2pDLE9BQU8sQ0FBQyxnQkFBZ0IsQ0FBQyxDQUszQjtBQUVELHdCQUFnQiwyQkFBMkIsQ0FDekMsWUFBWSxFQUFFLE1BQU0sRUFDcEIsZ0JBQWdCLEVBQUUsZ0JBQWdCLEdBQ2pDLGdCQUFnQixHQUFHLFNBQVMsQ0FFOUI7QUFFRCx3QkFBZ0Isc0JBQXNCLENBQ3BDLFlBQVksRUFBRSxNQUFNLEVBQ3BCLGdCQUFnQixFQUFFLGdCQUFnQixHQUNqQyxXQUFXLEdBQUcsU0FBUyxDQUt6QjtBQUVEOzs7Ozs7Ozs7R0FTRztBQUNILHdCQUFzQiw4QkFBOEIsQ0FDbEQsZUFBZSxFQUFFLEdBQUcsRUFBRSxFQUN0QixRQUFRLEVBQUUsWUFBWSxFQUN0QixnQkFBZ0IsRUFBRSxnQkFBZ0IsRUFDbEMsSUFBSSxTQUFJLEVBQ1IsaUJBQWlCLFNBQU8sRUFDeEIsdUJBQXVCLENBQUMsRUFBRSxFQUFFLEdBQzNCLE9BQU8sQ0FBQztJQUNULGFBQWEsRUFBRSxtQkFBbUIsQ0FBQztJQUNuQyxnQkFBZ0IsRUFBRSwyQkFBMkIsQ0FBQztJQUM5Qyx3QkFBd0IsRUFBRSxFQUFFLENBQUM7Q0FDOUIsQ0FBQyxDQStCRCJ9

package/dest/public/avm/testing/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../../../src/public/avm/testing/utils.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,iCAAiC,CAAC;AAC9D,OAAO,EAAE,EAAE,EAAE,MAAM,gCAAgC,CAAC;AACpD,OAAO,EACL,KAAK,gBAAgB,EACrB,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACrB,gBAAgB,EAEjB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAC3D,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,2BAA2B,EAEjC,MAAM,wBAAwB,CAAC;AAIhC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAKlD,eAAO,MAAM,uBAAuB,oBAAoB,CAAC;AACzD,eAAO,MAAM,iBAAiB,EAAE,MAAe,CAAC;AAChD,eAAO,MAAM,oBAAoB,aAAkB,CAAC;AAEpD;;GAEG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,GAAG,EAAE,SAAS,EAAE,GAAG,GAAG,GAAG,CAEhE;AAED,wBAAgB,mBAAmB,CACjC,YAAY,EAAE,MAAM,EACpB,gBAAgB,EAAE,gBAAgB,GACjC,OAAO,CAAC,gBAAgB,CAAC,CAK3B;AAED,wBAAgB,2BAA2B,CACzC,YAAY,EAAE,MAAM,EACpB,gBAAgB,EAAE,gBAAgB,GACjC,gBAAgB,GAAG,SAAS,CAE9B;AAED,wBAAgB,sBAAsB,CACpC,YAAY,EAAE,MAAM,EACpB,gBAAgB,EAAE,gBAAgB,GACjC,WAAW,GAAG,SAAS,CAKzB;AAED;;;;;;;;;GASG;AACH,wBAAsB,8BAA8B,CAClD,eAAe,EAAE,GAAG,EAAE,EACtB,QAAQ,EAAE,YAAY,EACtB,gBAAgB,EAAE,gBAAgB,EAClC,IAAI,SAAI,EACR,iBAAiB,SAAO,EACxB,uBAAuB,CAAC,EAAE,EAAE,GAC3B,OAAO,CAAC;IACT,aAAa,EAAE,mBAAmB,CAAC;IACnC,gBAAgB,EAAE,2BAA2B,CAAC;IAC9C,wBAAwB,EAAE,EAAE,CAAC;CAC9B,CAAC,CA+BD"}

package/dest/public/avm/{fixtures → testing}/utils.js

@@ -4,14 +4,11 @@ import { Fr } from '@aztec/foundation/curves/bn254';
 import { FunctionSelector, getAllFunctionAbis } from '@aztec/stdlib/abi';
 import { AztecAddress } from '@aztec/stdlib/aztec-address';
 import { computeInitializationHash } from '@aztec/stdlib/contract';
-import { isNoirCallStackUnresolved } from '@aztec/stdlib/errors';
 import { siloNullifier } from '@aztec/stdlib/hash';
 import { deriveKeys } from '@aztec/stdlib/keys';
 import { makeContractClassPublic, makeContractInstanceFromClassId } from '@aztec/stdlib/testing';
 import { strict as assert } from 'assert';
 import merge from 'lodash.merge';
-import { resolveAssertionMessageFromRevertData, traverseCauseChain } from '../../../common/index.js';
-import { Field, Uint8, Uint32, Uint64 } from '../avm_memory_types.js';
 export const PUBLIC_DISPATCH_FN_NAME = 'public_dispatch';
 export const DEFAULT_TIMESTAMP = 99833n;
 export const DEFAULT_BLOCK_NUMBER = BlockNumber(42);
@@ -20,26 +17,6 @@ export const DEFAULT_BLOCK_NUMBER = BlockNumber(42);
  */ export function allSameExcept(original, overrides) {
     return merge({}, original, overrides);
 }
-export function randomMemoryBytes(length) {
-    return [
-        ...Array(length)
-    ].map((_)=>new Uint8(Math.floor(Math.random() * 255)));
-}
-export function randomMemoryUint32s(length) {
-    return [
-        ...Array(length)
-    ].map((_)=>new Uint32(Math.floor(Math.random() * 255)));
-}
-export function randomMemoryUint64s(length) {
-    return [
-        ...Array(length)
-    ].map((_)=>new Uint64(Math.floor(Math.random() * 255)));
-}
-export function randomMemoryFields(length) {
-    return [
-        ...Array(length)
-    ].map((_)=>new Field(Fr.random()));
-}
 export function getFunctionSelector(functionName, contractArtifact) {
     const fnArtifact = getAllFunctionAbis(contractArtifact).find((f)=>f.name === functionName);
     assert(!!fnArtifact, `Function ${functionName} not found in ${contractArtifact.name}`);
@@ -52,16 +29,6 @@ export function getContractFunctionArtifact(functionName, contractArtifact) {
 export function getContractFunctionAbi(functionName, contractArtifact) {
     return contractArtifact.functions.find((f)=>f.name === functionName) ?? contractArtifact.nonDispatchPublicFunctions.find((f)=>f.name === functionName);
 }
-export function resolveContractAssertionMessage(functionName, revertReason, output, contractArtifact) {
-    traverseCauseChain(revertReason, (cause)=>{
-        revertReason = cause;
-    });
-    const functionArtifact = getAllFunctionAbis(contractArtifact).find((f)=>f.name === functionName);
-    if (!functionArtifact || !revertReason.noirCallStack || !isNoirCallStackUnresolved(revertReason.noirCallStack)) {
-        return undefined;
-    }
-    return resolveAssertionMessageFromRevertData(output, functionArtifact);
-}
 /**
  * Create a contract class and instance given constructor args, artifact, etc.
  * NOTE: This is useful for testing real-ish contract class registration and instance deployment TXs (via logs)
@@ -77,17 +44,20 @@ export function resolveContractAssertionMessage(functionName, revertReason, outp
     const constructorAbi = getContractFunctionAbi('constructor', contractArtifact);
     const { publicKeys } = await deriveKeys(new Fr(seed));
     const initializationHash = await computeInitializationHash(constructorAbi, constructorArgs);
+    const immutablesHash = new Fr(seed + 1);
     const contractInstance = originalContractClassId === undefined ? await makeContractInstanceFromClassId(contractClass.id, seed, {
         deployer,
         initializationHash,
+        immutablesHash,
         publicKeys
     }) : await makeContractInstanceFromClassId(originalContractClassId, seed, {
         deployer,
         initializationHash,
         currentClassId: contractClass.id,
+        immutablesHash,
         publicKeys
     });
-    const contractAddressNullifier = await siloNullifier(AztecAddress.fromNumber(CONTRACT_INSTANCE_REGISTRY_CONTRACT_ADDRESS), contractInstance.address.toField());
+    const contractAddressNullifier = await siloNullifier(AztecAddress.fromNumberUnsafe(CONTRACT_INSTANCE_REGISTRY_CONTRACT_ADDRESS), contractInstance.address.toField());
     return {
         contractClass,
         contractInstance,

package/dest/public/avm_simulator.d.ts

@@ -0,0 +1,28 @@
+import type { PublicContractsDB } from './public_db_sources.js';
+/**
+ * Identifies the contract data a single simulation reads. The AVM's contract-data lookups during a
+ * `simulate` call are answered from `contractsDB`; `forkId` and `timestamp` scope those lookups to the
+ * world-state fork being simulated against. How this reaches the AVM (in-process call, IPC callback
+ * server, ...) is the implementation's concern — callers only supply the context.
+ */
+export interface AvmContractsDBContext {
+    contractsDB: PublicContractsDB;
+    forkId: number;
+    timestamp: bigint;
+}
+/**
+ * Something that can run AVM simulations, independent of how the work is dispatched (a single external
+ * process, a pool of them, or an in-process stub). Callers hold this and never see the underlying transport.
+ */
+export interface AvmSimulator {
+    /**
+     * Run a fast simulation and return the msgpack-encoded result. `context` supplies the contracts DB whose
+     * data the simulation reads. If `signal` aborts, the simulation stops at the next cancellation checkpoint.
+     */
+    simulate(inputBuffer: Uint8Array, context: AvmContractsDBContext, signal?: AbortSignal): Promise<Uint8Array>;
+    /** Run a simulation collecting proving hints and return the msgpack-encoded result. */
+    simulateWithHints(inputBuffer: Uint8Array): Promise<Uint8Array>;
+    /** Release any resources held by the underlying implementation. */
+    destroy?(): Promise<void>;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiYXZtX3NpbXVsYXRvci5kLnRzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vc3JjL3B1YmxpYy9hdm1fc2ltdWxhdG9yLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sS0FBSyxFQUFFLGlCQUFpQixFQUFFLE1BQU0sd0JBQXdCLENBQUM7QUFFaEU7Ozs7O0dBS0c7QUFDSCxNQUFNLFdBQVcscUJBQXFCO0lBQ3BDLFdBQVcsRUFBRSxpQkFBaUIsQ0FBQztJQUMvQixNQUFNLEVBQUUsTUFBTSxDQUFDO0lBQ2YsU0FBUyxFQUFFLE1BQU0sQ0FBQztDQUNuQjtBQUVEOzs7R0FHRztBQUNILE1BQU0sV0FBVyxZQUFZO0lBQzNCOzs7T0FHRztJQUNILFFBQVEsQ0FBQyxXQUFXLEVBQUUsVUFBVSxFQUFFLE9BQU8sRUFBRSxxQkFBcUIsRUFBRSxNQUFNLENBQUMsRUFBRSxXQUFXLEdBQUcsT0FBTyxDQUFDLFVBQVUsQ0FBQyxDQUFDO0lBQzdHLHVGQUF1RjtJQUN2RixpQkFBaUIsQ0FBQyxXQUFXLEVBQUUsVUFBVSxHQUFHLE9BQU8sQ0FBQyxVQUFVLENBQUMsQ0FBQztJQUNoRSxtRUFBbUU7SUFDbkUsT0FBTyxDQUFDLElBQUksT0FBTyxDQUFDLElBQUksQ0FBQyxDQUFDO0NBQzNCIn0=

package/dest/public/avm_simulator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"avm_simulator.d.ts","sourceRoot":"","sources":["../../src/public/avm_simulator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAEhE;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IACpC,WAAW,EAAE,iBAAiB,CAAC;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,QAAQ,CAAC,WAAW,EAAE,UAAU,EAAE,OAAO,EAAE,qBAAqB,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAC7G,uFAAuF;IACvF,iBAAiB,CAAC,WAAW,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAChE,mEAAmE;IACnE,OAAO,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B"}

package/dest/public/avm_simulator.js

@@ -0,0 +1,4 @@
+/**
+ * Something that can run AVM simulations, independent of how the work is dispatched (a single external
+ * process, a pool of them, or an in-process stub). Callers hold this and never see the underlying transport.
+ */ export { };

package/dest/public/avm_simulator_pool.d.ts

@@ -0,0 +1,45 @@
+import type { AvmContractsDBContext, AvmSimulator } from './avm_simulator.js';
+export interface AvmSimulatorPoolOptions {
+    /** Maximum number of concurrent AVM processes. If not set, defaults to AVM_MAX_CONCURRENT_SIMULATIONS env var or 4. */
+    maxSize?: number;
+    /** Path to the bb-avm-sim binary. If omitted, the generated package resolves it. */
+    avmBinaryPath?: string;
+    /** IPC path for the shared WSDB server. */
+    wsdbIpcPath: string;
+    /** Optional logger function for AVM process output. */
+    logger?: (msg: string) => void;
+}
+/**
+ * The public-execution AVM backend: a lazily-grown pool of bb-avm-sim processes plus the CDB server that
+ * answers those processes' contract-data callbacks. Callers hold this as an {@link AvmSimulator}; the pool,
+ * the CDB server, its IPC path, and fork-id routing are all hidden behind that interface. Each `simulate`
+ * registers the call's contracts DB on the CDB server for the duration of the simulation (keyed by fork id
+ * so concurrent simulations on different forks don't collide) and unregisters it once the call returns.
+ */
+export declare class AvmSimulatorPool implements AvmSimulator {
+    private options;
+    private slots;
+    private available;
+    private waiters;
+    private createdCount;
+    private log;
+    private maxSize;
+    private cdbServer;
+    constructor(options: AvmSimulatorPoolOptions);
+    static spawn(options: AvmSimulatorPoolOptions): Promise<AvmSimulatorPool>;
+    [Symbol.asyncDispose](): Promise<void>;
+    simulate(inputBuffer: Uint8Array, context: AvmContractsDBContext, signal?: AbortSignal): Promise<Uint8Array>;
+    simulateWithHints(inputBuffer: Uint8Array): Promise<Uint8Array>;
+    /** Destroy all AVM processes in the pool and close the CDB server. */
+    destroy(): Promise<void>;
+    /**
+     * Eagerly spawn up to `count` AVM processes (capped at maxSize) and leave them available, so the
+     * first simulate() doesn't pay process spawn/connect cost. Idempotent.
+     */
+    prewarm(count?: number): Promise<void>;
+    private checkout;
+    /** Return an AVM process to the pool after use. */
+    private return;
+    private createSlot;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiYXZtX3NpbXVsYXRvcl9wb29sLmQudHMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvcHVibGljL2F2bV9zaW11bGF0b3JfcG9vbC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFHQSxPQUFPLEtBQUssRUFBRSxxQkFBcUIsRUFBRSxZQUFZLEVBQUUsTUFBTSxvQkFBb0IsQ0FBQztBQUc5RSxNQUFNLFdBQVcsdUJBQXVCO0lBQ3RDLHVIQUF1SDtJQUN2SCxPQUFPLENBQUMsRUFBRSxNQUFNLENBQUM7SUFDakIsb0ZBQW9GO0lBQ3BGLGFBQWEsQ0FBQyxFQUFFLE1BQU0sQ0FBQztJQUN2QiwyQ0FBMkM7SUFDM0MsV0FBVyxFQUFFLE1BQU0sQ0FBQztJQUNwQix1REFBdUQ7SUFDdkQsTUFBTSxDQUFDLEVBQUUsQ0FBQyxHQUFHLEVBQUUsTUFBTSxLQUFLLElBQUksQ0FBQztDQUNoQztBQWFEOzs7Ozs7R0FNRztBQUNILHFCQUFhLGdCQUFpQixZQUFXLFlBQVk7SUFTdkMsT0FBTyxDQUFDLE9BQU87SUFSM0IsT0FBTyxDQUFDLEtBQUssQ0FBc0M7SUFDbkQsT0FBTyxDQUFDLFNBQVMsQ0FBZ0I7SUFDakMsT0FBTyxDQUFDLE9BQU8sQ0FBaUc7SUFDaEgsT0FBTyxDQUFDLFlBQVksQ0FBSztJQUN6QixPQUFPLENBQUMsR0FBRyxDQUFTO0lBQ3BCLE9BQU8sQ0FBQyxPQUFPLENBQVM7SUFDeEIsT0FBTyxDQUFDLFNBQVMsQ0FBZTtJQUVoQyxZQUFvQixPQUFPLEVBQUUsdUJBQXVCLEVBSW5EO0lBRUQsT0FBYSxLQUFLLENBQUMsT0FBTyxFQUFFLHVCQUF1QixHQUFHLE9BQU8sQ0FBQyxnQkFBZ0IsQ0FBQyxDQUs5RTtJQUVLLENBQUMsTUFBTSxDQUFDLFlBQVksQ0FBQyxJQUFJLE9BQU8sQ0FBQyxJQUFJLENBQUMsQ0FFM0M7SUFFSyxRQUFRLENBQUMsV0FBVyxFQUFFLFVBQVUsRUFBRSxPQUFPLEVBQUUscUJBQXFCLEVBQUUsTUFBTSxDQUFDLEVBQUUsV0FBVyxHQUFHLE9BQU8sQ0FBQyxVQUFVLENBQUMsQ0Fjakg7SUFFSyxpQkFBaUIsQ0FBQyxXQUFXLEVBQUUsVUFBVSxHQUFHLE9BQU8sQ0FBQyxVQUFVLENBQUMsQ0FRcEU7SUFFRCxzRUFBc0U7SUFDaEUsT0FBTyxJQUFJLE9BQU8sQ0FBQyxJQUFJLENBQUMsQ0FtQjdCO0lBRUQ7OztPQUdHO0lBQ0csT0FBTyxDQUFDLEtBQUssU0FBSSxHQUFHLE9BQU8sQ0FBQyxJQUFJLENBQUMsQ0FVdEM7WUFHYSxRQUFRO0lBZXRCLG1EQUFtRDtJQUNuRCxPQUFPLENBQUMsTUFBTTtZQVlBLFVBQVU7Q0E4QnpCIn0=

package/dest/public/avm_simulator_pool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"avm_simulator_pool.d.ts","sourceRoot":"","sources":["../../src/public/avm_simulator_pool.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,qBAAqB,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAG9E,MAAM,WAAW,uBAAuB;IACtC,uHAAuH;IACvH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oFAAoF;IACpF,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,2CAA2C;IAC3C,WAAW,EAAE,MAAM,CAAC;IACpB,uDAAuD;IACvD,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CAChC;AAaD;;;;;;GAMG;AACH,qBAAa,gBAAiB,YAAW,YAAY;IASvC,OAAO,CAAC,OAAO;IAR3B,OAAO,CAAC,KAAK,CAAsC;IACnD,OAAO,CAAC,SAAS,CAAgB;IACjC,OAAO,CAAC,OAAO,CAAiG;IAChH,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,GAAG,CAAS;IACpB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,SAAS,CAAe;IAEhC,YAAoB,OAAO,EAAE,uBAAuB,EAInD;IAED,OAAa,KAAK,CAAC,OAAO,EAAE,uBAAuB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAK9E;IAEK,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAE3C;IAEK,QAAQ,CAAC,WAAW,EAAE,UAAU,EAAE,OAAO,EAAE,qBAAqB,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CAcjH;IAEK,iBAAiB,CAAC,WAAW,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAQpE;IAED,sEAAsE;IAChE,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAmB7B;IAED;;;OAGG;IACG,OAAO,CAAC,KAAK,SAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAUtC;YAGa,QAAQ;IAetB,mDAAmD;IACnD,OAAO,CAAC,MAAM;YAYA,UAAU;CA8BzB"}

package/dest/public/avm_simulator_pool.js

@@ -0,0 +1,197 @@
+var _computedKey;
+import { AvmService } from '@aztec/bb-avm-sim';
+import { createLogger } from '@aztec/foundation/log';
+import { CdbIpcServer } from './cdb_ipc_server.js';
+_computedKey = Symbol.asyncDispose;
+/**
+ * The public-execution AVM backend: a lazily-grown pool of bb-avm-sim processes plus the CDB server that
+ * answers those processes' contract-data callbacks. Callers hold this as an {@link AvmSimulator}; the pool,
+ * the CDB server, its IPC path, and fork-id routing are all hidden behind that interface. Each `simulate`
+ * registers the call's contracts DB on the CDB server for the duration of the simulation (keyed by fork id
+ * so concurrent simulations on different forks don't collide) and unregisters it once the call returns.
+ */ export class AvmSimulatorPool {
+    options;
+    slots;
+    available;
+    waiters;
+    createdCount;
+    log;
+    maxSize;
+    cdbServer;
+    constructor(options){
+        this.options = options;
+        this.slots = [];
+        this.available = [];
+        this.waiters = [];
+        this.createdCount = 0;
+        this.log = createLogger('simulator:avm-pool');
+        this.maxSize = options.maxSize ?? parseInt(process.env.AVM_MAX_CONCURRENT_SIMULATIONS ?? '4', 10);
+        this.cdbServer = new CdbIpcServer();
+    }
+    static async spawn(options) {
+        const pool = new AvmSimulatorPool(options);
+        // Always start one process up front so the first simulate() doesn't pay process spawn/connect cost.
+        await pool.prewarm();
+        return pool;
+    }
+    async [_computedKey]() {
+        await this.destroy();
+    }
+    async simulate(inputBuffer, context, signal) {
+        // Register the fork's contracts DB so the C++ AVM's callbacks (which carry this fork id) route to it,
+        // and unregister once the simulation returns — registration is only needed while the call is running.
+        this.cdbServer.registerFork(context.forkId, context.contractsDB, context.timestamp);
+        try {
+            const simulator = await this.checkout();
+            try {
+                return await simulator.simulate(inputBuffer, signal);
+            } finally{
+                this.return(simulator);
+            }
+        } finally{
+            this.cdbServer.unregisterFork(context.forkId);
+        }
+    }
+    async simulateWithHints(inputBuffer) {
+        // The hinted path makes no contract-data callbacks, so no CDB registration is needed.
+        const simulator = await this.checkout();
+        try {
+            return await simulator.simulateWithHints(inputBuffer);
+        } finally{
+            this.return(simulator);
+        }
+    }
+    /** Destroy all AVM processes in the pool and close the CDB server. */ async destroy() {
+        for (const waiter of this.waiters){
+            waiter.reject(new Error('AVM simulator pool destroyed'));
+        }
+        this.waiters = [];
+        const destroyPromises = [];
+        for (const slot of this.slots){
+            if (slot) {
+                destroyPromises.push(slot.destroy());
+            }
+        }
+        await Promise.all(destroyPromises);
+        this.slots = [];
+        this.available = [];
+        this.createdCount = 0;
+        await this.cdbServer.close();
+        this.log.info('AVM simulator pool destroyed');
+    }
+    /**
+   * Eagerly spawn up to `count` AVM processes (capped at maxSize) and leave them available, so the
+   * first simulate() doesn't pay process spawn/connect cost. Idempotent.
+   */ async prewarm(count = 1) {
+        const target = Math.min(count, this.maxSize);
+        const created = [];
+        while(this.createdCount < target){
+            created.push(await this.createSlot());
+        }
+        // Hand the freshly-spawned processes back to the pool so checkout() reuses them.
+        for (const simulator of created){
+            this.return(simulator);
+        }
+    }
+    /** Check out an AVM process from the pool, blocking until one is free. Caller must return() it when done. */ async checkout() {
+        const idx = this.available.pop();
+        if (idx !== undefined && this.slots[idx]) {
+            return this.slots[idx];
+        }
+        if (this.createdCount < this.maxSize || idx !== undefined && !this.slots[idx]) {
+            return await this.createSlot(idx);
+        }
+        return new Promise((resolve, reject)=>{
+            this.waiters.push({
+                resolve,
+                reject
+            });
+        });
+    }
+    /** Return an AVM process to the pool after use. */ return(simulator) {
+        const waiter = this.waiters.shift();
+        if (waiter) {
+            waiter.resolve(simulator);
+        } else {
+            const idx = this.slots.indexOf(simulator);
+            if (idx >= 0) {
+                this.available.push(idx);
+            }
+        }
+    }
+    async createSlot(reuseIdx) {
+        const reuse = reuseIdx !== undefined && reuseIdx < this.slots.length;
+        // Reserve the slot count synchronously, before the async spawn, so concurrent checkouts can't all
+        // observe `createdCount < maxSize` and overshoot the pool (the count is only bumped once control has
+        // yielded on the await). Roll back the reservation if the spawn itself fails.
+        if (!reuse) {
+            this.createdCount++;
+        }
+        let simulator;
+        try {
+            simulator = await AvmSimulatorProcess.spawn({
+                binaryPath: this.options.avmBinaryPath,
+                wsdbIpcPath: this.options.wsdbIpcPath,
+                cdbIpcPath: this.cdbServer.ipcPath,
+                logger: this.options.logger
+            });
+        } catch (err) {
+            if (!reuse) {
+                this.createdCount--;
+            }
+            throw err;
+        }
+        if (reuse) {
+            this.slots[reuseIdx] = simulator;
+        } else {
+            this.slots.push(simulator);
+        }
+        this.log.debug(`Created AVM pool slot (${this.createdCount}/${this.maxSize})`);
+        return simulator;
+    }
+}
+class AvmSimulatorProcess {
+    service;
+    constructor(service){
+        this.service = service;
+    }
+    static async spawn(options) {
+        const service = await AvmService.spawn({
+            binaryPath: options.binaryPath,
+            transport: 'uds',
+            logger: options.logger,
+            extraArgs: [
+                '--wsdb',
+                options.wsdbIpcPath,
+                '--cdb',
+                options.cdbIpcPath
+            ]
+        });
+        return new AvmSimulatorProcess(service);
+    }
+    async simulate(inputBuffer, signal) {
+        // Signal the C++ process to stop at its next cancellation checkpoint when the caller aborts.
+        const onAbort = ()=>this.service.sendProcessSignal('SIGUSR1');
+        if (signal?.aborted) {
+            onAbort();
+        }
+        signal?.addEventListener('abort', onAbort, {
+            once: true
+        });
+        try {
+            return (await this.service.simulate({
+                inputs: inputBuffer
+            })).result;
+        } finally{
+            signal?.removeEventListener('abort', onAbort);
+        }
+    }
+    async simulateWithHints(inputBuffer) {
+        return (await this.service.simulateWithHints({
+            inputs: inputBuffer
+        })).result;
+    }
+    async destroy() {
+        await this.service.destroy();
+    }
+}