Deploying Contracts

This guide shows you how to deploy compiled contracts to Aztec using the generated TypeScript interfaces.

Overview

Deploying a contract to Aztec involves publishing the contract class (the bytecode) and creating a contract instance at a specific address. The generated TypeScript classes handle this process through an API: you call deploy() with constructor arguments and send() with transaction options to deploy and get the contract instance. The contract address is deterministically computed from the contract class, constructor arguments, salt, and deployer address.

Prerequisites

• Compiled contract artifacts (see How to Compile)
• Connected to a network with a EmbeddedWallet instance and funded accounts
• TypeScript project set up

Generate TypeScript bindings

Compile and generate code

# Compile the contract
aztec compile

# Generate TypeScript interface
aztec codegen ./target/my_contract-MyContract.json -o src/artifacts

info

The codegen command creates a TypeScript class with typed methods for deployment and interaction. This provides type safety and autocompletion in your IDE.

Deploy a contract

Step 1: Import and connect

import { MyContract } from "./artifacts/MyContract";

About wallets and accounts

In the examples below, wallet refers to a Wallet instance that manages keys and signs transactions. See Creating Accounts for how to set up a wallet. The from option in send() specifies which account pays for the transaction. This account must be registered in the wallet and have sufficient fee juice. On a local network, test accounts are pre-funded; on testnet, you typically use sponsored fees.

Step 2: Deploy the contract

How you deploy depends on how you pay for it. When paying using an account's fee juice (like a test account on the local network):

deploy_basic_local

// wallet and aliceAddress are from the connection guide
// Deploy with constructor arguments
const { contract: token } = await TokenContract.deploy(
  wallet,
  aliceAddress,
  "TestToken",
  "TST",
  18,
).send({ from: aliceAddress }); // alice has fee juice and is registered in the wallet

^{_{Source code: docs/examples/ts/aztecjs_advanced/index.ts#L30-L40}}

On testnet, your account likely won't have Fee Juice. Instead, pay fees using the Sponsored Fee Payment Contract method:

deploy_sponsored_fpc_contract

// Set up the Sponsored FPC (see fees guide for full setup)
const sponsoredFPCInstance = await getContractInstanceFromInstantiationParams(
  SponsoredFPCContract.artifact,
  { salt: new Fr(0) },
);
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(
  wallet,
  aliceAddress,
  "SponsoredToken",
  "SPT",
  18,
).send({ from: aliceAddress, fee: { paymentMethod: sponsoredPaymentMethod } });

^{_{Source code: docs/examples/ts/aztecjs_advanced/index.ts#L42-L59}}

Here's a complete example from the test suite:

deploy_basic

const { contract } = await StatefulTestContract.deploy(wallet, owner, 42).send({ from: defaultAccountAddress });

^{_{Source code: yarn-project/end-to-end/src/e2e_deploy_contract/deploy_method.test.ts#L42-L44}}

Use deployment options

Deploy with custom salt

By default, the deployment's salt is random, but you can specify it (for example, if you want to get a deterministic address):

deploy_custom_salt

// wallet and aliceAddress are from the connection guide
const customSalt = Fr.random();

const { contract: saltedContract } = await TokenContract.deploy(
  wallet,
  aliceAddress,
  "SaltedToken",
  "SALT",
  18,
).send({
  from: aliceAddress,
  contractAddressSalt: customSalt,
});

^{_{Source code: docs/examples/ts/aztecjs_advanced/index.ts#L61-L75}}

Deploy universally

Deploy to the same address across networks by setting universalDeploy: true:

deploy_universal

const opts = { universalDeploy: true, from: defaultAccountAddress };
const { contract } = await StatefulTestContract.deploy(wallet, owner, 42).send(opts);

^{_{Source code: yarn-project/end-to-end/src/e2e_deploy_contract/deploy_method.test.ts#L61-L64}}

info

Universal deployment excludes the sender from address computation, allowing the same address on any network with the same salt.

Skip initialization

Deploy without running the constructor:

skip_initialization

// Deploy without running the constructor using skipInitialization
const { contract: delayedToken } = await TokenContract.deploy(
  wallet,
  aliceAddress,
  "DelayedToken",
  "DLY",
  18,
).send({
  from: aliceAddress,
  skipInitialization: true,
});

console.log(`Contract deployed at: ${delayedToken.address}`);

// Initialize later by calling the constructor manually
await delayedToken.methods
  .constructor(aliceAddress, "DelayedToken", "DLY", 18)
  .send({ from: aliceAddress });

console.log("Contract initialized");

^{_{Source code: docs/examples/ts/aztecjs_advanced/index.ts#L250-L271}}

Deploy with a specific initializer

Some contracts have multiple initializer functions (e.g., both a private constructor and a public_constructor). By default, the generated deploy() method uses the default initializer (typically named constructor). To deploy using a different initializer, use deployWithOpts:

deploy_with_opts

const { contract } = await StatefulTestContract.deployWithOpts(
  { wallet, method: 'public_constructor' },
  owner,
  42,
).send({
  from: defaultAccountAddress,
});

^{_{Source code: yarn-project/end-to-end/src/e2e_deploy_contract/deploy_method.test.ts#L85-L93}}

The deployWithOpts method accepts an options object as its first argument:

• wallet: The wallet to use for deployment (required)
• method: The name of the initializer function to call (optional, defaults to constructor)
• publicKeys: Custom public keys for the contract instance (optional)

The remaining arguments are the parameters for the chosen initializer function.

tip

This is useful for contracts that support multiple initialization patterns, such as token standards that allow both private and public minting during deployment.

Calculate deployment address

Get address before deployment

calculate_address_before_deploy

// Calculate address without deploying
// wallet is from the connection guide (see prerequisites)
const deploymentSalt = Fr.random();
const deployMethod = TokenContract.deploy(
  wallet,
  aliceAddress,
  "PredictedToken",
  "PRED",
  18,
);
const instance = await deployMethod.getInstance({ contractAddressSalt: deploymentSalt });
const predictedAddress = instance.address;

console.log(`Contract will deploy at: ${predictedAddress}`);

^{_{Source code: docs/examples/ts/aztecjs_advanced/index.ts#L77-L92}}

warning

This is an advanced pattern. For most use cases, deploy the contract directly and get the address from the deployed instance.

Monitor deployment progress

Track deployment transaction

Use NO_WAIT to get the transaction hash immediately and track deployment:

no_wait_deploy

// Use NO_WAIT to get the transaction hash immediately and track deployment
const { txHash } = await TokenContract.deploy(
  wallet,
  aliceAddress,
  "AnotherToken",
  "ATK",
  18,
).send({
  from: aliceAddress,
  wait: NO_WAIT,
});

console.log(`Deployment tx: ${txHash}`);

// Wait for the transaction to be mined using the node
const receipt = await waitForTx(node, txHash);
console.log(`Deployed in block ${receipt.blockNumber}`);

^{_{Source code: docs/examples/ts/aztecjs_advanced/index.ts#L129-L147}}

For most use cases, simply await the deployment to get the contract directly:

deploy_contract

import { TokenContract } from "@aztec/noir-contracts.js/Token";

const { contract: token } = await TokenContract.deploy(
  wallet,
  aliceAddress,
  "TestToken",
  "TST",
  18,
).send({ from: aliceAddress });

console.log(`Token deployed at: ${token.address.toString()}`);

^{_{Source code: docs/examples/ts/aztecjs_connection/index.ts#L91-L103}}

Deploy multiple contracts

Deploy a token contract

Here's an example deploying a TokenContract with constructor arguments for admin, name, symbol, and decimals:

deploy_token

const { contract: token } = await TokenContract.deploy(wallet, owner, 'TOKEN', 'TKN', 18).send({
  from: defaultAccountAddress,
});

^{_{Source code: yarn-project/end-to-end/src/e2e_deploy_contract/deploy_method.test.ts#L74-L78}}

Deploy contracts with dependencies

When one contract depends on another, deploy them sequentially and pass the first contract's address:

deploy_with_dependencies

// Deploy contracts with dependencies - deploy sequentially and pass addresses
const { contract: baseToken } = await TokenContract.deploy(
  wallet,
  aliceAddress,
  "BaseToken",
  "BASE",
  18,
).send({ from: aliceAddress });

// A second contract could reference the first (example pattern)
const { contract: derivedToken } = await TokenContract.deploy(
  wallet,
  baseToken.address, // Use first contract's address as admin
  "DerivedToken",
  "DERIV",
  18,
).send({ from: aliceAddress });

console.log(`Base token at: ${baseToken.address.toString()}`);
console.log(`Derived token at: ${derivedToken.address.toString()}`);

^{_{Source code: docs/examples/ts/aztecjs_advanced/index.ts#L208-L229}}

Deploy contracts in parallel

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),
]);

console.log(`Contract 1 at: ${contracts[0].address}`);
console.log(`Contract 2 at: ${contracts[1].address}`);
console.log(`Contract 3 at: ${contracts[2].address}`);

^{_{Source code: docs/examples/ts/aztecjs_advanced/index.ts#L231-L248}}

Parallel deployment considerations

Parallel deployment is faster, but transactions from the same account share a nonce sequence. The wallet handles nonce assignment automatically, but if one deployment fails, subsequent deployments may also fail due to nonce gaps. For reliable parallel deployments:

• Use separate accounts for each deployment, or
• Handle failures gracefully and retry with fresh nonces
• Consider using BatchCall to bundle multiple operations into a single transaction (see below)

Deploy with BatchCall

Use BatchCall to bundle a deployment with other calls into a single transaction. This is useful when you need to deploy a contract and immediately call methods on it:

deploy_batch

// Create a contract instance and make the PXE aware of it
const deployMethod = StatefulTestContract.deploy(wallet, owner, 42);
const contract = await deployMethod.register();

// Batch deployment and a public call into the same transaction
const publicCall = contract.methods.increment_public_value(owner, 84);
await new BatchCall(wallet, [deployMethod, publicCall]).send({ from: defaultAccountAddress });

^{_{Source code: yarn-project/end-to-end/src/e2e_deploy_contract/deploy_method.test.ts#L133-L141}}

Verify deployment

Check contract state

Use wallet.getContractMetadata() to check your contract's current state:

const metadata = await wallet.getContractMetadata(contractAddress);

// Check each state:
metadata.instance; // Contract registered in your wallet?
metadata.isContractClassPubliclyRegistered; // Class registered on the network?
metadata.isContractPublished; // Instance registered on the network?
metadata.isContractInitialized; // Constructor has been called?

For a complete overview of what these states mean and when functions become callable, see Contract Readiness States.

Here's a complete example:

verify_deployment

const metadata = await wallet.getContractMetadata(contract.address);
const classMetadata = await wallet.getContractClassMetadata(metadata.instance!.currentContractClassId);
const isPublished = classMetadata.isContractClassPubliclyRegistered;

^{_{Source code: yarn-project/end-to-end/src/e2e_deploy_contract/deploy_method.test.ts#L51-L55}}

What the PXE checks automatically

When you simulate or send a transaction, the PXE automatically verifies:

• Contract instance is registered in your wallet
• Contract artifact is available locally
• Contract class ID matches the network state

The PXE does not automatically check:

• Whether the contract is published on the network
• Whether the contract is initialized
• Whether the contract class is registered on the network

If you call a public function on an unpublished contract, the transaction will fail at the network level, not during local simulation. Use getContractMetadata() to check these states before sending transactions if you want to provide better error messages to users.

Verify contract is callable

verify_contract_callable

// token is from the deployment step above; aliceAddress is from the connection guide
try {
  // Try calling a view function
  const { result: balance } = await token.methods
    .balance_of_public(aliceAddress)
    .simulate({ from: aliceAddress });
  console.log("Contract is callable, balance:", balance);
} catch (error) {
  console.error("Contract not accessible:", (error as Error).message);
}

^{_{Source code: docs/examples/ts/aztecjs_advanced/index.ts#L94-L105}}

Register deployed contracts

Add existing contract to wallet

If a contract was deployed by another account:

register_external_contract

// wallet is from the connection guide; contractAddress is the address of the deployed contract
const contractAddress = token.address;

// Get the contract metadata from the node (includes the instance)
const metadata = await wallet.getContractMetadata(contractAddress);

// Register the contract with the wallet
// The registerContract method takes positional parameters:
// - instance: ContractInstanceWithAddress (required)
// - artifact: ContractArtifact (optional)
// - secretKey: Fr (optional)
await wallet.registerContract(metadata.instance!, TokenContract.artifact);

// Now you can interact with the contract
const externalContract = await TokenContract.at(contractAddress, wallet);

^{_{Source code: docs/examples/ts/aztecjs_advanced/index.ts#L107-L123}}

warning

You need the exact deployment parameters (salt, initialization hash, etc.) to correctly register an externally deployed contract. If you don't have access to the contract instance, you can reconstruct it:

reconstruct_contract_instance

// Reconstruct a contract instance from deployment parameters
// Use this when you need to register a contract deployed by someone else
const reconstructedInstance = await getContractInstanceFromInstantiationParams(
  TokenContract.artifact,
  {
    publicKeys: PublicKeys.default(),
    constructorArtifact: "constructor",
    constructorArgs: [aliceAddress, "ReconstructedToken", "RTK", 18],
    deployer: aliceAddress,
    salt: new Fr(12345), // The original deployment salt
  },
);

// Register the reconstructed contract with the wallet
await wallet.registerContract(reconstructedInstance, TokenContract.artifact);
console.log(
  `Reconstructed contract address: ${reconstructedInstance.address.toString()}`,
);

^{_{Source code: docs/examples/ts/aztecjs_advanced/index.ts#L173-L192}}

Next steps

• Contract Readiness States - Understand the different states a contract progresses through
• Send transactions to interact with your contract
• Read contract data including simulating functions and reading events
• Use authentication witnesses for delegated calls