Upgrade ERC20 tokens for interop

pages/interop/tutorials/_meta.json

@@ -3,6 +3,7 @@
     "deploy-superchain-erc20": "Deploying a SuperchainERC20",    
     "transfer-superchainERC20": "Transferring a SuperchainERC20",
     "custom-superchain-erc20": "Custom SuperchainERC20 tokens",    
+    "upgrade-to-superchain-erc20": "Upgrade ERC20 for Superchain support",
     "bridge-crosschain-eth": "Bridging native cross-chain ETH transfers",
     "relay-messages-cast": "Relaying interop messages using `cast`",
     "relay-messages-viem": "Relaying interop messages using `viem`",

pages/interop/tutorials/upgrade-to-superchain-erc20.mdx

@@ -0,0 +1,58 @@
+---
+title: Upgrading ERC20 to SuperchainERC20
+lang: en-US
+description: Tutorial on how to take an existing ERC20 and upgrade it to SuperchainERC20.
+topic: Interoperability
+personas: [Developer]
+categories: [Tutorial, Interop]
+content_type: article
+---
+
+import { Callout, Steps, Card, Cards } from 'nextra/components'
+
+<Callout>
+  The SuperchainERC20 standard is ready for production deployments.
+  Please note that the OP Stack interoperability upgrade, required for crosschain messaging, is currently still in active development.
+</Callout>
+
+# Upgrading ERC20 to SuperchainERC20
+
+## Overview
+
+This guide explains how to upgrade an ERC20 to a [`SuperchainERC20`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/SuperchainERC20.sol) that can teleport across the [Superchain interop cluster](/interop/explainer#superchain-interop-cluster) using the [`SuperchainTokenBridge`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/SuperchainTokenBridge.sol) contract. For more information on how it works, [see the explainer](/interop/superchain-erc20).
+
+{/* 
+
+I put this warning here when we don't have it on most pages because this tutorial
+has, IMHO, code that is a lot more likely to be used in production. It doesn't just
+show what is possible, it does the exact job needed.
+
+*/}
+
+There are several ways to upgrade an existing ERC20 for interop, depending on your circumstances:
+
+{/* 
+
+*   If you can upgrade the existing contract, but the address is not available on other chains? In that case, use a custom bridge 
+
+upgrade-to-superchain-erc20/custom-bridge.
+
+*/}
+
+| When To Use                                                 | Action                                                                                                                    |
+| ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| You can install a new ERC20 contract                        | [**Deploy New SuperchainERC20 contracts** directly](/interop/tutorials/deploy-superchain-erc20)                           |
+| Existing ERC20 contract cannot be upgraded                  | [**Implement Lockbox Solution** to bridge between tokens](/interop/tutorials/upgrade-to-superchain-erc20/lockbox)         |
+| You can deploy to other chains using the same proxy address | [**Perform Contract Upgrade** while maintaining address](/interop/tutorials/upgrade-to-superchain-erc20/contract-upgrade) |
+
+<Cards>
+  <Card title="Contract upgrade" href="/interop/tutorials/upgrade-to-superchain-erc20/contract-upgrade" icon={<img src="/img/icons/shapes.svg" />} />
+
+  <Card title="Lockboxes for permissionless interop" href="/interop/tutorials/upgrade-to-superchain-erc20/lockbox" icon={<img src="/img/icons/shapes.svg" />} />
+</Cards>
+
+## Next steps
+
+*   Deploy a [SuperchainERC20](/interop/tutorials/deploy-superchain-erc20) to the Superchain
+*   [Learn more about SuperchainERC20](/interop/superchain-erc20)
+*   Build a [revolutionary app](/app-developers/get-started) that uses multiple blockchains within the Superchain

pages/interop/tutorials/upgrade-to-superchain-erc20/_meta.json

@@ -0,0 +1,4 @@
+{
+    "contract-upgrade": "Contract upgrade"
+    "lockbox": "Lockboxes for permissionless interop",
+}