Skip to main content

Inter-chain Messaging Facility (ICMF)

Overview​

The Inter-chain Messaging Facility (ICMF) enables cross-blockchain messaging within the Chromia network. It enables blockchains to broadcast and subscribe to messages on topics.

Common use-cases include:

  • State synchronization — when there is some shared state that must be synchronized between blockchains. For example, a dApp might be split into multiple blockchains with different concerns, but some common states like users need to be synchronized between them.
  • Event notification — when there is a need to notify other blockchains of events on the blockchain that might be of interest to them.
  • Workflow coordination — when there is a multi-step process that needs to be orchestrated across blockchains. For example, a purchase on one blockchain might trigger something to be created on another blockchain, which in turn reports back if creation was successful or not (in which case a refund might be paid out).

ICMF is the best choice for cross-blockchain communication when clients cannot be relied on to facilitate communication between blockchains. Otherwise, a client-driven protocol like ICCF (Inter-chain Confirmation Facility) might be a better choice.

Protocol fundamentals​

There are two types of ICMF message topics. Global and local. Messages on global topics can only be sent by system chains and can be received by any blockchain without having to specify the blockchain RID of the sender. Messages on local topics can be sent by any blockchain, and the receiver blockchain must specify exactly which blockchain RIDs it wants to listen to.

Messages are guaranteed to be delivered once and only once to receiving chains. There are no guarantees about delivery times. The messages are only guaranteed to be in order per sender chain and topic.

Sender blockchain​

ICMF message sending is implemented in a GTX module called IcmfSenderGTXModule. This module ensures that hashes of sent messages in a block are added to the block header so that the receiver can verify the integrity of messages received from the blockchain. It also exposes queries to fetch messages that have been sent on the blockchain. Messages can be sent by emitting events from Rell code that the GTX module listens to, there is a Rell library that simplifies this interaction with the GTX module.

Message sending on global topics is also picked up by the cluster anchoring chains. The block RID of the block with messages is stored in the anchoring chain block header. This enables one more layer of validation for the messages sent on the topic. It also enables more efficient message reception, since the receiver chains only have to ask the anchoring chain if there are any new messages on the topic sent by any blockchain in the cluster it is anchoring.

Receiver blockchain​

ICMF message receiving is implemented in a GTX module called IcmfReceiverGTXModule as well as a synchronization infrastructure extension called IcmfReceiverSynchronizationInfrastructureExtension. There is also a Rell library that can simplify the message receiving in Rell.

The synchronization infrastructure extension will spin up background tasks that periodically check the anchoring chain (global topics) or the sender chain (local topics) for new messages on the topics subscribed to by the receiver chain. When new messages are found, they are injected into the receiver chain via special operations. Unlike other special operations these are allowed to fail, if so, the particular topic will be blocked for some time, and the message reception will eventually be retried in another block.

ICMF data flow

Building with ICMF​

When sending and receiving messages with ICMF, you need to specify a topic. Global topics must be prefixed with G_ and local topics with L_ so that cluster anchoring chain and other validation mechanisms can understand what the intended scope is for the topic. The message body can be any GTV structure.

Sender chain setup​

A sender chain must be configured with the sender ICMF GTX module.

blockchains:
  target:
    module: main
    config:
      gtx:
        modules:
          - "net.postchain.d1.icmf.IcmfSenderGTXModule"
libs:
  com.chromia.icmf:
    version: 1.102.2

How to send a message using the ICMF Rell library:

import lib.icmf;

val EXAMPLE_TOPIC = "L_example";

operation trigger_message() {
  icmf.send_message(EXAMPLE_TOPIC, "Hello World!".to_gtv());
}

Receiver chain setup​

A receiver chain must be configured with the receiver ICMF GTX module and synchronization infrastructure extension. You must also specify the topics you want to subscribe to. For local topics a sender blockchain RID must be specified.

blockchains:
  target:
    module: main
    config:
      gtx:
        modules:
          - "net.postchain.d1.icmf.IcmfReceiverGTXModule"
      sync_ext:
        - "net.postchain.d1.icmf.IcmfReceiverSynchronizationInfrastructureExtension"
      icmf:
        receiver:
          global:
            topics:
              - G_example
          local:
            - topic: L_example
              bc-rid: x"0000000000000000000000000000000000000000000000000000000000000000"
libs:
  com.chromia.icmf:
    version: 1.102.2

How to receive messages using the ICMF Rell library, simply extend the receive_icmf_message function:

import lib.icmf.receiver;

val EXAMPLE_TOPIC = "L_example";

@extend(receiver.receive_icmf_message)
function handle_example_message(sender: byte_array, topic: text, body: gtv) {
  if (topic != EXAMPLE_TOPIC) return;

  log("Got example message %s from %s".format(body, sender));
}

If you need height and timestamp of the sent message you can use the metadata receiver module:

import lib.icmf.metadata_receiver;

val EXAMPLE_TOPIC = "L_example";

@extend(metadata_receiver.receive_icmf_message)
function handle_example_message(sender: byte_array, sender_height: integer, sender_timestamp: integer, topic: text, body: gtv) {
  if (topic != EXAMPLE_TOPIC) return;

  log("Got example message %s from %s, sent at height %s and time %s".format(body, sender, sender_height, sender_timestamp));
}

Examples & Further Resources​

The following resources provide practical examples, learning materials, reference documentation, and production implementations demonstrating ICMF integration.

1. ICMF Course on Chromia Learning​

An interactive course covering ICMF theory, protocol mechanics, implementation patterns, and common pitfalls through guided exercises and real-world scenarios.

Link: https://learn.chromia.com/courses/icmf-course/introduction

2. ICMF Rell Library Reference​

Source code for the ICMF Rell library, containing all utility functions for both sender and receiver chains.

Link: https://gitlab.com/chromaway/postchain-chromia/-/tree/dev/chromia-infrastructure/rell/src/lib/icmf