LayerZero Docs

Template project for creating custom omnichain applications (OApp) powered by the LayerZero protocol. This example demonstrates how to build applications that can send and receive arbitrary messages across different blockchains.

• Prerequisite Knowledge
• Requirements
• Scaffold this example
• Helper Tasks
• Setup
• Build
  • Compiling your contracts
• Deploy
• Enable Messaging
• Sending Messages
• Next Steps
• Production Deployment Checklist
• Appendix
  • Running Tests
  • Adding other chains
  • Using Multisigs
  • LayerZero Hardhat Helper Tasks
  • Contract Verification
  • Troubleshooting

• What is an OApp (Omnichain Application)?
• How does LayerZero work?

• Node.js - >=18.16.0
• pnpm (recommended) - or another package manager of your choice (npm, yarn)
• forge (optional) - >=0.2.0 for testing, and if not using Hardhat for compilation

Create your local copy of this example:

pnpm dlx create-lz-oapp@latest --example oapp

Specify the directory, select OApp and proceed with the installation.

Note that create-lz-oapp will also automatically run the dependencies install step for you.

Throughout this walkthrough, helper tasks will be used. For the full list of available helper tasks, refer to the LayerZero Hardhat Helper Tasks section. All commands can be run at the project root.

• Copy .env.example into a new .env

• Set up your deployer address/account via the .env

  • You can specify either MNEMONIC or PRIVATE_KEY:

    MNEMONIC="test test test test test test test test test test test junk"
    or...
    PRIVATE_KEY="0xabc...def"
    

• Fund this deployer address/account with the native tokens of the chains you want to deploy to. This example by default will deploy to the following chains' testnets: Optimism Sepolia and Arbitrum Sepolia.

This project supports both hardhat and forge compilation. By default, the compile command will execute both:

pnpm compile

If you prefer one over the other, you can use the tooling-specific commands:

pnpm compile:forge
pnpm compile:hardhat

To deploy the OApp contracts to your desired blockchains, run the following command:

pnpm hardhat lz:deploy --tags SavioLZManager

Select all the chains you want to deploy the OApp to.

After deploying the OApp on the respective chains, you enable messaging by running the wiring task.

ℹ️ This example uses the Simple Config Generator, which is recommended over manual configuration.

Run the wiring task:

pnpm hardhat lz:oapp:wire --oapp-config layerzero.config.ts

Submit all the transactions to complete wiring. After all transactions confirm, your OApps are wired and can send messages to each other.

With your OApps wired, you can now send messages cross-chain.

Send a message from Optimism Sepolia to Arbitrum Sepolia:

pnpm hardhat lz:oapp:send --dst-eid 40231 --string 'Hello from Ethereum!' --network optimism-testnet

Send a message from Arbitrum Sepolia to Optimism Sepolia:

pnpm hardhat lz:oapp:send --dst-eid 40161 --string 'Hello from Arbitrum!' --network arbitrum-testnet

ℹ️ 40161 and 40231 are the Endpoint IDs of Optimism Sepolia and Arbitrum Sepolia respectively. The source network is determined by the --network flag, not a separate --src-eid parameter. View the list of chains and their Endpoint IDs on the Deployed Endpoints page.

Upon a successful send, the script will provide you with the link to the message on LayerZero Scan.

Once the message is delivered, you will be able to click on the destination transaction hash to verify that the message was received.

Congratulations, you have now sent a message cross-chain!

If you run into any issues, refer to Troubleshooting.

Now that you've gone through a simplified walkthrough, here are what you can do next.

• If you are planning to deploy to production, go through the Production Deployment Checklist.
• Read on DVNs / Security Stack
• Read on Message Execution Options

Before deploying, ensure the following:

• (recommended) you have profiled the gas usage of lzReceive on your destination chains
• (recommended) you have configured appropriate DVNs for your security requirements
• (recommended) you have tested your application thoroughly on testnets

Join our community! | Follow us on X (formerly Twitter)

Similar to the contract compilation, we support both hardhat and forge tests. By default, the test command will execute both:

pnpm test

If you prefer one over the other, you can use the tooling-specific commands:

pnpm test:forge
pnpm test:hardhat

If you're adding another EVM chain, first, add it to the hardhat.config.ts. Adding non-EVM chains do not require modifying the hardhat.config.ts.

Then, modify layerzero.config.ts with the following changes:

• declare a new contract object (specifying the eid and contractName)
• decide whether to use an existing EVM enforced options variable or declare a new one
• create a new entry in the connections array
• add the new contract into the contracts array of the export default function

After applying the desired changes, make sure you re-run the wiring task:

pnpm hardhat lz:oapp:wire --oapp-config layerzero.config.ts

The wiring task supports the usage of Safe Multisigs.

To use a Safe multisig as the signer for these transactions, add the following to each network in your hardhat.config.ts and add the --safe flag to lz:oapp:wire --safe:

// hardhat.config.ts

networks: {
  // Include configurations for other networks as needed
  fuji: {
    /* ... */
    // Network-specific settings
    safeConfig: {
      safeUrl: 'http://something', // URL of the Safe API, not the Safe itself
      safeAddress: 'address'
    }
  }
}

LayerZero Devtools provides several helper hardhat tasks to easily deploy, verify, configure, connect, and interact with OApps cross-chain.

pnpm hardhat lz:deploy --help

pnpm hardhat lz:oapp:config:init --contract-name CONTRACT_NAME --oapp-config FILE_NAME

pnpm hardhat lz:oapp:wire --oapp-config YOUR_LAYERZERO_CONFIG_FILE

You can verify EVM chain contracts using the LayerZero helper package:

pnpm dlx @layerzerolabs/verify-contract -n <NETWORK_NAME> -u <API_URL> -k <API_KEY> --contracts <CONTRACT_NAME>

Refer to Debugging Messages or Error Codes & Handling.