Build Your First Cross-Chain App with Hyperlane

This tutorial will guide you through creating a simple cross-chain messaging app using Hyperlane, allowing users to send messages from one blockchain to another.

What You’ll Learn

✅ How to deploy a cross-chain smart contract
✅ How to send and receive messages across different chains
✅ How to integrate Hyperlane’s interchain messaging into a dApp

Setting Up Your Development Environment

Prerequisites

🔹 Install Node.js (v18+)
🔹 Install Hardhat for smart contract development
🔹 Install MetaMask (for interacting with deployed contracts)
🔹 Get some testnet ETH (for gas fees)

Install Dependencies

Run the following command in your terminal:

mkdir hyperlane-crosschain && cd hyperlane-crosschain
npm init -y
npm install --save-dev hardhat dotenv ethers @openzeppelin/contracts

Writing the Cross-Chain Smart Contract

Create a Solidity contract that:
✅ Sends a message from one chain to another
✅ Receives the message on the target chain

📜 contracts/InterchainMessenger.sol

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

import "@hyperlane/contracts/interfaces/IMailbox.sol";

contract InterchainMessenger {
    IMailbox public mailbox;
    address public lastSender;
    string public lastMessage;

event MessageSent(uint32 destination, address sender, string message);
    event MessageReceived(address sender, string message);

    constructor(address _mailbox) {
        mailbox = IMailbox(_mailbox);
    }

    function sendMessage(uint32 destinationDomain, address recipient, string calldata message) external {
        mailbox.dispatch(destinationDomain, recipient, bytes(message));
        emit MessageSent(destinationDomain, msg.sender, message);
    }

    function handle(uint32, bytes32 sender, bytes calldata message) external {
        require(msg.sender == address(mailbox), "Unauthorized sender");
        lastSender = address(uint160(uint256(sender)));
        lastMessage = string(message);
        emit MessageReceived(lastSender, lastMessage);
    }
}

Deploying the Contract on Two Chains

Modify hardhat.config.js:


require("@nomicfoundation/hardhat-toolbox");
require("dotenv").config();

module.exports = {
  networks: {
    ethereum: {
      url: process.env.ETHEREUM_RPC_URL,
      accounts: [process.env.PRIVATE_KEY],
    },
    optimism: {
      url: process.env.OPTIMISM_RPC_URL,
      accounts: [process.env.PRIVATE_KEY],
    },
  },
  solidity: "0.8.20",
};

Sending a Cross-Chain Message

You can call the sendMessage function from a front-end dApp or script:

const ethers = require("ethers");
const contractABI = require("./artifacts/InterchainMessenger.json");

async function sendMessage() {
  const provider = new ethers.providers.JsonRpcProvider(process.env.ETHEREUM_RPC_URL);
  const wallet = new ethers.Wallet(process.env.PRIVATE_KEY, provider);
  const contract = new ethers.Contract(process.env.CONTRACT_ADDRESS, contractABI, wallet);

  const tx = await contract.sendMessage(420, process.env.RECIPIENT_CONTRACT, "Hello from Ethereum!");
  await tx.wait();
  console.log("Message Sent!");
}

sendMessage();

Frontend Integration (React + Ethers.js)

Build a simple frontend to let users send messages between chains.

React Component (MessageSender.js)

import { useState } from "react";
import { ethers } from "ethers";
import contractABI from "./InterchainMessenger.json";

function MessageSender() {
  const [message, setMessage] = useState("");
  
  async function sendMessage() {
    const provider = new ethers.providers.Web3Provider(window.ethereum);
    const signer = provider.getSigner();
    const contract = new ethers.Contract(process.env.CONTRACT_ADDRESS, contractABI, signer);
    
    const tx = await contract.sendMessage(420, process.env.RECIPIENT_CONTRACT, message);
    await tx.wait();
    alert("Message Sent!");
  }

button

return (
    <div>
      <input type="text" onChange={(e) => setMessage(e.target.value)} placeholder="Enter message" />
      <button onClick={sendMessage}>Send Message</button>
    </div>
  );
}

export default MessageSender;

Testing & Deployment

Test on Local Fork

Use Hardhat to simulate cross-chain calls:

npx hardhat node

Deploy Frontend

Host on Vercel or Netlify:

npm run build
npx vercel deploy

Final Thoughts

🚀 Congrats! You just built a Hyperlane-powered cross-chain messaging app!

What’s Next?

🔹 Expand it to support multiple chains
🔹 Add token transfers using Hyperlane Warp Messaging
🔹 Implement gas fee optimization

📚 Resources:
Hyperlane Docs:

What’s Next?

🔹 Expand it to support multiple chains
🔹 Add token transfers using Hyperlane Warp Messaging
🔹 Implement gas fee optimization

📚 Resources:
Hyperlane Docs: https://docs.hyperlane.xyz

Understanding Hyperlane & Interchain Messaging

What is Hyperlane?

Hyperlane is a modular interoperability protocol that lets you send messages and assets between blockchains.

🔹 Why Use Hyperlane?
	•	Permissionless: Deploy on any EVM-compatible chain.
	•	Modular Security: Customize security settings based on your needs.
	•	Cross-Chain Communication: Easily send messages, tokens, and data between chains.

How It Works

Hyperlane operates using mailboxes:
📩 Sender Contract → Hyperlane Mailbox → 🌍 Destination Chain → 📬 Receiver Contract