A secure, minimal bridge implementation for Custom Gas Token (CGT) functionality on OP Stack chains.

This project implements a bridge system that enables OP Stack L2 chains to use custom assets as their native gas token instead of ETH. The bridge manages the conversion between L1 ERC20 tokens and L2 native CGT.

L1 Bridge (L1CGTBridge)

• Locks L1 ERC20 tokens on deposit
• Unlocks tokens on withdrawal from L2
• Communicates with L2 via CrossDomainMessenger
• Tracks total locked tokens to ensure 1:1 backing

L2 Bridge (L2CGTBridge)

• Mints native CGT when L1 tokens are deposited
• Burns native CGT on withdrawal requests
• Authorized as minter on LiquidityController predeploy
• Ensures total bridged amount matches L1 locked amount

LiquidityController Integration

• L2 predeploy at 0x420000000000000000000000000000000000002a
• Manages native asset supply via authorized minters
• L2CGTBridge must be authorized to mint/burn native assets

• Pausable: Emergency pause mechanism on both L1 and L2
• Reentrancy Protection: All external functions protected against reentrancy
• Access Control: Owner-based permissions for critical operations
• Supply Tracking: Maintains accounting invariants across layers

This implementation follows the new CGT design principles:

• Minimal: Single isCustomGasToken() flag disables ETH transfers
• Token-agnostic: Works with any ERC20 token, L2-native tokens, or tokens without ERC20 representation
• Decoupled: Bridge lives at application layer, not enshrined in protocol
• Flexible: Supports various bridging mechanisms and supply models

See CGT_SPECS.md for complete design rationale and architecture diagrams.

Current Status: Initial security review completed with hardening recommendations implemented.

Key security features:

• Reentrancy guards on all state-changing functions
• SafeERC20 for token operations
• Pausable emergency controls
• Ownership-based access control
• Supply invariant checks

See SECURITY_REVIEW.md for detailed security analysis and audit recommendations.

• Foundry
• Two Anvil instances (for L1 and L2)

forge build

forge test

Run with verbose output:

forge test -vvv

forge fmt

Check formatting:

forge fmt --check

For local testing with Anvil, see the Deployment Guide.

The deployment process uses two scripts:

1. DeployL2.s.sol - Deploy L2 bridge first
2. DeployL1.s.sol - Deploy L1 bridge with L2 address

src/ ├── L1/ │ ├── L1CGTBridge.sol # L1 bridge implementation │ └── interfaces/ # L1 interface definitions ├── L2/ │ ├── L2CGTBridge.sol # L2 bridge implementation │ └── interfaces/ # L2 interface definitions └── libraries/ ├── BridgeErrors.sol # Custom error definitions └── Predeploys.sol # Predeploy address constants 

• CGT Specification - Complete design rationale and architecture
• Security Review - Security analysis and recommendations
• Deployment Guide - Local deployment instructions
• Requirements - Original project requirements

MIT