Інтеграція з LayerZero

Інтеграція з LayerZero

LayerZero — протокол omnichain мессенджингу, який дозволяє смарт-контрактам у різних блокчейнах спілкуватися напрямую. Не просто bridge для токенів — узагальнений протокол передачі повідомлень. OFT (Omnichain Fungible Token), ONFT (Omnichain NFT), cross-chain governance, кросс-чейн протоколи ліквідності будуються на його основі.

Ключова відмінність від класичних мостів: немає централізованого custodian, який тримає кошти. Існують DVN (Decentralized Verifier Networks) — незалежні верифікатори, які підтверджують доставку повідомлень. Безпека через незалежність верифікаторів.

Архітектура V2

LayerZero V2 (актуальна версія) спростила архітектуру порівняно з V1. Ключові компоненти:

Endpoint — singleton контракт у кожній мережі. Всі взаємодії йдуть через нього. Адреса одинакова на всіх підтримуваних мережах: 0x1a44076050125825900e736c501f859c50fE728c.

DVN (Decentralized Verifier Network) — набір верифікаторів, які читають eventi вихідного чейна та підтверджують їх на цільовому. Розробник вибирає конфігурацію DVN: мінімальна кількість верифікаторів, required vs optional DVN. Google Cloud, Polyhedra, Axelar — приклади DVN провайдерів.

Executor — агент, який викликає lzReceive на цільовому чейні після підтвердження DVN. Або LayerZero executor, або кастомний.

OApp: базовий паттерн інтеграції

OApp (Omnichain Application) — базовий контракт для будь-якої LayerZero інтеграції:

import { OApp, Origin, MessagingFee } from "@layerzerolabs/oapp-evm/contracts/oapp/OApp.sol";

contract CrossChainMessenger is OApp {
    event MessageReceived(uint32 srcEid, bytes32 sender, string message);

    constructor(address _endpoint, address _owner)
        OApp(_endpoint, _owner) {}

    // Відправка повідомлення на іншу мережу
    function sendMessage(
        uint32 dstEid,       // destination endpoint ID (наприклад, 30101 = Ethereum)
        string calldata message,
        bytes calldata options // ліміт газу на цільовому
    ) external payable {
        bytes memory payload = abi.encode(message);
        
        MessagingFee memory fee = _quote(dstEid, payload, options, false);
        require(msg.value >= fee.nativeFee, "Insufficient fee");
        
        _lzSend(dstEid, payload, options, fee, payable(msg.sender));
    }

    // Отримання повідомлення (викликається Executor)
    function _lzReceive(
        Origin calldata origin,
        bytes32 /*guid*/,
        bytes calldata payload,
        address /*executor*/,
        bytes calldata /*extraData*/
    ) internal override {
        string memory message = abi.decode(payload, (string));
        emit MessageReceived(origin.srcEid, origin.sender, message);
    }
    
    // Квота fee перед відправкою
    function quoteSend(
        uint32 dstEid,
        string calldata message,
        bytes calldata options
    ) external view returns (MessagingFee memory) {
        return _quote(dstEid, abi.encode(message), options, false);
    }
}

options — важливий параметр. Кодує ліміт газу lzReceive на цільовому, drop ETH на адресу цільового (airdrop), упорядкована доставка. Використовуючи OptionsBuilder:

bytes memory options = OptionsBuilder.newOptions()
    .addExecutorLzReceiveOption(200000, 0); // 200k газу, 0 ETH airdrop

Недостатній ліміт газу → транзакція на цільовому revert. Занадто великий → користувач переплачує. Потрібно профілювати реальну газ-споживання через тести.

OFT: Omnichain Fungible Token

OFT — головний use case LayerZero. Замість мосту (lock-and-mint) токен існує нативно у кожній мережі. При кросс-чейн трансфері: спалення на вихідному + випуск на цільовому. Немає custodian, немає заблокованої ліквідності.

import { OFT } from "@layerzerolabs/oft-evm/contracts/OFT.sol";

contract MyOFT is OFT {
    constructor(
        string memory _name,
        string memory _symbol,
        address _lzEndpoint,
        address _owner
    ) OFT(_name, _symbol, _lzEndpoint, _owner) {}
}

Це буквально весь контракт для базового OFT. Логіка кросс-чейн трансфер у батьківському контракті OFT. Розгорніть на кожній цільовій мережі та зв'яжіть через setPeer:

// На Ethereum: сказуємо, що контрагент на Arbitrum — це адреса
myOFT.setPeer(30110, bytes32(uint256(uint160(arbitrumOFTAddress))));

setPeer — критична операція безпеки. Неправильний peer — повідомлення йдуть у неправильний контракт або ігноруються.

OFTAdapter для існуючих токенів

Якщо токен уже існує на одній мережі і потрібен кросс-чейн — використовуйте OFTAdapter. Він lock-and-mint: оригінальні токени блокуються в Adapter, OFT версія випускається на інших мережах:

import { OFTAdapter } from "@layerzerolabs/oft-evm/contracts/OFTAdapter.sol";

contract MyTokenAdapter is OFTAdapter {
    constructor(address _token, address _lzEndpoint, address _owner)
        OFTAdapter(_token, _lzEndpoint, _owner) {}
}

Розгорніть OFTAdapter на home chain, звичайний OFT на інших. OFTAdapter — єдиний custodian.

DVN конфігурація та безпека

Вибір DVN — ключове рішення безпеки. Конфігурація через ILayerZeroEndpointV2.setConfig:

// Установка required DVN (потрібні всі) та optional DVN (потрібен мінімум threshold)
const configParams = [{
  eid: dstEid,
  configType: CONFIG_TYPE_ULN,
  config: ethers.AbiCoder.defaultAbiCoder().encode(
    ['tuple(uint64,uint8,uint8,uint8,address[],address[])'],
    [[
      0,          // confirmations (0 = за замовчуванням)
      2,          // requiredDVNCount
      1,          // optionalDVNCount
      0,          // optionalDVNThreshold
      [dvn1, dvn2], // requiredDVNs
      [dvn3]      // optionalDVNs
    ]]
  )
}]

await endpoint.setConfig(oappAddress, sendLibAddress, configParams)

Мінімальна безпечна конфігурація: 2 незалежні DVN у required. Компромісс одного не ломає систему. Популярна: LayerZero Labs DVN + Google Cloud DVN.

Тестування та DevTools

Hardhat/Foundry: офіційні пакети @layerzerolabs/devtools-evm-hardhat містять задачі для wire (setPeer на всіх мережах), конфігурація DVN, деплой.

Тестування у Foundry: TestHelper з @layerzerolabs/test-devtools-evm-foundry дозволяє тестувати кросс-чейн логіку локально:

contract OFTTest is TestHelper {
    function setUp() public virtual override {
        super.setUp();
        // Створює два endpoint та з'єднує їх
        setUpEndpoints(2, LibraryType.UltraLightNode);
    }
}

lzScan — офіційний explorer для LayerZero повідомлень. Перший інструмент для debug кросс-чейн проблем.

Типові проблеми інтеграції

Недостатньо газу на цільовому — lzReceive revert з малого ліміту газу в options. Рішення: збільшити ліміт газу в OptionsBuilder, вимірювання через тести.

Неупорядкована доставка — повідомлення можуть приходити не в порядку відправки за замовчуванням. Якщо порядок важливий — використовуйте опцію упорядкованої доставки (дорожче).

Оцінка комісії — _quote має викликатися безпосередньо перед транзакцією. Комісія залежить від газ-ціни на цільовому та змінюється.

Stack та таймлайни

Базова інтеграція OFT (існуючий токен + кросс-чейн трансфер): 2-3 тижні. Включає контракти, деплой на 2-3 мережах, конфігурація DVN, тести.

Кросс-чейн додаток з кастомною мессенджинг логікою, кілька мереж, UI: 6-8 тижнів. Аудит рекомендований для OFT зі значною ліквідністю — конфігурація setPeer критична.