Configure gas payments for cross-chain message delivery using InterchainGasPaymaster contracts
During the post-dispatch hook, the InterchainGasPaymaster
contract will revert if payment is insufficient to cover the relayer’s anticipated costs. The gas quote calculated at dispatch
time must align with the relayer’s anticipated costs.
The gasLimit
is set based on the cost of calling handle
on the destination chain for a given message. This can vary depending on message content and the logic of the handler.
The default gasLimit
for metering the handle call is a static default of 50_000
gas. This is sufficient for simple operations but may not be enough for more complex handle
functions.
If your handle
function performs complex operations or requires more gas, you must override the default gasLimit
in metadata to avoid transaction reverts. Benchmark your handle
implementations in unit tests to determine a reasonable gasLimit
to use.
This hook expects metadata in a packed encoding of StandardHookMetadata
. See the Mailbox dispatch overloads for how to pass metadata overrides.
The StandardHookMetadata
struct defines the fields required for metadata encoding:
variant
: Specifies the metadata format version.msgValue
: Amount of native token sent with the message.gasLimit
: Gas limit for the handle
function on the destination chain. Ensure this matches your simulation results.refundAddress
: Address to refund unused gas payments.To encode this metadata, use the StandardHookMetadata.formatMetadata
library function. Direct encoding of the struct with abi.encodePacked
is not supported in Solidity.
handle
function on your message recipient. Ensure the from
address is set to the Mailbox contract on your chain.50,000
gas, calculate an appropriate gasLimit
and update your metadata.gasLimit
based on the simulation.gasLimit
in your metadata to ensure the relayer will deliver your message.For each remote domain, the InterchainGasPaymaster sets the domain gas config.
The gas overhead is set as part of the destination gas configuration. This corresponds to the operational cost of processing a message on the destination chain.
gasOverhead
sufficiently covers the range of ISMs on
your destination chain. - As you can configure different ISMs for different
message types, you may have different gas overheads for each ISM’s verify
function.Interchain Gas Payment requirements are calculated using oraclized gas prices and exchange rates between the origin and destination chains.
IGP contracts may be configured with gas oracles, which are responsible for tracking remote token gas prices and exchange rates. Developers should use the quoteDispatch
function on the Mailbox contract to calculate gas fees. The quoteDispatch
accounts for system-level overhead and ensures accurate fee calculation for the entire dispatch
process.
Exchange rates and gas prices are up to the relayer to decide. A spread may be charged to account for drift and operating costs.
Eventually, a relayer will be able to automatically update their gas oracles in order to ensure that their IGP always quotes a fair price for remote gas.
getExchangeRateAndGasPrice
Parameters
destinationDomain
: The message’s destination domainReturns
tokenExchangeRate
: The exchange rate between the origin and destination chain’s gas tokensgasPrice
: The gas price for the destination chainquoteGasPayment
The quoteGasPayment
function calculates fees for the relayer’s anticipated costs.
Parameters
destinationDomain
: The message’s destination domaingasLimit
: The gas limit to meter the handle
call withReturns
fee
: The payment required for the postDispatch
to succeedThe quoteGasPayment
gives an estimated fee based on the destinationDomain
and gasLimit
. However, it does not include extra gas costs added by the Interchain Gas Paymaster (IGP) for the Default ISM payment.
To get the full fee, use quoteDispatch()
from the Mailbox contract. It provides a complete quote that includes these additional costs.
👉 See Quote Dispatch for more details.
If the handle
call consumes more gas than quoted, the relayer will not submit a process transaction. This issue often occurs due to insufficient gas payment during the initial dispatch
.
In this case, additional gas can be paid for with the payForGas
function.
Parameters
messageId
: The message identifier returned from dispatch
calldestinationDomain
: The message’s destination domaingasAmount
: The additional gas amount to pay forrefundAddress
: The address to refund excess payment toThe Hyperlane Explorer is a powerful tool to debug cross-chain message issues, including gas payments and relayer behavior.
This section covers common issues developers encounter with Interchain Gas Payments, along with potential solutions.
GasPaymentRequirementNotMet
WarningReason: This occurs when the gas payment provided during dispatch
does not meet the relayer’s calculated requirement.
Solution:
quoteDispatch
to calculate the aggregate fee required for a dispatch
call to be successful.msg.value
in your metadata covers the relayer’s quoted fee.Retry(GasPaymentRequirementNotMet)
.Reason: msg.value
exceeds the required gas payment, triggering the fallback routing hook.
Solution:
quoteDispatch
) matches the relayer’s anticipated fees.gasLimit
values without first benchmarking the handle
function.Reason: A very high gasLimit
was set, leading to excessively large gas quotes.
Solution:
gasLimit
specified in your metadata.quoteDispatch
) matches the relayer’s anticipated fees.gasLimit
to match the estimated gas consumption of your handle
function.