Superchain Starter Kit

A lightweight, focused starting point for prototyping/building on the Superchain, featuring

• 🛠 foundry, supersim, super-cli
• 🎨 wagmi, viem
• @eth-optimism/viem, @eth-optimism/wagmi - viem/wagmi extensions for the Superchain
• 💡 simple example app - CrossChainCounter

🚀 Getting started

Get prototyping Superchain apps in under < 1 min! ❤️‍🔥

Prerequisites: Foundry & Node

Follow this guide to install Foundry

1. Create a new repository using this template:

Click the "Use this template" button above on GitHub, or generate directly

2. Clone your new repository

git clone <your-new-repository-url>
cd <your-new-repository>

3. Install dependencies

pnpm i

4. Get started

pnpm dev

This command will:

• Start a local Superchain network (1 L1 chain and 2 L2 chains) using supersim
• Launch the frontend development server at (http://localhost:5173)
• Deploy the smart contracts to your local network

Start building on the Superchain!

Deploying contracts

The starter kit uses super-cli (or sup) to streamline contract deployment across the Superchain ecosystem. sup works great with Foundry projects while eliminating common multichain friction points:

• 🔄 Foundry Compatible: Seamlessly works with your existing Foundry setup and artifacts
• ⛓️ Multi-Chain: Deploy to multiple chains with a single command and pre-configured RPCs
• ⛽ Gasless Deployments: Instead of having to bridge to n chains
• 🎯 Interactive mode: No more complex command-line arguments

Alternatively, if you want to use Forge scripts directly, follow the multichain deployment example at contracts/script/Deploy.s.sol

Deploying

Once you're ready to deploy, start sup in interactive mode

pnpm sup

Then you can follow the steps to deploy to supersim or the interop-alpha devnet

🚀 Deploy Create2 Wizard

 ✓  Enter Foundry Project Path ./contracts/
 ✓  Select Contract CrossChainCounter.sol
 ✓  Configure Constructor Arguments
 ✓  Configure Salt ethers phoenix
 ✓  Select Network interop-alpha
 ✓  Select Chains interop-alpha-0, interop-alpha-1
 >  Verify Contract

Press ← to go back

 Do you want to verify the contract on the block explorer? Y/n

Non-interactive mode

You can also skip the interactive mode entirely by passing the necessary arguments

pnpm sup deploy create2 --chains supersiml2a,supersiml2b --salt ethers phoenix --forge-artifact-path contracts/out/CrossChainCounter.sol/CrossChainCounter.json --network supersim --private-key 0x5de4111afa1a4b94908f83103eb1f1706367c2e68ca870fc3fb9a804cdab365a

--prepare mode

To "prepare" a command without running it, run sup with the prepare mode. This will print the command instead of running it. Then you can run the prepared command directly to run immediately in non-interactive mode.

pnpm sup --prepare

Make sure to build before deploying

sup assumes that your foundry project has already been built. Make sure to build before attempting to deploy

pnpm build:contracts

👀 Overview

Example app

CrossChainCounter contract

• Simple Hello world for Superchain Interop
• Unlike the single chain Counter, this one can only be incremented via cross-chain messages
• Learn more about this contract here

Tools

• supersim: Local test environment with 1 L1 and multiple L2 chains, includes pre-deployed Superchain contracts
• sup (super-cli): Deploy and verify contracts across multiple chains, with sponsored transactions
• foundry: Blazing fast smart contract development framework
• wagmi / viem: Best in class Typescript library for the EVM,
• vite / tailwind / shadcn: Frontend development tools and UI components

📁 Directory structure

This starter kit is organized to get you building on the Superchain as quickly as possible. Solidity code goes in /contracts, and the typescript frontend goes in /src

superchain-starter/
├── contracts/                   # Smart contract code (Foundry)
├── src/                        # Frontend code (vite, tailwind, shadcn, wagmi, viem)
│   └── App.tsx                # Main application component
├── public/                     # Static assets for the frontend
├── supersim-logs/             # Local supersim logs
├── package.json               # Project dependencies and scripts
└── mprocs.yaml               # Run multiple commands using mprocs

A note on project structure

While this structure is great for getting started and building proof of concepts, it's worth noting that many production applications eventually migrate to separate repositories for contracts and frontend code.

For reference, here are some examples of this separation in production applications:

• Uniswap: Uniswap contracts, Uniswap frontend
• Across: Across contracts, Across frontend
• Farcaster: Farcaster contracts

📚 More resources

• Interop recipes / guides: https://docs.optimism.io/app-developers/tutorials/interop
• Superchain Dev Console: https://console.optimism.io/

😎 Moooaaar examples

Want to see more? Here are more example crosschain apps for inspiration / patterns!

• ⚡ Crosschain Flash Loan
  • Dependent cross-chain messages (compose multiple cross-domain messages)
  • Using SuperchainTokenBridge for cross-chain ERC20 transfers
  • Multichain lending vaults using L2ToL2CrossDomainMessenger
• 💸 Multisend
  • How to set up cross-chain callbacks (contract calling itself on another chain)
  • Using SuperchainWETH for cross-chain ETH transfers
  • Dependent cross-chain messages (compose multiple cross-domain messages)
• 🪙 SuperchainERC20
  • Using ERC-7802 interface for SuperchainERC20 tokens
  • How to upgrade existing ERC20s into SuperchainERC20
  • Minting supply on only one chain
  • Deterministic address deployment on all chains
• 🏓 CrossChainPingPong
  • Simple example of passing state between multiple chains using cross domain messenger
  • How to set up cross-chain callbacks (contract calling itself on another chain)
• 🕹️ CrossChainTicTacToe
  • Allows players to play each other from any chain without cross-chain calls, instead relying on cross-chain event reading
  • Creating horizontally scalable apps with interop

⚖️ License

Files are licensed under the MIT license.