| **Chain ID** | **Name** | **Bridge contract address** |
| 279 |  BPX | 0x53fa3006A40AA0Cb697736819485cE6D30DEAEb5 |
| 42161 |  Arbitrum | 0x5CD1A383d9C881577dDF6E5E092Db25b2D50e9B3 |
| 137 |  Polygon | 0x5CD1A383d9C881577dDF6E5E092Db25b2D50e9B3 |
| 43114 |  Avalanche C-Chain | 0x5CD1A383d9C881577dDF6E5E092Db25b2D50e9B3 |
| **Original asset** | **Original chain** | **Wrapped asset** | **Wrapped asset chain** |
| BPX Chain (**BPX**) *native token* | BPX Chain | BPX Chain (**BPX**) *0x602d550a4cA5eAe83195486AC85dC40032dAA787* | Arbitrum |
| BPX Chain (**BPX**) *native token* | BPX Chain | BPX Chain (**BPX**) *0x602d550a4cA5eAe83195486AC85dC40032dAA787* | Polygon |
| BPX Chain (**BPX**) *native token* | BPX Chain | BPX Chain (**BPX**) *0x602d550a4cA5eAe83195486AC85dC40032dAA787* | Avalanche C-Chain |
| Ethereum (**ETH**) *native token* | Arbitrum | π Ethereum (**ETH**) *0x8EF2a6c2a7f6ed5ef63D4d9667C1CCd09C2721C8* | BPX Chain |
| Polygon (**MATIC**) *native token* | Polygon | π Polygon (**MATIC**) *0x43A478B2A63098De753b345f0dFCBa24Da06849d* | BPX Chain |
| Avalanche (**AVAX**) *native token* | Avalanche C-Chain | π Avalanche (**AVAX**) *0xA303b26580e0eB63fAcEC99E26B4A8a6b549e550* | BPX Chain |
| Tether USD (**USDT**) *0xfd086bc7cd5c481dcc9c85ebe478a1c0b69fcbb9* | Arbitrum | π Tether USD (**USDT**) *0x67c7950934833E001cfc8c62E903EaeC69D34790* | BPX Chain |
| Tether USD (**USDT**) *0xc2132D05D31c914a87C6611C10748AEb04B58e8F* | Polygon | π Tether USD (**USDT**) *0x67c7950934833E001cfc8c62E903EaeC69D34790* | BPX Chain |
| Tether USD (**USDT**) *0x9702230A8Ea53601f5cD2dc00fDBc13d4dF4A8c7* | Avalanche C-Chain | π Tether USD (**USDT**) *0x67c7950934833E001cfc8c62E903EaeC69D34790* | BPX Chain |
| USD Coin (**USDC**) 0xaf88d065e77c8cC2239327C5EDb3A432268e5831 | Arbitrum | π USD Coin (**USDC**) *0x0b2ffE5CC332B72293Ca87d48ae9400bFd9Ba97e* | BPX Chain |
| USD Coin (**USDC**) *0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359* | Polygon | π USD Coin (**USDC**) *0x0b2ffE5CC332B72293Ca87d48ae9400bFd9Ba97e* | BPX Chain |
| USD Coin (**USDC**) *0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E* | Avalanche C-Chain | π USD Coin (**USDC**) *0x0b2ffE5CC332B72293Ca87d48ae9400bFd9Ba97e* | BPX Chain |
We have established a convention that all tokens wrapped by the bridge on the BPX chain have the "bridge at night" emoji (π) at the beginning of their original name and original token symbol. However, wrapped BPX on externals chains is always named "BPX Chain" and has the original symbol "BPX". We do not add any prefixes, like WBPX, WETH, unless the original asset already have one.
# Transaction flow Each bridge transaction proceeds according to the following scheme: [](https://docs.bpxchain.cc/uploads/images/gallery/2024-05/Rwg4HqnFlIWKBxEW-bridge-transaction-flow.png) 1. The user initiates a source asset transfer to the bridge contract running on the source blockchain. If the source asset is a native blockchain token, the user transacts to the bridge contract's `transfer()` method. If the source asset is an ERC-20 token, the user transacts to the token's `approve()` method, then transacts to the bridge contract's `transferERC20()` method. 2. If the user sent the original token to get wrapped one, the token is locked in the bridge contract. If the user sent the wrapped token to recover the original asset, the wrapped token is burned. 3. The bridge contract generates a cross-chain message - a bytes string that contains all transaction details. The `MessageCreated()` event is emitted. 4. Bridge relayers constantly listen for bridge contract events. After receiving information about a new message, each relayer performs a checks according to a deterministic algorithm whether it should sign this message or not. Only 8 relayers out of all will be delegated to sign a certain message. 5. Selected relayers sign the message with their private key and send it to the user using the Synapse network. 6. The user waits for all 8 signatures to be received and checks their validity and compliance with the algorithm rules. 7. The user sends a cross-chain message with 8 signatures to the bridge contract running on the destination chain by transacting to the `messageProcess()` method. In the same transaction, the user pays a bridge fee. 8. The bridge contract validates the message, checks whether the signatures are correct and come from exactly those relayers that were selected by the algorithm. 9. If the user unwraps the wrapped tokens, the bridge contract sends the original assets back to the user's wallet. If the user wraps assets, the bridge contract mints the wrapped token to the user's wallet. Additionally the bridge contract divides the received fee into 8 equal amounts and adds them to the balances of relayers involved in a given transaction processing. 10. The user receives the destination assets on the destination blockchain. # Relayer selection algorithm BPX Bridge associates each transaction and signature to a so-called epoch - 20-minute period of time. When the epoch changes, for the same transaction, the set of selected validators will be completely different. So if a transaction cannot be completed in a given epoch due to a relayer failure, the algorithm will select a different set of relayers within 20 minutes at the latest and the transaction will not be stuck forever. The algorithm for delegating 8 relayers for a transaction going through the bridge works as follows: 1\. The bridge smart contract keeps a list of all wallet addresses that have registered as a relayer. Letβs visualize this list as a circle, because the algorithm is based on infinite shifting of the relayers list. For example, if there are 20 relayers in total, we will be adding a number 10, or 20, or 100, etc. to the index 15 to jump over the end of the list and get the relayer with index of 5 again, instead of getting non-existing relayer 25. [](https://docs.bpxchain.cc/uploads/images/gallery/2024-05/PLRoOvq9qOyt50cw-bridge-relayer-algo1.png) 2\. The smart contract picks up 8 individual spacings between relayers. These values will remain constant throughout the entire bridge epoch. To calculate these spacings, we are using transaction-independent pseudorandom data β hashes of previous blocks in the chain. Therefore the bridge user has no influence on the calculated values. If we relied on transaction-dependent data, a hostile user could craft the transaction parameters in a such way, that only hostile relayers under his full control were delegated to validate the transaction. In our example, the calculated spacings have the following values: 3, 4, 1, 6, 2, 8, 7, 2. [](https://docs.bpxchain.cc/uploads/images/gallery/2024-05/OycEoZki8yV7exCu-bridge-relayer-algo2.png) 3\. For each transaction, the displacement of relayers list is calculated. We are shifting the entire list by a value based on transaction-dependent data, so each transaction, even in the same epoch, has a different set of relayers. Potential hostile bridge user can influence the calculated displacement by modifying the transaction parameters, but is still unable to modify the spacings from the previous step. [](https://docs.bpxchain.cc/uploads/images/gallery/2024-05/6K29IAz1PB1RbUv0-bridge-relayer-algo3.png) 4\. After applying the displacement, relayers selected to validate the transaction are as follows: 7, 11, 12, 18, 0, 8, 15, 17. The order is important - the signatures will be invalid if they are swapped. [](https://docs.bpxchain.cc/uploads/images/gallery/2024-05/sfAh5RUhl7UTX6WV-bridge-relayer-algo4.png)If the algorithm happens to select the same relayer twice or more, the next available relayer in the list is selected instead.
# Smart contracts All BPX Bridge smart contracts are open source and available in the public GitHub repository: [https://github.com/bpx-chain/bridge-contracts](https://github.com/bpx-chain/bridge-contracts) ### BridgeHome.sol This contract is deployed only on the BPX chain. In addition to the standard bridge logic, it contains a map of all supported chains and assets and a set of methods that resolve the local token contract address to the remote one and vice versa. ### BridgeForeign.sol This contract is deployed on all chains except BPX. It contains the standard bridge logic, but it does not contain a map of supported chains and assets. The only allowed opposite chain is BPX and in all generated messages it includes local addresses of the token contracts, which must be resolved by the BridgeHome contract on the opposite side of the bridge. ### Proxy.sol Typical Solidity proxy contract that enables future updates of the BridgeHome and BridgeForeign contracts. ### BridgedToken.sol The smart contract of any token wrapped by the bridge. A classic ERC-20 implementation that does not perform any additional functions apart from minting and burning by the owner. The owner is always the bridge contract. # Bridge contract methods These are all the public methods exposed by the underlying Bridge contract from which both the BridgeHome and BridgeForeign contracts inherit. ### Asset methods ```javascript function assetResolve(uint256 chainId, address contractLocal) view returns (address) ``` In the BridgeHome contract (running on the BPX chain), it queries the assets database and returns the remote token contract address by provided remote chain ID and local token contract address. In the BridgeForeign contract (running on other chains), it just returns the `contractLocal` parameter. ### Message methods ```javascript function messageCheckSignatures(uint256 chainId, bytes32 messageHash, tuple(uint8 v, bytes32 r, bytes32 s)[8] signatures, uint64 sigEpoch) view returns (address[8]) ``` Checks the signatures of a cross-chain message before actually posting it for execution. ```javascript function messageGetRelayers(uint256 chainId, bytes32 messageHash, uint64 epoch) view returns (address[8]) ``` Returns addresses of 8 relayers delegated to sign a given message in the given epoch. ```javascript function messageProcess(bytes message, tuple(uint8 v, bytes32 r, bytes32 s)[8] signatures, uint64 sigEpoch) payable ``` Executes a signed cross-chain message and transfers funds to the destination wallet. The function is payable and requires a bridge fee which will go to the relayers as their earnings. The fee amount must meet both conditions: - The fee must be greater than or equal to the gas price of the current transaction (`tx.gasprice`) multiplied by 21000 - The fee must be divisible by 8 ### Relayer methods ```javascript function relayerActivate(uint256 chainId) payable ``` Activates the caller wallet as a bridge relayer. Activation takes effect from the next epoch after the current one. The function is payable and requires a relayer stake deposit. The amount of the required stake can be checked by the `relayerGetStake` method. ```javascript function relayerDeactivate(uint256 chainId) ``` Deactivates the caller wallet as a bridge relayer. Deactivation takes effect from the next epoch after the current one. ```javascript function relayerGetBalance(uint256 chainId, address relayerAddr) view returns (uint256) ``` Returns the entire relayer balance (deposited stake + all earnings). ```javascript function relayerGetStake(address relayerAddr) view returns (uint256) ``` Returns the stake amount required to become a bridge relayer. ```javascript function relayerGetStatus(uint256 chainId, address relayerAddr) view returns (bool, uint64) ``` Returns whether the relayer is active or not (`bool`) and from which epoch it has its current activation status (`uint64`). ```javascript function relayerGetWithdrawalMax(uint256 chainId, address relayerAddr) view returns (uint256) ``` Returns the relayer balance available for withdrawal. For an active relayer, these will be be only earnings. For an inactive relayer, it will be a stake + all earnings. ```javascript function relayerWithdraw(uint256 chainId, address to, uint256 value) ``` Withdraws funds from the caller relayer balance. The amount of funds that can be withdrawn can be checked using the `relayerGetWithdrawalMax` method. ### Transfer methods ```javascript function transfer(uint256 dstChainId, address dstAddress) payable ``` Initiates the transfer of a native token. This function is payable and transaction should have the value to be transferred by the bridge. ```javascript function transferERC20(address srcContract, uint256 dstChainId, address dstAddress, uint256 value) ``` Initiates an ERC-20 token transfer. The bridge contract must be approved to perform an ERC-20 transfer from caller wallet (ERC-20 `approve()` method). # Becoming a relayer Anyone can become a BPX Bridge relayer and validate transactions passing through the bridge. For helping maintain the bridge secure, relayers are paid in each blockchain native currencies. To become a relayer, the following conditions must be met: - You must have a fast and stable Internet connection, uninterrupted power supply and a server running 24/7 with Windows, Linux or Mac OS. VPS in the dedicated hosting company is also allowed. - You must have the RPC access to full nodes of BPX Chain and other blockchains for which you want to relay transactions. Using the public RPC endpoints is strongly discouraged, local nodes are preferred. - You must activate your relayer wallet in bridge smart contracts and thus deposit a relayer stake for each relay direction. For example, if you only want to relay transactions coming from the BPX network to Arbitrum, you must only deposit on the Arbitrum network. If you want to relay transactions going both ways, you need to deposit on both networks. If you want to validate transactions between the BPX, Arbitrum and Polygon in all allowed directions, you must deposit on the Arbitrum network, deposit on the Polygon network, and deposit on the BPX network **twice**. Of course, after unregistering the relayer, you could immediately withdraw all deposited funds, and for the whole time deposits are locked by a smart contracts. BPX developers are not their custodians. - You must run the open source relayer software for each relay direction and ensure it is always running without any issues. Current relayer stake amounts in all supported chains:| **Chain** | **Relayer stake** |
| BPX Chain | 3,000,000 BPX |
| Arbitrum | 0.25 ETH |
| Polygon | 1500 MATIC |
| Avalanche C-Chain | 25 AVAX |
Relayer stake is a crucial mechanism for ensuring bridge security. Without this deposit, one person could register millions of relayer wallets and thus gain a huge probability of being able to sign transactions themselves, without other honest relayers. Additionally, the deposit enforces relayer to unregister from the smart contract to end their relaying activity which protects the bridge against stucked transactions because of lack of signature from "abandoned" relayer.
# Relayer software The official JavaScript (node.js) implementation of the relayer software is available here: [https://github.com/bpx-chain/bridge-relayer](https://github.com/bpx-chain/bridge-relayer) The software works on all popular operating systems. The only requirements are Node.js and npm installed. ### Installation ```bash git clone https://github.com/bpx-chain/bridge-relayer cd bridge-relayer npm install ``` ### Usage ```bash $ node bbrelay.js -h Usage: bbrelay [options] BPX Bridge relayer Options: -s, --src-rpc