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.

Sign up for GitHub

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

Rewrite the SuperchainERC20 page #1273

Open
wants to merge 9 commits into
base: main
Choose a base branch
from
+94 −53
Open

Rewrite the SuperchainERC20 page #1273

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
4bde6ce
Update the `SuperchainERC20` page
qbzzt Jan 22, 2025
fbdaea0
Most @zainbacchus comments
qbzzt Jan 23, 2025
725115a
Merge branch 'main' into 250122-erc20
qbzzt Jan 23, 2025
3a467eb
Last @zainbacchus comments (for now, anyway)
qbzzt Jan 23, 2025
50bd0f9
Unified comments
qbzzt Jan 23, 2025
6e8dc2e
Apply suggestions from @krofax
qbzzt Jan 23, 2025
e2f3ff3
Update pages/stack/interop/superchain-erc20.mdx
qbzzt Jan 23, 2025
a573008
Fixed
qbzzt Jan 23, 2025
7415fd6
Merge branch 'main' into 250122-erc20
sbvegan Jan 24, 2025
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
155 changes: 101 additions & 54 deletions pages/stack/interop/superchain-erc20.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,94 +6,141 @@ description: Learn about the basic details of the SuperchainERC20 implementation

import { Callout } from 'nextra/components'

# SuperchainERC20
import { InteropCallout } from '@/components/WipCallout'

<Callout>
Interop is currently in active development and not yet ready for production use. The information provided here may change. Check back regularly for the most up-to-date information.
</Callout>
<InteropCallout />

`SuperchainERC20` is an implementation of [ERC-7802](https://ethereum-magicians.org/t/erc-7802-crosschain-token-interface/21508) designed to enable asset interoperability in the Superchain.
Asset interoperability allows for tokens to securely move across chains without asset wrapping or liquidity pools for maximal capital efficiency, thus unifying liquidity and simplifying the user experience.
# SuperchainERC20

[`SuperchainERC20`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/SuperchainERC20.sol) is an implementation of [ERC-7802](https://ethereum-magicians.org/t/erc-7802-crosschain-token-interface/21508) designed to enable asset interoperability in the Superchain.
Asset interoperability allows tokens to move securely in the Superchain by burning tokens on the source chain and minting the same number of tokens that were burned on the destination chain.
Asset interoperability solves the issues of liquidity fragmentation and poor user experiences caused by asset wrapping or liquidity pools.
Instead, assets essentially teleport from one chain in the Superchain to another, providing users with a secure and capital-efficient way to transact within the Superchain.
qbzzt marked this conversation as resolved.
Show resolved Hide resolved

Additional features:

* **Simplified deployments**: 0-infrastructure cost to make your token cross-chain. Provides a consistent, unified implementation for tokens across all Superchain-compatible networks and a common cross-chain interface for the EVM ecosystem at large.
* **Permissionless propagation**: Easily clone an existing token contract to a new OP Stack chain using `create2` without requiring the original owner, which enables movement of assets to the new chain once Interop goes live. Importantly, permissionless propagation retains the integrity of the original owner on the contract and preserves security but proliferates the contract's availability to new chains.
* **Simplified deployments**: Zero infrastructure cost to make your token cross-chain.
Provides a consistent, unified implementation for tokens across all Superchain-compatible networks and a common cross-chain interface for the EVM ecosystem at large.
* **Common standard**: Implements ERC-7802, a unified interface that can be used across all of Ethereum to enable cross-chain mint/burn functionality.

## How it works

`SuperchainERC20` facilitates secure token transfers between chains in the Superchain networks via native burning and minting.

* **Token Burning**: Initiating message where token is **burned** on the source chain. A user initiates a transfer of token from one blockchain to another and specifies the recipient wallet address on the destination chain. A specified amount of token is burned on the source chain.
* **Token Minting**: Executing message where token is **minted** on the destination chain. The specified amount of token is minted on the destination chain directly to the recipient wallet address.
[`SuperchainERC20`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/SuperchainERC20.sol) and [`SuperchainTokenBridge`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/SuperchainTokenBridge.sol) work together to allow ERC-20 tokens to be transferred from one chain to the other.

An important thing to note is using `crosschainBurn` and `crosschainMint` on the `SuperchainERC20` to move your asset across the Superchain only affects which chain your asset is located on and does not change the overall supply of the token. This keeps the token's total amount the same across all networks, ensuring its value stays stable during the move and that the `SuperchainERC20` retains a unified, global supply count.
The initiating message burns tokens on the source chain.
The executing message then mints them on the destination chain.

```mermaid

%%{
init: {
"sequence": {
"wrap": true
}
}
}%%

sequenceDiagram
box rgba(255, 4, 32, 0.1) ChainA
participant User-chainA
participant SuperchainERC20-chainA
participant SuperchainERC20Bridge-chainA
end
box rgba(248, 61, 213, 0.1) ChainB
participant SuperchainERC20Bridge-chainB
participant SuperchainERC20-chainB
participant User-chainB
end


User-chainA->>SuperchainERC20-chainA: Initiate token transfer
SuperchainERC20-chainA->>SuperchainERC20Bridge-chainA: Bridge to chainB
SuperchainERC20Bridge-chainA->>SuperchainERC20-chainA: Burn tokens
SuperchainERC20Bridge-chainA-->>SuperchainERC20Bridge-chainA: Emit cross-chain event
SuperchainERC20Bridge-chainB-->>SuperchainERC20Bridge-chainB: Validates message
SuperchainERC20Bridge-chainB-->>SuperchainERC20-chainB: Mint tokens
SuperchainERC20-chainB->>User-chainB: User receives tokens
box rgba(0,0,0,0.1) Source Chain
participant src-erc20 as SuperchainERC20
participant src-bridge as SuperchainTokenBridge
end
actor user as User
box rgba(0,0,0,0.1) Destination Chain
participant dst-l2Xl2 as L2ToL2CrossDomainMessenger
participant dst-bridge as SuperchainTokenBridge
participant dst-erc20 as SuperchainERC20
end
rect rgba(0,0,0,0.1)
note over src-erc20, dst-l2Xl2: Initiating Message
user->>src-bridge: 1. Move n tokens
src-bridge->>src-erc20: 2. Burn n tokens
src-bridge->>dst-l2Xl2: 3. Relay n tokens to user
end
rect rgba(0,0,0,0.1)
note over user,dst-erc20: Executing message
user->>dst-l2Xl2: 4. Relay the message
dst-l2Xl2->>dst-bridge: 4. Relay the message
dst-bridge->>dst-erc20: 5. Mint n tokens to user
end
```

This diagram illustrates the process where tokens are burned on the source chain and minted on the destination chain, enabling seamless cross-chain transfers without the need for asset wrapping or liquidity pools.
#### Initiating message (source chain)

## Major components
1. The user (or a contract) calls [`SuperchainTokenBridge.sendERC20`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/SuperchainTokenBridge.sol#L52-L78).

* **Token Contract**: implements `SuperchainERC20` with bridging functionality.
* **Bridging Functions**: using methods like `sendERC20` and `relayERC20` for cross-chain transfers.
2. The token bridge calls [`SuperchainERC20.crosschainBurn`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/SuperchainERC20.sol#L37-L46) to burn those tokens on the source chain.

## Comparison to other token implementations
3. The source token bridge calls [`SuperchainTokenBridge.relayERC20`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/SuperchainTokenBridge.sol#L80-L97) on the destination token bridge.
This call is relayed using [`L2ToL2CrossDomainMessenger`](./message-passing).

`SuperchainERC20` differs from other token implementations in its focus and implementation:
#### Executing message (destination chain)

* `SuperchainERC20` implements ERC-7802, which provides a minimal crosschain mint/burn interface designed to be a common pattern for the EVM ecosystem.
* `SuperchainERC20` shares trust assumptions across all chains in the Superchain, such that custom assumptions around security and latency are not required to account for when executing transfers.
4. The user, or a relayer, sends an executing message to [`L2ToL2CrossDomainMessenger`](./message-passing) to relay the message.

<Callout type="info">
Projects moving from other token implementations may need to adapt to the `SuperchainERC20` specification.
</Callout>
5. The destination token bridge calls [`SuperchainERC20.crosschainMint`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/SuperchainERC20.sol#L26-L35) to mint tokens for the user/contract that called `SuperchainTokenBridge.sendERC20` originally.

## Requirements

## Consistent addresses across chains
Application developers must do two things to make their tokens `SuperchainERC20` compatible.
Doing this setup now ensures that tokens benefit from interop (once it is available).
qbzzt marked this conversation as resolved.
Show resolved Hide resolved

It is best to use predefined addresses: Assign and verify the same address for each `SuperchainERC20` instance on every chain. Predefined addresses reduce deployment conflicts and ensure tokens are accurately recognized across chains. Otherwise, the `SuperchainERC20Bridge` would need a way to verify if the tokens they mint on destination, correspond to the tokens that were burned on source.
* Grant permission to `SuperchainTokenBridge` (address `0x4200000000000000000000000000000000000028`) to call `crosschainMint` and `crosschainBurn`.
If you are using [`SuperchainERC20`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/SuperchainERC20.sol) this is already done for you.

Consider using `Create2Deployer` or one of our [predeploys](https://specs.optimism.io/interop/predeploys.html) to ensure this.
{/*

Link to tutorial here

*/}

## Implementation details
* Deploy the ERC-20 contract at the same address on every chain in the Superchain.
This is easiest when using [`create2`](https://book.getfoundry.sh/tutorials/create2-tutorial).

Application developers must do two things to make their tokens `SuperchainERC20` compatible. Doing this setup now ensures that tokens can benefit from Interop once the Interop upgrade happens.
<Callout type="warning">
To do this securely you must either write the deployer in such a way that only a specific trusted ERC-20 contract, such as `SuperchainERC20`, can be deployed through it,
or call the contract with `CREATE2` directly from an EOA you control.
This is critical because if somebody can deploy a different ERC-20 contract at the same address, on any superchain network, they can mint themselves as many tokens as they'd like and then bridge them to the network where the original ERC-20 contract is located.
</Callout>
qbzzt marked this conversation as resolved.
Show resolved Hide resolved

1. Permission only `SuperchainERC20Bridge` to call `crosschainMint` and `crosschainBurn`.
2. Deployment at same address on every chain in the Superchain using `create2` function.
{/*

For now, application developers should view `SuperchainERC20`as ERC20 tokens with additional built-in functions that allow cross-chain asset movement that will be enabled once Interop goes live.
Add this after the tutorial is written

For step-by-step information on implementing SuperchainERC20, see [Deploy assets using SuperchainERC20](/stack/interop/assets/deploy-superchain-erc20)

<Callout type="warning">
To enable asset interoperability, `SuperchainERC20` must give access to the address where the future `SuperchainERC20Bridge` will live.
*/}

## Comparison to other token implementations

`SuperchainERC20` differs from other token implementations in its focus and implementation:

* `SuperchainERC20` implements ERC-7802, which provides a minimal crosschain mint/burn interface designed to be a common pattern for the EVM ecosystem.
* `SuperchainERC20` uses the shared trust assumptions of the Superchain.
Traffic originating in any of the Superchain's chains is trusted, because all those chains [share the same security standard](https://docs.optimism.io/superchain/standard-configuration).
qbzzt marked this conversation as resolved.
Show resolved Hide resolved

<Callout type="info">
Projects moving from other token implementations may need to adapt to the `SuperchainERC20` specification.
</Callout>

## FAQ

### What happens if I bridge to a chain that does not have the ERC-20 contract?

The initiating message will successfully burn the tokens on the source chain.
However, the executing message will try to call `crosschainMint` on a non-existent contract and fail.
Once a `SuperchainERC20` contract is properly deployed at the destination chain, you can attempt the executing message again and get your tokens.

qbzzt marked this conversation as resolved.
Show resolved Hide resolved
## Next steps

* Watch the [ERC20 to SuperchainERC20 video walkthrough](https://www.youtube.com/watch?v=Gb8glkyBdBA) to learn how to modify an existing ERC20 contract to make it interoperable within the Superchain.
* Explore the [SuperchainERC20 specifications](https://specs.optimism.io/interop/token-bridging.html) for in-depth implementation details.
* Check out the [SuperchainERC20 starter kit](https://github.com/ethereum-optimism/superchainerc20-starter) to get started with implementation.
* Review the [Deploy SuperchainERC20 tutorial](./tutorials/deploy-superchain-erc20) to learn how to deploy a SuperchainERC20.

{/*

Add this back when the tutorial is written.

* Review the [Deploy SuperchainERC20 tutorial](../assets/deploy-superchain-erc20) to learn how to deploy a SuperchainERC20.

*/}
1 change: 0 additions & 1 deletion words.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -162,7 +162,6 @@ Inator
inator
INFLUXDBV
influxdbv
intiating
IPCDISABLE
ipcdisable
ipcfile
Expand Down