Overview

The Msgport layer is a simplified abstract layer that provides essential interfaces for various message lines established between two chains. Apart from the interfaces, it contains a message line registry. This document will guide you through several significant concepts within this layer and outline the workflow for sending messages.

Concepts

IMessageLine Interface

The IMessageLine interface in the Msgport layer is designed to encapsulate messaging protocols for dApp developers. It provides a unified interface for sending cross-chain messages using different messaging protocols. The interface has two essential functions: send() and fee(). The Msgport layer supports multiple message lines that implement this interface, such as ORMP, lCMP, XCMP, etc. The code snippet below provides a comprehensive explanation of the function usage. If you have any questions, feel free to ask in our technical discord.

solidity
// https://github.com/darwinia-network/darwinia-msgport/blob/main/src/interfaces/IMessageLine.sol

// This file is part of Darwinia.
// Copyright (C) 2018-2023 Darwinia Network
// SPDX-License-Identifier: GPL-3.0
//
// Darwinia is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// Darwinia is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with Darwinia. If not, see <https://www.gnu.org/licenses/>.

pragma solidity ^0.8.0;

interface IMessageLine {
    error MessageFailure(bytes errorData);

    /// @dev Send a cross-chain message over the MessageLine.
    /// @notice Send a cross-chain message over the MessageLine.
    /// @param toChainId The message destination chain id. <https://eips.ethereum.org/EIPS/eip-155>
    /// @param toDapp The user application contract address which receive the message.
    /// @param message The calldata which encoded by ABI Encoding.
    /// @param params Extend parameters to adapt to different message protocols.
    function send(uint256 toChainId, address toDapp, bytes calldata message, bytes calldata params) external payable;

    /// @notice Get a quote in source native gas, for the amount that send() requires to pay for message delivery.
    ///         It should be noted that not all lines will implement this interface.
    /// @dev If the messaging protocol does not support on-chain fetch fee, then revert with "Unimplemented!".
    /// @param toChainId The message destination chain id. <https://eips.ethereum.org/EIPS/eip-155>
    /// @param toDapp The user application contract address which receive the message.
    /// @param message The calldata which encoded by ABI Encoding.
    /// @param params Extend parameters to adapt to different message protocols.
    function fee(uint256 toChainId, address toDapp, bytes calldata message, bytes calldata params)
        external
        view
        returns (uint256);
}

LineRegistry

The LineRegistry serves as a registry for MessageLines between the source and target chains. It is maintained by a decentralized entity called MsgDao. Each line in the registry has a unique name and undergoes a thorough audit and registration process through governance. Once registered, DApp developers can leverage these message lines to build powerful cross-chain applications. This decentralized approach ensures transparency and trust in the messaging infrastructure, allowing developers to confidently utilize the registered lines for their application needs.

solidity
// https://github.com/darwinia-network/darwinia-msgport/blob/main/src/LineRegistry.sol

// This file is part of Darwinia.
// Copyright (C) 2018-2023 Darwinia Network
// SPDX-License-Identifier: GPL-3.0
//
// Darwinia is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// Darwinia is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with Darwinia. If not, see <https://www.gnu.org/licenses/>.

pragma solidity ^0.8.17;

import "@openzeppelin/contracts/access/Ownable2Step.sol";
import "./interfaces/ILineMetadata.sol";

/// @title LineRegistry
/// @notice LineRegistry will be deployed on each chain.
///         It is the registry of messageLine and can be used to verify whether the line has been registered.
contract LineRegistry is Ownable2Step {
    event AddLine(string name, address line);

    string[] private _names;
    // lineName => lineAddress
    mapping(string => address) private _lineLookup;

    constructor(address dao) {
        _transferOwnership(dao);
    }

    function count() public view returns (uint256) {
        return _names.length;
    }

    function list() public view returns (string[] memory) {
        return _names;
    }

    function getLine(string calldata name) external view returns (address) {
        return _lineLookup[name];
    }

    function addLine(address line) external onlyOwner {
        string memory name = ILineMetadata(line).name();
        require(_lineLookup[name] == address(0), "Line name already exists");
        _names.push(name);
        _lineLookup[name] = line;
        emit AddLine(name, line);
    }
}

Msgport API

The Msgport API is an independent tool designed to aid the Msgport Apps in gathering supplementary information during the message delivery process. As of now, its sole function is to estimate the cross-chain fee in the native coin format. This fee represents the cross-chain expenses that Dapps are obligated to cover.

Beyond providing fee information, the API also delivers associated parameter data. These parameters are necessary for the messaging layer, which is the cross-chain messaging protocol employed by Msgport. Simply put, these parameters are the directives required by the messaging protocol's relayer to carry out cross-chain operations on the destination chain.

Sending message workflow

Obtain the message line endpoint address.

To obtain the endpoint for a specific message line, you have two options:

Retrieve the endpoint from the Supported Networks. This information is readily available and can be accessed directly.

Query the LineRegistry contract using the lineRegistry.getLine(string protocolName) function. This will allow you to obtain the endpoint for the desired chain by providing the protocol name as a parameter. The LineRegistry contract maintains a comprehensive record of registered lines and their associated endpoints, making it a reliable source of information.

Retrieve the fee and adapter params from the Msgport API.

Send message using message line.

toChainId: Use the standard EVM chainId, see Supported Networks

toDapp: The address of your receiver DApp.

message: The payload of your message.

params: Adapter params obtained from the Msgport API in step 2.

solidity
messageLine.send(toChainId, toDapp, message, params);

Verify the received message.

Sometimes, it's necessary to verify the senderLine and senderDapp addresses when receiving the message before dispatch. Check this example for reference.