Bridge de Solana vers Chiliz Chain

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

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

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

LayerZero V2 OFT Quickstart - LayerZeroLayerZero Documentation

Prérequis

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

Vous aurez donc besoin des environnements suivants :

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

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

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

• L'adresse mint du SPL Token existant dont vous souhaitez faire le bridge vers Chiliz Chain.

• Un wallet Web3 pour chaque chaîne :

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

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

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

  • Sur Solana : des tokens SOL.

  • Sur Chiliz Chain : des tokens CHZ.

Étape 1 : Développement des contrats

Le défi des « Shared Decimals »

Parce que l'Ethereum Virtual Machine (EVM) gère les mathématiques des tokens différemment de Solana, nous devons aligner leur précision décimale avant que les tokens ne traversent le bridge :

• Solana (Source) : les SPL Tokens natifs ont typiquement une précision de 9 décimales.

• Chiliz Chain (Destination) : les tokens ERC-20 standards (et votre nouvel OFT de destination) utilisent typiquement 18 décimales.

Si vous envoyiez un payload à 9 décimales depuis Solana directement vers Chiliz sans conversion, le contrat EVM interpréterait mal le montant, ce qui aboutirait au mint d'une fraction microscopique d'un token sur la chaîne de destination.

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

• Lorsqu'un utilisateur fait le bridge de 1,00 SPL token depuis Solana, l'Adapter Solana réduit le nombre à 6 décimales (traitant les 3 décimales les plus basses du SPL token comme de la « poussière » et les laissant en sécurité dans le wallet de l'utilisateur).

• Le payload de message à 6 décimales est envoyé à travers le bridge.

• Le Native OFT Chiliz Chain reçoit le nombre à 6 décimales et le met à l'échelle vers le haut à ses 18 décimales locales avant de minter le token ERC-20 dans le wallet EVM de l'utilisateur.

En savoir plus ici.

Développement du programme Solana

Parce que votre token existe déjà sur Solana, vous n'avez pas besoin de créer un nouveau contrat de token. Au lieu de cela, vous déploierez un Solana OFT Adapter Program écrit en Rust. Ce programme agira comme un coffre-fort décentralisé, conservant en sécurité vos SPL tokens lorsque les utilisateurs en font le bridge vers Chiliz Chain, et les libérant lorsque les utilisateurs font le bridge en sens inverse.

LayerZero fournit un workspace Anchor avec des contrats pré-construits et audités, afin que vous n'ayez pas à écrire la logique Rust à partir de zéro.

1. Cloner le SDK Solana de LayerZero

Commencez par cloner le dépôt officiel d'outils pour développeurs de LayerZero, qui contient l'exemple de Solana OFT Adapter.

Ouvrez votre terminal et exécutez :

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

2. Compiler le programme Solana Adapter

Ce répertoire est un workspace Anchor contenant à la fois les implémentations Native OFT et OFT Adapter. Vous devez compiler le programme Rust pour générer votre Solana Program ID unique.

anchor build

Une fois la compilation terminée, récupérez votre nouveau Program ID en exécutant :

anchor keys list

Vous devez mettre à jour le fichier Anchor.toml et la macro declare_id! dans le fichier programs/oft-adapter/src/lib.rs avec votre nouveau Program ID avant de déployer.

3. Déployer sur Solana Mainnet

Assurez-vous que votre Solana CLI est configuré pour Mainnet et que votre wallet local dispose de suffisamment de $SOL pour couvrir la taille du déploiement et le storage rent.

solana config set --url mainnet-beta
anchor deploy

4. Initialiser l'OFT Adapter

Contrairement au Native OFT (qui nécessite la création d'un nouveau Mint), l'initialisation de l'Adapter relie simplement votre Program ID nouvellement déployé à votre adresse Mint de SPL Token existante.

Le SDK LayerZero fournit des tâches Hardhat pour gérer cette initialisation depuis la ligne de commande. Assurez-vous que votre Solana LayerZero Endpoint (30168) est configuré, puis exécutez :

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

Voici des paramètres cruciaux :

• --mint : ce doit être l'adresse Mint Base58 exacte du SPL token dont vous voulez faire le bridge. L'Adapter créera un compte d'entiercement spécifiquement pour ce token.

• --shared-decimals 6 : ceci dicte la manière dont l'Adapter met à l'échelle le payload avant de l'envoyer à l'EVM. Si votre token Solana a 9 décimales, laisser 6 shared decimals ici garantit qu'il se traduit en toute sécurité à travers le bridge sans problème de dépassement.

Une fois cette transaction d'initialisation confirmée sur Solana, votre Adapter est en ligne et prêt à verrouiller en toute sécurité vos SPL tokens !

Développement du contrat Chiliz

Parce que votre SPL token Solana n'existe pas encore sur Chiliz Chain, vous devez déployer un contrat OFT natif standard. Ce contrat agira comme le minter. Lorsqu'il reçoit un message vérifié de votre Adapter Solana, il mintera les tokens ERC-20 correspondants ; lorsqu'un utilisateur fait le bridge en sens inverse vers Solana, il les brûlera.

Comme nous l'avons abordé dans « Le défi des Shared Decimals », votre Adapter Solana met à l'échelle le payload vers le bas à 6 décimales avant de l'envoyer.

L'implémentation EVM de LayerZero est telle que vous n'avez pas besoin d'écrire de logique de mise à l'échelle personnalisée. Par défaut, le contrat OFT.sol utilise 18 décimales locales et 6 shared decimals. Il détectera automatiquement le payload à 6 décimales arrivant de Solana et le mettra à l'échelle vers le haut au format standard de 18 décimales () avant de minter le token ERC-20 dans le wallet de l'utilisateur.

Déployer l'OFT sur Chiliz Chain

Créez un nouveau fichier nommé ChilizNativeOFT.sol dans le dossier contracts/ de votre projet 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,    // The name of the token (Should match your Solana SPL Token)
        string memory _symbol,  // The symbol of the token (Should match your Solana SPL Token)
        address _lzEndpoint,    // The LayerZero V2 Endpoint address on Chiliz
        address _delegate       // The address capable of making configuration changes
    ) OFT(_name, _symbol, _lzEndpoint, _delegate) Ownable(_delegate) {}
}

Ne déployez pas encore ! Mais gardez ceci à l'esprit :

• Assurez-vous que les paramètres _name et _symbol correspondent exactement à votre SPL token Solana d'origine afin d'offrir une expérience unifiée à vos utilisateurs.

• Lors du déploiement sur Chiliz Mainnet, vous passerez l'adresse Chiliz Endpoint V2 (0x6F475642a6e85809B1c36Fa62763669b1b48DD5B) comme _lzEndpoint.

Étape 2 : Configuration LayerZero

Maintenant que votre Adapter Solana est initialisé et que votre Native OFT Chiliz est prêt à être déployé, vous devez configurer la connexion entre eux.

Le principal défi ici est le formatage des adresses. La messagerie cross-chain de LayerZero nécessite que toutes les adresses des peers soient formatées en bytes32. La toolbox Hardhat LayerZero V2 gère cela automatiquement en décodant votre Solana Adapter Program ID Base58 et en le complétant au format EVM standard.

Le Simple Config Generator est la méthode recommandée pour générer la configuration de wiring, car il automatise le wiring bidirectionnel et applique les configurations de sécurité recommandées en coulisses.

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';

// Define the Contracts
const solanaContract: OmniPointHardhat = {
    eid: EndpointId.SOLANA_V2_MAINNET,
    address: 'YourSolanaAdapterProgramIdHereInBase58', 
    // NOTE: Non-EVMs use 'address' instead of 'contractName'
};

const chilizContract: OmniPointHardhat = {
    eid: EndpointId.CHILIZ_V2_MAINNET,
    contractName: 'ChilizNativeOFT', // Your Hardhat deployment name on EVM
};

// Define Execution Options for Chiliz (EVM Gas)
const EVM_ENFORCED_OPTIONS: OAppEnforcedOption[] = [
    {
        msgType: 1, 
        optionType: ExecutorOptionType.LZ_RECEIVE,
        gas: 200000, // Standard EVM gas units to mint tokens on Chiliz
        value: 0,
    },
];

// Define Execution Options for the return trip to Solana (Compute Units & Lamports)
const SOLANA_ENFORCED_OPTIONS: OAppEnforcedOption[] = [
    {
        msgType: 1, 
        optionType: ExecutorOptionType.LZ_RECEIVE,
        gas: 200000,    // Solana Compute Units to execute the unlock
        value: 2500000, // Lamports to cover the ATA creation rent fee
    },
];

// Export the Generated Configuration
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], // Options [To Chiliz EVM, To Solana SVM]
            ],
        ]),
    };
}

Le générateur gère la conversion automatique de votre adresse Solana Base58 en padding bytes32 EVM requis par le smart contract Chiliz.

Étape 3 : Workflow de déploiement

À ce stade, votre Adapter Solana est déjà compilé, déployé et initialisé (comme couvert à l'Étape 1). Maintenant, vous devez déployer le côté EVM du bridge — le Native OFT — sur Chiliz Chain.

Vous utiliserez Hardhat pour pousser ce contrat vers Chiliz Mainnet.

1. Le script de déploiement du Native OFT Chiliz

Dans votre projet Hardhat, créez un script de déploiement dans votre répertoire deploy/ nommé 01_deploy_chiliz_native_oft.ts. Ce script initialisera le nouveau token ERC-20 sur Chiliz.

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

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

    // Token Details (Must strictly match your existing Solana SPL Token)
    const TOKEN_NAME = "My Solana Token";
    const TOKEN_SYMBOL = "SOLTKN";

    // The Chiliz Mainnet Endpoint V2 Address
    const CHILIZ_ENDPOINT_V2 = "0x6F475642a6e85809B1c36Fa62763669b1b48DD5B";

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

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

2. Le déploiement du programme Solana

Pour rappel rapide, votre Adapter Solana n'utilise pas Hardhat pour son déploiement initial. Vous devriez déjà avoir :

1. Exécuté anchor build et anchor deploy pour pousser le programme Rust vers Solana Mainnet.

2. Exécuté la tâche lz:oft-adapter-solana:init pour relier votre Adapter à votre Mint de SPL Token existant.

3. Copié le Program ID Base58 résultant dans votre fichier layerzero.config.ts.

3. Exécuter le déploiement Chiliz

Assurez-vous que votre fichier hardhat.config.ts a l'URL RPC et la clé privée correctement configurées pour le réseau chiliz.

Exécutez la commande suivante dans votre terminal pour déployer le Native OFT :

npx hardhat deploy --network chiliz --tags ChilizNativeOFT

Une fois le déploiement terminé, Hardhat enregistrera l'adresse du contrat Chiliz nouvellement créé dans le dossier deployments/. Vous avez désormais des contrats en ligne à la fois sur Solana (SVM) et sur Chiliz Chain (EVM), mais ils ne sont pas encore autorisés à communiquer entre eux.

Étape 4 : Wiring et peering

À ce stade, vous avez un Rust Adapter Program sur Solana et un Native EVM OFT sur Chiliz Chain. Pour leur permettre de communiquer en toute sécurité, vous devez les « wirer » ensemble en tant que peers de confiance.

Tout comme pour le bridge dans le sens inverse, nous avons affaire à deux Virtual Machines complètement différentes (SVM et EVM). De ce fait, configurer correctement les Enforced Options (Gas Limits) est essentiel pour garantir que vos transactions ne restent pas bloquées sur la chaîne de destination.

Les « Enforced Options » pour Chiliz (EVM)

Lorsqu'un utilisateur fait le bridge de son SPL token de Solana vers Chiliz, le LayerZero Executor a besoin de gas EVM pour appeler la fonction lzReceive sur votre contrat Chiliz afin de minter les tokens ERC-20.

Inversement, pour le voyage retour (de Chiliz vers Solana), l'Executor aura besoin de Solana Compute Units et de Lamports pour déverrouiller les SPL tokens et potentiellement payer le rent d'un Associated Token Account (ATA).

Mettre à jour la configuration

Pour garantir que l'Executor dispose de suffisamment de gas dans les deux directions, vous devez définir ces limites dans votre fichier layerzero.config.ts avant le wiring.

Mettez à jour le tableau connections dans votre fichier de configuration pour inclure les enforcedOptions suivants :

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

// ... (contracts array from Step 3)

    connections: [
        // Pathway 1: Solana -> Chiliz (The primary route)
        {
            from: 'YourSolanaAdapterProgramIdHereInBase58',
            to: 'ChilizNativeOFT',
            config: {
                enforcedOptions: [
                    {
                        msgType: 1, // Standard OFT Transfer
                        optionType: ExecutorOptionType.LZ_RECEIVE,
                        gas: 200000, // Standard EVM Gas to mint tokens on Chiliz
                        value: 0,    // No native drop needed on Chiliz EVM
                    }
                ]
            },
        },
        // Pathway 2: Chiliz -> Solana (The return trip)
        {
            from: 'ChilizNativeOFT',
            to: 'YourSolanaAdapterProgramIdHereInBase58',
            config: {
                enforcedOptions: [
                    {
                        msgType: 1, 
                        optionType: ExecutorOptionType.LZ_RECEIVE,
                        gas: 200000,    // Solana Compute Units for the unlock
                        value: 2500000, // Lamports (covers the ATA rent fee if needed)
                    }
                ]
            },
        },
    ],
// ...

Exécuter la tâche de wiring

Une fois votre configuration sauvegardée, la toolbox LayerZero V2 automatise le processus de peering. Elle décode votre adresse Solana Base58, la complète au format EVM bytes32 requis, et soumet les transactions de configuration à la fois sur Solana Mainnet et sur Chiliz Mainnet.

Exécutez la commande suivante dans votre terminal :

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

Le CLI vous demandera de confirmer les transactions. Il utilisera votre wallet Solana configuré pour soumettre la transaction source (coûtant $SOL) et Hardhat pour soumettre la transaction de destination Chiliz (coûtant $CHZ).

Du côté Chiliz, la toolbox Hardhat LayerZero générera et exécutera automatiquement 6 transactions de configuration requises :

1. setSendLibrary : assigne la V2 MessageLib pour l'envoi des messages.

2. setReceiveLibrary : assigne la MessageLib pour la réception des messages.

3. setConfig (Send Library) : configure les DVN et l'Executor.

4. setConfig (Receive Library) : configure les DVN pour la vérification entrante.

5. setEnforcedOptions : garantit des paramètres d'exécution cohérents (en s'assurant spécifiquement que suffisamment de Solana Compute Units sont payés pour le voyage retour).

6. setPeer : relie cryptographiquement l'EID Chiliz au Program ID Base58 de votre Adapter Solana (converti en bytes32).

Le SDK Solana gère en coulisses les instructions programmatiques équivalentes pour le côté SVM.

Une fois les deux transactions confirmées, votre bridge Solana-vers-Chiliz est officiellement en ligne et sécurisé par les permissions !

Étape 5 : Opération et tests

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

1) Préparer votre wallet Solana

Contrairement à l'EVM où vous devez exécuter une transaction approve() distincte et préalable pour accorder une allowance à un Adapter, Solana gère les approbations et les transferts de tokens dans les mêmes instructions de transaction.

Cependant, vous devez vous assurer que votre wallet Solana local (celui configuré dans votre projet) détient bien un solde des SPL tokens dont vous avez l'intention de faire le bridge, ainsi que suffisamment de $SOL pour payer les frais de la transaction source et les frais de message cross-chain de LayerZero.

2) Envoyer le message cross-chain vers Chiliz

La toolbox LayerZero V2 inclut une tâche Hardhat pour envoyer des transferts OFT directement depuis la ligne de commande, même lorsque la chaîne source est Solana.

Contrairement aux transferts Solana-vers-Solana, votre destination ici est une adresse de wallet EVM hexadécimale standard (par exemple, 0x123...). Le CLI LayerZero gère automatiquement le padding et la conversion en bytes pour le payload.

Exécutez la commande suivante dans votre terminal :

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

Que se passe-t-il ici ?

1. Le script estime les frais cross-chain en $SOL.

2. Il construit une transaction qui transfère 10 SPL tokens depuis votre wallet vers le compte d'entiercement de l'Adapter Solana.

3. L'Adapter réduit le montant du SPL token de 9 décimales aux 6 shared decimals.

4. Le LayerZero Endpoint émet le paquet vers Chiliz Mainnet.

3) Suivre le paquet sur LayerZero Scan

Parce que faire le bridge depuis Solana implique de traduire entre deux mécanismes de consensus entièrement différents et de finaliser la transaction sur le SVM avant de l'exécuter sur l'EVM, 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 du CLI.

Apprenez-en davantage sur cet outil ici :

LayerZero Scan - LayerZeroLayerZero Documentation

Le Native OFT Chiliz aura automatiquement remis à l'échelle le payload à 6 décimales vers les 18 décimales standard de l'EVM, donc vous recevez exactement 10 tokens complets

4) Résoudre les messages bloqués

Si votre transaction est marquée comme confirmée sur Solana mais échoue à s'exécuter sur Chiliz, la cause la plus courante est une erreur EVM Out-of-Gas.

• Si le paramètre gas de vos enforcedOptions (configuré à l'Étape 5) était défini trop bas pour que le réseau Chiliz puisse traiter la fonction de mint lzReceive, le LayerZero Executor échouera à délivrer le message.

• Solution : vous ne perdez pas vos tokens. Vous pouvez pousser manuellement un message bloqué via l'interface LayerZero Scan. Connectez simplement votre wallet EVM à Chiliz Chain, cliquez sur le bouton « Force Resume » ou « Execute » sur l'explorateur de blocs, et payez vous-même les frais de gas Chiliz pour finaliser le mint.