Most z Solana do Chiliz Chain

Wdróż OFT Adapter na Solana oraz Native OFT na Chiliz Chain, używając LayerZero v2 do mostkowania tokenów z Solana do Chiliz Chain.

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

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

LayerZero V2 OFT Quickstart - LayerZeroLayerZero Documentation

Wymagania wstępne

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

Będziesz zatem potrzebować następujących środowisk:

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

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

Ten przewodnik wymaga, co następuje:

• Mint address istniejącego tokena SPL, który chcesz zmostkować do Chiliz Chain.

• Portfela Web3 dla każdego chaina:

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

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

• 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 Solana: tokeny SOL.

  • Na Chiliz Chain: tokeny CHZ.

Krok 1: Tworzenie kontraktów

Wyzwanie "Shared Decimals"

Ponieważ Ethereum Virtual Machine (EVM) obsługuje matematykę tokenów inaczej niż Solana, musimy wyrównać ich precyzję dziesiętną, zanim tokeny przejdą przez bridge:

• Solana (źródło): natywne tokeny SPL mają zwykle precyzję 9 miejsc po przecinku.

• Chiliz Chain (cel): standardowe tokeny ERC-20 (oraz Twój nowy docelowy OFT) używają zwykle 18 miejsc po przecinku.

Gdybyś wysłał payload z 9 miejscami po przecinku z Solana bezpośrednio do Chiliz bez konwersji, kontrakt EVM błędnie zinterpretowałby kwotę, co skutkowałoby zmintowaniem na chainie docelowym mikroskopijnego ułamka tokena.

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

• Gdy użytkownik mostkuje 1.00 tokena SPL z Solana, Adapter na Solana skaluje liczbę w dół do 6 miejsc po przecinku (traktując najniższe 3 miejsca dziesiętne tokena SPL jako "pył" i bezpiecznie pozostawiając je w portfelu użytkownika).

• Payload wiadomości z 6 miejscami po przecinku jest wysyłany przez bridge.

• Native OFT na Chiliz Chain otrzymuje liczbę z 6 miejscami po przecinku i skaluje ją w górę do swoich lokalnych 18 miejsc, zanim zmintuje token ERC-20 do portfela EVM użytkownika.

Dowiedz się więcej tutaj.

Tworzenie programu na Solana

Ponieważ Twój token już istnieje na Solana, nie musisz tworzyć nowego kontraktu tokena. Zamiast tego wdrożysz Solana OFT Adapter Program napisany w Ruście. Program ten będzie działać jak zdecentralizowany sejf, bezpiecznie przechowując Twoje tokeny SPL, gdy użytkownicy mostkują je do Chiliz Chain, i zwalniając je, gdy użytkownicy mostkują je z powrotem.

LayerZero udostępnia workspace Anchor z gotowymi, zaudytowanymi kontraktami, więc nie musisz pisać logiki w Ruście od zera.

1. Klonowanie Solana SDK od LayerZero

Zacznij od sklonowania oficjalnego repozytorium narzędzi deweloperskich LayerZero, które zawiera przykład Solana OFT Adapter.

Otwórz terminal i uruchom:

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

2. Budowanie programu Adapter na Solana

Ten katalog to workspace Anchor zawierający implementacje zarówno Native OFT, jak i OFT Adapter. Musisz zbudować program w Ruście, aby wygenerować swój unikalny Solana Program ID.

anchor build

Po zakończeniu budowania pobierz swój nowy Program ID, uruchamiając:

anchor keys list

Przed wdrożeniem musisz zaktualizować plik Anchor.toml oraz makro declare_id! wewnątrz pliku programs/oft-adapter/src/lib.rs swoim nowym Program ID.

3. Wdrażanie na Solana Mainnet

Upewnij się, że Twoje Solana CLI jest skonfigurowane dla Mainnet oraz że Twój lokalny portfel ma wystarczająco $SOL, aby pokryć rozmiar wdrożenia oraz storage rent.

solana config set --url mainnet-beta
anchor deploy

4. Inicjalizacja OFT Adapter

W przeciwieństwie do Native OFT (który wymaga utworzenia nowego Mint), inicjalizacja Adaptera po prostu łączy Twój nowo wdrożony Program ID z istniejącym Mint Address Twojego tokena SPL.

LayerZero SDK udostępnia taski Hardhat do obsługi tej inicjalizacji z linii poleceń. Upewnij się, że Twój Solana LayerZero Endpoint (30168) jest skonfigurowany, a następnie uruchom:

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

Oto kluczowe parametry:

• --mint: musi to być dokładny Mint Address w formacie Base58 tokena SPL, który chcesz zmostkować. Adapter utworzy konto escrow specjalnie dla tego tokena.

• --shared-decimals 6: określa, jak Adapter skaluje payload przed wysłaniem go do EVM. Jeśli Twój token Solana ma 9 miejsc po przecinku, pozostawienie tutaj 6 shared decimals zapewnia, że zostanie on bezpiecznie przetłumaczony przez bridge bez problemów z przepełnieniem.

Gdy ta transakcja inicjalizacyjna zostanie potwierdzona na Solana, Twój Adapter jest aktywny i gotowy do bezpiecznego blokowania Twoich tokenów SPL!

Tworzenie kontraktów na Chiliz

Ponieważ Twój token SPL z Solana jeszcze nie istnieje na Chiliz Chain, musisz wdrożyć standardowy kontrakt Native OFT. Kontrakt ten będzie działać jako minter. Gdy otrzyma zweryfikowaną wiadomość od Twojego Adaptera na Solana, zmintuje odpowiadające tokeny ERC-20; gdy użytkownik zmostkuje z powrotem do Solana, spali je.

Jak omawialiśmy w sekcji "Wyzwanie Shared Decimals", Twój Adapter na Solana skaluje payload w dół do 6 miejsc po przecinku przed wysłaniem go.

Implementacja EVM od LayerZero jest taka, że nie musisz pisać własnej logiki skalowania. Domyślnie kontrakt OFT.sol używa 18 lokalnych miejsc po przecinku i 6 shared decimals. Automatycznie wykryje payload z 6 miejscami po przecinku przybywający z Solana i przeskaluje go w górę do standardowego formatu z 18 miejscami po przecinku () przed zmintowaniem tokena ERC-20 do portfela użytkownika.

Wdrażanie OFT na Chiliz Chain

Utwórz nowy plik o nazwie ChilizNativeOFT.sol w folderze contracts/ swojego projektu Hardhat:

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

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

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

Nie wdrażaj jeszcze! Ale pamiętaj o tym:

• Upewnij się, że parametry _name i _symbol dokładnie odpowiadają Twojemu oryginalnemu tokenowi SPL z Solana, aby zapewnić użytkownikom spójne doświadczenie.

• Podczas wdrażania na Chiliz Mainnet jako _lzEndpoint przekażesz adres Chiliz Endpoint V2 (0x6F475642a6e85809B1c36Fa62763669b1b48DD5B).

Krok 2: Konfiguracja LayerZero

Teraz, gdy masz zainicjalizowany Adapter na Solana oraz gotowy do wdrożenia Chiliz Native OFT, musisz skonfigurować połączenie między nimi.

Głównym wyzwaniem jest tutaj formatowanie adresów. Cross-chainowe przesyłanie wiadomości w LayerZero wymaga, aby wszystkie adresy peerów były sformatowane jako bytes32. Toolbox Hardhat LayerZero V2 obsługuje to automatycznie, dekodując Twój Program ID Adaptera na Solana w formacie Base58 i dopełniając go do standardowego formatu EVM.

Simple Config Generator to zalecany sposób generowania konfiguracji wiring, ponieważ automatyzuje dwukierunkowe wiring oraz stosuje zalecane konfiguracje bezpieczeństwa pod maską.

Utwórz lub zaktualizuj plik layerzero.config.ts w katalogu głównym swojego 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 solanaContract: OmniPointHardhat = {
    eid: EndpointId.SOLANA_V2_MAINNET,
    address: 'YourSolanaAdapterProgramIdHereInBase58', 
    // NOTE: Non-EVMs use 'address' instead of 'contractName'
};

const chilizContract: OmniPointHardhat = {
    eid: EndpointId.CHILIZ_V2_MAINNET,
    contractName: 'ChilizNativeOFT', // Your Hardhat deployment name on EVM
};

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

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

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

Generator obsługuje automatyczną konwersję Twojego adresu Solana w formacie Base58 na dopełnienie bytes32 EVM wymagane przez smart contract Chiliz.

Krok 3: Workflow wdrożenia

Na tym etapie Twój Adapter na Solana jest już skompilowany, wdrożony i zainicjalizowany (jak opisano w Kroku 1). Teraz musisz wdrożyć stronę EVM bridge'a — Native OFT — na Chiliz Chain.

Użyjesz Hardhat, aby wypchnąć ten kontrakt na Chiliz Mainnet.

1. Skrypt wdrożenia Chiliz Native OFT

W swoim projekcie Hardhat utwórz skrypt wdrożenia w katalogu deploy/ o nazwie 01_deploy_chiliz_native_oft.ts. Skrypt ten zainicjalizuje nowy token ERC-20 na Chiliz.

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

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

    // Token Details (Must strictly match your existing Solana SPL Token)
    const TOKEN_NAME = "My Solana Token";
    const TOKEN_SYMBOL = "SOLTKN";

    // The Chiliz Mainnet Endpoint V2 Address
    const CHILIZ_ENDPOINT_V2 = "0x6F475642a6e85809B1c36Fa62763669b1b48DD5B";

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

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

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

2. Wdrożenie programu na Solana

Tytułem szybkiego przypomnienia, Twój Adapter na Solana nie używa Hardhat do swojego początkowego wdrożenia. Powinieneś już:

1. Uruchomić anchor build i anchor deploy, aby wypchnąć program w Ruście na Solana Mainnet.

2. Wykonać task lz:oft-adapter-solana:init, aby połączyć Twój Adapter z istniejącym Mint Twojego tokena SPL.

3. Skopiować wynikowy Program ID w formacie Base58 do swojego pliku layerzero.config.ts.

3. Wykonanie wdrożenia na Chiliz

Upewnij się, że Twój plik hardhat.config.ts ma poprawnie skonfigurowany URL RPC oraz klucz prywatny dla sieci chiliz.

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

npx hardhat deploy --network chiliz --tags ChilizNativeOFT

Po zakończeniu wdrożenia Hardhat zapisze nowo zmintowany adres kontraktu Chiliz w folderze deployments/. Masz teraz aktywne kontrakty zarówno na Solana (SVM), jak i na Chiliz Chain (EVM), ale nie są one jeszcze autoryzowane do wzajemnej komunikacji.

Krok 4: Wiring i peering

W tym momencie masz program Adapter w Ruście na Solana oraz Native EVM OFT na Chiliz Chain. Aby umożliwić im bezpieczną komunikację, musisz "powiązać" je ze sobą jako zaufane peery.

Podobnie jak przy mostkowaniu w przeciwnym kierunku, mamy do czynienia z dwiema całkowicie różnymi Virtual Machines (SVM i EVM). Z tego powodu poprawne skonfigurowanie Enforced Options (Gas Limits) jest kluczowe dla zapewnienia, że Twoje transakcje nie zawisną na chainie docelowym.

"Enforced Options" dla Chiliz (EVM)

Gdy użytkownik mostkuje swój token SPL z Solana do Chiliz, LayerZero Executor potrzebuje gas EVM, aby wywołać funkcję lzReceive na Twoim kontrakcie Chiliz w celu zmintowania tokenów ERC-20.

Z kolei dla podróży powrotnej (z Chiliz z powrotem do Solana) Executor będzie potrzebował Solana Compute Units oraz Lamports, aby odblokować tokeny SPL i potencjalnie pokryć rent za Associated Token Account (ATA).

Aktualizacja konfiguracji

Aby zagwarantować, że Executor ma wystarczająco gas dla obu kierunków, musisz zdefiniować te limity w swoim pliku layerzero.config.ts przed wiringiem.

Zaktualizuj tablicę connections w pliku konfiguracyjnym, aby zawierała następujące enforcedOptions:

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

// ... (contracts array from Step 3)

    connections: [
        // Pathway 1: Solana -> Chiliz (The primary route)
        {
            from: 'YourSolanaAdapterProgramIdHereInBase58',
            to: 'ChilizNativeOFT',
            config: {
                enforcedOptions: [
                    {
                        msgType: 1, // Standard OFT Transfer
                        optionType: ExecutorOptionType.LZ_RECEIVE,
                        gas: 200000, // Standard EVM Gas to mint tokens on Chiliz
                        value: 0,    // No native drop needed on Chiliz EVM
                    }
                ]
            },
        },
        // Pathway 2: Chiliz -> Solana (The return trip)
        {
            from: 'ChilizNativeOFT',
            to: 'YourSolanaAdapterProgramIdHereInBase58',
            config: {
                enforcedOptions: [
                    {
                        msgType: 1, 
                        optionType: ExecutorOptionType.LZ_RECEIVE,
                        gas: 200000,    // Solana Compute Units for the unlock
                        value: 2500000, // Lamports (covers the ATA rent fee if needed)
                    }
                ]
            },
        },
    ],
// ...

Wykonanie zadania Wire

Gdy Twoja konfiguracja jest zapisana, toolbox LayerZero V2 automatyzuje proces peeringu. Dekoduje Twój adres Solana w formacie Base58, dopełnia go do wymaganego formatu bytes32 EVM i przesyła transakcje konfiguracyjne zarówno do Solana Mainnet, jak i do Chiliz Mainnet.

Uruchom następujące polecenie w terminalu:

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

CLI poprosi Cię o potwierdzenie transakcji. Użyje Twojego skonfigurowanego portfela Solana, aby przesłać transakcję źródłową (kosztem $SOL), oraz Hardhat, aby przesłać transakcję docelową na Chiliz (kosztem $CHZ).

Po stronie Chiliz toolbox Hardhat LayerZero automatycznie wygeneruje i wykona 6 wymaganych transakcji konfiguracyjnych:

1. setSendLibrary: przypisuje V2 MessageLib do wysyłania wiadomości.

2. setReceiveLibrary: przypisuje MessageLib do odbierania wiadomości.

3. setConfig (Send Library): konfiguruje DVN oraz Executor.

4. setConfig (Receive Library): konfiguruje DVN do przychodzącej weryfikacji.

5. setEnforcedOptions: zapewnia spójne parametry wykonania (konkretnie zapewniając, że za podróż powrotną opłacono wystarczająco Solana Compute Units).

6. setPeer: kryptograficznie łączy EID Chiliz z Program ID Adaptera na Solana w formacie Base58 (przekonwertowanym na bytes32).

Solana SDK pod maską obsługuje równoważne programowe instrukcje dla strony SVM.

Gdy obie transakcje zostaną potwierdzone, Twój bridge Solana-do-Chiliz jest oficjalnie aktywny i bezpiecznie objęty uprawnieniami!

Krok 5: Działanie i testowanie

Gdy Twój Adapter na Solana jest wdrożony, Twój Chiliz Native OFT zainicjalizowany, a oba poprawnie ze sobą powiązane, Twój token SPL jest oficjalnie gotowy do przekroczenia podziału SVM/EVM. Ostatnim krokiem jest wykonanie i śledzenie testowego transferu z Solana do Chiliz Chain.

1) Przygotowanie portfela Solana

W przeciwieństwie do EVM, gdzie musisz wykonać osobną, wcześniejszą transakcję approve(), aby przyznać Adapterowi allowance, Solana obsługuje zatwierdzenia i transfery tokenów w ramach tych samych instrukcji transakcji.

Musisz jednak upewnić się, że Twój lokalny portfel Solana (ten skonfigurowany w Twoim projekcie) faktycznie posiada saldo tokenów SPL, które zamierzasz zmostkować, oraz wystarczająco $SOL, aby pokryć opłatę za transakcję źródłową i cross-chainową opłatę za wiadomość LayerZero.

2) Wysyłanie cross-chainowej wiadomości do Chiliz

Toolbox LayerZero V2 zawiera task Hardhat do wysyłania transferów OFT bezpośrednio z linii poleceń, nawet gdy chainem źródłowym jest Solana.

W przeciwieństwie do transferów Solana-do-Solana, Twoim celem jest tutaj standardowy szesnastkowy adres portfela EVM (np. 0x123...). LayerZero CLI automatycznie obsługuje dopełnienie i konwersję bajtów dla payloadu.

Uruchom następujące polecenie w terminalu:

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

Co się tutaj dzieje?

1. Skrypt kwotuje cross-chainową opłatę w $SOL.

2. Konstruuje transakcję, która przenosi 10 tokenów SPL z Twojego portfela na konto escrow Adaptera na Solana.

3. Adapter skaluje kwotę tokena SPL z 9 miejscami po przecinku w dół do 6 shared decimals.

4. LayerZero Endpoint emituje pakiet w kierunku Chiliz Mainnet.

3) Śledzenie pakietu na LayerZero Scan

Ponieważ mostkowanie z Solana obejmuje tłumaczenie między dwoma całkowicie różnymi mechanizmami konsensusu oraz finalizowanie transakcji na SVM przed wykonaniem na EVM, asynchroniczne opóźnienie jest normalne.

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

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

LayerZero Scan - LayerZeroLayerZero Documentation

Chiliz Native OFT automatycznie przeskaluje payload z 6 miejscami po przecinku z powrotem w górę do standardowych 18 miejsc EVM, więc otrzymasz 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 Solana, ale nie wykonuje się na Chiliz, najczęstszą przyczyną jest błąd Out-of-Gas EVM.

• Jeśli parametr gas w Twoich enforcedOptions (skonfigurowany w Kroku 5) został ustawiony zbyt nisko, aby sieć Chiliz mogła przetworzyć funkcję mintującą lzReceive, LayerZero Executor nie zdoła dostarczyć wiadomości.

• Rozwiązanie: nie tracisz swoich tokenów. Możesz ręcznie przepchnąć zablokowaną wiadomość przez interfejs LayerZero Scan. Po prostu połącz swój portfel EVM z Chiliz Chain, kliknij przycisk "Force Resume" lub "Execute" w eksploratorze bloków i sam zapłać opłatę gas Chiliz, aby sfinalizować mintowanie.