Bridge de Chiliz Chain vers Base

Déployez un OFT Adapter sur Chiliz Chain et un OFT natif sur Base en utilisant LayerZero v2 pour rendre un token Chiliz Chain omnichain sur Base.

Pour faire le bridge d'un token existant de Chiliz Chain vers Base, 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 (Base).

Notez que LayerZero fournit leur propre QuickStart pour les contrats OFT, ainsi qu'un tutoriel pour apprendre comment minter de Chiliz Chain vers une autre chaîne EVM comme Base. Ce tutoriel utilise Optimism comme chaîne cible, mais vous pouvez le remplacer par les détails de Base.

Prérequis

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

• Une adresse de contrat ERC-20 sur Chiliz Chain.

• Un portefeuille Web3 (comme MetaMask) configuré pour fonctionner avec Chiliz Chain et Base.

  • Voir ici pour la configuration RPC de Chiliz Chain.

  • Voir ici pour la configuration RPC du Mainnet Base.

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

  • Sur Chiliz Chain : tokens CHZ.

  • Sur Base : tokens ETH.

Nous utiliserons Hardhat comme environnement de développement, et Node/npx.

Étape 1 : Développement des contrats

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 les utilisateurs font le bridge de leurs tokens en dehors de Chiliz Chain, ce contrat verrouille les tokens ERC-20 originaux.

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 ChilizTokenAdapter is OFTAdapter {
    constructor(
        address _token,      // L'adresse de votre Token EXISTANT sur Chiliz Chain
        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 LayerZero OFT Adapter, ainsi qu'un contrat standard Ownable.sol pour donner les clés administratives. Vous avez besoin des deux afin que vous, et vous seul, puissiez connecter les chaînes en toute sécurité.

Lors du déploiement sur le Mainnet de Chiliz Chain, vous devez passer l'adresse du contrat de votre token existant comme _token et l'adresse Chiliz Endpoint V2 (0x6F475642a6e85809B1c36Fa62763669b1b48DD5B) comme _lzEndpoint.

Voir tous les endpoints disponibles pour Chiliz Chain ici :

Chiliz Mainnet - LayerZeroLayerZero Documentation

Préparer l'OFT sur Base

Étant donné que le token n'existe pas encore nativement sur Base, vous devez déployer un contrat OFT standard. Ce contrat a l'autorité de minter de nouveaux tokens lorsqu'il reçoit un message valide de l'OFT Adapter déployé sur Chiliz, et de les brûler lorsque les utilisateurs font le bridge en retour.

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

// 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 BaseTokenOFT is OFT {
    constructor(
        string memory _name,   // Le nom du token (doit correspondre à votre token Chiliz)
        string memory _symbol, // Le symbole du token (doit correspondre à votre token Chiliz)
        address _lzEndpoint,   // L'adresse de l'Endpoint LayerZero V2 sur Base
        address _delegate      // L'adresse capable d'effectuer des changements de configuration
    ) OFT(_name, _symbol, _lzEndpoint, _delegate) Ownable(_delegate) {}
}

Comme vous pouvez le voir, ce contrat étend le contrat LayerZero OFT ainsi qu'un contrat standard Ownable.sol, pour les mêmes raisons citées ci-dessus.

Lors du déploiement sur Base, assurez-vous que le _name et le _symbol correspondent à votre token original sur Chiliz Chain pour éviter de confondre les utilisateurs. Passez l'adresse Base Endpoint V2 (0x1a44076050125825900e736c501f859c50fE728c) comme _lzEndpoint.

Voir tous les endpoints disponibles pour Base ici :

Base Mainnet - LayerZeroLayerZero Documentation

Étape 2 : Configuration LayerZero

Une fois vos contrats prêts, vous devez indiquer aux outils LayerZero comment ils se connectent. Cela se fait en utilisant un fichier layerzero.config.ts situé à la racine de votre projet Hardhat.

Ce fichier de configuration sert de schéma pour votre architecture cross-chain. Il mappe vos smart contracts déployés à leurs Endpoint IDs (EIDs) LayerZero respectifs et définit les chemins (connexions) entre eux.

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

// Définir les contrats
const chilizContract: OmniPointHardhat = {
    eid: EndpointId.CHILIZ_V2_MAINNET,
    contractName: 'ChilizTokenAdapter',
};

const baseContract: OmniPointHardhat = {
    eid: EndpointId.BASE_V2_MAINNET,
    contractName: 'BaseFanTokenOFT',
};

// Définir les limites de gas EVM standards (Enforced Options)
const EVM_ENFORCED_OPTIONS: OAppEnforcedOption[] = [
    {
        msgType: 1,  // Transfert OFT standard
        optionType: ExecutorOptionType.LZ_RECEIVE,
        gas: 200000, // Limite de gas de base sûre pour minter/déverrouiller
        value: 0,    
    },
];

// Exporter la configuration générée
export default async function () {
    return {
        contracts: [
            { contract: chilizContract },
            { contract: baseContract },
        ],
        connections: await generateConnectionsConfig([
            [
                chilizContract,  // Source
                baseContract,    // Destination
                [['LayerZero Labs'], []], // Configuration DVN par défaut
                [1, 1],                   // Confirmations de blocs
                [EVM_ENFORCED_OPTIONS, EVM_ENFORCED_OPTIONS], // Options d'exécution [Vers Chiliz, Vers Base]
            ],
        ]),
    };
}

Étape 3 : Workflow de déploiement

Avec vos contrats écrits et votre layerzero.config.ts préparé, il est temps de déployer les contrats sur leurs réseaux respectifs. La boîte à outils LayerZero V2 s'appuie sur le plugin hardhat-deploy pour gérer les déploiements efficacement.

Vous devrez créer deux scripts de déploiement dans le répertoire deploy/ de votre projet : un pour le Mainnet de Chiliz Chain et un pour le Mainnet Base.

Le script de déploiement de l'Adapter Chiliz

Créez un fichier nommé 01_deploy_chiliz_adapter.ts dans votre dossier deploy/. Ce script passe l'adresse de votre token existant et l'adresse Chiliz Endpoint V2 dans le 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
    const TOKEN_ADDRESS = "0xYourTokenAddressHere"; 
    
    // L'adresse Chiliz Mainnet Endpoint V2
    const CHILIZ_ENDPOINT_V2 = "0x6F475642a6e85809B1c36Fa62763669b1b48DD5B";

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

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

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

Le script de déploiement de l'OFT Base

Créez un second fichier nommé 02_deploy_base_oft.ts dans votre dossier deploy/. Ce script initialise le nouvel OFT natif sur Base.

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

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

    // Détails du token (doit correspondre à votre token Chiliz)
    const TOKEN_NAME = "My Token";
    const TOKEN_SYMBOL = "TKN";

    // L'adresse Base Mainnet Endpoint V2 
    const BASE_ENDPOINT_V2 = "0x1a44076050125825900e736c501f859c50fE728c";

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

    await deploy('BaseTokenOFT', {
        from: deployer,
        args: [
            TOKEN_NAME,         // _name
            TOKEN_SYMBOL,       // _symbol
            BASE_ENDPOINT_V2,   // _lzEndpoint
            deployer            // _delegate (Owner)
        ],
        log: true,
        waitConfirmations: 2,
    });
};

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

Exécuter les déploiements

Assurez-vous que votre hardhat.config.ts a les URLs RPC et les clés privées correctement configurées pour Chiliz Chain et Base.

Se connecter via RPC

Connecting to Base - Base DocumentationBase documentation

Exécutez les commandes suivantes dans votre terminal pour déployer les contrats :

# 1. Déployer l'Adapter sur Chiliz Chain
npx hardhat deploy --network chiliz --tags ChilizTokenAdapter

# 2. Déployer l'OFT natif sur Base
npx hardhat deploy --network base --tags BaseTokenOFT

Une fois les déploiements terminés, Hardhat sauvegardera les adresses des contrats dans un dossier deployments/. Les outils LayerZero liront automatiquement ces adresses lors de l'exécution de la commande de câblage à l'étape suivante.

Étape 4 : Câblage et peering

À ce stade, vos contrats ChilizTokenAdapter et BaseTokenOFT sont déployés sur chaque chaîne, mais ils sont complètement isolés. Si le contrat Base reçoit un message lui indiquant de minter des tokens, il doit savoir que le message provient vraiment de votre Adapter sur Chiliz, et non d'un acteur malveillant.

Vous devez établir cette confiance en "câblant" cryptographiquement les contrats ensemble comme peers.

Cela se fait en exécutant la commande wire, qui générera et exécutera des transactions sur Chiliz et Base.

Ce qui se passe en coulisses

Une configuration complète de chemin LayerZero V2 nécessite en réalité 6 transactions sur chaque chaîne :

• setSendLibrary : Attribue la MessageLib LayerZero responsable de l'envoi de messages.

• setReceiveLibrary : Attribue la MessageLib responsable de la réception de messages.

• setConfig (Send Library) : Configure les DVNs et Executors spécifiques pour les messages sortants.

• setConfig (Receive Library) : Configure les DVNs spécifiques requis pour vérifier les messages entrants.

• setEnforcedOptions : définit les limites de gas d'exécution requises. Lorsqu'un utilisateur envoie un message depuis Chiliz Chain, il paie pour le gas de destination à l'avance. La définition des enforced options garantit qu'il paie suffisamment de gas pour que l'Executor LayerZero traite avec succès la transaction sur Chiliz Chain.

• setPeer : Lie un Endpoint ID (EID) de destination à une adresse de contrat de confiance. Vous devez dire au contrat Chiliz Chain de faire confiance au contrat Base, et au contrat Base de faire confiance au contrat Chiliz Chain.

Exécuter la tâche Wire

Exécutez la commande suivante dans votre terminal :

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

La chaîne d'outils calculera automatiquement les paramètres requis, vous présentera un tableau des transactions qu'elle va exécuter, et les soumettra à Chiliz et Base en utilisant votre portefeuille de déploiement.

Une fois les transactions confirmées sur les deux réseaux, votre bridge de tokens est officiellement en ligne et entièrement configuré ! L'Adapter Chiliz est maintenant autorisé à envoyer des commandes de mint à Base, et Base est autorisé à envoyer des commandes de déverrouillage en retour vers Chiliz.

Étape 5 : Opération et tests

Avec vos contrats déployés et sécurisés ensemble, votre token est désormais omnichain. L'étape finale consiste à exécuter un transfert cross-chain du Mainnet de Chiliz Chain vers le Mainnet Base.

1) Exécuter le transfert cross-chain

La boîte à outils LayerZero V2 fournit une tâche Hardhat intégrée pour tester les transferts OFT directement depuis votre terminal. Cette commande estimera les frais de gas cross-chain, débitera votre portefeuille en $CHZ (le token gas natif sur la chaîne source), et initiera le transfert.

Parce que le ChilizTokenAdapter a besoin de permission pour verrouiller vos Fan Tokens existants, une transaction ERC-20 approve() est requise.

Le CLI LayerZero détecte cela et gère l'approbation automatiquement avant d'envoyer le message.

Exécutez la commande suivante :

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

Ce que fait cette commande :

1. Recherche le Mainnet Chiliz (30409) et le Mainnet Base (30184) dans votre config.

2. Estime les frais cross-chain requis par l'Executor LayerZero.

3. Appelle la fonction send() sur votre Adapter Chiliz.

4. L'Adapter verrouille 10 tokens et émet un paquet vers l'Endpoint LayerZero.

2) Suivre le paquet sur LayerZero Scan

Les transactions cross-chain sont asynchrones. Bien que votre transaction Chiliz confirme en quelques secondes, le message doit encore être vérifié et exécuté sur Base.

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

Pour en savoir plus sur cet outil :

LayerZero Scan - LayerZeroLayerZero Documentation

Configurer les limites de gas

Il est très important de définir des limites de gas, car ne pas le faire peut entraîner l'échec de vos messages cross-chain sur le réseau de destination.

Lorsqu'un utilisateur fait le bridge d'un token de Chiliz Chain vers Base, il paie les frais de gas pour les deux chaînes à l'avance en une seule transaction sur Chiliz (en utilisant $CHZ). LayerZero utilise ensuite une partie de ces frais pour payer le gas ETH réel nécessaire pour exécuter la transaction de minting sur Base.

Pour garantir que LayerZero dispose de suffisamment de gas pour traiter avec succès la fonction lzReceive sur la chaîne de destination, vous devez définir des Enforced Options. Si celles-ci ne sont pas définies, la transaction peut être annulée sur la chaîne de destination en raison d'une erreur "Out of Gas".

Configurer les options

Cette option est configurée dans votre fichier layerzero.config.ts. Mettez à jour le tableau connections pour inclure le bloc enforcedOptions pour chaque chemin :

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

// ... (définitions des contrats comme précédemment)

connections: [
    {
        from: 'ChilizTokenAdapter',
        to: 'BaseTokenOFT',
        config: {
            enforcedOptions: [
                {
                    msgType: 1,        // 1 = Transfert OFT standard (SEND)
                    optionType: 1,     // 1 = Option lzReceive
                    gas: 200000,       // Limite de gas estimée pour minter sur Base
                },
                {
                    msgType: 2,        // 2 = Transfert OFT avec payload (SEND_AND_CALL)
                    optionType: 1,
                    gas: 250000,       // Limite de gas légèrement plus élevée pour les appels complexes
                }
            ]
        },
    },
    {
        from: 'BaseTokenOFT',
        to: 'ChilizTokenAdapter',
        config: {
            enforcedOptions: [
                {
                    msgType: 1,
                    optionType: 1,
                    gas: 200000,       // Limite de gas estimée pour déverrouiller sur Chiliz
                }
            ]
        },
    },
],
// ...

Explication des paramètres :

• msgType: 1 : Représente un transfert de token standard. msgType: 2 est utilisé pour les appels "composés" (par exemple, bridger un token et immédiatement le staker en un seul clic).

• optionType: 1 : Indique à l'Executor de simplement exécuter la fonction lzReceive.

• gas: 200000 : Une limite de gas de base sûre pour les mints et déverrouillages OFT standards. Vous pouvez l'ajuster en fonction de la consommation de gas spécifique de vos contrats déployés.

Si vous avez défini cette option après avoir déjà câblé les chaînes, vous pouvez recâbler avec les options maintenant en place en utilisant la même commande :

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

Les outils détecteront automatiquement les changements et soumettront une transaction setEnforcedOptions() à vos contrats sur Chiliz et Base. Désormais, chaque fois qu'un utilisateur déclenche un bridge, les contrats imposeront que l'utilisateur paie pour au moins 200 000 unités de gas sur la chaîne de destination, assurant une livraison fiable.