Skip to main content
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: 
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 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