Most z Chiliz Chain do Solana

Wdróż OFT Adapter na Chiliz Chain oraz Native OFT na Solana przy użyciu LayerZero v2, aby mostkować tokeny z Chiliz Chain do sieci Solana.

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

Zwróć uwagę, że LayerZero udostępnia własny QuickStart dla kontraktów OFT:

LayerZero V2 OFT Quickstart - LayerZeroLayerZero Documentation

Wymagania wstępne

Mostkowanie z Chiliz Chain (EVM) do Solana (Non-EVM) wymaga developmentu na dwóch stosach technologicznych. Będziesz potrzebować środowisk i portfeli skonfigurowanych dla obu ekosystemów.

W związku z tym będziesz potrzebować następujących środowisk:

• Do interakcji z Chiliz Chain: Node/npx oraz Hardhat.

• Do interakcji z Solana: Rustup (smart contracty Solana używają języka programowania Rust), Solana CLI oraz framework Anchor i Solana SDK od LayerZero.

Ten przewodnik wymaga następujących elementów:

• Adresu kontraktu tokenu na Chiliz Chain. Nie musisz być jego właścicielem.

• Portfela Web3 dla każdego chaina (MetaMask nie obsługuje chainów non-EVM):

  • Dla Chiliz Chain: portfel MetaMask z konfiguracją RPC dla Chiliz Chain.

  • Dla Solana: portfel Solflare z konfiguracją Solana Mainnet. Oto ich przewodnik konfiguracji.

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

  • Na Chiliz Chain: tokeny CHZ.

  • Na Solana: tokeny SOL.

Krok 1: Tworzenie kontraktów

Wyzwanie "Shared Decimals"

Ponieważ Solana obsługuje matematykę tokenów inaczej niż Ethereum Virtual Machine (EVM), musimy poprawnie obsłużyć liczbę miejsc dziesiętnych:

• Chiliz Chain (EVM): standardowe tokeny ERC-20 mają zazwyczaj 18 miejsc dziesiętnych precyzji.

• Solana: natywne tokeny SPL mają zazwyczaj 9 miejsc dziesiętnych precyzji.

Jeśli wyślesz jednostek z Chiliz do Solana, kontrakt Solana błędnie zinterpretuje tę kwotę, co spowoduje ogromną inflację tokenu na chainie docelowym.

Aby znormalizować matematykę, LayerZero używa konfiguracji sharedDecimals. Domyślnie standard LayerZero V2 OFT ustawia sharedDecimals na 6.

• Gdy użytkownik mostkuje 1.00 tokenu z Chiliz, Adapter odrzuca najniższe 12 miejsc dziesiętnych (traktując je jako "dust"), aby przeskalować liczbę w dół do 6 miejsc dziesiętnych.

• Wiadomość jest wysyłana przez bridge.

• Program Solana otrzymuje 6-cyfrową liczbę i skaluje ją w górę do swoich lokalnych 9 miejsc dziesiętnych przed mintowaniem.

Dowiedz się więcej tutaj.

Przygotowanie OFTAdapter na Chiliz Chain

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

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

Ponieważ OFTAdapter od LayerZero domyślnie ustawia sharedDecimals na 6, możesz użyć standardowej implementacji. Jeśli kiedykolwiek będziesz musiał to zmienić (np. na 8), nadpisałbyś funkcję sharedDecimals().

Utwó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 ChilizSolanaAdapter is OFTAdapter {
    constructor(
        address _token,      // The address of your EXISTING Token on Chiliz Chain (18 decimals)
        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 widzisz, ten kontrakt rozszerza kontrakt OFT Adapter od LayerZero, a także standardowy kontrakt Ownable.sol, aby nadać klucze administracyjne. Potrzebujesz obu, aby Ty, i tylko Ty, mógł bezpiecznie połączyć (wire) chainy ze sobą.

Przygotowanie i wdrożenie OFT na Solana

W przeciwieństwie do Chiliz Chain, Solana nie używa Ethereum Virtual Machine (EVM) ani języka Solidity. Smart contracty Solana (zwane "Programami") są pisane w Rust.

Aby zmostkować swój token, musisz wdrożyć program OFT na Solana. Gdy ten program otrzyma zweryfikowaną wiadomość z Twojego OFTAdapter wdrożonego na Chiliz, zmintuje odpowiedni token SPL do portfela Solana użytkownika.

Solana OFT - LayerZeroLayerZero Documentation

LayerZero udostępnia gotowy do użycia przykład Anchor, więc nie musisz pisać logiki bridge w Rust od zera.

1. Sklonuj przykład OFT Solana od LayerZero:

git clone https://github.com/LayerZero-Labs/devtools.git
cd devtools/examples/oft-solana
npm install

2. Zbuduj program Rust

To również wygeneruje Twój unikalny Solana Program ID (odpowiednik adresu kontraktu w EVM):

anchor build

Po zakończeniu budowania Anchor wygeneruje nową parę kluczy w target/deploy/oft_solana-keypair.json. Możesz pobrać swój nowy Program ID, uruchamiając:

anchor keys list

3. Wdróż na Solana Mainnet

Upewnij się, że Twoje Solana CLI jest skonfigurowane dla Mainnet, a Twój lokalny portfel ma wystarczająco $SOL na wdrożenie i rent za przechowywanie. Nie zapomnij zaktualizować pliku Anchor.toml oraz makra lib.rs declare_id! tym nowym Program ID przed wdrożeniem.

solana config set --url mainnet-beta
anchor deploy

4. Zainicjuj OFT oraz SPL Mint

Na Solana logika tokenu i jego rejestr (ledger) są rozdzielone. Musisz zainicjować nowe Mint Account (token SPL) i przypisać swój nowo wdrożony program OFT jako Mint Authority. Gwarantuje to, że tylko bridge LayerZero może mintować nowe tokeny na Solana.

LayerZero SDK udostępnia zadania Hardhat/TypeScript do obsługi tej inicjalizacji bezpośrednio z linii poleceń. W swoim projekcie oft-solana skonfiguruj swój LayerZero Endpoint dla Solana (30168) i uruchom skrypt inicjalizacji:

npx hardhat lz:oft-solana:init --program-id <YOUR_NEW_PROGRAM_ID> --mint-decimals 9 --shared-decimals 6

Kluczowe parametry:

• --mint-decimals 9: ustawia standardową precyzję tokenu SPL na Solana.

• --shared-decimals 6: musi odpowiadać shared decimals, które skonfigurowałeś (lub wartości domyślnej) na swoim OFTAdapter na Chiliz Chain. To gwarantuje, że 1 token Chiliz = 1 token Solana.

Gdy ta transakcja inicjalizacji zostanie potwierdzona na blockchainie Solana, Twój natywny program OFT jest w pełni skonfigurowany i gotowy do połączenia (wire) z OFTAdapter na Chiliz!

Krok 2: Konfiguracja LayerZero

Po wdrożeniu Adaptera Chiliz i zainicjowaniu programu OFT na Solana musisz teraz skonfigurować ich połączenie. To tutaj różnica między sieciami EVM i non-EVM staje się szczególnie widoczna.

Formatowanie adresów:

• Chiliz Chain (EVM): używa standardowych 20-bajtowych adresów szesnastkowych (np. 0x123...).

• Solana: używa adresów zakodowanych w Base58 (np. YourProgramId111111111111111111111111111111).

Cross-chainowe przesyłanie wiadomości LayerZero wymaga, aby wszystkie adresy peerów były sformatowane jako bytes32. Na szczęście narzędzia Hardhat LayerZero V2 automatycznie obsługują konwersję Base58-na-Bytes32, o ile poprawnie zdefiniujesz endpointy w swojej konfiguracji.

Simple Config Generator jest rekomendowanym sposobem generowania konfiguracji połączeń (wiring), ponieważ automatyzuje dwukierunkowe łączenie i stosuje pod spodem rekomendowane konfiguracje bezpieczeństwa.

Utwórz lub zaktualizuj swój 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: 'ChilizSolanaAdapter', // Your Hardhat deployment name on EVM
};

const solanaContract: OmniPointHardhat = {
    eid: EndpointId.SOLANA_V2_MAINNET,
    address: 'YourSolanaProgramIdHereInBase58', // Base58 address format for Solana
};

// Define Execution Options for Solana (Compute Units & Lamports)
const SOLANA_ENFORCED_OPTIONS: OAppEnforcedOption[] = [
    {
        msgType: 1,
        optionType: ExecutorOptionType.LZ_RECEIVE,
        gas: 200000,    // Solana Compute Units needed for destination execution
        value: 2500000, // Lamports to cover the potential ATA creation rent fee
    },
];

// Define Execution Options for the return trip to Chiliz (EVM Gas)
const EVM_ENFORCED_OPTIONS: OAppEnforcedOption[] = [
    {
        msgType: 1, 
        optionType: ExecutorOptionType.LZ_RECEIVE,
        gas: 200000, // Standard EVM gas units to unlock tokens on Chiliz
        value: 0,
    },
];

// Export the Generated Configuration
export default async function () {
    return {
        contracts: [
            { contract: chilizContract },
            { contract: solanaContract },
        ],
        connections: await generateConnectionsConfig([
            [
                chilizContract, 
                solanaContract,
                [['LayerZero Labs'], []], 
                [1, 1], 
                [SOLANA_ENFORCED_OPTIONS, EVM_ENFORCED_OPTIONS], // Options [To Solana SVM, To Chiliz EVM]
            ],
        ]),
    };
}

Zadanie wire LayerZero odczyta to, zdekoduje string Base58, dopełni go do 32 bajtów i bezpiecznie przekaże do funkcji setPeer OFTAdapter na Chiliz.

Krok 3: Proces wdrożenia

Po napisaniu kontraktów i przygotowaniu pliku layerzero.config.ts nadszedł czas, aby wdrożyć OFTAdapter na Chiliz. Ponieważ natywny program OFT Solana zbudowałeś i wdrożyłeś już przy użyciu Anchor w Kroku 1, ten krok skupia się na wdrożeniu strony EVM bridge przy użyciu Hardhat.

Wdrożenie kontraktu OFTAdapter na Chiliz

W swoim projekcie Hardhat utwórz skrypt wdrożeniowy w katalogu deploy/ o nazwie 01_deploy_chiliz_solana_adapter.ts. Ten skrypt przekazuje do konstruktora adres Twojego istniejącego tokenu oraz adres Chiliz Endpoint V2 (EID).

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 (18 decimals)
    const TOKEN_ADDRESS = "0xYourTokenAddressHere"; 
    
    // The Chiliz Mainnet Endpoint V2 Address
    const CHILIZ_ENDPOINT_V2 = "0x6F475642a6e85809B1c36Fa62763669b1b48DD5B";

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

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

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

Wdrożenie OFTAdapter na Chiliz

Zanim przejdziesz dalej, upewnij się, że:

• skopiowałeś wynikowy Program ID w formacie Base58 do swojego pliku layerzero.config.ts.

• Twój hardhat.config.ts ma poprawnie skonfigurowany URL RPC oraz klucz prywatny dla Chiliz Chain Mainnet.

Uruchom następujące polecenie w terminalu, aby wdrożyć EVM Adapter:

npx hardhat deploy --network chiliz --tags ChilizSolanaAdapter

Po zakończeniu wdrożenia Hardhat zapisze adres kontraktu Chiliz w folderze deployments/.

W tym momencie masz działające kontrakty zarówno na Chiliz Chain (EVM), jak i na Solana (SVM), ale nie ufają one jeszcze sobie nawzajem. Czas je ze sobą zapoznać!

Krok 4: Połączenie i peering

Aby umożliwić komunikację między Twoim kontraktem OFTAdapter a programem OFT, musisz "połączyć" (wire) je ze sobą jako zaufane peery.

Ponieważ mostkujemy pomiędzy dwiema całkowicie różnymi maszynami wirtualnymi (EVM i SVM), konfiguracja wymaga szczególnej uwagi.

EVM gas vs Solana compute units

Gdy użytkownik mostkuje token z Chiliz Chain do innego chaina EVM (jak Base), Executor LayerZero potrzebuje EVM gas, aby wywołać lzReceive.

Jednak przy mostkowaniu z Chiliz Chain do Solana chain docelowy nie używa EVM gas. Używa Compute Units i Lamports (ułamków $SOL). Co więcej, jeśli użytkownik mostkuje tokeny do portfela Solana, który nie posiada jeszcze Twojego tokenu, Executor musi opłacić solanową opłatę "rent exemption", aby utworzyć dla niego Associated Token Account (ATA). Wymaga to przekazania faktycznej wartości $SOL na chainie docelowym.

Aby zagwarantować, że Executor ma wystarczająco Compute Units i Lamports do mintowania tokenów oraz tworzenia ATA na Solana, musisz zdefiniować te limity w swoim pliku layerzero.config.ts przed połączeniem (wiring).

Uruchom zautomatyzowane polecenie wire w terminalu:

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

To przygotuje 6 wymaganych transakcji konfiguracyjnych:

1. setSendLibrary: przypisuje MessageLib dla pakietów wychodzących.

2. setReceiveLibrary: przypisuje MessageLib dla pakietów przychodzących.

3. setConfig: konfiguruje DVN-y oraz Executor.

4. setConfig : konfiguruje DVN-y dla weryfikacji przychodzącej.

5. setEnforcedOptions: zapewnia spójne parametry wykonania (kluczowe dla zagwarantowania, że użytkownik z góry płaci wystarczająco, aby pokryć Solana Compute Units i rent w Lamportach).

6. setPeer: łączy Solana EID z Twoim docelowym Program ID w formacie Base58.

Toolbox LayerZero V2 automatyzuje najtrudniejszą pracę: zdekoduje adres Solana w Base58, dopełni go do wymaganego formatu bytes32 EVM oraz prześle transakcje setPeer i setEnforcedOptions na oba chainy.

Gdy transakcje połączenia zostaną potwierdzone, Twój bridge EVM-do-Solana jest aktywny i bezpiecznie zabezpieczony uprawnieniami.

Twój token jest oficjalnie gotowy do przekroczenia podziału EVM/SVM!

Krok 5: Działanie i testowanie

Po wdrożeniu Adaptera Chiliz, zainicjowaniu Native OFT na Solana oraz poprawnym połączeniu ich ze sobą, Twój token jest oficjalnie gotowy do przekroczenia podziału EVM/SVM. Ostatnim krokiem jest wykonanie i śledzenie testowego transferu z Chiliz Chain do Solana.

1) Wysłanie cross-chainowej wiadomości do Solana

Toolbox LayerZero V2 zawiera zadanie Hardhat do wysyłania transferów OFT bezpośrednio z linii poleceń.

W przeciwieństwie do transferów EVM-do-EVM, gdzie Twoim celem jest standardowy string szesnastkowy, tutaj Twoim celem jest adres portfela Solana w formacie Base58. LayerZero CLI automatycznie obsługuje konwersję Base58-na-Bytes32 dla payloadu wiadomości.

Uruchom następujące polecenie w terminalu:

npx hardhat lz:oft:send --oapp-config layerzero.config.ts --from-eid 30409 --to-eid 30168 --to <YOUR_SOLANA_WALLET_ADDRESS_BASE58> --amount 10

Co się tutaj dzieje?

1. Skrypt wycenia opłatę cross-chainową w $CHZ (która pokrywa EVM gas, opłaty sieci weryfikatorów oraz opłaty docelowe Solana).

2. Wywołuje funkcję send() na Twoim Adapterze Chiliz.

3. Adapter blokuje 10 tokenów (18 miejsc dziesiętnych). Odrzuca najniższe 12 miejsc dziesiętnych jako "dust" (pozostawiając je w Twoim portfelu Chiliz), aby przeskalować payload w dół do 6 sharedDecimals.

4. LayerZero Endpoint emituje pakiet w kierunku Solana Mainnet.

2) Śledzenie pakietu na LayerZero Scan

Ponieważ mostkowanie do Solana obejmuje translację pomiędzy dwoma całkowicie różnymi mechanizmami konsensusu oraz oczekiwanie na finalność SVM, asynchroniczne opóźnienie jest normalne.

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

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

LayerZero Scan - LayerZeroLayerZero Documentation

Translacja miejsc dziesiętnych

Native OFT na Solana automatycznie przeskaluje 6-cyfrowy payload przychodzący z bridge w górę do standardowych 9 miejsc dziesiętnych SPL, więc Twój portfel Solana otrzyma dokładnie 10 pełnych tokenów.

4) Rozwiązywanie problemów z zablokowanymi wiadomościami

Jeśli Twoja transakcja jest oznaczona jako potwierdzona na Chiliz, ale nie wykonuje się na Solana, najczęstszym winowajcą jest błąd Insufficient Lamports lub Compute Units.

• Jeśli docelowy portfel Solana nie miał jeszcze Associated Token Account (ATA) dla Twojego konkretnego tokenu, Executor LayerZero musiał opłacić solanową opłatę "rent exemption", aby go utworzyć.

• Jeśli parametr value (Lamports) w Twoich enforcedOptions był ustawiony zbyt nisko, aby pokryć ten rent, lub jeśli gas (Compute Units) był niewystarczający, Executor odmówi płacenia z własnej kieszeni, a wiadomość utknie.

• Rozwiązanie: nie tracisz swoich tokenów. Możesz ręcznie przepchnąć zablokowaną wiadomość przez UI LayerZero Scan. Podłącz swój portfel Solana, kliknij przycisk "Force Resume" lub "Execute" w eksploratorze bloków i samodzielnie opłać lokalną opłatę docelową (Compute Units + ATA Rent w $SOL), aby sfinalizować mintowanie.