CreateX – A Trustless, Universal Contract Deployer

Factory smart contract to make easier and safer usage of the CREATE and CREATE2 EVM opcodes as well as of CREATE3-based (i.e. without an initcode factor) contract creations.

[!NOTE] The CreateX contract should be considered as maximally extensible. Be encouraged to build on top of it! The Solidity-based interface can be found here.

• So What on Earth Is a Contract Factory?
• Available Versatile Functions
• Special Features
  • Permissioned Deploy Protection and Cross-Chain Redeploy Protection
  • Pseudo-Random Salt Value
• Design Principles
• Security Considerations
• Tests
  • Test Coverage
• ABI (Application Binary Interface)
• New Deployment(s)
  • ethers.js
  • cast
  • Contract Verification
• CreateX Deployments
  • EVM-Based Production Networks
  • Ethereum Test Networks
  • Additional EVM-Based Test Networks
• Integration With External Tooling
• Community-Maintained Dune Dashboards
• 🙏🏼 Acknowledgement

So What on Earth Is a Contract Factory?

It is important to understand that Ethereum Virtual Machine (EVM) opcodes can only be called via a smart contract. A contract factory in the context of the EVM refers to a special smart contract that is used to create and deploy other smart contracts on EVM-compatible blockchains using contract creation opcodes (i.e. CREATE or CREATE2). Using a contract factory provides a flexible and efficient way to deploy and manage smart contracts that share similar functionalities but may have different configurations or settings.

Different approaches can be used to create contracts using a factory contract, and this is exactly what CreateX offers: a comprehensive range of contract creation functions that are triggered by a smart contract itself. It is worth emphasising the two differences in the address calculation of the opcodes CREATE and CREATE2 (|| stands for byte-wise concatenation, [12:] refers to the last 20 bytes of a 32-byte expression, and rlp is an abbreviation for Ethereum's "Recursive Length Prefix" serialisation scheme):

• CREATE: address computedAddress = keccak256(rlpEncode([deployerAddress, deployerNonce]))[12:],
• CREATE2: address computedAddress = keccak256(0xff||deployerAddress||salt||keccak256(initCode))[12:].

Available Versatile Functions

CreateX
├── CREATE
│   ├── Read-Only Functions
│   │   ├── "function computeCreateAddress(uint256) view returns (address)"
│   │   └── "function computeCreateAddress(address,uint256) view returns (address)"
│   └── Write Functions
│       ├── "function deployCreate(bytes) payable returns (address)"
│       ├── "function deployCreateAndInit(bytes,bytes,tuple(uint256,uint256)) payable returns (address)"
│       ├── "function deployCreateAndInit(bytes,bytes,tuple(uint256,uint256),address) payable returns (address)"
│       └── "function deployCreateClone(address,bytes) payable returns (address)"
├── CREATE2
│   ├── Read-Only Functions
│   │   ├── "function computeCreate2Address(bytes32,bytes32) view returns (address)"
│   │   └── "function computeCreate2Address(bytes32,bytes32,address) pure returns (address)"
│   └── Write Functions
│       ├── "function deployCreate2(bytes) payable returns (address)"
│       ├── "function deployCreate2(bytes32,bytes) payable returns (address)"
│       ├── "function deployCreate2AndInit(bytes,bytes,tuple(uint256,uint256)) payable returns (address)"
│       ├── "function deployCreate2AndInit(bytes32,bytes,bytes,tuple(uint256,uint256)) payable returns (address)"
│       ├── "function deployCreate2AndInit(bytes,bytes,tuple(uint256,uint256),address) payable returns (address)"
│       ├── "function deployCreate2AndInit(bytes32,bytes,bytes,tuple(uint256,uint256),address) payable returns (address)"
│       ├── "function deployCreate2Clone(address,bytes) payable returns (address)"
│       └── "function deployCreate2Clone(bytes32,address,bytes) payable returns (address)"
└── CREATE3
    ├── Read-Only Functions
    │   ├── "function computeCreate3Address(bytes32) view returns (address)"
    │   └── "function computeCreate3Address(bytes32,address) pure returns (address)"
    └── Write Functions
        ├── "function deployCreate3(bytes) payable returns (address)"
        ├── "function deployCreate3(bytes32,bytes) payable returns (address)"
        ├── "function deployCreate3AndInit(bytes,bytes,tuple(uint256,uint256)) payable returns (address)"
        ├── "function deployCreate3AndInit(bytes32,bytes,bytes,tuple(uint256,uint256)) payable returns (address)"
        ├── "function deployCreate3AndInit(bytes,bytes,tuple(uint256,uint256),address) payable returns (address)"
        └── "function deployCreate3AndInit(bytes32,bytes,bytes,tuple(uint256,uint256),address) payable returns (address)"

Special Features

[!TIP] Note that the separate project createXcrunch is a Rust-based program designed to efficiently find zero-leading, zero-containing, or pattern-matching deployment addresses, taking into account the subsequent special features of CreateX.

Permissioned Deploy Protection and Cross-Chain Redeploy Protection

The salt value implements different safeguarding mechanisms depending on the encoded values in the salt (|| stands for byte-wise concatenation):

=> salt (32 bytes) = 0xbebebebebebebebebebebebebebebebebebebebe||ff||1212121212121212121212

• The first 20 bytes (i.e. bebebebebebebebebebebebebebebebebebebebe) may be used to implement a permissioned deploy protection by setting them equal to msg.sender,
• The 21st byte (i.e. ff) may be used to implement a cross-chain redeploy protection by setting it equal to 0x01,
• The last random 11 bytes (i.e. 1212121212121212121212) allow for $2^{88}$ bits of entropy for mining a salt.

The full logic is implemented in the internal _guard function:

function _guard(bytes32 salt) internal view returns (bytes32 guardedSalt) {
  (
    SenderBytes senderBytes,
    RedeployProtectionFlag redeployProtectionFlag
  ) = _parseSalt({ salt: salt });

  if (
    senderBytes == SenderBytes.MsgSender &&
    redeployProtectionFlag == RedeployProtectionFlag.True
  ) {
    // Configures a permissioned deploy protection as well as a cross-chain redeploy protection.
    guardedSalt = keccak256(abi.encode(msg.sender, block.chainid, salt));
  } else if (
    senderBytes == SenderBytes.MsgSender &&
    redeployProtectionFlag == RedeployProtectionFlag.False
  ) {
    // Configures solely a permissioned deploy protection.
    guardedSalt = _efficientHash({
      a: bytes32(uint256(uint160(msg.sender))),
      b: salt
    });
  } else if (senderBytes == SenderBytes.MsgSender) {
    // Reverts if the 21st byte is greater than `0x01` in order to enforce developer explicitness.
    revert InvalidSalt({ emitter: _SELF });
  } else if (
    senderBytes == SenderBytes.ZeroAddress &&
    redeployProtectionFlag == RedeployProtectionFlag.True
  ) {
    // Configures solely a cross-chain redeploy protection. In order to prevent a pseudo-randomly
    // generated cross-chain redeploy protection, we enforce the zero address check for the first 20 bytes.
    guardedSalt = _efficientHash({ a: bytes32(block.chainid), b: salt });
  } else if (
    senderBytes == SenderBytes.ZeroAddress &&
    redeployProtectionFlag == RedeployProtectionFlag.Unspecified
  ) {
    // Reverts if the 21st byte is greater than `0x01` in order to enforce developer explicitness.
    revert InvalidSalt({ emitter: _SELF });
  } else {
    // For the non-pseudo-random cases, the salt value `salt` is hashed to prevent the safeguard mechanisms
    // from being bypassed. Otherwise, the salt value `salt` is not modified.
    guardedSalt = (salt != _generateSalt())
      ? keccak256(abi.encode(salt))
      : salt;
  }
}

Please note that when you configure a permissioned deploy protection, you must specify whether you want cross-chain redeploy protection (i.e. 21st byte equals 0x01) or not (i.e. the 21st byte equals 0x00). The underlying reason for this logic is to enforce developer explicitness. If you don't specify a cross-chain redeploy protection decision (i.e. the 21st byte is greater than 0x01) the function reverts.

Furthermore, you can configure only cross-chain redeploy protection by setting the first 20 bytes equal to the zero address 0x0000000000000000000000000000000000000000. The rationale behind this logic is to prevent a pseudo-randomly generated 32 byte salt from inadvertently activating cross-chain redeploy protection. Also in this case, if you don't specify a cross-chain redeploy protection, i.e. the 21st byte is greater than 0x01, the function reverts. The underlying reason for this logic is as well to enforce developer explicitness.

[!IMPORTANT]
When using the read-only functions computeCreate2Address(bytes32,bytes32) or computeCreate3Address(bytes32), it is essential to provide the guarded salt value, meaning the value after being processed by the _guard function, as the input parameter. This ensures the correct computation of the deployment address. For more details, refer to this issue.

Pseudo-Random Salt Value

For developer convenience, the CreateX contract offers several overloaded functions that generate the salt value pseudo-randomly using a diverse selection of block and transaction properties. Please note that this approach does not guarantee true randomness!

The full logic is implemented in the internal _generateSalt function:

function _generateSalt() internal view returns (bytes32 salt) {
  unchecked {
    salt = keccak256(
      abi.encode(
        // We don't use `block.number - 256` (the maximum value on the EVM) to accommodate
        // any chains that may try to reduce the amount of available historical block hashes.
        // We also don't subtract 1 to mitigate any risks arising from consecutive block
        // producers on a PoS chain. Therefore, we use `block.number - 32` as a reasonable
        // compromise, one we expect should work on most chains, which is 1 epoch on Ethereum
        // mainnet. Please note that if you use this function between the genesis block and block
        // number 31, the block property `blockhash` will return zero, but the returned salt value
        // `salt` will still have a non-zero value due to the hashing characteristic and the other
        // remaining properties.
        blockhash(block.number - 32),
        block.coinbase,
        block.number,
        block.timestamp,
        block.prevrandao,
        block.chainid,
        msg.sender
      )
    );
  }
}

Design Principles

• CreateX should cover most but not all contract creation use cases.
• CreateX should be human-readable and should be simple to understand for readers with low prior experience.
• CreateX should be maximally secure, i.e. no hidden footguns.
• CreateX should be trustless.
• CreateX should be stateless.
• CreateX should be extensible (i.e. it can be used to deploy protocols, within protocols, or to deploy other types of deterministic deployer factories).

The following consequences result from these principles:

• We only use inline assembly if it is required or if the code section itself is based on short and/or audited code.
• We document the contract to the smallest detail.
• We extensively fuzz test all functions.
• We deliberately do not implement special functions for clones with immutable arguments, as there is neither a finalised standard nor a properly audited contract version.
• We do not implement any special functions for EIP-5202 (a.k.a. blueprint contracts), as all existing functions in CreateX are already cost-effective alternatives in our opinion.

Security Considerations

[!WARNING] This contract is unaudited! Special thanks go to Oleksii Matiiasevych for his thorough review and feedback 🙏🏽.

Generally, for security issues, see our Security Policy. Furthermore, you must be aware of the following aspects:

• Several functions allow for reentrancy, however we refrain from adding a mutex lock to keep it as use-case agnostic as possible. Please ensure at the protocol level that potentially malicious reentrant calls do not affect your smart contract system.

• In the functions:

  • deployCreate3(bytes32,bytes),
  • deployCreate3AndInit(bytes32,bytes,bytes,tuple(uint256,uint256)), and
  • deployCreate3AndInit(bytes32,bytes,bytes,tuple(uint256,uint256),address)

  we strongly recommend implementing a permissioned deploy protection by setting the first 20 bytes equal to msg.sender in the salt to prevent maliciously intended frontrun proxy deployments on other chains.

• The target EVM version for compilation is set to paris, i.e. neither the contract creation bytecode of CreateX nor the returned runtime bytecode contains a PUSH0 instruction.

• Please refer to our comment in the discussion here for background information on the risks of our private-key-based deployment approach. We recommend verifying prior to interacting with CreateX on any chain, that the keccak256 hash of the broadcasted contract creation bytecode is 0x12ec861579b63a3ab9db3b5a23c57d56402ad3061475b088f17054e2f2daf22f or of the deployed runtime bytecode is 0xbd8a7ea8cfca7b4e5f5041d7d4b17bc317c5ce42cfbc42066a00cf26b43eb53f.

Tests

For all (fuzz) tests available in the test directory, we have consistently applied the Branching Tree Technique with bulloak. This means that each test file is accompanied by a .tree file that defines all the necessary branches to be tested.

Example (CreateX._guard.tree):

CreateX_Guard_Internal_Test
├── When the first 20 bytes of the salt equals the caller
│   ├── When the 21st byte of the salt equals 0x01
│   │   └── It should return the keccak256 hash of the ABI-encoded values msg.sender, block.chainid, and the salt.
│   ├── When the 21st byte of the salt equals 0x00
│   │   └── It should return the keccak256 hash of the ABI-encoded values msg.sender and the salt.
│   └── When the 21st byte of the salt is greater than 0x01
│       └── It should revert.
├── When the first 20 bytes of the salt equals the zero address
│   ├── When the 21st byte of the salt equals 0x01
│   │   └── It should return the keccak256 hash of the ABI-encoded values block.chainid and the salt.
│   ├── When the 21st byte of the salt equals 0x00
│   │   └── It should return the keccak256 hash of the ABI-encoded value salt.
│   └── When the 21st byte of the salt is greater than 0x01
│       └── It should revert.
└── When the first 20 bytes of the salt do not equal the caller or the zero address
    ├── It should return the keccak256 hash of the ABI-encoded value salt.
    └── When the salt value is generated pseudo-randomly
        └── It should return the unmodified salt value.

Test Coverage

This project repository uses forge coverage. Simply run:

forge coverage

In order to generate an HTML file with the coverage data, you can invoke:

pnpm coverage:report

The written tests available in the directory test achieve a test coverage of 100% for the CreateX contract:

| File            | % Lines           | % Statements      | % Branches      | % Funcs         |
|-----------------|-------------------|-------------------|-----------------|-----------------|
| src/CreateX.sol | 100.00% (149/149) | 100.00% (210/210) | 100.00% (78/78) | 100.00% (31/31) |

[!IMPORTANT] A test coverage of 100% does not mean that there are no vulnerabilities. What really counts is the quality and spectrum of the tests themselves!

ABI (Application Binary Interface)

[!TIP] If you forge install this repository, the Solidity-based interface can also be found here.

New Deployment(s)

We offer two options for deploying CreateX to your desired chain:

1. Deploy it yourself by using one of the pre-signed transactions. Details can be found in the subsequent paragraph.
2. Request a deployment by opening an issue. You can significantly reduce the time to deployment by sending funds to cover the deployment cost (a reliable amount with a small tip 😏 would be ~0.3 ETH) to the deployer account: 0xeD456e05CaAb11d66C4c797dD6c1D6f9A7F352b5.

[!CAUTION] Prior to using a pre-signed transaction, you MUST ensure that the gas metering of the target chain is EQUIVALENT to that of Ethereum's EVM version!

The default pre-signed transaction has a gas limit of 3,000,000 gas, so if the target chain requires more than 3 million gas to deploy, the contract creation transaction will revert and we will not be able to deploy CreateX to the address 0xba5Ed099633D3B313e4D5F7bdc1305d3c28ba5Ed. In this case, the only way to get CreateX deployed at the expected address is for the chain to store the contract there as a predeploy.

If you are not sure how to validate this, you can either use the eth_estimateGas JSON-RPC method or simply deploy the CreateX contract from another account and see how much gas is needed for the deployment. Standard EVM chains should require exactly 2,580,902 gas to deploy CreateX.

We repeat: PLEASE DO NOT BROADCAST ANY PRE-SIGNED TRANSACTION WITHOUT LOCAL TESTING! Also, before deploying, you MUST send at least 0.3 ETH to the deployer address 0xeD456e05CaAb11d66C4c797dD6c1D6f9A7F352b5. We offer three pre-signed, pre-EIP-155 transactions with the same gas price of 100 gwei, but different gasLimit levels:

• Default Case: gasLimit = 3_000_000; signed_serialised_transaction_gaslimit_3000000_.json,
• Medium Case: gasLimit = 25_000_000; signed_serialised_transaction_gaslimit_25000000_.json,
• Heavy Case: gasLimit = 45_000_000; signed_serialised_transaction_gaslimit_45000000_.json.

You can broadcast the transaction using either ethers.js or cast:

ethers.js

It is recommended to install pnpm through the npm package manager, which comes bundled with Node.js when you install it on your system. It is recommended to use a Node.js version >= 22.0.0.

Once you have npm installed, you can run the following both to install and upgrade pnpm:

npm install -g pnpm

After having installed pnpm, simply run:

git clone https://github.com/pcaversaccio/createx.git
cd createx
pnpm install

Now configure your target chain in the hardhat.config.ts file with the networks and etherscan properties, or use one of the preconfigured network configurations. After you have locally ensured that the gasLimit of 3 million works on your target chain, you can invoke:

npx hardhat run --no-compile --network <NETWORK_NAME> scripts/deploy.ts

The deploy.ts script ensures that CreateX is automatically verified if you have configured the etherscan property accordingly. The current script broadcasts the default pre-signed transaction, which has a gas limit of 3,000,000 gas. If you want to use a different pre-signed transaction, you must change the import of the pre-signed transaction in the deploy.ts script.

cast

It is recommended to install Foundry via:

curl -L https://foundry.paradigm.xyz | bash
foundryup

To broadcast a pre-signed transaction, you can invoke:

# $TX is the pre-signed transaction.
# $RPC_URL is the RPC URL of the target chain to which you want to deploy.
cast publish $TX --rpc-url $RPC_URL

You must verify the CreateX contract separately, as specified in the next section.

[!IMPORTANT] After deployment, please open a pull request that updates the deployments.json file and the CreateX Deployments section with the new deployment so that other users can easily know that it has been deployed.

Contract Verification

To verify a deployed CreateX contract on a block explorer, use the following parameters:

• Verification Method / Compiler Type: Solidity (Standard JSON Input),
• Compiler Version: v0.8.23+commit.f704f362,
• Open Source License Type: GNU Affero General Public License (GNU AGPLv3),
• Standard Input JSON File: Upload the file here,
• Constructor Arguments ABI-Encoded: Leave empty.

[!IMPORTANT] We removed the metadata hash bytecodeHash from the bytecode in order to guarantee a deterministic compilation across all operating systems. This implies that all sourcify.eth verifications have partial verification, as opposed to perfect verification, which requires a matching metadata hash.

CreateX Deployments

📌 The deployment address of CreateX is 0xba5Ed099633D3B313e4D5F7bdc1305d3c28ba5Ed.

[!TIP] The complete list with additional chain information per deployment can be retrieved via createx.rocks. In addition, all sourcify.eth verification links (for the chains that are supported by sourcify.eth) can be found in the deployments.json file.

EVM-Based Production Networks

• Ethereum
• Binance Smart Chain
• Optimism
• Arbitrum One
• Arbitrum Nova
• Polygon
• Polygon zkEVM
• Fantom
• Avalanche
• Gnosis Chain
• Moonriver
• Moonbeam
• Celo
• Aurora
• Harmony
• Fuse Network
• Cronos
• Evmos
• Boba Network
• Canto
• Base
• Mantle
• Filecoin
• Scroll
• Linea
• Zora
• LUKSO
• Manta Pacific
• Blast
• DOS Chain
• Fraxtal
• Endurance
• Kava
• Metis Andromeda
• Mode
• X Layer
• BOB
• Core
• Telos
• Rootstock
• Chiliz
• Taraxa
• Gravity Alpha
• Taiko
• ZetaChain
• 5ireChain
• Oasis Sapphire
• World Chain
• XDC Network
• SX Network
• Lisk
• Metal L2

Ethereum Test Networks

• Sepolia
• Holešky (Holešovice)

Additional EVM-Based Test Networks

• Binance Smart Chain Testnet
• Optimism Sepolia Testnet
• Arbitrum Sepolia Testnet
• Polygon Sepolia Testnet (Amoy)
• Polygon Testnet (zkEVM)
• Fantom Testnet
• Avalanche Testnet (Fuji)
• Gnosis Chain Testnet (Chiado)
• Moonbeam Testnet (Moonbase Alpha)
• Celo Testnet (Alfajores)
• Aurora Testnet
• Harmony Testnet
• Fuse Network Testnet (Spark)
• Cronos Testnet
• Evmos Testnet
• Boba Network Testnet
• Canto Testnet
• Base Sepolia Testnet
• Mantle Sepolia Testnet
• Filecoin Testnet (Calibration)
• Scroll Sepolia Testnet
• Linea Sepolia Testnet
• Zora Sepolia Testnet
• LUKSO Testnet
• Manta Pacific Sepolia Testnet
• Blast Sepolia Testnet
• DOS Chain Testnet
• Fraxtal Holešky Testnet
• Metis Sepolia Testnet
• Mode Sepolia Testnet
• Sei Arctic Testnet
• X Layer Sepolia Testnet
• BOB Sepolia Testnet
• Core Testnet
• Telos Testnet
• Rootstock Testnet
• Chiliz Testnet (Spicy)
• Taraxa Testnet
• Taiko Holešky Testnet
• ZetaChain Testnet (Athens-3)
• 5ireChain Testnet
• Oasis Sapphire Testnet
• World Chain Sepolia Testnet
• Plume Sepolia Testnet
• Unichain Sepolia Testnet
• XDC Network Testnet (Apothem)
• SX Network Sepolia Testnet (Toronto)
• Lisk Sepolia Testnet
• Metal L2 Sepolia Testnet
• Superseed Sepolia Testnet

Integration With External Tooling

A list of external tooling that integrates with CreateX:

• xdeployer
• createx-forge
• createXcrunch
• hardhat-ignition

Community-Maintained Dune Dashboards

• CreateX Factory

🙏🏼 Acknowledgement

All the work has been done jointly by myself and Matt Solomon as a public good for our ecosystem. Public good software is not just code; it's the embodiment of collective progress, a testament to collaboration's power, and a canvas where innovation meets the needs of the many. I hope we can live up to these principles! 🫡