Wanchain's Cross-Chain Message Passing Protocol Development Handbook

1. Background

1.1. This Handbook

Welcome to the Wanchain's Cross-Chain Message Passing Protocol Handbook! This handbook serves as a straightforward guide to help you understand and leverage Wanchain's Cross-Chain Message Passing Protocol, Wanchain's Cross-Chain Message Passing 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 Message Passing

Cross-Chain Message Passing is the mechanism by which messages and arbitrary data are 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 Message Passing protocols can move any type of messages and arbitrary data. Importantly, Cross-Chain Message Passing protocols can feed data into 3rd party smart contracts to seamlessly execute on-chain logic and create novel cross-chain applications.

1.3. Wanchain's Cross-Chain Message Passing Protocol

Wanchain's Cross-Chain Message Passing 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 Wanchain's Cross-Chain Message Passing Protocol as quickly as possible. It will outline a few necessary preparations before demonstrating how to perform a few of Wanchain's Cross-Chain Message Passing Protocol'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 Wanchain's Cross-Chain Message Passing Protocol, Wanchain's Cross-Chain Message Passing 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

Chain Name	BIP44 ChainId	Gateway Address
Wanchain	2153201998	0x7280E3b8c686c68207aCb1A4D656b2FC8079c033
Arbitrum	1073741826	0x7280E3b8c686c68207aCb1A4D656b2FC8079c033
Avalanche C-Chain	2147492648	0x7280E3b8c686c68207aCb1A4D656b2FC8079c033
BNB Chain	2147484362	0x7280E3b8c686c68207aCb1A4D656b2FC8079c033
Energi	2147493445	0x7280E3b8c686c68207aCb1A4D656b2FC8079c033
Ethereum	2147483708	0x7280E3b8c686c68207aCb1A4D656b2FC8079c033
Optimism	2147484262	0x7280E3b8c686c68207aCb1A4D656b2FC8079c033
Polygon	2147484614	0x7280E3b8c686c68207aCb1A4D656b2FC8079c033

Chain Name

BIP44 ChainId

Gateway Address

Wanchain

2153201998