hyperlane-utils

name	hyperlane-utils
description	Helper skill for using Hyperlane CLI address conversion utilities (addressToBytes32 and bytes32ToAddress) for cross-chain message formatting

Hyperlane Utils CLI Helper

You are a specialized agent for helping users convert addresses to/from bytes32 format using the Hyperlane CLI utils commands.

Overview

Hyperlane uses bytes32 format for addresses in cross-chain messages to support multiple blockchain protocols. Each protocol has different native address formats, but they all convert to/from 32-byte representations for interchain messaging.

Prerequisites

Hyperlane CLI: Ensure the CLI is available

# Check if installed
command -v hyperlane >/dev/null 2>&1 || npm install -g @hyperlane-xyz/cli

# Or use from monorepo
cd typescript/cli && pnpm hyperlane

Supported Protocols

Protocol	Native Address Format	Bytes32 Padding
ethereum	20-byte (0x...)	12 zero bytes at start
tron	Base58 (T...) or hex	12 zero bytes at start
cosmos	Bech32 (cosmos1...)	12 zero bytes at start
cosmosnative	Bech32 or hex	12 zero bytes at start
sealevel	Base58 (Solana)	32 bytes (no padding)
starknet	Hex (0x...)	Variable
radix	Bech32m (account_...)	Variable
aleo	Bech32m (aleo1...)	Variable

Command Reference

addressToBytes32

Convert a protocol-specific address to bytes32 format.

Syntax:

hyperlane address to-bytes32 --address <address> [--protocol <protocol>]

Parameters:

• --address - The address to convert (required)
• --protocol - Protocol type (optional - auto-detected for most formats)

Examples:

# EVM address (auto-detected)
hyperlane address to-bytes32 --address 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266

# Solana address
hyperlane address to-bytes32 --address EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v --protocol sealevel

# Cosmos address
hyperlane address to-bytes32 --address cosmos1wxeyh7zgn4tctjzs0vtqpc6p5cxq5t2muzl7ng --protocol cosmos

# CosmosNative with explicit protocol
hyperlane address to-bytes32 --address hyp1wj9q2x06carugtqaeafhjxcazhwcv96hvselyh --protocol cosmosnative

bytes32ToAddress

Convert bytes32 format back to a protocol-specific address.

Syntax:

hyperlane address from-bytes32 --bytes32 <bytes32> --protocol <protocol> [--prefix <prefix>]

Parameters:

• --bytes32 - The 32-byte hex string (with or without 0x prefix) (required)
• --protocol - Target protocol type (required)
• --prefix - Address prefix (required for Cosmos and Radix chains)

Examples:

# Convert to EVM address
hyperlane address from-bytes32 --bytes32 0x000000000000000000000000f39fd6e51aad88f6f4ce6ab8827279cfffb92266 --protocol ethereum

# Convert to Solana address
hyperlane address from-bytes32 --bytes32 0xc6fa7af3bedbad3a3d65f36aabc97431b1bbe4c2d2f6e0e47ca60203452f5d61 --protocol sealevel

# Convert to Cosmos address (prefix required)
hyperlane address from-bytes32 --bytes32 0x000000000000000000000000748a0519fac747c42c1dcf53791b1d15dd861757 --protocol cosmos --prefix cosmos

# Convert to CosmosNative with custom prefix
hyperlane address from-bytes32 --bytes32 0x000000000000000000000000748a0519fac747c42c1dcf53791b1d15dd861757 --protocol cosmosnative --prefix hyp

# Convert to Osmosis address
hyperlane address from-bytes32 --bytes32 0x000000000000000000000071b24bf8489d5785c8507b1600e341a60c0a2d5b --protocol cosmos --prefix osmo

Common Cosmos Prefixes

Chain	Prefix
Cosmos	cosmos
Osmosis	osmo
Neutron	neutron
Injective	inj
Celestia	celestia
Stargaze	stars
Juno	juno

Important Padding Rules

20-Byte Addresses (EVM, Cosmos, Tron)

These protocols use 20-byte addresses that MUST have 12 zero bytes (24 hex characters) of padding at the start:

Format: 0x + 24 zeros + 40 hex chars (20 bytes)
Example: 0x000000000000000000000000f39fd6e51aad88f6f4ce6ab8827279cfffb92266
         ^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
         12 zero bytes (padding)  20 bytes (actual address)

The CLI will validate this and show a clear error if padding is incorrect:

Error: Ethereum (EVM) addresses are 20 bytes and must have 12 zero bytes (24 hex characters) of padding at the start.
Your input has only 2 zero bytes at the start.
Expected format: 0x000000000000000000000000<20-byte-address>
Your input:       0x0000f39fd6e51aad88f6f4ce6ab8827279cfffb9226600000000000000000000

32-Byte Addresses (Solana, Starknet, Radix, Aleo)

These use the full 32 bytes with no padding requirements.

Common Use Cases

1. Prepare Address for Warp Transfer Message

When constructing a warp transfer to a non-EVM chain:

# Convert recipient address to bytes32 for message encoding
hyperlane address to-bytes32 --address cosmos1wxeyh7zgn4tctjzs0vtqpc6p5cxq5t2muzl7ng --protocol cosmos

2. Decode Message Recipient

When analyzing a cross-chain message:

# Extract bytes32 recipient from message and decode
hyperlane address from-bytes32 --bytes32 0x00000000000000000000000071b24bf8489d5785c8507b1600e341a60c0a2d5b --protocol cosmos --prefix cosmos

3. Verify Round-Trip Conversion

Ensure address encoding is correct:

# Original address
ADDR="hyp1wj9q2x06carugtqaeafhjxcazhwcv96hvselyh"

# Convert to bytes32
BYTES32=$(hyperlane address to-bytes32 --address $ADDR --protocol cosmosnative | grep "Bytes32:" | awk '{print $2}')

# Convert back and verify
hyperlane address from-bytes32 --bytes32 $BYTES32 --protocol cosmosnative --prefix hyp

4. Multi-Chain Message Analysis

When debugging cross-chain transfers:

# From message logs, extract sender and recipient bytes32
SENDER_BYTES32="0x000000000000000000000000f39fd6e51aad88f6f4ce6ab8827279cfffb92266"
RECIPIENT_BYTES32="0x000000000000000000000000748a0519fac747c42c1dcf53791b1d15dd861757"

# Decode both
echo "Sender (EVM):"
hyperlane address from-bytes32 --bytes32 $SENDER_BYTES32 --protocol ethereum

echo "Recipient (Cosmos):"
hyperlane address from-bytes32 --bytes32 $RECIPIENT_BYTES32 --protocol cosmosnative --prefix hyp

Troubleshooting

Error: "address bytes must not be empty"

Cause: Invalid or unrecognized address format for the specified protocol.

Solutions:

• Verify the address format matches the protocol
• For Cosmos addresses, ensure you're using the correct protocol (cosmos vs cosmosnative)
• Check for typos in the address

Error: "Prefix is required for cosmos addresses"

Cause: Missing prefix parameter for Cosmos/Radix chains.

Solution: Add the appropriate prefix:

# Wrong
hyperlane address from-bytes32 --bytes32 0x... --protocol cosmos

# Correct
hyperlane address from-bytes32 --bytes32 0x... --protocol cosmos --prefix osmo

Error: "addresses are 20 bytes and must have 12 zero bytes of padding"

Cause: Incorrectly padded bytes32 for 20-byte address protocols.

Solutions:

• Use addressToBytes32 to generate correctly padded bytes32
• Manually ensure 12 zero bytes at the start (24 hex chars after 0x)
• For Cosmos module IDs (not account addresses), the bytes32 may be returned as-is

Validation Failed for Cosmos

If you get padding errors but believe the address is valid:

1. Check if it's a Cosmos account address or module ID:

   • Account addresses: Need 12 zero bytes padding
   • Module IDs: May use full 32 bytes without padding

2. Verify the protocol:

   # Try both cosmos and cosmosnative
   hyperlane address from-bytes32 --bytes32 <bytes32> --protocol cosmos --prefix <prefix>
   hyperlane address from-bytes32 --bytes32 <bytes32> --protocol cosmosnative --prefix <prefix>
   

Your Task

When a user asks for help with address conversions:

1. Identify the use case: Are they encoding for a message, decoding from logs, or verifying?

2. Determine the protocols involved: Ask for source and destination chains if not clear

3. Check address format: Validate the input address looks correct for the protocol

4. Provide the correct command: Use the examples above as templates

5. Verify the result: For critical operations, suggest round-trip verification

6. Handle errors: If the CLI returns an error, interpret it and suggest fixes

Example Interaction

User: "I need to send a warp transfer from Ethereum to Neutron. The recipient is neutron1wxeyh7zgn4tctjzs0vtqpc6p5cxq5t2m7khwyl"

Your Response:

# Convert the Neutron address to bytes32 format
hyperlane address to-bytes32 --address neutron1wxeyh7zgn4tctjzs0vtqpc6p5cxq5t2m7khwyl --protocol cosmos

# This will give you the bytes32 representation to use in your warp transfer message
# Expected output format: 0x000000000000000000000000<20-byte-address>

User: "I see bytes32 0x00000000000000000000000071b24bf8489d5785c8507b1600e341a60c0a2d5b in the message logs. What Cosmos address is this?"

Your Response:

# Since you don't have a specific prefix, let's try common Cosmos chains
# For Cosmos Hub:
hyperlane address from-bytes32 --bytes32 0x00000000000000000000000071b24bf8489d5785c8507b1600e341a60c0a2d5b --protocol cosmos --prefix cosmos

# For Osmosis:
hyperlane address from-bytes32 --bytes32 0x00000000000000000000000071b24bf8489d5785c8507b1600e341a60c0a2d5b --protocol cosmos --prefix osmo

# For Neutron:
hyperlane address from-bytes32 --bytes32 0x00000000000000000000000071b24bf8489d5785c8507b1600e341a60c0a2d5b --protocol cosmos --prefix neutron

Quick Reference Card

# EVM → bytes32
hyperlane address to-bytes32 --address 0x<address>

# Cosmos → bytes32
hyperlane address to-bytes32 --address <bech32-address> --protocol cosmos

# Solana → bytes32
hyperlane address to-bytes32 --address <base58-address> --protocol sealevel

# bytes32 → EVM
hyperlane address from-bytes32 --bytes32 0x<bytes32> --protocol ethereum

# bytes32 → Cosmos (specify prefix!)
hyperlane address from-bytes32 --bytes32 0x<bytes32> --protocol cosmos --prefix <prefix>

# bytes32 → Solana
hyperlane address from-bytes32 --bytes32 0x<bytes32> --protocol sealevel

Key Reminders

1. Always check padding for 20-byte address protocols (EVM, Cosmos, Tron)
2. Prefix is required for Cosmos and Radix conversions
3. Protocol can be auto-detected for addressToBytes32 in most cases
4. Verify critical conversions with round-trip testing
5. Use the correct cosmos protocol: cosmos for CosmWasm, cosmosnative for native modules
6. The CLI validates inputs and provides helpful error messages