> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hyperlane.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Deploy to a New Chain

> Step-by-step guide on how to connect your chain with Hyperlane

<Note>
  * This guide is for **EVM-compatible** chains only.
  * For Cosmos SDK chains, use [Deploy to a Cosmos Chain](/docs/guides/chains/deploy-hyperlane-cosmos).
  * It will walk you through deploying Hyperlane to your new chain as quickly as possible for testing, not production. This includes the core Mailbox and ISM contracts as well as Hyperlane Warp Route contracts for asset bridging.
  * To see which chains are already supported, visit the [Registry](https://github.com/hyperlane-xyz/hyperlane-registry/tree/main/chains).
  * If you need any help, reach out on [GitHub Discussions](https://github.com/hyperlane-xyz/hyperlane-monorepo/discussions) or [get in touch](https://forms.gle/KyRTaWvo4XNmNvrq6).
</Note>

## Prerequisites

Anyone can begin this quickstart guide once they have the following artifacts & assets available:

* A new, custom, or pre-existing network of your choice, including the following metadata:
  * A chain name, e.g. `ethereum`
  * A chain ID, e.g. `1`
  * A RPC URL, e.g. `https://eth.llamarpc.com`
* A deployer wallet/EOA private key or seed phrase
  * This EOA should be funded on your custom chain and any chain you will be passing messages to & from
* [Hyperlane CLI](/docs/reference/developer-tools/cli)

## 1. Registry

Let’s create a custom chain config, run:

```bash theme={null}
hyperlane registry init
```

Follow the prompts to set up your chain metadata. Setting up block or gas properties is optional.

Now, under `$HOME/.hyperlane/chains` you will find a new folder named with your custom chain’s name, and a file named `metadata.yaml` within that folder.

<details>
  <summary>
    Example content of this config at `$HOME/.hyperlane/chains/yourchain/metadata.yaml`
  </summary>

  ```yaml theme={null}
  # yaml-language-server: $schema=../schema.json
  # Metadata for your custom chain

  blockExplorers:
    - apiUrl: https://explorer.yourchain.com/api
      apiKey: XXXX # helpful to avoid rate limiting on the contract verification API
      family: etherscan #explorer you're using, also supporting routescan or blockscout
      name: Chainscan
      url: https://explorer.yourchain.com
  blocks:
    confirmations: 1
    estimateBlockTime: 1
    reorgPeriod: 0
  chainId: 171717
  displayName: Chain Name
  domainId: 171717
  isTestnet: true # optional
  name: yourchain
  nativeToken:
    name: Ether
    symbol: ETH
    decimals: 18
  protocol: ethereum
  rpcUrls:
    - http: https://hyper-lane-docs.rpc.caldera.xyz/http
  ```
</details>

## 2. Core

Next, let’s configure, deploy and test your custom chain’s core contracts.

### Initialize configuration

1. From your local environment, set the private key or seed phrase of your funded deployer address to `HYP_KEY`. For example: `export HYP_KEY='<YOUR_PRIVATE_KEY>'`
2. From the same terminal instance, run:

```bash theme={null}
hyperlane core init
```

<details>
  <summary>
    The deployment config will be written to `./configs/core-config.yaml`
  </summary>

  ```yaml theme={null}
  # The address that owns and manages the deployed contracts. This account has admin privileges.
  owner: "0x16F4898F47c085C41d7Cc6b1dc72B91EA617dcBb"

  # The default Interchain Security Module (ISM) configuration.
  defaultIsm:
    #`type`: Specifies the type of ISM. Here, it uses a trusted relayer ism.
    type: trustedRelayerIsm
    #`relayer`: The address of the relayer responsible for processing interchain messages.
    relayer: "0x16F4898F47c085C41d7Cc6b1dc72B91EA617dcBb"

  defaultHook:
    # A hook configuration that specifies the use of a Merkle Tree.
    type: merkleTreeHook

  requiredHook:
    # The owner address responsible for managing the hook configuration.
    owner: "0x16F4898F47c085C41d7Cc6b1dc72B91EA617dcBb"
    # The type of hook. This one applies a protocol fee mechanism.
    type: protocolFee
    # The address that receives the protocol fees.
    beneficiary: "0x16F4898F47c085C41d7Cc6b1dc72B91EA617dcBb"
    # The maximum fee allowed by the protocol, in wei.
    maxProtocolFee: "100000000000000000"
    # The current fee charged by the protocol, set to 0 for testing purposes.
    protocolFee: "0"
  ```
</details>

### Deploy contracts

To deploy contracts, run:

```bash theme={null}
hyperlane core deploy
```

Use the arrows and enter to select your custom chain from the bottom of the mainnet list. It will take a few minutes for all contracts to deploy.

<details>
  <summary>
    Under `$HOME/.hyperlane/chains` you will find a new folder named with your
    custom chain’s name, and a file named `addresses.yaml` within that folder
  </summary>

  ```yaml theme={null}
  staticMerkleRootMultisigIsmFactory: "0x6906cb4741d3E2322E9f9aA645DfC8AB6F122c47"
  staticMessageIdMultisigIsmFactory: "0x3CE97a32d9C8294691cBd2baC09B078EDa75c429"
  staticAggregationIsmFactory: "0x81f969fDBF48278Ce09685Ce48e03388B6785aF4"
  staticAggregationHookFactory: "0x3d864A3c25F61E3c3A7d02e980453A6E1f0a92A6"
  domainRoutingIsmFactory: "0xC4c01f7B03f0fFa77A0265C600dEF7Ad28BCa5A2"
  proxyAdmin: "0xABb7175d5F123172E7B7Fa467CC9fE4C2FEdb942"
  mailbox: "0x5F58d75A9caDE4e2b191313223978dF049f93b81"
  interchainAccountRouter: "0x43c0745b0dE9Cb780816a24ddE63d79Ca99B5dE8"
  interchainAccountIsm: "0x9C96dC8f4257413225d6B5C47d1afbafc39B269F"
  validatorAnnounce: "0xE3bd39BF92DB385dE6313D6070b035bD934378CB"
  testRecipient: "0xa58462b1943Be1469Ed58db690C78583BA34Fd2E"
  ```
</details>

<Warning>
  * `eth_getStorageAt()` Compatibility: Some chains may not utilize the
    [`eth_getStorageAt()`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getstorageat)
    API. If your deployment encounters related issues, refer to the
    [Troubleshooting
    Guide](/docs/guides/deploy-hyperlane-troubleshooting#eth-getstorageat-compatibility).
</Warning>

### Send test message

To send a test message, run:

```bash theme={null}
hyperlane send message --relay
```

The `--relay` flag is optional and will deliver the message to the destination chain.

You can also run a relayer in the background with

```bash theme={null}
hyperlane relayer --chains yourchain,sepolia
```

<Check>
  **🎉 Congrats! You have successfully sent a message to your custom chain**
</Check>

## 3. Hyperlane Warp Route

Now that you have a Hyperlane Mailbox and core contracts on your chain, it’s time to set up token bridging between your chain and any other Hyperlane chain.

Continue on to the [Deploy a Hyperlane Warp Route](/docs/guides/quickstart/deploy-warp-route) docs for more details.

## 4. Submit to Registry

If you want other chains to connect with you as well as to take this to production, make a registry PR.

### Ensure complete info

Make sure your metadata is complete:

* add a `logo.svg` file inside the folder
* include `Deployer` information identifying the team deploying
* indicate `isTestnet` `true` if the chain is testnet
* add the api url `gnosisSafeTransactionServiceUrl` if you have a gnosis safe service
* lint the yaml files and order alphabetically

### Commit to GitHub

First, navigate to your local instance of the registry and commit changes

```bash theme={null}
cd ~/.hyperlane && git init && git add . && git commit
```

Then, sync local registry with canonical registry

```bash theme={null}
git remote add canonical git@github.com:hyperlane-xyz/hyperlane-registry.git
git pull canonical main --rebase
```

Finally, push local registry to github fork and submit a PR. Please include a [changeset](https://github.com/changesets/changesets/blob/main/docs/adding-a-changeset.md) in your PR.

<Check>
  **Congrats! You have successfully deployed Hyperlane to your chain and added your work to the Hyperlane registry**

  Thank you for contributing to the future of permissionless interop 🫡
</Check>