Contract Presets

Immutable provides a set of preset contracts than can be used by customers to deploy known, battle-tested contracts to the zkEVM.

Immutable's preset contracts are equipped with features purpose-built for Web3 gaming, simplifying the integration process with Immutable's zkEVM platform.

These contracts can be deployed seamlessly via the Immutable Hub. For a comprehensive understanding of these contracts, please review the detailed documentation provided for each contract listed below.

We encourage you to delve into the capabilities offered by our ERC721 and ERC1155 preset contract, meticulously crafted to enhance the efficiency of game development on our platform.

Smart Contracts Deployed

Key smart contracts in the Immutable ecosystem are deployed at addresses listed here

Explore the smart contracts deployed on Immutable's zkEVM Mainnet via the Explorer

🛠️Deprecation Notice

The Immutable zkEVM contracts package, @imtbl/zkevm-contracts, was recently deprecated. Please use the new Immutable Smart Contracts monorepo @imtbl/contracts where the zkEVM contracts have been moved to.

List of zkEVM Immutable Preset Contracts

Contract	Type	Purpose	Useful For
ERC20	Game Token Contract	Creating fungible tokens for your game. These tokens are typically traded on traditional centralized crypto exchanges, with all assets in an ERC20 contract being identical.	Currency tokens, traditionally on centralized crypto exchanges Funding your game through pre-launch token sales Creating in-game currencies
ERC721-Recommended	Game Asset Collection	Immutable's recommended smart contract for creating non-fungible assets (NFTs) for your game. Each asset has a unique `token_id`, and a single collection can contain different types of assets. This contract offers multiple batch minting functions for various gaming use cases. Implements the Operator Allowlist	NFTs Primary Sales In-game assets that are unique High value assets Minting where the minter can request the next `token_id` Minting where the system generates the `token_id`
ERC721-Mint By ID	Game Asset Collection	A limited ERC721 collection with fewer batch minting functions. While less versatile than the recommended preset, it's useful when all mints will use the less gas-efficient minting function where the minter specifies the `token_id` pre-mint. Implements the Operator Allowlist	NFTs Primary Sales In-game assets that are unique High value assets Minting where the minter can request the next `token_id`
ERC721-Base	Game Asset Collection	The base ERC721 contract that all Immutable ERC721 presets inherit from. This documentation should be used as a reference, but the collection should not be deployed without adding additional features from either Immutable or your game.	Base contract reference, not for standalone deployment.
ERC1155	Game Asset Collection	Immutable's recommended smart contract for creating semi-fungible assets (SFTs) for your game. Most in-game assets are semi-fungible, making this the most practical gaming asset contract. A single collection can contain different types of assets, with each `token_id` delineating a different asset. Implements the Operator Allowlist	SFTs Best for in-game assets that are not unique More gas-efficient than ERC721 for handling multiple asset transactions Low value assets like consumables
Multicaller	Utility Contract	A utility contract that batches multiple events into a single transaction.	Batching events involving multiple assets from different collections in a single atomic transaction Crafting operations
Fee Splitter	Utility Contract	A utility contract that collects ERC20 tokens sent to it. When prompted, it will release a specific ERC20 token, or all ERC20 tokens, to a predetermined list of recipients in a pre-determined ratio.	Paying multiple royalty recipients Rewarding team members with ERC20 tokens Splitting fees between multiple recipients
Permits	Contract Feature	A feature in Immutable's presets that can be used instead of approvals. Permits do not require gas until the permitted action is executed, unlike approvals that incur gas fees immediately when granted.	Gasless listings Crafting operations

zkEVM Collection Requirements: Operator Allowlist

All in-game asset collections (i.e. ERC721 and ERC1155) deployed on Immutable's zkEVM must utilise the operator allowlist to protect content creator (eg: you, the game studio's) royalty fees and Immutable's 2% protocol fees.

This can be achieved through embedding the following into your smart contract collection designs:

Recommended Approach

For seamless implementation use or inherit Immutable's preset contracts tailored for gas-efficient creation of Web3 gaming assets on the zkEVM network. Immutable offers the following 3 preset contracts; these contracts implement the Operator Allowlist:

Recommended Presets for Web3 Games:
- ImmutableERC721.sol - Multiple batch minting functions for optimised gas efficiency. Compatible with Minting API. Multiple batch minting functions for offering gas efficiencies for different Web3 gaming use cases.
- ImmutableERC1155.sol. Semi-fungible tokens. Compatible with Minting API.
Alternative Presets:
- ImmutableERC721MintByID.sol. Single batch minting function requiring game studio to specify token_id at time of mint. Optimised for gas, yet less gas efficient than ImmutableERC721.sol. Compatible with Minting API.

Minimally Required Standard

If the above options are not compatible with your game design, it is mandatory for your collection to inherit the OperatorAllowlistEnforced.sol contract and adding necessary overrides to approve and transfer functions, allowing your collection to interact with the OperatorAllowlist. OperatorAllowlistEnforced includes the modifier functions to identify compliant smart contracts for approvals and transfers, ensuring the preservation of content creators’ royalty fees and protocol fees in third-party marketplace transactions.

If your game design restricts your collections from importing Immutable's preset contracts, please note that your request for inclusion on the Mainnet's deployer allowlist may undergo additional processing time. Immutable will conduct thorough verification to ensure that your collections comply with our mandated standards, safeguarding content creators on the network. Thank you for your understanding and cooperation in ensuring Immutable's zkEVM network remains secure for our web3 gaming community.

Example contracts using OpenZeppelin's ERC721 and ERC1155 standards with the OperatorAllowlistEnforced contract are provided below:

ERC721
ERC721 Upgradable
ERC1155
ERC1155 Upgradable

Below is an example ClashOfCatsERC721 contract that inherits our OperatorAllowlistEnforced:

// SPDX-License-Identifier: UNLICENSED
pragma solidity 0.8.19;

import '@openzeppelin/contracts/token/ERC721/ERC721.sol';
import {Ownable} from '@openzeppelin/contracts/access/Ownable.sol';
import {OperatorAllowlistEnforced} from '@imtbl/contracts/contracts/allowlist/OperatorAllowlistEnforced.sol';

contract ClashOfCatsERC721 is ERC721, Ownable, OperatorAllowlistEnforced {
  constructor(
    string memory name,
    string memory symbol,
    address operatorAllowlist_
  ) ERC721(name, symbol) Ownable() {
    // OAL address is set in the constructor
    _setOperatorAllowlistRegistry(operatorAllowlist_);
  }

  // Overrides _approve function to include `validateApproval` modifier for OAL
  function _approve(
    address to,
    uint256 tokenId
  ) internal override(ERC721) validateApproval(to) {
    super._approve(to, tokenId);
  }

  // Overrides setApprovalForAll function to include `validateApproval` modifier for OAL
  function setApprovalForAll(
    address operator,
    bool approved
  ) public override(ERC721) validateApproval(operator) {
    super.setApprovalForAll(operator, approved);
  }

  // Overrides _transfer function to include `validateTransfer` modifier for OAL
  function _transfer(
    address from,
    address to,
    uint256 tokenId
  ) internal override(ERC721) validateTransfer(from, to) {
    super._transfer(from, to, tokenId);
  }
}

Below is an example ClashOfCatsERC721Upgradable contract that inherits our OperatorAllowlistEnforced:

pragma solidity 0.8.19;

import '@openzeppelin/contracts-upgradeable/token/ERC721/ERC721Upgradeable.sol';
import {Ownable} from '@openzeppelin/contracts/access/Ownable.sol';
import {OperatorAllowlistEnforced} from '@imtbl/contracts/contracts/allowlist/OperatorAllowlistEnforced.sol';

contract ClashOfCatsERC721Upgradable is
  ERC721Upgradeable,
  OperatorAllowlistEnforced
{
  function initialize(
    string memory name_,
    string memory symbol_,
    address operatorAllowlist_
  ) public initializer {
    __ERC721_init(name_, symbol_);
    // OAL address is set in the constructor
    _setOperatorAllowlistRegistry(operatorAllowlist_);
  }

  // Overrides approve function to include `validateApproval` modifier for OAL
  function approve(
    address to,
    uint256 tokenId
  ) public virtual override(ERC721Upgradeable) validateApproval(to) {
    super.approve(to, tokenId);
  }

  // Overrides setApprovalForAll function to include `validateApproval` modifier for OAL
  function setApprovalForAll(
    address operator,
    bool approved
  ) public virtual override(ERC721Upgradeable) validateApproval(operator) {
    super.setApprovalForAll(operator, approved);
  }

  // Overrides _safeTransfer function to include `validateTransfer` modifier for OAL
  function _safeTransfer(
    address from,
    address to,
    uint256 tokenId,
    bytes memory _data
  ) internal virtual override(ERC721Upgradeable) validateTransfer(from, to) {
    super._safeTransfer(from, to, tokenId, _data);
  }

  // Overrides transferFrom function to include `validateTransfer` modifier for OAL
  function transferFrom(
    address from,
    address to,
    uint256 tokenId
  ) public virtual override(ERC721Upgradeable) validateTransfer(from, to) {
    super.transferFrom(from, to, tokenId);
  }
}

Below is an example ClashOfCatsERC1155 contract that inherits our OperatorAllowlistEnforced:

// SPDX-License-Identifier: UNLICENSED
pragma solidity 0.8.19;

import '@openzeppelin/contracts/token/ERC1155/ERC1155.sol';
import {Ownable} from '@openzeppelin/contracts/access/Ownable.sol';
import {OperatorAllowlistEnforced} from '@imtbl/contracts/contracts/allowlist/OperatorAllowlistEnforced.sol';

contract ClashOfCatsERC1155 is ERC1155, Ownable, OperatorAllowlistEnforced {
  constructor(
    string memory baseTokenURI,
    address operatorAllowlist_
  ) ERC1155(baseTokenURI) Ownable() {
    // OAL address is set in the constructor
    _setOperatorAllowlistRegistry(operatorAllowlist_);
  }

  // Overrides _safeTransferFrom function to include `validateTransfer` modifier for OAL
  function _safeTransferFrom(
    address from,
    address to,
    uint256 id,
    uint256 value,
    bytes memory data
  ) internal override validateTransfer(from, to) {
    super._safeTransferFrom(from, to, id, value, data);
  }

  // Overrides _safeBatchTransferFrom function to include `validateTransfer` modifier for OAL
  function _safeBatchTransferFrom(
    address from,
    address to,
    uint256[] memory ids,
    uint256[] memory values,
    bytes memory data
  ) internal override validateTransfer(from, to) {
    super._safeBatchTransferFrom(from, to, ids, values, data);
  }

  // Overrides setApprovalForAll function to include `validateApproval` modifier for OAL
  function setApprovalForAll(
    address operator,
    bool approved
  ) public override(ERC1155) validateApproval(operator) {
    super.setApprovalForAll(operator, approved);
  }
}

Below is an example ClashOfCatsERC1155Upgradable contract that inherits our OperatorAllowlistEnforced:

// SPDX-License-Identifier: UNLICENSED
pragma solidity 0.8.19;

import '@openzeppelin/contracts-upgradeable/token/ERC1155/ERC1155Upgradeable.sol';
import {Ownable} from '@openzeppelin/contracts/access/Ownable.sol';
import {OperatorAllowlistEnforced} from './OperatorAllowlistEnforced.sol';

contract ClashOfCatsERC1155Upgradable is
  ERC1155Upgradeable,
  OperatorAllowlistEnforced
{
  function initialize(
    string memory uri_,
    address operatorAllowlist_
  ) public initializer {
    __ERC1155_init(uri_);
     // OAL address is set in the constructor
    _setOperatorAllowlistRegistry(operatorAllowlist_);
  }

  // Overrides _safeTransferFrom function to include `validateTransfer` modifier for OAL
  function _safeTransferFrom(
    address from,
    address to,
    uint256 id,
    uint256 value,
    bytes memory data
  ) internal override(ERC1155Upgradeable) validateTransfer(from, to) {
    super._safeTransferFrom(from, to, id, value, data);
  }

  // Overrides _safeBatchTransferFrom function to include `validateTransfer` modifier for OAL
  function _safeBatchTransferFrom(
    address from,
    address to,
    uint256[] memory ids,
    uint256[] memory values,
    bytes memory data
  ) internal override(ERC1155Upgradeable) validateTransfer(from, to) {
    super._safeBatchTransferFrom(from, to, ids, values, data);
  }

  // Overrides setApprovalForAll function to include `validateApproval` modifier for OAL
  function setApprovalForAll(
    address operator,
    bool approved
  ) public override(ERC1155Upgradeable) validateApproval(operator) {
    super.setApprovalForAll(operator, approved);
  }
}

💡Operator Allowlist Checklist

Here is a simple collection operator allowlist checklist you should follow to ensure your game has no delays at launch:

Have you imported OperatorAllowlistEnforced.sol?
Have you implemented the allowlist check on transfers?
Have you implemented the allowlist check on approvals?

note

The use of the preset contracts accelerates integration with Immutable's ecosystem. If your studio has developed custom ERC721 or ERC1155 collections, ensure they adhere to their respective standards in addition to inheriting the OperatorAllowlistEnforced.sol contract, to safeguard compatibility with Immutable's ecosystem.

Contract Presets

List of zkEVM Immutable Preset Contracts​

zkEVM Collection Requirements: Operator Allowlist​

Recommended Approach​

Minimally Required Standard​

List of zkEVM Immutable Preset Contracts

zkEVM Collection Requirements: Operator Allowlist

Recommended Approach

Minimally Required Standard