ORMP stands for Oracle Relayer Messaging Protocol. It is an omni-chain messaging protocol that can be used to build decentralized applications, or Dapps, that operate across multiple blockchains with minimal effort for developers. It's named after the two important roles involved in message cross-chaining:
  • The Oracle
    • In this context refers to any source of credible off-chain data. In ORMP, this data refers specifically to the root of an incremental merkle tree composed of cross-chain messages. We refer to this as the message root or msgroot for short. The message root is used to verify the authenticity of the cross-chain messages. The Oracle can either be a traditional off-chain data service, or a data feed based on the light client. Both of these methods can be used to provide the message root of another chain.
  • The Relayer
    • It’s an off-chain piece of software that's responsible for taking messages from one blockchain and relaying them to another. It queries the source chain to find messages that have not yet been relayed, and then relays the message and its proof to the target chain. Once the target chain receives the message, along with the msg_root provided by the Oracle, the target channel can verify the authenticity of the message and process it further if it is found to be valid.
These two roles play a vital role in the entire process of sending, verifying, and receiving messages.


  • The cross-chain application provides the option to choose a different Oracle and Relayer if the user does not trust the ones provided by the official team.
  • Messages are stored in an incremental Merkle tree, and the target chain relies on the tree root to validate the legitimacy of the received message.
  • The protocol does not guarantee the ordering of messages. However, the application has the option to maintain a nonce or a unique identifier to ensure that messages are received in the correct order, if ordering is necessary. This allows for ordered delivery of messages, even if the protocol itself doesn't provide that guarantee.

Messaging Design

Raw Message Structure

struct Message { address channel; // The messages channel to another chain. uint256 index; // The leaf index lives in channel's incremental mekle tree. uint256 fromChainId; // The source chain's chain id. address from; // The application address in the source chain. uint256 toChainId; // The target chain's chain id. address to; // The application address in the target chain. uint256 gasLimit; // The gas limit for destination application used. bytes encoded; // The eth-abi encoded message payload. }

Message Sending Flow

  1. The cross-chain application, built on the msgport, invokes the send method of the ORMP . This method is a payable method, meaning it requires the payment of a specific fee to execute. The fee structure is further explained below.
  1. Upon receiving the message, the ORMP contracts store it in an IMT (Incremental Merkle Tree) and emit the MessageAccepted event. Subsequently, it invokes the specified relayer and oracle to emit the Assigned event, signaling them to commence their respective tasks.
    1. 💡
      An incremental Merkle Tree is a Merkle Tree of fixed depth where each leaf start as a zero value, and non-zero values are added by replacing the zero leaves starting from the left-most leaf to the right-most leaf one-by-one. The Incremental Merkle Tree is a gas efficient Merkle Tree.
Once these two steps are completed, the message sending process is considered finished.

Message Relaying Flow

  1. The Relayer monitors its source chain for the emission of the "Assigned" event.
  1. Upon detecting this event, the Relayer retrieves the corresponding MessageAccepted event and extracts detailed information about the message from it through the ORMP contract. Subsequently, the Relayer fetches the latest AggregatedORMPData event from the oracle network, indicating the readiness of a specific message root. The Relayer then compares the block height of the message with the block height at which this message root was generated on the source chain. If the block height of the message root surpasses that of the message, it signifies that the message root is prepared.
  1. Following this verification, the Relayer calculates the proof of the message under this message root and proceeds to invoke the relay method on the Relayer contract on the target chain, completing the relay of the message and its proof.

Message Receiving Flow

When the relay method of the target chain contract is called, it first validates the message. If the validation is successful, the message is then sent to the corresponding user application. Unless an exception occurs, the user contract's method is invoked to complete the cross-chain task associated with the message. At this point, we can consider the cross-chain message to have reached its destination.

Cross-chain Fee

The fee for cross-chain messaging is paid in the native token of the source chain. The application can retrieve the cross-chain fee by calling the fee function in the msgport interface.
The total cross-chain fee consists of two parts: the oracle fee and the relayer fee. The oracle fee covers the cost of the message root oracle service. The relayer fee includes both the fee for relaying the message and the fee for executing the message on the target chain
If the fee paid exceeds the actual required fee, the excess amount will be refunded to the application.

Powered by Notaku