Migrating from V1 to V2

Migration options exist for deployed LayerZero V1 applications looking to take advantage of LayerZero V2.

Deployed Apps on Endpoint V1

If you have already deployed on Endpoint V1, migrating to the new LayerZero V2 protocol is entirely optional.

LayerZero V2 comes with enhancements to the core protocol design that increase message efficiency and customizability.

You can access the new Security Stack and Independent Execution by configuring your application's Message Library to Ultra Light Node 301.

With UltraLightNode301, your deployed LZApp on Endpoint V1 will be able to configure the new Security Stack for message authentication, as well as an Executor to ensure your application receives messages on the destination chain.

Prerequisites

You should have an LZApp to start with that's already working with default settings. Any app that inherits LZApp.sol (including the Endpoint V1 OFT and ONFT standards) can be used.

Configuring UltraLightNode301

To set a new MessageLib on Endpoint V1, you will call the setConfig function on Chain A and Chain B.

Below is a simple example for how to set your MessageLib:

// @dev function to set your LZApp's send MessageLib
function setSendVersion(uint16 _version) external override onlyOwner {
        lzEndpoint.setSendVersion(_version);
}

// @dev function to set your LZApp's receive MessageLib
function setReceiveVersion(uint16 _version) external override onlyOwner {
        lzEndpoint.setReceiveVersion(_version);
}

To find the specific Send/Receive version for a given chain, call the latestVersion variable on the chain's endpoint contract.

const latestVersion = await endpointContract.latestVersion();

The latestVersion represents the index of the last MessageLib that was appended to the chain's endpoint, which currently is ReceiveULN301 for all endpoints, while SendULN301 is the index before ReceiveULN301.

const receiveUln301Version = latestVersion;
const sendUln301Version = latestVersion - 1;

Finally, you can use the respective Send/Receive versions to set your OApp to UltraLightNode301:

const sendTx = await oappContract.setSendVersion(sendUln301Version);
await sendTx.wait();

const receiveTx = await oappContract.setReceiveVersion(receiveUln301Version);
await receiveTx.wait();

After setting your libraries to the new UltraLightNode301, you can configure your LZApp using the Endpoint V1 setConfig function, passing the configType and config values for the specific Security Stack and Executors.

function setConfig(
    uint16 _version,
    uint16 _chainId,
    uint _configType,
    bytes calldata _config
) external override onlyOwner {
    lzEndpoint.setConfig(_version, _chainId, _configType, _config);
}

With UltraLightNode301, your deployed LZApp on Endpoint V1 will be able to configure the new Security Stack for message authentication, as well as an Executor to ensure your application receives messages on the destination chain.

This enables a wider range of security configurations while simultaneously isolating network liveness from message execution.

See the full list of improvements for Deployed V1 Apps in the V2 Overview.

New Apps on Endpoint V2

For new applications deciding between Endpoint V1 and Endpoint V2, we recommend deploying exclusively with V2 Contracts to take advantage of on-chain specific benefits (i.e., higher message throughput, smaller contract sizes, gas optimization, and horizontal message composability).

You will need to deploy using the new Contract Standards on Endpoint V2.

info

These benefits specifically come from improvements in on-chain protocol and application related contracts. For your application to receive these specific benefits, you will need to deploy new OApps using these contracts. See the full overview in New Protocol Contracts.