LogoLogo
  • ⏩Introduction
    • Hyperlane Introduction
    • Getting started
    • Why Should You Use Hyperlane?
  • Permissionless Interoperability
    • Overview
    • Deploy Hyperlane
    • Warp Routes
      • Deploy a Warp Route
      • Deploy a UI for your Warp Route
    • Modular Rollup Interoperability
  • Build With Hyperlane
    • Quickstarts
      • Messaging
      • Accounts
      • Queries
      • hyperlane-quickstart repo
    • Guides
      • Finding my messages
      • Automatically pay for interchain gas
      • Manually pay for interchain gas
      • Choosing an interchain gas paymaster contract
      • Unit testing
      • Specifying an ISM
      • V2 migration guide
    • Explorer
      • Debugging messages
      • Configuring PI Chains
      • REST API
      • GraphQL API
    • Troubleshooting/Developer FAQ
    • Example apps
  • APIs and SDKs
    • Messaging API
      • Send
      • Receive
    • Accounts API
    • Queries API
    • Warp Route API
    • Interchain gas paymaster API
    • Hyperlane App Framework
      • Example usage
        • HelloWorld
        • Interchain Token
      • Solidity SDK
        • HyperlaneConnectionClient
        • Router
      • NodeJS SDK
        • RPC Providers
        • Deployment
        • Interchain testing
        • Quoting gas payments
        • App Abstraction
    • Hooks API
      • Contract addresses
  • Protocol
    • Overview
    • Mailbox
    • Interchain security modules
      • Interface
      • Multisig ISM
      • Routing ISM
      • Aggregation ISM
      • Optimistic ISM
      • Wormhole ISM
      • Hook ISM
      • CCIP-Read ISM
    • Interchain gas payments
    • Staking and slashing
    • Agents
      • Validators
      • Relayers
      • Watchtowers
    • Warp Routes
    • Implementation Guide
  • Operators
    • Validators
      • Guide
      • AWS setup
      • Monitoring and alerting
    • Relayers
      • Guide
      • Message filtering
    • Agent keys
      • Hexadecimal keys
      • AWS KMS keys
    • Agent configuration
      • Configuration reference
    • Running with docker compose
  • Resources
    • FAQ
    • Glossary
    • Contract addresses
      • Permissionless Deployment Contract Addresses
    • Domain identifiers
      • Permissionless Domain Identifiers
    • Default ISM settings
    • Coming Soon: Hyperlane v3
    • Token sources & faucets
    • Latencies
    • Github
    • Discord
    • Website
Powered by GitBook
On this page
  • Interface
  • Refunds
  1. APIs and SDKs

Interchain gas paymaster API

Pay for message delivery on the origin chain

PreviousWarp Route APINextHyperlane App Framework

Last updated 1 year ago

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.

Learn more about Interchain gas payments protocol

Interface

The interchain gas paymaster (IGP) interface exposes two functions that can be used together to quote and pay for interchain gas.

  1. quoteGasPayment is 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. payGasFor is 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.

You can find deployed IGPs on Contract addresses

// 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);
}

Refunds

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. This allows users to not need to call quoteGasPayment explicitly.

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.

Reentrancy Risk

Unsuccessful Refunds

If a refund is unsuccessful, the payForGas call will revert.

Note that refunding overpayment involves the IGP contract calling the _refundAddress, which can present a risk of for your application. Special care should be made by callers to ensure they are not vulnerable to reentrancy exploits.

here
reentrancy