Warp Route Deploy Init

You are generating the initial deploy.yaml for a new Hyperlane warp route deployment.

Step 0: Confirm the working environment

Before anything else, surface the checkout you're operating in so a stale-branch or wrong-directory run is visible up front:

git rev-parse --show-toplevel && git rev-parse --abbrev-ref HEAD

Skills load from whatever branch is checked out — running an older branch's copy silently follows outdated instructions. Confirm with the operator that this is the intended monorepo + branch before proceeding. (This is a visibility check; a hard "you must be on branch X" validation belongs at the harness level, since the skill can't know the intended branch on its own.)

PREREQUISITE (per-chain gate): confirmed sufficient deployer funds

Before running warp deploy, EVERY chain in the route must be in one of two states:

1. Verified sufficient — the deployer's native balance (and, on collateral chains, ≥ 1 USD of the collateral token) has been checked via /warp-deploy-fund-deployer — or an equivalent manual check appropriate to the chain's billing model — and reported ✅ OK for the route's shape (base-collateral vs cross-collateral vs cross-collateral + fee program each require different floors on non-EVM chains; see /warp-deploy-fund-deployer Step 5's shape table).
2. Verified short and topped up — a ⚠️ LOW / ❌ EMPTY was funded to ✅ OK before proceeding.

If you are unsure about a chain, treat it as unverified — run /warp-deploy-fund-deployer <ticket-id> and let it check. It is a preflight, not an unconditional funding action: chains already at ✅ OK are skipped, only shortfalls trigger transfers.

The gate is per-chain, not per-run. If a prior session already left ethereum at ✅ OK and nothing has changed since (no other deploys draining the key), skipping re-check on that chain is fine. Any chain that is unverified OR short must be resolved before Step 1.

Why: an under-funded chain fails mid-deploy after partial contract deployment on other chains, leaving orphaned artifacts that need manual cleanup before a retry. Fund-deployer's role is to catch shortfalls up front. The reactive text later in Step 8 ("insufficient gas → run /warp-deploy-fund-deployer first") is a defensive fallback for state that decayed between preflight and deploy — it is not a substitute for the preflight itself.

Run Log (mandatory)

Maintain the durable, per-ticket run log per /warp-run-log — that skill owns the storage contract (Linear-document-by-title primary, single-writer discipline, local-file fallback), the chain | protocol | shape | floor | actual | verdict machine-row + prose entry shape, and the surface-the-URL-as-proof hard gate. Use warp-deploy-init-route as the skill name in each prose entry, and do not report this skill complete until the run-log URL has been surfaced.

Log at least: (a) skill entry with the ticket ID, (b) every [CONFIRM:] gate — before showing it to the user AND after their response, (c) every command execution, with expected vs actual (gas amounts, tx hashes, deployed addresses, wall-clock times), (d) skill exit (success or bail-out). If any number, timing, or output diverges from what this skill's text predicts, log it — the diff is the input to the next skill revision. Log smooth steps too — success data grounds the retrospective as much as failure data.

Input

The user provides:

• Linear ticket URL or ID (required, e.g. ENG-3516 or https://linear.app/hyperlane-xyz/issue/ENG-3516/...)

If the ticket is not provided, ask for it now.

Key Context (Prerequisite)

This skill needs deployer key(s) per protocol to sign the warp-deploy txs, and the matching deployer address per protocol to fill owner fields in the deploy.yaml. It auto-loads ~/.hyperlane/key-contexts/<ticket-id>.yaml produced by /warp-deploy-select-keys. If the artifact does not exist, invoke /warp-deploy-select-keys <ticket-id> first — do not ask the user for an env var name or a deployer address inline.

From the artifact, read per protocol:

• keys.<protocol>.name — the GCP secret name (or env var name) for the signer
• keys.<protocol>.address — the derived address used as owner in the deploy.yaml on all chains of that protocol

A pure-EVM route uses one ethereum key + one EVM owner address across all EVM chains. A cross-VM route uses one key + address per protocol. Real ownership is transferred later via /warp-deploy-update-owners — never use real Safe/ICA addresses in this step.

---

Step 1: Fetch the Linear Ticket

Fetch the ticket per /fetch-linear-ticket — it extracts the issue ID, fetches via the agent's Linear integration or the GraphQL API + LINEAR_API_KEY, halts if neither is configured, and shows the title + description. Extract the Step 2 fields from that returned description.

---

Step 2: Extract Warp Route Details

Parse the ticket description to extract the following. Read every value from the ticket itself — do not infer it by copying a similar-looking existing route's deploy.yaml. Existing production deploy.yamls are a reference for structural format only. The warp route ID, fee type, per-chain owners, and (for offchain-quoted fees) quote signers are ticket-specific and are the fields most often drafted wrong from a prior route — copy each verbatim from the ticket. Ask the user to clarify anything that is ambiguous or missing:

Field	Description
Token name	Full name (e.g. RISE)
Token symbol	Symbol (e.g. RISE)
Warp route ID	The route's registry ID exactly as the ticket gives it (e.g. WBTC/staging). If the ticket states one, use it verbatim — do NOT synthesize a <TOKEN>/<chains> name. Only derive <TOKEN>/<chains-alphabetical> (Step 7a) when the ticket gives no explicit ID.
Decimals	Token decimals (e.g. 18) — use the reference table below for USDC; query on-chain if unsure
Collateral chain(s)	Chain(s) where the real token lives — may be multiple for multi-collateral routes
Collateral token address(es)	ERC-20 contract address per collateral chain — use the reference table below for USDC
Synthetic chains	Chains that get a synthetic (bridged) representation
Warp fee	Fee in basis points (bps) + direction (deposits / withdrawals) from the ticket's Warp Fee checkboxes
Fee type	The fee contract type the ticket specifies (LinearFee, OffchainQuotedLinearFee, …). Take it from the ticket — never default to whatever type a similar route happened to use. OffchainQuotedLinearFee additionally requires quoteSigners (below).
Fee owner	Address that receives fees — defaults to "Standard AW controlled ICA" per the ticket
Quote signers	OffchainQuotedLinearFee only: the EVM (hex) addresses authorized to sign off-chain quotes, from the ticket. Required whenever the fee type is offchain-quoted; omitting them ships a fee contract nobody can quote against.
Type overrides	Any chain that should be native instead of collateral/synthetic
Yield route type	If the ticket mentions yield/ERC4626/vault, determine the yield subtype (see below)
Daily Rate Limit	Optional amount (e.g. 200,000,000) — present in the structured Daily Rate Limit row on newer tickets. If present, the route adds a rate-limited hook on the synthetic chain (see Step 4).

Validate the token symbol UNCONDITIONALLY and FIRST — before the eager logo download (below) or any other filesystem write, and regardless of whether the ticket gives an explicit route ID. <TOKEN> (the symbol) is used verbatim as the registry directory deployments/warp_routes/<TOKEN>/, as the logo path, and — when no explicit ID is given — as the base of the derived route ID; a symbol containing ../, whitespace, or shell metacharacters would escape the registry directory or inject into the curl/deploy commands well before Step 7 validates the derived ID. Require: a single path component matching ^[A-Za-z0-9._-]+$, neither . nor .., no whitespace, no shell metacharacters (; | & $ ` > < ( ) * ? \). Then build any path from it (e.g. the logo path or deploy.yaml path), resolve non-strictly (realpath -m), and assert the result stays under $REGISTRY_PATH/deployments/warp_routes/<TOKEN>/ specifically before writing. Halt with a clear error on any violation.

Validate an explicit Warp route ID immediately — fail fast, here, before any registry/filesystem work. It must be exactly <TOKEN>/<suffix>: exactly one /; each of the two components matches ^[A-Za-z0-9._-]+$ and is neither . nor .. (a bare ./.. component matches the charset but is still a traversal); no whitespace, no shell metacharacters (; | & $ ` > < ( ) * ? \). The <TOKEN> component must equal the ticket's token symbol (the canonical registry key), not an arbitrary string. Halt with a clear error otherwise — the id later becomes a registry filename and a --warp-route-id argument, so a hostile value is a path-traversal / command-injection vector. When you later build the deploy.yaml path, resolve it non-strictly (realpath -m, which canonicalizes without requiring the file to exist — for a new deploy the deploy.yaml isn't created yet, so a strict realpath would error) and assert it stays under $REGISTRY_PATH/deployments/warp_routes/<TOKEN>/ specifically — a bare deployments/warp_routes/ check doesn't prove it didn't escape the token directory. (Re-validated the same way in Step 7a.)

Yield routes: if the ticket mentions "yield", "ERC4626", "vault", "rebasing", "Aave", or the token is a known yield-bearing token (sUSDS, sDAI, etc.), it is a yield route. There are two subtypes:

Ticket language	Collateral type	Synthetic type	Behavior
"owner yield" / "non-rebasing"	collateralVault	synthetic	Yield accrues to contract owner; owner calls sweep() to claim
"rebasing" / yield distributed to holders	collateralVaultRebase	syntheticRebase	Yield auto-distributes to all bridged token holders via exchange rate updates

If the ticket says "owner yield", use collateralVault + synthetic. If ambiguous, ask the user.

For collateralVault routes — check if the collateral token already implements ERC4626:

Run this check on the collateral token address from the ticket:

cast call <collateral-token-address> "asset()(address)" --rpc-url <RPC_URL>

• If asset() returns a non-zero address → the token IS an ERC4626 vault. Use it directly as token in the deploy.yaml. No vault deployment needed.

• If asset() reverts or returns zero → the token is a plain ERC20. Warn the user:

  ⚠️ The collateral token does not implement ERC4626. You must deploy an Aave ERC4626 vault wrapping it first using hyperlane-xyz/Aave-Vault, then replace <VAULT_ADDRESS> in the deploy.yaml with the deployed vault address. The vault owner controls who can sweep() yield — confirm the yield beneficiary with product before deploying.

  Real example: WETH/incentiv vault 0xB1ea329f0B79d0b213957569594ca2a9dE637215 = "Wrapped Aave Ethereum WETH" (waEthWETH), underlying = WETH 0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2

  Use <VAULT_ADDRESS> as a placeholder in the deploy.yaml until the vault is deployed.

collateralVaultRebase constraint: ALL destination chains MUST be syntheticRebase — you cannot mix syntheticRebase with synthetic in the same route. Each syntheticRebase chain requires a collateralChainName field pointing to the collateral chain.

Multi-collateral routes: when the ticket lists multiple collateral chains, each gets its own token address. All owner fields use the deployer address — real ICA/multisig addresses are set later in /warp-deploy-update-owners.

Rebalancing: if the ticket includes liquidity weights (e.g. 35% ethereum, 20% arb…), the route uses the rebalancer. Add allowedRebalancers and allowedRebalancingBridges to each collateral chain (not synthetic). Use the hardcoded values in the reference tables below — no need to search the registry. The weights themselves are NOT in the deploy.yaml — they go in typescript/infra/config/environments/mainnet3/balances/desiredRebalancerBalances.json in the monorepo. Flag this to the user as a separate step.

Daily Rate Limit: if the ticket's Daily Rate Limit row is set (e.g. 200,000,000), the route needs a rate-limited hook on the synthetic chain. Add the hook config to that chain's entry in deploy.yaml. The value is the daily rate limit cap in the token's smallest unit (i.e. apply × 10^decimals to the human-readable number from the ticket).

Ownership validation prerequisite: before generating the deploy.yaml in Step 4, the agent invokes /warp-deploy-validate-owners with the same Linear ticket as input. That skill produces a per-chain owner resolution table (ICA / Safe / Squads / EOA-rejected). The deploy.yaml in Step 4 uses the same deployer address for owner fields (real owner transfer happens later in /warp-deploy-update-owners), but the validation pass ensures the eventual owners are valid before any chain is touched. If /warp-deploy-validate-owners reports any ❌ row, abort — don't proceed to deploy against rejected owners.

Logo handling: the Linear ticket's SVG logo row links to a Linear upload URL with ?signature=…&exp=… JWT parameters that expire (typically ~5 minutes). To prevent 401s mid-flow on longer runs, download the logo eagerly right after fetching the ticket in Step 1 and cache it locally to <registry>/deployments/warp_routes/<TOKEN>/logo.<ext>:

# After mcp__plugin_linear_linear__get_issue returns, grab the SVG/PNG row's image URL
curl -sSL -o "$REGISTRY_PATH/deployments/warp_routes/<TOKEN>/logo.<ext>" "<signed-url>"

Use logo.svg if the upload is SVG; logo.png otherwise. The local file is then referenced by logoURI in <chain>-config.yaml later (/warp-deploy-update-owners Step 11b). Eagerly downloading prevents the signed URL from expiring before that later step needs to read it.

---

Reference: Known Token Addresses and Bridge Contracts

USDC (decimals: 6)

Chain	Token Address
ethereum	0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48
arbitrum	0xaf88d065e77c8cC2239327C5EDb3A432268e5831
base	0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
optimism	0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85
polygon	0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359
avalanche	0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E
unichain	0x078D782b760474a361dDA0AF3839290b0EF57AD6
linea	0x176211869cA2b568f2A7D4EE941E073a821EE1ff
worldchain	0x79A02482A880bCE3F13e09Da970dC34db4CD24d1
hyperevm	0xb88339CB7199b77E23DB6E890353E22632Ba630f
ink	0x2D270e6886d130D724215A266106e6832161EAEd

Rebalancer

Single rebalancer address used across all multi-collateral routes:

0xa3948a15e1d0778a7d53268b651B2411AF198FE3

CCTP Bridge Addresses (per source chain)

Used in allowedRebalancingBridges on each collateral chain. The two addresses are the CCTP bridge contracts on that source chain — list them for every destination collateral chain in the route.

Source Chain	Bridge Address 1	Bridge Address 2
ethereum	0x8c8D831E1e879604b4B304a2c951B8AEe3aB3a23	0x7A576Bb5291567cfDbB4585B1911CF7C9891ea07
arbitrum	0x4c19c653a8419A475d9B6735511cB81C15b8d9b2	0xE086378F7f0afd5C3ff95E10B5e7806a0901b33f
base	0x33e94B6D2ae697c16a750dB7c3d9443622C4405a	0x31169ee5A8C0D680de74461d7B5394fFc7C3576B
optimism	0x33e94B6D2ae697c16a750dB7c3d9443622C4405a	0x4eFaacbf0D3d57b401Cb6B559e84b344448b0C30
polygon	0x33e94B6D2ae697c16a750dB7c3d9443622C4405a	0x07d89DE0F7E18c9bcAAE81F44aee9CA02EBeE872
avalanche	0x33e94B6D2ae697c16a750dB7c3d9443622C4405a	0xCB35d7730843F770625bE36A0E4228c17fDcBC09
unichain	0x33e94B6D2ae697c16a750dB7c3d9443622C4405a	0xCB35d7730843F770625bE36A0E4228c17fDcBC09
linea	0x33e94B6D2ae697c16a750dB7c3d9443622C4405a	0x89aAa89D36F995b41d929f2D29b8Ee7C9c8e54cA
worldchain	0x33e94B6D2ae697c16a750dB7c3d9443622C4405a	0x89aAa89D36F995b41d929f2D29b8Ee7C9c8e54cA
hyperevm	0xDdf252a063f8c5C399B9ccDBbaDBA55225F53Da1	0xe10b7b030C75C80359841CB0ec892E233F03f145
ink	0x92dFEB6f7Daa532de0F3c75c2091e1607c6593b7	0x70CF23d09784fCA62be304c928BCA9F1801B1F21

Source: extracted from deployments/warp_routes/USDC/eclipsemainnet-deploy.yaml (2025-04-02). If a chain is missing from this table, look it up in that file.

---

Step 3: Look Up Mailbox Addresses

For each chain (collateral + synthetics), read the mailbox address from the local registry:

REGISTRY_PATH="$(pwd)/../hyperlane-registry"
cat "$REGISTRY_PATH/chains/<chain>/addresses.yaml" | grep "^mailbox:"

If a chain is not found in the registry, warn the user — the chain may not have a Hyperlane deployment yet.

For Sealevel chains (solanamainnet, eclipsemainnet): also look up the IGP address from the monorepo's program-ids.json (NOT from addresses.yaml):

cat "rust/sealevel/environments/mainnet3/<chain>/core/program-ids.json" | python3 -c "import sys,json; print(json.load(sys.stdin)['igp_program_id'])"

Known values (verify against the file before using):

Chain	igp_program_id
solanamainnet	BhNcatUDC2D5JTyeaqrdSukiVFsEHK7e3hVmKMztwefv
eclipsemainnet	Hs7KVBU67nBnWhDPZkEFwWqrFMUfJbmY2DQ4gmCZfaZp

Save this address — it is used as the hook field in Step 4.

---

Step 4: Generate deploy.yaml

Compose the deploy.yaml using the extracted details and mailbox addresses.

Canonical schema files — read these before authoring nested ISM / hook / fee configs. A deploy.yaml that fails Zod validation never reaches on-chain state — warp apply rejects it at parse time, but the resulting error output is voluminous; start from a correct shape:

• Per-chain router config (token type + ISM + hook + fee + proxyAdmin + remoteRouters + destinationGas): typescript/sdk/src/token/types.ts — HypTokenRouterConfigSchema is the per-chain entry; HypTokenConfig is the token-type discriminated union (collateral, native, synthetic, xerc20, opL1/L2, cctp, everclear, depositAddress, crossCollateral, unknown).
• ISMs: typescript/sdk/src/ism/types.ts — IsmConfigSchema union, plus per-type schemas (PausableIsmConfigSchema, RateLimitedIsmConfigSchema, AggregationIsmConfigSchema, RoutingIsmConfigSchema, etc.). Threshold semantics: staticAggregationIsm with threshold = modules.length is AND across all modules; threshold: 1 is OR.
• Hooks: typescript/sdk/src/hook/types.ts — HookConfigSchema union. Note defaultHook is the sentinel that means "use mailbox default"; fallbackRoutingHook is the standard pattern for "default hook on most chains, custom hook on a specific chain".
• Fees: typescript/sdk/src/fee/types.ts — TokenFeeConfigSchema discriminated union (LinearFee, OffchainQuotedLinearFee, RoutingFee, CrossCollateralRoutingFee, etc.). The bps field on LinearFee is immutable at the contract level so a bps edit redeploys the contract.
• Shared mixins: typescript/sdk/src/types.ts — OwnableSchema (owner + optional ownerOverrides) and PausableSchema (Ownable + paused: boolean). Many ISM / hook configs extend these, so owner is required on more types than the schema name alone suggests.

Token-type ⇔ fee-wrapper coupling (mandatory pairing). The outer fee wrapper on a chain's tokenFee block is constrained by the chain's token type:

Chain type	Outer tokenFee.type	Inner (per-destination) fee shape
synthetic / syntheticRebase	RoutingFee	feeContracts: Record<destChain, LinearFee | OffchainQuotedLinearFee | …> — single-level nesting
collateral / collateralVault / …	RoutingFee	Same as synthetic
crossCollateral	CrossCollateralRoutingFee	feeContracts: Record<destChain, Record<routerKey-bytes32, LinearFee | OffchainQuotedLinearFee | …>> — two-level nesting
native / nativeScaled	RoutingFee (if fees needed)	Same as synthetic

Cross-collateral routers MUST be paired with CrossCollateralRoutingFee — the inner routerKey layer maps the on-chain router (per crossCollateralRouters in the same chain block) to its fee contract. Attempting to use RoutingFee on a crossCollateral chain (or CrossCollateralRoutingFee on a plain collateral / synthetic chain) fails Zod validation at parse time.

SVM-specific fields on fee configs: on Sealevel chains, fee contracts can carry beneficiary: <base58> (the account that accrues collected fees, distinct from owner which controls limits). OffchainQuotedLinearFee also takes quoteSigners: [EVM hex address, …] — EVM addresses regardless of the fee contract's own protocol. Both fields visible in USDCFEE/sol-deploy.yaml and USDTFEE/sol-deploy.yaml on internal test branches; grep the registry for OffchainQuotedLinearFee for the current live shape.

Reference existing production deploy.yamls in the registry (deployments/warp_routes/*/*-deploy.yaml) — grep for the token type + protocol combination you want (e.g. a crossCollateral chain with type: LinearFee inside RoutingFee on a synthetic chain in the same route), then copy the canonical shape. Different protocols may need different fields (e.g. foreignDeployment on Sealevel synthetics, gas: 300000 on Sealevel entries, contractVersion on newer Sealevel deploys); the schema is protocol-aware.

Multi-collateral format (multiple collateral chains + one synthetic): same as standard but repeated for each collateral chain, each with its own token address and owner:

<collateral-chain-1>:
  decimals: <decimals>
  mailbox: '<mailbox-address>'
  name: <token-name>
  owner: '<owner-or-ica-address>'
  symbol: <token-symbol>
  token: '<token-address-on-this-chain>'
  type: collateral

<collateral-chain-2>:
  decimals: <decimals>
  mailbox: '<mailbox-address>'
  name: <token-name>
  owner: '<owner-or-ica-address>'
  symbol: <token-symbol>
  token: '<token-address-on-this-chain>'
  type: collateral

<synthetic-chain>:
  decimals: <decimals>
  mailbox: '<mailbox-address>'
  name: <token-name>
  owner: '<owner-or-ica-address>'
  symbol: <token-symbol>
  type: synthetic

The tokenFee on the synthetic chain lists ALL collateral chains in feeContracts (each may have a different owner if per-chain ICAs differ).

Standard format (single collateral + synthetic chains):

<collateral-chain>:
  decimals: <decimals>
  mailbox: '<mailbox-address>'
  name: <token-name>
  owner: '<owner-address>'
  symbol: <token-symbol>
  token: '<token-contract-address>'
  type: collateral

<synthetic-chain>:
  decimals: <decimals>
  mailbox: '<mailbox-address>'
  name: <token-name>
  owner: '<owner-address>'
  symbol: <token-symbol>
  type: synthetic

For collateralVault type chains (owner-yield ERC4626 — yield accrues to owner, not holders):

⚠️ Vault must be deployed before the warp route. The token field is the ERC4626 vault address, NOT the underlying asset. Use hyperlane-xyz/Aave-Vault to deploy the vault if one doesn't already exist. Real-world examples: WETH/incentiv vault 0xB1ea329f0B79d0b213957569594ca2a9dE637215 (waEthWETH, wraps WETH), USDT/incentiv vault 0x04DA4b99FFc82f0e44DEd14c3539A6fDaD08E2fE (wraps USDT).

Name and symbol: use the name and symbol of the underlying asset (from asset()), NOT the vault token. The vault is an implementation detail; users think of themselves as bridging the underlying token. Look up the underlying's name/symbol on-chain:

ASSET=$(cast call <vault-address> "asset()(address)" --rpc-url <RPC_URL>)
cast call $ASSET "symbol()(string)" --rpc-url <RPC_URL>
cast call $ASSET "name()(string)" --rpc-url <RPC_URL>

The warp route directory and warp route ID also use the underlying asset symbol (e.g. WETH/igra, not waEthWETH/igra).

<collateral-chain>:
  decimals: <decimals> # decimals of the underlying asset
  gas: 300000 # REQUIRED: vault withdrawal costs more than default 68k gas
  mailbox: '<mailbox-address>'
  name: <underlying-asset-name> # from asset().name(), NOT vault name
  owner: '<owner-address>'
  symbol: <underlying-symbol> # from asset().symbol(), NOT vault symbol
  token: '<erc4626-vault-address>' # vault address — NOT the underlying asset address
  type: collateralVault

<synthetic-chain>:
  decimals: <decimals>
  mailbox: '<mailbox-address>'
  name: <underlying-asset-name>
  owner: '<owner-address>'
  symbol: <underlying-symbol>
  type: synthetic # standard synthetic — NOT syntheticRebase

⚠️ gas: 300000 is required on the collateralVault chain. Delivering to a collateralVault triggers an ERC4626 vault withdrawal, which costs ~430k gas — far above the default 68k destinationGas. Without this override the relayer underpays the IGP and the delivery transaction will revert. 300k was validated empirically on the WETH/igra route (required: ~430k total, IGP overhead: ~160k, so destinationGas needed: ~270k → 300k gives headroom).

For collateralVaultRebase type chains (rebasing ERC4626 — yield auto-distributes to all bridged holders):

⚠️ Same ERC4626 check as collateralVault: run cast call <token> "asset()" — if it returns a non-zero address, use the token directly; if it reverts, a vault must be deployed first. Same name/symbol rule applies: use the underlying asset's name and symbol.

<collateral-chain>:
  decimals: <decimals>
  mailbox: '<mailbox-address>'
  name: <underlying-asset-name>
  owner: '<owner-address>'
  symbol: <underlying-symbol>
  token: '<erc4626-vault-address>'
  type: collateralVaultRebase

<synthetic-chain>:
  collateralChainName: <collateral-chain> # REQUIRED for syntheticRebase
  decimals: <decimals>
  mailbox: '<mailbox-address>'
  name: <underlying-asset-name>
  owner: '<owner-address>'
  symbol: <underlying-symbol>
  type: syntheticRebase # ALL destinations must be syntheticRebase when collateralVaultRebase is used

For native type chains (chain's native gas token is being bridged — no token, name, or symbol field):

<chain>:
  decimals: <decimals>
  mailbox: '<mailbox-address>'
  owner: '<owner-address>'
  type: native

If a warp fee is specified, fee placement depends on route type:

• Standard routes (collateral/native → synthetic): tokenFee on the synthetic chain only. feeContracts lists all collateral/native chains. Fee is charged when bridging FROM synthetic TO collateral/native.
• All-native routes (every chain is native): tokenFee on every chain, each listing all other chains as feeContracts.
• Multi-collateral with rebalancer: tokenFee on the synthetic chain listing all collateral chains (user-facing fee for bridging out of synthetic). Rebalancer-internal fees between collateral chains are NOT part of initial deploy — added later if needed.

<synthetic-chain>:
  ...
  tokenFee:
    feeContracts:
      <collateral-or-native-chain>:
        bps: <fee-in-bps>
        owner: "<fee-owner-address>"
        type: LinearFee
    owner: "<fee-owner-address>"
    type: RoutingFee
  type: synthetic

The fee-owner-address defaults to the chain's owner unless separately specified.

Sealevel chain rules (solanamainnet, eclipsemainnet, etc.): For any Sealevel chain in the route, add extra fields depending on token type:

All Sealevel chains (any type):

• hook: the IGP address looked up in Step 3 (from program-ids.json, NOT addresses.yaml)
• gas: 300000: sending to Solana costs more than the default 68k gas

Sealevel synthetic chains only (additional required fields):

• decimals: Solana SPL tokens are capped at 9 decimals. If the collateral token has more than 9 decimals (e.g. 18 on EVM), set decimals: 9 on the Sealevel synthetic and add scale: 1000000000 (i.e. 10^(collateral_decimals - 9)). For 6-decimal tokens (e.g. USDC), use decimals: 6 with no scale needed.

• metadataUri: a URL that will be stored in the Token 2022 on-chain metadata extension. This is never fetched at deploy time — any valid URL works, including a placeholder. The URI length affects rent (longer = marginally more SOL needed). Use the registry raw URL pattern so it resolves correctly after the registry PR is merged:

  https://raw.githubusercontent.com/hyperlane-xyz/hyperlane-registry/main/deployments/warp_routes/<TOKEN>/metadata.json
  

  Also create a metadata.json file next to the deploy.yaml in the registry:

  {
    "name": "<TOKEN_NAME>",
    "symbol": "<TOKEN_SYMBOL>",
    "image": "https://raw.githubusercontent.com/hyperlane-xyz/hyperlane-registry/main/deployments/warp_routes/<TOKEN>/logo.svg"
  }
  

  This JSON is the Metaplex-compatible metadata that Solana wallets (Phantom, etc.) use to display the token. If an SVG logo is attached to the Linear ticket, reference it via the registry raw URL.

Example (collateral has 18 decimals → Solana synthetic uses 9 with scale):

solanamainnet:
  decimals: 9
  gas: 300000
  hook: '<igp-address-from-registry>'
  mailbox: '<mailbox-address>'
  metadataUri: 'https://raw.githubusercontent.com/hyperlane-xyz/hyperlane-registry/main/deployments/warp_routes/TOKEN/metadata.json'
  name: TOKEN
  owner: '<solana-owner-address>'
  scale: 1000000000
  symbol: TOKEN
  type: synthetic

Example (collateral has 6 decimals → Solana synthetic uses 6, no scale needed):

solanamainnet:
  decimals: 6
  gas: 300000
  hook: '<igp-address-from-registry>'
  mailbox: '<mailbox-address>'
  metadataUri: 'https://raw.githubusercontent.com/hyperlane-xyz/hyperlane-registry/main/deployments/warp_routes/TOKEN/metadata.json'
  name: TOKEN
  owner: '<solana-owner-address>'
  symbol: TOKEN
  type: synthetic

Rules:

• Alphabetical sort, both levels (top-level chain entries AND keys within each entry) per /registry-yaml-sort-policy — that skill carries the canonical deploy.yaml key order. Insert every field at its alphabetical position; CI / CodeRabbit blocks unsorted PRs.
• token field only present on collateral, collateralVault, and collateralVaultRebase types
• name and symbol omitted on native type; decimals IS included
• collateralChainName is REQUIRED on every syntheticRebase chain; omit on all other types
• tokenFee goes on the synthetic chain only (or all chains if all-native route)
• Do NOT include interchainSecurityModule, proxyAdmin, or remoteRouters — those are added post-deployment

---

Step 5: Determine Output Path

The deploy.yaml goes in the local registry at:

$REGISTRY_PATH/deployments/warp_routes/<TOKEN>/<route-suffix>-deploy.yaml

<route-suffix> precedence:

1. If the ticket gave an explicit warp route ID (Step 2, e.g. WBTC/staging), use its suffix verbatim → deployments/warp_routes/WBTC/staging-deploy.yaml. The route ID and the filename suffix are the same string, so an explicit ticket ID drives both — do NOT overwrite it with a chain list.
2. Otherwise, derive <chains-alphabetical> — every chain in the route, lowercase, joined with - in alphabetical order.

Where:

• <TOKEN> is the token symbol (uppercase)

Examples (matching current registry convention):

• base + arbitrum → arbitrum-base-deploy.yaml
• ethereum + coti → coti-ethereum-deploy.yaml
• arbitrum + base + blast + bsc → arbitrum-base-blast-bsc-deploy.yaml
• single chain (no other legs deployed yet) → <chain>-deploy.yaml

This matches existing multi-chain routes in the registry (e.g. arbitrum-base-blast-…). Naming the file after every chain — rather than just the "new" or synthetic chain — prevents collisions when more routes with the same token are added later (e.g. a future ETH/arbitrum-only route wouldn't conflict with this one).

Before writing, scan deployments/warp_routes/<TOKEN>/ for existing routes and check that the alphabetical-joined filename you're about to write doesn't already exist. If it does, show the user the existing file and ask if they want to overwrite.

---

Step 6: Write the File

Write the deploy.yaml to the registry path, then show the user the final content and full path.

Ask the user to review the deploy.yaml and confirm or describe any changes needed. End your message with this marker (this MUST be the very last thing in your message):

[CONFIRM: Proceed with deploy.yaml as written]

Do not proceed to Step 7 until the user confirms.

Note: [CONFIRM: ...] is a Haggis-specific harness primitive — Haggis renders it as an inline approve/reject button. In other coding-assistant contexts it is just text.

---

Step 7: Prepare Warp Deploy Command

7a: Determine Warp Route ID

The warp route ID is derived from the deploy.yaml output path:

$REGISTRY_PATH/deployments/warp_routes/<TOKEN>/<chains-alphabetical>-deploy.yaml
                                        └────────────────────────────────────┘
                                        Warp route ID = <TOKEN>/<chains-alphabetical>

Examples:

• deployments/warp_routes/ETH/arbitrum-base-deploy.yaml → warp route ID ETH/arbitrum-base
• deployments/warp_routes/USDC/eclipsemainnet-ethereum-solanamainnet-deploy.yaml → USDC/eclipsemainnet-ethereum-solanamainnet

The route ID always matches the filename suffix (without -deploy.yaml), so it follows the same Step 5 precedence: if the ticket gave an explicit route ID (e.g. WBTC/staging) the suffix is that ID; otherwise it is every chain in the route, lowercase, joined by - in alphabetical order. Never re-derive a chain-list ID over an explicit one the ticket provided.

Refer to this resolved value as <warp-route-id> in the commands below (Steps 7d and 8) — it is the explicit ticket ID when one was given, the derived chains-alphabetical ID otherwise. Do not hardcode <TOKEN>/<chains-alphabetical> in the deploy commands, or an explicit-ID deploy (e.g. WBTC/staging) would write/deploy under the wrong id.

Validate the resolved ID before it crosses a filesystem or shell boundary — it becomes a registry filename and a --warp-route-id argument, so a hostile value is an injection/traversal vector. Require exactly <TOKEN>/<suffix>: exactly one /; each component matches ^[A-Za-z0-9._-]+$ and is neither . nor ..; no additional /, whitespace, or shell metacharacters (; | & $ ` > < ( ) * ? \). The <TOKEN> component must equal the ticket's token symbol. Halt with a clear error on any mismatch (a ./../metacharacter-laden value could escape the token directory or alter the privileged deploy command). Then build the deploy.yaml path, resolve it non-strictly (realpath -m — canonicalizes even when the file doesn't exist yet), and assert it lives under $REGISTRY_PATH/deployments/warp_routes/<TOKEN>/ specifically (not merely under deployments/warp_routes/) before writing. Always pass the id as a single quoted argument (--warp-route-id "<warp-route-id>"), never unquoted.

7b: Identify Required Protocols

For each chain in the route, determine its VM protocol type:

Protocol	Example chains	Key flag
EVM (ethereum)	ethereum, arbitrum, base, optimism, polygon, avalanche, bsc	--key.ethereum
Sealevel	solana, eclipsemainnet	--key.sealevel
Cosmos	neutron, osmosis	--key.cosmos
Starknet	starknet	--key.starknet

If all chains are EVM, only one key is needed. If the route spans multiple VM types, a separate key flag is needed per protocol.

7c: Load Keys from the Key-Context Artifact

For each unique protocol in the route, read keys.<protocol>.name and keys.<protocol>.source from ~/.hyperlane/key-contexts/<ticket-id>.yaml. Do NOT ask the user for env var names inline — the artifact is the source of truth.

7d: Build and Show the Command (preview only — do NOT run yet)

Assemble the full deploy command and show it to the user as a preview for the [CONFIRM:] gate below. Do NOT execute the deploy in this step — Step 8 starts the HTTP registry first and then runs the deploy. Running the command here against the filesystem registry would skip the private-RPC injection, exposing the deploy to flaky public-RPC gas estimates (stale-gas underflow → mid-deploy out-of-gas on opstack chains in particular).

The command must be run from typescript/cli. Always include --yes to skip the interactive confirmation prompt. Include exactly one --key.<protocol> flag for each protocol actually present in the route (EVM, tron, sealevel, cosmos, starknet) and drop the rest — a Sealevel-only route needs no --key.ethereum, a route with a starknet chain needs --key.starknet, and a route with a tron chain needs --key.tron (the CLI keys tron separately from EVM — do not rely on the ethereum key for a tron chain). The preview (7d) and execution (8b) commands must use the same protocol set. For each included protocol, expand <KEY_<PROTOCOL>_VALUE> per the artifact's source field using the canonical key-value expansion legend in /warp-key-value-expansion.

pnpm --silent -C typescript/cli hyperlane warp deploy \
  --registry http://localhost:<port> \
  --warp-route-id <warp-route-id> \
  [--key.ethereum <KEY_ETHEREUM_VALUE>]   # only if EVM chains present
  [--key.tron <KEY_TRON_VALUE>]           # only if tron chains present (CLI keys tron separately)
  [--key.sealevel <KEY_SEALEVEL_VALUE>]   # only if sealevel chains present
  [--key.cosmos <KEY_COSMOS_VALUE>]       # only if cosmos chains present
  [--key.starknet <KEY_STARKNET_VALUE>]   # only if starknet chains present
  --yes

Where <warp-route-id> is the resolved route ID from Step 7a, <port> is the HTTP registry port (typically 3333), and <KEY_<PROTOCOL>_VALUE> is expanded per the artifact's source for that protocol (e.g. "$(gcloud secrets versions access latest --secret=<name>)" for gcp-secret, "$<name>" for env-var).

Show the user the exact command with the resolved secret/env-var NAMES substituted (from the artifact), never private-key values. Also show the corresponding derived address per protocol so the human can spot a wrong-key foot-gun at the gate. End your message with this marker (this MUST be the very last thing in your message):

[CONFIRM: Run warp deploy for <warp-route-id>]

---

Step 8: Run Warp Deploy

8a: Start the HTTP Registry FIRST

The HTTP registry MUST be running before the deploy command. Starting it later or skipping it means the deploy falls back to public-RPC gas estimates and is exposed to OOG / nonce errors on chains with flaky public free-tier RPCs (notably base, optimism, drpc-routed chains).

Start it per /start-http-registry with --writeMode (the deploy persists the route config back through the server). Note the port (typically 3333) and the background task/shell ID — you will need both to stop the server after the skill completes.

8b: Run the Deploy Command

Tell the user upfront:

Starting warp deploy for <warp-route-id>. This deploys contracts on each chain sequentially and typically takes 5–15 minutes. Chains: <list all chains> You'll see the full output when it completes.

Then run the deploy command from typescript/cli, with the port substituted from Step 8a. Always include --yes. Expand <KEY_<PROTOCOL>_VALUE> per the artifact's source field (see the canonical key-value expansion legend in /warp-key-value-expansion):

pnpm --silent -C typescript/cli hyperlane warp deploy \
  --registry http://localhost:<port> \
  --warp-route-id <warp-route-id> \
  [--key.ethereum <KEY_ETHEREUM_VALUE>]   # only if EVM chains present
  [--key.tron <KEY_TRON_VALUE>]           # only if tron chains present (CLI keys tron separately)
  [--key.sealevel <KEY_SEALEVEL_VALUE>]   # only if sealevel chains present
  [--key.cosmos <KEY_COSMOS_VALUE>]       # only if cosmos chains present
  [--key.starknet <KEY_STARKNET_VALUE>]   # only if starknet chains present
  --yes

On success: the CLI writes a <chains-alphabetical>-config.yaml file next to the deploy.yaml in the registry. Show the user the full deploy output so they can see which contracts were deployed and their addresses.

On failure: show the error output and stop the HTTP registry (Step 8a), then do not proceed to Step 9. Common issues:

• Insufficient gas → run /warp-deploy-fund-deployer first
• RPC errors → check the chain's RPC URL in the registry
• Key not set → confirm the env variable is exported in the shell

8c: Multi-RPC failure modes (and the mandatory cleanup gate)

Two deploy failures come from read-after-write lag across a chain's load-balanced private RPCs, NOT from a real problem — recognize them so you don't chase a phantom or re-fund unnecessarily:

• Stale-gas OOG on the proxy initialize. A fresh impl deploys, then initialize is gas-estimated against an RPC replica that hasn't indexed the new contract yet → it returns an EOA-sized (~25k) estimate and the tx runs out of gas. Signature: OOG on initialize right after a successful impl deploy, on opstack / multi-RPC chains (base, optimism). Fix: pin the affected chain to a single RPC in the local registry metadata for the duration of the deploy.
• Confirmation-timeout on a tx that actually landed. Timeout (Xms) waiting for N block confirmations for tx 0x… where the tx already succeeded on-chain (check the receipt: status: 1). Root cause: the CLI's confirmation budget is confirmations × estimateBlockTime × 2, as low as ~6s on chains whose registry estimateBlockTime is 3s (bsc, tron). Fix: raise estimateBlockTime in the local registry metadata for those chains (e.g. eth 13→45, bsc/tron 3→30). This survives the GCP RPC-override merge, unlike re-pinning RPCs — do NOT re-pin RPCs for this one.

Prevent, don't just react. A mid-deploy abort burns gas and forces a fresh re-run, so apply these cushions up front rather than waiting for the signature: before deploying, pin a single premium RPC per chain on opstack / multi-RPC chains (base, optimism), and raise estimateBlockTime on short-block / confirmation-timeout-prone chains (ethereum, bsc, tron) so the confirmations × estimateBlockTime × 2 budget isn't razor-thin. These are the same edits described above and fall under the same cleanup gate.

Cleanup gate (mandatory). Any single-RPC pin or estimateBlockTime bump above is a LOCAL registry edit. After a green deploy, restore the original values and confirm git -C $HYPERLANE_REGISTRY diff is clean before moving on — a left-behind override silently drifts the local registry from canonical for every later run.

Orphaned contracts on a failed deploy. The <chains>-config.yaml is written only on FULL success, so a mid-deploy failure leaves the already-deployed contracts orphaned on chain (and the deployer nonce advanced). A clean re-run picks fresh addresses — do NOT try to salvage partial addresses; fix the cause, re-run, and note the burnt gas.

---

Step 9: Warp Send Test

Run the send test now, while the deployer still owns the contracts — before transferring ownership in Step 10 — via /warp-deploy-send-test. Reuse the deployer key from the key-context artifact (loaded in Step 7c) and the HTTP registry already running from the deploy.

That skill owns the test shape (full collateral mesh vs. round trip), the enrollment-coverage rule (every chain must originate at least one send or its outbound enrollment goes unverified), per-destination gas budgeting + fundkey top-ups, prod-relayer delivery, fee accrual + return-leg sizing, and per-leg reporting (message ID + explorer link). This send test is a functional smoke test, not the config-vs-target validation — that runs in /warp-deploy-update-owners Step 10e (/warp-verify-onchain-config Mode A).

After the send test (or on any failure), stop the HTTP registry per /stop-http-registry — always, even if sends failed.

---

Next Steps

Once Step 9 is complete, run /warp-deploy-update-owners to transfer ownership, add the CoinGecko ID, and open the registry PR. The post-change on-chain config verification for this deploy runs there — the comprehensive warp check gate in Step 10e, which is the /warp-verify-onchain-config contract's Mode A (everything in the deploy chain is deployer-signed, so the check is live). This skill's send test is a functional smoke test, not the config-vs-target validation.

---

Notes

• The registry path is $(pwd)/../hyperlane-registry when run from the monorepo root. The hyperlane-registry repo is expected to be cloned at the same level as hyperlane-monorepo.
• For USDC, use the token addresses and CCTP bridge addresses from the reference tables above — no need to search the registry
• If the ticket has links to token contracts on block explorers, use those addresses
• All owner fields always use the deployer address — never use real Safe/ICA addresses in deploy.yaml. Real ownership is transferred via /warp-deploy-update-owners after testing.
• Do NOT search the registry for example deploys to copy from — the reference tables above have the canonical values