Documentation Index
Fetch the complete documentation index at: https://docs.layerzero.network/llms.txt
Use this file to discover all available pages before exploring further.
NexusERC20 is an upgradeable ERC20 token designed for Tokenized RWAs OFT. Unlike ERC20Plus which embeds allowlist and pause logic directly, NexusERC20 delegates these checks to a shared NexusERC20Guard contract — one guard serving multiple tokens.
Comparison with ERC20Plus
| Feature | ERC20Plus | NexusERC20 |
|---|
| Allowlist (3-mode) | Inline | Delegated to NexusERC20Guard |
| Pause | Global (inline) | Per-token via guard (PauseByID, keyed by uint160(token)) |
| Fund recovery | Yes | Yes |
| ERC20Permit (EIP-2612) | Yes | Yes |
| RBAC mint/burn | Yes | Yes |
| Guard contract | N/A | Shared across tokens |
| Upgradeable | Yes (EIP-7201) | Yes (EIP-7201) |
NexusERC20
Roles
bytes32 public constant MINTER_ROLE = keccak256("MINTER_ROLE");
bytes32 public constant BURNER_ROLE = keccak256("BURNER_ROLE");
NexusERC20 itself or a separate contract) must be granted both roles. Nexus calls mint/burn via configurable function selectors.
Guard Checks
Every transfer, transferFrom, and burn call goes through the guard:
guard.checkTransfer(address(this), msg.sender, _from, _to, _amount);
- Pause —
_assertNotPaused(uint160(_token)), keyed by the token’s address
- Allowlist —
_assertAllowlisted() for caller, sender, and recipient (non-zero addresses)
mint does not enforce checks — funds cannot be debited from a non-allowlisted address or when the contract is paused, so restricting inflows is unnecessary.
Fund Recovery
Same as ERC20Plus — addresses holding DEFAULT_ADMIN_ROLE can transfer tokens from non-allowlisted addresses:
function recoverFunds(address _from, address _to, uint256 _amount) public;
CannotRecoverFromAllowlisted if _from is allowlisted.
ERC20Permit (EIP-2612)
Built-in gasless approvals, identical to ERC20Plus.
NexusERC20Guard
A single upgradeable guard shared by all NexusERC20 tokens on the same chain.
What It Does
The guard combines two concerns:
- AllowlistRBACUpgradeable — Three-mode allowlist (Open / Blacklist / Whitelist) with the same behavior as Stablecoin OFT’s allowlist
- PauseByIDRBACUpgradeable — Per-token pause using
uint160(tokenAddress) as the pause ID
Initialization
function initialize(address _initialAdmin) public initializer;
AllowlistMode.Open (no transfer restrictions).
Roles
| Role | Source | Used For |
|---|
DEFAULT_ADMIN_ROLE | AccessControl2StepUpgradeable | Admin transfer, set allowlist mode |
BLACKLISTER_ROLE | AllowlistRBACUpgradeable | Blacklist addresses |
WHITELISTER_ROLE | AllowlistRBACUpgradeable | Whitelist addresses |
PAUSER_ROLE | PauseByIDRBACUpgradeable | setDefaultPaused (when pausing), setPaused (when effectively pausing by token address as ID) |
UNPAUSER_ROLE | PauseByIDRBACUpgradeable | setDefaultPaused (when unpausing), setPaused (when effectively unpausing or no-op) |
Allowlist Modes
| Mode | Behavior |
|---|
| Open | No restrictions |
| Blacklist | Block specific addresses |
| Whitelist | Allow only specific addresses |
getBlacklist(offset, limit) and getWhitelist(offset, limit).
Next Steps
