core-deploy - SKILL.md Agent Skill

name: core-deploy description: Use this skill when deploying, applying, updating, verifying, or debugging Hyperlane core deployments in this repository, including EVM and cosmosnative/Celestia flows.

Core Deploy Skill

When to use

Use this skill when the task involves any of the following in this repo:

Adding or updating Hyperlane core deployment config files under configs/<chain>-core.yaml
Running hyperlane core init, hyperlane core deploy, hyperlane core apply, or hyperlane core read
Updating chains/<chain>/addresses.yaml or aggregated chains/addresses.yaml with core addresses
Configuring Mailbox default ISM, default hook, required hook, IGP, or domain routing ISM
Onboarding a new remote domain to a Celestia/cosmosnative core deployment
Verifying core addresses, hook/ISM configuration, relayer readiness, or gas/ISM routing

Required user input intake

Before drafting configs or running deploy/apply commands, explicitly ask the user for missing core deployment inputs.

Minimum required inputs:

target chain name from this repo, e.g. edentestnet, sepolia, celestiatestnet
protocol path: ethereum/EVM or cosmosnative
deploy intent: new deployment vs update existing deployment
owner address for the chain/protocol address format
target security posture: testnet/dev vs mainnet/production

Also ask/confirm when unclear:

desired default ISM (testIsm, domainRoutingIsm, merkleRootMultisig, etc.)
desired default hook (protocolFee or interchainGasPaymaster)
desired required hook (merkleTreeHook or a composed/aggregation hook)
remote domains/chains to register in domainRoutingIsm and IGP configs
IGP beneficiary, oracleKey, oracleConfig, overhead, gas price, and token exchange rate values
validator addresses and threshold for multisig ISM setup
whether ownership is a multisig and whether the CLI can sign the needed changes
whether relayer/config.json and docs/indexes should be updated after deployment

Source of truth

Treat this repository as the canonical Hyperlane registry. Use local registry files for chain names, domain IDs, protocol types, RPC URLs, owners, and deployed addresses.

When behavior, commands, config shape, or operational details are unspecified or unclear, refer to the local docs in docs/ before proceeding.

Required environment

Before CLI operations, ensure:

HYP_KEY is set for EVM-chain signing
HYP_KEY_COSMOSNATIVE is set for Celestia/cosmosnative signing

Optional:

HYP_MNEMONIC if direct celestia-appd key recovery is needed
chain-specific keys like HYP_CHAINS_<CHAIN>_SIGNER_KEY from .env

Never commit secrets/private keys. The user must authorize CLI tooling before the agent runs it on their behalf.

Deployer readiness gate

Always verify deployer configuration before running hyperlane core deploy or hyperlane core apply.

Default behavior:

use HYP_KEY for EVM chains
use HYP_KEY_COSMOSNATIVE for cosmosnative chains

If the required key is missing:

stop and prompt the user to set it or confirm an alternate signer/multisig flow
do not proceed with deploy/apply until signer configuration is explicit

For mainnet or multisig-owned deployments:

do not assume CLI core apply can mutate ownership-gated config
generate or prepare the exact multisig transactions when needed
prefer dry-run/read-only validation before proposing writes

Workflow

1) Preflight

Confirm required user inputs are collected.
Read chains/<chain>/metadata.yaml and confirm name, domainId, chainId, protocol, RPC URLs, native token, and gas settings.
Read existing chains/<chain>/addresses.yaml and configs/<chain>-core.yaml if present.
Confirm the chain exists in aggregated chains/metadata.yaml; if adding a new chain, keep per-chain and aggregate files aligned with chains/schema.json.
Confirm deployer readiness for the protocol.
Confirm intended config file path: configs/<chain>-core.yaml.
Use --registry . on every Hyperlane CLI command in this repo.

2) EVM core deploy path

Use this path when chains/<chain>/metadata.yaml has protocol: ethereum.

Recommended testnet/dev defaults:

defaultIsm: testIsm (no production security guarantees)
defaultHook: protocolFee (often fee 0)
requiredHook: merkleTreeHook

Recommended mainnet/production shape:

defaultIsm: domainRoutingIsm with per-domain ISMs, commonly merkleRootMultiSig
defaultHook: interchainGasPaymaster with per-domain gas config
requiredHook: merkleTreeHook or a deliberate required aggregation hook

Initialize config:

hyperlane core init --advanced --config configs/<chain>-core.yaml --registry .

Deploy:

hyperlane core deploy --chain <chain> --config configs/<chain>-core.yaml --registry .

Read back on-chain state:

hyperlane core read --chain <chain> --config configs/<chain>-core.yaml --registry .

Expected outputs:

deployed addresses in chains/<chain>/addresses.yaml
refreshed core artifact in configs/<chain>-core.yaml

After deploy/read, mirror address changes into chains/addresses.yaml if the CLI did not update the aggregate file.

3) Cosmosnative core deploy path

Use this path when chains/<chain>/metadata.yaml has protocol: cosmosnative (for example Celestia or Noble).

For cosmosnative chains, prefer existing local registry metadata or official registry metadata over interactive hyperlane registry init prompts.

Author configs/<chain>-core.yaml explicitly. The typical Celestia shape is:

owner: bech32 owner address
defaultHook.type: interchainGasPaymaster
defaultHook.beneficiary: bech32 recipient for gas payments
defaultHook.oracleKey: bech32 gas oracle updater key
defaultHook.oracleConfig.<remote-chain> with gasPrice, tokenExchangeRate, and tokenDecimals when required by the local config shape
defaultHook.overhead.<remote-chain>
defaultIsm.type: domainRoutingIsm
defaultIsm.domains.<remote-chain> with the desired ISM, often testIsm in testnets
requiredHook.type: merkleTreeHook

Deploy:

hyperlane core deploy --chain <chain> --config configs/<chain>-core.yaml --registry .

Read back on-chain state:

hyperlane core read --chain <chain> --config configs/<chain>-core.yaml --registry .

Expected outputs:

deployed module IDs/addresses in chains/<chain>/addresses.yaml
refreshed core artifact in configs/<chain>-core.yaml

After deploy/read, mirror address changes into chains/addresses.yaml if the CLI did not update the aggregate file.

4) Updating existing core deployment

Use core apply for deliberate config changes after reading current on-chain state first.

Read current state:

hyperlane core read --chain <chain> --config configs/<chain>-core.yaml --registry .

Edit configs/<chain>-core.yaml with the intended changes only.

Apply:

hyperlane core apply --chain <chain> --config configs/<chain>-core.yaml --registry .

Read again:

hyperlane core read --chain <chain> --config configs/<chain>-core.yaml --registry .

For IGP-only recurring updates, avoid broad automated core apply unless the signer is intended to own broad core config. Prefer direct, narrowly scoped IGP/oracle setter transactions when automation should only update gas pricing.

5) Celestia remote-domain onboarding

Before a Warp Route can reliably send between Celestia and a new remote chain, Celestia core needs both:

a routing ISM entry for the remote domain (inbound verification)
an IGP destination gas config for the remote domain (outbound gas quoting/payment)

Use docs/new-chain-onboarding.md for the Celestia transaction flow:

Create a Merkle root multisig ISM when using multisig security:

celestia-appd tx hyperlane ism create-merkle-root-multisig <validators> <threshold> <flags>

celestia-appd tx hyperlane ism set-routing-ism-domain <routing-ism-id> <domain> <ism-id> <flags>

Set destination gas config:

celestia-appd tx hyperlane hooks igp set-destination-gas-config <igp-id> <remote-domain> <token-exchange-rate> <gas-price> <gas-overhead> <flags>

For multisig-owned Celestia deployments, use --generate-only where appropriate and have multisig participants sign externally.

6) Relayer follow-up

After adding or changing a core chain, check whether relayer/config.json needs the chain in relayChains and matching chain settings.

Useful checks:

docker compose ps
docker logs hyperlane-relayer -f

Verification checklist

After deploy/apply/read:

configs/<chain>-core.yaml contains addresses for deployed hooks/ISMs where applicable
chains/<chain>/addresses.yaml contains expected core addresses such as mailbox, merkleTreeHook, interchainGasPaymaster, interchainSecurityModule, factories, or validatorAnnounce
chains/addresses.yaml mirrors per-chain address changes
hyperlane core read --chain <chain> --config configs/<chain>-core.yaml --registry . succeeds
default ISM and hook choices match the intended security posture
domainRoutingIsm has all required remote domains
IGP has all required remote destination gas configs
relayer config is updated if the chain should be relayed

For EVM-specific verification, use cast call against the chain RPC when needed to confirm Mailbox owner/hooks or contract getters.

For cosmosnative-specific verification, use celestia-appd query hyperlane ... commands from the docs to confirm ISM, hook, IGP, and routing module state when CLI read output is insufficient.

Guardrails

Always pass --registry . for Hyperlane CLI commands in this repo.
Do not overwrite unrelated chain addresses, configs, or warp route artifacts.
Do not commit .env or private keys.
Treat testIsm as testnet/dev-only unless the user explicitly accepts its security properties.
For domainRoutingIsm and interchainGasPaymaster, missing remote-domain entries can break inbound verification or outbound gas quoting.
For required safety controls, prefer requiredHook; defaultHook may be overrideable by callers depending on dispatch path.
Read before apply, apply only intentional changes, then read again.