[TOC]
This rule restricts transfers so that only whitelisted addresses may send and receive tokens. Optionally, spender addresses (used in transferFrom) can also be checked.
| Parameter | Description |
|---|---|
admin |
Address granted DEFAULT_ADMIN_ROLE (implicitly holds all roles) |
forwarderIrrevocable |
ERC-2771 trusted forwarder address for meta-transactions (use address(0) to disable) |
checkSpender_ |
If true, transferFrom spender address is also verified against the whitelist |
allowMintBurn |
If true, pre-lists address(0) at deployment to allow mint/burn flows without a post-deploy addAddress(address(0)) call |
When checkSpender is true, the spender in a transferFrom call must also be whitelisted. This flag can be toggled post-deployment by the admin with setCheckSpender(bool).
| Constant | Code | Meaning |
|---|---|---|
CODE_ADDRESS_FROM_NOT_WHITELISTED |
21 | Sender is not in the whitelist |
CODE_ADDRESS_TO_NOT_WHITELISTED |
22 | Recipient is not in the whitelist |
CODE_ADDRESS_SPENDER_NOT_WHITELISTED |
23 | Spender is not in the whitelist (only when checkSpender is enabled) |
The default admin is the address passed as admin in the constructor. It is granted DEFAULT_ADMIN_ROLE, which implicitly holds all roles.
| Role | Description |
|---|---|
DEFAULT_ADMIN_ROLE |
Manages all roles; can call all privileged functions |
ADDRESS_LIST_ADD_ROLE |
May add addresses to the whitelist (addAddress, addAddresses) |
ADDRESS_LIST_REMOVE_ROLE |
May remove addresses from the whitelist (removeAddress, removeAddresses) |
Adds a single address to the whitelist. Reverts if the address is already listed.
Batch-adds addresses to the whitelist. Silently skips duplicates (no revert).
Removes a single address from the whitelist. Reverts if the address is not listed.
Batch-removes addresses from the whitelist. Silently skips addresses not listed (no revert).
Returns true if the address is in the whitelist.
Returns a boolean array indicating whitelist membership for each address.
Enables or disables spender checks for transferFrom. Restricted to DEFAULT_ADMIN_ROLE.
The zero address (address(0)) may be added to the whitelist. This is required by CMTAT to allow minting (mints are transfer(address(0), to, value)) and burning (to == address(0)). You can either set allowMintBurn=true in the constructor to pre-list address(0), or add it later with addAddress(address(0)). OpenZeppelin prevents actual ERC-20 transfers to or from the zero address, so this does not create a security issue.
Single-item operations (addAddress, removeAddress) revert on duplicate/missing input. Batch operations (addAddresses, removeAddresses) skip invalid entries silently to allow partial lists without full rollback.
The operator deploys RuleWhitelist, grants ADDRESS_LIST_ADD_ROLE to a compliance manager, and registers the rule in the RuleEngine. The compliance manager calls addAddresses([alice, bob]). Transfers between whitelisted addresses pass; any transfer from or to an unlisted address is rejected with codes 21 or 22.