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.

ICMF can be compared to a message queue, where a chain can emit events on a specific topic or subscribe to several topics. This is an integral part of the architecture of Chromia, where blockchains need to communicate without user interaction.

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

1. The sender dapp calls the function send_message, a part of the icmf rell library. This could be user-triggered via an operation or by the dapp itself.

2. This emits an event on the node, which is sent to the cluster's anchoring chain.

3. The receiver node polls for messages on the subscribed topics before each block gets built.

4. When a message is found, the node calls the __icmf_message special operation on the dapp.

5. The function receive_icmf_message gets called by the icmf library, which triggers any logic defined by the dapp.

Based on this, we see that the type of dapps that are ideal for this type of messaging is when you want chains to broadcast a message to indicate that it has completed an action. Then, it is up to the other chains to subscribe to this action and perform an action based on the information in the message. This way, you can add more chains to your solution with new responsibilities, and they just have to subscribe to their topics of interest; no logic needs to be changed in the sender chain.

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"

3. 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"

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