xdeployer 💥

Hardhat plugin to deploy your smart contracts across multiple Ethereum Virtual Machine (EVM) chains with the same deterministic address.

[!TIP] It is pronounced cross-deployer.

[!IMPORTANT] This plugin currently targets Hardhat 2 and is not compatible with Hardhat 3.

What

This plugin will help you make easier and safer usage of the CREATE2 EVM opcode. CREATE2 can be used to compute in advance the address where a smart contract will be deployed, which allows for interesting new mechanisms known as counterfactual interactions.

Installation

With npm versions >=7:

# based on ethers v6
npm install --save-dev xdeployer

With npm version 6:

# based on ethers v6
npm install --save-dev xdeployer '@nomicfoundation/hardhat-ethers@^3.1.3' ethers

<details> <summary> Using <code>ethers</code> version <code>5</code> </summary>

With npm versions >=7:

# based on ethers v5
npm install --save-dev 'xdeployer@^1.2.7'

With npm version 6:

# based on ethers v5
npm install --save-dev 'xdeployer@^1.2.7' @nomiclabs/hardhat-ethers 'ethers@^5.7.2' '@openzeppelin/contracts@^4.9.0'

</details>

Or if you are using Yarn:

# based on ethers v6
yarn add --dev xdeployer '@nomicfoundation/hardhat-ethers@^3.1.3' ethers

<details> <summary> Using <code>ethers</code> version <code>5</code> </summary>

# based on ethers v5
yarn add --dev 'xdeployer@^1.2.7' @nomiclabs/hardhat-ethers 'ethers@^5.7.2' '@openzeppelin/contracts@^4.9.0'

</details>

In case you are using pnpm, invoke:

# based on ethers v6
pnpm add --save-dev xdeployer

<details> <summary> Using <code>ethers</code> version <code>5</code> </summary>

# based on ethers v5
pnpm add --save-dev 'xdeployer@^1.2.7'

</details>

If you are a Bun user, run:

# based on ethers v6
bun add --dev xdeployer

<details> <summary> Using <code>ethers</code> version <code>5</code> </summary>

# based on ethers v5
bun add --dev 'xdeployer@^1.2.7'

</details>

[!NOTE] This plugin uses the optional chaining operator (?.). Optional chaining is not supported in Node.js v13 and below.

Import the plugin in your hardhat.config.js:

require("xdeployer");

Or if you are using TypeScript, in your hardhat.config.ts:

import "xdeployer";

Required Plugins

• @nomicfoundation/hardhat-ethers@3
• ethers

Tasks

This plugin provides the xdeploy task, which allows you to deploy your smart contracts across multiple EVM chains with the same deterministic address:

npx hardhat xdeploy

Environment Extensions

This plugin does not extend the environment.

Configuration

You need to add the following configurations to your hardhat.config.js file:

module.exports = {
  networks: {
    mainnet: { ... }
  },
  xdeploy: {
    contract: "YOUR_CONTRACT_NAME_TO_BE_DEPLOYED",
    constructorArgsPath: "PATH_TO_CONSTRUCTOR_ARGS", // optional; default value is `undefined`
    salt: "YOUR_SALT_MESSAGE",
    signer: "SIGNER_PRIVATE_KEY",
    networks: ["LIST_OF_NETWORKS"],
    rpcUrls: ["LIST_OF_RPCURLS"],
    gasLimit: 1_500_000, // optional; default value is `1.5e6`
  },
};

Or if you are using TypeScript, in your hardhat.config.ts:

const config: HardhatUserConfig = {
  networks: {
    mainnet: { ... }
  },
  xdeploy: {
    contract: "YOUR_CONTRACT_NAME_TO_BE_DEPLOYED",
    constructorArgsPath: "PATH_TO_CONSTRUCTOR_ARGS", // optional; default value is `undefined`
    salt: "YOUR_SALT_MESSAGE",
    signer: "SIGNER_PRIVATE_KEY",
    networks: ["LIST_OF_NETWORKS"],
    rpcUrls: ["LIST_OF_RPCURLS"],
    gasLimit: 1_500_000, // optional; default value is `1.5e6`
  },
};

The parameters constructorArgsPath and gasLimit are optional. The salt parameter is a random string value used to create the contract address. If you have previously deployed the same contract with the identical salt, the contract creation transaction will fail due to EIP-684. For more details, see also here.

[!IMPORTANT] Please note that xdeployer computes the UTF-8 byte representation of the specified salt and calculates the keccak256 hash, which represents the 32-byte salt value that is passed to CREATE2.

Example:

xdeploy: {
    contract: "ERC20Mock",
    constructorArgsPath: "./deploy-args.ts",
    salt: "WAGMI",
    signer: vars.get("PRIVATE_KEY", ""),
    networks: ["hardhat", "sepolia", "hoodi"],
    rpcUrls: [
      "hardhat",
      vars.get("ETH_SEPOLIA_TESTNET_URL", "https://rpc.sepolia.org"),
      vars.get("ETH_HOODI_TESTNET_URL", "https://0xrpc.io/hoodi"),
    ],
    gasLimit: 1.2 * 10 ** 6,
},

[!NOTE] We recommend using Hardhat configuration variables introduced in Hardhat version 2.19.0 to set the private key of your signer.

The current available networks are:

[!TIP] To display the complete list of supported networks with the corresponding block explorer links and chain IDs, run npx hardhat xdeploy --list-networks.

• Local:
  • localhost
  • hardhat
• EVM-Based Test Networks:
  • sepolia
  • hoodi
  • bscTestnet
  • opbnbTestnet
  • optimismSepolia
  • arbitrumSepolia
  • amoy
  • polygonZkEVMTestnet
  • fantomTestnet
  • fuji
  • chiado
  • moonbaseAlpha
  • celoTestnet
  • auroraTestnet
  • harmonyTestnet
  • spark
  • cronosTestnet
  • evmosTestnet
  • bobaTestnet
  • cantoTestnet
  • baseSepolia
  • mantleTestnet
  • filecoinTestnet
  • scrollSepolia
  • lineaTestnet
  • zoraSepolia
  • luksoTestnet
  • mantaTestnet
  • blastTestnet
  • dosTestnet
  • fraxtalTestnet
  • metisTestnet
  • modeTestnet
  • seiArcticDevnet
  • seiAtlanticTestnet
  • xlayerTestnet
  • bobTestnet
  • coreTestnet
  • telosTestnet
  • rootstockTestnet
  • chilizTestnet
  • taraxaTestnet
  • taikoTestnet
  • zetaChainTestnet
  • 5ireChainTestnet
  • sapphireTestnet
  • worldChainTestnet
  • plumeTestnet
  • unichainTestnet
  • xdcTestnet
  • sxTestnet
  • liskTestnet
  • metalL2Testnet
  • superseedTestnet
  • storyTestnet
  • sonicTestnet
  • flowTestnet
  • inkTestnet
  • morphTestnet
  • shapeTestnet
  • etherlinkTestnet
  • soneiumTestnet
  • swellTestnet
  • hemiTestnet
  • berachainTestnet
  • monadTestnet
  • cornTestnet
  • arenazTestnet
  • iotexTestnet
  • hychainTestnet
  • zircuitTestnet
  • megaETHTestnet
  • bitlayerTestnet
  • roninTestnet
  • zkSyncTestnet
  • immutableZkEVMTestnet
  • abstractTestnet
  • hyperevmTestnet
  • apeChainTestnet
  • botanixTestnet
  • tacTestnet
  • katanaTestnet
  • plasmaTestnet
  • sophonTestnet
  • jovayTestnet
  • intuitionTestnet
  • memecoreTestnet
  • lightlinkTestnet
  • xrplEVMTestnet
  • arcTestnet
  • dmdTestnet
  • citreaTestnet
  • tempoTestnet
  • lensTestnet
• EVM-Based Production Networks:
  • ethMain
  • bscMain
  • opbnbMain
  • optimismMain
  • arbitrumOne
  • arbitrumNova
  • polygon
  • polygonZkEVMMain
  • fantomMain
  • avalanche
  • gnosis
  • moonriver
  • moonbeam
  • celo
  • auroraMain
  • harmonyMain
  • fuse
  • cronosMain
  • evmosMain
  • bobaMain
  • cantoMain
  • baseMain
  • mantleMain
  • filecoinMain
  • scrollMain
  • lineaMain
  • zoraMain
  • luksoMain
  • mantaMain
  • blastMain
  • dosMain
  • fraxtalMain
  • enduranceMain
  • kavaMain
  • metisMain
  • modeMain
  • seiMain
  • xlayerMain
  • bobMain
  • coreMain
  • telosMain
  • rootstockMain
  • chilizMain
  • taraxaMain
  • gravityAlphaMain
  • taikoMain
  • zetaChainMain
  • 5ireChainMain
  • sapphireMain
  • worldChainMain
  • plumeMain
  • unichainMain
  • xdcMain
  • sxMain
  • liskMain
  • metalL2Main
  • superseedMain
  • storyMain
  • sonicMain
  • flowMain
  • inkMain
  • morphMain
  • shapeMain
  • etherlinkMain
  • soneiumMain
  • swellMain
  • hemiMain
  • berachainMain
  • monadMain
  • cornMain
  • arenazMain
  • iotexMain
  • hychainMain
  • zircuitMain
  • megaETHMain
  • bitlayerMain
  • roninMain
  • zkSyncMain
  • immutableZkEVMMain
  • abstractMain
  • hyperevmMain
  • kaiaMain
  • apeChainMain
  • botanixMain
  • tacMain
  • katanaMain
  • plasmaMain
  • sophonMain
  • jovayMain
  • intuitionMain
  • memecoreMain
  • lightlinkMain
  • xrplEVMMain
  • dmdMain
  • citreaMain
  • tempoMain
  • lensMain

[!IMPORTANT] Note that you must ensure that your deployment account has sufficient funds on all target networks.

Local Deployment

If you also want to test deploy your smart contracts on "hardhat" or "localhost", you must first add the following Solidity file called Create2DeployerLocal.sol to your contracts/ folder:

//