Bridge de Base para Chiliz Chain

Implante um OFT Adapter na Base e um OFT Nativo na Chiliz Chain usando LayerZero v2 para fazer bridge de um token ERC-20 existente da Base para a Chiliz Chain.

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

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

Pré-requisitos

Este guia requer o seguinte:

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

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

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

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

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

  • Na Base: tokens ETH.

  • Na Chiliz Chain: tokens CHZ.

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

Passo 1: Desenvolvimento dos Contratos

Preparando o OFTAdapter na Base

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 Base, este contrato bloqueia os tokens ERC-20 originais.

Crie um novo arquivo chamado BaseTokenAdapter.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 BaseTokenAdapter is OFTAdapter {
    constructor(
        address _token,      // O endereço do seu token EXISTENTE na Base
        address _lzEndpoint, // O endereço do LayerZero V2 Endpoint na Base
        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 Base Mainnet, você deve passar o endereço do contrato do seu token existente como _token e o endereço do Base Endpoint V2 (0x1a44076050125825900e736c501f859c50fE728c) como _lzEndpoint.

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

Base Mainnet - LayerZeroLayerZero Documentation

Preparando o OFT na Chiliz Chain

Como o token ainda não existe nativamente na Chiliz Chain, 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 Base, e queimá-los quando usuários fazem bridge de volta.

Crie um novo arquivo chamado ChilizTokenOFT.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 ChilizTokenOFT is OFT {
    constructor(
        string memory _name,   // O nome do token (deve corresponder ao seu token na Base)
        string memory _symbol, // O símbolo do token (deve corresponder ao seu token na Base)
        address _lzEndpoint,   // O endereço do LayerZero V2 Endpoint na Chiliz Chain
        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 Chiliz Chain, certifique-se de que _name e _symbol correspondam ao seu token original na Base para evitar confusão dos usuários. Passe o endereço do Chiliz Chain Endpoint V2 (0x6F475642a6e85809B1c36Fa62763669b1b48DD5B) como _lzEndpoint.

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

Chiliz 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 baseContract: OmniPointHardhat = {
    eid: EndpointId.BASE_V2_MAINNET,
    contractName: 'BaseTokenAdapter',
};

const chilizContract: OmniPointHardhat = {
    eid: EndpointId.CHILIZ_V2_MAINNET,
    contractName: 'ChilizNativeOFT',
};

// 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 execução
        value: 0,    // Native drop (0 para transferências padrão)
    },
];

// Exportar a Configuração Gerada
export default async function () {
    return {
        contracts: [
            { contract: baseContract },
            { contract: chilizContract },
        ],
        // O gerador cria automaticamente os caminhos A->B e B->A!
        connections: await generateConnectionsConfig([
            [
                baseContract,      // Origem
                chilizContract,    // 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]
            ],
        ]),
    };
}

O array [EVM_ENFORCED_OPTIONS, EVM_ENFORCED_OPTIONS] instrui o LayerZero Executor a exigir 200.000 unidades de gas ao entregar a mensagem à Chiliz, e igualmente 200.000 unidades de gas ao retornar a mensagem à 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 Base Mainnet e outro para a Chiliz Chain Mainnet.

Script de Implantação do Adapter da Base

Crie um arquivo chamado 01_deploy_base_adapter.ts na sua pasta deploy/. Este script passa o endereço do seu token existente e o endereço do Base 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 Base
    const TOKEN_ADDRESS = "0xYourTokenAddressHere"; 
    
    // O Endereço Base Mainnet Endpoint V2
    const BASE_ENDPOINT_V2 = "0x1a44076050125825900e736c501f859c50fE728c";

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

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

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

Script de Implantação do OFT da Chiliz Chain

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

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 Base)
    const TOKEN_NAME = "My Token";
    const TOKEN_SYMBOL = "TKN";

    // O Endereço Chiliz Chain Mainnet Endpoint V2 
    const CHILIZ_ENDPOINT_V2 = "0x6F475642a6e85809B1c36Fa62763669b1b48DD5B";

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

    await deploy('BaseTokenOFT', {
        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 = ['BaseTokenOFT'];

Executando as Implantações

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

Connecting to Base - Base DocumentationBase documentation

Conectar via RPC

Execute os seguintes comandos no terminal para implantar os contratos:

# 1. Implantar o Adapter na Base
npx hardhat deploy --network chiliz --tags BaseTokenAdapter

# 2. Implantar o OFT Nativo na Chiliz Chain
npx hardhat deploy --network base --tags ChilizTokenOFT

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 BaseTokenAdapter e ChilizTokenOFT estão implantados em cada rede, mas estão completamente isolados. Se o contrato da Chiliz Chain receber uma mensagem instruindo-o a mintar tokens, ele precisa saber que a mensagem realmente se originou do seu Adapter na Base, 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 Decentralized Verifier Networks (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 Base, 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 Base para confiar no contrato da Chiliz Chain, e ao contrato da Chiliz Chain para confiar no contrato da Base.

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 Base agora está autorizado a enviar comandos de mint para a Chiliz Chain, e a Chiliz Chain está autorizada a enviar comandos de desbloqueio de volta para a Base.

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 Base Mainnet para a Chiliz Chain 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 $ETH (o token de gas nativo na rede de origem, Base) e iniciará a transferência.

Execute o seguinte comando:

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

O que este comando faz:

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

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

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

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 Base para a Chiliz Chain, ele paga a taxa de gas para ambas as redes antecipadamente em uma única transação na Base (usando $ETH). 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 Chiliz Chain.

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: 'BaseTokenAdapter',
        to: 'ChilizTokenOFT',
        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 Chiliz Chain
                },
                {
                    msgType: 2,        // 2 = Transferência OFT com payload (SEND_AND_CALL)
                    optionType: 1,
                    gas: 250000,       // Limite de gas ligeiramente maior para chamadas complexas
                }
            ]
        },
    },
    {
        from: 'ChilizTokenOFT',
        to: 'BaseTokenAdapter',
        config: {
            enforcedOptions: [
                {
                    msgType: 1,
                    optionType: 1,
                    gas: 200000,       // Limite de gas estimado para desbloquear na Base
                }
            ]
        },
    },
],
// ...

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 Base e na Chiliz. 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.