Create LZ OApp Quickstart

LayerZero provides create-lz-oapp, a CLI Toolkit designed to streamline the process of building, testing, deploying, and configuring omnichain applications (OApps).

tip

Get started by running the following from your command line:

npx create-lz-oapp@latest

create-lz-oapp is an npx package that allows developers to create any omnichain application, from a simple, barebones dApp to a feature-rich decentralized platform, in <4 minutes!

Setting Up Your LayerZero Project

Run npx create-lz-oapp@latest to bootstrap your initial LayerZero project:

npx create-lz-oapp@latest

Following this, a simple project creation wizard will guide you through setting up a project template. Choose from a variety of examples to match your project needs:

✔ Where do you want to start your project? … ./my-lz-oapp
✔ Which example would you like to use as a starting point? › OFT
✔ What package manager would you like to use in your project? › yarn

After that, the wizard will create some directories and files before installing the necessary dependencies.

This will initialize a repo with example contracts, cross-chain unit tests for the sample contracts, custom LayerZero configuration files, deployment scripts, and more.

Sample LayerZero Project

LayerZero projects are Node.js projects with both the Hardhat and Foundry development frameworks installed.

The initialized project has the following structure:

contracts/
deploy/
test/
foundry.toml
hardhat.config.ts
layerzero.config.ts

If you need to change these paths, refer to the hardhat paths configuration documentation.

To see all of the available LayerZero project tasks, you can run:

$ npx hardhat
Hardhat version 2.20.1

AVAILABLE TASKS:

  // ... hardhat defaults

  lz:deploy                     Deploy LayerZero contracts
  lz:errors:decode              Decodes custom error data based
  lz:errors:list                List all custom errors from your project
  lz:oapp:config:get            Outputs Custom OApp Config, Default OApp Config, and Active OApp Config. Each config contains Send & Receive Libraries, Send Uln & Executor Configs, and Recieve Executor Configs
  lz:oapp:config:get:default    Outputs the Default OApp Config. Each config contains Send & Receive Libraries, Send Uln & Executor Configs, and Receive Executor Configs
  lz:oapp:config:get:executor   Outputs the Executors destination configurations including the native max cap amount
  lz:oapp:enforced-opts:get     Outputs OApp enforced options
  lz:oapp:peers:get             Outputs OApp peer connections
  lz:oapp:wire                  Wire LayerZero OApp

Adding External Networks

After initialization, you will need to modify project configurations to add new networks you plan to deploy on.

Follow the standard Hardhat process for adding external networks to your hardhat.config.ts, with the only additional requirement being that a LayerZero Endpoint has been deployed to the chain:

fuji: {
    eid: EndpointId.AVALANCHE_V2_TESTNET,
    url: 'https://rpc.ankr.com/avalanche_fuji',
    accounts,
},

Review the list of LayerZero Endpoint Addresses to see which networks you can set.

Testing LayerZero Contracts

To begin testing your sample LayerZero contracts locally, you can use Hardhat and / or Foundry unit tests, with specific local testing utilities for each:

• Hardhat: EndpointV2Mock.sol, a mock LayerZero V2 Endpoint contract, meant for local testing of LayerZero message passing in Hardhat.

• Foundry: TestHelper.sol, an extensive LayerZero V2 testing framework, designed for simulating LayerZero state changes and contract interactions in Foundry.

As well as other useful plugins. You can learn more about this in Testing Contracts.

Deploying LayerZero Contracts

To deploy your LayerZero contracts, you can run:

npx hardhat lz:deploy

Using the network names defined in your hardhat.config.ts and the contract defined in your layerzero.config.ts.

See Deploying Contracts to learn more.

Configuring LayerZero Contracts

LayerZero contracts have unique configurations on a per pathway basis (i.e., from A to B has different properties than from B to A).

For a detailed overview of all possible configuration commands, see Configuring Contracts.

To configure your LayerZero contracts, simply modify the config of the pathway in your layerzero.config.ts.

To return the default configuration for all possible network pathways from your hardhat.config.ts, run:

npx hardhat lz:oapp:config:get:default

Once you have configured your contract pathways, you can wire them together using:

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

This function will call setPeer on each contract instance, as well as implement the custom configurations added.

See Wiring Contracts to review how to set a pathway configurations.

Debugging Contract Errors

To list all the custom errors defined in the LayerZero protocol and your project, run:

npx hardhat lz:errors:list

To help decode unknown error signatures when testing, run:

npx hardhat lz:errors:decode <error selector>