Skip to main content

SuperchainERC20

note

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.

Overview​

What is SuperchainERC20?​

The SuperchainERC20 contract implements ERC-7802 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.

Prerequisites​

Deploying a SuperchainERC20 Token​

In this section, you will deploy a new SuperchainERC20 token to Soneium Minato.

  1. Clone the SuperchainERC20 Starter Kit repository:

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

  1. Install project dependencies using pnpm:

    pnpm i

  1. Initialize .env files:

    pnpm init:env

  1. Setup deployment config (RPC URLs and token info):

    This script automatically fetches the public RPC URLs for each chain listed in the Superchain Registry and adds 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 the script, run:

    pnpm contracts:update:rpcs

    Now, open the file packages/contracts/configs/deploy-config.toml and add sepolia/soneium-minato to the chains array within the [deploy_config] section, as shown below:

    packages/contracts/configs/deploy-config.toml
    [deploy_config]
    salt = "ethers phoenix"
    chains = ["sepolia/soneium-minato"]

    [token]
    owner_address = "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266"
    name = "TestSuperchainERC20"
    symbol = "TSU"
    decimals = 18
    note

    If you want to deploy to Soneium mainnet, use mainnet/soneium instead.

    In the [token] section modify the data according to your needs.

    • owner_address: The address designated as the owner of the token.
      • The L2NativeSuperchainERC20.sol contract included in the superchainerc20-starter repository extends the Ownable contract.
      • example: owner_address = 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266
    • name: The token's name.
      • example: name = TestSuperchainERC20
    • symbol: The token's symbol.
      • example: symbol = TSU
    • decimals: The number of decimal places the token supports.
      • example: decimals = 18

  1. Set up your deployer private key:

    echo 'DEPLOYER_PRIVATE_KEY=<YOUR PRIVATE KEY>' > packages/contracts/.env
    warning

    Never share your private key. It grants full access to your wallet.

    tip

    Refer to the MetaMask documentation for instructions on exporting your account's private key.

    tip

    To use a Ledger or Trezor hardware wallet for this process, refer to the Foundry documentation for detailed instructions on private key management.

  1. Deploy your token:

    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.

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.

Further Reading​

For more information about the SuperchainERC20 implementation, please refer to the following pages:

On This Page