Interoperability
SuperchainERC20 starter kit
💡

The SuperchainERC20 standard is ready for production use with active Mainnet deployments. Please note that the OP Stack interoperability upgrade, required for crosschain messaging, is currently still in active development.

Deploying a SuperchainERC20 (Starter Kit)

The SuperchainERC20 Starter Kit (opens in a new tab) is a development toolkit designed to simplify the creation, deployment, and testing of SuperchainERC20 tokens. It leverages cross-chain interoperability for the deployment of ERC20 tokens that can be used across different blockchains in the Superchain ecosystem.

How it works

Here's a breakdown of what's under the hood:

  • Cross-Chain Interoperability: SuperchainERC20 tokens can move across multiple chains. This is possible by using the IERC-7802 (opens in a new tab) interface, which lets tokens be minted on one chain and burned on another to maintain a consistent supply.

  • Superchain Network: The Superchain is a network of connected blockchains, allowing smooth data and asset flow. By using Optimism's scaling solutions, the Superchain reduces gas fees and speeds up transactions.

  • Deployment: The kit helps deploy SuperchainERC20 tokens on Ethereum-compatible chains, including setting up contracts, minting, burning, and cross-chain communication.

  • Testing: Test scripts simulate real token transfers across chains to ensure everything works properly before going live.

Setup

Install foundry

supersim requires anvil to be installed.

Follow the Foundry toolchain (opens in a new tab) guide for detailed instructions.

Clone the repo

Next, you need to clone and navigate to the repo:

git clone https://github.com/ethereum-optimism/superchainerc20-starter.git
cd superchainerc20-starter

Install dependencies

Install project dependencies using pnpm:

pnpm i

Initialize .env files

pnpm init:env

Start the development environment

This command will:

  • Start the supersim local development environment
  • Deploy the smart contracts to the test networks
  • Launch the example frontend application
pnpm dev
Sanity check

Browse to the console (opens in a new tab), mint some tokens and transfer them.

Deploy SuperchainERC20s

Configure RPC urls

This repository includes a script to automatically fetch the public RPC URLs for each chain listed in the Superchain Registry (opens in a new tab) and add them to the [rpc_endpoints] configuration section of foundry.toml.

The script ensures that only new RPC URLs are appended, preserving any URLs already present in foundry.toml. To execute this script, run:

pnpm contracts:update:rpcs

Modify deploy config parameters

The deployment configuration for token deployments is managed through the deploy-config.toml file. Below is a detailed breakdown of each configuration section:

[deploy-config]

This section defines parameters for deploying token contracts.

ParameterDescriptionExample
saltA unique identifier used for deploying token contracts via [Create2]. This value along with the contract bytecode ensures that contract deployments are deterministic.salt = "ethers phoenix"
chainsLists the chains where the token will be deployed. Each chain must correspond to an entry in the [rpc_endpoints] section of foundry.toml.chains = ["op_chain_a","op_chain_b"]

[token]

Deployment configuration for the token that will be deployed.

ParameterDescriptionExample
owner_addressThe address designated as the owner of the token. The L2NativeSuperchainERC20.sol contract included in this repo extends the Ownable (opens in a new tab) contract.owner_address = "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266"
nameThe token's name.name = "TestSuperchainERC20"
symbolThe token's symbol.symbol = "TSU"
decimalsThe number of decimal places the token supports.decimals = 18

Deploy a token

  • Before proceeding, ensure that your deploy-config.toml file is fully configured (see the Modify Deploy Config Parameters section setup details).
  • Also, confirm that the [rpc_endpoints] section in foundry.toml is properly set up by following the instructions in Configure RPC urls.
💡

Deployments are executed through the SuperchainERC20Deployer.s.sol script. This script deploys tokens across each specified chain in the deployment configuration using Create2, ensuring deterministic contract addresses for each deployment. The script targets the L2NativeSuperchainERC20.sol contract by default. If you need to modify the token being deployed, either update this file directly or point the script to a custom token contract of your choice.

  • To execute a token deployment run:
pnpm contracts:deploy:token

Best practices for deploying SuperchainERC20

Use Create2 to deploy SuperchainERC20

Create2 ensures that the address is deterministically determined by the bytecode of the contract and the provided salt. This is crucial because in order for cross-chain transfers of SuperchainERC20s to work with interop, the tokens must be deployed at the same address across all chains.

Set safe crosschainMint and crosschainBurn permissions

For best security practices SuperchainERC20Bridge should be the only contract with permission to call crosschainMint and crosschainBurn. These permissions are set up by default when using the SuperchainERC20 contract.

Next Steps