Skip to main content

Interchain Messaging Facility (ICMF)

This documentation is for dapp developers looking to integrate the Interchain Messaging Facility (ICMF) into their decentralized applications. ICMF facilitates cross-chain communication, enabling interaction between blockchains without direct client involvement. This guide will walk you through sending and receiving ICMF messages in your dapps.

ICMF operates similarly to a message queue, allowing chains to emit events on specific topics or subscribe to multiple topics. It's an essential part of Chromia's architecture to enable blockchain communication without client involvement.

Sending a message using ICMF in Rell is straightforward, but what happens under the hood?

  1. The sender dapp calls the function send_message from the ICMF Rell library. This can be triggered either by a user operation or by the dapp itself.
  2. This triggers an event on the node, which is then sent to the cluster's anchoring chain.
  3. The receiver node checks for messages on subscribed topics before building each block.
  4. When a message is detected, the node invokes the __icmf_message special operation on the dapp.
  5. The function receive_icmf_message is called by the ICMF Rell library, executing any logic defined by the dapp.

In this context, this messaging system is ideal for dapps that need chains to broadcast the completion of an action. Other chains can then subscribe to these broadcasts and respond accordingly, allowing for scalable solutions where new chains subscribe to relevant topics without requiring changes to the sender chain's logic.

Topics in ICMF​

ICMF messages are organized around topics, acting as communication channels that direct messages to their intended recipients. When working with ICMF topics, consider the following guidelines:

  • All topics in ICMF must start with L_. This prefix signifies that the message is sent within your local blockchain network.

  • Only system chains can send messages on a global level.

Send messages​

Integration steps​

To enable your blockchain to send ICMF messages, add the ICMF Sender GTX module to your blockchain configuration.

  1. Open your blockchain's configuration file.

  2. Locate the gtx section under config and insert the following lines:

    gtx:
      modules:
      - "net.postchain.d1.icmf.IcmfSenderGTXModule"

  3. Save and apply the configuration changes.

Send ICMF messages​

After integrating the ICMF Sender GTX module, you can now use the ICMF module to send messages. The ICMF module provides a function send_message(topic: text, body: gtv) for this purpose. The topic parameter represents the message topic, while the body parameter contains the content of the message. See instructions on installing the ICMF rell code library here.

Remember that the body parameter is of type gtv, allowing you to send messages with various data structures. However, ensure that the receivers can parse the data you send.

Receive messages​

Integration steps​

To enable your blockchain to receive ICMF messages, add the ICMF Receiver GTX module and the ICMF Receiver Synchronization Infrastructure Extension to your blockchain configuration.

  1. Open your blockchain's configuration file.

  2. Locate the gtx section under config and insert the following lines:

    gtx:
      modules:
      - "net.postchain.d1.icmf.IcmfReceiverGTXModule"

    sync_ext:
      - "net.postchain.d1.icmf.IcmfReceiverSynchronizationInfrastructureExtension"

  3. Save and apply the configuration changes.

Implement message reception​

To handle received ICMF messages, you need to implement the message receive operation in Rell. Here's an example implementation:

operation __icmf_message(sender: byte_array, topic: text, body: gtv) {
 // Parse and handle the message here
}

In this operation, the sender parameter represents the blockchain-rid of the sender chain, the topic parameter specifies the message topic and the body parameter carries the message content.

Configure topics and sender chains​

To specify which topics and sender chains your blockchain wants to listen to, you need to configure the ICMF receiver settings in your blockchain's configuration file:

icmf:
  receiver:
    local:
 - bc-rid: x"0000000000000000000000000000000000000000000000000000000000000001"
        topic: "L_topic1"
 - bc-rid: x"0000000000000000000000000000000000000000000000000000000000000002"
        topic: "L_topic2"
 - etc.

In the icmf section, under receiver, you can list the chains and topics your blockchain should listen to. The bc-rid parameter refers to the blockchain-rid of the sender chain, and the topic parameter specifies the topic of interest.