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

package/src/contract/fastforward_contract_update.ts

@@ -0,0 +1,71 @@
+import { Fr } from '@aztec-labs/foundation/curves/bn254';
+import { ProtocolContractAddress } from '@aztec-labs/protocol-contracts';
+import type { AztecAddress } from '@aztec-labs/stdlib/aztec-address';
+import {
+  DelayedPublicMutableValuesWithHash,
+  ScheduledDelayChange,
+  ScheduledValueChange,
+} from '@aztec-labs/stdlib/delayed-public-mutable';
+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 async 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> {
+  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 } },
+  });
+}

package/src/contract/interaction_options.ts

@@ -0,0 +1,301 @@
+import type { Fr } from '@aztec-labs/foundation/curves/bn254';
+import type { FieldsOf } from '@aztec-labs/foundation/types';
+import type { AuthWitness } from '@aztec-labs/stdlib/auth-witness';
+import { AztecAddress } from '@aztec-labs/stdlib/aztec-address';
+import type { GasSettings, GasUsed, ManaUsageEstimate } from '@aztec-labs/stdlib/gas';
+import {
+  type Capsule,
+  OFFCHAIN_MESSAGE_IDENTIFIER,
+  type OffchainEffect,
+  type SimulationOverrides,
+  type SimulationStats,
+  type TxHash,
+  type TxReceipt,
+} from '@aztec-labs/stdlib/tx';
+
+import type { FeePaymentMethod } from '../fee/fee_payment_method.js';
+import type { ProfileOptions, SendOptions, SimulateOptions } from '../wallet/index.js';
+import type { WaitOpts } from './wait_opts.js';
+
+/**
+ * Interactions allow configuring a custom fee payment method that gets bundled with the transaction before
+ * sending it to the wallet
+ */
+export type FeePaymentMethodOption = {
+  /** Fee payment method to embed in the interaction */
+  paymentMethod?: FeePaymentMethod;
+};
+
+/**
+ * User-defined partial gas settings for the interaction. This type is completely optional since
+ * the wallet will fill in the missing options
+ */
+export type GasSettingsOption = {
+  /** The gas settings */
+  gasSettings?: Partial<FieldsOf<GasSettings>>;
+  /**
+   * Assumed network congestion level for fee prediction. Controls how aggressively the wallet
+   * estimates future fees: None assumes empty blocks, Target assumes steady-state usage,
+   * and Limit assumes blocks at maximum capacity. Higher estimates produce higher fee predictions,
+   * reducing the risk of underpriced transactions during congestion spikes.
+   * Defaults to Limit (worst case) when not specified.
+   */
+  congestionEstimate?: ManaUsageEstimate;
+};
+
+/** Fee options as set by a user. */
+export type InteractionFeeOptions = GasSettingsOption & FeePaymentMethodOption;
+
+/**
+ * Represents the options to configure a request from a contract interaction.
+ * Allows specifying additional auth witnesses and capsules to use during execution
+ */
+export type RequestInteractionOptions = {
+  /** Extra authwits to use during execution */
+  authWitnesses?: AuthWitness[];
+  /** Extra capsules to use during execution */
+  capsules?: Capsule[];
+  /** Fee payment method to embed in the interaction request */
+  fee?: FeePaymentMethodOption;
+};
+
+/**
+ * Constant for explicitly not waiting for transaction confirmation.
+ * We use this instead of false to avoid confusion with falsy checks.
+ */
+export const NO_WAIT = 'NO_WAIT' as const;
+
+/**
+ * Type for the NO_WAIT constant.
+ */
+export type NoWait = typeof NO_WAIT;
+
+/**
+ * Constant for explicitly opting out of account contract mediation.
+ * When used as the `from` parameter, the wallet executes the payload directly
+ * via the DefaultEntrypoint without wrapping it in an account contract entrypoint.
+ * The app is responsible for assembling the complete execution payload, including
+ * any entrypoint wrapping (e.g. multicall) if needed. This will result in the
+ * first call of the chain receiving msg_sender as Option::none
+ */
+export const NO_FROM = 'NO_FROM' as const;
+
+/**
+ * Type for the NO_FROM constant.
+ */
+export type NoFrom = typeof NO_FROM;
+
+/**
+ * Type for wait options in interactions.
+ * - NO_WAIT symbol: Don't wait for confirmation, return TxHash immediately
+ * - WaitOpts object: Wait with custom options and return receipt/result
+ * - undefined: Wait with default options and return receipt/result
+ */
+export type InteractionWaitOptions = NoWait | WaitOpts | undefined;
+
+/**
+ * Base options for calling a (constrained) function in a contract, without wait parameter.
+ */
+export type SendInteractionOptionsWithoutWait = RequestInteractionOptions & {
+  /** The sender's Aztec address, or NO_FROM to execute without account contract mediation. */
+  from: AztecAddress | NoFrom;
+  /** The fee options for the transaction. */
+  fee?: InteractionFeeOptions;
+  /**
+   * Additional addresses whose private state and keys should be accessible during execution,
+   * beyond the sender's. Required when the transaction needs to access private state or keys
+   * belonging to an address other than `from`, e.g. withdrawing from an escrow that holds
+   * its own private notes.
+   */
+  additionalScopes?: AztecAddress[];
+  /**
+   * Overrides the sender address used to derive discovery tags for private messages (notes, events, logs).
+   * Recipients use these tags to find messages addressed to them.
+   *
+   * Defaults to `from`. Typically set when `from === NO_FROM`, since there is no account address to derive tags from.
+   */
+  sendMessagesAs?: AztecAddress;
+};
+
+/**
+ * Represents options for calling a (constrained) function in a contract.
+ */
+export type SendInteractionOptions<W extends InteractionWaitOptions = undefined> = SendInteractionOptionsWithoutWait & {
+  /**
+   * Whether to wait for the transaction to be mined.
+   * - undefined (default): wait with default options and return TxReceipt
+   * - WaitOpts object: wait with custom options and return TxReceipt
+   * - NO_WAIT: return txHash immediately without waiting
+   */
+  wait?: W;
+};
+
+/**
+ * Represents the options for simulating a contract function interaction.
+ * Allows specifying the address from which the method should be called.
+ * Disregarded for simulation of public functions
+ */
+export type SimulateInteractionOptions = Omit<SendInteractionOptions, 'fee'> & {
+  /** The fee options for the transaction. */
+  fee?: InteractionFeeOptions;
+  /** Simulate without checking for the validity of the resulting transaction, e.g. whether it emits any existing nullifiers. */
+  skipTxValidation?: boolean;
+  /** Whether to ensure the fee payer is not empty and has enough balance to pay for the fee. */
+  skipFeeEnforcement?: boolean;
+  /** Whether to include metadata such as performance statistics (e.g. timing information of the different circuits and oracles) and simulated gas usage
+   * in the simulation result, in addition to the return value and offchain effects */
+  includeMetadata?: boolean;
+  /** Pre-simulation overrides applied to the ephemeral fork and contract DB (publicStorage writes, contract instance overrides). */
+  overrides?: SimulationOverrides;
+};
+
+/**
+ * Represents the options for profiling an interaction.
+ */
+export type ProfileInteractionOptions = SimulateInteractionOptions & {
+  /** Whether to return gates information or the bytecode/witnesses. */
+  profileMode: 'gates' | 'execution-steps' | 'full';
+  /** Whether to generate a Chonk proof or not */
+  skipProofGeneration?: boolean;
+};
+
+/** A message emitted during execution or proving, to be delivered offchain. */
+export type OffchainMessage = {
+  /** The intended recipient of the message. */
+  recipient: AztecAddress;
+  /** The message payload (typically encrypted). */
+  payload: Fr[];
+  /** The contract that emitted the message. */
+  contractAddress: AztecAddress;
+  /** Anchor block timestamp at message emission. */
+  anchorBlockTimestamp: bigint;
+};
+
+/** Groups all unproven outputs from private execution that are returned to the client. */
+export type OffchainOutput = {
+  /** Raw offchain effects emitted during execution. */
+  offchainEffects: OffchainEffect[];
+  /** Messages emitted during execution, to be delivered offchain. */
+  offchainMessages: OffchainMessage[];
+};
+
+/**
+ * Splits an array of offchain effects into decoded offchain messages and remaining effects.
+ * Effects whose data starts with `OFFCHAIN_MESSAGE_IDENTIFIER` are parsed as messages and removed
+ * from the effects array.
+ */
+export function extractOffchainOutput(effects: OffchainEffect[], anchorBlockTimestamp: bigint): OffchainOutput {
+  const offchainEffects: OffchainEffect[] = [];
+  const offchainMessages: OffchainMessage[] = [];
+
+  for (const effect of effects) {
+    if (effect.data.length >= 2 && effect.data[0].equals(OFFCHAIN_MESSAGE_IDENTIFIER)) {
+      offchainMessages.push({
+        recipient: AztecAddress.fromFieldUnsafe(effect.data[1]),
+        payload: effect.data.slice(2),
+        contractAddress: effect.contractAddress,
+        anchorBlockTimestamp,
+      });
+    } else {
+      offchainEffects.push(effect);
+    }
+  }
+
+  return { offchainEffects, offchainMessages };
+}
+
+/**
+ * Represents the result of a simulation.
+ * Always includes the return value and offchain output.
+ * When `includeMetadata` is set, also includes stats and the simulated gas usage.
+ */
+export type SimulationResult = {
+  /** Return value of the function */
+  result: any;
+  /** Additional stats about the simulation. Present when `includeMetadata` is set. */
+  stats?: SimulationStats;
+  /**
+   * Raw gas consumed by the simulated transaction. Present when `includeMetadata` is set. Apps that want to
+   * declare explicit gas limits should derive their own from this (e.g. pad `totalGas`) and pass them via the
+   * fee options; otherwise the wallet fills in the network's per-tx admission limits automatically.
+   */
+  gasUsed?: GasUsed;
+} & OffchainOutput;
+
+/** Result of sendTx when not waiting for mining. */
+export type TxSendResultImmediate = {
+  /** The hash of the sent transaction. */
+  txHash: TxHash;
+} & OffchainOutput;
+
+/** Result of sendTx when waiting for mining. */
+export type TxSendResultMined<TReturn = TxReceipt> = {
+  /** The transaction receipt. */
+  receipt: TReturn;
+} & OffchainOutput;
+
+/**
+ * Represents the result type of sending a transaction.
+ * If `wait` is NO_WAIT, returns TxSendResultImmediate.
+ * Otherwise returns TxSendResultMined.
+ */
+export type SendReturn<T extends InteractionWaitOptions, TReturn = TxReceipt> = T extends NoWait
+  ? TxSendResultImmediate
+  : TxSendResultMined<TReturn>;
+
+/**
+ * Transforms and cleans up the higher level SendInteractionOptions defined by the interaction into
+ * SendOptions, which are the ones that can be serialized and forwarded to the wallet
+ * @param options - The send interaction options with optional wait parameter
+ * @returns The send options to forward to the wallet
+ */
+export function toSendOptions<W extends InteractionWaitOptions = undefined>(
+  options: SendInteractionOptions<W>,
+): SendOptions<W> {
+  return {
+    ...options,
+    fee: {
+      // If a payment method that includes gas settings was used,
+      // try to reuse as much as possible while still allowing
+      // manual override. CAREFUL: this can cause mismatches during proving
+      gasSettings: {
+        ...options.fee?.paymentMethod?.getGasSettings(),
+        ...options.fee?.gasSettings,
+      },
+      congestionEstimate: options.fee?.congestionEstimate,
+    },
+    wait: options.wait, // Pass through wait option
+  };
+}
+
+/**
+ * Transforms and cleans up the higher level SimulateInteractionOptions defined by the interaction into
+ * SimulateOptions, which are the ones that can be serialized and forwarded to the wallet
+ */
+export function toSimulateOptions(options: SimulateInteractionOptions): SimulateOptions {
+  return {
+    ...options,
+    fee: {
+      // If a payment method that includes gas settings was used,
+      // try to reuse as much as possible while still allowing
+      // manual override. CAREFUL: this can cause mismatches during proving
+      gasSettings: {
+        ...options.fee?.paymentMethod?.getGasSettings(),
+        ...options.fee?.gasSettings,
+      },
+      congestionEstimate: options.fee?.congestionEstimate,
+    },
+  };
+}
+
+/**
+ * Transforms and cleans up the higher level ProfileInteractionOptions defined by the interaction into
+ * ProfileOptions, which are the ones that can be serialized and forwarded to the wallet
+ */
+export function toProfileOptions(options: ProfileInteractionOptions): ProfileOptions {
+  return {
+    ...toSimulateOptions(options),
+    profileMode: options.profileMode,
+    skipProofGeneration: options.skipProofGeneration,
+  };
+}

package/src/contract/protocol_contracts/contract-class-registry.ts

@@ -0,0 +1,104 @@
+/* Autogenerated file, do not edit! */
+/* eslint-disable */
+import { ProtocolContractAddress } from '@aztec-labs/protocol-contracts';
+import { FunctionType } from '@aztec-labs/stdlib/abi';
+
+import type { ContractArtifact } from '../../api/abi.js';
+import { PublicKeys } from '../../api/keys.js';
+import type {
+  AztecAddressLike,
+  EthAddressLike,
+  FieldLike,
+  FunctionSelectorLike,
+  OptionLike,
+  WrappedFieldLike,
+} from '../../utils/abi_types.js';
+import type { Wallet } from '../../wallet/wallet.js';
+import { ContractBase, type ContractMethod } from '../contract_base.js';
+import { ContractFunctionInteraction } from '../contract_function_interaction.js';
+
+const ContractClassRegistryContractArtifact: ContractArtifact = {
+  name: 'ContractClassRegistry',
+  aztecVersion: '6.0.0-nightly.20260826',
+  functions: [
+    {
+      ...{
+        functionType: FunctionType.PRIVATE,
+        name: 'publish',
+        isOnlySelf: false,
+        isStatic: false,
+        isInitializer: false,
+        parameters: [
+          { name: 'artifact_hash', type: { kind: 'field' }, visibility: 'private' },
+          { name: 'private_functions_root', type: { kind: 'field' }, visibility: 'private' },
+          { name: 'public_bytecode_commitment', type: { kind: 'field' }, visibility: 'private' },
+        ],
+        errorTypes: {
+          '10965409165809799877': {
+            error_kind: 'string',
+            string: 'Given in_len to absorb is larger than the input array len',
+          },
+          '12469291177396340830': { error_kind: 'string', string: 'call to assert_max_bit_size' },
+          '14990209321349310352': { error_kind: 'string', string: 'attempt to add with overflow' },
+          '15669273164684982983': { error_kind: 'string', string: 'num_permutations is greater than MAX_PERMUTATIONS' },
+          '15835548349546956319': { error_kind: 'string', string: 'Field failed to decompose into specified 32 limbs' },
+          '16431471497789672479': { error_kind: 'string', string: 'Index out of bounds' },
+          '16450579948625159707': { error_kind: 'string', string: 'Sponge must be in cache_size=1' },
+          '17655676068928457687': { error_kind: 'string', string: 'Reader did not read all data' },
+          '1998584279744703196': { error_kind: 'string', string: 'attempt to subtract with overflow' },
+          '361444214588792908': { error_kind: 'string', string: 'attempt to multiply with overflow' },
+          '922421554006670918': { error_kind: 'string', string: 'num_items is greater than MAX_ITEMS' },
+          '9475115977882098926': { error_kind: 'string', string: 'Extra bytes in the last field of the bytecode' },
+        },
+      },
+      bytecode: Buffer.from([]),
+      debugSymbols: '',
+    },
+    {
+      ...{
+        functionType: FunctionType.PUBLIC,
+        name: 'public_dispatch',
+        isOnlySelf: false,
+        isStatic: false,
+        isInitializer: false,
+        parameters: [{ name: 'selector', type: { kind: 'field' }, visibility: 'private' }],
+        errorTypes: { '1335198680857977525': { error_kind: 'string', string: 'No public functions' } },
+      },
+      bytecode: Buffer.from([]),
+      debugSymbols: '',
+    },
+  ],
+  nonDispatchPublicFunctions: [],
+  outputs: { structs: {}, globals: {} },
+  storageLayout: {},
+  fileMap: {},
+};
+
+export class ContractClassRegistryContract extends ContractBase {
+  private constructor(wallet: Wallet) {
+    super(ProtocolContractAddress.ContractClassRegistry, ContractClassRegistryContractArtifact, wallet);
+  }
+
+  /** Returns an interface to the canonical ContractClassRegistryContract instance, bound to the given wallet. */
+  public static withWallet(wallet: Wallet): ContractClassRegistryContract {
+    return new ContractClassRegistryContract(wallet);
+  }
+
+  /** @deprecated Use `withWallet` instead. */
+  public static at(wallet: Wallet): ContractClassRegistryContract {
+    return ContractClassRegistryContract.withWallet(wallet);
+  }
+
+  declare public methods: {
+    /** public_dispatch(selector: field) */
+    public_dispatch: ((selector: FieldLike) => ContractFunctionInteraction) & Pick<ContractMethod, 'selector'>;
+
+    /** publish(artifact_hash: field, private_functions_root: field, public_bytecode_commitment: field) */
+    publish: ((
+      artifact_hash: FieldLike,
+      private_functions_root: FieldLike,
+      public_bytecode_commitment: FieldLike,
+    ) => ContractFunctionInteraction) &
+      Pick<ContractMethod, 'selector'>;
+  };
+}