Skip to main content

Operator Allowlist

Operator Allowlist is a smart contract interface that enables token approvals and transfers to be restricted to allow listed users. This enables on-chain royalties to be enforced by restricting a contract's transfers to Immutable's version of the Seaport contract that honors royalties.


Key functionalityRecommended usage
  • Add or remove operators to the allowlist
  • Query allowlist for approved operators
  • Enabling token contracts to enforce royalties

Purpose of the Operator Allowlist

The Operator Allowlist serves a crucial purpose within Immutable's ecosystem, primarily aiming to shield game studios from potential vampire attacks. These attacks could otherwise enable trading on orderbooks or settlement smart contracts, creating avenues to bypass content creators' revenues, including royalties, and Immutable's 2% fee.

By implementing Immutable's Operator Allowlist within a collection, game studios can fortify their game economies against such threats. All collections are mandated to utilize the IOperatorAllowlist interface. It's noteworthy that all of Immutable's preset contracts inherently incorporate the Operator Allowlist as part of their default configuration.

All collections on Immutable's zkEVM are required to inherit OperatorAllowlistEnforced.sol to protect royalties and protocol fees. All preset and Immutable Developers Hub deployed contracts do this inherently.

How it works

ERC721 token smart contracts, such as Immutable's ERC721 Preset, can use the IOperatorAllowlist interface inside the contract to set an operator allowlist that limits approvals and transfers to a set of operators (see enforcement flows).

The allowlist serves as a registry containing a public list of authorized operators identified by their addresses. These addresses could be a specific contract address or its bytecode (the smart contract's compiled code). For example, a settlement contract would have its contract address allowlisted, and a smart contract wallet would have its bytecode allowlisted.

Approving smart contract proxy contracts

Additionally, as smart contract wallets are deployed as proxy contracts with a specific implementation contract module, they will need their implementation contract allowlisted. This means that for a smart contract wallet to be approved, it must have the bytecode of the proxy allowlisted as well as the address of the implementation contract that the proxy is forwarding to.

Who deploys and manages the allowlist?

Immutable will manage a deployed instance of the allowlist with a set of approved addresses. The set of approved addresses includes Immutable's Seaport and smart contract wallet deployments. It is recommended that collection owners use this registry instead of managing their own to avoid incurring gas fees for deploying and managing the contract.

Operator Allowlist values

The below table details the Operator Allowlist values for the operatorAllowlist parameter in Immutable's preset contracts:

Chain NameChain IDOperator Allowlist Address
imtbl-zkevm-testneteip155:134730x6b969FD89dE634d8DE3271EbE97734FEFfcd58eE
imtbl-zkevm-mainneteip155:133710x5F5EBa8133f68ea22D712b0926e2803E78D89221

Functionality

Access control

Management of the allowlist is done using access control (see below in Inheritance), where the REGISTRAR_ROLE is a role that can either add or remove entities from the allowlist. The DEFAULT_ADMIN_ROLE is the role responsible for granting and revoking the REGISTRAR_ROLE.

ERC165

The operator allowlist implements ERC165 (see below in Inheritance) to validate that interfacing token contracts when calling setOperatorAllowlistRegistry() supply an address that implements the IOperatorAllowlist interface.

Interfacing contracts

The operator allowlist defines an interface called IOperatorAllowlist which implements a single function, isAllowlisted(), to check whether the supplied address meets either of the following:

  • The address' contract address is within the allowlist
  • If the caller is a smart contract wallet, whether the bytecode of the proxy and the address of the implementation contract is within the allowlist

If either of these are satisfied, the address is within the allowlist. Token contracts which create an instance of IOperatorAllowlist, use isAllowlisted() to validate their approval and transfer functionality.

For approvals, the address which is being approved as an operator must be part of the allowlist. For transfers, the calling address must be within the allowlist. This will typically be the settlement contract.

Enforcement flows

approve(target) approveForAll(target)Allowed
Approval target is an EOATrue
Approval target is an address that has had its bytecode approvedTrue
Approval target is an address that has had its address approvedTrue
Approval target is an SC wallet that hasn't had its bytecode and implmentation approvedFalse
Approval target is a SC that hasn't had its address approvedFalse
transferFromAllowed
Caller is EOATrue
Caller is an SC wallet that hasn't had its bytecode and implmentation approvedTrue
Caller is a SC that has its address approved. For example, MarketplaceTrue
Caller is a SC wallet that hasn't had its bytecode approved and implmentationFalse
Caller is a SC that hasn't had its address approvedFalse

Interface

OperatorAllowlist.sol

FunctionDescription
isAllowlisted(target)Returns true if the targets contract address or bytecode is allowlisted, false otherwise
addAddressToAllowlist(addressTarget)Add the contract address of target address to the allowlist
removeAddressFromAllowlist(addressTarget)Remove the contract address of target address from the allowlist
addWalletToAllowlist(walletAddr)Add a smart contract wallet’s bytecode and implementation address to the allowlist
removeWalletFromAllowlist(walletAddr)Remove a smart contract wallet’s bytecode and implementation address from the allowlist
grantRegistrarRole(user)Grant registrar role to user
revokeRegistrarRole(user)Returns whether contract supports supplied interface ID

IOperatorAllowlist.sol

FunctionDescription
isAllowlisted(target)Returns true if the targets contract address or bytecode is allowlisted, false otherwise

Inheritance

Ethereum standard contracts

ContractFunctionality
AccessControl (code, EIP)Role setting (granting and revoking), role retrieval, role creation

IMX Whitepaper IMX Tokenomics Block Explorer Careers Contact Us