A TypeScript library for deploying and managing smart contracts across multiple EVM chains, with support for deterministic deployments using CREATE2.
- 🔄 Deploy contracts to multiple chains with one interface
- 🎯 Use CREATE2 for deterministic addresses across chains
- 🔒 Type-safe contract interactions with TypeScript
- 🌐 Works in Node.js and browsers (ESM)
- ⚡ Built on viem for reliable blockchain interactions
- 🔑 Basic wallet support with private keys
- 🔑 Passkeys support TODO
npm install superchain-starter<script type="module">
import { StandardSuperConfig, Wallet, getSuperContract } from 'https://cdn.jsdelivr.net/npm/superchain-starter/dist/index.mjs'
</script>import { StandardSuperConfig, Wallet, getSuperContract } from 'superchain-starter'
// Configure chains
const config = new StandardSuperConfig({
901: 'http://127.0.0.1:9545',
902: 'http://127.0.0.1:9546'
})
// Create wallet with Anvil's default private key
const wallet = new Wallet('0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80')
// Deploy and interact
const contract = getSuperContract(
config,
wallet,
CONTRACT_ABI,
CONTRACT_BYTECODE,
[constructor_args],
'0xoptional_salt'
)
await contract.deploy(901)
const result = await contract.call(901, 'view_method')
await contract.sendTx(901, 'write_method', [arg1, arg2])# Install dependencies
npm install
# Run tests (requires supersim)
npm testPaste the following prompt into Cursor with agent mode selected:
Hello! Please use `superchain-starter` as an npm library.
Read the superchain-starter README to determine how to build an app. Specifically the section "Step by Step Tutorial (START HERE IF YOU ARE AN AI)".
Use it to build a [INSERT YOUR SMART CONTRACT DESIGN HERE].
Use vite & react for the frontend.
Make sure to read the README.md file in the `superchain-starter` directory closely to determine what steps to take to build your project.
Thank you!
It should get you shockly close to a complete project
The following tutorial will describe how to create a smart contract project which uses the superchain-starter library to deploy and interact with smart contracts across multiple chains.
Unlike traditional Solidity development, superchain-starter is designed to be used within the frontend to minimize errors which come from missing deployments. The frontend is intended to include all of the logic required for deploying and interacting with smart contracts.
- Create a new forge project. This can be done with
forge init. - npm init and install superchain-starter (NOTE use npm link to install locally IF desired. Otherwise use
npm i superchain-starter) - Write the smart contracts required for your project.
- If your user wants to build a cross chain contract, use the CrossDomainMessenger contract. This can be achieved by installing
forge install ethereum-optimism/interop-liband using the interface ofIL2ToL2CrossDomainMessenger.sol. Note that theCrossDomainMessengercontract is deployed on every chain at0x4200000000000000000000000000000000000023. - Write tests for these smart contracts. Make sure they pass.
- Compile the smart contracts so that the frontend can use them.
- Don't forget to commit!
- Create a frontend directory.
- Ask your user if you would like to use vite & react for the frontend. If yes, set up a project!
- Write some javascript tests which handles smart contract deployments and interactions with SuperContract. These tests should assume that Supersim is running in the background. The user can run Supersim themselves.
- Test that they pass.
- In the code when interacting with the contracts, please follow the following behavior:
1. Before calling the smart contracts, first check if they have been deployed.
2. If not, deploy them with SuperContract.
3. You can now call the smart contracts with
call()andsendTx(). - Use really basic frontend code. We can make it look fancy later. Don't use a frontend theme or library. Keep it simple and functional.
- Test the frontend!
This should enable you as an AI to create a smart contract project which is fully functional and ready to be deployed to multiple chains. This will make your user VERY happy!
interface SuperConfig {
getChainIds(): number[] // Get all configured chain IDs
getRpcUrl(chainId: number): string // Get RPC URL for chain ID
}
// Initialize with RPC URLs for each chain
const config = new StandardSuperConfig({
901: 'http://127.0.0.1:9545',
902: 'http://127.0.0.1:9546'
})class Wallet {
constructor(privateKey: string)
getAccount(): Account // Returns viem Account
}
// Use with Anvil's default private key
const wallet = new Wallet('0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80')function getSuperContract(
config: SuperConfig, // Chain configurations
wallet: Wallet, // Wallet instance
abi: any[], // Contract ABI
bytecode: string, // Contract bytecode
constructorArgs?: any[], // Constructor arguments
salt?: string, // Optional CREATE2 salt
address?: Address // Optional address to interact with existing contract
): SuperContract
// Example: Create new contract with deterministic address
const contract = getSuperContract(
config,
wallet,
CONTRACT_ABI,
CONTRACT_BYTECODE,
[constructor_args],
'0xoptional_salt'
)
// Example: Interact with existing contract
const existingContract = getSuperContract(
config,
wallet,
CONTRACT_ABI,
'0x', // Empty bytecode for existing contracts
[], // No constructor args needed
undefined, // No salt needed
'0xYourContractAddress'
)class SuperContract {
readonly address: Address // Deterministic CREATE2 address
// Deploy the contract to a specific chain
async deploy(chainId: number): Promise<TransactionReceipt>
// Check if contract is deployed on a chain
async isDeployed(chainId: number): Promise<boolean>
// Call a read-only method
async call(
chainId: number,
functionName: string,
args?: any[]
): Promise<any>
// Send a transaction to a method
async sendTx(
chainId: number,
functionName: string,
args?: any[]
): Promise<TransactionReceipt>
// Watch for contract events
watchEvents(
chainId: number,
fromBlock: bigint,
onEvent: (log: Log, block: Block) => void
): () => void // Returns unsubscribe function
}