How to Update Mailbox Default ISM

Using the Hyperlane CLI

When first deploying with the CLI, a new mailbox uses a Trusted Relayer ISM out of the box so you don't need to run a relayer or validator.

In order to go to production, you'll need to remove this ISM with 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.

info

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.

This particular config has a trustedRelayerIsm. This means contracts (e.g., warp routes) that fallback to the mailbox's defaultIsm will give permission to relayer address to execute arbitrary messages. This may be undesirable in cases outside of the self-relaying feature. Follow these steps using the CLI to update the existing default Ism to a different configuration.

Step 1: Update Configuration

Alternatively, you can update the relayer address to something else (e.g., "burn" it by setting it to an inaccessible address).

core-config.yaml

defaultHook:
  address: "0xC2E88eC0aB5FDB9756CD3EFEE40D24120fFa6E57"
  type: merkleTreeHook
defaultIsm:
  address: "0xF37395A79f56268FD0040E1f5711e9Af974a545A"
- relayer: "0xa5558cA30cd9952Ab0e2349C274a3736698bD60e"
+ relayer: "0x0000000000000000000000000000000000000001"
  type: trustedRelayerIsm
owner: "0xa5558cA30cd9952Ab0e2349C274a3736698bD60e"
requiredHook:
  address: "0x4f54055C94DCbC2b502146D46909A2cC7461c5D8"
  beneficiary: "0xa5558cA30cd9952Ab0e2349C274a3736698bD60e"
  maxProtocolFee: "100000000000000000"
  owner: "0xa5558cA30cd9952Ab0e2349C274a3736698bD60e"
  protocolFee: "0"
  type: protocolFee

Alternatively, you can update the defaultIsm config to a different ISM config. As shown, it is updated to a messageIdMultisigIsm.

warning

Configuring ISMs is an advanced feature that require knowledge of different ISM types and how they work together topologically.

core-config.yaml

defaultHook:
  address: "0xC2E88eC0aB5FDB9756CD3EFEE40D24120fFa6E57"
  type: merkleTreeHook
defaultIsm:
- address: "0xF37395A79f56268FD0040E1f5711e9Af974a545A"
- relayer: "0xa5558cA30cd9952Ab0e2349C274a3736698bD60e"
- type: trustedRelayerIsm
+ threshold: 1
+ type: messageIdMultisigIsm
+ validators:
+  - "0xa5558cA30cd9952Ab0e2349C274a3736698bD60e"
owner: "0xa5558cA30cd9952Ab0e2349C274a3736698bD60e"
requiredHook:
  address: "0x4f54055C94DCbC2b502146D46909A2cC7461c5D8"
  beneficiary: "0xa5558cA30cd9952Ab0e2349C274a3736698bD60e"
  maxProtocolFee: "100000000000000000"
  owner: "0xa5558cA30cd9952Ab0e2349C274a3736698bD60e"
  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 default ISM:

defaultHook:
  address: "0x67F8c06Fd2915728E9D21451E33FbDFbCcd63c44"
  type: "merkleTreeHook"
defaultIsm:
  address: "0xac7D6df90fa937ADEfE7aD2d4905f0AEa170c467"
  relayer: "0x0000000000000000000000000000000000000001"
  type: "trustedRelayerIsm"
owner: "0xa5558cA30cd9952Ab0e2349C274a3736698bD60e"
requiredHook:
  address: "0x1Cd94b4D9B5f0e3474a6bDB8b9503Ca84F53e548"
  beneficiary: "0xa5558cA30cd9952Ab0e2349C274a3736698bD60e"
  maxProtocolFee: "100000000000000000"
  owner: "0xa5558cA30cd9952Ab0e2349C274a3736698bD60e"
  protocolFee: "0"
  type: "protocolFee"

By completing these steps, you've successfully updated the mailbox default ISM and enhanced the security of your mailbox. Your mailbox is now ready for production use.