# Inter-chain Messaging Facility (ICMF) · Chromia Docs (concept)

> The Inter-chain Messaging Facility (ICMF) enables cross-blockchain messaging within the Chromia network.

Source: https://docs.chromia.com/get-started/about/protocols/icmf/

# Inter-chain Messaging Facility (ICMF)

On this page

* [Overview](#overview)
* [Protocol fundamentals](#protocol-fundamentals)
* [Sender blockchain](#sender-blockchain)
* [Receiver blockchain](#receiver-blockchain)
* [Building with ICMF](#building-with-icmf)
* [Sender chain setup](#sender-chain-setup)
* [Receiver chain setup](#receiver-chain-setup)
* [Examples & Further Resources](#examples--further-resources)
* [1. ICMF Course on Chromia Learning](#1-icmf-course-on-chromia-learning)
* [2. ICMF Rell Library Reference](#2-icmf-rell-library-reference)

## 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](https://docs.chromia.com/img/icmf_sequence_diagram_light.svg)

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

YAML

```
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:

Rell

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

YAML

```
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:

Rell

```
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:

Rell

```
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>

[View this page on docs.chromia.com](https://docs.chromia.com/get-started/about/protocols/icmf/)Content mirrored from the live docs
