Upgradable Contracts Learning Project

This project is dedicated to learning and building upgradable smart contracts on Ethereum and compatible networks like Base. It serves as an educational resource for developers interested in implementing upgradeable contract patterns using Foundry and OpenZeppelin libraries. More contracts and examples will be added over time.

Table of Contents

• What are Upgradable Contracts?
• Types of Upgradable Contracts
• Proxy Methodologies
• Learning Modules
• Examples Included
• Study Resources
• Project Structure
• Getting Started
• Contributing
• License

What are Upgradable Contracts?

Upgradable contracts allow smart contracts to be modified or enhanced after deployment, which is crucial since blockchain data is immutable but contract logic can be updated through proxy patterns. This enables fixing bugs, adding features, and improving functionality without losing the contract's state or address.

Key benefits:

• Bug Fixes: Correct vulnerabilities post-deployment
• Feature Additions: Implement new functionalities
• Optimization: Improve gas efficiency or performance
• Maintenance: Adapt to changing requirements

Types of Upgradable Contracts

1. Transparent Proxy

• Uses a proxy contract that delegates calls to an implementation contract
• Admin can upgrade the implementation address
• Users interact directly with the proxy
• OpenZeppelin provides TransparentUpgradeableProxy

2. UUPS (Universal Upgradeable Proxy Standard)

• Upgrade logic is embedded in the implementation contract itself
• More gas-efficient than transparent proxies
• Implementation contract contains the upgrade function
• OpenZeppelin provides UUPSUpgradeable

3. Beacon Proxy

• Uses a beacon contract that points to the current implementation
• Multiple proxies can share the same beacon
• Allows upgrading multiple contracts simultaneously
• Useful for factory patterns

4. Diamond Pattern (EIP-2535)

• Multi-faceted proxy supporting multiple implementation contracts
• Allows selective upgrades of specific functions
• More complex but highly flexible
• Enables modular contract design

Proxy Methodologies

Delegatecall Mechanism

• Proxies use delegatecall to execute implementation logic in the proxy's context
• State is stored in the proxy contract
• Implementation contracts should not have constructors that initialize state

Storage Layout

• Critical to maintain compatible storage layouts between versions
• Use inheritance and careful slot management
• OpenZeppelin provides utilities for storage gaps

Initialization

• Use initializer modifier instead of constructors
• Prevents re-initialization attacks
• Ensure proper access control for upgrade functions

Security Considerations

• Implement timelocks for upgrades
• Use multi-signature wallets for admin functions
• Thoroughly test upgrade mechanisms
• Consider using formal verification

Learning Modules

This project is structured as a progressive learning path for understanding upgradable contracts:

Module 1: Proxy Fundamentals

• Delegatecall Mechanism: Understanding how proxies execute logic in their own context
• Storage Layout: Critical concepts for maintaining state compatibility
• Initialization Patterns: Using initializer instead of constructors

Module 2: Basic Proxy Implementation

• SmallProxy.sol: A minimal proxy contract demonstrating core concepts
• DelegateCallExample.sol: Practical examples of delegatecall usage
• State Management: How to handle contract state across upgrades

Module 3: OpenZeppelin Upgradeable Contracts

• Transparent Proxy Pattern: Using TransparentUpgradeableProxy
• UUPS Pattern: Implementing UUPSUpgradeable for gas efficiency
• Beacon Pattern: Understanding shared implementation contracts

Module 4: Advanced Patterns

• Box Contract Example: V1 to V2 upgrade demonstration
• Factory Patterns: Creating multiple upgradeable instances
• Access Control: Admin roles and upgrade permissions

Module 5: Security & Best Practices

• Common Vulnerabilities: Avoiding upgrade-related security issues
• Testing Strategies: Comprehensive testing for upgradeable contracts
• Audit Considerations: What auditors look for in upgradeable systems

Examples Included

Core Examples

• SmallProxy.sol: Minimal proxy implementation for learning delegatecall
• DelegateCallExample.sol: Demonstrates delegatecall functionality and state management
• BoxV1.sol & BoxV2.sol: Complete upgrade example showing version transitions

OpenZeppelin Integration

• Integration with openzeppelin-contracts-upgradeable
• Foundry upgrades plugin (openzeppelin-foundry-upgrades)
• Deployment and verification scripts

Test Coverage

• Unit tests for all contract functionality
• Upgrade-specific test scenarios
• Security-focused test cases

Study Resources

Documentation

• OpenZeppelin Upgrades Documentation
• EIP-1967: Proxy Storage Slots
• EIP-1822: Universal Upgradeable Proxy Standard

Learning Paths

1. Beginner: Start with SmallProxy.sol and DelegateCallExample.sol
2. Intermediate: Study BoxV1/V2 upgrade pattern
3. Advanced: Implement custom upgradeable contracts with security considerations

Key Concepts to Master

• Delegatecall vs Call: Understanding execution contexts
• Storage Slots: EIP-1967 standard for proxy storage
• Initialization Guards: Preventing re-initialization attacks
• Upgrade Authorization: Who can upgrade and when

Recommended Reading

• "Mastering Ethereum" - Chapter on Upgradeable Contracts
• OpenZeppelin blog posts on proxy patterns
• Security audits of major upgradeable contract deployments

Project Structure

├── src/
│   ├── BoxV1.sol                    # Version 1 of upgradeable Box contract
│   ├── BoxV2.sol                    # Version 2 with additional functionality
│   └── sublesson/
│       ├── SmallProxy.sol           # Basic proxy implementation
│       └── DelegateCallExample.sol  # Delegatecall demonstration
├── test/
│   └── ...                          # Comprehensive test suites
├── script/
│   └── ...                          # Deployment and upgrade scripts
├── lib/
│   ├── forge-std/                   # Foundry standard library
│   ├── openzeppelin-contracts/      # Standard OpenZeppelin contracts
│   ├── openzeppelin-contracts-upgradeable/  # Upgradeable contract variants
│   └── openzeppelin-foundry-upgrades/       # Foundry upgrade tools
├── foundry.toml                     # Foundry configuration
├── remappings.txt                   # Import remappings
├── commit-upgradable-contracts.ps1  # Git commit automation script
└── README.md                        # This comprehensive guide

Getting Started

Prerequisites

• Foundry
• Git

Installation

1. Clone the repository:

git clone <repository-url>
cd upgradable-contract-genesis

2. Install dependencies:

forge install

This will install:

• forge-std: Foundry's standard testing library
• openzeppelin-contracts: Standard OpenZeppelin contracts
• openzeppelin-contracts-upgradeable: Upgradeable variants of OpenZeppelin contracts
• openzeppelin-foundry-upgrades: Foundry-specific upgrade tools

Build

forge build

Test

forge test

Format

forge fmt

Gas Snapshots

forge snapshot

Local Development

Start a local Ethereum node:

anvil

Deploy

Deploy using scripts in the script/ directory:

forge script script/YourScript.s.sol --rpc-url <your_rpc_url> --private-key <your_private_key>

How to Study This Project

Recommended Learning Order

1. Start with Fundamentals:

   • Read the theoretical sections above (What are Upgradable Contracts?, Types, Methodologies)
   • Study src/sublesson/SmallProxy.sol - understand the basic proxy mechanism
   • Examine src/sublesson/DelegateCallExample.sol - learn about delegatecall

2. Practice with Examples:

   • Analyze src/BoxV1.sol and src/BoxV2.sol - see a complete upgrade scenario
   • Run the tests to understand expected behavior
   • Try modifying the contracts and see how upgrades work

3. Deep Dive into OpenZeppelin:

   • Explore the upgradeable contracts in lib/openzeppelin-contracts-upgradeable/
   • Study the Foundry upgrade tools in lib/openzeppelin-foundry-upgrades/
   • Implement your own upgradeable contract using these libraries

4. Testing & Security:

   • Review the test files to understand testing patterns for upgradeable contracts
   • Learn about common security pitfalls and how to avoid them

Study Tips

• Experiment: Modify the example contracts and observe the results
• Test Thoroughly: Always run tests after making changes
• Read the Code: Each contract includes detailed comments explaining the concepts
• Build Incrementally: Start simple and gradually add complexity

Questions to Ask While Studying

• Why do we need proxies instead of direct upgrades?
• What happens to contract state during upgrades?
• How does delegatecall differ from regular calls?
• What are the security implications of each pattern?

Contributing

Contributions are welcome! This is a learning project, so feel free to:

• Add new upgradable contract examples
• Improve documentation
• Submit bug fixes
• Enhance test coverage

Please ensure all code follows Solidity best practices and includes comprehensive tests.

License

This project is licensed under the MIT License - see the LICENSE file for details.