The content here is a little messy. We'll sweep over this and make it prettier for you soon.
Hot Cross has built a bridge technology that allows end users to security transfer ERC20 tokens from the Ethereum network to the Binance Smart Chain (BSC) and vice versa. This is a continuation on the work we have already done with the V1 version of the bridge, which has successfully secured the transfer of millions of tokens from one chain to another.
The goal of the system is to allow open participation from any team that has an existing token on one chain and wishes to create a bridge.
- Token Owner
- Token team
High level architecture
The following diagram illustrates the different parts of the system.
The system primarily consist of a set of smart contracts deployed on the Ethereum and Binance Smart Chain blockchains. This setup is exactly what makes our system secure; most of the logic is driven by audited smart contracts and funds are locked in a secure non-custodial manner.
Below we describe each component:
Any reference to ETH_TOKEN and BSC_TOKEN do not target a specific smart contract. We essentially refer to any ERC20 and BEP20 tokens that are registered with the Token Registry smart contract and via the Bridge Registration process described below
- Ethereum Bridge: The main smart contract that Alice would use to initiate a transfer of an ERC20 token on Ethereum and receive the corresponding BEP20 token on the BSC chain. The core functionality of this part of the system is to allow users to lock a selected ERC20 tokens in a secure vault and later on unlock them; thus establishing a peg-in/peg-out bridge. The process of pegging in is described in the diagrams below, however at the basic level it includes a step at which user call a method of the Ethereum Bridge smart contract via the DApp.
- BSC Bridge: A similar set of smart contracts residing on the Binance Smart Chain. The purpose of these contracts is to mint and transfer an equal amount of BEP20 tokens based on the size of the funds locked on the Ethereum blockchain. That is, if Alice locks 100 ETH_TOKEN tokens on the Ethereum blockchain, an equal amount of 100 BSC_TOKEN tokens will minted and transferred to Alice's account on the BSC blockchain. At the same time Alice will be able to return the full amount or part of the 100 BSC_TOKEN tokens and receive back the original locked ETH_TOKEN tokens on the Ethereum blockchain. The smart contract will be transparent and the total balances on both blockchains will be visible to the user via the DApp.
- Validator Registry: Both networks will have a Validator Registry smart contract deployed. This the central point of reference that will be used during the cryptographic verification that will happen in various methods of the Ethereum Bridge and BSC Bridge smart contracts. It acts a a registry that records the validators for each token registered with the platform.
- Token Registry: A smart contract that maintains a record of all the tokens that are currently registered with the platform, as well as, their owners.
- Fee Manager: Each individual token owner can set setup a fee mechanism. This will be in a form of percentage of the amount that is transferred. The exact fee can be set only by the token owner i.e, the account that has registered a new bridge. We envision this to be an optional feature and teams will set the fee to zero.
- Limit Checker: Teams registering a new bridge for their token can optionally set daily cap and minimum amount of transfer. This gives a flexibility to the team to decide inflow and outflow of tokens from one network to another. At the same time it allows teams to decide what is the minimum amount of a transfer that they're willing to cater for
As described earlier, validators will have to pay for the cost of submitting cryptographic proofs into the BSC blockchain which will incur some gas cost.
- Ethereum Bridge Manager: As described in the Bridge Registration section, adding a new token bridge into the platform is done in a pure decentralized way. A token team owner can use the DApp and seamlessly integrate a new token bridge within a few minutes. The magic that makes that possible lies in the Bridge manager contracts on both networks. The Ethereum Bridge Manager will
- Add the ERC20 token to the token registry
- Register the ERC20 token address with the validator registry
- Setup the limits via the LimitChecker contract
- Setup the fee via the FeeManager contract
- BSC Bridge Manager: Similar to the Ethereum Bridge Manager, but does all the necessary work on the BSC side. More specifically:
- Deploy a new BEP20 smart contract
- Add the BEP20 token to the token registry
- Register the BEP20 token address with the validator registry
- Setup the limits via the LimitChecker contract
- Validators. This is the off-chain set of processes that will apply the bridging logic. It is a well known fact that the Ethereum and BSC, although both EVM based blockchains, cannot communicate directly with each other. This implies that the logic of peg-in/peg-out we described above cannot be solely performed by just these two entities. We need external, off-chain trusted services that will relay messages from one blockchain to another. The validators play exactly this role in our system. They utilize the event mechanism of both blockchain to accept user requests and relay those request to the opposite side. This whole process is done via cryptography communication protocols and can be freely audited by any external party. Any message from one blockchain to another is executed when a quorum is reached. That is, N out M validators would need to sign the execution of a request before it can be completed. The core involvement is during the following two use cases
- Listen to the requests from the Ethereum blockchain. More specifically, each validator will listen to an specific event that signifies the intent of a user to lock an amount of ETH_TOKEN tokens The validators would need to complete the second part of that process by triggering the minting of an equal amount of tokens on the BSC blockchain and transfer them to the user's account. Note, that the validators do not have any control on the ETH_TOKEN tokens on the Ethereum blockchain. The sole purpose of the validator is to relay the intent of the user from one blockchain to another.
- Listen to events on the BSC blockchain and trigger the unlocking of token on the Ethereum blockchain. In essence, users will have to burn their tokens on the BSC blockchain in order to receive their initial deposited ETH_TOKEN tokens. Note they do not have to burn the full amount of their BSC_TOKEN balance. However, the system will make sure than no user will get more ETH_TOKEN tokens from what they deposited. At the same time no user will get more BSC_TOKEN tokens on the BSC blockchain. In essence, the ETH_TOKEN and BSC_TOKEN will always be in balance on both blockchains; thus avoiding double spending or erroneously claim more tokens that one possess.
One of the important steps is the registration of the new bridge in the first step. This process is entirely driven by the token owner and it is triggered via the DApp. Any team that has a running ERC20 token on Ethereum should be able to bridge it over to the BSC following a few simple steps.
- Token owner visits the hot cross DApp via a browser
- The token owner clicks Register New Bridge
- A form with the following inputs is presented. - ERC20 token address - Name and symbol of the BEP20 token that will deployed on BSC - Limits i.e daily cap and min amount, as described earlier - Validator address This step will do the necessary setup work on the BSC Network.
- The token owner clicks next and this will trigger a transaction that will be sent to the BSC Bridge Manager contract. The pre-requisites are: - The ERC20 has not previously been registered with hot cross - The token owner sends the service fee in BNB
- When the transaction is finalised, a new similar to the previous form is presented. - The transaction fee and fee collector address. These fields are optional This step will do the necessary setup work on the Ethereum Network.
- The token owner clicks Finish which will trigger a transaction to the Eth Bridge Manager contract.
The pre-requisites are: - The ERC20 has not previously been registered with hot cross - The token owner sends the service fee in ETH
As you probably noticed, the token owner would need to interact with both networks and split the service fee payment amongst these two networks.
Finally, the DApp will present a config file. The token owner would have to download the Validator client that hot cross will build and run it using the aforementioned config file.
The end result will be a new token to be registered with the platform and can be used to peg-in/peg-out tokens from one chain to another.
Below we list the two user journeys and the steps included in each.
ETH_TOKEN → BSC_TOKEN
- Alice visits the DApp using her browser
- Alice connects her Metamask to the Ethereum RPC node.
- The DApp recognizes the current blockchain and present a simple UI form containing a select box where she can choose the ETH_TOKEN token she wishes to peg-in.
- After selecting the ETH_TOKEN, Alice enters the amount of ETH_TOKEN tokens she would like to lock on the Ethereum Bridge and consequently receive BSC_TOKEN on the other side.
- She enters 100 and clicks transfer. If she has enough balance of the selected ETH_TOKEN, her Metamask will prompt her to submit the transaction.
- The request will be transmitted to the Ethereum blockchain which will trigger a token transfer from her balance to the account of the Ethereum Bridge Smart Contract. In other words, the Ethereum Bridge Smart Contract will now have a balance of ETH_TOKEN tokens that no other party can use.
- At the same time validators are listening to the blockchain events. When a new TokenRelayed event is detected, they start the process of relaying the request to the BSC blockchain. The end result will be a new transaction transmitted to the BSC blockchain.
- The transaction will call the processRequest method on the BSC Bridge Smart Contract which will start the processing of Alice's request that was earlier submitted to the Ethereum Blockchain.
- If the quorum condition is met i.e. enough validators has signed the message, then 100 BSC_TOKEN tokens will be minted and transferred to the Alice's balance.
- If Alice now switches to the BSC network on her Metamask wallet, she will see a balance of 100 BSC_TOKEN tokens.
BSC_TOKEN → ETH_TOKEN
- Alice visits the DApp using her browser
- Alice connects her Metamask to the BSC RPC node.
- The DApp recognizes the current blockchain and present a simple UI form containing a select box where she can choose the BSC_TOKEN token she wishes to peg-out.
- She enters 100 and clicks transfer. If she has enough balance of BSC_TOKEN, her Metamask will prompt her to submit the transaction.
- The request will be transmitted to the BSC chain and the transferAndCall method of the BSC_TOKEN smart contract will be called. The 100 BSC_TOKEN tokens will be transferred to the BSC Bridge Smart Contract. the requestUnlock function will be called during the same transaction.which will make sure that the given amount of BSC_TOKEN tokens is burnt.
- The validators will listen on the event emitted from the BSC Bridge Smart Contract and will sign and send messages back thus committing on the unlock request.
- When enough signatures are sent from the validators i.e. quorum is reached, the BSC Bridge Smart Contract will emit an event dignifying that anyone can now use the message id and call the unlock function on the Ethereum Bridge Smart Contract.
- The Ethereum Bridge Smart Contract will get the packed signatures, cryptographically verify the signatures and make sure that enough validators has committed.
- Finally the locked 100 ETH_TOKEN tokens will be transferred to Alice.
This is the exact process users would follow in the V1 version of the platform. The only difference is that Alice has to explicitly select the token via the UI.
- What will happen if Chunk (malicious user) decides to register a bridge for a token with the end-goal to achieve a denial-of-service. This can happen if Chunk follows the Bridge Registration process but do not run the validator client. The result will be that the new token will appear in the list of all available tokens. Alice would be able to call the transactions via the DApp, tokens will be locked in the Eth Bridge but no BSC_TOKENS will be minted on the BSC side because no validator is running. The issue here is that tokens will be locked in the bridge and Alice will not be able to withdraw. At the same time, a legitimate team account will be denied from registering a the bridge for his token since the token has already been registered by Chunk.
- Similar to the previous issue, but this time it's Bob a legitimate token owner that runs the validator for some time and then decides that he doesn't want to be involved any more. Similar to the previous issue, tokens will be locked on the ETH bridge and users will not be able to get them back.
One proposed solution is to introduce the idea of master validators. A master validator is a similar client to the typical validator, however it is maintained by the hot cross team (and maybe other parties in the future).
The role of this entity is to make sure that no service is denied to the platform's users. The way this mechanism will work is as follows:
- In addition to the bridge registration process, the token owner would need to also stake an amount of native coins e.g. ETH. This stake is used a tool to penalise any rogue malicious behaviour from the token owner side (either a legitimate or illegitimate token owner).
- A master validator will be running the same exact steps as we described earlier. The only difference between the typical validator is that it will execute requests with a much bigger delay.
For example, Imaging Alice doing a new ETH_TOKEN transfer to the BSC chain; as highlighted earlier, this will trigger an TokenRelayed event which will be picked up by the validator maintained by the token team. A master validator will listen to the same event, however it will try to execute it with a delay of N minutes. The reason we run it with a bigger delay is that, if the team is running a validator, the request will be processed successfully and by the time the master validator tries to execute it, it will realise that the request has already been processed and just ignore. In essence, in the happy path scenario, the master validator will not send any transactions and thus no cost will be incurred. However, in the case that the team validators are not running, the master validator will make sure that user is not denied and that the request is executed. We must highlight that the master validator will not permanently replace the team validator. It will do so for M requests (or M days) after which the team validator will be flagged as malicious. Once that happens the bridge of that token transits into an emergency state. In an emergency state, the following steps will take place:
- The teams staked will be slashed
- Hot cross via the Master Validator setup will provide a grace period during which all users will have to unlock (if they wish) their token from the Eth Bridge.
This requires that the hot cross takes the cost of executing all those peg-out transactions. The problem is that the staked amount might not be enough to execute all those transactions which will result in Hot Cross paying the cost.
A solution to that might be that, in an emergency state, the master validator creates cryptographic and shares them off-chain. Then it's the user's responsibility to pay for the gas costs.