Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

fix(website): Update bridge concept #14665

Merged
merged 6 commits into from
Sep 14, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 17 additions & 13 deletions packages/website/pages/docs/concepts/bridging.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -64,11 +64,11 @@ Let's walk through an example:
2. Next, we call `eth_getProof`, which will give us a proof that we did indeed send a message on the source chain.
3. Finally, we call `isSignalReceived` on the destination chain's SignalService which essentially just verifies the merkle proof. `isSignalReceived` will look up the block hash you are asserting you had stored a message on the source chain (where you originally sent the message), and with the sibling hashes inside the merkle proof it will rebuild the merkle root, which verifies the signal was included in that merkle root—meaning it was sent.

And boom! We have sent a cross-chain message. Confusing? Well leave some feedback please if it is, so we can clear it up.
And boom! We have sent a cross-chain message. If this is confusing, you can also find a simple dApp that was built during one of our workshops to demonstrate the fundamentals. You can find it [here](https://github.com/taikoxyz/MessageServiceShowCaseApp).

## How the bridge works

The bridge is a set of smart contracts and a frontend web app that allow you to send testnet ETH and ERC-20 tokens between Sepolia and Taiko. This bridge is just one possible implementation built on top of Taiko's core protocol, specifically the signal service which anybody can use to build bridges.
The bridge is a set of smart contracts and a frontend web app that allow you to send testnet ETH and ERC-20, ERC-1155 and ERC-721 tokens between Sepolia and Taiko. This bridge is just one possible implementation built on top of Taiko's core protocol, specifically the signal service which anybody can use to build bridges.

First, here is a flowchart of how our bridge dapp implementation works, which uses the signal service:

Expand All @@ -83,27 +83,31 @@ Taiko's bridge utilizes the Signal Service we described. Here is the general use
2. The Bridge locks the Ether, and stores a message by calling `sendSignal(message)` on the SignalService contract
3. The user receives Ether on the destination chain, if they (or another) provide a valid merkle proof that the message was received on the source chain

### How does ERC-20 bridging work?
With the current design there are 2 ways to bridge `Ether`:
1. `Ether` only case: The user interacts directly with the Bridge contract by calling `sendMessage`
2. `ERC-XXX` + `Ether` + case: The user interacts with the `ERCXXXVault` (ERC20, ERC721, ERC1155) because he/she wants to bridge over some tokens, but in case he/she fills the `message.value` field, also `Ether` will be bridged

### How does ERC-20 (or ERC-721, ERC-1155) bridging work?

ERC-20 tokens originate from a canonical chain. To send a token and bridge it to the other chain, a new BridgedERC20 contract needs to be deployed on the destination chain.

#### Bridge from canonical chain to destination chain

Here are the overall steps for transferring canonical ERC-20 from a source chain to the destination chain:
Here are the overall steps for transferring canonical ERC-20 (the overall process is identical for ERC-721, and ERC-1155 token types as well!) from a source chain to the destination chain:

1. A contract for the ERC-20 must first be deployed on the destination chain (will be done automatically by the TokenVault if not already deployed)
1. A contract for the ERC-20 (or ERC-721, ERC-1155) must first be deployed on the destination chain (will be done automatically by the ERC20Vault if not already deployed)

2. Call sendERC20 on the source chain TokenVault, this will **transfer** the amount by using the `safeTransferFrom` function on the canonical ERC-20 contract, on the source chain, to the TokenVault.
2. Call `sendToken` on the source chain ERC20Vault, this will **transfer** the amount by using the `safeTransferFrom` function on the canonical ERC-20 contract, on the source chain, to the ERC20Vault.

3. Send a message to the Signal Service (on the source chain), this message will contain some metadata related to the bridge request, but most importantly it includes the calldata for the `receiveERC20` method.
3. The vault contract (via the Bridge) sends a message to the Signal Service (on the source chain), this message will contain some metadata related to the bridge request, but most importantly it includes the calldata for the `receiveToken` method.

4. Process the message on the destination chain by submitting a merkle proof (generated from the source chain), proving that a message is included in the state of the source chain Signal Service. After verifying this occurred and doing some checks, it will attempt to invoke the `receiveERC20` method encoded in the message. This will **mint** ERC-20 on the BridgedERC20 contract to the `to` address on the destination chain!
4. Process the message on the destination chain by submitting a merkle proof (generated from the source chain), proving that a message is included in the state of the source chain Signal Service. After verifying this occurred and doing some checks, it will attempt to invoke the `receiveToken` method encoded in the message. This will **mint** ERC-20 (or ERC-721, ERC-1155) on the BridgedERC20 contract to the `to` address on the destination chain!

#### Bridge from destination chain back to the canonical chain

Okay now let's do the reverse, how do we transfer a bridged token from a source chain to the destination chain?
Okay now let's do the reverse, how do we transfer a bridged token from a source chain to the destination chain? (Destination chain in this case is the canonical chain, where the original token lives.)

1. A contract for the ERC-20 already exists on the canonical chain, so no need to deploy a new one.
2. Call sendERC20 on the source chain TokenVault, this will **burn** the ERC-20 on the BridgedERC20 contract.
3. Send a message to the Signal Service (on the source chain), this message will contain some metadata related to the bridge request, but most importantly it includes the calldata for the `receiveERC20` method.
4. Process the message on the destination chain by submitting a merkle proof (generated from the source chain), proving that a message is included in the state of the source chain Signal Service. After verifying this occurred and doing some checks, it will attempt to invoke the `receiveERC20` method encoded in this message. This will **transfer** the amount from the destination chain TokenVault to the `to` address on the destination chain.
1. A contract for the ERC-20 (or ERC-721, ERC-1155) already exists on the canonical chain, so no need to deploy a new one.
2. Call `sendToken` on the source chain token vault contract, this will **burn** the ERC-20 on the BridgedERC20 contract.
3. The vault contract (via the Bridge) sends a message to the Signal Service (on the source chain), this message will contain some metadata related to the bridge request, but most importantly it includes the calldata for the `receiveToken` method.
4. Process the message on the destination chain by submitting a merkle proof (generated from the source chain), proving that a message is included in the state of the source chain Signal Service. After verifying this occurred and doing some checks, it will attempt to invoke the `receiveToken` method encoded in this message. This will **transfer** the amount from the destination chain TokenVault to the `to` address on the destination chain.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading