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

# Architecture

> Nexus OApp, NexusOFT wrappers, OFT registry, message encoding, and modular security.

Tokenized RWAs OFT is built around the Nexus contract — a single upgradeable OApp that owns all cross-chain messaging for multiple registered tokens. Each token gets a thin `NexusOFT` wrapper that exposes the standard `IOFT` interface, while the `Nexus` contract handles burn/mint, fee collection, and module delegation.

## System Overview

```
+--------------------------------------------------------------+
|  Pluggable Modules                                           |
|  NexusFeeConfigModule | NexusPauseModule | NexusRateLimiter  |
|  (independently upgradeable, admin-swappable)                |
+--------------------------------------------------------------+
|  Nexus Hub                                                   |
|  OApp + OFT Registry + FeeHandler                            |
|  (burn/mint, _lzSend/_lzReceive, module delegation)          |
+===========================+===========================+======+
|  NexusOFT (per token)     |  NexusOFT (per token)     |  ... |
|  IOFT -> delegates to hub |  IOFT -> delegates to hub |      |
+===========================+===========================+======+
|  NexusERC20 + NexusERC20Guard                                |
|  (shared allowlist + pause-by-token)                         |
+--------------------------------------------------------------+
```

## Core Contracts

### Nexus (Hub)

The Nexus contract is the only contract that interacts with the LayerZero endpoint. It handles OApp messaging, peer/delegate management, enforced options, fee deposit, and the OFT registry.

It stores three mutable module pointers:

```solidity theme={null}
INexusPause pauseModule;
INexusFeeConfig feeConfigModule;
INexusRateLimiter rateLimiterModule;
```

If a module is not set (`address(0)`), its extension is inactive — pause returns `false`, fee returns `0`, rate limiter capacity returns `type(uint256).max`.

### NexusOFT (Per-Token)

A stateless contract that implements `IOFT` by forwarding all calls to Nexus:

* `quoteOFT()` → `Nexus.nexusQuoteOFT()`
* `quoteSend()` → `Nexus.nexusQuoteSend()`
* `send()` → `Nexus.nexusSend()`

On the receive path, the Nexus contract calls `NexusOFT.nexusReceive()` to emit events and forward compose messages.

### NexusERC20 + NexusERC20Guard

See [NexusERC20](/v2/developers/evm/tokenized-rwas-oft/nexus-erc20) for the token layer.

## OFT Registry

Tokens are registered in the `Nexus` contract with a unique `uint32 tokenId` that maps to:

* An `oftAddress` (the `NexusOFT` wrapper)
* A `burnerMinterAddress` (the `NexusERC20` or a wrapper contract)

Registration validates that all tokens share the same local and shared decimals, the `NexusOFT.tokenId()` matches the registered `tokenId`, and no duplicate registrations exist.

## Nexus ID and Message Encoding

Cross-chain messages are encoded with a **4-byte `tokenId` prefix** via `NexusMsgCodec`, allowing Nexus to route messages for multiple tokens over a single OApp channel:

```
| tokenId (4 bytes) | sendTo (32 bytes) | amountSD (8 bytes) | [composeFrom + composeMsg] |
```

Modules identify pathways using a **composite Nexus ID**:

```
nexusId = (uint256(tokenId) << 32) | uint256(eid)
```

This encodes both the token and destination chain into a single `uint256`, enabling the 4-level priority resolution used by fee and pause modules. The rate limiter uses only the EID portion (per-destination).

## Module Delegation

On an outbound `nexusSend()`, Nexus delegates to modules in this order:

```
1. Pause        → _isPaused(nexusId) — reverts if paused
2. Fee          → _debitView() calculates fee via feeConfigModule
3. Rate Limiter → _outflow(nexusId, from, amountReceivedLD)
4. Burn         → burns amountSentLD from sender, mints fee to feeDeposit
5. _lzSend      → sends encoded message to LayerZero endpoint
```

On an inbound `_lzReceive()`:

```
1. Rate Limiter → _inflow(nexusId, to, amountLD)
2. Mint         → mints amountLD to recipient
3. Compose      → forwards compose message to NexusOFT if present
```

## Alt Variants

For chains where gas fees are paid via an ERC20 token (using `EndpointV2Alt`):

* `NexusAlt` — Hub variant that overrides `_payNative()` to no-op (native fee pushed by `NexusOFTAlt`)
* `NexusOFTAlt` — Wrapper that pushes both native ERC20 and LZ token fees to the endpoint before calling Nexus

## Upgradeability

All upgradeable contracts use EIP-7201 namespaced storage. `NexusOFT` is **not upgradeable** — it is a thin stateless wrapper with only immutable state.

The Nexus contract and each module can be upgraded independently through their respective proxies. Module addresses are mutable, so a new module deployment can be swapped in by `DEFAULT_ADMIN_ROLE` without upgrading the Nexus proxy.

## Next Steps

* [Modules](/v2/developers/evm/tokenized-rwas-oft/modules) for fee, pause, and rate limiter configuration
* [NexusERC20](/v2/developers/evm/tokenized-rwas-oft/nexus-erc20) for the token and guard layer
* [RBAC Reference](/v2/developers/evm/tokenized-rwas-oft/rbac-reference) for the complete role mapping