Skip to main content

Interchain Messaging Facility (ICMF)

This documentation is specifically designed for Dapp developers who want to integrate Interchain Messaging Facility (ICMF) messages into their decentralized applications. ICMF facilitates cross-chain communication without the need for a client's involvement, enabling seamless interaction between different blockchains. This guide will walk you through the process of sending and receiving ICMF messages in your Dapps.

To better understand the concept of cross-chain communication, please read this page.

Topics in ICMF​

ICMF messages are organized around topics, which act as channels for communication. Topics play a crucial role in directing messages to their intended recipients. It's important to note the following guidelines when working with ICMF topics:

  • All topics used in ICMF must be prefixed with L_. This prefix indicates that the message is sent on a local topic within your blockchain network.

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

Sending messages​

Integration steps​

To enable your blockchain to send ICMF messages, you need to 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 add the following lines:
gtx:
  modules:
    - "net.postchain.d1.icmf.IcmfSenderGTXModule"
  1. Save and apply the configuration changes.

Sending 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 how to install 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.

Receiving messages​

Integration steps​

To enable your blockchain to receive ICMF messages, you need to add both 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 add the following lines:
gtx:
  modules:
    - "net.postchain.d1.icmf.IcmfReceiverGTXModule"

sync_ext:
  - "net.postchain.d1.icmf.IcmfReceiverSynchronizationInfrastructureExtension"
  1. Save and apply the configuration changes.

Implementing message reception​

To handle received ICMF messages, you need to implement the message receive operation in the Rell language. 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 contains the message content.

Configuring 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.