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?
- 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. - This triggers an event on the node, which is then sent to the cluster's anchoring chain.
- The receiver node checks for messages on subscribed topics before building each block.
- When a message is detected, the node invokes the
__icmf_message
special operation on the dapp. - 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.
-
Open your blockchain's configuration file.
-
Locate the
gtx
section underconfig
and insert the following lines:gtx:
modules:
- "net.postchain.d1.icmf.IcmfSenderGTXModule" -
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.
-
Open your blockchain's configuration file.
-
Locate the
gtx
section underconfig
and insert the following lines:gtx:
modules:
- "net.postchain.d1.icmf.IcmfReceiverGTXModule"
sync_ext:
- "net.postchain.d1.icmf.IcmfReceiverSynchronizationInfrastructureExtension" -
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.