Most z Chiliz Chain do Base

Wdróż OFT Adapter na Chiliz Chain oraz Native OFT na Base przy użyciu LayerZero v2, aby uczynić token z Chiliz Chain omnichain na Base.

Aby zmostować istniejący token z Chiliz Chain do Base, musisz napisać i wdrożyć dwa osobne smart contracty: OFT Adapter na chainie, na którym token już istnieje (Chiliz Chain), oraz Native OFT na chainie docelowym (Base).

Pamiętaj, że LayerZero udostępnia własny QuickStart dla kontraktów OFT, a także tutorial pokazujący, jak mintować z Chiliz Chain na inny chain EVM taki jak Base. Ten tutorial używa Optimism jako chainu docelowego, ale możesz go zastąpić danymi Base.

Wymagania wstępne

Ten przewodnik wymaga następujących rzeczy:

• Adresu kontraktu tokena ERC20 na Chiliz Chain.

• Portfela Web3 (takiego jak MetaMask) skonfigurowanego do pracy zarówno z Chiliz Chain, jak i Base.

  • Konfigurację RPC dla Chiliz Chain znajdziesz tutaj.

  • Konfigurację RPC dla Base Mainnet znajdziesz tutaj.

• Wystarczającej ilości tokenów gas na każdym chainie, aby pokryć wdrożenia kontraktów oraz opłaty gas za wysyłanie wiadomości.

  • Na Chiliz Chain: tokeny CHZ.

  • Na Base: tokeny ETH.

Jako środowisko deweloperskie użyjemy Hardhat oraz Node/npx.

Krok 1: Tworzenie kontraktów

Przygotowanie OFTAdapter na Chiliz Chain

To krok przygotowawczy, nie wdrażaj od razu! Wdrożenie nastąpi w Kroku 3.

Kontrakt OFTAdapter działa jako skarbiec (lockbox) dla Twojego istniejącego tokena. Gdy użytkownicy mostują swoje tokeny z Chiliz Chain, ten kontrakt blokuje oryginalne tokeny ERC20.

Stwórz nowy plik o nazwie ChilizTokenAdapter.sol w swoim folderze contracts:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.30;

import { OFTAdapter } from "@layerzerolabs/lz-evm-oapp-v2/contracts/oft/OFTAdapter.sol";
import { Ownable } from "@openzeppelin/contracts/access/Ownable.sol";

contract ChilizTokenAdapter is OFTAdapter {
    constructor(
        address _token,      // The address of your EXISTING Token on Chiliz Chain
        address _lzEndpoint, // The LayerZero V2 Endpoint address on Chiliz
        address _delegate    // The address capable of making configuration changes (usually your wallet)
    ) OFTAdapter(_token, _lzEndpoint, _delegate) Ownable(_delegate) {}
}

Jak widać, ten kontrakt rozszerza kontrakt OFT Adapter od LayerZero, a także standardowy kontrakt Ownable.sol, który nadaje klucze administracyjne. Potrzebujesz obu, aby tylko Ty mógł bezpiecznie połączyć (wire) chainy ze sobą.

Wdrażając ten kontrakt na Chiliz Chain Mainnet, musisz przekazać adres kontraktu swojego istniejącego tokena jako _token oraz adres Chiliz Endpoint V2 (0x6F475642a6e85809B1c36Fa62763669b1b48DD5B) jako _lzEndpoint.

Wszystkie dostępne endpointy dla Chiliz Chain znajdziesz tutaj:

Chiliz Mainnet - LayerZeroLayerZero Documentation

Przygotowanie OFT na Base

Ponieważ token nie istnieje jeszcze natywnie na Base, musisz wdrożyć standardowy kontrakt OFT. Ten kontrakt ma uprawnienia do mintowania nowych tokenów, gdy otrzyma poprawną wiadomość od OFT Adapter wdrożonego na Chiliz, oraz do ich palenia (burn), gdy użytkownicy mostują z powrotem.

Stwórz nowy plik o nazwie BaseTokenOFT.sol w swoim folderze contracts:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.30;

import { OFT } from "@layerzerolabs/lz-evm-oapp-v2/contracts/oft/OFT.sol";
import { Ownable } from "@openzeppelin/contracts/access/Ownable.sol";

contract BaseTokenOFT is OFT {
    constructor(
        string memory _name,   // The name of the token (Should match your Chiliz Token)
        string memory _symbol, // The symbol of the token (Should match your Chiliz Token)
        address _lzEndpoint,   // The LayerZero V2 Endpoint address on Base
        address _delegate      // The address capable of making configuration changes
    ) OFT(_name, _symbol, _lzEndpoint, _delegate) Ownable(_delegate) {}
}

Jak widać, ten kontrakt rozszerza kontrakt OFT od LayerZero, a także standardowy kontrakt Ownable.sol, z tych samych powodów co wymienione powyżej.

Wdrażając ten kontrakt na Base, upewnij się, że _name i _symbol odpowiadają oryginalnemu tokenowi na Chiliz Chain, aby nie wprowadzać użytkowników w błąd. Przekaż adres Base Endpoint V2 (0x1a44076050125825900e736c501f859c50fE728c) jako _lzEndpoint.

Wszystkie dostępne endpointy dla Base znajdziesz tutaj:

Base Mainnet - LayerZeroLayerZero Documentation

Krok 2: Konfiguracja LayerZero

Gdy Twoje kontrakty są gotowe, musisz powiedzieć narzędziom LayerZero, jak się łączą. Robi się to za pomocą pliku layerzero.config.ts umieszczonego w katalogu głównym projektu Hardhat.

Ten plik konfiguracyjny pełni rolę schematu Twojej architektury cross-chain. Mapuje wdrożone smart contracty na ich odpowiednie identyfikatory LayerZero Endpoint (EID) i definiuje ścieżki (połączenia) między nimi.

Simple Config Generator to zalecany sposób generowania konfiguracji połączeń (wiring), ponieważ automatyzuje dwukierunkowe wiring i stosuje pod spodem zalecane konfiguracje bezpieczeństwa.

Stwórz lub zaktualizuj plik layerzero.config.ts w katalogu głównym projektu Hardhat:

import { ExecutorOptionType } from '@layerzerolabs/lz-v2-utilities';
import { OAppEnforcedOption, OmniPointHardhat } from '@layerzerolabs/toolbox-hardhat';
import { EndpointId } from '@layerzerolabs/lz-definitions';
import { generateConnectionsConfig } from '@layerzerolabs/metadata-tools';

// Define the Contracts
const chilizContract: OmniPointHardhat = {
    eid: EndpointId.CHILIZ_V2_MAINNET,
    contractName: 'ChilizTokenAdapter',
};

const baseContract: OmniPointHardhat = {
    eid: EndpointId.BASE_V2_MAINNET,
    contractName: 'BaseFanTokenOFT',
};

// Define standard EVM Gas Limits (Enforced Options)
const EVM_ENFORCED_OPTIONS: OAppEnforcedOption[] = [
    {
        msgType: 1,  // Standard OFT Transfer
        optionType: ExecutorOptionType.LZ_RECEIVE,
        gas: 200000, // Safe baseline gas limit for minting/unlocking
        value: 0,    
    },
];

// Export the Generated Configuration
export default async function () {
    return {
        contracts: [
            { contract: chilizContract },
            { contract: baseContract },
        ],
        connections: await generateConnectionsConfig([
            [
                chilizContract,  // Source
                baseContract,    // Destination
                [['LayerZero Labs'], []], // Default DVN Configuration
                [1, 1],                   // Block confirmations
                [EVM_ENFORCED_OPTIONS, EVM_ENFORCED_OPTIONS], // Execution Options [To Chiliz, To Base]
            ],
        ]),
    };
}

Krok 3: Proces wdrożenia

Mając napisane kontrakty oraz przygotowany plik layerzero.config.ts, czas wdrożyć kontrakty do ich odpowiednich sieci. Toolbox LayerZero V2 opiera się na pluginie hardhat-deploy, aby efektywnie zarządzać wdrożeniami.

Będziesz musiał stworzyć dwa skrypty wdrożeniowe w katalogu deploy/ swojego projektu: jeden dla Chiliz Chain Mainnet i jeden dla Base Mainnet.

Skrypt wdrożenia Chiliz Adapter

Stwórz plik o nazwie 01_deploy_chiliz_adapter.ts w swoim folderze deploy/. Ten skrypt przekazuje adres Twojego istniejącego tokena oraz adres Chiliz Endpoint V2 do konstruktora.

import { DeployFunction } from 'hardhat-deploy/types';

const deployAdapter: DeployFunction = async ({ getNamedAccounts, deployments }) => {
    const { deploy } = deployments;
    const { deployer } = await getNamedAccounts();

    // The address of your existing ERC-20 token on Chiliz
    const TOKEN_ADDRESS = "0xYourTokenAddressHere"; 
    
    // The Chiliz Mainnet Endpoint V2 Address
    const CHILIZ_ENDPOINT_V2 = "0x6F475642a6e85809B1c36Fa62763669b1b48DD5B";

    console.log("Deploying OFTAdapter to Chiliz Mainnet...");

    await deploy('ChilizTokenAdapter', {
        from: deployer,
        args: [
            TOKEN_ADDRESS,   // _token
            CHILIZ_ENDPOINT_V2,  // _lzEndpoint
            deployer             // _delegate (Owner)
        ],
        log: true,
        waitConfirmations: 2,
    });
};

export default deployAdapter;
deployAdapter.tags = ['ChilizTokenAdapter'];

Skrypt wdrożenia Base OFT

Stwórz drugi plik o nazwie 02_deploy_base_oft.ts w swoim folderze deploy/. Ten skrypt inicjalizuje nowy Native OFT na Base.

import { DeployFunction } from 'hardhat-deploy/types';

const deployOFT: DeployFunction = async ({ getNamedAccounts, deployments }) => {
    const { deploy } = deployments;
    const { deployer } = await getNamedAccounts();

    // Token Details (Must match your Chiliz Token)
    const TOKEN_NAME = "My Token";
    const TOKEN_SYMBOL = "TKN";

    // The Base Mainnet Endpoint V2 Address 
    const BASE_ENDPOINT_V2 = "0x1a44076050125825900e736c501f859c50fE728c";

    console.log("Deploying Native OFT to Base Mainnet...");

    await deploy('BaseTokenOFT', {
        from: deployer,
        args: [
            TOKEN_NAME,         // _name
            TOKEN_SYMBOL,       // _symbol
            BASE_ENDPOINT_V2,   // _lzEndpoint
            deployer            // _delegate (Owner)
        ],
        log: true,
        waitConfirmations: 2,
    });
};

export default deployOFT;
deployOFT.tags = ['BaseTokenOFT'];

Wykonanie wdrożeń

Upewnij się, że Twój hardhat.config.ts ma poprawnie skonfigurowane adresy URL RPC oraz klucze prywatne zarówno dla Chiliz Chain, jak i Base.

polaczenie-przez-rpc.md

Connecting to Base - Base DocumentationBase documentation

Uruchom następujące polecenia w terminalu, aby wdrożyć kontrakty:

# 1. Deploy the Adapter to Chiliz Chain
npx hardhat deploy --network chiliz --tags ChilizTokenAdapter

# 2. Deploy the Native OFT to Base
npx hardhat deploy --network base --tags BaseTokenOFT

Gdy wdrożenia zostaną zakończone, Hardhat zapisze adresy kontraktów w folderze deployments/. Narzędzia LayerZero automatycznie odczytają te adresy, gdy w następnym kroku uruchomimy polecenie wiring.

Krok 4: Wiring i peering

Na tym etapie Twoje kontrakty ChilizTokenAdapter i BaseTokenOFT są wdrożone na każdym chainie, ale są całkowicie odizolowane. Jeśli kontrakt na Base otrzyma wiadomość nakazującą mintowanie tokenów, musi wiedzieć, że wiadomość naprawdę pochodzi od Twojego Adaptera na Chiliz, a nie od złośliwego podmiotu.

Musisz ustanowić to zaufanie, kryptograficznie „łącząc" (wiring) kontrakty ze sobą jako peery.

Robi się to przez uruchomienie polecenia wire, które wygeneruje i wykona transakcje zarówno na Chiliz, jak i na Base.

Co dzieje się pod spodem?

Pełna konfiguracja ścieżki LayerZero V2 wymaga w rzeczywistości 6 transakcji na każdym chainie:

• setSendLibrary: Przypisuje LayerZero MessageLib odpowiedzialną za wysyłanie wiadomości (np. konfigurując ją do użycia V2 Send Library).

• setReceiveLibrary: Przypisuje MessageLib odpowiedzialną za odbieranie wiadomości. (Zawiera gracePeriod, zwykle ustawiony na 0).

• setConfig (Send Library): Ustawia konkretne Decentralized Verifier Networks (DVN) i Executory dla wiadomości wychodzących.

• setConfig (Receive Library): Ustawia konkretne DVN wymagane do weryfikacji wiadomości przychodzących.

• setEnforcedOptions: ustawia wymagane limity gas wykonania. Gdy użytkownik wysyła wiadomość z Chiliz Chain, płaci za gas docelowy z góry. Ustawienie enforced options zapewnia, że płacą wystarczająco dużo gas, aby LayerZero Executor mógł pomyślnie przetworzyć transakcję na Chiliz Chain.

• setPeer: Łączy docelowe Endpoint ID (EID) z zaufanym adresem kontraktu. Musisz powiedzieć kontraktowi na Chiliz Chain, aby ufał kontraktowi na Base, a kontraktowi na Base, aby ufał kontraktowi na Chiliz Chain.

Wykonanie zadania Wire

Uruchom następujące polecenie w terminalu:

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

Toolchain automatycznie obliczy wymagane parametry, wyświetli tabelę transakcji, które ma zamiar wykonać, i prześle je do Chiliz oraz Base przy użyciu Twojego portfela deployera.

Gdy transakcje zostaną potwierdzone w obu sieciach, Twój bridge tokena jest oficjalnie aktywny i w pełni skonfigurowany! Chiliz Adapter jest teraz upoważniony do wysyłania poleceń mint do Base, a Base jest upoważniony do wysyłania poleceń unlock z powrotem do Chiliz.

Krok 5: Działanie i testowanie

Mając kontrakty wdrożone i bezpiecznie połączone ze sobą, Twój token jest teraz omnichain. Ostatnim krokiem jest wykonanie transferu cross-chain z Chiliz Chain Mainnet do Base Mainnet.

1) Wykonanie transferu cross-chain

Toolbox LayerZero V2 udostępnia wbudowane zadanie Hardhat do testowania transferów OFT bezpośrednio z terminala. To polecenie oszacuje opłatę gas cross-chain, obciąży Twój portfel w $CHZ (natywnym tokenie gas na chainie źródłowym) i zainicjuje transfer.

Ponieważ ChilizTokenAdapter potrzebuje uprawnień do zablokowania Twoich istniejących Fan Tokens, wymagana jest transakcja approve() ERC-20.

CLI LayerZero wykrywa to i automatycznie obsługuje zatwierdzenie (approval) przed wysłaniem wiadomości.

Uruchom następujące polecenie:

npx hardhat lz:oft:send --oapp-config layerzero.config.ts --from-eid 30409 --to-eid 30184 --amount 10

Co robi to polecenie:

1. Wyszukuje w Twojej konfiguracji Chiliz Mainnet (30409) i Base Mainnet (30184).

2. Wycenia opłatę cross-chain wymaganą przez LayerZero Executor.

3. Wywołuje funkcję send() na Twoim Chiliz Adapter.

4. Adapter blokuje 10 tokenów i emituje pakiet do LayerZero Endpoint.

2) Śledzenie pakietu na LayerZero Scan

Transakcje cross-chain są asynchroniczne. Podczas gdy Twoja transakcja na Chiliz potwierdzi się w kilka sekund, wiadomość nadal musi zostać zweryfikowana i wykonana na Base.

Aby śledzić tę podróż w czasie rzeczywistym, kliknij link do LayerZero Scan, który pojawia się w output CLI.

Dowiedz się więcej o tym narzędziu tutaj:

LayerZero Scan - LayerZeroLayerZero Documentation

Ustawianie limitów gas

Ustawienie limitów gas jest bardzo ważne, ponieważ ich brak może spowodować, że Twoje wiadomości cross-chain nie powiodą się w sieci docelowej.

Gdy użytkownik mostuje token z Chiliz Chain do Base, płaci opłatę gas za oba chainy z góry w jednej transakcji na Chiliz (używając $CHZ). LayerZero używa następnie części tej opłaty, aby zapłacić rzeczywisty gas w ETH wymagany do wykonania transakcji mintowania na Base.

Aby zapewnić, że LayerZero ma wystarczająco dużo gas, by pomyślnie przetworzyć funkcję lzReceive na chainie docelowym, musisz ustawić Enforced Options. Jeśli nie zostaną one ustawione, transakcja może zostać cofnięta (revert) na chainie docelowym z powodu błędu „Out of Gas".

Konfigurowanie opcji

Tę opcję ustawia się w pliku layerzero.config.ts. Zaktualizuj tablicę connections, aby zawierała blok enforcedOptions dla każdej ścieżki:

import { EndpointId } from '@layerzerolabs/lz-definitions';

// ... (contract definitions as before)

connections: [
    {
        from: 'ChilizTokenAdapter',
        to: 'BaseTokenOFT',
        config: {
            enforcedOptions: [
                {
                    msgType: 1,        // 1 = Standard OFT Transfer (SEND)
                    optionType: 1,     // 1 = lzReceive Option
                    gas: 200000,       // Estimated gas limit to mint on Base
                },
                {
                    msgType: 2,        // 2 = OFT Transfer with payload (SEND_AND_CALL)
                    optionType: 1,
                    gas: 250000,       // Slightly higher gas limit for complex calls
                }
            ]
        },
    },
    {
        from: 'BaseTokenOFT',
        to: 'ChilizTokenAdapter',
        config: {
            enforcedOptions: [
                {
                    msgType: 1,
                    optionType: 1,
                    gas: 200000,       // Estimated gas limit to unlock on Chiliz
                }
            ]
        },
    },
],
// ...

Wyjaśnienie parametrów:

• msgType: 1: Reprezentuje standardowy transfer tokena. msgType: 2 jest używany dla wywołań „złożonych" (composed) (np. mostowanie tokena i natychmiastowe staking go jednym kliknięciem).

• optionType: 1: Instruuje Executora, aby po prostu wykonał funkcję lzReceive.

• gas: 200000: Bezpieczny bazowy limit gas dla standardowych operacji mint i unlock OFT. Możesz to dostosować w oparciu o konkretne zużycie gas Twoich wdrożonych kontraktów.

Jeśli ustawiłeś tę opcję po już połączeniu (wiring) chainów, możesz ponownie połączyć je z opcjami będącymi teraz na miejscu, używając tego samego polecenia:

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

Narzędzia automatycznie wykryją zmiany i prześlą transakcję setEnforcedOptions() do Twoich kontraktów zarówno na Chiliz, jak i na Base. Teraz, gdy użytkownik uruchomi bridge, kontrakty będą wymagać, aby użytkownik zapłacił za co najmniej 200 000 jednostek gas na chainie docelowym, zapewniając niezawodne dostarczenie.