Cross-Chain Gateway Deployment Guide

·

Cross-chain technology is transforming how blockchains interact, enabling seamless interoperability between disparate networks. At the heart of this ecosystem lies the cross-chain gateway (Pier) — a critical component that allows application chains to securely connect to the BitXHub relay chain and execute cross-chain transactions. This guide walks you through the complete deployment process for a cross-chain gateway, covering key steps from contract deployment to node activation.

Whether you're integrating Ethereum, Fabric, BCOS, CITA, or Hyperchain, this step-by-step tutorial ensures your application chain is properly configured and verified for full cross-chain functionality.

Understanding the Cross-Chain Gateway

The Pier gateway serves as a bridge between your application chain and the BitXHub cross-chain platform. It enables secure message routing, validation, and execution of inter-blockchain operations. Supported chains include:

If your target blockchain isn't on this list, you can contribute by developing custom plugins and smart contracts to expand compatibility.

👉 Discover how decentralized interoperability can power your next blockchain project.

Deployment involves five core phases:

  1. Deploy cross-chain contracts
  2. Obtain deployment package & configure Pier
  3. Register application chain
  4. Deploy validation rules
  5. Start the cross-chain gateway

Let’s dive into each stage in detail.

Step 1: Deploy Cross-Chain Contracts

Before launching the gateway, you must deploy two essential smart contracts on your application chain:

⚠️ Prerequisite: Ensure your application chain (e.g., Ethereum or Fabric) is already running.

For Ethereum

Use tools like Remix to compile and deploy contracts. First, clone the client repository:

git clone https://github.com/meshplus/pier-client-ethereum.git && git checkout v1.6.2

Contract files are located in the example/ directory:

Deployment order matters:

  1. Deploy broker.sol first.
  2. Update BrokerAddr in transfer.sol with the deployed broker address.
  3. Deploy transfer.sol.

After deployment, call the audit method on the broker contract to approve the transfer contract:

audit("<transfer_contract_address>", 1)

Passing 1 signifies approval.

For Hyperledger Fabric

Use fabric-cli to install and instantiate contracts. Begin by installing the tool:

go get github.com/securekey/fabric-examples/fabric-cli/cmd/fabric-cli

Retrieve the contract files:

git clone https://github.com/meshplus/pier-client-ethereum.git && git checkout v1.6.2
unzip -q contracts.zip

Then install and instantiate both contracts:

fabric-cli chaincode install --gopath ./contracts --ccp broker --ccid broker --config "${CONFIG_YAML}" --orgid org2 --user Admin --cid mychannel
fabric-cli chaincode instantiate --ccp broker --ccid broker --config "${CONFIG_YAML}" --orgid org2 --user Admin --cid mychannel

fabric-cli chaincode install --gopath ./contracts --ccp transfer --ccid transfer --config "${CONFIG_YAML}" --orgid org2 --user Admin --cid mychannel
fabric-cli chaincode instantiate --ccp transfer --ccid transfer --config "${CONFIG_YAML}" --orgid org2 --user Admin --cid mychannel

Finally, audit the transfer contract:

fabric-cli chaincode invoke --cid mychannel --ccid=broker \
--args='{"Func":"audit", "Args":["mychannel", "transfer", "1"]}' \
--user Admin --orgid org2 --payload --config "${CONFIG_YAML}"

Step 2: Get Deployment Package & Configure Pier

Now that contracts are deployed, prepare the Pier binary and configure it for your environment.

Option A: Build from Source

Compile Pier and the relevant plugin:

cd $HOME
git clone https://github.com/meshplus/pier.git
cd pier && git checkout v1.6.2
make prepare && make build

# For Ethereum plugin
cd $HOME
git clone https://github.com/meshplus/pier-client-ethereum.git
cd pier-client-ethereum && git checkout v1.6.2
make eth

For Fabric:

git clone https://github.com/meshplus/pier-client-fabric.git
cd pier-client-fabric && git checkout v1.6.2
make fabric1.4

Option B: Download Binaries

Alternatively, download pre-built binaries:

Ensure shared libraries (libwasmer.so on Linux, libwasmer.dylib on macOS) are in the same directory as binaries. Set library path:

export LD_LIBRARY_PATH=$(pwd)

Initialize Pier Configuration

Create config directory:

./pier --repo=~/.pier init

Key configuration file: ~/.pier/pier.toml

Modify Port Settings (Optional)

[port]
http = 44544
pprof = 44555

Configure Relay Chain Connection

[mode]
type = "relay"
[mode.relay]
addrs = ["localhost:60011", "localhost:60012", "localhost:60013", "localhost:60014"]
quorum = 2
validators = [
 "0x000f1a7a08ccc48e5d30f80850cf1cf283aa3abd",
 "0xe93b92f1da08f925bdee44e91e7768380ae83307",
 ...
]

Set Application Chain Type

For Ethereum:

[appchain]
plugin = "eth-client"
config = "ether"

For Fabric:

[appchain]
plugin = "fabric-client-1.4"
config = "fabric"

Configure Plugin-Specific Files

Copy plugin binaries and configs:

cp eth-client ~/.pier/plugins/
cd pier-client-ethereum && cp -r config $HOME/.pier/ether

Important files in ~/.pier/ether:

Example ethereum.toml:

[ether]
addr = "wss://kovan.infura.io/ws/v3/cc512c8c74c94938aef1c833e1b50b9a"
name = "ether-kovan"
contract_address = "0xYourBrokerAddress"
abi_path = "broker.abi"
key_path = "account.key"
password = "your_password"

For Fabric:

cp fabric-client-1.4 ~/.pier/plugins/
cd pier-client-fabric && cp -r config $HOME/.pier/fabric

Update:

👉 See how leading platforms achieve seamless blockchain interoperability today.

Step 3: Register Application Chain

Registration requires approval via governance voting on BitXHub.

Initiate registration:

./pier --repo ~/.pier appchain register \
--name=ethereum \
--type=ether \
--consensusType POS \
--validators=~/.pier/ether/ether.validators \
--desc="Ethereum appchain for test" \
--version=1.0.0

Output includes Chain ID and Proposal ID.

BitXHub administrators vote to approve:

./bitxhub --repo ../node1 client governance vote \
--id <proposal_id> \
--info approve \
--reason approve
✅ Success Condition: Majority of BitXHub nodes approve (or single approval in solo mode).

Check status:

./bitxhub --repo ../node1 client governance proposals --type AppchainMgr

Step 4: Deploy Validation Rules

Once registered, deploy the WASM-based validation rule:

pier --repo ~/.pier rule deploy --path=~/.pier/ether/validating.wasm

This ensures transaction integrity across chains.

Step 5: Start the Cross-Chain Gateway

Launch Pier:

./pier --repo=~/.pier start

Monitor logs for:

Success means your chain is now live on the cross-chain network.

Frequently Asked Questions (FAQ)

Q: What is a cross-chain gateway?
A: A Pier node acts as a bridge between an application chain and the BitXHub relay chain, enabling secure cross-chain communication and transaction execution.

Q: Can I connect unsupported blockchains?
A: Yes! You can develop custom plugins and contracts to integrate new chains into the BitXHub ecosystem.

Q: Why is governance voting required for registration?
A: Voting ensures trust and security by requiring consensus among relay chain validators before onboarding a new chain.

Q: Do I need gas tokens for cross-chain operations?
A: Yes, especially on chains like Ethereum where calling smart contracts consumes gas.

Q: What happens if validation fails?
A: Invalid transactions are rejected by the relay chain, maintaining system integrity and preventing malicious activity.

Q: How do I troubleshoot connection issues?
A: Verify network addresses, certificate paths, contract ABIs, and ensure all services are running with correct permissions.

By following this guide, you’ve successfully deployed a cross-chain gateway and connected your blockchain to a broader interoperable network. With proper configuration and validation, your application can now participate in secure, trustless cross-chain interactions.

👉 Unlock advanced cross-chain capabilities with cutting-edge infrastructure solutions.