@tokamak-network/thanos-contracts

Thanos Smart Contracts

This package contains the L1 and L2 contracts and components to build the Thanos. We can use ERC20 token as L2 native token after modifying configuration in deploy-config.

Directory Structure

├── deploy-config: Pre-defined deployment configuration on each network
├── deployments: Information about the contracts deployed on each network
├── genesis: Deployed contract address list, L2 Genesis file, Rollup configuration on each network
├── uniswap-v3-artifacts: Hardhat artifacts for Uniswap V3
├── invariant-docs: Documentation for all defined invariant tests
├── lib: External libraries with Git submodules
├── scripts: Deploy Scripts
├── src: Contracts
│   ├── L1: Contracts deployed on the L1
│   ├── L2: Contracts deployed on the L2
│   ├── cannon: Contracts for cannon
│   ├── dispute: Contracts for dispute game
│   ├── libraries: Libraries
│   │    └── Predeploys.sol: Pre-deployed contract addresses on L2 Genesis
│   ├── tokamak-contracts
│   │    └── USDC: Contract for USDC bridge
│   └── universal: Universal contracts
├── test: Contracts for unit test
├── foundry.toml: Foundry configuration
├── hardhat.config.ts: Hardhat configuration
...

Contracts Overview

Contracts deployed to L1

Name	Proxy Type	Description
L1CrossDomainMessenger	ResolvedDelegateProxy	High-level interface for sending messages to and receiving messages from Thanos
L1StandardBridge	L1ChugSplashProxy	Standardized system for transferring ERC20 tokens to/from Thanos
L2OutputOracle	Proxy	Stores commitments to the state of Thanos which can be used by contracts on L1 to access L2 state
OptimismPortal	Proxy	Low-level message passing interface supported L2 output root
OptimismPortal2	Proxy	Low-level message passing interface supported fault proof
OptimismMintableERC20Factory	Proxy	Deploys standard OptimismMintableERC20 tokens that are compatible with either StandardBridge
ProxyAdmin	-	Contract that can upgrade L1 contracts

Contracts deployed to L2

Name	Proxy Type	Description
GasPriceOracle	Proxy	Stores L2 gas price configuration values
L1Block	Proxy	Stores L1 block context information (e.g., latest known L1 block hash)
L2CrossDomainMessenger	Proxy	High-level interface for sending messages to and receiving messages from L1
L2StandardBridge	Proxy	Standardized system for transferring ERC20 tokens to/from L1
L2ToL1MessagePasser	Proxy	Low-level message passing interface
SequencerFeeVault	Proxy	Vault for L2 transaction fees
OptimismMintableERC20Factory	Proxy	Deploys standard OptimismMintableERC20 tokens that are compatible with either StandardBridge
ProxyAdmin	-	Contract that can upgrade L2 contracts when sent a transaction from L1

Installation

We export contract ABIs, contract source code, and contract deployment information for this package via pnpm:

pnpm install @tokamak-network/thanos-contracts

Build

We can build the package in the monorep using pnpm

# Install dependencies
pnpm install

# Compile the contracts and make artifacts
pnpm build

Test

We are able to run unit tests for all contracts within the package. The files used for testing are located in the test directory. Please refer to Test Options for more forge test options.

# Run the unit test all contracts in this package
pnpm test

# Run the unit test for specific contract
forge test --match-contract <contract-name>

Deployment

The smart contracts are deployed using foundry with a hardhat-deploy compatibility layer. When the contracts are deployed, they will write a temp file to disk that can then be formatted into a hardhat-deploy style artifact by calling another script.

Configuration

Create or modify a file <network-name>.json inside of the deploy-config folder. By default, the network name will be selected automatically based on the chainid. Alternatively, the DEPLOYMENT_CONTEXT env var can be used to override the network name. The IMPL_SALT env var can be used to set the create2 salt for deploying the implementation contracts.

Execution

1. Set the env vars ETH_RPC_URL, PRIVATE_KEY and ETHERSCAN_API_KEY if contract verification is desired
2. Deploy the contracts with forge script -vvv scripts/Deploy.s.sol:Deploy --rpc-url $ETH_RPC_URL --broadcast --private-key $PRIVATE_KEY Pass the --verify flag to verify the deployments automatically with Etherscan.
3. Generate the hardhat deploy artifacts with forge script -vvv scripts/Deploy.s.sol:Deploy --sig 'sync()' --rpc-url $ETH_RPC_URL --broadcast --private-key $PRIVATE_KEY

Deploying a single contract

All of the functions for deploying a single contract are public meaning that the --sig argument to forge script can be used to target the deployment of a single contract.

Static Analysis

contracts-bedrock uses slither as its primary static analysis tool. Slither will be run against PRs as part of CI, and new findings will be reported as a comment on the PR.