Bridge de Chiliz Chain para Base

Implante um OFT Adapter na Chiliz Chain e um OFT Nativo na Base usando LayerZero v2 para tornar um token da Chiliz Chain omnichain na Base.

Para fazer bridge de um token existente da Chiliz Chain para a Base, você precisa escrever e implantar dois smart contracts separados: um OFT Adapter na rede onde o token já existe (Chiliz Chain) e um OFT Nativo na rede de destino (Base).

Note que o LayerZero fornece seu próprio QuickStart para contratos OFT, bem como um tutorial para aprender como mintar da Chiliz Chain para outra rede EVM como a Base. Esse tutorial usa Optimism como rede de destino, mas você pode substituí-lo pelos detalhes da Base.

Pré-requisitos

Este guia requer o seguinte:

• Um endereço de contrato ERC-20 na Chiliz Chain.

• Uma carteira Web3 (como MetaMask) configurada para funcionar com Chiliz Chain e Base.

  • Veja aqui a configuração RPC da Chiliz Chain.

  • Veja aqui a configuração RPC da Base Mainnet.

• Tokens de gas suficientes em cada rede para pagar as implantações de contratos e as taxas de gas para envio de mensagens.

  • Na Chiliz Chain: tokens CHZ.

  • Na Base: tokens ETH.

Usaremos o Hardhat como ambiente de desenvolvimento, e Node/npx.

Passo 1: Desenvolvimento dos Contratos

Preparando o OFTAdapter na Chiliz Chain

Este é um passo preparatório, não implante ainda! Você implantará no Passo 3.

O contrato OFTAdapter age como um cofre para seu token existente. Quando usuários fazem bridge de seus tokens para fora da Chiliz Chain, este contrato bloqueia os tokens ERC-20 originais.

Crie um novo arquivo chamado ChilizTokenAdapter.sol na pasta de contratos:

// 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,      // O endereço do seu Token EXISTENTE na Chiliz Chain
        address _lzEndpoint, // O endereço do LayerZero V2 Endpoint na Chiliz
        address _delegate    // O endereço capaz de fazer alterações de configuração (normalmente sua carteira)
    ) OFTAdapter(_token, _lzEndpoint, _delegate) Ownable(_delegate) {}
}

Como você pode ver, este contrato estende o contrato LayerZero OFT Adapter, bem como um contrato padrão Ownable.sol para dar as chaves administrativas. Você precisa de ambos para que somente você possa conectar as redes com segurança.

Ao implantar na Chiliz Chain Mainnet, você deve passar o endereço do contrato do seu token existente como _token e o endereço do Chiliz Endpoint V2 (0x6F475642a6e85809B1c36Fa62763669b1b48DD5B) como _lzEndpoint.

Veja todos os endpoints disponíveis para a Chiliz Chain aqui:

Chiliz Mainnet - LayerZeroLayerZero Documentation

Preparando o OFT na Base

Como o token ainda não existe nativamente na Base, você deve implantar um contrato OFT padrão. Este contrato tem autoridade para mintar novos tokens quando recebe uma mensagem válida do OFT Adapter implantado na Chiliz, e queimá-los quando usuários fazem bridge de volta.

Crie um novo arquivo chamado BaseTokenOFT.sol na pasta de contratos:

// 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,   // O nome do token (deve corresponder ao seu token na Chiliz)
        string memory _symbol, // O símbolo do token (deve corresponder ao seu token na Chiliz)
        address _lzEndpoint,   // O endereço do LayerZero V2 Endpoint na Base
        address _delegate      // O endereço capaz de fazer alterações de configuração
    ) OFT(_name, _symbol, _lzEndpoint, _delegate) Ownable(_delegate) {}
}

Como você pode ver, este contrato estende o contrato LayerZero OFT bem como um contrato padrão Ownable.sol, pelas mesmas razões citadas acima.

Ao implantar na Base, certifique-se de que _name e _symbol correspondam ao seu token original na Chiliz Chain para evitar confusão dos usuários. Passe o endereço do Base Endpoint V2 (0x1a44076050125825900e736c501f859c50fE728c) como _lzEndpoint.

Veja todos os endpoints disponíveis para a Base aqui:

Base Mainnet - LayerZeroLayerZero Documentation

Passo 2: Configuração do LayerZero

Com seus contratos prontos, você precisa informar ao tooling do LayerZero como eles se conectam. Isso é feito usando um arquivo layerzero.config.ts localizado na raiz do seu projeto Hardhat.

Este arquivo de configuração age como o blueprint da sua arquitetura cross-chain. Ele mapeia seus smart contracts implantados para seus respectivos Endpoint IDs (EIDs) do LayerZero e define os caminhos (conexões) entre eles.

O Simple Config Generator é a maneira recomendada de gerar configuração de wiring, pois automatiza o wiring bidirecional e aplica configurações de segurança recomendadas.

Crie ou atualize seu arquivo layerzero.config.ts na raiz do seu projeto 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';

// Definir os Contratos
const chilizContract: OmniPointHardhat = {
    eid: EndpointId.CHILIZ_V2_MAINNET,
    contractName: 'ChilizTokenAdapter',
};

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

// Definir Limites de Gas EVM padrão (Enforced Options)
const EVM_ENFORCED_OPTIONS: OAppEnforcedOption[] = [
    {
        msgType: 1,  // Transferência OFT padrão
        optionType: ExecutorOptionType.LZ_RECEIVE,
        gas: 200000, // Limite de gas de baseline seguro para mints/desbloqueios
        value: 0,    
    },
];

// Exportar a Configuração Gerada
export default async function () {
    return {
        contracts: [
            { contract: chilizContract },
            { contract: baseContract },
        ],
        connections: await generateConnectionsConfig([
            [
                chilizContract,  // Origem
                baseContract,    // Destino
                [['LayerZero Labs'], []], // Configuração DVN padrão
                [1, 1],                   // Confirmações de bloco
                [EVM_ENFORCED_OPTIONS, EVM_ENFORCED_OPTIONS], // Opções de Execução [Para Chiliz, Para Base]
            ],
        ]),
    };
}

Passo 3: Fluxo de Implantação

Com seus contratos escritos e seu layerzero.config.ts preparado, é hora de implantar os contratos em suas respectivas redes. O toolbox LayerZero V2 depende do plugin hardhat-deploy para gerenciar implantações de forma eficiente.

Você precisará criar dois scripts de implantação na pasta deploy/ do seu projeto: um para a Chiliz Chain Mainnet e outro para a Base Mainnet.

Script de Implantação do Adapter da Chiliz

Crie um arquivo chamado 01_deploy_chiliz_adapter.ts na sua pasta deploy/. Este script passa o endereço do seu token existente e o endereço do Chiliz Endpoint V2 para o construtor.

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

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

    // O endereço do seu token ERC-20 existente na Chiliz
    const TOKEN_ADDRESS = "0xYourTokenAddressHere"; 
    
    // O Endereço Chiliz Mainnet Endpoint V2
    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 de Implantação do OFT da Base

Crie um segundo arquivo chamado 02_deploy_base_oft.ts na sua pasta deploy/. Este script inicializa o novo OFT Nativo na Base.

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

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

    // Detalhes do Token (deve corresponder ao seu Token na Chiliz)
    const TOKEN_NAME = "My Token";
    const TOKEN_SYMBOL = "TKN";

    // O Endereço Base Mainnet Endpoint V2 
    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'];

Executando as Implantações

Certifique-se de que seu hardhat.config.ts tem as URLs RPC e chaves privadas configuradas corretamente para Chiliz Chain e Base.

Conectar via RPC

Connecting to Base - Base DocumentationBase documentation

Execute os seguintes comandos no terminal para implantar os contratos:

# 1. Implantar o Adapter na Chiliz Chain
npx hardhat deploy --network chiliz --tags ChilizTokenAdapter

# 2. Implantar o OFT Nativo na Base
npx hardhat deploy --network base --tags BaseTokenOFT

Após concluir as implantações, o Hardhat salvará os endereços dos contratos em uma pasta deployments/. O tooling do LayerZero lerá automaticamente esses endereços quando executarmos o comando de wiring no próximo passo.

Passo 4: Wiring e Peering

Neste ponto, seus contratos ChilizTokenAdapter e BaseTokenOFT estão implantados em cada rede, mas estão completamente isolados. Se o contrato da Base receber uma mensagem instruindo-o a mintar tokens, ele precisa saber que a mensagem realmente se originou do seu Adapter na Chiliz, e não de um ator malicioso.

Você deve estabelecer essa confiança conectando criptograficamente os contratos como peers.

Isso é feito executando o comando wire, que irá gerar e executar transações na Chiliz e na Base.

O que acontece por baixo dos panos?

Uma configuração completa de caminho LayerZero V2 requer 6 transações em cada rede:

• setSendLibrary: Atribui o MessageLib do LayerZero responsável pelo envio de mensagens.

• setReceiveLibrary: Atribui o MessageLib responsável pelo recebimento de mensagens. (Inclui um gracePeriod, tipicamente definido como 0).

• setConfig (Send Library): Define as DVNs e Executors específicos para mensagens de saída.

• setConfig (Receive Library): Define as DVNs específicas necessárias para verificar mensagens de entrada.

• setEnforcedOptions: define os limites de gas de execução necessários. Quando um usuário envia uma mensagem da Chiliz Chain, ele paga pelo gas de destino antecipadamente. Definir enforced options garante que eles paguem gas suficiente para o LayerZero Executor processar com sucesso a transação na Chiliz Chain.

• setPeer: Vincula um ID de Endpoint de destino (EID) a um endereço de contrato confiável. Você deve informar ao contrato da Chiliz Chain para confiar no contrato da Base, e ao contrato da Base para confiar no contrato da Chiliz Chain.

Executando a Tarefa Wire

Execute o seguinte comando no terminal:

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

O toolchain calculará automaticamente os parâmetros necessários, apresentará uma tabela das transações que está prestes a executar e as submeterá à Chiliz e à Base usando sua carteira de implantador.

Após as transações serem confirmadas em ambas as redes, sua bridge de tokens está oficialmente no ar e totalmente configurada! O Adapter da Chiliz agora está autorizado a enviar comandos de mint para a Base, e a Base está autorizada a enviar comandos de desbloqueio de volta para a Chiliz.

Passo 5: Operação e Testes

Com seus contratos implantados e conectados com segurança, seu token agora é omnichain. O passo final é executar uma transferência cross-chain da Chiliz Chain Mainnet para a Base Mainnet.

1) Executando a Transferência Cross-Chain

O toolbox LayerZero V2 fornece uma tarefa Hardhat integrada para testar transferências OFT diretamente do terminal. Este comando estimará a taxa de gas cross-chain, cobrará sua carteira em $CHZ (o token de gas nativo na rede de origem) e iniciará a transferência.

Como o ChilizTokenAdapter precisa de permissão para bloquear seus Fan Tokens existentes, uma transação ERC-20 approve() é necessária.

A CLI do LayerZero detecta isso e trata da aprovação automaticamente antes de enviar a mensagem.

Execute o seguinte comando:

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

O que este comando faz:

1. Localiza Chiliz Mainnet (30409) e Base Mainnet (30184) na sua configuração.

2. Calcula a taxa cross-chain exigida pelo LayerZero Executor.

3. Chama a função send() no seu Adapter da Chiliz.

4. O Adapter bloqueia 10 tokens e emite um pacote para o LayerZero Endpoint.

2) Rastreando o Pacote no LayerZero Scan

Transações cross-chain são assíncronas. Embora sua transação na Chiliz seja confirmada em alguns segundos, a mensagem ainda precisa ser verificada e executada na Base.

Para rastrear essa jornada em tempo real, clique no link do LayerZero Scan que aparece na saída da CLI.

Saiba mais sobre esta ferramenta aqui:

LayerZero Scan - LayerZeroLayerZero Documentation

Configurando Limites de Gas

É muito importante definir limites de gas, pois não fazê-lo pode fazer com que suas mensagens cross-chain falhem na rede de destino.

Quando um usuário faz bridge de um token da Chiliz Chain para a Base, ele paga a taxa de gas para ambas as redes antecipadamente em uma única transação na Chiliz (usando $CHZ). O LayerZero então usa uma parte dessa taxa para pagar o gas ETH real necessário para executar a transação de mintagem na Base.

Para garantir que o LayerZero tenha gas suficiente para processar com sucesso a função lzReceive na rede de destino, você deve definir Enforced Options. Se não forem definidas, a transação pode reverter na rede de destino com erro de "Out of Gas".

Configurando as Opções

Esta opção é configurada no seu arquivo layerzero.config.ts. Atualize o array connections para incluir o bloco enforcedOptions para cada caminho:

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

// ... (definições de contratos como antes)

connections: [
    {
        from: 'ChilizTokenAdapter',
        to: 'BaseTokenOFT',
        config: {
            enforcedOptions: [
                {
                    msgType: 1,        // 1 = Transferência OFT padrão (SEND)
                    optionType: 1,     // 1 = Opção lzReceive
                    gas: 200000,       // Limite de gas estimado para mintar na Base
                },
                {
                    msgType: 2,        // 2 = Transferência OFT com payload (SEND_AND_CALL)
                    optionType: 1,
                    gas: 250000,       // Limite de gas ligeiramente maior para chamadas complexas
                }
            ]
        },
    },
    {
        from: 'BaseTokenOFT',
        to: 'ChilizTokenAdapter',
        config: {
            enforcedOptions: [
                {
                    msgType: 1,
                    optionType: 1,
                    gas: 200000,       // Limite de gas estimado para desbloquear na Chiliz
                }
            ]
        },
    },
],
// ...

Explicação dos parâmetros:

• msgType: 1: Representa uma transferência de token padrão. msgType: 2 é usado para chamadas "compostas" (ex.: fazer bridge de um token e imediatamente fazer staking em um clique).

• optionType: 1: Instrui o Executor a simplesmente executar a função lzReceive.

• gas: 200000: Um limite de gas de baseline seguro para mints e desbloqueios OFT padrão. Você pode ajustar com base no consumo de gas específico dos seus contratos implantados.

Se você definiu esta opção após já ter conectado as redes, pode reconectar com as opções agora definidas usando o mesmo comando:

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

O tooling detectará automaticamente as alterações e submeterá uma transação setEnforcedOptions() aos seus contratos na Chiliz e na Base. Agora, sempre que um usuário iniciar uma bridge, os contratos exigirão que o usuário pague pelo menos 200.000 unidades de gas na rede de destino, garantindo uma entrega confiável.