@aztec-labs/aztec.js 6.0.0-nightly.20260829

package/dest/contract/deploy_method.js

@@ -0,0 +1,471 @@
+import { Fr } from '@aztec-labs/foundation/curves/bn254';
+import { getInitializer } from '@aztec-labs/stdlib/abi';
+import { AztecAddress } from '@aztec-labs/stdlib/aztec-address';
+import { computePartialAddress, getContractClassFromArtifact, getContractInstanceFromInstantiationParams } from '@aztec-labs/stdlib/contract';
+import { PublicKeys } from '@aztec-labs/stdlib/keys';
+import { ExecutionPayload, mergeExecutionPayloads } from '@aztec-labs/stdlib/tx';
+import { publishContractClass } from '../deployment/publish_class.js';
+import { publishInstance } from '../deployment/publish_instance.js';
+import { BaseContractInteraction } from './base_contract_interaction.js';
+import { ContractFunctionInteraction } from './contract_function_interaction.js';
+import { NO_FROM, NO_WAIT, extractOffchainOutput, toProfileOptions, toSendOptions, toSimulateOptions } from './interaction_options.js';
+/**
+ * Umbrella type for a contract deployment interaction.
+ *
+ * `DeployMethod` is abstract: callers always interact with one of three concrete flavors —
+ * {@link BoundDeployMethod}, {@link UniversalDeployMethod}, or {@link PendingDeployMethod} —
+ * picked by {@link DeployMethod.create} based on the supplied {@link DeployInstantiationOptions}.
+ * The flavors only differ in their initial deployer-lock state; the full API
+ * (`request` / `send` / `simulate` / `profile` / `getInstance` / `getAddress` /
+ * `getPartialAddress` / `register` / `with`) lives on this base, so consumers can type
+ * variables as `DeployMethod<T>` and treat all three uniformly.
+ *
+ * The deployer (and therefore the deployed address) is locked once and never changes. Locking
+ * happens either at construction (via `deployer` or `universalDeploy: true` in the instantiation
+ * options) or lazily on the first `send` / `simulate` / `profile` call, which lock from
+ * `options.from`. Once locked:
+ *
+ * - The address is stable for the lifetime of this object.
+ * - Subsequent `send` / `simulate` / `profile` calls with a `from` that would imply a different
+ *   deployer throw, to prevent silently deploying at a different address than `getAddress()`
+ *   reported.
+ * - A locked universal deployer (`AztecAddress.ZERO`) is compatible with any `from`, since the
+ *   address does not depend on the sender.
+ *
+ * Note that for some contracts, a tx is not required as part of its "creation":
+ * If there are no public functions, and if there are no initialization functions,
+ * then technically the contract has already been "created", and all of the contract's
+ * functions (private and utility) can be interacted-with immediately, without any
+ * "deployment tx".
+ */ export class DeployMethod extends BaseContractInteraction {
+    /** Salt used in the address preimage. */ salt;
+    /** Public keys mixed into the address preimage. */ publicKeys;
+    /** Immutables hash folded into the salted initialization hash. */ immutablesHash;
+    /** Cached instance promise; resolved once the deployer is known. */ #instancePromise;
+    /** Resolved value of `#instancePromise`, populated synchronously once the promise settles. */ #resolvedInstance;
+    /** Constructor function to call. */ constructorArtifact;
+    /** Build artifact of the contract being deployed. */ artifact;
+    /** Factory invoked after deployment to produce the typed contract handle. */ postDeployCtor;
+    /** Encoded constructor arguments for the contract. */ args;
+    /** Extra hashed args propagated through `with(...)` and into the deploy payload. */ extraHashedArgs;
+    constructor(wallet, contract, salt, publicKeys, immutablesHash, payload = {}){
+        super(wallet, payload.authWitnesses ?? [], payload.capsules ?? []);
+        this.artifact = contract.artifact;
+        this.postDeployCtor = contract.postDeployCtor;
+        this.args = contract.args ?? [];
+        this.constructorArtifact = getInitializer(contract.artifact, contract.constructorNameOrArtifact);
+        this.salt = salt ?? Fr.random();
+        this.publicKeys = publicKeys ?? PublicKeys.default();
+        this.immutablesHash = immutablesHash ?? Fr.ZERO;
+        this.extraHashedArgs = payload.extraHashedArgs ?? [];
+    }
+    /**
+   * Constructs the right concrete `DeployMethod` flavor for the supplied instantiation options:
+   * - `{ deployer: <addr> }` → {@link BoundDeployMethod}
+   * - `{ universalDeploy: true }` → {@link UniversalDeployMethod}
+   * - neither set → {@link PendingDeployMethod}
+   *
+   * Mixing `deployer` and `universalDeploy` throws. Returns the umbrella `DeployMethod<T>` type so
+   * callers can use the result generically without narrowing.
+   *
+   * @param wallet - Wallet used to send / simulate the deploy tx.
+   * @param contract - The contract being deployed (artifact, factory, args, initializer).
+   * @param instantiation - Address-affecting parameters (salt, deployer / universalDeploy, publicKeys). Defaults to pending.
+   * @param payload - Auth witnesses, capsules, and extra hashed args propagated to the deploy. Defaults to empty.
+   */ static create(wallet, contract, instantiation = {}, payload = {}) {
+        if (instantiation.deployer !== undefined && instantiation.universalDeploy) {
+            throw new Error('DeployInstantiationOptions: `deployer` and `universalDeploy` are mutually exclusive.');
+        }
+        const { salt, publicKeys, immutablesHash, deployer, universalDeploy } = instantiation;
+        if (universalDeploy) {
+            return new UniversalDeployMethod(wallet, contract, {
+                salt,
+                publicKeys,
+                immutablesHash,
+                universalDeploy: true
+            }, payload);
+        }
+        if (deployer !== undefined) {
+            return new BoundDeployMethod(wallet, contract, {
+                salt,
+                publicKeys,
+                immutablesHash,
+                deployer
+            }, payload);
+        }
+        return new PendingDeployMethod(wallet, contract, {
+            salt,
+            publicKeys,
+            immutablesHash
+        }, payload);
+    }
+    /**
+   * Returns the execution payload that allows this operation to happen on chain. Requires the
+   * deployer to be known — call `getDeployerAddress()` first; on a `PendingDeployMethod` this
+   * throws unless a prior `send` / `simulate` / `profile` has already locked the deployer.
+   *
+   * @param options - Configuration options.
+   * @returns The execution payload for this operation
+   */ async request(options = {}) {
+        const publication = await this.getPublicationExecutionPayload(options);
+        if (!options?.skipRegistration) {
+            await this.wallet.registerContract(await this.getInstance(), this.artifact);
+        }
+        const { authWitnesses, capsules } = options;
+        // Propagates the included authwitnesses, capsules, and extraHashedArgs
+        // potentially baked into the interaction
+        const initialExecutionPayload = new ExecutionPayload([], this.authWitnesses.concat(authWitnesses ?? []), this.capsules.concat(capsules ?? []), this.extraHashedArgs);
+        const initialization = await this.getInitializationExecutionPayload(options);
+        const feeExecutionPayload = options?.fee?.paymentMethod ? await options.fee.paymentMethod.getExecutionPayload() : undefined;
+        const finalExecutionPayload = feeExecutionPayload ? mergeExecutionPayloads([
+            initialExecutionPayload,
+            feeExecutionPayload,
+            publication,
+            initialization
+        ]) : mergeExecutionPayloads([
+            initialExecutionPayload,
+            publication,
+            initialization
+        ]);
+        if (!finalExecutionPayload.calls.length) {
+            throw new Error(`No transactions are needed to publish or initialize contract ${this.artifact.name}`);
+        }
+        return finalExecutionPayload;
+    }
+    /**
+   * Converts DeployOptions to SendOptions.
+   * @param options - Deploy options with wait parameter.
+   */ convertDeployOptionsToSendOptions(options) {
+        return toSendOptions({
+            ...options,
+            wait: options.wait
+        });
+    }
+    /**
+   * Converts deploy simulation options into wallet-level simulate options.
+   * @param options - The deploy simulation options to convert.
+   */ convertDeployOptionsToSimulateOptions(options) {
+        return toSimulateOptions(options);
+    }
+    /**
+   * Converts deploy profile options into wallet-level profile options.
+   * @param options - The deploy profile options to convert.
+   */ convertDeployOptionsToProfileOptions(options) {
+        return toProfileOptions(options);
+    }
+    /**
+   * Adds this contract to the wallet and returns the Contract object.
+   */ async register() {
+        const instance = await this.getInstance();
+        await this.wallet.registerContract(instance, this.artifact);
+        return this.postDeployCtor(instance, this.wallet);
+    }
+    /**
+   * Returns an execution payload for:
+   * - publication of the contract class and
+   * - publication of the contract instance to enable public execution
+   * depending on the provided options.
+   * @param options - Contract creation options.
+   * @returns An execution payload with potentially calls (and bytecode capsule) to the class registry and instance registry.
+   */ async getPublicationExecutionPayload(options) {
+        const calls = [];
+        // Set contract instance object so it's available for populating the DeploySendTx object
+        const instance = await this.getInstance();
+        // Obtain contract class from artifact and check it matches the reported one by the instance.
+        // TODO(@spalladino): We're unnecessarily calculating the contract class multiple times here.
+        const contractClass = await getContractClassFromArtifact(this.artifact);
+        if (!instance.currentContractClassId.equals(contractClass.id)) {
+            throw new Error(`Contract class mismatch when deploying contract: got ${instance.currentContractClassId.toString()} from instance and ${contractClass.id.toString()} from artifact`);
+        }
+        // Publish the contract class if it hasn't been published already.
+        if (!options?.skipClassPublication) {
+            const classMetadata = await this.wallet.getContractClassMetadata(contractClass.id);
+            if (!classMetadata.isContractClassPubliclyRegistered) {
+                this.log.info(`Creating request for publishing contract class ${contractClass.id.toString()} as part of deployment for ${instance.address.toString()}`);
+                const registerContractClassInteraction = await publishContractClass(this.wallet, this.artifact);
+                calls.push(await registerContractClassInteraction.request());
+            } else {
+                this.log.debug(`Skipping contract class publication for ${contractClass.id.toString()} as it is already registered`);
+            }
+        }
+        // Publish the contract instance:
+        if (!options?.skipInstancePublication) {
+            // TODO(https://github.com/AztecProtocol/aztec-packages/issues/15596):
+            // Read the artifact, and if there are no public functions, warn the caller that publication of the
+            // contract instance is not necessary (until such time as they wish to update the instance (i.e. change its class_id)).
+            const deploymentInteraction = publishInstance(this.wallet, instance);
+            calls.push(await deploymentInteraction.request());
+        }
+        return mergeExecutionPayloads(calls);
+    }
+    /**
+   * Returns the calls necessary to initialize the contract.
+   * @param options - Deployment options.
+   * @returns - An array of function calls.
+   */ async getInitializationExecutionPayload(options) {
+        const executionsPayloads = [];
+        if (this.constructorArtifact && !options?.skipInitialization) {
+            const { address } = await this.getInstance();
+            const constructorCall = new ContractFunctionInteraction(this.wallet, address, this.constructorArtifact, this.args);
+            executionsPayloads.push(await constructorCall.request());
+        }
+        return mergeExecutionPayloads(executionsPayloads);
+    }
+    // eslint-disable-next-line jsdoc/require-jsdoc
+    async send(options) {
+        this.lockDeployer(options.from);
+        const executionPayload = await this.request(options);
+        const sendOptions = this.convertDeployOptionsToSendOptions(options);
+        if (options.wait === NO_WAIT) {
+            const result = await this.wallet.sendTx(executionPayload, sendOptions);
+            this.log.debug(`Sent deployment tx ${result.txHash.hash} of ${this.artifact.name} contract`);
+            return result;
+        }
+        const { receipt, ...offchainOutput } = await this.wallet.sendTx(executionPayload, sendOptions);
+        this.log.debug(`Deployed ${this.artifact.name} contract in tx ${receipt.txHash}`);
+        // Attach contract instance
+        const instance = await this.getInstance();
+        const contract = this.postDeployCtor(instance, this.wallet);
+        return {
+            contract,
+            receipt,
+            instance,
+            ...offchainOutput
+        };
+    }
+    /**
+   * Builds the contract instance and returns it. The instance is computed once and cached for
+   * the lifetime of this DeployMethod; subsequent calls return the same instance.
+   *
+   * On a {@link PendingDeployMethod} this throws unless a prior `send` / `simulate` / `profile`
+   * call has already locked the deployer — otherwise the resolved address could silently differ
+   * from the eventually-deployed one.
+   *
+   * @returns An instance object.
+   */ getInstance() {
+        const deployer = this.getDeployerAddress();
+        if (!this.#instancePromise) {
+            this.#instancePromise = getContractInstanceFromInstantiationParams(this.artifact, {
+                constructorArgs: this.args,
+                salt: this.salt,
+                publicKeys: this.publicKeys,
+                immutablesHash: this.immutablesHash,
+                constructorArtifact: this.constructorArtifact,
+                deployer
+            }).then((instance)=>{
+                this.#resolvedInstance = instance;
+                return instance;
+            });
+        }
+        return this.#instancePromise;
+    }
+    /**
+   * Simulate the deployment
+   *
+   * @param options - An optional object containing additional configuration for the simulation.
+   * @returns A simulation result object containing metadata of the execution, including gas
+   * estimations (if requested via options), execution statistics and emitted offchain effects
+   */ async simulate(options) {
+        this.lockDeployer(options.from);
+        const executionPayload = await this.request(options);
+        const simulatedTx = await this.wallet.simulateTx(executionPayload, this.convertDeployOptionsToSimulateOptions(options));
+        return {
+            stats: simulatedTx.stats,
+            ...extractOffchainOutput(simulatedTx.offchainEffects, simulatedTx.publicInputs.constants.anchorBlockHeader.globalVariables.timestamp),
+            result: undefined,
+            gasUsed: simulatedTx.gasUsed
+        };
+    }
+    /**
+   * Simulate a deployment and profile the gate count for each function in the transaction.
+   * @param options - Same options as `send`, plus extra profiling options.
+   *
+   * @returns An object containing the function return value and profile result.
+   */ async profile(options) {
+        this.lockDeployer(options.from);
+        const executionPayload = await this.request(options);
+        return await this.wallet.profileTx(executionPayload, this.convertDeployOptionsToProfileOptions(options));
+    }
+    /** Returns the deployed contract address. */ async getAddress() {
+        return (await this.getInstance()).address;
+    }
+    /** Returns the partial address for this deployment. */ async getPartialAddress() {
+        return computePartialAddress(await this.getInstance());
+    }
+    /**
+   * Returns the cached resolved instance synchronously, or throws if no instance has been computed yet.
+   * Intended for subclasses that run inside a code path where `getInstance()` is guaranteed to have already
+   * been awaited (e.g. `request()` invoked it). Not part of the public API.
+   */ getCachedInstanceOrThrow() {
+        if (!this.#resolvedInstance) {
+            throw new Error('Contract instance has not been computed yet. Call getInstance() first.');
+        }
+        return this.#resolvedInstance;
+    }
+    /**
+   * Augments this DeployMethod with additional metadata, such as authWitnesses and capsules. The
+   * deployer lock is preserved: a Pending that has not yet been locked stays Pending; a Pending
+   * that has already locked, along with Owned and Universal, returns the matching locked flavor
+   * so the cloned method deploys at the same address as `this`.
+   * @param options - An object containing the metadata to add to the interaction
+   * @returns A new DeployMethod with the added metadata, but calling the same original function in the same manner
+   */ with({ authWitnesses = [], capsules = [], extraHashedArgs = [] }) {
+        return DeployMethod.create(this.wallet, {
+            artifact: this.artifact,
+            postDeployCtor: this.postDeployCtor,
+            args: this.args,
+            constructorNameOrArtifact: this.constructorArtifact?.name
+        }, this.cloneInstantiation(), {
+            authWitnesses: this.authWitnesses.concat(authWitnesses),
+            capsules: this.capsules.concat(capsules),
+            extraHashedArgs: this.extraHashedArgs.concat(extraHashedArgs)
+        });
+    }
+}
+/**
+ * Deploy method whose deployer is fixed at construction to a concrete {@link AztecAddress}. The
+ * deployer is mixed into the address preimage, so the contract address is fully determined.
+ *
+ * Sending from a different account throws — letting it through would silently produce a deployed
+ * address different from the one `getAddress()` reported.
+ */ export class BoundDeployMethod extends DeployMethod {
+    /** The address baked into the address preimage. Read-only — set at construction. */ deployer;
+    constructor(wallet, contract, instantiation, payload = {}){
+        // `BoundInstantiationOptions` requires a `deployer` and forbids `universalDeploy` at the type
+        // level. We still reject `AztecAddress.ZERO` here because the type system can't model it.
+        if (instantiation.deployer.equals(AztecAddress.ZERO)) {
+            throw new Error('BoundDeployMethod requires a non-zero `deployer`; use `UniversalDeployMethod` (`{ universalDeploy: true }`) for universal deploys.');
+        }
+        super(wallet, contract, instantiation.salt, instantiation.publicKeys, instantiation.immutablesHash, payload);
+        this.deployer = instantiation.deployer;
+    }
+    /** Returns the locked deployer baked into the address preimage. */ getDeployerAddress() {
+        return this.deployer;
+    }
+    /**
+   * Throws unless `from` matches the locked deployer; the deployer is part of the address.
+   * @param from - The send-time `from` value (`AztecAddress`, `NO_FROM`, or `undefined`).
+   */ lockDeployer(from) {
+        if (from === undefined || from === NO_FROM || !this.deployer.equals(from)) {
+            const sender = from === undefined ? '<unspecified>' : from === NO_FROM ? 'NO_FROM' : from.toString();
+            throw new Error(`Deployer for this DeployMethod is locked to ${this.deployer.toString()}; cannot send from ${sender} ` + `because that would imply a different deployer than the one used to derive the address. ` + `Pass \`from: ${this.deployer.toString()}\` to send from the locked deployer, or reconstruct the ` + `deploy with a different \`deployer\` if you need a different sender.`);
+        }
+    }
+    /** Re-emits this method's `DeployInstantiationOptions` for `with(...)` to consume. */ cloneInstantiation() {
+        return {
+            salt: this.salt,
+            publicKeys: this.publicKeys,
+            immutablesHash: this.immutablesHash,
+            deployer: this.deployer
+        };
+    }
+}
+/**
+ * Deploy method whose deployer is fixed at construction to {@link AztecAddress.ZERO} (universal
+ * deploy). The address does not depend on the sender, so any account may sign the deploy tx.
+ */ export class UniversalDeployMethod extends DeployMethod {
+    constructor(wallet, contract, instantiation, payload = {}){
+        // `UniversalInstantiationOptions` forbids `deployer` and requires `universalDeploy: true` at
+        // the type level — no runtime check is needed.
+        super(wallet, contract, instantiation.salt, instantiation.publicKeys, instantiation.immutablesHash, payload);
+    }
+    /** Universal deploys are anchored at `AztecAddress.ZERO`; the sender does not enter the preimage. */ getDeployerAddress() {
+        return AztecAddress.ZERO;
+    }
+    /**
+   * Universal deploys accept any sender, including `NO_FROM` / `undefined`.
+   * @param _from - Ignored.
+   */ lockDeployer(_from) {
+    // No-op.
+    }
+    /** Re-emits this method's `DeployInstantiationOptions` for `with(...)` to consume. */ cloneInstantiation() {
+        return {
+            salt: this.salt,
+            publicKeys: this.publicKeys,
+            immutablesHash: this.immutablesHash,
+            universalDeploy: true
+        };
+    }
+}
+/**
+ * Deploy method whose deployer is not yet decided. The first `send` / `simulate` / `profile` call
+ * promotes this into an {@link BoundDeployMethod} or {@link UniversalDeployMethod} (depending on
+ * whether `options.from` is an address or `NO_FROM` / `undefined`); subsequent calls reuse that
+ * promotion and reject mismatching `from` values.
+ *
+ * Reading the address (`getInstance` / `getAddress` / `getPartialAddress`) or building a payload
+ * (`request`) before the promotion happens throws — the address would otherwise be ambiguous and
+ * could differ from what `send()` ends up deploying.
+ */ export class PendingDeployMethod extends DeployMethod {
+    /**
+   * The locked sibling created on the first send-side call. Once set, all flavor-specific
+   * decisions (sender compatibility, address derivation, clone shape) delegate to it, so a second
+   * call with a mismatched `from` is rejected by `BoundDeployMethod.lockDeployer`.
+   */ #locked;
+    constructor(wallet, contract, instantiation = {}, payload = {}){
+        super(wallet, contract, instantiation.salt, instantiation.publicKeys, instantiation.immutablesHash, payload);
+    }
+    /**
+   * Returns the locked deployer once it has happened. Throws while still pending — the
+   * address would otherwise differ from what `send()` ends up deploying.
+   */ getDeployerAddress() {
+        if (!this.#locked) {
+            throw new Error('Cannot resolve contract address: deployer is not yet locked. Pass `deployer: <address>` ' + 'or `universalDeploy: true` as the instantiation option when constructing the deploy ' + '(e.g. `MyContract.deploy(wallet, ...args, { deployer: alice })`), or call `.send` / ' + '`.simulate` / `.profile` first to lock the deployer from the sender. ');
+        }
+        return this.#locked.getDeployerAddress();
+    }
+    /**
+   * On the first call, promotes this pending method into a locked sibling and remembers it. On
+   * subsequent calls, defers to the locked sibling — so a mismatched `from` is rejected by the
+   * sibling's own policy, not a duplicate one here.
+   * @param from - The send-time `from` value (`AztecAddress`, `NO_FROM`, or `undefined`).
+   */ lockDeployer(from) {
+        if (!this.#locked) {
+            this.#locked = this.#promoteFrom(from);
+            return;
+        }
+        this.#locked.lockDeployer(from);
+    }
+    /** Re-emits this method's `DeployInstantiationOptions` for `with(...)` to consume. */ cloneInstantiation() {
+        if (!this.#locked) {
+            return {
+                salt: this.salt,
+                publicKeys: this.publicKeys,
+                immutablesHash: this.immutablesHash
+            };
+        }
+        return this.#locked.cloneInstantiation();
+    }
+    /**
+   * Builds the locked sibling implied by a send-time `from`: an `AztecAddress` becomes
+   * {@link BoundDeployMethod}; `NO_FROM` / `undefined` becomes {@link UniversalDeployMethod}.
+   * @param from - The send-time `from` value.
+   */ #promoteFrom(from) {
+        const { wallet, artifact, postDeployCtor, args, salt, publicKeys, immutablesHash, authWitnesses, capsules, extraHashedArgs } = this;
+        const contract = {
+            artifact,
+            postDeployCtor,
+            args,
+            constructorNameOrArtifact: this.constructorArtifact?.name
+        };
+        const payload = {
+            authWitnesses,
+            capsules,
+            extraHashedArgs
+        };
+        if (from === undefined || from === NO_FROM) {
+            return new UniversalDeployMethod(wallet, contract, {
+                salt,
+                publicKeys,
+                immutablesHash,
+                universalDeploy: true
+            }, payload);
+        }
+        return new BoundDeployMethod(wallet, contract, {
+            salt,
+            publicKeys,
+            immutablesHash,
+            deployer: from
+        }, payload);
+    }
+}

package/dest/contract/fastforward_contract_update.d.ts

@@ -0,0 +1,25 @@
+import { Fr } from '@aztec-labs/foundation/curves/bn254';
+import type { AztecAddress } from '@aztec-labs/stdlib/aztec-address';
+import type { AztecNode } from '@aztec-labs/stdlib/interfaces/client';
+import { SimulationOverrides } from '@aztec-labs/stdlib/tx';
+/**
+ * Builds `SimulationOverrides` that simulate a deployed instance as if it had already been upgraded to a
+ * new contract class. Mirrors a real onchain upgrade (scheduling the new class and waiting out the delay):
+ *
+ * - `publicStorage` rewrites the `ContractInstanceRegistry`'s delayed-public-mutable storage so the AVM's
+ *   `UpdateCheck` resolves to the new class id.
+ * - `contracts` swaps the deployed instance for one whose `currentContractClassId` is bumped to the new class.
+ *
+ * The new class must already be registered on chain.
+ *
+ * @throws If the instance is not deployed, the class is not registered on chain, or the instance is already on the target class.
+ */
+export declare function fastForwardContractUpdate(args: {
+    /** Address of the deployed instance to upgrade. */
+    instanceAddress: AztecAddress;
+    /** ID of the (already-registered) class to upgrade to. */
+    newClassId: Fr;
+    /** Node used to fetch the existing instance and validate the class is registered. */
+    node: AztecNode;
+}): Promise<SimulationOverrides>;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZmFzdGZvcndhcmRfY29udHJhY3RfdXBkYXRlLmQudHMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvY29udHJhY3QvZmFzdGZvcndhcmRfY29udHJhY3RfdXBkYXRlLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sRUFBRSxFQUFFLEVBQUUsTUFBTSxxQ0FBcUMsQ0FBQztBQUV6RCxPQUFPLEtBQUssRUFBRSxZQUFZLEVBQUUsTUFBTSxrQ0FBa0MsQ0FBQztBQU1yRSxPQUFPLEtBQUssRUFBRSxTQUFTLEVBQUUsTUFBTSxzQ0FBc0MsQ0FBQztBQUN0RSxPQUFPLEVBQUUsbUJBQW1CLEVBQUUsTUFBTSx1QkFBdUIsQ0FBQztBQUU1RDs7Ozs7Ozs7Ozs7R0FXRztBQUNILHdCQUFzQix5QkFBeUIsQ0FBQyxJQUFJLEVBQUU7SUFDcEQsbURBQW1EO0lBQ25ELGVBQWUsRUFBRSxZQUFZLENBQUM7SUFDOUIsMERBQTBEO0lBQzFELFVBQVUsRUFBRSxFQUFFLENBQUM7SUFDZixxRkFBcUY7SUFDckYsSUFBSSxFQUFFLFNBQVMsQ0FBQztDQUNqQixHQUFHLE9BQU8sQ0FBQyxtQkFBbUIsQ0FBQyxDQXdDL0IifQ==

package/dest/contract/fastforward_contract_update.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fastforward_contract_update.d.ts","sourceRoot":"","sources":["../../src/contract/fastforward_contract_update.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,EAAE,EAAE,MAAM,qCAAqC,CAAC;AAEzD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kCAAkC,CAAC;AAMrE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sCAAsC,CAAC;AACtE,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAE5D;;;;;;;;;;;GAWG;AACH,wBAAsB,yBAAyB,CAAC,IAAI,EAAE;IACpD,mDAAmD;IACnD,eAAe,EAAE,YAAY,CAAC;IAC9B,0DAA0D;IAC1D,UAAU,EAAE,EAAE,CAAC;IACf,qFAAqF;IACrF,IAAI,EAAE,SAAS,CAAC;CACjB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAwC/B"}

package/dest/contract/fastforward_contract_update.js

@@ -0,0 +1,57 @@
+import { Fr } from '@aztec-labs/foundation/curves/bn254';
+import { ProtocolContractAddress } from '@aztec-labs/protocol-contracts';
+import { DelayedPublicMutableValuesWithHash, ScheduledDelayChange, ScheduledValueChange } from '@aztec-labs/stdlib/delayed-public-mutable';
+import { SimulationOverrides } from '@aztec-labs/stdlib/tx';
+/**
+ * Builds `SimulationOverrides` that simulate a deployed instance as if it had already been upgraded to a
+ * new contract class. Mirrors a real onchain upgrade (scheduling the new class and waiting out the delay):
+ *
+ * - `publicStorage` rewrites the `ContractInstanceRegistry`'s delayed-public-mutable storage so the AVM's
+ *   `UpdateCheck` resolves to the new class id.
+ * - `contracts` swaps the deployed instance for one whose `currentContractClassId` is bumped to the new class.
+ *
+ * The new class must already be registered on chain.
+ *
+ * @throws If the instance is not deployed, the class is not registered on chain, or the instance is already on the target class.
+ */ export async function fastForwardContractUpdate(args) {
+    const { instanceAddress, newClassId, node } = args;
+    const instance = await node.getContract(instanceAddress);
+    if (!instance) {
+        throw new Error(`Instance not deployed at ${instanceAddress}. Deploy it before fast-forwarding an update.`);
+    }
+    const klass = await node.getContractClass(newClassId);
+    if (!klass) {
+        throw new Error(`Contract class ${newClassId} is not registered on chain. Publish it before fast-forwarding to it.`);
+    }
+    if (instance.currentContractClassId.equals(newClassId)) {
+        throw new Error(`Instance ${instanceAddress} is already on class ${newClassId}. Nothing to fast-forward.`);
+    }
+    // Build the SVC the same way `ContractInstanceRegistry::update` would have, but with a timestamp_of_change
+    // safely in the past so the AVM's UpdateCheck resolves to the post-upgrade class id at any sim timestamp.
+    const svc = new ScheduledValueChange(/*previous=*/ [
+        new Fr(0)
+    ], /*post=*/ [
+        newClassId
+    ], /*timestampOfChange=*/ 1n);
+    const sdc = ScheduledDelayChange.empty();
+    const dpmv = new DelayedPublicMutableValuesWithHash(svc, sdc);
+    const { delayedPublicMutableSlot } = await DelayedPublicMutableValuesWithHash.getContractUpdateSlots(instanceAddress);
+    const fields = await dpmv.toFields();
+    const publicStorage = fields.map((value, i)=>({
+            contract: ProtocolContractAddress.ContractInstanceRegistry,
+            slot: delayedPublicMutableSlot.add(new Fr(i)),
+            value
+        }));
+    const upgradedInstance = {
+        ...instance,
+        currentContractClassId: newClassId
+    };
+    return new SimulationOverrides({
+        publicStorage,
+        contracts: {
+            [instanceAddress.toString()]: {
+                instance: upgradedInstance
+            }
+        }
+    });
+}