Skip to main content

Configuring Permissionless 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, click either the Origin or the Destination button on the explorer's home page. This will open the chain selection modal. From there, click the plus icon in the top-right.

The displayed form accepts JSON or YAML confirming to the ChainMetadata schema.

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 Metadata Examples​

A minimal example in JSON:

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

A more detailed example in YAML:

# Yaml metadata example
blockExplorers:
  - apiUrl: https://api-sepolia.etherscan.io/api
    family: etherscan
    name: Etherscan
    url: https://sepolia.etherscan.io
blocks:
  confirmations: 1
  estimateBlockTime: 13
  reorgPeriod: 2
chainId: 11155111
deployer:
  name: Abacus Works
  url: https://www.hyperlane.xyz
displayName: Sepolia
domainId: 11155111
isTestnet: true
name: sepolia
nativeToken:
  decimals: 18
  name: Ether
  symbol: ETH
protocol: ethereum
rpcUrls:
  - http: https://ethereum-sepolia.publicnode.com
  - http: https://ethereum-sepolia.blockpi.network/v1/rpc/public
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.