Rewrite the SuperchainERC20 page

pages/stack/interop/superchain-erc20.mdx

@@ -6,94 +6,137 @@ description: Learn about the basic details of the SuperchainERC20 implementation
 
 import { Callout } from 'nextra/components'
 
+import { InteropCallout } from '@/components/WipCallout'
+
+<InteropCallout />
+
 # SuperchainERC20
 
-<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>
+The [`SuperchainERC20`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/SuperchainERC20.sol) contract implements [ERC-7802](https://ethereum-magicians.org/t/erc-7802-crosschain-token-interface/21508) to enable asset interoperability within the Superchain. 
+
+Asset interoperability allows tokens to move securely across the Superchain by burning tokens on the source chain and minting an equivalent amount on the destination chain. This approach addresses issues such as liquidity fragmentation and poor user experiences caused by asset wrapping or reliance on liquidity pools.
+
+Instead of wrapping assets, this mechanism effectively "teleports" tokens between chains in the Superchain. It provides users with a secure and capital-efficient method for transacting across chains.
 
-`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.
 
 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.
 
-## Consistent addresses across chains
+## Requirements
 
-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.
+Application developers must complete two steps to make their tokens compatible with `SuperchainERC20`. 
+Setting this up in advance ensures tokens will benefit from interop when it becomes available.
 
-Consider using `Create2Deployer` or one of our [predeploys](https://specs.optimism.io/interop/predeploys.html) to ensure this.
+*   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.
 
-## Implementation details
+      {/* 
 
-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.
+      Add this after the tutorial is written
 
-1.  Permission only `SuperchainERC20Bridge` to call `crosschainMint` and `crosschainBurn`.
-2.  Deployment at same address on every chain in the Superchain using `create2` function.
+For detailed, step-by-step instructions on implementing SuperchainERC20, refer to [Deploy assets using SuperchainERC20](/stack/interop/assets/deploy-superchain-erc20).
 
-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.
+      */}
 
-For step-by-step information on implementing SuperchainERC20, see [Deploy assets using SuperchainERC20](/stack/interop/assets/deploy-superchain-erc20)
+*   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).
 
 <Callout type="warning">
-  To enable asset interoperability, `SuperchainERC20` must give access to the address where the future `SuperchainERC20Bridge` will live.
+To ensure security, you must either design the deployer to allow only a specific trusted ERC-20 contract, such as `SuperchainERC20`, to be deployed through it, or call `CREATE2` to deploy the contract directly from an EOA you control. 
+
+This precaution is critical because if an unauthorized ERC-20 contract is deployed at the same address on any Superchain network, it could allow malicious actors to mint unlimited tokens and bridge them to the network where the original ERC-20 contract resides.
+</Callout>
+
+
+## Comparison to other token implementations
+
+`SuperchainERC20` differs from other token implementations in both focus and design:
+
+*   It implements `ERC-7802`, a minimal cross-chain mint/burn interface designed to establish a common standard across the EVM ecosystem.  
+*   It relies on the shared trust assumptions of the Superchain. All traffic originating from any chain within the Superchain is trusted because these chains [share the same security standard](/superchain/standard-configuration).
+
+
+<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 fail because it attempts to call `crosschainMint` on a non-existent contract. 
+Once a `SuperchainERC20` contract is properly deployed on the destination chain, you can retry the executing message to retrieve your tokens.
 ## 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.
+
+*/}

words.txt

@@ -162,7 +162,6 @@ Inator
 inator
 INFLUXDBV
 influxdbv
-intiating
 IPCDISABLE
 ipcdisable
 ipcfile