Introduction

In this guide, we are going to integrate Wormhole into our existing solidity smart contracts. While numerous solutions exist for sending cross-chain messages, Wormhole stands out as one of the most streamlined options for developers looking to expand their smart contracts across multiple blockchains. In my experience, Wormhole offers a user-friendly approach that simplifies the process of going cross-chain for smart contract developers of all skill levels.

What is Wormhole?

Wormhole is a cross-chain message transfer protocol that enables seamless communication between different blockchains. Traditionally, blockchains operate as isolated systems, making it challenging to directly transfer tokens or send messages from one chain to another. This is where Wormhole steps in, providing a trustless solution for transferring messages across various blockchain networks. By bridging these isolated systems, Wormhole facilitates interoperability and opens up new possibilities for decentralized applications and cross-chain functionality.

Step-by-step guide:

Environment setup
Writing initial contracts
Integrating wormhole
sending cross-chain messages

Environment Setup

Pre-requisites:

Setup Node.js v18+ (recommended via nvm with nvm install 18)
Setup hardhat v2+ (recommended via npm with npx hardhat init)

Setup your project

Let's set up a hardhat project to compile and deploy our Solidity Contract. Create a new hardhat project with the following command:

npx hardhat init

After successful compilation, we need to add networks to our hardhat.config.js file.

Edit the hardhat.config.js file with the following code:

require("@nomicfoundation/hardhat-toolbox");

const PRIVATE_KEY = "YOUR PRIVATE KEY";

/** @type import('hardhat/config').HardhatUserConfig */
module.exports = {
  solidity: "0.8.24",
  networks: {
    opSepolia: {
      url: `YOUR OPTIMISM SEPOLIA RPC URL`,
      accounts: [PRIVATE_KEY],
    },
    baseSepolia: {
      url: `YOUR BASE SEPOLIA RPC URL`,
      accounts: [PRIVATE_KEY],
    },
  },
};

Also, deploy.js file with the following code to set up deployment.

const hre = require("hardhat");

async function main() {
  const [deployer] = await hre.ethers.getSigners();

  console.log("Deploying contracts with the account:", deployer.address);

  const contract = await hre.ethers.deployContract("YourContract");

  console.log("Contract address:", await contract.getAddress());
}

main().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});

Finally, to deploy the contract, execute the following command in the terminal:

npx hardhat run scripts/deploy.js --network opSepolia

Writing initial contracts

Let's examine an example contract that demonstrates how we can send messages on a single blockchain.

contract HelloWormhole {
    event MessageSent(uint256 messageId, string message );
    event MessageReceived(address sourceAddress, uint256 messageId, string message);

    function sendMessage(
        address targetAddress,
        uint256 messageId,
        string memory message) public {
            HelloWormhole(targetAddress).receiveMessage(address(this), messageId, message);
            emit MessageSent(messageId, message);
        }

    function receiveMessage(
        address sourceAddress,
        uint256 messageId, 
        string memory message) public {
            emit MessageReceived(sourceAddress, messageId, message);
        }
}

This contract demonstrates a simple message-sending mechanism between identical HelloWormhole contracts on a single network. However, it fails to address a crucial aspect of modern blockchain ecosystems: the existence of multiple, diverse blockchains. In reality, users often need to send cross-chain messages from one blockchain to another. While we acknowledge that blockchains are inherently isolated systems, the question arises: how can we make cross-chain communication possible? That's where Wormhole helps us with.

Integrating Wormhole

Let's integrate Wormhole into our existing contracts.

Wormhole ChainIds

In the Wormhole ecosystem, distinct chain identifiers are used to specify the source and destination chains for cross-chain communications. It's important to note that the chainId parameters used in the following contracts are specific to Wormhole's network identification system, rather than the standard Ethereum-based chain IDs. These Wormhole-specific chain IDs uniquely identify each blockchain network within the Wormhole protocol.

Reference - https://docs.wormhole.com/wormhole/reference/constants

Required Contracts:

IWormholeRelayer.sol - https://github.com/wormhole-foundation/wormhole-solidity-sdk/blob/main/src/interfaces/IWormholeRelayer.sol
IWormholeReceiver.sol - https://github.com/wormhole-foundation/wormhole-solidity-sdk/blob/main/src/interfaces/IWormholeRelaye.sol

Add these contracts inside the project. So that we can inherit those to our HelloWormhole.sol contract.

Here is the HelloWormhole.sol contract after integrating Wormhole :

import "../IWormholeRelayer.sol";
import "../IWormholeReceiver.sol";

contract HelloWormhole is IWormholeReceiver {
    event MessageSent(uint256 messageId, string message );
    event MessageReceived(address sourceAddress, uint256 messageId, string message);

    // The address of the wormhole relayer
    IWormholeRelayer public immutable wormholeRelayer;

    // Initializing the wormhole relayer
    constructor(address _wormholeRelayer) {
        wormholeRelayer = IWormholeRelayer(_wormholeRelayer);
    }

    // Quotes the cost of sending a message to the targetChain with the given gas_limit using Wormhole
    function quoteCrossChainSendingFee(
        uint16 targetChain,
        uint256 gas_limit
        ) public view returns (uint256 cost) {
            (cost, ) = wormholeRelayer.quoteEVMDeliveryPrice(
                targetChain,
                0,
                gas_limit
            );
        }

    function sendMessage(
        uint16 targetChain,
        uint256 gas_limit,
        address targetAddress,
        uint256 messageId,
        string memory message) public payable{
            // Check the provided fee is valid
            uint256 cost = quoteCrossChainSendingFee(targetChain, gas_limit);
            require(msg.value == cost, "Invalid value sent");

            wormholeRelayer.sendPayloadToEvm{value: cost}(
                targetChain, // Wormhole chainId of the target chain
                targetAddress,
                abi.encode(messageId, message), // payload
                0, // no receiver value needed since we're just passing a message
                gas_limit,
                currentChain, // Wormhole chainId of the refund address
                msg.sender // Address  where the refund will be sent
            );
        }

    function receiveWormholeMessages(
        bytes memory payload,
        bytes[] memory, // additionalVaas
        bytes32 sourceAddress,
        uint16 sourceChain,
        bytes32 // delivery hash
        ) public payable override onlyWormholeRelayer notBase {
            require(payload.length > 0, "Invalid payload");

            (uint256 messageId, string memory message) = abi.decode(
                payload,
                (uint256, string)
            );

            address source = address(uint160(uint256(sourceAddress)));

            emit MessageReceived(source, messageId, message);
        }
}

Let's see all the components of the contracts and how it works 😇

Components

wormholeRelayer


    // The address of the wormhole relayer
    IWormholeRelayer public immutable wormholeRelayer;

This is the address of the relayer contract which would relay our message.

Here are the addresses of the relayer contracts used in all EVM chains: https://docs.wormhole.com/wormhole/reference/blockchain-environments/evm

QuoteCrossChainSendingFee

// Quotes the cost of sending a message to the targetChain with the given gas_limit using Wormhole
    function quoteCrossChainSendingFee(
        uint16 targetChain,
        uint256 gas_limit
        ) public view returns (uint256 cost) {
            (cost, ) = wormholeRelayer.quoteEVMDeliveryPrice(
                targetChain,
                0,
                gas_limit
            );
        }

Wormhole charges some amount of fee to be passed in the sendMessage function to deliver it cross-chain. This function returns the fee based on the targetChain and the gas_limit provided.

sendMessage

function sendMessage(
        uint16 targetChain,
        uint256 gas_limit,
        address targetAddress,
        uint256 messageId,
        string memory message) public payable{
            // Check the provided fee is valid
            uint256 cost = quoteCrossChainSendingFee(targetChain, gas_limit);
            require(msg.value == cost, "Invalid value sent");

            wormholeRelayer.sendPayloadToEvm{value: cost}(
                targetChain, // Wormhole chainId of the target chain
                targetAddress,
                abi.encode(messageId, message), // payload
                0, // no receiver value needed since we're just passing a message
                gas_limit,
                currentChain, // Wormhole chainId of the refund address
                msg.sender // Address where the refund will be sent
            );
        }

Sends a cross-chain message to the target address on the target chain. Internally, calls sendPayloadToEvm to interact with wormholeRelayers. You need to pass the fee as msg.value to send the message.

Additionally, refunds the excess amount of deducted fees to any of the supported chains and to any address.

receiveWormholeMessages

function receiveWormholeMessages(
        bytes memory payload,
        bytes[] memory, // additionalVaas
        bytes32 sourceAddress,
        uint16 sourceChain,
        bytes32 // delivery hash
        ) public payable override onlyWormholeRelayer notBase {
            require(payload.length > 0, "Invalid payload");

            (uint256 messageId, string memory message) = abi.decode(
                payload,
                (uint256, string)
            );

            address source = address(uint160(uint256(sourceAddress)));

            emit MessageReceived(source, messageId, message);
        }

Receives the message emitted from the source address on the source chain where the current contract is provided as the target address.

Validation

It's crucial to verify both the source address and the chain ID from which the message originates. This verification step is essential because malicious actors could potentially send unauthorized or harmful messages to your contract.

Check SourceAddress

require(
    address(uint160(uint256(sourceAddress))) == designatedSourceAddress,
    "Invalid source address"
);

Check SourceChain

require(
    sourceChain == designatedChainId,
    "Invalid source chain"
);

Sending cross-chain messages

Let's deploy the contract to Optimism Sepolia and Base Sepolia.

npx hardhat run scripts/deploy.js --network opSepolia
npx hardhat run scripts/deploy.js --network baseSepolia

After deployment let's send a message from Optimism Sepolia to Base Sepolia.

We are using Ethers V5.7.2 in the following example.

const opSepolia = {
    rpcUrl: "YOUR OPTIMISM SEPOLIA RPCURL",
    sourceAddress: "Address of the HelloWormhole contract deployed on Optimism Sepolia",
}

const baseSepolia = {
    rpcUrl: "YOUR BASE SEPOLIA RPCURL",
    targetAddress: "Address of the HelloWormhole contract deployed on Base Sepolia",
    wormholeChainId: 10004, // Reference : https://docs.wormhole.com/wormhole/reference/blockchain-environments/evm
    gasLimit: 300000,
}

const main = async () => {
    const provider = new ethers.providers.JsonRpcProvider(opSepolia.rpcUrl);

    const HelloWormholeContract = new ethers.Contract(
        opSepolia.sourceAddress,
        HelloWormholeABI,
        provider
    );

    const sendingCost = await HelloWormholeContract.quoteCrossChainSendingFee(
        baseSepolia.wormholeChainId,
        baseSepolia.gasLimit
    );

     const signer = new ethers.Wallet("Your Private Key", provider);

     const data = HelloWormholeContract.interface.encodeFunctionData(
        "sendMessage",
        [
            baseSepolia.wormholeChainId,
            baseSepolia.gasLimit,
            baseSepolia.targetAddress,
            "1",
            "Hello Wormhole"
        ]
    );

    const unSignedTx = {
      to: opSepolia.sourceAddress,
      value: sendingCost,
      data,
    };

    const signedTx = await signer.sendTransaction(unSignedTx);

    const receipt = await signedTx.wait();

    console.log(receipt);
}

main();

Performance

The performance of sending Cross-chain messages using Wormhole fully depends on the finality of the blocks.

Your message can take more than 15 minutes to be delivered from Optimism Sepolia. Whereas, it takes 1 minute to be delivered from Avalanche Fuji.

Our Project Fusion on ENCODE X WORMHOLE Hackathon

Check our project submitted for the ENCODE X WORMHOLE Hackathon and see how our ZK-based smart contract wallet goes multi-chain using Wormhole.

https://www.getfusion.tech

How to send your first cross-chain message using Wormhole

Table of contents