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 functionality | Recommended usage |
|---|---|
|
|
Purpose of the Operator Allowlist
The Operator Allowlist is a key component within Immutable's ecosystem, designed to protect game studios from potential vampire attacks. These attacks could exploit trading on unauthorized order books or settlement smart contracts, potentially bypassing content creators' revenues, including royalties, and Immutable's 2% fee.
By integrating Immutable's Operator Allowlist into a collection, game studios can safeguard their game economies from such threats. All collections on Immutable's zkEVM are required to implement the IOperatorAllowlist interface.
To ensure protection of royalties and protocol fees, every collection on Immutable's zkEVM must inherit from OperatorAllowlistEnforced.sol.
All preset contracts and those deployed via the Immutable Developers Hub have this protection built-in by default.
If you are using a custom collection, refer to this guide for instructions on how to implement the Operator Allowlist in your contract.
How it works
ERC721 and ERC1155 smart contracts, such as Immutable's ERC721 and ERC1155 presets, 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.
How do I request to be added to the operator allowlist (OAL)?
You can request to be added to the allowlist via Immutable Hub.
Log into Immutable Hub
Verify your contract via Immutable's explorer. For more information on verifying your smart contract on Immutable's Explorer check out this guide.
Link your smart contract by clicking Link Contract on the "Contracts" page in Immutable Hub.
- Go to the contract details page of the contract that you want to be added to OAL. And hit the Add to OAL button.
- Follow the instructions provided in the OAL request drawer and submit your request. Once submitted, approval on the testnet typically takes seconds, while approval on the mainnet involves a manual process that may take up to one week.
Operator Allowlist values
The below table details the Operator Allowlist values for the operatorAllowlist parameter in Immutable's preset contracts:
| Chain Name | Chain ID | Operator Allowlist Address |
|---|---|---|
imtbl-zkevm-testnet | eip155:13473 | https://api.sandbox.immutable.com/v1/chains returns operator_allowlist_address |
imtbl-zkevm-mainnet | eip155:13371 | https://api.immutable.com/v1/chains returns operator_allowlist_address |
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 EOA | True |
| Approval target is an address that has had its bytecode approved | True |
| Approval target is an address that has had its address approved | True |
| Approval target is an SC wallet that hasn't had its bytecode and implmentation approved | False |
| Approval target is a SC that hasn't had its address approved | False |
| transferFrom | Allowed |
|---|---|
| Caller is EOA | True |
| Caller is an SC wallet that hasn't had its bytecode and implmentation approved | True |
| Caller is a SC that has its address approved. For example, Marketplace | True |
| Caller is a SC wallet that hasn't had its bytecode approved and implmentation | False |
| Caller is a SC that hasn't had its address approved | False |
Interface
OperatorAllowlist.sol
| Function | Description |
|---|---|
| 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
| Function | Description |
|---|---|
| isAllowlisted(target) | Returns true if the targets contract address or bytecode is allowlisted, false otherwise |
Inheritance
Ethereum standard contracts
| Contract | Functionality |
|---|---|
| AccessControl (code, EIP) | Role setting (granting and revoking), role retrieval, role creation |