chore: backport DeployMethod refactor (#22985) to v4-next (#23029)

## Summary

Backport of
[#22985](#22985)
(`fix: better DeployMethod`) to `backport-to-v4-next-staging`.

The original PR refactors `DeployMethod` so that all address-affecting
parameters (`salt`, `deployer`, `universalDeploy`, `publicKeys`) are
locked in at construction time via a new `DeployInstantiationOptions`
argument, and removes the silent salt-cache poisoning bug where the
address could change between calls. See the migration notes added under
`## TBD` for the full API change.

## Commits

This backport preserves the standard 3-commit history so reviewers can
see exactly what conflicted and how it was resolved:

1. **`chore: cherry-pick #22985 ... with conflicts`** — raw `git
cherry-pick` result with conflict markers in place. Does not compile.
2. **`fix: resolve cherry-pick conflicts`** — resolution. Notable
choices:
- `migration_notes.md`: only the new DeployMethod note was added. Other
entries that came in via the cherry-pick (`getBlock` / `getCheckpoint`,
`feeAssetPriceModifier`, Domain separators, aztec-up table reformatting)
belong to PRs that have not been backported, so they were dropped to
avoid bringing in unrelated changes.
- `txe_oracles.nr`, `constants.nr`, `constants_tests.nr`: dropped
formatting-only diffs that depended on constants/types not present on
v4-next (`MAX_PRIVATE_LOGS_PER_TX`, `PRIVATE_LOG_SIZE_IN_FIELDS`,
`DOM_SEP__HANDSHAKE_SECRET_HASH`, `DOM_SEP__MERKLE_HASH`, etc.).
- `bot/src/factory.ts`: dropped the new
`setupTokenWithOptionalEarlyRefuel` /
`setupTokenContractWithOptionalEarlyRefuel` / `getTokenInstance` helpers
(introduced by an unrelated PR) and applied the new
`DeployInstantiationOptions` API to the existing `setupToken` flow.
- `e2e/composed/ha/e2e_ha_full.test.ts`: dropped the `should reload
keystore via admin API and keep building blocks after swapping
attesters` test that does not exist on v4-next.
- `docs/examples/ts/aave_bridge`, `docs/examples/ts/example_swap`: kept
deleted (modify/delete conflict — these examples don't exist on
v4-next).
- `docs/examples/ts/token_bridge/index.ts`: kept
`node.getProvenBlockNumber()` — the new `getBlockNumber('proven')` is
from a different PR.
- End-to-end tests, `aztec.js/src/api/contract.ts`, `bot`, etc.: adopted
the new `DeployInstantiationOptions` API; kept v4-next-only
`DeployTxReceipt` / `DeployWaitOptions` exports.
3. **`fix: restore DeployInteractionWaitOptions for v4-next
returnReceipt API`** — v4-next still supports `wait: { returnReceipt:
true }` (a feature added on v4-next that does not exist upstream). The
upstream PR removed `DeployInteractionWaitOptions` and tightened
`DeployOptions<W extends InteractionWaitOptions>`, which broke
type-checking for the existing `returnReceipt` callers. This commit
restores `DeployInteractionWaitOptions = NoWait | DeployWaitOptions |
undefined` and rewires `DeployOptions` / `DeployReturn` / `send` to use
it, so the v4-next-only `returnReceipt: true` callers keep
type-checking.

## Test plan
- [ ] CI green on this branch
- [ ] e2e_deploy_contract tests pass

ClaudeBox log: https://claudebox.work/s/2e03d384f1f73fd0?run=1

Author: Thunkar

boxes/boxes/react/src/hooks/useContract.tsx

@@ -15,13 +15,11 @@ export function useContract() {
     setWait(true);
     const wallet = await deployerEnv.getWallet();
     const defaultAccountAddress = deployerEnv.getDefaultAccountAddress();
-    const salt = Fr.random();
 
     const { BoxReactContract } = await import('../../artifacts/BoxReact');
 
     const deploymentPromise = BoxReactContract.deploy(wallet, Fr.random(), defaultAccountAddress).send({
       from: defaultAccountAddress,
-      contractAddressSalt: salt,
     });
 
     const { contract } = await toast.promise(deploymentPromise, {

boxes/boxes/vanilla/scripts/deploy.ts

@@ -72,12 +72,10 @@ async function deployContract(wallet: Wallet, deployer: AztecAddress) {
 
   const sponsoredPFCContract = await getSponsoredPFCContract();
 
-  const { contract } = await PrivateVotingContract.deploy(
-    wallet,
-    deployer
-  ).send({
+  const { contract } = await PrivateVotingContract.deploy(wallet, deployer, {
+    salt,
+  }).send({
     from: deployer,
-    contractAddressSalt: salt,
     fee: {
       paymentMethod: new SponsoredFeePaymentMethod(
         sponsoredPFCContract.address

boxes/boxes/vite/src/hooks/useContract.tsx

@@ -15,13 +15,11 @@ export function useContract() {
     setWait(true);
     const wallet = await deployerEnv.getWallet();
     const defaultAccountAddress = deployerEnv.getDefaultAccountAddress();
-    const salt = Fr.random();
 
     const { BoxReactContract } = await import('../../artifacts/BoxReact');
 
     const deploymentPromise = BoxReactContract.deploy(wallet, Fr.random(), defaultAccountAddress).send({
       from: defaultAccountAddress,
-      contractAddressSalt: salt,
     });
 
     const { contract } = await toast.promise(deploymentPromise, {

docs/docs-developers/docs/resources/migration_notes.md

@@ -9,6 +9,97 @@ Aztec is in active development. Each version may introduce breaking changes that
 
 ## TBD
 
+### [Aztec.js] `DeployMethod` address-affecting parameters move to construction time
+
+Salt, deployer, and public keys are now passed when the `DeployMethod` is constructed, not on every call to `send` / `simulate` / `request` / `getInstance`. This locks the contract address once it is determined and prevents the silent salt-cache poisoning bug where the address could change between calls.
+
+`contractAddressSalt`, `deployer`, and `universalDeploy` have been removed from `DeployOptions`, `RequestDeployOptions`, and `SimulateDeployOptions`. They now live on a new `DeployInstantiationOptions` argument passed at construction. `deployer` and `universalDeploy` are mutually exclusive; passing both throws. `Contract.deployWithPublicKeys` and the generated `MyContract.deployWithPublicKeys(...)` factories have been removed; pass `publicKeys` via the `instantiation` argument of `deploy(...)` instead. The buggy synchronous `address` and `partialAddress` getters have been removed and replaced with `getAddress()` and `getPartialAddress()` (both `async`).
+
+The compact form keeps working: `MyContract.deploy(wallet, ...args).send({ from: alice })` deploys with `deployer = alice` and `salt = random()`, exactly as before. The deployer is locked the first time `send` / `simulate` / `profile` is called (from `options.from`, with `NO_FROM` or undefined → universal) and cannot change after that:
+
+- Subsequent `send` / `simulate` / `profile` calls with a `from` that would imply a different deployer throw, instead of silently producing a different address.
+- A lock to universal (`AztecAddress.ZERO`) is the only one compatible with any sender, since the universal address does not depend on `from`.
+- A lock to a concrete address only accepts that exact `from` on subsequent calls.
+
+**Migration:**
+
+Universal deployment with a fixed salt:
+
+```diff
+- const deploy = MyContract.deploy(wallet, ...args);
+- await deploy.send({
+-   from: alice,
+-   contractAddressSalt: salt,
+-   universalDeploy: true,
+- });
++ const deploy = MyContract.deploy(wallet, ...args, { salt, universalDeploy: true });
++ await deploy.send({ from: alice });
+```
+
+Non-universal deploy where `from` doubles as the deployer:
+
+```diff
+- const deploy = MyContract.deploy(wallet, ...args);
+- await deploy.send({ from: alice, contractAddressSalt: salt });
++ const deploy = MyContract.deploy(wallet, ...args, { salt });
++ await deploy.send({ from: alice });
+```
+
+If you need to read the address before sending, lock the deployer at construction:
+
+```typescript
+const deploy = MyContract.deploy(wallet, ...args, { salt, deployer: alice });
+const address = await deploy.getAddress(); // resolves; deployer was locked at construction
+await deploy.send({ from: alice }); // deploys at the address `getAddress` returned
+```
+
+Universal deploys can be sent by any account, since the universal address does not depend on `from`:
+
+```typescript
+const deploy = MyContract.deploy(wallet, ...args, { universalDeploy: true });
+await deploy.send({ from: bob }); // OK, universal accepts any sender
+```
+
+A lock to a concrete deployer rejects sending from a different account, instead of silently deploying at a different address:
+
+```typescript
+const deploy = MyContract.deploy(wallet, ...args, { deployer: alice });
+await deploy.send({ from: bob }); // throws: deployer is locked to alice
+```
+
+`deployWithPublicKeys` is gone; pass `publicKeys` in the instantiation options instead:
+
+```diff
+- const deploy = MyContract.deployWithPublicKeys(publicKeys, wallet, ...args);
++ const deploy = MyContract.deploy(wallet, ...args, { publicKeys });
+```
+
+`ContractDeployer.deploy(...)` now takes the instantiation argument as its first parameter (pass `{}` to use defaults and rely on lazy locking from `from`):
+
+```diff
+- const cd = new ContractDeployer(artifact, wallet);
+- await cd.deploy(...ctorArgs).send({ from: alice, contractAddressSalt: salt });
++ const cd = new ContractDeployer(artifact, wallet);
++ await cd.deploy(ctorArgs, { salt }).send({ from: alice });
+```
+
+The synchronous `address` / `partialAddress` getters are gone:
+
+```diff
+- const address = deploy.address;                       // sync, possibly undefined
+- const partial = await deploy.partialAddress;          // sync getter wrapping async value
++ const address = await deploy.getAddress();            // requires the deployer to be locked
++ const partial = await deploy.getPartialAddress();     // requires the deployer to be locked
+```
+
+`getInstance()` no longer takes options; use the construction-time instantiation instead:
+
+```diff
+- const instance = await deploy.getInstance({ contractAddressSalt: salt });
++ const deploy = MyContract.deploy(wallet, ...args, { salt, deployer: alice });
++ const instance = await deploy.getInstance();
+```
+
 ### [Aztec.nr] TXE `call_public_incognito` no longer takes a `from` parameter
 
 `TestEnvironment::call_public_incognito` previously accepted a `from` address that was silently ignored (the function always uses a null `msg_sender`). The `from` parameter has been removed.

docs/examples/ts/aztecjs_advanced/index.ts

@@ -16,14 +16,22 @@ import { getPublicEvents } from "@aztec/aztec.js/events";
 import { GasSettings } from "@aztec/stdlib/gas";
 
 // Setup: connect to network
-const node = createAztecNodeClient(process.env.AZTEC_NODE_URL ?? "http://localhost:8080");
+const node = createAztecNodeClient(
+  process.env.AZTEC_NODE_URL ?? "http://localhost:8080",
+);
 await waitForNode(node);
 const wallet = await EmbeddedWallet.create(node, { ephemeral: true });
 
 const testAccounts = await getInitialTestAccountsData();
 const [aliceAddress, bobAddress] = await Promise.all(
   testAccounts.slice(0, 2).map(async (account) => {
-    return (await wallet.createSchnorrAccount(account.secret, account.salt, account.signingKey)).address;
+    return (
+      await wallet.createSchnorrAccount(
+        account.secret,
+        account.salt,
+        account.signingKey,
+      )
+    ).address;
   }),
 );
 
@@ -45,8 +53,13 @@ const sponsoredFPCInstance = await getContractInstanceFromInstantiationParams(
   SponsoredFPCContract.artifact,
   { salt: new Fr(0) },
 );
-await wallet.registerContract(sponsoredFPCInstance, SponsoredFPCContract.artifact);
-const sponsoredPaymentMethod = new SponsoredFeePaymentMethod(sponsoredFPCInstance.address);
+await wallet.registerContract(
+  sponsoredFPCInstance,
+  SponsoredFPCContract.artifact,
+);
+const sponsoredPaymentMethod = new SponsoredFeePaymentMethod(
+  sponsoredFPCInstance.address,
+);
 
 // wallet is from the connection guide; sponsoredPaymentMethod is from the fees guide
 const { contract: sponsoredContract } = await TokenContract.deploy(
@@ -68,9 +81,9 @@ const { contract: saltedContract } = await TokenContract.deploy(
   "SaltedToken",
   "SALT",
   18,
+  { salt: customSalt },
 ).send({
   from: aliceAddress,
-  contractAddressSalt: customSalt,
 });
 // docs:end:deploy_custom_salt
 
@@ -84,8 +97,9 @@ const deployMethod = TokenContract.deploy(
   "PredictedToken",
   "PRED",
   18,
+  { salt: deploymentSalt, deployer: aliceAddress },
 );
-const instance = await deployMethod.getInstance({ contractAddressSalt: deploymentSalt });
+const instance = await deployMethod.getInstance();
 const predictedAddress = instance.address;
 
 console.log(`Contract will deploy at: ${predictedAddress}`);
@@ -235,15 +249,21 @@ console.log(`Derived token at: ${derivedToken.address.toString()}`);
 // docs:start:parallel_deploy
 // Deploy contracts in parallel using Promise.all
 const contracts = await Promise.all([
-  TokenContract.deploy(wallet, aliceAddress, "Token1", "T1", 18).send({
-    from: aliceAddress,
-  }).then(({ contract }) => contract),
-  TokenContract.deploy(wallet, aliceAddress, "Token2", "T2", 18).send({
-    from: aliceAddress,
-  }).then(({ contract }) => contract),
-  TokenContract.deploy(wallet, aliceAddress, "Token3", "T3", 18).send({
-    from: aliceAddress,
-  }).then(({ contract }) => contract),
+  TokenContract.deploy(wallet, aliceAddress, "Token1", "T1", 18)
+    .send({
+      from: aliceAddress,
+    })
+    .then(({ contract }) => contract),
+  TokenContract.deploy(wallet, aliceAddress, "Token2", "T2", 18)
+    .send({
+      from: aliceAddress,
+    })
+    .then(({ contract }) => contract),
+  TokenContract.deploy(wallet, aliceAddress, "Token3", "T3", 18)
+    .send({
+      from: aliceAddress,
+    })
+    .then(({ contract }) => contract),
 ]);
 
 console.log(`Contract 1 at: ${contracts[0].address}`);
@@ -293,8 +313,12 @@ async function pollForTransferEvents() {
 
     for (const { event, metadata } of events) {
       // Process each transfer event
-      console.log(`Transfer: ${event.amount} from ${event.from} to ${event.to}`);
-      console.log(`  in block ${metadata.l2BlockNumber}, tx ${metadata.txHash}`);
+      console.log(
+        `Transfer: ${event.amount} from ${event.from} to ${event.to}`,
+      );
+      console.log(
+        `  in block ${metadata.l2BlockNumber}, tx ${metadata.txHash}`,
+      );
     }
 
     lastProcessedBlock = currentBlock;
@@ -307,7 +331,11 @@ await pollForTransferEvents();
 
 // docs:start:connect_to_contract
 // wallet is from the connection guide; token is the contract deployed in the deploy guide
-const contract = await Contract.at(token.address, TokenContract.artifact, wallet);
+const contract = await Contract.at(
+  token.address,
+  TokenContract.artifact,
+  wallet,
+);
 // docs:end:connect_to_contract
 
 // docs:start:basic_send_transaction
@@ -333,7 +361,10 @@ console.log("DA gas limit:", metaResult.estimatedGas.gasLimits.daGas);
 // docs:end:simulate_with_metadata
 
 // docs:start:read_public_logs
-const publicLogs = await node.getPublicLogs({ fromBlock: 1, toBlock: await node.getBlockNumber() + 1 });
+const publicLogs = await node.getPublicLogs({
+  fromBlock: 1,
+  toBlock: (await node.getBlockNumber()) + 1,
+});
 if (publicLogs.logs.length > 0) {
   const rawFields = publicLogs.logs[0].log.getEmittedFields(); // Fr[]
   console.log("Raw log fields:", rawFields.length);
@@ -385,24 +416,32 @@ const networkFees = await node.getCurrentMinFees();
 const gasSettings = GasSettings.from({
   gasLimits: { daGas: 100_000, l2Gas: 2_000_000 },
   teardownGasLimits: { daGas: 100_000, l2Gas: 2_000_000 },
-  maxFeesPerGas: { feePerDaGas: networkFees.feePerDaGas * 2n, feePerL2Gas: networkFees.feePerL2Gas * 2n },
+  maxFeesPerGas: {
+    feePerDaGas: networkFees.feePerDaGas * 2n,
+    feePerL2Gas: networkFees.feePerL2Gas * 2n,
+  },
   maxPriorityFeesPerGas: { feePerDaGas: 0n, feePerL2Gas: 0n },
 });
 // docs:end:custom_gas_settings
 
 // docs:start:send_with_gas_settings
-const { receipt: gsReceipt } = await token.methods.mint_to_public(aliceAddress, 1n).send({
-  from: aliceAddress,
-  fee: { gasSettings },
-});
+const { receipt: gsReceipt } = await token.methods
+  .mint_to_public(aliceAddress, 1n)
+  .send({
+    from: aliceAddress,
+    fee: { gasSettings },
+  });
 // docs:end:send_with_gas_settings
 
 // docs:start:read_logs_by_filter
 // Get logs for a specific transaction
 const txLogs = await node.getPublicLogs({ txHash: gsReceipt.txHash });
 
 // Get logs for a block range
-const rangeLogs = await node.getPublicLogs({ fromBlock: 1, toBlock: await node.getBlockNumber() + 1 });
+const rangeLogs = await node.getPublicLogs({
+  fromBlock: 1,
+  toBlock: (await node.getBlockNumber()) + 1,
+});
 // docs:end:read_logs_by_filter
 
 // docs:start:auto_gas_estimation
@@ -435,5 +474,4 @@ const { result: privateBalance } = await token.methods
   .simulate({ from: aliceAddress });
 // docs:end:simulate_private_access
 
-
 console.log("All advanced examples completed successfully");

docs/examples/ts/token_bridge/index.ts

@@ -63,7 +63,10 @@ console.log(`NFTPortal: ${portalAddress}\n`);
 // docs:start:deploy_l2_contracts
 console.log("Deploying L2 contracts...\n");
 
-const { contract: l2Nft } = await NFTPunkContract.deploy(aztecWallet, account.address).send({
+const { contract: l2Nft } = await NFTPunkContract.deploy(
+  aztecWallet,
+  account.address,
+).send({
   from: account.address,
 });
 
@@ -201,11 +204,9 @@ async function mine2Blocks(
 ) {
   await NFTPunkContract.deploy(aztecWallet, accountAddress).send({
     from: accountAddress,
-    contractAddressSalt: Fr.random(),
   });
   await NFTPunkContract.deploy(aztecWallet, accountAddress).send({
     from: accountAddress,
-    contractAddressSalt: Fr.random(),
   });
 }
 // docs:end:mine_blocks
@@ -303,7 +304,11 @@ while (provenBlockNumber < exitReceipt.blockNumber!) {
 console.log("Block proven!\n");
 
 // Compute the membership witness using the message hash and the L2 tx hash
-const witness = await computeL2ToL1MembershipWitness(node, msgLeaf, exitReceipt.txHash);
+const witness = await computeL2ToL1MembershipWitness(
+  node,
+  msgLeaf,
+  exitReceipt.txHash,
+);
 const epoch = witness!.epochNumber;
 console.log(`   Epoch for block ${exitReceipt.blockNumber}: ${epoch}`);
 

playground/src/components/contract/components/CreateContractDialog.tsx

@@ -115,17 +115,13 @@ export function CreateContractDialog({
       if (publiclyDeploy) {
         const postDeployCtor = (instance: ContractInstanceWithAddress, wallet: Wallet) =>
           Contract.at(instance.address, contractArtifact, wallet);
-        deployMethod = new DeployMethod(
-          contract.publicKeys,
-          wallet,
-          contractArtifact,
-          postDeployCtor,
-          parameters,
-          initializer?.name,
-        );
+        deployMethod = new DeployMethod(wallet, contractArtifact, postDeployCtor, parameters, initializer?.name, {
+          publicKeys: contract.publicKeys,
+          salt: contract.salt,
+          deployer: from,
+        });
         opts = {
           from,
-          contractAddressSalt: salt,
           fee: { paymentMethod: feePaymentMethod },
         };
         onClose(contract, publiclyDeploy, deployMethod, opts);

yarn-project/aztec.js/src/api/contract.ts

@@ -71,6 +71,7 @@ export { DefaultWaitOpts, type WaitOpts } from '../contract/wait_opts.js';
 export { ContractBase, type ContractMethod, type ContractStorageLayout } from '../contract/contract_base.js';
 export { BatchCall } from '../contract/batch_call.js';
 export {
+  type DeployInstantiationOptions,
   type DeployOptions,
   type DeployResultMined,
   type DeployReturn,