README.md

GMP between EVM and Cosmos chains

Axelar Network utilizes a canonical account axelar1dv4u5k73pzqrxlzujxg3qp8kvc3pje7jtdvu72npnt5zhq05ejcsn5qme5 to facilitate GMP communication. The recipient chain can authenticate the message using channel-id and the account address.

EVM -> Cosmos

1. Wrap the payload with version number and call Axelar Gateway contract.

   bytes4  version number (0 for native chain integration)
   bytes   payload
   

   e.g.

   uint32 version = 0;
   
   bytes memory payload = abi.encodePacked(
       bytes4(version),
       abi.encode(...)
   );
   
   gateway.callContractWithToken(destinationChain, destinationAddress, payload, symbol, amount);

2. Axelar verifies the message, attaches source chain and address info, and forwards the message to the destination chain using the ICS20 packet memo.

   Message is a JSON struct containing source_chain, source_address and payload. For instance:

   {
     "source_chain": "Ethereum",
     "source_address": "0x777d2D82dAb1BF06a4dcf5a3E07057C41100c22D",
     "payload": bytes,
     "type": 1
   }

   The type field denotes the message type

   • 1: pure message
   • 2: message with token

   On packet arrival, the recipient chain can processe the payload as needed.

3. Refer to the sample middleware for an example of unmarshal and process the message.

Cosmos -> EVM

1. Initiate an IBC transfer to Axelar GMP account (axelar1dv4u5k73pzqrxlzujxg3qp8kvc3pje7jtdvu72npnt5zhq05ejcsn5qme5) and attach the message in the memo field. The message specifies the destination chain, address, payload and message type. The message type can be

   • 1: pure message
   • 2: message with token
   • 3: pure token transfer

   type Message struct {
     DestinationChain   string `json:"destination_chain"`
     DestinationAddress string `json:"destination_address"`
     Payload            []byte `json:"payload"`
     Type               int64  `json:"type"`
     Fee                *Fee   `json:"fee"` // Optional
   }

   For example,

   {
     "destination_chain": "Ethereum",
     "destination_address": "0x777d2D82dAb1BF06a4dcf5a3E07057C41100c22D",
     "payload": bytes,
     "type": 1
   }

2. Upon arrival, Axelar network authenticates the message using channel-id. Validators co-sign an approval, which relayers then relay to the Axelar EVM Gateway.

3. If a smart contract implements the IAxelarExecutable interface, Axelar offers an auto-executing service. For instructions on Solidity smart contracts, refer to the Developer doc

Relayer Service for Cosmos -> EVM

Message senders can choose to pay a relayer on Axelar network to handle message execution on the destination EVM chain. The sender can include an optional fee field in the message, specifying the amount and recipient.

Axelar relayer address to use as the fee recipient: Testnet: axelar1zl3rxpp70lmte2xr6c4lgske2fyuj3hupcsvcd Mainnet: axelar1aythygn6z5thymj6tmzfwekzh05ewg3l7d6y89

1. Estimate the source gas fee in the desired token. Calcualte the gas required to execute the message on destination, and then use estimateGasFee (WIP integrating cosmos chains) to determine the source gas fee in the desired token.

2. Add the fee field to the message. The ICS20 packet total amount should equal to desired amount on destination + gas amount

   type Fee struct {
   Amount    string `json:"amount"`
   Recipient string `json:"recipient"`
   }

   For example,

   {
     "destination_chain": "Ethereum",
     "destination_address": "0x777d2D82dAb1BF06a4dcf5a3E07057C41100c22D",
     "payload": bytes,
     "type": 1,
     "fee": {
       "amount": "1000000",
       "recipient": "axelar1zl3rxpp70lmte2xr6c4lgske2fyuj3hupcsvcd"
     }
   }

3. Axelar network deducts fee from the ICS20 packet, and forward the remaining value to the destination EVM chain.

Refunds

If the prepaid fee exceeds the actual amount required for relaying a message, the executor service refunds the excess gas to the original packet sender after execution.

Increasing Fee

If the prepaid fee is insufficient, anyone can top up a pending message. They can send gas token to the executor address, and indicate the message id in memo field. The message id is a unique identifier generated by Axelar network for each general message.

Cross-Chain Token Transfer with Memo

A Cosmos chain can send a message to the Axelar GMP account to initiate a pure cross-chain token transfer with a message type 3. When the message type is 3, the message payload will be ignored.

Here's an example of sending axlUSDC tokens to Avalanche:

MEMO='{"destination_chain": "avalanche", "destination_address": "0x68B93045fe7D8794a7cAF327e7f855CD6Cd03BB8", "payload":null, "type":3}'
gaiad tx ibc-transfer transfer transfer channel-id axelar1dv4u5k73pzqrxlzujxg3qp8kvc3pje7jtdvu72npnt5zhq05ejcsn5qme5 1000000ibc/denom --memo "$MEMO"

In this example, the following parameters are used:

• destination_chain: Specifies the target blockchain, in this case, "avalanche".
• destination_address: Provides the recipient's address on the target chain, in this case, "0x68B93045fe7D8794a7cAF327e7f855CD6Cd03BB8".
• payload: This field will be ignored since the message type is 3.
• type: Sets the message type to 3, indicating a pure cross-chain token transfer.