# Bridge Overview

ChainFusion is a decentralized bridge that provides fast, cheap and secure cross-chain communication, like sending assets between blockchains. We strongly believe that bridges should be decentralized and trustless, everyone should be able to become a validator and secure the bridge. Recent events show that current cross-chain solutions are highly vulnerable, sometimes it's enough to compromise few private keys in order to steal all locked value. Risks increase with centralized setups, where only bridge operating company decides who could become a validator. ### Decentralizing the Bridge On vast majority of the blockchains, to make transaction it's enough to create a valid ECDSA signature using private key. [Recent findings](https://eprint.iacr.org/2020/540) in cryptology propose a solution on how to make such signature by cooperation of any number of parties, without knowing private key. It also allows to identify parties that do not cooperate, effectively allowing to slash (ban) them from being validators using automated voting performed by nodes. Using algorithm mentioned above, validators generate distributed key by performing several communication rounds between each other. After last round complete, each party derives his own secret key share. This key share allows honest majority of participants to create valid transaction signatures from mutual public key. This mutual public key has the rights to perform bridging actions, like sending assets on destination chain to receiver who deposited asset on source chain. To make this process happen, validators constantly monitor events on each blockchain supported by bridge and then perform signing rounds in cooperation with other validators. At the end of signing rounds, validators compose valid threshold ECDSA signature for transaction. ### Making bridging cheap In bridges with setup of more than one validator, usually on-chain signature is used. It's costly to check signatures on-chain when number of validators increases, each new signature verification consumes transaction fee. More validators, means more signatures to verify, which means bigger on-chain confirmation costs, resulting in higher bridge fees. Threshold ECDSA allow us to compose one single signature using majority of validators. It's much cheaper to validate single signature and it does not affect security of validation. ### Supported operations Currently bridge supports ERC-20 token transfers, our team constantly expands list of supported blockchains and tokens. We plan to also support NFTs and arbitrary data transfer between blockchains soon. ## ChainFusion Testnet Recently we have launched ChainFusion Testnet. Below you can find useful URLs to explore the project.

Name	URL
Chain ID	`953842`
Explorer	https://testnet-explorer.chainfusion.org/
Bridge App	https://app.chainfusion.org/
HTTPS RPC API	https://rpc.chainfusion.org
WebSocket RPC API	wss://wc-rpc.chainfusion.org

## Bridgenet 1

Name	URL
Chain ID	`9991`
Explorer	https://explorer-bg1.chainfusion.org
HTTPS RPC API	https://rpc-bg1.chainfusion.org
WebSocket RPC API	wss://ws-rpc-bg1.chainfusion.org

## Bridgenet 2

Name	URL
Chain ID	`9992`
Explorer	https://explorer-bg2.chainfusion.org
HTTPS RPC API	https://rpc-bg2.chainfusion.org
WebSocket RPC API	wss://ws-rpc-bg2.chainfusion.org

## Bridgenet 3

Name	URL
Chain ID	`9993`
Explorer	https://explorer-bg3.chainfusion.org
HTTPS RPC API	https://rpc-bg3.chainfusion.org
WebSocket RPC API	wss://ws-rpc-bg3.chainfusion.org

# Making a Transfer ChainFusion bridge allows to transfer assets between various blockchains and makes it fast, cheap, secure in a decentralized fashion. ## Transferring using UI ### Connect Wallet Go to bridge app at [https://app.chainfusion.org](#using-ui) and press **Connect Wallet** button.

After pressing **Connect Wallet** you will see wallet selection dialog. Select one of the supported wallet providers.

You will be prompted to connect wallet, press **Connect**. In this example we use [Metamask](https://metamask.io/).

### Make a transfer After you connect the wallet, you should select source chain, destination chain and enter amount. You can specify either transfer amount or receiving amount. Optional: You can approve ERC-20 token spend by ChainFusion by pressing **Approve** button. Some token standards, like ERC-677 do not require approval.

Press **Transfer** button in order to initiate transfer of specified amount from **source chain** to **destination** chain.

### Recent transfers history Recent transfers are shown in **Recent Transfers** section. You can select **All** in order to see all recent transfers or select **Only My** in order to see transfers performed by account you have connected. Transfer history is limited only to recent transfers, older records won't be shown.

## Transferring using bridge smart contract To transfer assets from one blockchain to another, you would need to use [bridge contract's](https://gitlab.com/chainfusion/erc-20-bridge-contracts/-/blob/main/contracts/chain/ERC20Bridge.sol?ref_type=heads) `deposit()` function. Deposit function has four parameters: * `token` - address of token to deposit, on the chain, you are transferring from * `destinationChainId` - identifier of blockchain you are transferring to * `receiver` - address of receiver, you are transferring to (usually the same account you are transferring from) * `amount` - amount of tokens to transfer through bridge After you made a deposit, usually it takes few minutes for validators to confirm your transfer and compose transaction on destination chain. # Become a Validator Running a validator node requires server based on any linux distributive, installed docker and basic unix shell skills. ### Clone the repo To get started, you need to clone a repository `https://gitlab.com/chainfusion/cfnode-compose.git`, this project contains directories with different configurations that help to run a node in docker environment. Right after cloning the repo you need to open `validator` directory: ```bash git clone https://gitlab.com/chainfusion/cfnode-compose.git cd cfnode-compose/validator ``` ### Generate keystore file A validator needs a key in order to sign blocks, process bridge events and receive a reward. To generate validator key, you need to execute the following command: ```bash docker run \ --rm -v $(pwd)/keystore:/data/keystore -it chainfusion/cfnode:latest \ account new --datadir=/data ``` When generating the key, you will be asked to create new password that will encrypt your generated key. Generated key will be stored in the `keystore/` directory. Make sure you remember the password you gave when creating a key. Without it you are not able to unlock your account and lose access to validator stake. ### Configure validator node Copy file `.env.example` as `.env`. In this file you will need to put docker image tag into a `IMAGE` variable, put the password of the generated key into a `ACCOUNT_PWD` variable, put your public address without leading `0x` from generated key into a `ADDRESS` variable. The resulting `.env` file should look like this: ```bash # Docker image of validator node, # could be left without changes IMAGE=chainfusion/cfnode:latest # List of initial nodes to connect to, # could be left without changes BOOTNODES=enode://6295b6ea88a1519b7b0078c9e7d39921cdc73bdca67e029c1675c67076b0ccdcadc51b2f333f1eafab4ea6501afecb1bad7cb7cd4edaf91e5696ee89dce05edb@bootnode.chainfusion.org:30303 # External IP of your machine, where validator is started, # should be set to be findable by other nodes EXTERNAL_IP=127.0.0.1 # Public address of generated keystore, without leading 0x, # could be found inside keystore file ADDRESS= # Password for keystore file, # in case you set it during generation, # otherwise leave empty PASSWORD= ``` ### Launch validator node Now let's launch your validator node in background using `docker-compose` command: ```bash docker-compose up -d ``` ### See validator logs Last 100 lines of validator logs: ```bash docker-compose logs --tail=100 -f validator ``` All validator logs: ```bash docker-compose logs -f validator ``` ### Staking After your node is up and running, you can finally stake and become a validator to receive rewards during validation process. You need to call `stake()` method in [ValidatorStaking](https://explorer.chainfusion.org/address/0x5E85B5Ab4ABfBf7178B1E92AB9df0C1188e839D1) contract. Minimum stake amount is **1000 CFN**, more stake amount increases relative validation rewards in **CFN**. ### Verify that node is producing blocks In order for you to start validating, you must wait for the new epoch (i.e. validation cycle). If everything went correctly before and the committed stake was sufficient to enter the validator shortlist, your validator node will start to produce blocks in the next validation cycle. # Slashing During validation process, participants actively monitor each other to check if everyone cooperate according to consensus rules. In case validators nodes see any non-cooperative participant, they vote against him on-chain, which may result in slashing. During slashing misbehaving participant is removed from validator list and his stake is distributed to other validators as a reward for keeping bridge secure. ### Validator responsibilities List of main validator responsibilities: * producing new blocks in ChainFusion network * participating in DKG process when validators list is changed * participating in threshold signatures creation to confirm bridge transfers * slashing misbehaving validators * sending keep-alive packets to P2P network of validator nodes # Providing Liquidity Some tokens are not originated from this bridge and already deployed on several blockchains. To make cross-chain transfers of these tokens possible, bridge needs liquidity. To incentivise providing of liquidity, bridge distributes part of collected fees during bridge transfers to liquidity providers. ### Providing liquidity To provide liquidity, you can deposit to [liquidity pools contract](https://gitlab.com/chainfusion/chainfusion-contracts/-/blob/main/contracts/bridge/LiquidityPools.sol) with any supported token. ### Calculating rewards Liquidity rewards depends on liquidity pool fee, transfer volume of provided token and relative share of provided liquidity between other liquidity providers. Let's say you provided **1000 USDT** on Ethereum liquidity pool, which is **5%** of all liquidity provided to **USDT** on this chain (relative to other liquidity providers). Some bridge user transfers **100 USDT** from other chain to Ethereum. In case liquidity pool fee is **1%**, you will get `(100 USDT * 1%) * 5%`, resulting in **0.05 USDT** of rewards on this transaction. More volume goes through the pool, more rewards you receive. ### Withdrawing rewards Liquidity pools do not have any limitation on when or how much liquidity provider can withdraw from it. # Distributed Key Generation To confirm bridge transfers, validators use distributed key. Validators participate in distributed key generation (DKG) process to come up with individual secret key shares, which later allows them to create signatures from mutual account. No one has access to full private key, from which signatures are created. ### Key generation process Once validators list is changed, due to **staking** or **slashing**, they participate in four rounds of key generation. Each next round requires completion of previous round by all the DKG participants. Results of each round is written to special [DKG smart contract](https://gitlab.com/chainfusion/chainfusion-contracts/-/blob/main/contracts/system/DKG.sol). Round result includes public data, for all participants, encrypted private data for other participants and encrypted intermediate data for validator itself. Intermediate data in contract allows to restore validator secret share, even if node is restarted from scratch and synchronized from the first block. ### Avoiding misbehaving validators It's not a secret that we live in a not ideal world and we cannot be sure that validators will run their nodes with 100% uptime, or that validators won't submit any corrupted data as a round results. To address this issue, validators, during DKG process can vote against misbehaving participants on-chain and restart the DKG process without them. Fortunately [DKG algorithm](https://eprint.iacr.org/2020/540.pdf) that we use allows to identify misbehaving participants. If validators misbehave too often, they are being [slashed](/validation/slashing). # Transfer Confirmation Validators constantly monitor bridging events on all supported blockchains. Once they see a transfer event on **source** chain, they start the process of 6 rounds of transaction signing on **destination** chain. This transaction confirms that all the validators seen this event and transfer really took place. After transaction is executed, bridge user receives his funds on **destination** chain. Not every validator needs to be online when there is need to create mutual transaction signature. This is achieved by using threshold signatures, meaning that, let's say only 20 of 30 validators required to participate in signing, while still allowing them to create a valid mutual signature.

### Keep-alive validator messages Validators send keep-alive messages peer-to-peer to other validator nodes to report that they are online and able to participate is signing. When validators start to process bridge transfer, they use list of validators that recently send keep-alive messages to form list of active validators. ### Threshold signing process ![](https://2166523257-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FJlWwc82UlNit3R3Fkv5G%2Fuploads%2FL4rt7h8ENiQSpsZfucwV%2FBridge%20Event%20Handling%402x.png?alt=media\&token=b2c8b072-34f7-4963-b4f4-aeaf1b8f7c20) Each active validator node, maintains pool of unconfirmed transfers, during monitoring of supported blockchains. Unconfirmed transfers go through 6 round distributed signing process by active validator nodes. During which it's decided what to sign (which transfer, using which gas price and other transaction details), so resulting transaction hash is deterministic. Once transaction is signed, it's being broadcasted by validators on **destination** chain. Validators don't need to have any amount of native currency on destination blockchains. As all the transactions are being created collectively, from the mutual address. This mutual address is funded from bridge transfer fees.