Bridge de Chiliz Chain para Solana

Implante um OFT Adapter na Chiliz Chain e um Native OFT na Solana usando LayerZero v2 para fazer bridge de tokens da Chiliz Chain para a rede Solana.

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

Observe que o LayerZero fornece seu próprio QuickStart para contratos OFT:

LayerZero V2 OFT Quickstart - LayerZeroLayerZero Documentation

Pré-requisitos

Fazer bridge da Chiliz Chain (EVM) para Solana (não-EVM) requer desenvolvimento em duas stacks.\ Você precisará de ambientes e carteiras configurados para ambos os ecossistemas.

Portanto, você precisará dos seguintes ambientes:

• Para interações com a Chiliz Chain: Node/npx e Hardhat.

• Para interações com a Solana: Rustup (smart contracts da Solana usam a linguagem de programação Rust), Solana CLI e framework Anchor e o SDK Solana do LayerZero.

Este guia exige o seguinte:

• Um endereço de contrato de token na Chiliz Chain. Você não precisa ser o proprietário.

• Uma carteira Web3 para cada cadeia (o MetaMask não suporta cadeias não-EVM):

  • Para a Chiliz Chain: carteira MetaMask com a configuração RPC da Chiliz Chain.

  • Para a Solana: carteira Solflare com configuração da Solana Mainnet. Aqui está o guia de configuração deles.

• Tokens de gas suficientes em cada cadeia para pagar pelos deploys dos contratos e pelas taxas de gas do envio de mensagens.

  • Na Chiliz Chain: tokens CHZ.

  • Na Solana: tokens SOL.

Etapa 1: Desenvolvimento dos Contratos

O Desafio dos "Decimais Compartilhados"

Como a Solana lida com a matemática de tokens de forma diferente da Ethereum Virtual Machine (EVM), precisamos lidar com os decimais corretamente:

• Chiliz Chain (EVM): Tokens ERC-20 padrão normalmente têm 18 casas decimais de precisão.

• Solana: Tokens SPL nativos normalmente têm 9 casas decimais de precisão.

Se você enviar unidades da Chiliz para a Solana, o contrato Solana interpretaria incorretamente o valor, resultando em uma inflação massiva do token na cadeia de destino.

Para normalizar a matemática, o LayerZero usa uma configuração sharedDecimals. Por padrão, o padrão OFT V2 do LayerZero define sharedDecimals como 6.

• Quando um usuário faz bridge de 1,00 token da Chiliz, o Adapter descarta os 12 decimais mais baixos (tratando-os como "dust") para reduzir o número para 6 decimais.

• A mensagem é enviada pela bridge.

• O programa Solana recebe o número de 6 decimais e o escala para cima até seus 9 decimais locais antes de mintar.

Saiba mais aqui.

Preparando o OFTAdapter na Chiliz Chain

Esta é uma etapa preparatória, não faça o deploy agora!\ Você fará o deploy na Etapa 3.

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

Como o OFTAdapter do LayerZero define sharedDecimals como 6 por padrão, você pode usar a implementação padrão. Se precisar alterar isso (por exemplo, para 8), você sobrescreveria a função sharedDecimals().

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

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

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

Preparando e Implantando o OFT na Solana

Ao contrário da Chiliz Chain, a Solana não usa a Ethereum Virtual Machine (EVM) ou a linguagem Solidity. Os smart contracts da Solana (chamados de "Programs") são escritos em Rust.

Para fazer bridge do seu token, você precisa implantar um programa OFT na Solana. Quando este programa recebe uma mensagem verificada do seu OFTAdapter implantado na Chiliz, ele mintará o token SPL correspondente na carteira Solana do usuário.

Solana OFT - LayerZeroLayerZero Documentation

O LayerZero fornece um exemplo Anchor pronto para uso para que você não precise escrever a lógica de bridge em Rust do zero.

1. Clone o exemplo OFT Solana do LayerZero:

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

2. Compile o programa Rust

Isso também gerará seu Program ID único da Solana (equivalente a um endereço de contrato na EVM):

anchor build

Após a conclusão da compilação, o Anchor gerará um novo par de chaves em target/deploy/oft_solana-keypair.json.\ Você pode recuperar seu novo Program ID executando:

anchor keys list

3. Implante na Solana Mainnet

Certifique-se de que sua CLI Solana esteja configurada para a Mainnet e que sua carteira local tenha SOL suficiente para o deploy e o rent de armazenamento.\ Não se esqueça de atualizar o arquivo Anchor.toml e a macro declare_id! em lib.rs com este novo Program ID antes do deploy.

solana config set --url mainnet-beta
anchor deploy

4. Inicialize o OFT e o SPL Mint

Na Solana, a lógica de um token e seu ledger são separados. Você deve inicializar uma nova Conta Mint (o Token SPL) e atribuir ao seu programa OFT recém-implantado como a Mint Authority. Isso garante que apenas a bridge LayerZero possa mintar novos tokens na Solana.

O SDK LayerZero fornece tarefas Hardhat/TypeScript para lidar com essa inicialização diretamente da linha de comando. No seu projeto oft-solana, configure seu Endpoint LayerZero para Solana (30168) e execute o script de inicialização:

npx hardhat lz:oft-solana:init --program-id <SEU_NOVO_PROGRAM_ID> --mint-decimals 9 --shared-decimals 6

Parâmetros cruciais:

• --mint-decimals 9: Define a precisão padrão do token SPL na Solana.

• --shared-decimals 6: Deve corresponder aos shared decimals que você configurou (ou o padrão) no seu OFTAdapter na Chiliz Chain. Isso é o que garante que 1 token Chiliz = 1 token Solana.

Uma vez que esta transação de inicialização seja confirmada na blockchain Solana, seu programa OFT nativo está totalmente configurado e pronto para ser conectado ao OFTAdapter da Chiliz!

Etapa 2: Configuração do LayerZero

Com o seu Adapter da Chiliz implantado e seu programa OFT da Solana inicializado, você deve agora configurar a conexão entre eles. É aqui que a diferença entre redes EVM e não-EVM se torna muito visível.

Formatação de Endereços:

• Chiliz Chain (EVM): Usa endereços hexadecimais padrão de 20 bytes (ex.: 0x123...).

• Solana: Usa endereços codificados em Base58 (ex.: YourProgramId111111111111111111111111111111).

As mensagens cross-chain do LayerZero exigem que todos os endereços de peer sejam formatados como bytes32. Felizmente, o tooling Hardhat V2 do LayerZero lida automaticamente com a conversão de Base58 para Bytes32, desde que você defina os endpoints corretamente na sua configuração.

O Simple Config Generator é a forma recomendada de gerar a 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: 'ChilizSolanaAdapter', // Nome do deploy Hardhat na EVM
};

const solanaContract: OmniPointHardhat = {
    eid: EndpointId.SOLANA_V2_MAINNET,
    address: 'YourSolanaProgramIdHereInBase58', // Formato de endereço Base58 para Solana
};

// Definir Opções de Execução para Solana (Compute Units e Lamports)
const SOLANA_ENFORCED_OPTIONS: OAppEnforcedOption[] = [
    {
        msgType: 1,
        optionType: ExecutorOptionType.LZ_RECEIVE,
        gas: 200000,    // Compute Units Solana necessários para execução no destino
        value: 2500000, // Lamports para cobrir a possível taxa de criação de ATA
    },
];

// Definir Opções de Execução para o retorno à Chiliz (EVM Gas)
const EVM_ENFORCED_OPTIONS: OAppEnforcedOption[] = [
    {
        msgType: 1, 
        optionType: ExecutorOptionType.LZ_RECEIVE,
        gas: 200000, // Unidades de gas EVM padrão para desbloquear tokens na Chiliz
        value: 0,
    },
];

// Exportar a Configuração Gerada
export default async function () {
    return {
        contracts: [
            { contract: chilizContract },
            { contract: solanaContract },
        ],
        connections: await generateConnectionsConfig([
            [
                chilizContract, 
                solanaContract,
                [['LayerZero Labs'], []], 
                [1, 1], 
                [SOLANA_ENFORCED_OPTIONS, EVM_ENFORCED_OPTIONS], // Opções [Para Solana SVM, Para Chiliz EVM]
            ],
        ]),
    };
}

A tarefa de wire do LayerZero lerá isso, decodificará a string Base58, preencherá para 32 bytes e a passará com segurança para a função setPeer do OFTAdapter da Chiliz.

Etapa 3: Fluxo de Deploy

Com seus contratos escritos e seu layerzero.config.ts preparado, é hora de implantar o OFTAdapter da Chiliz. Como você já compilou e implantou o programa OFT nativo da Solana usando Anchor na Etapa 1, esta etapa se concentra em implantar o lado EVM da bridge usando Hardhat.

Implantando o Contrato OFTAdapter da Chiliz

No seu projeto Hardhat, crie um script de deploy no diretório deploy/ chamado 01_deploy_chiliz_solana_adapter.ts. Este script passa o endereço do seu token existente e o endereço do Endpoint V2 da Chiliz (EID) 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 (18 decimais)
    const TOKEN_ADDRESS = "0xSeuEnderecoDeTokenAqui"; 
    
    // O Endereço do Endpoint V2 da Chiliz Mainnet
    const CHILIZ_ENDPOINT_V2 = "0x6F475642a6e85809B1c36Fa62763669b1b48DD5B";

    console.log("Implantando OFTAdapter na Chiliz Mainnet...");

    await deploy('ChilizSolanaAdapter', {
        from: deployer,
        args: [
            TOKEN_ADDRESS,       // _token
            CHILIZ_ENDPOINT_V2,  // _lzEndpoint
            deployer             // _delegate (Proprietário)
        ],
        log: true,
        waitConfirmations: 2,
    });
};

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

Implantando o OFTAdapter da Chiliz

Antes de prosseguir, certifique-se de que:

• você copiou o Program ID Base58 resultante para o seu arquivo layerzero.config.ts.

• seu hardhat.config.ts tem a URL RPC e a chave privada corretamente configuradas para a Chiliz Chain Mainnet.

Execute o seguinte comando no terminal para implantar o Adapter EVM:

npx hardhat deploy --network chiliz --tags ChilizSolanaAdapter

Após o deploy, o Hardhat salvará o endereço do contrato Chiliz na pasta deployments/.

Neste ponto, você tem contratos ativos na Chiliz Chain (EVM) e na Solana (SVM), mas eles ainda não confiam um no outro. Hora de apresentá-los!

Etapa 4: Wiring e Peering

Para permitir que seu contrato OFTAdapter e programa OFT se comuniquem, você deve "conectá-los" como peers confiáveis.

Como estamos fazendo bridge entre duas Virtual Machines completamente diferentes (EVM e SVM), a configuração requer atenção especial.

Gas EVM vs Compute Units da Solana

Quando um usuário faz bridge de um token da Chiliz Chain para outra cadeia EVM (como Base), o Executor LayerZero precisa de gas EVM para chamar lzReceive.

No entanto, ao fazer bridge da Chiliz Chain para a Solana, a cadeia de destino não usa gas EVM. Ela usa Compute Units e Lamports (frações de $SOL).\ Além disso, se um usuário fizer bridge de tokens para uma carteira Solana que ainda não possua seu token, o Executor deve pagar a taxa de "isenção de rent" da Solana para criar uma Associated Token Account (ATA) para ele. Isso requer depositar valor real em $SOL no destino.

Para garantir que o Executor tenha Compute Units e Lamports suficientes para mintar tokens e criar ATAs na Solana, você deve definir esses limites no arquivo layerzero.config.ts antes do wiring.

Execute o comando de wire automatizado no terminal:

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

Isso preparará as 6 transações de configuração necessárias:

1. setSendLibrary: Atribui a MessageLib para pacotes de saída.

2. setReceiveLibrary: Atribui a MessageLib para pacotes de entrada.

3. setConfig: Configura os DVNs e o Executor.

4. setConfig: Configura os DVNs para verificação de entrada.

5. setEnforcedOptions: Garante parâmetros de execução consistentes (crucial para garantir que o usuário pague antecipadamente o suficiente para cobrir os Compute Units e o rent de Lamport da Solana).

6. setPeer: Vincula o EID da Solana ao seu Program ID Base58 de destino.

O toolbox LayerZero V2 automatiza o trabalho pesado: decodificará o endereço Solana em Base58, preencherá para o formato bytes32 EVM necessário e enviará as transações setPeer e setEnforcedOptions para ambas as cadeias.

Após a confirmação das transações de wiring, sua bridge EVM para Solana estará ativa e com permissões seguras.

Seu token está oficialmente pronto para cruzar a fronteira EVM/SVM!

Etapa 5: Operação e Testes

Com o seu Adapter da Chiliz implantado, o OFT nativo da Solana inicializado e os dois devidamente conectados, seu token está oficialmente pronto para cruzar a fronteira EVM/SVM. A etapa final é executar e monitorar uma transferência de teste da Chiliz Chain para a Solana.

1) Enviando a Mensagem Cross-Chain para a Solana

O toolbox LayerZero V2 inclui uma tarefa Hardhat para enviar transferências OFT diretamente da linha de comando.

Ao contrário das transferências EVM para EVM onde o destino é uma string hexadecimal padrão, seu destino aqui é um endereço de carteira Solana em Base58. A CLI LayerZero lida com a conversão de Base58 para Bytes32 no payload da mensagem automaticamente.

Execute o seguinte comando no terminal:

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

O que acontece aqui?

1. O script cotiza a taxa cross-chain em $CHZ (que cobre o gas EVM, as taxas da rede verificadora e as taxas de destino da Solana).

2. Ele chama a função send() no seu Adapter Chiliz.

3. O Adapter bloqueia 10 tokens (18 decimais). Ele descarta os 12 decimais mais baixos como "dust" (deixando-os na sua carteira Chiliz) para reduzir o payload para os 6 sharedDecimals.

4. O Endpoint LayerZero emite o pacote em direção à Solana Mainnet.

2) Rastreando o Pacote no LayerZero Scan

Como fazer bridge para a Solana envolve a tradução entre dois mecanismos de consenso completamente diferentes e aguardar a finalidade da SVM, um atraso assíncrono é normal.

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

Saiba mais sobre essa ferramenta aqui:

LayerZero Scan - LayerZeroLayerZero Documentation

Tradução de Decimais

O OFT Nativo da Solana terá automaticamente escalado o payload de 6 decimais vindo da bridge para os 9 decimais SPL padrão, de modo que sua carteira Solana receba exatamente 10 tokens completos.

4) Solução de Problemas em Mensagens Travadas

Se sua transação estiver marcada como confirmada na Chiliz, mas falhar na execução da Solana, a causa mais comum é um erro de Lamports insuficientes ou Compute Units insuficientes.

• Se a carteira Solana de destino ainda não tinha uma Associated Token Account (ATA) para o seu token específico, o Executor LayerZero teve que pagar a taxa de "isenção de rent" da Solana para criá-la.

• Se o parâmetro value (Lamports) nas suas enforcedOptions estava muito baixo para cobrir esse rent, ou se o gas (Compute Units) era insuficiente, o Executor se recusará a pagar do próprio bolso e a mensagem ficará parada.

• Solução: Você não perde seus tokens. Você pode empurrar manualmente uma mensagem travada pela UI do LayerZero Scan. Conecte sua carteira Solana, clique no botão "Force Resume" ou "Execute" no block explorer e pague a taxa de destino local (Compute Units + ATA Rent em $SOL) você mesmo para finalizar a mintagem.