XPort: Wanchain's Cross-Chain Data Transfer Protocol Development Handbook

1. Background

1.1. This Handbook

Welcome to the XPort Handbook! This handbook serves as a straightforward guide to help you understand and leverage XPort, Wanchain's Cross-Chain Data Transfer Protocol, to build decentralised cross-chain applications. Whether you're a seasoned cross-chain developer or someone taking their first steps into the world of blockchain technology, this handbook caters to all levels of expertise. We're excited to witness the innovative cross-chain applications you can envision and bring to life!

1.2. Cross-Chain Data Transfers

Cross-Chain Data Transfer Protocols enable data to be passed from one blockchain to another. Rather than only moving fungible and non-fungible tokens, which are a specific type of data structure, Cross-chain data transfer protocols s can move any type of data. Importantly, Cross-Chain Data Transfer Protocols can feed data into 3rd party smart contracts to seamlessly execute on-chain logic and create novel cross-chain applications.

1.3. XPort: Wanchain's Cross-Chain Data Transfer Protocol

XPort, Wanchain's Cross-Chain Data Transfer Protocol, is composed of two basic elements: one robust off-chain relayer and a set of rudimentary on-chain smart contracts called Cross-Chain Gateways.

The off-chain relayer is the same Bridge Node Group that secures all cross-chain transactions executed using the WanBridge. These permissionless Bridge Nodes are rotated and re-elected monthly. They use Multiparty Computation and Shamir’s Secret Sharing cryptography to transfer messages and arbitrary data across chains.
A single smart contract, called a Cross-Chain Gateway, is deployed on each supported blockchain. These Cross-Chain Gateways have limited functionality – they can essentially only send and receive messages and arbitrary data. They serve as the point of contact for all 3rd party developers.

2. Getting Started

This section establishes a solid foundation to get you using XPort, Wanchain's Cross-Chain Data Transfer Protocol, as quickly as possible. It will outline a few necessary preparations before demonstrating how to perform a few of XPort's basic operations. This handbook will use https://remix.ethereum.org/, an online Solidity IDE, as the development environment.

2.1. Necessary Preparations

Open your browser and visit https://remix.ethereum.org/.
Click the File Explorer icon in the left navigation bar of Remix.
Click the "+" icon to create a new workspace. Name your workspace anything you like.

Create a new .sol smart contract and name it something that's easy to remember like "MyContract.sol".

2.2. Basic Operations

In your new .sol smart contract, import WmbApp.sol. Use is to indicate that your contract inherits WmbApp. This allows your smart contract to access all public and protected members from WmbApp. For example, you can declare your contract as follows:

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

import "@wandevs/message@0.2.1/contracts/app/WmbApp.sol";

contract MyContract is WmbApp {
    // Your contract codes
}

Override the _wmbReceive function in your smart contract. _wmbReceive is a protected function provided by WmbApp. It will be called when your smart contract receives a cross-chain message. Customise the _wmbReceive function to meet your application's specific needs. _wmbReceive defines how your contract will behave when it receives a cross-chain message.

function _wmbReceive(
        bytes calldata data,
        bytes32 messageId,
        uint256 fromChainId,
        address fromSC
    ) internal override {
		// do something you want...
}

When initializing your smart contract contract, call the WmbApp initialize function. initialize takes two parameters: admin and _wmbGateway. Pass in the address of the administrator account as admin and the address of the WmbGateway as _wmbGateway. For example:

constructor(address admin, address _wmbGateway) WmbApp() {
    initialize(admin, _wmbGateway);
    // Your initialization code
}

In your smart contract, you may need to send messages or contract calls to other chains. For this, call the _dispatchMessage function. _dispatchMessage is a protected function provided by WmbApp. It can send messages to any chain or contract you specify. _dispatchMessage takes four parameters:
- toChainId: The ID of the chain that will receive the message.
- toAddress: The address of the smart contract that will receive the message.
- msgData: The message data you want to send.
- feeAmount: The fee you want to pay.
For example, you can call the _dispatchMessage function like this:

function sendMessage(
	uint256 toChainId, address toAddress, bytes memory msgData,
	uint feeAmount) public payable {
    _dispatchMessage(toChainId, toAddress, msgData, feeAmount);
}

Note: In this example, the sendMessage function takes the above parameters and simply calls the _dispatchMessage function. You can customise the function in your own smart contract and call the _dispatchMessage function in accordance with your needs. Before calling the _dispatchMessage function, use the estimateFee function to estimate the fee.

estimateFee is a public function provided by WmbApp. It can help you calculate the fee required to send a cross-chain message. estimateFee takes two parameters:
- toChain: The BIP44 ChainId of the chain that will receive the message.
- gasLimit: The gas limit required to execute the contract call on the receiving chain.
Use the fee value returned by the estimateFee function as the feeAmount parameter of the _dispatchMessage function. You can use msg.value to pass in the native token of your chain as the fee, or use the balance of your smart contract as the fee.
For example, you can call the _dispatchMessage function like this:

function sendMessage(
	uint256 toChainId, address toAddress,
	bytes memory msgData, uint256 gasLimit) public payable {
    uint256 fee = estimateFee(toChainId, gasLimit);
    require(msg.value >= fee, "Insufficient fee");
    _dispatchMessage(toChainId, toAddress, msgData, msg.value);
}

Note: In this example, the sendMessage function adds the gasLimit parameter and calls the estimateFee function to calculate the fee inside the function. Then, the smart contract checks whether msg.value is greater than or equal to the calculated fee. If it is not enough, an exception is thrown. Finally, the _dispatchMessage function is called and uses msg.value as the fee.

2.3. Additional Operations

WmbApp provides a function called _dispatchMessageBatch. It can be used to send transactions in batches to different contract addresses on the target chain. _dispatchMessageBatch can also be used to interact with multiple different contracts or to ensure the sequential execution of multiple operations. _dispatchMessageBatch takes three parameters:
- toChainId: the ID of the chain that will receive the message.
- messages: an array containing multiple Message structures. Each Message structure contains a target address and a message data.
- fee: The fee you want to pay.
For example, you can call the _dispatchMessageBatch function like this:

function sendMessageBatch(
	uint256 toChainId, Message[] memory messages, uint256 gasLimit)
	public payable {
    uint256 fee = estimateFee(toChainId, gasLimit);
    require(msg.value >= fee, "Insufficient fee");
    _dispatchMessageBatch(toChainId, messages, msg.value);
}

Note: In this example, the sendMessageBatch function calculates the fee using the estimateFee function. It then checks if msg.value is greater than or equal to the calculated fee. If it is not, an exception is thrown. Finally, the _dispatchMessageBatch function is called using msg.value as the fee.

After your smart contract is deployed and initialized, the administrator needs to call the setTrustedRemotes function to explicitly specify which chains and contracts have permission to send cross-chain messages to your contract. This is an important step to ensure the security of your contract. The setTrustedRemotes function accepts three parameters:
- fromChainIds: an array containing multiple chain IDs, each of which is a uint type.
- froms: an array containing multiple contract addresses, each of which is an address type. Each address corresponds to the chain ID at the same position in the fromChainIds array.
- trusted: an array containing multiple Boolean values, each of which represents whether the corresponding chain and contract is trusted and can send cross-chain messages to your contract.

2.4 Before Moving On

After completing the above operations, your smart contract is ready to receive and send cross-chain messages. Please note that it is your responsibility to ensure the security of your smart contract. You can compile and deploy your smart contract to a blockchain using Remix and MetaMask.

Now that you have an understanding of the basics of XPort, Wanchain's Cross-Chain Data Transfer Protocol, you can customise your smart contracts to receive and send cross-chain messages to serve the unique needs of your application or use case.

3. Supported Blockchains

3.1 Mainnets

Index

Network

WmbGateway Address (XPort Gateway Address)

Bip44 chainId

Polygon

0x7280E3b8c686c68207aCb1A4D656b2FC8079c033

2147484614

BSC

0x7280E3b8c686c68207aCb1A4D656b2FC8079c033

2147484362

Wanchain

0x7280E3b8c686c68207aCb1A4D656b2FC8079c033

2153201998

Avalanche

0x7280E3b8c686c68207aCb1A4D656b2FC8079c033

2147492648

Optimism

0x7280E3b8c686c68207aCb1A4D656b2FC8079c033

2147484262

Arbitrum

0x7280E3b8c686c68207aCb1A4D656b2FC8079c033

1073741826

Energi

0x7280E3b8c686c68207aCb1A4D656b2FC8079c033

2147493445

Bitrock

0x7280E3b8c686c68207aCb1A4D656b2FC8079c033

2154655314

Ethereum

0x7280E3b8c686c68207aCb1A4D656b2FC8079c033

2147483708

Plyr

0x7280E3b8c686c68207aCb1A4D656b2FC8079c033

1073741849

Base

0x7280E3b8c686c68207aCb1A4D656b2FC8079c033

1073741841

Waterfall

0x7280E3b8c686c68207aCb1A4D656b2FC8079c033

1073741851

DIONE Mainnet

0x7280E3b8c686c68207aCb1A4D656b2FC8079c033

1073741848

3.2 Testnets

Index

Chain Name

WmbGateway Address (XPort Gateway Address)

Chain ID

Avalanche Fuji Testnet