design_docs.md

Design Documentation

• ETH Bridge
  • ETH Bridge Deposit
  • ETH Bridge Withdrawal
• ERC-20 Bridge
  • ERC-20 Bridge Deposit
  • ERC-20 Bridge Withdrawal
• Retryable Messages

This document defines the high level bridge implementation.

ETH Bridge

The ETH bridge facilitates the transfer of ETH from Ethereum to be represented as the native token on Fuel.

ETH Bridge Deposit

1. User starts a deposit by calling depositETH() on FuelMessagePortal which accepts an amount of ETH that gets custodied while bridged
2. The Fuel client sees an outgoing message event emitted on the FuelMessagePortal and adds a corresponding InputMessage to the UTXO set with the designated recipient
3. The recipient can now spend the amount value in the input message like any other input

ETH Bridge Withdrawal

1. User starts a withdrawal by creating a transaction that creates a MessageOut receipt, via the SMO opcode, with a specific amount of ETH
2. The messageIds from all MessageOut receipts in a block are put into a merkle tree and included in the block header, which gets committed to the FuelChainState contract
3. After a finalization period, the user calls relayMessage on the FuelMessagePortal contract with a block inclusion proof that is cross verified with the FuelChainState contract, which then sends the ETH to the message recipient

ERC-20 Bridge

The ERC-20 bridge facilitates the transfer of ERC-20 tokens from Ethereum to be represented as tokens on Fuel.

ERC-20 Bridge Deposit

1. User starts a deposit by calling the deposit() function on the FuelERC20Gateway (after they have approved token transfer to FuelERC20Gateway)
2. The FuelERC20Gateway transfers tokens to itself to custody while they are bridged
3. The FuelERC20Gateway creates a message in the FuelMessagePortal to be relayed on Fuel with the MessageToContractPredicate as the recipient so that anyone can spend the InputMessage on the user's behalf but with guarantees that the spending transaction correctly relays the message data
4. The Fuel client sees an outgoing message event emitted on the FuelMessagePortal and adds a corresponding InputMessage to the UTXO set with the designated recipient predicate
5. A transaction is built and submitted by either the user or a third party that meets the requirements of the MessageToContractPredicate recipient
6. A single call is made from the transaction script to the intended target Fuel token contract specified in the messages data field. This function verifies the sender of the InputMessage, parses the data from the InputMessage data field and mints the appropriate amount of tokens

ERC-20 Bridge Withdrawal

1. User starts a withdrawal by calling withdraw on the token specific BridgeFungibleToken contract, sending the coins to withdraw along with it
2. The BridgeFungibleToken contract looks to see what coins it was sent, burns them and then creates a MessageOut receipt via the SMO opcode
3. The messageIds from all MessageOut receipts in a block are put into a merkle tree and included in the block header, which gets committed to the FuelChainState contract
4. After a finalization period, the user calls relayMessage on the FuelMessagePortal contract with a block inclusion proof that is cross verified with the FuelChainState contract, which then calls to the FuelERC20Gateway with the abi specified in the message data
5. The FuelERC20Gateway verifies it’s being called by the FuelMessagePortal and releases the specified amount of tokens to the specified address