> ## 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 Cosmos Chain

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

<Note>
  * This guide is for **Cosmos SDK** chains with the Hyperlane module integrated. For CosmWasm-based chains, see the [CosmWasm implementation](https://github.com/many-things/cw-hyperlane).
  * 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 components as well as Hyperlane Warp Route components 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 Cosmos SDK chain with the Hyperlane module integrated (including the `x/core` and `x/warp` modules)
* A new, custom, or pre-existing Cosmos SDK network of your choice, including the following metadata:
  * The chain name, e.g. `hyp1`
  * The chain ID, e.g. `hyperlane-local-1`
  * The bech32 prefix, e.g. `hyp`
  * RPC, REST, and gRPC URLs
  * Native token denomination and gas price
* A deployer wallet hex private key (64 hex characters, with or without `0x` prefix)
  * This wallet should be funded on your custom chain and any chain you will be passing messages to & from
  * If you use a mnemonic wallet, export/derive the raw hex private key before running CLI commands
* [Hyperlane CLI](/docs/reference/developer-tools/cli)

## 1. Registry

The `hyperlane registry init` command is currently designed for EVM chains and does not support Cosmos SDK chains. Instead, create your chain metadata file manually.

Create the directory and file:

```bash theme={null}
mkdir -p $HOME/.hyperlane/chains/yourchain
```

Then create `$HOME/.hyperlane/chains/yourchain/metadata.yaml` with the following content, replacing values with your chain's details:

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

bech32Prefix: hyp
chainId: hyperlane-local-1
displayName: My Cosmos Chain
domainId: 758986691 # Must be globally unique; generate with: python3 -c 'print(int("NAME".encode().hex(), 16) % 4_294_967_295)'
name: yourchain
protocol: cosmosnative
slip44: 118
nativeToken:
  decimals: 6
  denom: uhyp
  name: TEST
  symbol: TEST
gasPrice:
  amount: '0.2'
  denom: uhyp
rpcUrls:
  - http: http://127.0.0.1:26657
restUrls:
  - http: http://127.0.0.1:1317
grpcUrls:
  - http: http://127.0.0.1:9090
blockExplorers:
  - name: My Chain Explorer
    url: https://mychain.com/explorer
    apiUrl: https://mychain.com/explorer/api
```

<Note>
  Key Cosmos-specific fields:

  * **`protocol: cosmosnative`** — Must be exactly `cosmosnative` (not `cosmos` or `ethereum`)
  * **`bech32Prefix`** — Your chain's address prefix (e.g. `cosmos`, `osmo`, `hyp`)
  * **`slip44`** — [SLIP-44](https://github.com/satoshilabs/slips/blob/master/slip-0044.md) coin type (use `118` for standard Cosmos chains)
  * **`grpcUrls`** — Required for Cosmos SDK chains
  * **`gasPrice`** — Must include both `amount` and `denom`
  * **`nativeToken.denom`** — The on-chain denomination (e.g. `uatom`, `uosmo`)
  * **`domainId`** — Must be unique across the Hyperlane network (do not reuse another chain's domain)
</Note>

## 2. Core

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

### Create Configuration

1. Set the hex private key of your funded deployer address for Cosmos-native operations:
   * `export HYP_KEY_COSMOSNATIVE='<YOUR_PRIVATE_KEY>'` (64 hex characters, with or without `0x` prefix)
   * Or pass `--key.cosmosnative` directly to deploy commands
2. Create `./configs/core-config.yaml` using the template below.

<Note>
  `HYP_KEY` is treated as the legacy Ethereum shared key in the current CLI. For Cosmos SDK chains, use `HYP_KEY_COSMOSNATIVE` (or `--key.cosmosnative`) to avoid key prompts.
</Note>

<details>
  <summary>
    Use this template for `./configs/core-config.yaml`
  </summary>

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

  # The default Interchain Security Module (ISM) configuration.
  defaultIsm:
    # Specifies the type of ISM. Here, it uses a multisig ISM.
    type: merkleRootMultisigIsm
    threshold: 1
    validators:
      # Validators use hex addresses (0x...) even on Cosmos chains.
      - '0x0c60e7eCd06429052223C78452F791AAb5C5CAc6'

  defaultHook:
    # A hook configuration that specifies the use of an Interchain Gas Paymaster.
    type: interchainGasPaymaster
    owner: "hyp1jq304cthpx0lwhpqzrdjrcza559ukyy3sc4dw5"
    beneficiary: "hyp1jq304cthpx0lwhpqzrdjrcza559ukyy3sc4dw5"
    # Address authorized to set gas oracle prices. On Cosmos, typically the same as owner.
    oracleKey: "hyp1jq304cthpx0lwhpqzrdjrcza559ukyy3sc4dw5"
    overhead:
      hyp: 200000
    oracleConfig:
      hyp:
        gasPrice: '1'
        tokenDecimals: 6
        tokenExchangeRate: '10000000000'

  requiredHook:
    # The type of hook. This one applies a Merkle Tree for message dispatch.
    type: merkleTreeHook
  ```
</details>

### Deploy

To deploy, run:

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

Use the arrows and enter to select your custom chain from the bottom of the list. It will take a few minutes for all components 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}
  # Example — your actual Hex32 IDs will differ
  mailbox: "0x68797065726c616e650000000000000000000000000000000000000000000000"
  validatorAnnounce: "0x68797065726c616e650000000000000000000000000000000000000000000000"
  staticMerkleRootMultisigIsmFactory: "0x68797065726c616e650000000000000000000000000000000000000000000000"  # Populated based on your ISM type
  # Other factory fields may appear as empty strings
  ```
</details>

<Note>
  [Aggregation ISMs](/docs/protocol/ISM/standard-ISMs/aggregation-ISM) are currently not supported on Cosmos SDK chains due to AltVM limitations. Use `messageIdMultisigIsm` or `merkleRootMultisigIsm` instead.
</Note>

### Verify Deployment

After deployment, verify your core components are configured correctly:

```bash theme={null}
hyperlane core read --chain yourchain
```

<Note>
  `hyperlane send message` does not currently support Cosmos SDK chains. To test message delivery, deploy a [Warp Route](/docs/guides/warp-routes/cosmos/cosmos-warp-route-guide) and use a [relayer](/docs/operate/relayer/run-relayer) to process transfers.
</Note>

### Update Core Configuration (Day 2)

Use `core read` output as your editable config for updates such as validator rotation, default ISM changes, or gas oracle updates:

```bash theme={null}
hyperlane core read --chain yourchain --config ./yourchain-core.yaml
# Edit ./yourchain-core.yaml
hyperlane core apply --chain yourchain --config ./yourchain-core.yaml
```

<Note>
  Once ownership has been transferred away from the deployer, `core apply` will no longer work with the deployer key alone. Use the `--strategy` flag with a file submitter to submit transactions through the new owner (e.g. a multisig).
</Note>

For production hardening, see:

* [Update Mailbox Default ISM](/docs/guides/production/core-deployment/update-mailbox-default-ism)
* [Transfer Mailbox Ownership](/docs/guides/production/core-deployment/transfer-mailbox-ownership)

<Check>
  **🎉 Congrats! You have successfully deployed Hyperlane core to your custom Cosmos chain**
</Check>

## 3. Hyperlane Warp Route

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

Continue with one of the following guides:

* [Deploy a Cosmos Warp Route](/docs/guides/warp-routes/cosmos/cosmos-warp-route-guide)
* [Deploy an EVM ↔ Cosmos HWR](/docs/guides/warp-routes/evm-cosmos-warp-route-guide)
* [Deploy a Cosmos ↔ SVM HWR](/docs/guides/warp-routes/cosmos-svm-warp-route-guide)

## 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
* 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 Cosmos chain and added your work to the Hyperlane registry**
</Check>