M0 Portals

Overview

Native Multichain $M

The core objective of M0's multichain strategy is to make the native $M token accessible across various blockchains beyond Ethereum mainnet. This aims to provide users with a consistent experience, particularly regarding yield-earning capabilities, regardless of the chain they operate on, while maintaining Ethereum as the authoritative source for $M issuance and governance.

M Portals are the set of smart contracts that facilitate this cross-chain functionality. They are responsible for bridging the $M token itself, as well as propagating essential system information like the yield index and governance parameters between Ethereum and connected Spoke chains.

To cater to different ecosystem needs and technical requirements, M0 offers two distinct implementations of the Portal system.

M Portal Implementations: Standard vs. Lite

M0 provides two portal versions built on different underlying technologies. While they share the same core goal of bridging $M and its metadata, they have key differences in architecture, features, and chain support.

1. M Portal (Standard): The original, feature-rich implementation built on the Wormhole Native Token Transfer (NTT) framework. It is designed for maximum compatibility, supporting both EVM and non-EVM chains (like Solana) and allowing for spoke-to-spoke transfers.
2. M Portal Lite: A streamlined, gas-efficient, and more modular implementation built on the Hyperlane messaging protocol. It is designed specifically for EVM-only environments, follows a stricter hub-and-spoke model (no spoke-to-spoke transfers), and introduces enhanced security mechanisms and a developer-friendly upgradeable design.

At a Glance: M Portal vs. M Portal Lite

The Hub-and-Spoke Model

Both M Portal implementations employ a Hub-and-Spoke architecture for multichain deployment:

• Hub Chain (Ethereum):
  • The single source of truth for the native $M token (where it's initially minted and governed).
  • Hosts the HubPortal contract.
  • Token Mechanism: Lock-and-Release. When bridging from the Hub, $M tokens are locked. When bridging back to the Hub, these locked tokens are released.
  • Acts as the source for propagating the $M Earning Index and TTG Registrar values.
  • (M Portal Lite Specific): The HubPortal also tracks the principal amount of $M bridged to each spoke chain to ensure it never releases more tokens than were locked for that specific spoke.
• Spoke Chains (e.g., Optimism, Arbitrum):
  • Host representations of the $M token.
  • Host SpokePortal contracts.
  • Token Mechanism: Mint-and-Burn. When bridging to a Spoke chain, a corresponding amount of $M representation is minted. When bridging from a Spoke chain, the $M representation is burned.
  • Receive and apply the $M Earning Index and TTG Registrar values propagated from the Hub.

This model ensures that the canonical $M supply originates and is controlled solely on Ethereum, while Spoke chains manage representations backed by the locked tokens on the Hub.

Key Components

Common Components

• User: The EOA or contract initiating or receiving cross-chain transfers.
• $M Token: The native ERC-20 compliant token contract deployed on Ethereum.
• Wrapped $M / Extensions: ERC-20 wrappers for $M that must implement wrap and unwrap functions.
• HubPortal (Ethereum): Manages locking/releasing of native $M and propagates metadata.
• SpokePortal (Spoke Chains): Manages minting/burning of the Spoke chain's $M representation and receives metadata.

M Portal (Wormhole) Specific Components

• Wormhole NTT Framework: The underlying technology. HubPortal and SpokePortal inherit from its NttManager contract.
• Wormhole Transceiver: A Wormhole contract on each chain that NttManager uses to send/receive low-level messages.
• Wormhole Core / Guardians / Relayers: The fundamental Wormhole infrastructure that validates and delivers messages (VAAs).
• MerkleTreeBuilder.sol: A contract used on the Hub to generate Merkle roots for propagating large datasets (like earner lists) efficiently to non-EVM chains like Solana.

M Portal Lite (Hyperlane) Specific Components

• IBridge.sol: A generic interface that decouples the Portal logic from the underlying bridge technology.
• HyperlaneBridge.sol: The implementation of IBridge that interacts with the Hyperlane protocol (IMailbox) to send and receive messages.
• Hyperlane Mailbox / Relayers: The core Hyperlane infrastructure for message dispatch, security, and delivery.
• Upgradeable Contracts: HubPortal and SpokePortal are built using the OpenZeppelin Upgrades pattern, allowing for proxy-based upgrades.

Core Bridging Process

The transfer of $M (or its extensions like Wrapped $M) between the Hub and Spoke chains follows a similar logical flow in both implementations, orchestrated by the Portals and their underlying messaging bridge.

Transfer: Hub Chain to Spoke Chain

1. User Interaction: The user initiates a transfer by calling a function on the HubPortal contract on Ethereum, specifying the destination chain and amount. Beforehand, users can call a function to get the estimated delivery fee for the cross-chain transaction.
   • M Portal (Standard): The function is quoteDeliveryPrice, inherited from the Wormhole NTT framework.
   • M Portal Lite: The function is quoteTransfer. After getting the fee and approving the HubPortal to spend their $M or Wrapped $M, the user makes the final transfer call.
2. Token Handling:
   • If the user transferred Wrapped $M, the HubPortal first unwraps it to the native $M token.
   • The native $M tokens are then locked within the HubPortal contract.
   • (M Portal Lite Specific): The HubPortal increments its internal bridgedPrincipal counter for the destination spoke chain.
3. Message Creation & Sending:
   • The HubPortal constructs a cross-chain message containing transfer details (amount, recipient, destination chain) and additional metadata (like the current $M Index).
   • It interacts with its configured bridge to send this message.
     • M Portal (Wormhole): Interacts with the Wormhole Transceiver via the NttManager logic.
     • M Portal Lite (Hyperlane): Interacts with the HyperlaneBridge contract, which dispatches via the Hyperlane Mailbox.
4. Cross-Chain Relaying (Offchain): The message is validated by the underlying bridge's security mechanism (Wormhole Guardians or Hyperlane ISMs). Once validated, the message is delivered to the destination Spoke chain.
5. Message Reception & Processing: The bridge contract on the Spoke chain receives the message and passes it to the SpokePortal.
6. Token Minting & Delivery:
   • The SpokePortal processes the message.
   • It mints the corresponding amount of the $M token representation on the Spoke chain.
   • If the original transfer was for Wrapped $M, the SpokePortal wraps the newly minted $M.
   • The final token is transferred to the recipient address on the Spoke chain.

Transfer: Spoke Chain to Hub Chain

This is largely the reverse process.

1. User Interaction: User calls the SpokePortal on a Spoke chain to send tokens back to the Hub.
2. Token Handling:
   • If transferring Wrapped $M, it's unwrapped to the native $M representation.
   • The native $M tokens are burned by the SpokePortal.
3. Message Creation & Sending: The SpokePortal sends a cross-chain message back to the Hub Chain (Ethereum).
4. Cross-Chain Relaying: The message is relayed back to Ethereum.
5. Message Reception & Processing: The bridge on Ethereum receives the message and passes it to the HubPortal.
6. Token Releasing & Delivery:
   • The HubPortal processes the message and releases (unlocks) the equivalent amount of native $M tokens.
   • (M Portal Lite Specific): The HubPortal first verifies that the requested release amount does not exceed the bridgedPrincipal for that source spoke chain. It then decrements the counter.
   • The released tokens (wrapped if necessary) are delivered to the recipient on Ethereum.

Transfer: Spoke Chain to Spoke Chain

• M Portal (Wormhole): Supported. This process involves burning tokens on the source Spoke and minting them on the destination Spoke, with a message relayed via Wormhole.
• M Portal Lite (Hyperlane): Not Supported. The system is strictly Hub-and-Spoke. To move assets between spokes, a user must first bridge back to the Hub (Ethereum) and then out to the new Spoke chain.

Metadata Propagation

Beyond token value, M Portals are crucial for synchronizing the M0 protocol state across chains. The purpose and data are the same for both implementations, but the transport mechanism differs.

• Purpose: To ensure yield calculations (``$M Earning Index) and governance parameters (TTG Registrar values) are consistent between the Hub and all Spoke chains.
• Propagated Data:
  • $M Earning Index: A continuously accruing value representing the aggregate yield earned within the M0 system on Ethereum. Propagating this allows the $M representation on Spoke chains to reflect the correct yield.
  • TTG Registrar Values: Key-value pairs stored in the Registrar contract on Ethereum, set by M0 governance (TTG). Examples include the EARNERS_LIST which dictates which addresses are eligible for yield. Propagation ensures Spoke chains respect Hub governance decisions.
• Propagation Mechanisms:
  • Implicit (with token transfers): Every token transfer message from the HubPortal automatically includes the current ``$M Earning Indexin its payload. The receivingSpokePortal uses this to update its local state.
  • Explicit (on-demand): Anyone can permissionlessly call functions on the HubPortal to send the latest metadata to a specific Spoke chain.
    • sendMTokenIndex(uint16 destinationChainId): Sends the current $M Index to a specific Spoke chain.
    • sendRegistrarKey(uint16 destinationChainId, bytes32 key): Sends a specific key from the Hub Registrar.
    • sendRegistrarListStatus(uint16 destinationChainId, bytes32 listKey, address entry): Sends the inclusion status of an address within a list.
  • Frequency: Explicit updates are often triggered periodically by automated bots to ensure timely synchronization even without user transfer activity.

Underlying Technology

Wormhole NTT (M Portal)

M Portal (Standard) is built using the Wormhole Native Token Transfer (NTT) framework.

• Integration: HubPortal and SpokePortal inherit from Wormhole's NttManager abstract contract. This provides the base functionality for interacting with Wormhole Transceivers, encoding/decoding messages, and handling standard NTT flows.
• Customization: M0 extends this base functionality to:
  • Implement the specific Lock/Release (Hub) and Mint/Burn (Spoke) logic.
  • Handle the automatic unwrap/wrap mechanism for $M extensions.
  • Inject the M0-specific metadata (like ``$M Earning Index) into the additionalPayload field of standard NTT messages.
  • Define and handle custom message types for explicit metadata propagation.
• Abstraction: Using the NTT framework allows M Portals to leverage Wormhole's established messaging infrastructure while focusing on M0-specific logic.

Hyperlane (M Portal Lite)

M Portal Lite uses Hyperlane as its messaging layer and features a more modular design.

• Integration: The Portal contracts do not inherit from a bridge-specific contract. Instead, they hold an address of a contract that implements the generic IBridge interface. The HyperlaneBridge.sol contract is the concrete implementation that connects the Portals to the Hyperlane protocol.
• Decoupling: This design decouples the token bridging logic from the cross-chain messaging logic. The Portals are only aware of the IBridge interface, making the system potentially adaptable to other messaging bridges in the future.
• Message Flow:
  1. A Portal contract calls sendMessage() on the configured HyperlaneBridge.
  2. HyperlaneBridge formats the message and dispatches it through the Hyperlane IMailbox contract.
  3. On the destination chain, the Hyperlane network delivers the message to the destination HyperlaneBridge by calling its handle() function.
  4. The destination HyperlaneBridge authenticates the message (verifying it comes from the Mailbox and a known peer) and then calls receiveMessage() on its local Portal contract, delivering the payload.

Developer Integration and Security

• Audits: The M Portal contracts have undergone security audits. Refer to linked audit reports for findings and details.
• Upgradeability:
  • M Portal Lite: Designed as an upgradeable system using the UUPS proxy pattern (via OpenZeppelin Upgrades).
  • M Portal (Standard): The contracts are also designed to be upgradeable.
• Security Dependencies:
  • M Portal (Wormhole): Security relies significantly on the integrity of the Wormhole Guardians and the NTT framework contracts.
  • M Portal Lite (Hyperlane): Security relies on the Hyperlane protocol, including its configured Interchain Security Modules (ISMs) and the correctness of the Hyperlane Relayer network.
• Key Security Feature (Lite): The bridgedPrincipal tracking in the HubPortal of M Portal Lite provides an additional layer of accounting security, ensuring that the Hub cannot be drained of more tokens than were originally locked for a given spoke chain.
• Code Repositories:
  • M Portal (Wormhole): github.com/m0-foundation/m-portal
  • M Portal Lite (Hyperlane): github.com/m0-foundation/m-portal-lite
• External Documentation:
  • Wormhole NTT Documentation: docs.wormhole.com/wormhole/ntt/overview
  • Hyperlane Documentation: docs.hyperlane.xyz
• Audit Reports:
  • M Portal (Wormhole): github.com/m0-foundation/m-portal/tree/main/audits
  • M Portal Lite (Hyperlane): github.com/m0-foundation/m-portal-lite/tree/main/audits