Bridge từ Solana sang Chiliz Chain

Triển khai OFT Adapter trên Solana và Native OFT trên Chiliz Chain sử dụng LayerZero v2 để bridge token từ Solana sang Chiliz Chain.

Để bridge một token hiện có từ Solana sang Chiliz Chain, bạn cần viết và triển khai hai smart contract riêng biệt: một OFT Adapter trên chain nơi token đang tồn tại (Solana), và một Native OFT trên chain đích (Chiliz Chain).

Lưu ý rằng LayerZero cung cấp QuickStart riêng cho các hợp đồng OFT:

LayerZero V2 OFT Quickstart - LayerZeroLayerZero Documentation

Điều kiện tiên quyết

Bridge từ Solana (Non-EVM) sang Chiliz Chain (EVM) đòi hỏi phát triển dual-stack. Bạn sẽ cần thiết lập môi trường và ví cho cả hai hệ sinh thái.

Do đó, bạn sẽ cần các môi trường sau:

• Cho các tương tác với Solana: Rustup (smart contract Solana sử dụng ngôn ngữ lập trình Rust), Solana CLI và Anchor framework, và LayerZero's Solana SDK.

• Cho các tương tác với Chiliz Chain: Node/npx và Hardhat.

Hướng dẫn này yêu cầu những điều sau:

• Địa chỉ mint của SPL Token hiện có mà bạn muốn bridge sang Chiliz Chain.

• Một ví Web3 cho mỗi chain:

  • Cho Solana: ví Solflare với cấu hình Solana Mainnet. Đây là hướng dẫn cài đặt của họ.

  • Cho Chiliz Chain: ví MetaMask với cấu hình RPC của Chiliz Chain.

• Đủ token gas trên mỗi chain để thanh toán phí triển khai hợp đồng cũng như gas fee cho việc gửi tin nhắn.

  • Trên Solana: token SOL.

  • Trên Chiliz Chain: token CHZ.

Bước 1: Phát triển Hợp đồng

Thách thức "Shared Decimals"

Vì Ethereum Virtual Machine (EVM) xử lý toán học token khác với Solana, chúng ta phải căn chỉnh độ chính xác thập phân trước khi token vượt qua bridge:

• Solana (Nguồn): Native SPL Token thường có 9 chữ số thập phân.

• Chiliz Chain (Đích): Token ERC-20 tiêu chuẩn (và OFT đích mới của bạn) thường dùng 18 chữ số thập phân.

Nếu bạn gửi payload 9 chữ số thập phân từ Solana trực tiếp sang Chiliz mà không chuyển đổi, hợp đồng EVM sẽ hiểu sai số lượng, dẫn đến một phần tử nhỏ của token được đúc trên chain đích.

Để chuẩn hóa phép tính, LayerZero sử dụng cấu hình sharedDecimals. Theo mặc định, chuẩn OFT LayerZero V2 đặt sharedDecimals là 6.

• Khi người dùng bridge 1.00 SPL token từ Solana, Solana Adapter sẽ co số về 6 chữ số thập phân (coi 3 chữ số thập phân thấp nhất của SPL token là "bụi" và giữ nguyên trong ví người dùng).

• Payload 6 chữ số thập phân được gửi qua bridge.

• Native OFT trên Chiliz Chain nhận số 6 chữ số thập phân và mở rộng lên 18 chữ số thập phân cục bộ trước khi đúc token ERC-20 vào ví EVM của người dùng.

Tìm hiểu thêm tại đây.

Phát triển Chương trình Solana

Vì token của bạn đã tồn tại trên Solana, bạn không cần tạo hợp đồng token mới. Thay vào đó, bạn sẽ triển khai một Solana OFT Adapter Program viết bằng Rust. Chương trình này sẽ hoạt động như một két khóa phi tập trung, giữ an toàn SPL token của bạn khi người dùng bridge chúng sang Chiliz Chain, và giải phóng chúng khi người dùng bridge ngược lại.

LayerZero cung cấp một Anchor workspace với các hợp đồng đã được xây dựng sẵn và kiểm tra bảo mật, nên bạn không phải viết logic Rust từ đầu.

1. Clone LayerZero Solana SDK

Bắt đầu bằng cách clone repository công cụ phát triển chính thức của LayerZero, chứa ví dụ Solana OFT Adapter.

Mở terminal và chạy:

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

2. Build Chương trình Solana Adapter

Thư mục này là một Anchor workspace chứa cả hai cài đặt Native OFT và OFT Adapter. Bạn cần build chương trình Rust để tạo Program ID Solana độc nhất của mình.

anchor build

Sau khi build hoàn tất, lấy Program ID mới của bạn bằng cách chạy:

anchor keys list

Bạn phải cập nhật file Anchor.toml và macro declare_id! bên trong file programs/oft-adapter/src/lib.rs với Program ID mới của bạn trước khi triển khai.

3. Triển khai lên Solana Mainnet

Đảm bảo Solana CLI của bạn được cấu hình cho Mainnet và ví cục bộ của bạn có đủ $SOL để thanh toán kích thước triển khai và tiền thuê lưu trữ.

solana config set --url mainnet-beta
anchor deploy

4. Khởi tạo OFT Adapter

Khác với Native OFT (yêu cầu tạo Mint mới), việc khởi tạo Adapter chỉ đơn giản là liên kết Program ID vừa triển khai của bạn với Địa chỉ SPL Token Mint hiện có.

LayerZero SDK cung cấp các Hardhat task để xử lý việc khởi tạo này từ dòng lệnh. Đảm bảo LayerZero Endpoint Solana của bạn (30168) đã được cấu hình, sau đó chạy:

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

Có một số tham số quan trọng ở đây:

• --mint: Đây phải là Địa chỉ Mint Base58 chính xác của SPL token bạn muốn bridge. Adapter sẽ tạo một tài khoản escrow dành riêng cho token này.

• --shared-decimals 6: Điều này quyết định cách Adapter co payload trước khi gửi đến EVM. Nếu token Solana của bạn có 9 chữ số thập phân, để 6 shared decimals ở đây đảm bảo nó được dịch an toàn qua bridge mà không có vấn đề tràn số.

Khi giao dịch khởi tạo này được xác nhận trên Solana, Adapter của bạn đã hoạt động và sẵn sàng khóa SPL token của bạn một cách an toàn!

Phát triển Hợp đồng Chiliz

Vì SPL token Solana của bạn chưa tồn tại trên Chiliz Chain, bạn phải triển khai một hợp đồng Native OFT tiêu chuẩn. Hợp đồng này sẽ hoạt động như người đúc. Khi nhận được tin nhắn đã xác minh từ Solana Adapter, nó sẽ đúc các token ERC-20 tương ứng; khi người dùng bridge ngược lại Solana, nó sẽ đốt chúng.

Như đã thảo luận trong "Thách thức Shared Decimals", Solana Adapter của bạn co payload xuống 6 chữ số thập phân trước khi gửi.

Cài đặt EVM của LayerZero được thiết kế để bạn không cần viết logic co giãn tùy chỉnh. Theo mặc định, hợp đồng OFT.sol sử dụng 18 chữ số thập phân cục bộ và 6 shared decimals. Nó sẽ tự động phát hiện payload 6 chữ số thập phân đến từ Solana và mở rộng lên định dạng 18 chữ số thập phân chuẩn () trước khi đúc token ERC-20 vào ví người dùng.

Triển khai OFT trên Chiliz Chain

Tạo một file mới tên ChilizNativeOFT.sol trong thư mục contracts/ của dự án Hardhat của bạn:

// 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) {}
}

Chưa triển khai ngay! Nhưng hãy lưu ý điều này:

• Đảm bảo các tham số _name và _symbol khớp chính xác với SPL token Solana gốc của bạn để mang lại trải nghiệm thống nhất cho người dùng.

• Khi triển khai lên Chiliz Mainnet, bạn sẽ truyền địa chỉ Chiliz Endpoint V2 (0x6F475642a6e85809B1c36Fa62763669b1b48DD5B) làm _lzEndpoint.

Bước 2: Cấu hình LayerZero

Bây giờ bạn đã có Solana Adapter được khởi tạo và Chiliz Native OFT sẵn sàng triển khai, bạn phải cấu hình kết nối giữa chúng.

Thách thức chính ở đây là định dạng địa chỉ. Tin nhắn cross-chain của LayerZero yêu cầu tất cả địa chỉ peer phải được định dạng là bytes32. Hộp công cụ Hardhat LayerZero V2 xử lý điều này tự động bằng cách giải mã Program ID Solana Adapter Base58 của bạn và thêm padding vào định dạng EVM chuẩn.

Simple Config Generator là cách được khuyến nghị để tạo cấu hình kết nối, vì nó tự động hóa việc kết nối hai chiều và áp dụng các cấu hình bảo mật được khuyến nghị.

Tạo hoặc cập nhật file layerzero.config.ts của bạn trong thư mục gốc của dự án 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]
            ],
        ]),
    };
}

Trình tạo xử lý việc chuyển đổi tự động địa chỉ Solana Base58 của bạn thành padding bytes32 EVM mà smart contract Chiliz yêu cầu.

Bước 3: Quy trình Triển khai

Ở giai đoạn này, Solana Adapter của bạn đã được biên dịch, triển khai và khởi tạo (như đã đề cập trong Bước 1). Bây giờ, bạn cần triển khai phía EVM của bridge—Native OFT—lên Chiliz Chain.

Bạn sẽ sử dụng Hardhat để đẩy hợp đồng này lên Chiliz Mainnet.

1. Script Triển khai Chiliz Native OFT

Trong dự án Hardhat của bạn, tạo một script triển khai trong thư mục deploy/ có tên 01_deploy_chiliz_native_oft.ts. Script này sẽ khởi tạo token ERC-20 mới trên 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. Triển khai Chương trình Solana

Nhắc lại nhanh, Solana Adapter của bạn không sử dụng Hardhat cho lần triển khai ban đầu. Bạn lẽ ra đã phải:

1. Chạy anchor build và anchor deploy để đẩy chương trình Rust lên Solana Mainnet.

2. Thực thi task lz:oft-adapter-solana:init để liên kết Adapter với SPL Token Mint hiện có của bạn.

3. Sao chép Program ID Base58 kết quả vào file layerzero.config.ts của bạn.

3. Thực thi Triển khai Chiliz

Đảm bảo file hardhat.config.ts của bạn đã được cấu hình đúng URL RPC và private key cho mạng chiliz.

Chạy lệnh sau trong terminal để triển khai Native OFT:

npx hardhat deploy --network chiliz --tags ChilizNativeOFT

Sau khi triển khai hoàn tất, Hardhat sẽ lưu địa chỉ hợp đồng Chiliz mới được đúc trong thư mục deployments/. Bạn hiện có các hợp đồng đang hoạt động trên cả Solana (SVM) và Chiliz Chain (EVM), nhưng chúng chưa được phép giao tiếp với nhau.

Bước 4: Kết nối & Ghép nối

Tại thời điểm này, bạn có một Rust Adapter Program trên Solana và một Native EVM OFT trên Chiliz Chain. Để cho phép chúng giao tiếp an toàn, bạn phải "kết nối" chúng với nhau như các peer đáng tin cậy.

Giống như bridge theo chiều ngược lại, chúng ta đang làm việc với hai Máy ảo hoàn toàn khác nhau (SVM và EVM). Vì vậy, việc cấu hình đúng Enforced Options (Gas Limits) là rất quan trọng để đảm bảo giao dịch của bạn không bị kẹt trên chain đích.

"Enforced Options" cho Chiliz (EVM)

Khi người dùng bridge SPL token của họ từ Solana sang Chiliz, LayerZero Executor cần EVM gas để gọi hàm lzReceive trên hợp đồng Chiliz của bạn để đúc token ERC-20.

Ngược lại, cho chuyến về (Chiliz trở lại Solana), Executor sẽ cần Solana Compute Units và Lamports để mở khóa SPL token và có thể thanh toán tiền thuê cho Associated Token Account (ATA).

Cập nhật Cấu hình

Để đảm bảo Executor có đủ gas cho cả hai chiều, bạn phải định nghĩa các giới hạn này trong file layerzero.config.ts của bạn trước khi kết nối.

Cập nhật mảng connections trong file cấu hình của bạn để bao gồm enforcedOptions sau:

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)
                    }
                ]
            },
        },
    ],
// ...

Thực thi Wire Task

Sau khi cấu hình được lưu, hộp công cụ LayerZero V2 tự động hóa quá trình ghép nối. Nó giải mã địa chỉ Solana Base58 của bạn, thêm padding vào định dạng bytes32 EVM yêu cầu, và gửi các giao dịch cấu hình lên cả Solana Mainnet và Chiliz Mainnet.

Chạy lệnh sau trong terminal:

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

CLI sẽ nhắc bạn xác nhận các giao dịch. Nó sẽ sử dụng ví Solana đã cấu hình của bạn để gửi giao dịch nguồn (tốn $SOL) và Hardhat để gửi giao dịch đích Chiliz (tốn $CHZ).

Về phía Chiliz, hộp công cụ Hardhat LayerZero sẽ tự động tạo và thực thi 6 giao dịch cấu hình bắt buộc:

1. setSendLibrary: Gán V2 MessageLib để gửi tin nhắn.

2. setReceiveLibrary: Gán MessageLib để nhận tin nhắn.

3. setConfig (Send Library): Cấu hình các DVN và Executor.

4. setConfig (Receive Library): Cấu hình các DVN để xác minh đầu vào.

5. setEnforcedOptions: Đảm bảo các tham số thực thi nhất quán (đặc biệt đảm bảo đủ Solana Compute Units được thanh toán cho chuyến về).

6. setPeer: Liên kết mật mã Chiliz EID với Program ID Base58 của Solana Adapter (đã chuyển đổi thành bytes32).

Solana SDK xử lý các lệnh lập trình tương đương cho phía SVM.

Sau khi cả hai giao dịch xác nhận, bridge Solana-sang-Chiliz của bạn chính thức hoạt động và được cấp quyền an toàn!

Bước 5: Vận hành & Kiểm tra

Với Solana Adapter đã triển khai, Chiliz Native OFT đã khởi tạo, và cả hai được kết nối đúng cách, SPL Token của bạn chính thức sẵn sàng vượt qua ranh giới SVM/EVM. Bước cuối cùng là thực thi và theo dõi một giao dịch chuyển thử nghiệm từ Solana sang Chiliz Chain.

1) Chuẩn bị Ví Solana của Bạn

Không giống như EVM nơi bạn phải thực thi một giao dịch approve() riêng trước đó để cấp cho Adapter một khoản cho phép, Solana xử lý việc phê duyệt và chuyển token trong cùng các lệnh giao dịch.

Tuy nhiên, bạn phải đảm bảo rằng ví Solana cục bộ của bạn (ví được cấu hình trong dự án của bạn) thực sự giữ số dư của SPL token bạn muốn bridge, cũng như đủ $SOL để thanh toán phí giao dịch nguồn và phí tin nhắn cross-chain LayerZero.

2) Gửi Tin nhắn Cross-Chain đến Chiliz

Hộp công cụ LayerZero V2 bao gồm một Hardhat task để gửi các giao dịch chuyển OFT trực tiếp từ dòng lệnh, ngay cả khi chain nguồn là Solana.

Không giống như các giao dịch chuyển Solana-sang-Solana, đích của bạn ở đây là một địa chỉ ví EVM hexadecimal tiêu chuẩn (ví dụ: 0x123...). LayerZero CLI xử lý việc thêm padding và chuyển đổi byte cho payload tự động.

Chạy lệnh sau trong terminal:

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

Điều gì xảy ra ở đây?

1. Script báo giá phí cross-chain bằng $SOL.

2. Nó tạo một giao dịch chuyển 10 SPL token từ ví của bạn vào tài khoản escrow của Solana Adapter.

3. Adapter co số lượng SPL token 9 chữ số thập phân xuống 6 shared decimals.

4. LayerZero Endpoint phát packet hướng đến Chiliz Mainnet.

3) Theo dõi Packet trên LayerZero Scan

Vì bridge từ Solana liên quan đến việc dịch giữa hai cơ chế đồng thuận hoàn toàn khác nhau và hoàn thành giao dịch trên SVM trước khi thực thi trên EVM, độ trễ bất đồng bộ là bình thường.

Để theo dõi hành trình này theo thời gian thực, hãy nhấp vào liên kết LayerZero Scan xuất hiện trong output CLI.

Tìm hiểu thêm về công cụ này tại đây:

LayerZero Scan - LayerZeroLayerZero Documentation

Chiliz Native OFT sẽ tự động co payload 6 chữ số thập phân trở lại thành 18 chữ số thập phân chuẩn EVM, vì vậy bạn nhận được đúng 10 token đầy đủ

4) Xử lý Tin nhắn Bị Kẹt

Nếu giao dịch của bạn được đánh dấu là đã xác nhận trên Solana nhưng không thực thi được trên Chiliz, nguyên nhân phổ biến nhất là lỗi EVM Out-of-Gas.

• Nếu tham số gas trong enforcedOptions của bạn (được cấu hình ở Bước 5) được đặt quá thấp để mạng Chiliz xử lý hàm đúc lzReceive, LayerZero Executor sẽ không thể giao tin nhắn.

• Cách khắc phục: Bạn không mất token. Bạn có thể thủ công đẩy một tin nhắn bị kẹt qua giao diện LayerZero Scan UI. Chỉ cần kết nối ví EVM của bạn với Chiliz Chain, nhấp nút "Force Resume" hoặc "Execute" trên block explorer, và tự thanh toán Chiliz gas fee để hoàn tất việc đúc.