Bridge

Overview

Waterfall Bridge is a cross-chain bridge that enables the transfer of assets between the Waterfall Network and other blockchain networks.

The Waterfall Bridge allows users to move assets, such as cryptocurrencies or tokens, between Waterfall and other compatible blockchain networks. It serves as a connection point between these networks, enabling seamless interoperability and asset transfers.

The Waterfall Bridge utilizes a combination of smart contracts and other protocols to facilitate the transfer process. When a user wants to transfer assets from Waterfall to another blockchain, they initiate the transfer by interacting with the smart contract on the Waterfall network. The smart contract locks or holds the assets, ensuring they cannot be accessed or used while the transfer is in progress.

Once the transfer is initiated, the Waterfall Bridge communicates with the smart contract or bridge mechanism on the target blockchain network. This mechanism verifies the transfer request and facilitates the release of assets on the target network. The assets are then made available on the target network for the user to access and use.

Similarly, when a user wants to transfer assets from another blockchain to Waterfall, they would interact with the Bridge mechanism or smart contract on the source blockchain network. The smart contract on the source network locks the assets, and the Waterfall Bridge facilitates the release of the assets on the Waterfall network.

The Waterfall Bridge plays a crucial role in enabling cross-chain interoperability, allowing users to take advantage of the features and benefits offered by both Waterfall and other blockchain networks. It expands the possibilities for decentralized applications and provides users with more flexibility in managing their assets across different blockchain ecosystems.

Use Cases

1. The user sends ETH from the Ethereum network to the Waterfall network.
   1. User converts ETH to WETH ERC20 tokens using a smart contract. Simply transferring ETH from one network to another is not possible, the Bridge only supports the transfer of ERC20 tokens.
   2. In the Bridge web app, the user selects WETH tokens on the Ethereum network and automatically selects the Waterfall network for receiving.
   3. If the user has not used our Bridge before, the application will suggest replenishing the user’s balance in WATER so that the Bridge can carry out the transfer transaction at the user’s expense.
   4. If there is enough WATER balance and the selected amount of WETH tokens is specified, after clicking the confirm button, a MetaMask window pops up where the user confirms and signs the WETH transfer transaction to one of the Bridge addresses.
   5. The system waits for the required number of transaction confirmations.
   6. BFT consensus is reached and a transaction is formed to credit the user with WWETH on the Waterfall network.
   7. The transfer transaction is sent to the Waterfall network and after confirmation, the user sees WWETH ERC20 tokens in their balance.
2. The user sends WWETH from the Waterfall network to the Ethereum network.
   1. In the Bridge web app, the user selects WWETH tokens in the Waterfall network and selects the Ethereum network for receiving.
   2. If the user has not used ourBridge before, the application will suggest topping up the user’s balance in ETH so that the Bridge can carry out the transfer transaction at the user’s expense.
   3. If there is enough ETH balance for the fee and the selected amount of WWETH tokens is specified, after clicking the confirm button, a MetaMask window pops up where the user confirms and signs the WWETH transfer transaction to one of the Bridge addresses.
   4. The system waits for the required number of transaction confirmations.
   5. BFT consensus is reached and a transaction to credit the user with WETH in the Ethereum network is formed.
   6. The transfer transaction is sent to the Ethereum network and after confirmation, the user sees WETH ERC20 tokens in their balance.
   7. The user transfers WETH ERC20 tokens from the smart contract to ETH. It is not possible to simply transfer ETH from one network to another, we only support the transfer of ERC20 tokens.

Architecture

The system consists of the following components (let's consider, for example, when we have the Ethereum <-> Waterfall Bridge and the Binance Smart Chain (BSC) <-> Waterfall):

1. Web app
2. Bootnode, to which Bridge nodes connect to find other network participants
3. Consensus Node,
   • monitors the Ethereum network and participates in BFT only within the Ethereum -> Waterfall transfer
   • monitors the BSC network and participates in BFT only within the BSC -> Waterfall transfer
   • monitors the Waterfall network and participates in BFT only within the Waterfall -> Ethereum transfer
   • monitors the Waterfall network and participates in BFT only within the Waterfall -> BSC transfer
   • can perform one or several of the above functions
4. Private Node,
   • generates transactions for the Ethereum network
   • generates transactions for the BSC network
   • generates transactions for the Waterfall network
   • can perform one or several of the above functions, although for security it is better to have only one.

Algorithm for transferring tokens from the Ethereum network to the Waterfall network

1. The user sends tokens to the Ethereum Bridge address.
2. The Consensus Nodes monitoring the Ethereum network catch this transaction and wait for a certain number of confirmations (specified in the configuration file).
3. After they have received the required number of confirmations, the monitoring nodes check the user’s balance in the Waterfall network, and if there are enough funds to pay the fee, they create a transaction to send to the Waterfall network and to the private peer-to-peer network of the Bridge.
4. A Private Node, which forms a transaction for the Waterfall network, receives the necessary number of confirmations (checking the signatures of the Consensus Nodes) from the received transaction data, forms the transaction, and signs it with its key, sending it to the private peer-to-peer network of the Bridge.
5. Consensus Nodes connected to the Waterfall network simply send this transaction to Waterfall.

Security provision

1. Private peer-to-peer network
   To secure the work from hacking by a single server, several equal nodes are used, which are combined into a private network. This private network, for security reasons, is only used within an encrypted VPN, so that no one can read what packets are being sent within the network.
2. Trust nodes
   Only certain trusted nodes are connected to the private network. They are manually added individually on each node. Therefore, a new node cannot be connected without the consent of all participants. Trust nodes support trusted community members individually. This increases trust in the user’s Bridge as they understand who is behind it.
3. Decentralization
   There are 3 types of nodes that perform different functions and have different security requirements. This allows securing the weakest points of the system:
   • Bootnode. Its function is simply to connect the other Bridge network nodes. There are no requirements for it, except that it only works within the VPN network.
   • Consensus Node and network monitoring. These nodes communicate with each other in a private Bridge network, but also connect to Ethereum/BSC/Waterfall nodes for monitoring and transaction sending. For security, Ethereum/BSC/Waterfall nodes are installed separately, and consensus nodes connect to them via VPN. To lose control of the bridge, you would have to lose control over the majority of nodes of this type.
   • Private Node for transaction formation. This node is isolated from the outside world by a strong firewall. It only receives messages through a private peer-to-peer network via VPN. Its main function is to gather consensus, sign the transaction, and send it to the private network.
4. Key storage
   Each node uses keys to sign data, and the keys themselves are stored on the disc in encrypted form. To decrypt them, you not only need access to the key files, but you also need to know which version of the software was used to import them, as each software has its own salt. You also need the password entered by the user when launching the software node. After the node is launched, it is impossible to access the secret key.
5. Integrity protection of software The system has the built-in integrity protection of binary code. If changes are made to the software, the node will not work.

Possible attacks, consequences, and countermeasures

1. For an attacker to gain access to Ethereum/BSC/Waterfall nodes connected to Bridge nodes, they must gain access to the majority of Ethereum/BSC/Waterfall nodes connected to Bridge nodes. Since these nodes are deployed by trusted individuals from the community, it is difficult to simultaneously access such nodes. It would be challenging to even identify the IP addresses of the servers where these nodes are hosted.
2. If an attacker gains access to the VPN network, they will only be able to read the packets that are sent between the nodes, but they will not be able to affect the operation or manipulate the data, since all messages are signed with private keys. The administrator should ensure that no unauthorized person gains access.
3. If an intruder gains access to the server where Bootnode is running, they can only prevent a new consensus participant from finding other participants, thus preventing consensus.
   To prevent this from happening:
   1. When several Bootnodes are running, the attacker needs to gain access to all of them.
   2. You should secure SSH access with a firewall by IP address.
   3. Only the owner of the private RSA key can access the server.
4. If an attacker gains access to servers where Bridge Consensus Nodes are running, they would have to gain access to the majority of nodes to disrupt the consensus.
   This is impossible if:
   1. Nodes are hosted by different trusted entities in different data centers, and those entities do not know where the nodes are deployed.
   2. The SSH entry is secured with a firewall by IP address.
   3. The server can only be accessed by the owner of the private RSA key. Even if access to the keys is obtained, they cannot be decrypted without knowing the password and salt.
5. If an attacker gains access to the server where the Private Node signing transactions are located, this is the most serious attack, as the malicious actor can access the Bridge balances and take all the funds.
   To prevent this from happening, access to this server must be restricted as in previous cases:
   1. Secure SSH login with a firewall based on IP address.
   2. Only the owner of the private RSA key can access the server.
   3. The server does not have public access, only through VPN.
6. Even if the attacker gains access to the server:
   1. Wallet keys cannot be decrypted without knowing the password specified during key import and the salt embedded in the application binary.
   2. Due to protection against modifications in the binary, it is not possible to replace the node’s operation and thus send it a command to create a transaction to the attacker’s address.