Skip to Content
DocumentationAnalog GMPOverviewArchitectural Components

Architectural Components

The architectural components of Analog GMP can be grouped into two components: on-chain and off-chain.

On-Chain Components

Gateway Smart Contracts (GSCs)

A GSC is the primary contract that shards observe and which fundamentally facilitates cross-chain message passing. Analog Network supports one GSC on each blockchain, and this is the contract that the source and destination shard need to observe. There are two categories of GSC interfaces:

  1. User-space interfaces: These are interfaces that you’ll interact with. They can be grouped into two:
    1. IGmpReceiver, which receives GMP messages on the destination chain’s ASC.
    2. IGateway, which you’ll use to deposit funds, send GMP messages, and track GMP calls.
  2. System-space interface: This is the interface that the GMP protocol uses internally. It is implemented as IExecutor and handles the execution of GMP messages. Only the shards can call this interface.

IGmpReceiver Interface

The IGmpReceiver interface contains a single function onGmpReceived that must be implemented by any contract wanting to receive GMP messages. Implement it to handle incoming messages and return a result.

onGmpReceived

function onGmpReceived(
    bytes32 id,
    uint128 network,
    bytes32 source,
    uint64 nonce,
    bytes calldata payload
) external payable returns (bytes32);

Parameters:

  • id (bytes32): Unique identifier for the message (EIP-712 hash of the payload).
  • network (uint128): Source chain ID (e.g., Ethereum Mainnet = 1).
  • source (bytes32): Address/public key of the sender on the source chain.
  • nonce (uint64): Unique number to prevent message replay.
  • payload (bytes): Raw message data (decode this for your use case).

Returns:

  • bytes32: 32-byte result (e.g., hash or status) stored with the GMP message.

Note that contracts implementing this interface must validate that the caller (msg.sender) is indeed the authorized Gateway Contract address to avoid unauthorized message handling or malicious interactions.

Example: 

require(msg.sender == GATEWAY_ADDRESS, "Unauthorized");

IGateway Interface

The IGateway interface allows for cross-chain messaging, providing functions for message sending, gas cost calculation, and network details. It has three key functions (i.e., submitMessage, estimateMessageCost, and networkId) and one event (i.e., GmpCreated).

Functions:

submitMessage

Sends a cross-chain message.

  • Parameters:
    • destinationAddress (address): The target address on the destination blockchain.
    • destinationNetwork (uint16): The identifier of the destination blockchain network.
    • executionGasLimit (uint256): The maximum gas allowed for executing the message on the destination chain.
    • data (bytes): Arbitrary message payload.
  • Returns: A unique message identifier (bytes32) used to track the submitted message.

estimateMessageCost

Estimates how much gas (cost) is required to execute a cross-chain message.

Parameters:

  • networkid (uint16): The target blockchain network ID.
  • messageSize (uint256): Size of the message payload in bytes.
  • gasLimit (uint256): Desired gas limit for executing the message.

Returns:

  • Estimated cost (uint256) of executing the message.

estimateMessageCost returns a value that serves as a msg.value parameter of the gateway’s submitMessage function. You can use this value (i.e., msg.value) to pass in the native token of your origin chain as the gas fee. For example, you can call the submitMessage function like this:

gateway.submitMessage{value: msg.value}(dest_address, dest_network, GMP_GAS_LIMIT, payload);

networkId

Returns the identifier (uint16) of the current blockchain network.

Usage Example:

uint16 currentNetwork = gateway.networkId();

Events:

GmpCreated

Emitted whenever a new cross-chain message is successfully submitted.

Event Parameters:

  • id (bytes32 indexed): Unique identifier for the message (EIP-712 hash).
  • source (bytes32 indexed): Sender's account identifier (with a flag indicating contract or EOA).
  • destinationAddress (address indexed): Target address on the destination chain.
  • destinationNetwork (uint16): Target blockchain network ID.
  • executionGasLimit (uint64): Gas limit set for execution on the target chain.
  • gasCost (uint64): Gas cost associated with executing this message.
  • nonce (uint64): Unique sequence number per sender to ensure uniqueness of messages.
  • data (bytes): Arbitrary data payload sent in the message.

Note:

  • Ensure sufficient funds (msg.value) are provided when calling submitMessage to cover gas costs.
  • Always use estimateMessageCost before submitting messages to avoid transaction failures due to insufficient gas.

IExecutor Interface

The IExecutor interface defines functions and events for executing GMP messages, managing shard keys, and configuring routes within the GSC.

The GMP protocol relies on this interface for internal operations, and only Timechain shards can call it.

Functions:

There are three categories of functions: Message Execution, Shard Management, and Route Configuration.

  1. Message Execution

execute

Handles the execution of a single GMP message.

function execute(Signature calldata signature, GmpMessage calldata message)
    external returns (GmpStatus status, bytes32 result)
  • Verifies TSS signature
  • Executes target contract call
  • Returns execution status (Success/Revert)

batchExecute

Execute operations/messages in batch with signature verification:

function batchExecute(Signature calldata signature, InboundMessage calldata message) external
  • Executes a batch of commands (GMP messages, shard updates)
  • Requires valid TSS signature for the entire batch
  1. Shard Management

Shard Management

List currently registered shards:

function shards() external returns (TssKey[] memory);

Returns an array of currently registered shard TSS keys.

Register a single shard key:

function setShard(TssKey calldata publicKey) external;

Registers a single shard TSS key.

Register multiple shard keys at once:

function setShards(TssKey[] calldata publicKeys) external;

Registers multiple shard TSS keys in batch.

Revoke (unregister) a single shard key:

function revokeShard(TssKey calldata publicKey) external;

Revokes/unregisters a specific shard TSS key.

Revoke multiple shard keys at once:

function revokeShards(TssKey[] calldata publicKey) external;

Revokes multiple shard TSS keys simultaneously.

  1. Route Configuration

Route Configuration

List currently registered routes:

function routes() external returns (Route[] memory);

Returns an array of currently registered routes within the gateway.

Register or update a single route:

function setRoute(Route calldata info) external;

Creates or updates a single route entry.

Register or update multiple routes at once:

function setRoutes(Route[] calldata values) external;

Creates or updates multiple route entries simultaneously.

Events:

The interface defines several events to emit important state changes:

GmpExecuted

event GmpExecuted(
    bytes32 indexed id,
    GmpSender indexed source,
    address indexed dest,
    GmpStatus status,
    bytes32 result
);

Emitted whenever a GMP message is executed.

  • id: EIP-712 hash uniquely identifying the GMP payload.
  • source: Sender's public key or address (format chain-dependent).
  • dest: Recipient's Ethereum address.
  • status: Execution status of the GMP message.
  • result: Resulting data or hash from execution.

BatchExecuted

event BatchExecuted(uint64 batch);

Emitted when a batch of operations/messages is executed.

ShardsRegistered

event ShardsRegistered(TssKey[] keys);

Emitted when new shard keys are registered.

ShardsUnregistered

event ShardsUnregistered(TssKey[] keys);

Emitted when existing shard keys are revoked/unregistered.

Application Smart Contracts (ASCs)

A smart contract deployed by applications on the source and destination chains. An ASC can be your cross-chain dApp or an existing ecosystem protocol. To create a cross-chain smart contract execution call , you'll need to:

  • Use the IGateway interface in the source chain's ASC to call the submitMessage function on the source Gateway contract
  • Implement the IGmpReceiver interface on the destination chain's ASC to receive the cross-chain message in the onGmpReceived function.

Time Nodes

Validators that leverage the NPoS consensus protocol to secure the Timechain. See Timechain for more details.

Off-Chain Components

Chronicle Nodes

Validators that observe external chains for certain state changes, transactions, or events associated with a registered smart contract address and report them to the Timechain. For more details, read the Timepaper .

Shards

A process that Analog uses to parallelize the Chronicle Nodes network into partitions—called shards—to achieve multi-chain operability. Read the Timepaper  for more details.

Analog GMP relies on the Timechain to track and manage cross-chain requests by coordinating two shard committees. One source chain committee confirms finality and reports to the Timechain, and the destination chain committee executes the request. Both committees use Gateway Smart Contracts, with their public keys registered on the Timechain.

Threshold Signature Scheme (TSS)

A type of digital signature protocol that allows chronicle nodes to establish subsets such that only a certain subset of the group can generate signatures on behalf of the group when handling cross-chain requests via the GMP protocol. Read the Timepaper  for more details.

OverviewTransaction Lifecycle