Bridge de Chiliz Chain vers Solana

Déployez un OFT Adapter sur Chiliz Chain et un OFT natif sur Solana en utilisant LayerZero v2 pour faire le bridge de tokens de Chiliz Chain vers le réseau Solana.

Pour faire le bridge d'un token existant de Chiliz Chain vers Solana, vous devez écrire et déployer deux smart contracts séparés : un OFT Adapter sur la chaîne où le token existe déjà (Chiliz Chain), et un OFT natif sur la chaîne de destination (Solana).

Notez que LayerZero fournit son propre QuickStart pour les contrats OFT :

LayerZero V2 OFT Quickstart - LayerZeroLayerZero Documentation

Prérequis

Le bridge de Chiliz Chain (EVM) vers Solana (non-EVM) nécessite un développement dual-stack. Vous aurez besoin d'environnements et de portefeuilles configurés pour les deux écosystèmes.

Vous aurez donc besoin des environnements suivants :

• Pour les interactions Chiliz Chain : Node/npx et Hardhat.

• Pour les interactions Solana : Rustup (les smart contracts Solana utilisent le langage de programmation Rust), Solana CLI et le framework Anchor, et le SDK Solana de LayerZero.

Ce guide nécessite les éléments suivants :

• Une adresse de contrat de token sur Chiliz Chain. Vous n'avez pas besoin d'en être le propriétaire.

• Un portefeuille Web3 pour chaque chaîne (MetaMask ne supporte pas les chaînes non-EVM) :

  • Pour Chiliz Chain : portefeuille MetaMask avec la configuration RPC de Chiliz Chain.

  • Pour Solana : portefeuille Solflare avec la configuration Solana Mainnet. Voici leur guide de configuration.

• Suffisamment de tokens gas sur chaque chaîne pour payer les déploiements de contrats ainsi que les frais de gas pour l'envoi des messages.

  • Sur Chiliz Chain : tokens CHZ.

  • Sur Solana : tokens SOL.

Étape 1 : Développement des contrats

Le défi des « Shared Decimals »

Parce que Solana gère les mathématiques des tokens différemment de la Machine Virtuelle Ethereum (EVM), nous devons gérer correctement les décimales :

• Chiliz Chain (EVM) : Les tokens ERC-20 standards ont typiquement 18 décimales de précision.

• Solana : Les SPL Tokens natifs ont typiquement 9 décimales de précision.

Si vous envoyez unités de Chiliz vers Solana, le contrat Solana interpréterait mal le montant, entraînant une inflation massive du token sur la chaîne de destination.

Pour normaliser les calculs, LayerZero utilise une configuration sharedDecimals. Par défaut, le standard OFT V2 de LayerZero définit sharedDecimals à 6.

• Lorsqu'un utilisateur bridge 1,00 token de Chiliz, l'Adapter supprime les 12 décimales les plus basses (en les traitant comme de la « poussière ») pour mettre à l'échelle le nombre à 6 décimales.

• Le message est envoyé via le bridge.

• Le programme Solana reçoit le nombre à 6 décimales et le met à l'échelle vers le haut, vers ses 9 décimales locales, avant de minter.

En savoir plus ici.

Préparer l'OFTAdapter sur Chiliz Chain

Il s'agit d'une étape préparatoire, ne déployez pas tout de suite ! Vous déploierez à l'étape 3.

Le contrat OFTAdapter agit comme un coffre-fort pour votre token existant. Lorsque des utilisateurs bridgent leurs tokens hors de Chiliz Chain, ce contrat verrouille les tokens ERC20 d'origine.

Parce que l'OFTAdapter de LayerZero définit sharedDecimals à 6 par défaut, vous pouvez utiliser l'implémentation standard. Si vous avez un jour besoin de changer cela (par exemple, à 8), vous surchargeriez la fonction sharedDecimals().

Créez un nouveau fichier nommé ChilizTokenAdapter.sol dans votre dossier de contrats :

// 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,      // L'adresse de votre Token EXISTANT sur Chiliz Chain (18 décimales)
        address _lzEndpoint, // L'adresse de l'Endpoint LayerZero V2 sur Chiliz
        address _delegate    // L'adresse capable d'effectuer des changements de configuration ( (généralement votre portefeuille)
    ) OFTAdapter(_token, _lzEndpoint, _delegate) Ownable(_delegate) {}
}

Comme vous pouvez le voir, ce contrat étend le contrat OFT Adapter de LayerZero, ainsi qu'un contrat Ownable.sol standard pour attribuer les clés administratives. Vous avez besoin des deux afin que vous, et vous seul, puissiez câbler les chaînes ensemble en toute sécurité.

Préparer et déployer l'OFT sur Solana

Contrairement à Chiliz Chain, Solana n'utilise pas la Machine Virtuelle Ethereum (EVM) ni le langage Solidity. Les smart contracts Solana (appelés « Programmes ») sont écrits en Rust.

Pour faire le bridge de votre token, vous devez déployer un programme OFT sur Solana. Lorsque ce programme reçoit un message vérifié de votre OFTAdapter déployé sur Chiliz, il mintera le SPL token correspondant dans le portefeuille Solana de l'utilisateur.

Solana OFT - LayerZeroLayerZero Documentation

LayerZero fournit un exemple Anchor prêt à l'emploi afin que vous n'ayez pas à écrire la logique du bridge Rust à partir de zéro.

1. Cloner l'exemple OFT Solana LayerZero :

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

2. Compiler le programme Rust

Cela générera également votre Program ID Solana unique (équivalent à une adresse de contrat dans l'EVM) :

anchor build

Une fois la compilation terminée, Anchor générera une nouvelle keypair dans target/deploy/oft_solana-keypair.json. Vous pouvez récupérer votre nouveau Program ID en exécutant :

anchor keys list

3. Déployer sur Solana Mainnet

Assurez-vous que votre Solana CLI est configuré pour le Mainnet et que votre portefeuille local dispose de suffisamment de $SOL pour le déploiement et le rent de stockage. N'oubliez pas de mettre à jour le fichier Anchor.toml et la macro declare_id! dans lib.rs avec ce nouveau Program ID avant de déployer.

solana config set --url mainnet-beta
anchor deploy

4. Initialiser l'OFT et le SPL Mint

Sur Solana, la logique d'un token et son ledger sont séparés. Vous devez initialiser un nouveau Mint Account (le SPL Token) et assigner votre programme OFT nouvellement déployé comme Mint Authority. Cela garantit que seul le bridge LayerZero peut minter de nouveaux tokens sur Solana.

Le SDK LayerZero fournit des tâches Hardhat/TypeScript pour gérer cette initialisation directement depuis la ligne de commande. Dans votre projet oft-solana, configurez votre Endpoint LayerZero pour Solana (30168) et exécutez le script d'initialisation :

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

Paramètres cruciaux :

• --mint-decimals 9 : Définit la précision standard du SPL token sur Solana.

• --shared-decimals 6 : Doit correspondre aux décimales partagées que vous avez configurées (ou la valeur par défaut) sur votre OFTAdapter Chiliz Chain. C'est ce qui garantit que 1 token Chiliz = 1 token Solana.

Une fois cette transaction d'initialisation confirmée sur la blockchain Solana, votre programme OFT natif est entièrement configuré et prêt à être câblé à l'OFTAdapter Chiliz !

Étape 2 : Configuration LayerZero

Avec votre Adapter Chiliz déployé et votre programme OFT Solana initialisé, vous devez maintenant configurer leur connexion. C'est ici que la différence entre les réseaux EVM et non-EVM devient très visible.

Formatage des adresses :

• Chiliz Chain (EVM) : Utilise des adresses hexadécimales standard de 20 octets (par exemple, 0x123...).

• Solana : Utilise des adresses encodées en Base58 (par exemple, YourProgramId111111111111111111111111111111).

La messagerie cross-chain de LayerZero nécessite que toutes les adresses de peer soient formatées en bytes32. Heureusement, l'outillage Hardhat de LayerZero V2 gère automatiquement la conversion Base58-vers-Bytes32 pour vous, tant que vous définissez correctement les endpoints dans votre configuration.

Le Simple Config Generator est la méthode recommandée pour générer la configuration de câblage, car il automatise le câblage bidirectionnel et applique les configurations de sécurité recommandées en arrière-plan.

Créez ou mettez à jour votre fichier layerzero.config.ts à la racine de votre projet 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';

// Définir les Contrats
const chilizContract: OmniPointHardhat = {
    eid: EndpointId.CHILIZ_V2_MAINNET,
    contractName: 'ChilizSolanaAdapter', // Votre nom de déploiement Hardhat sur EVM
};

const solanaContract: OmniPointHardhat = {
    eid: EndpointId.SOLANA_V2_MAINNET,
    address: 'YourSolanaProgramIdHereInBase58', // Format d'adresse Base58 pour Solana
};

// Définir les Options d'Exécution pour Solana (Compute Units & Lamports)
const SOLANA_ENFORCED_OPTIONS: OAppEnforcedOption[] = [
    {
        msgType: 1,
        optionType: ExecutorOptionType.LZ_RECEIVE,
        gas: 200000,    // Compute Units Solana nécessaires à l'exécution sur la destination
        value: 2500000, // Lamports pour couvrir les frais de rent de création d'ATA potentiels
    },
];

// Définir les Options d'Exécution pour le voyage retour vers Chiliz (Gas EVM)
const EVM_ENFORCED_OPTIONS: OAppEnforcedOption[] = [
    {
        msgType: 1, 
        optionType: ExecutorOptionType.LZ_RECEIVE,
        gas: 200000, // Unités de gas EVM standard pour déverrouiller les tokens sur Chiliz
        value: 0,
    },
];

// Exporter la Configuration Générée
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], // Options [Vers Solana SVM, Vers Chiliz EVM]
            ],
        ]),
    };
}

La tâche wire de LayerZero lira ceci, décodera la chaîne Base58, la complétera à 32 octets, et la transmettra de façon sécurisée à la fonction setPeer de l'OFTAdapter Chiliz.

Étape 3 : Workflow de déploiement

Avec vos contrats écrits et votre layerzero.config.ts préparé, il est temps de déployer l'OFTAdapter Chiliz. Puisque vous avez déjà compilé et déployé le programme OFT natif Solana avec Anchor à l'étape 1, cette étape se concentre sur le déploiement du côté EVM du bridge à l'aide de Hardhat.

Déployer le contrat OFTAdapter Chiliz

Dans votre projet Hardhat, créez un script de déploiement dans votre répertoire deploy/ nommé 01_deploy_chiliz_solana_adapter.ts. Ce script transmet l'adresse de votre token existant et l'adresse de l'Endpoint V2 Chiliz (EID) au constructeur.

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

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

    // L'adresse de votre token ERC-20 existant sur Chiliz (18 décimales)
    const TOKEN_ADDRESS = "0xYourTokenAddressHere"; 
    
    // L'adresse de l'Endpoint V2 du Mainnet Chiliz
    const CHILIZ_ENDPOINT_V2 = "0x6F475642a6e85809B1c36Fa62763669b1b48DD5B";

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

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

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

Déployer l'OFTAdapter Chiliz

Avant de procéder, assurez-vous que :

• vous avez copié le Program ID Base58 résultant dans votre fichier layerzero.config.ts.

• votre hardhat.config.ts a l'URL RPC et la clé privée correctement configurées pour le Mainnet de Chiliz Chain.

Exécutez la commande suivante dans votre terminal pour déployer l'Adapter EVM :

npx hardhat deploy --network chiliz --tags ChilizSolanaAdapter

Une fois le déploiement terminé, Hardhat enregistrera l'adresse du contrat Chiliz dans le dossier deployments/.

À ce stade, vous avez des contrats actifs à la fois sur Chiliz Chain (EVM) et Solana (SVM), mais ils ne se font pas encore confiance. Il est temps de les faire se rencontrer !

Étape 4 : Câblage et peering

Pour permettre à votre contrat OFTAdapter et à votre programme OFT de communiquer, vous devez les « câbler » ensemble en tant que peers de confiance.

Parce que nous faisons un bridge entre deux Machines Virtuelles entièrement différentes (EVM et SVM), la configuration requiert une attention particulière.

Gas EVM vs Compute Units Solana

Lorsqu'un utilisateur bridge un token de Chiliz Chain vers une autre chaîne EVM (comme Base), l'Executor LayerZero a besoin de gas EVM pour appeler lzReceive.

Cependant, lors d'un bridge de Chiliz Chain vers Solana, la chaîne cible n'utilise pas de gas EVM. Elle utilise des Compute Units et des Lamports (fractions de $SOL). De plus, si un utilisateur bridge des tokens vers un portefeuille Solana qui ne détient pas encore votre token, l'Executor doit payer les frais de « rent exemption » de Solana pour créer un Associated Token Account (ATA) pour lui. Cela nécessite de déposer une valeur réelle en $SOL sur la destination.

Pour garantir que l'Executor dispose de suffisamment de Compute Units et de Lamports pour minter des tokens et créer des ATA sur Solana, vous devez définir ces limites dans votre fichier layerzero.config.ts avant le câblage.

Exécutez la commande de câblage automatisée dans votre terminal :

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

Cela préparera les 6 transactions de configuration requises :

1. setSendLibrary : Assigne la MessageLib pour les paquets sortants.

2. setReceiveLibrary : Assigne la MessageLib pour les paquets entrants.

3. setConfig : Configure les DVN et l'Executor.

4. setConfig : Configure les DVN pour la vérification entrante.

5. setEnforcedOptions : Garantit des paramètres d'exécution cohérents (crucial pour s'assurer que l'utilisateur paie suffisamment d'avance pour couvrir les Compute Units et le rent de Lamports de Solana).

6. setPeer : Lie l'EID Solana à votre Program ID Base58 de destination.

La boîte à outils V2 de LayerZero automatise le travail difficile : elle décodera l'adresse Solana Base58, la complétera au format EVM bytes32 requis, et soumettra les transactions setPeer et setEnforcedOptions aux deux chaînes.

Une fois les transactions de câblage confirmées, votre bridge EVM-vers-Solana est actif et permissionné en toute sécurité.

Votre token est officiellement prêt à franchir la frontière EVM/SVM !

Étape 5 : Opération et tests

Avec votre Adapter Chiliz déployé, votre OFT natif Solana initialisé, et les deux correctement câblés ensemble, votre token est officiellement prêt à franchir la frontière EVM/SVM. La dernière étape consiste à exécuter et suivre un transfert de test de Chiliz Chain vers Solana.

1) Envoyer le message cross-chain vers Solana

La boîte à outils V2 de LayerZero inclut une tâche Hardhat pour envoyer des transferts OFT directement depuis la ligne de commande.

Contrairement aux transferts EVM-vers-EVM où votre destination est une chaîne hexadécimale standard, votre destination ici est une adresse de portefeuille Solana Base58. La CLI LayerZero gère automatiquement la conversion Base58-vers-Bytes32 pour le payload du message.

Exécutez la commande suivante dans votre terminal :

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

Que se passe-t-il ici ?

1. Le script estime les frais cross-chain en $CHZ (qui couvrent le gas EVM, les frais du réseau de vérificateurs, et les frais de destination Solana).

2. Il appelle la fonction send() sur votre Adapter Chiliz.

3. L'Adapter verrouille 10 tokens (18 décimales). Il supprime les 12 décimales les plus basses comme « poussière » (en les laissant dans votre portefeuille Chiliz) pour mettre le payload à l'échelle des 6 sharedDecimals.

4. L'Endpoint LayerZero émet le paquet vers le Mainnet Solana.

2) Suivre le paquet sur LayerZero Scan

Parce que le bridge vers Solana implique une traduction entre deux mécanismes de consensus entièrement différents et l'attente de la finalité SVM, un délai asynchrone est normal.

Pour suivre ce parcours en temps réel, cliquez sur le lien LayerZero Scan qui apparaît dans la sortie CLI.

En savoir plus sur cet outil ici :

LayerZero Scan - LayerZeroLayerZero Documentation

Traduction décimale

L'OFT natif Solana aura automatiquement mis à l'échelle vers le haut le payload à 6 décimales venant du bridge vers les 9 décimales SPL standard, donc votre portefeuille Solana reçoit exactement 10 tokens complets.

4) Résoudre les messages bloqués

Si votre transaction est marquée comme confirmée sur Chiliz mais échoue à s'exécuter sur Solana, la cause la plus courante est une erreur de Lamports insuffisants, ou de Compute Units.

• Si le portefeuille Solana de destination ne possédait pas déjà d'Associated Token Account (ATA) pour votre token spécifique, l'Executor LayerZero a dû payer les frais de « rent exemption » de Solana pour le créer.

• Si le paramètre value (Lamports) dans vos enforcedOptions était défini trop bas pour couvrir ce rent, ou si le gas (Compute Units) était insuffisant, l'Executor refusera de payer de sa poche, et le message restera bloqué.

• Fix : Vous ne perdez pas vos tokens. Vous pouvez pousser manuellement un message bloqué via l'interface LayerZero Scan. Connectez votre portefeuille Solana, cliquez sur le bouton « Force Resume » ou « Execute » sur l'explorateur de blocs, et payez vous-même les frais de destination locaux (Compute Units + Rent ATA en $SOL) pour finaliser le minting.