Build a cross-chain token bridge between Celo and BSC from scratch

bobelr · May 1, 2023, 8:33pm

Introduction

Blockchains are isolated from one another even though some are forks of one another. This greatly hinders communication among them. The $Celo coin in your wallet is not available to use on the Binance Smart Chain network and vice versa. One solution to achieving interoperability today is bridging assets from one network to another.
In this guide, you will learn how to bridge assets between the Celo blockchain and Binance Smart Chain.

Prerequisites

At least an intermediate in smart contract development using Solidity language.
Experience working with Typescript and Javascript.
Using hardhat for smart contract development.

Requirements

You need a development environment - IDE. I recommend VSCode.
Install Node version >=14.0.0.

Concept of bridging/cross-chain bridging

Bridging is a system of creating utility for DApps or assets across different compatible or incompatible blockchain networks. Creating utilities between unrelated chains such as Celo → Solana involves extra tasks compared to compatible networks like Celo → Binance Smart Chain.

One of the goals of going cross-chain is to achieve interoperability among desired networks i.e making blockchains communicate with one another. With this solution, we can expand the network of users for DApps deployed on the Celo blockchain through the deployment of utilities that enable the Binance Smart Chain users to interact with the same DApp on the BSC blockchain.
At the time of creating this post, the cost of interacting with the Celo blockchain is relatively lower than that of the Binance network. This might be a good reason for bridging from the latter to the former.

There are two popular kinds of cross-chain bridging.

Centralized bridge

This is a kind of bridging system often used by centralized exchanges. Using APIs, users mostly deposit assets to a large pool, and the corresponding assets on the destination chain are sent out from another pool. One major disadvantage of this type is that it is controlled by a central body which is not really what most people want.

Decentralized bridge

This is a method of using smart contracts and a relayer to bridge utilities between or among blockchains. You don’t have to call any external API. Smart contracts are deployed on both the source and destination blockchains and a relayer facilitates timely communication between the networks by listening to events and triggering actions on both chains.
To better explain the concept, in the next section, we will programmatically explore how to build a cross-chain bridge.

Steps to building a cross-chain bridge

In this section, we will explore the smart contract and the backend part but exclude the front-end. We will create a CLI DApp. Everything runs in the terminal. I will make it comprehensive enough so that when you need to build a front, it will be a lot easier since you’d already understand what to do.

Before we proceed to the coding aspect, let’s quickly set up a hardhat environment. Please refer to this article and this for comprehensive tutorials on how to set up and use hardhat.

Create a project

mkdir build-a-cross-chain-token-bridge-between-celo-and-bsc
cd build-a-cross-chain-token-bridge-between-celo-and-bsc

Initialized the project using NPM

npm init --yes

Initialized a git repository

git init

Add hardhat using Yarn

yarn add hardhat

npx hardhat

Follow the instructions in the terminal, select the option to create a Typescript project, then install the required dependencies. This should include the web3 package.

Next, install the openzeppelin library.

yarn add '@openzeppelin/contracts'

If all steps is done correctly, installation should be successful.

Smart contract

Beforehand, let’s examine how the token bridge will work. You want to have a clear picture of what to do before proceeding to write the code. As a practice, I will be using the testnets: Celo Alfajores and Binance smart chain testnet for deployments.

Deploy a token on the Celo testnet - cBGT. It is the token source chain. You may set the total supply if you wish but it will be irrelevant in this guide.
Deploy a copy of the token on the BSC testnet - bBGT. It will be the token destination chain as we will only be performing a one-way bridging.
Deploy a bridge contract on Alfajores. this contract receives the bridge request, then it locks or simply burns the token it has access to from the caller’s account. It is a clear indication that the bridge contract should have admin access or control over the source token. When the bridge request is made, it should call the lock or burn method in the token contract whichever is available based on how you configure the token.
Deploy a copy of the bridge contract onto the Binance smart chain. This time, it should contain an additional mint method that mints the exact amount of token that was burnt or locked on the source chain. It is worthy of note there is a relayer that alerts the bridge contract on the destination chain which will come on the backend side.

Now that the steps are known ahead of time. Follow the instructions and steps below to copy/paste the code into their respective files.

In the contracts folder, make a new folder names tokens. Create three .sol files:

build-a-cross-chain-token-bridge-between-celo-and-bsc/contracts/tokens/BaseToken.sol. In this file, paste the code below.

 // SPDX-License-Identifier: MIT
  pragma solidity 0.8.18;

  import '@openzeppelin/contracts/token/ERC20/ERC20.sol';
  import '@openzeppelin/contracts/utils/math/SafeMath.sol';

  contract BaseToken is ERC20 {
    using SafeMath for uint;
    error Requested();

    struct TokenRequest {
      uint reqAmount;
      uint cooldown;
    }

    struct BridgeRequest {
      address requester;
      uint amount;
      uint nonce;
    }

    address public bridgeAddress;
    address public admin;

    uint public cooldownInterval;

    uint private nonces;

    uint public immutable maxRequest;

    address public currentRequester;

    mapping (address => TokenRequest) public tokenRequests;

    mapping (address => BridgeRequest) public bridgeRequests;

    mapping (address => uint) public cooldown;

    mapping (uint => bool) private processedNonces;

    constructor(
      string memory name,
      string memory symbol,
      uint _maxRequest,
      uint8 _coolDownInterval,
      address _admin,
      address _bridgeAddress
    ) ERC20(name, symbol) {
      require(_admin != address(0) && _bridgeAddress != address(0), "Address is zero");
      admin = _admin;
      cooldownInterval = _coolDownInterval;
      bridgeAddress = _bridgeAddress;
      maxRequest = _maxRequest * (10 ** uint(18));
    }

    modifier onlyBridgeAddress() {
      require(msg.sender == bridgeAddress, "Only bridgeAddress is allowed");
      _;
    }

    modifier onlyAdmin() {
      require(msg.sender == admin, "Only Admin is allowed");
      _;
    }

    function _transfer(
      address from,
      address to,
      uint256 amount
    ) internal override {
      if(to == bridgeAddress) {
        nonces ++;
        uint nonce = nonces;
        bridgeRequests[from] = BridgeRequest(from, amount, nonce);
        currentRequester = from;
        _burn(from, amount);
      } else _transfer(from, to, amount);
    }

    function updatebridgeAddress(address newbridgeAddress) external onlyAdmin {
      bridgeAddress = newbridgeAddress;
    }

    function mint(address to, uint amount, uint nonce) external onlyBridgeAddress {
      require(!processedNonces[nonce], "Request replay attempt");
      processedNonces[nonce] = true;
      _mint(to, amount);
    }

    function fulfillRequests(address who) public onlyAdmin {
      TokenRequest memory _requesters = tokenRequests[who];
      require(_requesters.reqAmount > 0, "No requests");
      tokenRequests[who] = TokenRequest(0, _now().add(cooldownInterval.mul(1 hours)));
      _mint(who, _requesters.reqAmount);
    }

    function requestFreeToken() public {
      uint amount = maxRequest;
      require(_now() >= tokenRequests[msg.sender].cooldown, "User in cooldown mode");
      tokenRequests[msg.sender] = (TokenRequest(amount, 0));
    }

    function _now() internal view returns(uint) {
      return block.timestamp;
    }
  }

build-a-cross-chain-token-bridge-between-celo-and-bsc/contracts/tokens/BSCbBGT.sol

  // SPDX-License-Identifier: MIT
  pragma solidity 0.8.18;

  import "./BaseToken.sol";

  contract BSCbBGT is BaseToken {
    constructor(
      uint16 _maxRequest,
      uint8 _coolDownInterval,
      address _bridgeAddress
    ) BaseToken(
      'Binance BGToken',
      'bBGT',
      _maxRequest,
      _coolDownInterval,
      msg.sender,
      _bridgeAddress
    ) {}
  }

build-a-cross-chain-token-bridge-between-celo-and-bsc/contracts/tokens/CelocBGT.sol

  // SPDX-License-Identifier: MIT
  pragma solidity 0.8.18;

  import "./BaseToken.sol";

  contract CelocBGT is BaseToken {
    constructor(
      uint16 _maxRequest,
      uint8 _coolDownInterval,
      address _bridgeAddress
    ) BaseToken(
      'Celo BGToken',
      'cBGT',
      _maxRequest,
      _coolDownInterval,
      msg.sender,
      _bridgeAddress
    ) {}
  }

The two token files should inherit from the BaseToken contract, and the constructors should be set appropriately.

Bridge contracts

build-a-cross-chain-token-bridge-between-celo-and-bsc/contracts/BaseBridge.sol

  // SPDX-License-Identifier: MIT
  pragma solidity 0.8.18;

  import "./tokens/BaseToken.sol";

  contract BaseBridge {
    event Burn(address from, uint amount, uint nonce);

    BaseToken private token;

    uint private genNonce;

    address public admin;

    modifier onlyAdmin() {
      require(msg.sender == admin,"Not an admin");
      _;
    }

    constructor() {
      admin = msg.sender;
    }

    function setToken(address baseToken) public onlyAdmin {
      require(address(baseToken) != address(0), "BaseToken is zero address");
      token = BaseToken(baseToken);
    }

    function bridgeToken(address to, uint amount, uint nonce) external onlyAdmin {
      token.mint(to, amount, nonce);
    }

  }

build-a-cross-chain-token-bridge-between-celo-and-bsc/contracts/CeloBridge.sol

  // SPDX-License-Identifier: MIT

  pragma solidity 0.8.18;

  import './BaseBridge.sol';

  contract CeloBridge is BaseBridge {
    constructor() BaseBridge() {}
  }

build-a-cross-chain-token-bridge-between-celo-and-bsc/contracts/BSCBridge.sol

  // SPDX-License-Identifier: MIT

  pragma solidity 0.8.18;
  import './BaseBridge.sol';

  contract BSCBridge is BaseBridge {
    constructor() BaseBridge() {}
  }

Compile

npx hardhat compile

We have completed the contract code. Next, we will write scripts that deploy and execute the above code. The scripts will run as CLI DApp with logs that show how each step run.

Setting up the utilities

This part uses the combination of web3.js and ethers.js. We’d already installed web3.js in the previous chapter while ethers was installed alongside hardhat.

Create a new file under the scripts folder named network.ts.

build-a-cross-chain-token-bridge-between-celo-and-bsc/scripts/network.ts
- Import ethersand web.
```
import { ethers } from "hardhat";
import Web3 from "web3";

// const str = (x:string|undefined) => String(x);
```
- Set up a connection to a node using the web3 wrapped version. In return, we get the provider object. Thereafter, generate web3 instances using the providers.

build-a-cross-chain-token-bridge-between-celo-and-bsc/scripts/network.ts

const ALFAJORES_SOCKET_URL = "wss://alfajores-forno.celo-testnet.org/ws";
const BINANCE_HTTP_URL = "https://data-seed-prebsc-2-s1.binance.org:8545";

// Construct a new instance of the providers for both chains.
const CELO_PROVIDER = new Web3.providers.WebsocketProvider(
  ALFAJORES_SOCKET_URL
);
const BSC_PROVIDER = new Web3.providers.HttpProvider(BINANCE_HTTP_URL);

// We create a new web3 instance parsing the provider as an argument.
const getWeb3Instance = function () {
  const web3_celo = new Web3(CELO_PROVIDER);
  const web3_bsc = new Web3(BSC_PROVIDER);

  return { web3_celo, web3_bsc };
};

This time, we are setting up a provider using ethers wrapped version. I love working with ethers.js, but sometimes, web3 can be very helpful. So I decided to blend them so you can refresh on their usage. Create the RPC object.

build-a-cross-chain-token-bridge-between-celo-and-bsc/scripts/network.ts

// RPC information
const rpcInfo = Object.assign(
  {},
  {
    CELOALFAJORES: {
      name: "Alfajores",
      rpc: ALFAJORES_SOCKET_URL,
      chainId: 44787,
    },
    BSC_TESTNET: {
      name: "BSC Testnet",
      rpc: BINANCE_HTTP_URL,
      chainId: 97,
    },
  }
);

Export the provider function.

build-a-cross-chain-token-bridge-between-celo-and-bsc/scripts/network.ts

export function getProviders() {
  const celoProvider = new ethers.providers.WebSocketProvider(
    rpcInfo.CELOALFAJORES.rpc,
    {
      chainId: rpcInfo.CELOALFAJORES.chainId,
      name: rpcInfo.CELOALFAJORES.name,
    }
  );

  const bscProvider = new ethers.providers.JsonRpcProvider(
    rpcInfo.BSC_TESTNET.rpc,
    {
      chainId: rpcInfo.BSC_TESTNET.chainId,
      name: rpcInfo.BSC_TESTNET.name,
    }
  );

  return { celoProvider, bscProvider };
}

The function waits until the transaction is confirmed within 2 blocks.

build-a-cross-chain-token-bridge-between-celo-and-bsc/scripts/network.ts

const waitForConfirmation = async function (trx: any) {
  console.log("Waiting for confirmation ...");
  return await trx.wait(2);
};

Lastly, in this file, export the utilities.

build-a-cross-chain-token-bridge-between-celo-and-bsc/scripts/network.ts

export function getUtils() {
  return {
    str,
    Web3,
    ethers,
    waitForTransaction,
    getWeb3Instance,
  };
}

build-a-cross-chain-token-bridge-between-celo-and-bsc/scripts/deploy.ts
- Import the utilities and the contract artifacts.