Bridge de Base vers Chiliz Chain

Déployez un OFT Adapter sur Base et un OFT natif sur Chiliz Chain en utilisant LayerZero v2 pour faire le bridge d'un token ERC-20 existant de Base vers Chiliz Chain.

Pour faire le bridge d'un token existant de Base vers Chiliz Chain, 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à (Base), et un OFT natif sur la chaîne de destination (Chiliz Chain).

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

Prérequis

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

• Une adresse de contrat ERC-20 sur Base.

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

  • Voir ici pour la configuration RPC du Mainnet Base.

  • Voir ici pour la configuration RPC de Chiliz Chain.

• 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 Base : tokens ETH.

  • Sur Chiliz Chain : tokens CHZ.

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

Étape 1 : Développement des contrats

Préparer l'OFTAdapter sur Base

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 Base, ce contrat verrouille les tokens ERC-20 originaux.

Créez un nouveau fichier nommé BaseTokenAdapter.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 BaseTokenAdapter is OFTAdapter {
    constructor(
        address _token,      // L'adresse de votre token EXISTANT sur Base
        address _lzEndpoint, // L'adresse de l'Endpoint LayerZero V2 sur Base
        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 Base, vous devez passer l'adresse du contrat de votre token existant comme _token et l'adresse Base Endpoint V2 (0x1a44076050125825900e736c501f859c50fE728c) comme _lzEndpoint.

Voir tous les endpoints disponibles pour Chiliz Chain ici :

Base Mainnet - LayerZeroLayerZero Documentation

Préparer l'OFT sur Chiliz Chain

Étant donné que le token n'existe pas encore nativement sur Chiliz Chain, 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 Base, et de les brûler lorsque les utilisateurs font le bridge en retour.

Créez un nouveau fichier nommé ChilizTokenOFT.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 ChilizTokenOFT is OFT {
    constructor(
        string memory _name,   // Le nom du token (doit correspondre à votre token Base)
        string memory _symbol, // Le symbole du token (doit correspondre à votre token Base)
        address _lzEndpoint,   // L'adresse de l'Endpoint LayerZero V2 sur Chiliz Chain
        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 Chiliz Chain, assurez-vous que le _name et le _symbol correspondent à votre token original sur Base pour éviter de confondre les utilisateurs. Passez l'adresse Chiliz Chain Endpoint V2 (0x6F475642a6e85809B1c36Fa62763669b1b48DD5B) comme _lzEndpoint.

Voir tous les endpoints disponibles pour Chiliz Chain ici :

Chiliz 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 baseContract: OmniPointHardhat = {
    eid: EndpointId.BASE_V2_MAINNET,
    contractName: 'BaseTokenAdapter',
};

const chilizContract: OmniPointHardhat = {
    eid: EndpointId.CHILIZ_V2_MAINNET,
    contractName: 'ChilizNativeOFT',
};

// 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 d'exécution
        value: 0,    // Native drop (0 pour les transferts standards)
    },
];

// Exporter la configuration générée
export default async function () {
    return {
        contracts: [
            { contract: baseContract },
            { contract: chilizContract },
        ],
        // Le générateur crée automatiquement les chemins A->B et B->A !
        connections: await generateConnectionsConfig([
            [
                baseContract,      // Source
                chilizContract,    // 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]
            ],
        ]),
    };
}

Le tableau [EVM_ENFORCED_OPTIONS, EVM_ENFORCED_OPTIONS] indique à l'Executor LayerZero d'imposer 200 000 unités de gas lors de la livraison du message à Chiliz, et identiquement 200 000 unités de gas lors du retour du message 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 Base et un pour le Mainnet de Chiliz Chain.

Le script de déploiement de l'Adapter Base

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

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

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

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

Le script de déploiement de l'OFT Chiliz Chain

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

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 Base)
    const TOKEN_NAME = "My Token";
    const TOKEN_SYMBOL = "TKN";

    // L'adresse Chiliz Chain Mainnet Endpoint V2 
    const CHILIZ_ENDPOINT_V2 = "0x6F475642a6e85809B1c36Fa62763669b1b48DD5B";

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

    await deploy('BaseTokenOFT', {
        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 = ['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 Base et Chiliz Chain.

Connecting to Base - Base DocumentationBase documentation

Se connecter via RPC

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

# 1. Déployer l'Adapter sur Base
npx hardhat deploy --network chiliz --tags BaseTokenAdapter

# 2. Déployer l'OFT natif sur Chiliz Chain
npx hardhat deploy --network base --tags ChilizTokenOFT

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 BaseTokenAdapter et ChilizTokenOFT sont déployés sur chaque chaîne, mais ils sont complètement isolés. Si le contrat Chiliz Chain reçoit un message lui indiquant de minter des tokens, il doit savoir que le message provient vraiment de votre Adapter sur Base, 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 Decentralized Verifier Networks (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 Base, 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 Base de faire confiance au contrat Chiliz Chain, et au contrat Chiliz Chain de faire confiance au contrat Base.

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 Base est maintenant autorisé à envoyer des commandes de mint à Chiliz Chain, et Chiliz Chain est autorisé à envoyer des commandes de déverrouillage en retour vers Base.

É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 Base vers le Mainnet de Chiliz Chain.

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 $ETH (le token gas natif sur la chaîne source, Base), et initiera le transfert.

Exécutez la commande suivante :

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

Ce que fait cette commande :

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

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

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

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 Base vers Chiliz Chain, il paie les frais de gas pour les deux chaînes à l'avance en une seule transaction sur Base (en utilisant $ETH). 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 Chiliz Chain.

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: 'BaseTokenAdapter',
        to: 'ChilizTokenOFT',
        config: {
            enforcedOptions: [
                {
                    msgType: 1,        // 1 = Transfert OFT standard (SEND)
                    optionType: 1,     // 1 = Option lzReceive
                    gas: 200000,       // Limite de gas estimée pour minter sur Chiliz Chain
                },
                {
                    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: 'ChilizTokenOFT',
        to: 'BaseTokenAdapter',
        config: {
            enforcedOptions: [
                {
                    msgType: 1,
                    optionType: 1,
                    gas: 200000,       // Limite de gas estimée pour déverrouiller sur Base
                }
            ]
        },
    },
],
// ...

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 Base et Chiliz. 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.