> ## 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 Tokenized RWAs OFT.

`NexusERC20` is an upgradeable ERC20 token designed for Tokenized RWAs OFT. Unlike [`ERC20Plus`](/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 Tokenized RWAs 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`, 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)

`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:

```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](/v2/developers/evm/stablecoin-oft/extensions#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](/v2/developers/evm/tokenized-rwas-oft/architecture) for how `NexusERC20` fits into Tokenized RWAs OFT
* [Modules](/v2/developers/evm/tokenized-rwas-oft/modules) for cross-chain fee, pause, and rate limiting
* [RBAC Reference](/v2/developers/evm/tokenized-rwas-oft/rbac-reference) for the complete role mapping