Configuring PI Chains

Hyperlane can be permissionlessly deployed to any chain, but messages on PI chains cannot be identified by the default Hyperlane agents. To view details about messages from PI chains, first configure the explorer with metadata about that chain.

To begin, go to the explorer's settings page.

From there, click the Add Custom Chain button. A modal will appear. Input the configuration for your PI Chain.

The chain config schema is an extension of the Hyperlane ChainMetadata schema but with a contracts object added. Currently only the mailbox contract address is required but more functionality may be enabled in the future if more addresses are provided.

If a valid Etherscan-based block explorer config is provided, the Hyperlane Explorer will utilize it to find the desired messages. If not, it will use the RPC URL. Note, Explorers with api keys (even just free-tier keys), perform faster and more reliably.

Chain Config Examples

A minimal chain config:

{
  "chainId": 11155111,
  "name": "sepolia",
  "protocol": "ethereum",
  "rpcUrls": [{ "http": "https://foobar.com" }]
}

A chain config with a block explorer and block timings included:

{
  "chainId": 11155111,
  "domainId": 11155111,
  "name": "sepolia",
  "protocol": "ethereum",
  "displayName": "Sepolia",
  "nativeToken": {
    "name": "Ether",
    "symbol": "ETH",
    "decimals": 18
  },
  "rpcUrls": [
    {
      "http": "https://rpc.sepolia.org"
    },
    {
      "http": "https://eth-sepolia.public.blastapi.io	"
    }
  ],
  "blockExplorers": [
    {
      "name": "Etherscan",
      "url": "https://sepolia.etherscan.io",
      "apiUrl": "https://api-sepolia.etherscan.io/api",
      "family": "etherscan"
    }
  ],
  "blocks": {
    "confirmations": 1,
    "reorgPeriod": 2,
    "estimateBlockTime": 13
  },
  "isTestnet": true,
  "mailbox": "0x123...",
  "interchainGasPaymaster": "0x123..."
}

info

If the origin or destination domainId of chains in your messages doesn't match their chainId then you must include the domainId field in your chain config.