Skip to main content

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.

This guide explains how to change the owner of your Hyperlane Mailbox using the Hyperlane CLI. Transferring ownership is necessary when you want to give control to a different address, such as for security reasons or when making changes to who manages the Mailbox. As the new owner, you will have full control over the Mailbox settings, including managing hooks, ISM configurations, and permissions for message handling. We’ll guide you through updating the owner address, applying the change, and confirming everything is set correctly.

​
Using the Hyperlane CLI

One of the quickest way to transfer a mailbox ownership is by using the Hyperlane CLI.

​
Prerequisites

  • The core config generated by hyperlane core init.
    • This config is used to deploy core contracts, including the mailbox. By default, it takes the filepath of CURRENT_DIR/configs/core-config.yaml.
  • The chain that the mailbox was deployed to.
  • Access to the private key that currently owns the mailbox.
If you followed the How to Connect Your Chain with Hyperlane guide, you may have deployed a mailbox with the owner set to the single private key. In production, it is advisable to use a multisig.
To confirm using the Hyperlane CLI, execute the following with --chain set to the name of your chain that the mailbox is deployed on: 
hyperlane core read --chain <yourChain>
After running core read, you should see a similar config with owner set to private key’s address: 
defaultHook:
  address: "0xC2E88eC0aB5FDB9756CD3EFEE40D24120fFa6E57"
  type: "merkleTreeHook"
defaultIsm:
  address: "0xF37395A79f56268FD0040E1f5711e9Af974a545A"
  relayer: "0xa5558cA30cd9952Ab0e2349C274a3736698bD60e"
  type: "trustedRelayerIsm"
owner: "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266"
requiredHook:
  address: "0x390d29a822C21F57B163F1173cD43382bd643401"
  beneficiary: "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266"
  maxProtocolFee: "100000000000000000"
  owner: "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266"
  protocolFee: "0"
  type: "protocolFee"
The output is saved to CURRENT_DIR/configs/core-config.yaml. Follow these steps using the CLI to transfer the existing ownership to another address.

​
Step 1: Update Config

Update owner address in the core-config.yaml
core-config.yaml
defaultHook:
  address: "0xE71AC7A1ccB822423576EfFdb0B74564C49BEcBA"
  type: merkleTreeHook
defaultIsm:
  address: "0x89842f40928f81FC4415b39bfBFC3205eB6161cB"
  relayer: "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266"
  type: trustedRelayerIsm
- owner: "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266"
+ owner: "0x70997970C51812dc3A010C7d01b50e0d17dc79C8"
requiredHook:
  address: "0x390d29a822C21F57B163F1173cD43382bd643401"
  beneficiary: "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266"
  maxProtocolFee: "100000000000000000"
  owner: "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266"
  protocolFee: "0"
  type: protocolFee

​
Step 2: Apply

Using the CLI, execute: 
hyperlane core apply --chain <yourChain>
You should see a batch of transactions executed on chain, and a final message indicating that the mailbox has been updated.

​
Step 3: Confirm

To confirm using the Hyperlane CLI, execute the following: 
hyperlane core read --chain <yourChain>
After running core read, you should see a similar config with the now updated owner: 
defaultHook:
  address: "0x67F8c06Fd2915728E9D21451E33FbDFbCcd63c44"
  type: "merkleTreeHook"
defaultIsm:
  address: "0xac7D6df90fa937ADEfE7aD2d4905f0AEa170c467"
  relayer: "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266"
  type: "trustedRelayerIsm"
owner: "0x70997970C51812dc3A010C7d01b50e0d17dc79C8"
requiredHook:
  address: "0x1Cd94b4D9B5f0e3474a6bDB8b9503Ca84F53e548"
  beneficiary: "0xa5558cA30cd9952Ab0e2349C274a3736698bD60e"
  maxProtocolFee: "100000000000000000"
  owner: "0xa5558cA30cd9952Ab0e2349C274a3736698bD60e"
  protocolFee: "0"
  type: "protocolFee"
By completing these steps, you have successfully transferred and verified ownership of your mailbox to a new address.