Bridge từ Chiliz Chain sang Base

Triển khai OFT Adapter trên Chiliz Chain và Native OFT trên Base bằng LayerZero v2 để tạo token omnichain trên Base từ Chiliz Chain.

Để bridge một token hiện có từ Chiliz Chain sang Base, 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 đã tồn tại (Chiliz Chain), và một Native OFT trên chain đích (Base).

Lưu ý rằng LayerZero cung cấp QuickStart riêng cho các hợp đồng OFT, cũng như hướng dẫn để tìm hiểu cách đúc token từ Chiliz Chain sang một EVM chain khác như Base. Hướng dẫn đó dùng Optimism làm chain đích, nhưng bạn có thể thay thế bằng thông tin của Base.

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

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

• Địa chỉ hợp đồng ERC-20 token trên Chiliz Chain.

• Một ví Web3 (chẳng hạn như MetaMask) được cấu hình để hoạt động với cả Chiliz Chain và Base.

  • Xem tại đây để cấu hình RPC của Chiliz Chain.

  • Xem tại đây để cấu hình RPC của Base Mainnet.

• Đủ 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 Chiliz Chain: token CHZ.

  • Trên Base: token ETH.

Chúng ta sẽ sử dụng Hardhat làm môi trường phát triển, cùng với Node/npx.

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

Chuẩn bị OFTAdapter trên Chiliz Chain

Đây là bước chuẩn bị, chưa triển khai ngay! Bạn sẽ triển khai ở Bước 3.

Hợp đồng OFTAdapter hoạt động như một hộp khóa cho token hiện có của bạn. Khi người dùng bridge token ra khỏi Chiliz Chain, hợp đồng này sẽ khóa các token ERC-20 gốc lại.

Tạo một file mới tên ChilizTokenAdapter.sol trong thư mục contracts của bạn:

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

Như bạn thấy, hợp đồng này mở rộng hợp đồng LayerZero OFT Adapter, cũng như hợp đồng Ownable.sol tiêu chuẩn để cấp quyền quản trị. Bạn cần cả hai để chỉ có bạn mới có thể kết nối các chain một cách an toàn.

Khi triển khai hợp đồng này lên Chiliz Chain Mainnet, bạn phải truyền địa chỉ hợp đồng token hiện có làm _token và địa chỉ Chiliz Endpoint V2 (0x6F475642a6e85809B1c36Fa62763669b1b48DD5B) làm _lzEndpoint.

Xem tất cả các endpoint khả dụng cho Chiliz Chain tại đây:

Chiliz Mainnet - LayerZeroLayerZero Documentation

Chuẩn bị OFT trên Base

Vì token chưa tồn tại tự nhiên trên Base, bạn phải triển khai một hợp đồng OFT tiêu chuẩn. Hợp đồng này có quyền đúc token mới khi nhận được tin nhắn hợp lệ từ OFT Adapter đã triển khai trên Chiliz, và đốt chúng khi người dùng bridge trở lại.

Tạo một file mới tên BaseTokenOFT.sol trong thư mục contracts của bạn:

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

Như bạn thấy, hợp đồng này mở rộng hợp đồng LayerZero OFT cũng như hợp đồng Ownable.sol tiêu chuẩn, vì những lý do đã nêu ở trên.

Khi triển khai hợp đồng này lên Base, hãy đảm bảo _name và _symbol khớp với token gốc của bạn trên Chiliz Chain để tránh gây nhầm lẫn cho người dùng. Truyền địa chỉ Base Endpoint V2 (0x1a44076050125825900e736c501f859c50fE728c) làm _lzEndpoint.

Xem tất cả các endpoint khả dụng cho Base tại đây:

Base Mainnet - LayerZeroLayerZero Documentation

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

Khi các hợp đồng đã sẵn sàng, bạn cần thông báo cho bộ công cụ LayerZero biết cách chúng kết nối với nhau. Điều này được thực hiện bằng file layerzero.config.ts nằm ở thư mục gốc của dự án Hardhat.

File cấu hình này đóng vai trò như bản thiết kế cho kiến trúc cross-chain của bạn. Nó ánh xạ các smart contract đã triển khai tới các LayerZero Endpoint ID (EID) tương ứng và định nghĩa các đường dẫn (kết nối) giữa chúng.

Simple Config Generator là cách được khuyến nghị để tạo cấu hình wiring, 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ị bên trong.

Tạo hoặc cập nhật file layerzero.config.ts ở 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 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]
            ],
        ]),
    };
}

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

Với các hợp đồng đã viết xong và layerzero.config.ts đã chuẩn bị, đã đến lúc triển khai các hợp đồng lên các mạng tương ứng. Bộ công cụ LayerZero V2 dựa vào plugin hardhat-deploy để quản lý việc triển khai hiệu quả.

Bạn cần tạo hai script triển khai trong thư mục deploy/ của dự án: một cho Chiliz Chain Mainnet và một cho Base Mainnet.

Script triển khai Chiliz Adapter

Tạo một file tên 01_deploy_chiliz_adapter.ts trong thư mục deploy/. Script này truyền địa chỉ token hiện có và địa chỉ Chiliz Endpoint V2 vào constructor.

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'];

Script triển khai Base OFT

Tạo file thứ hai tên 02_deploy_base_oft.ts trong thư mục deploy/. Script này khởi tạo Native OFT mới trên 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'];

Thực hiện triển khai

Hãy đảm bảo hardhat.config.ts của bạn đã cấu hình đúng URL RPC và private key cho cả Chiliz Chain và Base.

Kết nối bằng RPC

Connecting to Base - Base DocumentationBase documentation

Chạy các lệnh sau trong terminal để triển khai các hợp đồng:

# 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

Sau khi hoàn tất triển khai, Hardhat sẽ lưu các địa chỉ hợp đồng vào thư mục deployments/. Bộ công cụ LayerZero sẽ tự động đọc các địa chỉ này khi chúng ta chạy lệnh wiring ở bước tiếp theo.

Bước 4: Wiring & Peering

Ở giai đoạn này, các hợp đồng ChilizTokenAdapter và BaseTokenOFT của bạn đã được triển khai trên mỗi chain, nhưng chúng hoàn toàn độc lập với nhau. Nếu hợp đồng Base nhận được một tin nhắn yêu cầu đúc token, nó cần biết rằng tin nhắn đó thực sự xuất phát từ Adapter của bạn trên Chiliz, chứ không phải từ một kẻ tấn công độc hại.

Bạn phải thiết lập sự tin tưởng này bằng cách "wiring" các hợp đồng lại với nhau theo cặp thông qua mật mã.

Điều này được thực hiện bằng cách chạy lệnh wire, lệnh này sẽ tạo và thực thi các giao dịch trên cả Chiliz và Base.

Điều gì xảy ra bên trong?

Một cấu hình pathway LayerZero V2 hoàn chỉnh thực ra yêu cầu 6 giao dịch trên mỗi chain:

• setSendLibrary: Gán MessageLib của LayerZero chịu trách nhiệm gửi tin nhắn (ví dụ: cấu hình sử dụng V2 Send Library).

• setReceiveLibrary: Gán MessageLib chịu trách nhiệm nhận tin nhắn. (Bao gồm gracePeriod, thường đặt là 0).

• setConfig (Send Library): Đặt các Decentralized Verifier Networks (DVN) và Executor cụ thể cho các tin nhắn đi ra.

• setConfig (Receive Library): Đặt các DVN cụ thể cần thiết để xác minh các tin nhắn đến.

• setEnforcedOptions: Đặt giới hạn gas thực thi bắt buộc. Khi người dùng gửi tin nhắn từ Chiliz Chain, họ trả trước gas cho chain đích. Việc đặt enforced options đảm bảo họ trả đủ gas để LayerZero Executor xử lý thành công giao dịch trên Chiliz Chain.

• setPeer: Liên kết một Endpoint ID (EID) đích với một địa chỉ hợp đồng được tin tưởng. Bạn phải thông báo cho hợp đồng Chiliz Chain tin tưởng hợp đồng Base, và hợp đồng Base tin tưởng hợp đồng Chiliz Chain.

Thực thi tác vụ Wire

Chạy lệnh sau trong terminal:

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

Bộ công cụ sẽ tự động tính toán các tham số cần thiết, hiển thị cho bạn bảng các giao dịch sắp thực thi, và gửi chúng lên Chiliz và Base bằng ví deployer của bạn.

Sau khi các giao dịch được xác nhận trên cả hai mạng, cầu nối token của bạn đã chính thức hoạt động và được cấu hình đầy đủ! Chiliz Adapter hiện được phép gửi lệnh đúc token tới Base, và Base được phép gửi lệnh mở khóa trở lại Chiliz.

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

Với các hợp đồng đã triển khai và kết nối bảo mật với nhau, token của bạn giờ là omnichain. Bước cuối cùng là thực hiện một giao dịch chuyển cross-chain từ Chiliz Chain Mainnet sang Base Mainnet.

1) Thực hiện giao dịch chuyển Cross-Chain

Bộ công cụ LayerZero V2 cung cấp một tác vụ Hardhat tích hợp để kiểm tra các giao dịch chuyển OFT trực tiếp từ terminal. Lệnh này sẽ ước tính phí gas cross-chain, tính phí từ ví của bạn bằng $CHZ (token gas gốc trên chain nguồn), và khởi tạo việc chuyển nhượng.

Vì ChilizTokenAdapter cần quyền khóa Fan Tokens hiện có của bạn, một giao dịch approve() ERC-20 là bắt buộc.

LayerZero CLI phát hiện điều này và tự động xử lý việc phê duyệt trước khi gửi tin nhắn.

Chạy lệnh sau:

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

Lệnh này thực hiện những gì:

1. Tra cứu Chiliz Mainnet (30409) và Base Mainnet (30184) trong cấu hình của bạn.

2. Báo giá phí cross-chain mà LayerZero Executor yêu cầu.

3. Gọi hàm send() trên Chiliz Adapter của bạn.

4. Adapter khóa 10 token và phát ra một packet tới LayerZero Endpoint.

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

Các giao dịch cross-chain là bất đồng bộ. Trong khi giao dịch Chiliz của bạn sẽ được xác nhận trong vài giây, tin nhắn vẫn cần được xác minh và thực thi trên Base.

Để theo dõi hành trình này theo thời gian thực, hãy nhấp vào đường dẫn LayerZero Scan xuất hiện trong đầu ra CLI.

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

LayerZero Scan - LayerZeroLayerZero Documentation

Thiết lập giới hạn Gas

Việc đặt giới hạn gas là cực kỳ quan trọng, vì nếu không làm vậy, các tin nhắn cross-chain của bạn có thể thất bại trên mạng đích.

Khi người dùng bridge một token từ Chiliz Chain sang Base, họ trả phí gas cho cả hai chain trước trong một giao dịch duy nhất trên Chiliz (sử dụng $CHZ). LayerZero sau đó sử dụng một phần phí đó để trả gas ETH thực tế cần thiết để thực thi giao dịch đúc token trên Base.

Để đảm bảo LayerZero có đủ gas để xử lý thành công hàm lzReceive trên chain đích, bạn phải đặt Enforced Options. Nếu không đặt, giao dịch có thể bị revert trên chain đích do lỗi "Out of Gas".

Cấu hình Options

Tùy chọn này được thiết lập trong file layerzero.config.ts của bạn. Cập nhật mảng connections để bao gồm khối enforcedOptions cho mỗi pathway:

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

Giải thích các tham số:

• msgType: 1: Đại diện cho một giao dịch chuyển token tiêu chuẩn. msgType: 2 được dùng cho các lệnh gọi "composed" (ví dụ: bridge một token và ngay lập tức stake nó trong một lần nhấp).

• optionType: 1: Hướng dẫn Executor chỉ thực thi hàm lzReceive.

• gas: 200000: Giới hạn gas cơ bản an toàn cho các lần đúc và mở khóa OFT tiêu chuẩn. Bạn có thể điều chỉnh dựa trên mức tiêu thụ gas cụ thể của các hợp đồng đã triển khai.

Nếu bạn đã đặt tùy chọn này sau khi đã wiring các chain, bạn có thể wiring lại với các tùy chọn đã có bằng cách dùng lệnh tương tự:

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

Bộ công cụ sẽ tự động phát hiện các thay đổi và gửi giao dịch setEnforcedOptions() tới các hợp đồng của bạn trên cả Chiliz và Base. Bây giờ, mỗi khi người dùng kích hoạt bridge, các hợp đồng sẽ yêu cầu người dùng trả cho ít nhất 200.000 đơn vị gas trên chain đích, đảm bảo việc giao tin nhắn đáng tin cậy.