Cross-chain: BSC Relayer

BSC Relayer

Relayers are responsible to submit Cross-Chain Communication Packages between the two blockchains. Due to the heterogeneous parallel chain structure, two different types of Relayers are created.

Relayers for BC-to-BSC communication referred to as BSC Relayers are a standalone process that can be run by anyone, and anywhere, except that Relayers must register themselves onto BSC and deposit a certain amount of BNB. Only relaying requests from the registered Relayers will be accepted by BSC.

GitHub Implementation link:

Config Files:

Monitor and Parse Cross Chain Event

As a BSC relayer, it must have proper configurations on the following three items:

srcCrossChainIDuint16CrossChainID of BC, the value is 1 for testnet
destCrossChainIDuint16CrossChainID of BSC, the value is 2 for testnet
destChainNamestringname of targe chain, for Binance Smart Chain, the value should be “bsc”

A BSC relayer is required to parse all block results and pick out all events with event type “IBCPackage” from endBlock event table. This is an cross chain package event example:

  "type": "IBCPackage",
      "key": "IBCPackageInfo",
      "value": "bsc::2::8::19"

BSC relayer should iterate all the attributes and parse the attribute value:

  1. Split the value with “::” and get a 4-length string array
  2. Follow the following table to parse the 4 elements:
IndexDescriptionTypeExample Value
0destination chain namestringbsc
1CrossChainID of destination chainint162
2channel idint88
  1. Filter out attributes with mismatched destination chain CrossChainID or destination chain name.

Build Tendermint Header and Query Cross Chain Package

Build Tendermint Header

import tmtypes ""
type Header struct {
  ValidatorSet     *tmtypes.ValidatorSet `json:"validator_set"`
  NextValidatorSet *tmtypes.ValidatorSet `json:"next_validator_set"`

If a cross chain package event is found at height H, wait for block H+1 and call the following rpc methods to build the above Header object:


Header Encoding in golang:

  1. Add dependency on go-amino v0.14.1
  2. Add dependency on tendermint v0.32.3:
  3. Example golang code to encode Header
import ( amino "" tmtypes "" ) var cdc = amino.NewCodec() func init() { tmtypes.RegisterBlockAmino(cdc) } func EncodeHeader(h *Header) ([]byte, error) { bz, err := cdc.MarshalBinaryLengthPrefixed(h) if err != nil { return nil, err } return bz, nil }

Query Cross Chain Package With Merkle Proof

  1. Query height: H
  2. Query path: /store/ibc/key
  3. Follow the table to build a 14-length byte array as query key:
prefix1 bytes0x00
source chain CrossChainID2 bytessrcCrossChainID in bsc relayer configuration
destination chain CrossChainID2 bytesdestCrossChainID in bsc relayer configuration
channelID1 byteschannelID from event attribute
sequence8 bytessequence from event attribute
  1. Assemble the above parameters to the following rpc call.

Call Build-In System Contract

Sync BC Header

  • function syncTendermintHeader(bytes calldata header, uint64 height)Call syncTendermintHeader of TendermintLightClient contract to sync BC header. The contract address is 0x0000000000000000000000000000000000001003. The “header” is the encoding result of Header and the height should be H+1

Deliver Cross Chain Package

Follow this table to get build-in system contract address and method name:

ChannelIDDesriptioncontract addressMethods
1bind channel0x0000000000000000000000000000000000001004handleBindPackage
2transfer channel0x0000000000000000000000000000000000001004handleTransferInPackage
3refund channel0x0000000000000000000000000000000000001004handleRefundPackage
8staking channel0x0000000000000000000000000000000000001000handlePackage

All above methods shares the same parameter table:

Parameter NameTypeValue
msgBytes[]bytepackage bytes
proof[]bytemerkle proof bytes
packageSequenceuint64sequence from attribution value

Incentives Mechanism

BSC Relayer Incentive Mechanism