> ## 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

> Upgradeable ERC20 token with guard-delegated allowlist and pause, permit, and fund recovery for Multi-Asset OFT.

`NexusERC20` is an upgradeable ERC20 token designed for Multi-Asset OFT. Unlike [`ERC20Plus`](https://docs.layerzero.network/v2/developers/evm/stablecoin-oft/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

```solidity theme={null}
bytes32 public constant MINTER_ROLE = keccak256("MINTER_ROLE");
bytes32 public constant BURNER_ROLE = keccak256("BURNER_ROLE");
```

When used with Multi-Asset OFT, the **burner-minter address** (which can be the `NexusERC20` itself or a separate contract) must be granted both roles. Nexus calls mint/burn via configurable function selectors.

### Guard Checks

Every `transfer`, `transferFrom`, `mint`, and `burn` call goes through the guard:

```solidity theme={null}
guard.checkTransfer(address(this), msg.sender, _from, _to, _amount);
```

The guard enforces:

1. **Pause** — `_assertNotPaused(uint160(_token))`, keyed by the token's address
2. **Allowlist** — `_assertAllowlisted()` for caller, sender, and recipient (non-zero addresses)

On the cross-chain receive path, Nexus can [redirect credits](https://docs.layerzero.network/v2/developers/evm/multi-asset-oft/security-compliance.md#credit-redirect-for-non-allowlisted-recipients) to escrow when the intended recipient is not allowlisted.

### Fund Recovery

Same as `ERC20Plus` — addresses holding `DEFAULT_ADMIN_ROLE` can transfer tokens from non-allowlisted addresses:

```solidity theme={null}
function recoverFunds(address _from, address _to, uint256 _amount) public;
```

Reverts with `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](https://docs.layerzero.network/v2/developers/evm/stablecoin-oft/extensions.md#allowlist)
* **PauseByIDRBACUpgradeable** — Per-token pause using `uint160(tokenAddress)` as the pause ID

### Initialization

```solidity theme={null}
function initialize(address _initialAdmin) public initializer;
```

Initializes with `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 |

Mode transitions do not clear existing lists. Both lists support paginated enumeration via `getBlacklist(offset, limit)` and `getWhitelist(offset, limit)`.

## Next Steps

* [Architecture](https://docs.layerzero.network/v2/developers/evm/multi-asset-oft/architecture.md) for how `NexusERC20` fits into Multi-Asset OFT
* [Modules](https://docs.layerzero.network/v2/developers/evm/multi-asset-oft/modules.md) for cross-chain fee, pause, and rate limiting
* [RBAC Reference](https://docs.layerzero.network/v2/developers/evm/multi-asset-oft/rbac-reference.md) for the complete role mapping