How-to Guide
This guide provides practical instructions for using the GMP (General Message Passing) module to send cross-chain messages via IBC transfers.Basic Usage
The GMP module processes messages embedded in IBC transfer memo fields. To use GMP, you embed a structured JSON message in the memo field of a standard IBC transfer.Sending a General Message
To send a general message with an IBC transfer:Step 1: Prepare Your Payload
First, prepare the actual message content you want to send:Step 2: Encode the Payload
Convert your payload to bytes (base64 encoding is recommended):Step 3: Create GMP Message
Embed your payload in a GMP message structure:Step 4: Send IBC Transfer
Use the GMP message as the memo field in your IBC transfer:Sending a General Message with Token
For messages that specifically coordinate with token transfers, use type 2:Programming Examples
JavaScript/TypeScript
Python
Go
Receiving GMP Messages
Applications receiving GMP-processed transfers will see the extracted payload in the memo field, not the original GMP message structure.CosmWasm Contract Integration
Message Type Guidelines
When to Use Type 1 (GeneralMessage)
UseTypeGeneralMessage
(1) for:
- Informational messages
- Messages that don’t require specific token coordination
- General cross-chain communication
When to Use Type 2 (GeneralMessageWithToken)
UseTypeGeneralMessageWithToken
(2) for:
- Messages that must be processed atomically with token transfers
- Swap instructions
- Contract execution that depends on received tokens
Best Practices
Payload Design
- Keep payloads small: IBC packets have size limits
- Use efficient encoding: JSON is human-readable but not space-efficient
- Include version information: For future compatibility
- Validate on both sides: Don’t trust cross-chain data
Error Handling
- Handle parsing failures: Invalid GMP messages will cause packet failures
- Validate message types: Only use supported types (1 and 2)
- Test thoroughly: Cross-chain debugging is difficult
Security Considerations
- Don’t trust source fields:
source_chain
andsource_address
are informational only - Validate all payload content: Treat cross-chain data as untrusted
- Implement proper authentication: Use IBC’s cryptographic guarantees
Common Patterns
Cross-chain Swap
Cross-chain Governance Vote
Multi-step Transaction
Troubleshooting
Common Issues
- Invalid JSON: Ensure your GMP message is valid JSON
- Empty payload: Payloads cannot be empty or the message will be ignored
- Unsupported type: Only types 1 and 2 are supported
- Size limits: Large payloads may exceed IBC packet size limits
Debugging
- Check IBC events: Failed GMP processing will generate error acknowledgements
- Validate JSON: Use JSON validators before sending
- Test locally: Use local testnets for development
- Monitor relayers: Ensure relayers are processing your packets
Error Messages
"cannot unmarshal ICS-20 transfer packet data"
: Malformed IBC transfer packet"unrecognized message type: X"
: Invalid message type (not 1 or 2)"cannot marshal ICS-20 post-processed transfer packet data"
: Internal processing error