Bridge de Solana para Chiliz Chain

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

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

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

LayerZero V2 OFT Quickstart - LayerZeroLayerZero Documentation

Pré-requisitos

Fazer bridge da Solana (não-EVM) para a Chiliz Chain (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 Solana: Rustup (smart contracts da Solana usam a linguagem de programação Rust), Solana CLI e framework Anchor e o SDK Solana do LayerZero.

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

Este guia exige o seguinte:

• O endereço mint do Token SPL existente que você deseja fazer bridge para a Chiliz Chain.

• Uma carteira Web3 para cada cadeia:

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

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

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

  • Na Solana: tokens SOL.

  • Na Chiliz Chain: tokens CHZ.

Etapa 1: Desenvolvimento dos Contratos

O Desafio dos "Decimais Compartilhados"

Como a Ethereum Virtual Machine (EVM) lida com a matemática de tokens de forma diferente da Solana, precisamos alinhar a precisão decimal antes que os tokens cruzem a bridge:

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

• Chiliz Chain (Destino): Tokens ERC-20 padrão (e seu novo OFT de destino) normalmente usam 18 decimais.

Se você enviasse um payload de 9 decimais da Solana diretamente para a Chiliz sem conversão, o contrato EVM interpretaria incorretamente o valor, resultando em uma fração minúscula de um token sendo mintada 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 SPL da Solana, o Adapter Solana reduz o número para 6 decimais (tratando os 3 decimais mais baixos do token SPL como "dust" e deixando-os com segurança na carteira do usuário).

• O payload de mensagem de 6 decimais é enviado pela bridge.

• O OFT Nativo da Chiliz Chain recebe o número de 6 decimais e o escala para cima até seus 18 decimais locais antes de mintar o token ERC-20 na carteira EVM do usuário.

Saiba mais aqui.

Desenvolvimento do Programa Solana

Como seu token já existe na Solana, você não precisa criar um novo contrato de token. Em vez disso, você implantará um Programa OFT Adapter Solana escrito em Rust. Este programa atuará como um cofre descentralizado, mantendo seus tokens SPL com segurança quando os usuários os enviarem para a Chiliz Chain e liberando-os quando os usuários retornarem.

O LayerZero fornece um workspace Anchor com contratos pré-construídos e auditados para que você não precise escrever a lógica Rust do zero.

1. Clonando o SDK Solana do LayerZero

Comece clonando o repositório oficial de ferramentas para desenvolvedores do LayerZero, que contém o exemplo do OFT Adapter Solana.

Abra seu terminal e execute:

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

2. Compilando o Programa Adapter Solana

Este diretório é um workspace Anchor contendo implementações de Native OFT e OFT Adapter. Você precisa compilar o programa Rust para gerar seu Program ID único da Solana.

anchor build

Após a conclusão da compilação, recupere seu novo Program ID executando:

anchor keys list

Você deve atualizar o arquivo Anchor.toml e a macro declare_id! dentro do arquivo programs/oft-adapter/src/lib.rs com o seu novo Program ID antes de fazer o deploy.

3. Implantando na Solana Mainnet

Certifique-se de que sua CLI Solana esteja configurada para a Mainnet e que sua carteira local tenha $SOL suficiente para cobrir o tamanho do deploy e o rent de armazenamento.

solana config set --url mainnet-beta
anchor deploy

4. Inicializando o OFT Adapter

Ao contrário do Native OFT (que exige a criação de um novo Mint), inicializar o Adapter simplesmente vincula o Program ID recém-implantado ao Endereço Mint do seu Token SPL existente.

O SDK LayerZero fornece tarefas Hardhat para lidar com essa inicialização pela linha de comando. Certifique-se de que seu Endpoint LayerZero Solana (30168) esteja configurado e execute:

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

Há parâmetros cruciais aqui:

• --mint: Este deve ser o Endereço Mint Base58 exato do token SPL que você deseja fazer bridge. O Adapter criará uma conta de custódia especificamente para este token.

• --shared-decimals 6: Isso define como o Adapter escala o payload antes de enviá-lo para a EVM. Se o seu token Solana tiver 9 decimais, deixar 6 shared decimals garante que ele seja traduzido com segurança pela bridge sem problemas de overflow.

Após a confirmação desta transação de inicialização na Solana, seu Adapter está ativo e pronto para bloquear com segurança seus tokens SPL!

Desenvolvimento do Contrato Chiliz

Como o seu token SPL Solana ainda não existe na Chiliz Chain, você deve implantar um contrato OFT Nativo padrão. Este contrato atuará como o mintador. Quando receber uma mensagem verificada do seu Adapter Solana, ele mintará os tokens ERC-20 correspondentes; quando um usuário fizer bridge de volta para a Solana, ele os queimará.

Como discutimos no "Desafio dos Decimais Compartilhados", seu Adapter Solana reduz o payload para 6 decimais antes de enviá-lo.

A implementação EVM do LayerZero é tal que você não precisa escrever lógica de escalonamento personalizada. Por padrão, o contrato OFT.sol usa 18 decimais locais e 6 shared decimals. Ele detectará automaticamente o payload de 6 decimais chegando da Solana e o escalará para o formato padrão de 18 decimais () antes de mintar o token ERC-20 na carteira do usuário.

Implantando o OFT na Chiliz Chain

Crie um novo arquivo chamado ChilizNativeOFT.sol na pasta contracts/ do seu projeto Hardhat:

// 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,    // O nome do token (deve corresponder ao seu Token SPL Solana)
        string memory _symbol,  // O símbolo do token (deve corresponder ao seu Token SPL Solana)
        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
    ) OFT(_name, _symbol, _lzEndpoint, _delegate) Ownable(_delegate) {}
}

Não faça o deploy ainda! Mas tenha isso em mente:

• Certifique-se de que os parâmetros _name e _symbol correspondam exatamente ao seu token SPL Solana original para fornecer uma experiência unificada aos usuários.

• Ao implantar na Chiliz Mainnet, você passará o endereço do Endpoint V2 da Chiliz (0x6F475642a6e85809B1c36Fa62763669b1b48DD5B) como _lzEndpoint.

Etapa 2: Configuração do LayerZero

Agora que você tem o Adapter Solana inicializado e o OFT Nativo da Chiliz pronto para deploy, deve configurar a conexão entre eles.

O principal desafio aqui é a formatação de endereços. As mensagens cross-chain do LayerZero exigem que todos os endereços de peer sejam formatados como bytes32. O toolbox Hardhat V2 do LayerZero lida com isso automaticamente decodificando o Program ID Base58 do seu Adapter Solana e preenchendo-o para o formato EVM padrã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 solanaContract: OmniPointHardhat = {
    eid: EndpointId.SOLANA_V2_MAINNET,
    address: 'YourSolanaAdapterProgramIdHereInBase58', 
    // NOTA: Redes não-EVM usam 'address' em vez de 'contractName'
};

const chilizContract: OmniPointHardhat = {
    eid: EndpointId.CHILIZ_V2_MAINNET,
    contractName: 'ChilizNativeOFT', // Nome do deploy Hardhat na EVM
};

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

// Definir Opções de Execução para o retorno à Solana (Compute Units e Lamports)
const SOLANA_ENFORCED_OPTIONS: OAppEnforcedOption[] = [
    {
        msgType: 1, 
        optionType: ExecutorOptionType.LZ_RECEIVE,
        gas: 200000,    // Compute Units Solana para executar o desbloqueio
        value: 2500000, // Lamports para cobrir a taxa de criação de ATA
    },
];

// Exportar a Configuração Gerada
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], // Opções [Para Chiliz EVM, Para Solana SVM]
            ],
        ]),
    };
}

O gerador lida com a conversão automática do seu endereço Solana Base58 para o preenchimento bytes32 EVM exigido pelo smart contract Chiliz.

Etapa 3: Fluxo de Deploy

Neste ponto, seu Adapter Solana já está compilado, implantado e inicializado (conforme descrito na Etapa 1). Agora, você precisa implantar o lado EVM da bridge — o Native OFT — na Chiliz Chain.

Você usará Hardhat para enviar este contrato para a Chiliz Mainnet.

1. O Script de Deploy do OFT Nativo da Chiliz

No seu projeto Hardhat, crie um script de deploy no diretório deploy/ chamado 01_deploy_chiliz_native_oft.ts. Este script inicializará o novo token ERC-20 na Chiliz.

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

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

    // Detalhes do Token (Deve corresponder exatamente ao seu Token SPL Solana existente)
    const TOKEN_NAME = "Meu Token Solana";
    const TOKEN_SYMBOL = "SOLTKN";

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

    console.log("Implantando Native OFT na Chiliz Mainnet...");

    await deploy('ChilizNativeOFT', {
        from: deployer,
        args: [
            TOKEN_NAME,         // _name
            TOKEN_SYMBOL,       // _symbol
            CHILIZ_ENDPOINT_V2, // _lzEndpoint
            deployer            // _delegate (Proprietário)
        ],
        log: true,
        waitConfirmations: 2,
    });
};

export default deployOFT;
deployOFT.tags = ['ChilizNativeOFT'];

2. O Deploy do Programa Solana

Como lembrete rápido, seu Adapter Solana não usa Hardhat para o deploy inicial. Você já deve ter:

1. Executado anchor build e anchor deploy para enviar o programa Rust para a Solana Mainnet.

2. Executado a tarefa lz:oft-adapter-solana:init para vincular seu Adapter ao Mint do seu Token SPL existente.

3. Copiado o Program ID Base58 resultante para o seu arquivo layerzero.config.ts.

3. Executando o Deploy da Chiliz

Certifique-se de que seu arquivo hardhat.config.ts tenha a URL RPC e a chave privada corretamente configuradas para a rede chiliz.

Execute o seguinte comando no terminal para implantar o Native OFT:

npx hardhat deploy --network chiliz --tags ChilizNativeOFT

Após o deploy, o Hardhat salvará o endereço do contrato Chiliz recém-criado na pasta deployments/. Agora você tem contratos ativos na Solana (SVM) e na Chiliz Chain (EVM), mas eles ainda não estão autorizados a se comunicar.

Etapa 4: Wiring e Peering

Neste ponto, você tem um Programa Adapter em Rust na Solana e um OFT EVM Nativo na Chiliz Chain. Para permitir que eles se comuniquem com segurança, você deve "conectá-los" como peers confiáveis.

Assim como fazer bridge na direção oposta, estamos lidando com duas Virtual Machines completamente diferentes (SVM e EVM). Por isso, configurar corretamente as Enforced Options (Limites de Gas) é fundamental para garantir que suas transações não travem na cadeia de destino.

As "Enforced Options" para a Chiliz (EVM)

Quando um usuário faz bridge de seu token SPL da Solana para a Chiliz, o Executor LayerZero precisa de gas EVM para chamar a função lzReceive no seu contrato Chiliz para mintar os tokens ERC-20.

Por outro lado, para o retorno (Chiliz de volta para a Solana), o Executor precisará de Compute Units e Lamports da Solana para desbloquear os tokens SPL e potencialmente pagar o rent de uma Associated Token Account (ATA).

Atualizando a Configuração

Para garantir que o Executor tenha gas suficiente para ambas as direções, você deve definir esses limites no arquivo layerzero.config.ts antes do wiring.

Atualize o array connections no seu arquivo de configuração para incluir os seguintes enforcedOptions:

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

// ... (array contracts da Etapa 3)

    connections: [
        // Caminho 1: Solana -> Chiliz (A rota principal)
        {
            from: 'YourSolanaAdapterProgramIdHereInBase58',
            to: 'ChilizNativeOFT',
            config: {
                enforcedOptions: [
                    {
                        msgType: 1, // Transferência OFT Padrão
                        optionType: ExecutorOptionType.LZ_RECEIVE,
                        gas: 200000, // Gas EVM padrão para mintar tokens na Chiliz
                        value: 0,    // Sem drop nativo necessário na Chiliz EVM
                    }
                ]
            },
        },
        // Caminho 2: Chiliz -> Solana (O retorno)
        {
            from: 'ChilizNativeOFT',
            to: 'YourSolanaAdapterProgramIdHereInBase58',
            config: {
                enforcedOptions: [
                    {
                        msgType: 1, 
                        optionType: ExecutorOptionType.LZ_RECEIVE,
                        gas: 200000,    // Compute Units Solana para o desbloqueio
                        value: 2500000, // Lamports (cobre a taxa de rent da ATA se necessário)
                    }
                ]
            },
        },
    ],
// ...

Executando a Tarefa Wire

Após salvar sua configuração, o toolbox LayerZero V2 automatiza o processo de peering. Ele decodifica o endereço Solana Base58, preenche para o formato bytes32 EVM necessário e envia as transações de configuração tanto para a Solana Mainnet quanto para a Chiliz Mainnet.

Execute o seguinte comando no terminal:

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

A CLI solicitará que você confirme as transações. Ela usará sua carteira Solana configurada para enviar a transação de origem (custando $SOL) e o Hardhat para enviar a transação de destino na Chiliz (custando $CHZ).

No lado da Chiliz, o toolbox Hardhat LayerZero gerará e executará automaticamente 6 transações de configuração necessárias:

1. setSendLibrary: Atribui a MessageLib V2 para envio de mensagens.

2. setReceiveLibrary: Atribui a MessageLib para recebimento de mensagens.

3. setConfig (Send Library): Configura os DVNs e o Executor.

4. setConfig (Receive Library): Configura os DVNs para verificação de entrada.

5. setEnforcedOptions: Garante parâmetros de execução consistentes (especificamente garantindo que Compute Units Solana suficientes sejam pagos para o retorno).

6. setPeer: Vincula criptograficamente o EID da Chiliz ao Program ID Base58 do seu Adapter Solana (convertido para bytes32).

O SDK Solana lida com as instruções programáticas equivalentes para o lado SVM automaticamente.

Após a confirmação de ambas as transações, sua bridge Solana para Chiliz está oficialmente ativa e com permissões seguras!

Etapa 5: Operação e Testes

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

1) Preparando Sua Carteira Solana

Ao contrário da EVM onde você deve executar uma transação approve() separada e anterior para conceder uma allowance a um Adapter, a Solana lida com aprovações e transferências de tokens dentro das mesmas instruções de transação.

No entanto, você deve garantir que sua carteira Solana local (a configurada no seu projeto) realmente contenha um saldo dos tokens SPL que pretende fazer bridge, bem como $SOL suficiente para pagar a taxa de transação de origem e a taxa de mensagem cross-chain do LayerZero.

2) Enviando a Mensagem Cross-Chain para a Chiliz

O toolbox LayerZero V2 inclui uma tarefa Hardhat para enviar transferências OFT diretamente da linha de comando, mesmo quando a cadeia de origem é a Solana.

Ao contrário das transferências Solana para Solana, seu destino aqui é um endereço de carteira EVM hexadecimal padrão (ex.: 0x123...). A CLI LayerZero lida com o preenchimento e a conversão de bytes para o payload automaticamente.

Execute o seguinte comando no terminal:

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

O que acontece aqui?

1. O script cotiza a taxa cross-chain em $SOL.

2. Ele constrói uma transação que transfere 10 tokens SPL da sua carteira para a conta de custódia do Adapter Solana.

3. O Adapter reduz o valor do token SPL de 9 decimais para os 6 shared decimals.

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

3) Rastreando o Pacote no LayerZero Scan

Como fazer bridge da Solana envolve a tradução entre dois mecanismos de consenso completamente diferentes e a finalização da transação na SVM antes da execução na EVM, um atraso assíncrono é normal.

Para rastrear esta 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

O OFT Nativo da Chiliz terá automaticamente escalado o payload de 6 decimais de volta para os 18 decimais padrão da EVM, de modo que você receba exatamente 10 tokens completos.

4) Solução de Problemas em Mensagens Travadas

Se sua transação estiver marcada como confirmada na Solana, mas falhar na execução da Chiliz, a causa mais comum é um erro de Out-of-Gas na EVM.

• Se o parâmetro gas nas suas enforcedOptions (configurado na Etapa 5) estava muito baixo para a rede Chiliz processar a função de mintagem lzReceive, o Executor LayerZero falhará ao entregar a mensagem.

• Solução: Você não perde seus tokens. Você pode empurrar manualmente uma mensagem travada pela UI do LayerZero Scan. Simplesmente conecte sua carteira EVM à Chiliz Chain, clique no botão "Force Resume" ou "Execute" no block explorer e pague a taxa de gas da Chiliz você mesmo para finalizar a mintagem.