Overview
This document explains thegmp
module for the Neutron network.
The General Message Passing (GMP) module is an IBC middleware that enables cross-chain message passing by embedding structured messages within IBC transfer packet memo fields. This module allows developers to send both tokens and arbitrary data in a single IBC transaction, enabling sophisticated cross-chain interactions without requiring additional infrastructure.
The GMP module operates as IBC middleware, intercepting and processing IBC transfer packets that contain structured messages in their memo fields. It works transparently with existing IBC transfer functionality while adding message passing capabilities.
Table of contents
- Overview — a high-level description of the module.
- Explanation — an explanation of the module’s concepts and the reasoning behind its design choices.
- How To — short guides on performing basic operations with the module.
- Reference — details about the module’s interface, including message formats and processing logic.
Concepts
The GMP module processes two types of messages embedded in IBC transfer memo fields:- General Message: Contains arbitrary payload data that is passed through to the receiving application. The token transfer proceeds normally, but the payload is extracted and made available to downstream processing.
- General Message with Token: Similar to General Message, but specifically indicates that the message payload should be processed in conjunction with the token transfer. This is useful for applications that need to coordinate token receipt with message execution.
- Attempts to parse the memo field as a structured GMP message
- If successful, extracts the payload and processes it according to the message type
- Modifies the packet data to include the processed payload
- Passes the modified packet to the next layer in the IBC stack
Message Format
GMP messages are embedded in the memo field of IBC transfer packets using the following JSON structure:Message Types
The module recognizes the following message types:- TypeGeneralMessage (1): Standard message passing without specific token handling requirements
- TypeGeneralMessageWithToken (2): Message passing that explicitly coordinates with token transfers
Processing Logic
When a valid GMP message is detected:- The original memo content is replaced with the extracted payload
- The modified packet continues through the IBC stack
- Receiving applications can access both the transferred tokens and the message payload
Integration with IBC Stack
The GMP module integrates seamlessly with the existing IBC transfer flow:- Sending: Applications embed GMP messages in transfer memo fields using standard IBC transfer calls
- Receiving: The GMP middleware processes messages transparently, with receiving applications getting both tokens and payload data
- Compatibility: Non-GMP transfers continue to work normally without any changes
Use Cases
The GMP module enables several cross-chain interaction patterns:- Cross-chain Contract Calls: Send tokens and execution instructions in a single transaction
- Atomic Swaps: Coordinate token transfers with swap execution data
- Cross-chain Governance: Send tokens along with voting or proposal data
- Multi-chain Applications: Synchronize state and value transfer across chains
Security Considerations
- Payload Size: While the module doesn’t enforce payload size limits, IBC packet size limits still apply
- Message Validation: Applications receiving GMP messages should validate payload content
- Source Verification: The source_chain and source_address fields are provided for reference but should not be trusted for security decisions