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 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 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 Name | Chain ID | Operator Allowlist Address |
|---|---|---|
imtbl-zkevm-testnet | eip155:13473 | 0x6b969FD89dE634d8DE3271EbE97734FEFfcd58eE |
imtbl-zkevm-mainnet | eip155:13371 | 0x5F5EBa8133f68ea22D712b0926e2803E78D89221 |
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 |