Interchain gas paymaster API
Pay for message delivery on the origin chain
Hyperlane provides an on-chain API on the origin chain that allows message senders to pay one or more Relayers to deliver a message on the destination chain.
The interchain gas paymaster (IGP) interface exposes two functions that can be used together to quote and pay for interchain gas.
- 1.
quoteGasPaymentis a view function that allows users to get a quote for an amount of gas on the destination chain, denominated in the origin chain's native token - 2.
payGasForis a payable function that pays a relayer to deliver a specific message to the destination chain
These functions do not necessarily need to be called in the same transaction as the message dispatch.
// SPDX-License-Identifier: MIT OR Apache-2.0
pragma solidity >=0.6.11;
/**
* @title IInterchainGasPaymaster
* @notice Manages payments on a source chain to cover gas costs of relaying
* messages to destination chains.
*/
interface IInterchainGasPaymaster {
/**
* @notice Emitted when a payment is made for a message's gas costs.
* @param messageId The ID of the message to pay for.
* @param gasAmount The amount of destination gas paid for.
* @param payment The amount of native tokens paid.
*/
event GasPayment(
bytes32 indexed messageId,
uint256 gasAmount,
uint256 payment
);
/**
* @notice Deposits msg.value as a payment for the relaying of a message
* to its destination chain.
* @dev Overpayment will result in a refund of native tokens to the _refundAddress.
* Callers should be aware that this may present reentrancy issues.
* @param _messageId The ID of the message to pay for.
* @param _destinationDomain The domain of the message's destination chain.
* @param _gasAmount The amount of destination gas to pay for.
* @param _refundAddress The address to refund any overpayment to.
*/
function payForGas(
bytes32 _messageId,
uint32 _destinationDomain,
uint256 _gasAmount,
address _refundAddress
) external payable;
/**
* @notice Quotes the amount of native tokens to pay for interchain gas.
* @param _destinationDomain The domain of the message's destination chain.
* @param _gasAmount The amount of destination gas to pay for.
* @return The amount of native tokens required to pay for interchain gas.
*/
function quoteGasPayment(uint32 _destinationDomain, uint256 _gasAmount)
external
view
returns (uint256);
}
Under some circumstances, users may call
payGasFor with msg.value greater than what would be returned by quoteGasPayment. In this case, the IGP contract should refund the difference to the _refundAddress provided.For example, if you are paying for 1M gas and pass 0.1 ETH to the IGP contract, but
quoteGasPayment quotes a payment of 0.08 ETH, the _refundAddress will be refunded 0.02 ETH.Note that refunds are only made if what is paid was greater than what was quoted. Refunds are not made if delivery of a message on the destination chain winds up requiring less gas than what was paid for.
Note that refunding overpayment involves the IGP contract calling the
_refundAddress, which can present a risk of reentrancy for your application. Special care should be made by callers to ensure they are not vulnerable to reentrancy exploits.If a refund is unsuccessful, the
payForGas call will revert.