There are five major proxy upgradeability patterns in Ethereum smart contract development:
- 🧱 Eternal Storage Proxy
- 🔍 Transparent Proxy
- 🔄 UUPS (Universal Upgradeable Proxy Standard)
- 🗼 Beacon Proxy
- 💎 Diamond Proxy (EIP-2535)
While these patterns are widely discussed in theory, practical, minimal-to-advanced implementations are hard to find — especially for beginners. This project fills that gap.
This project aims to educate, guide, and encourage open-source collaboration on the most used smart contract upgradeability patterns. Through minimalistic examples, contributors and learners will gain:
- 💡 Hands-on experience with Solidity and low-level EVM concepts like
delegatecall - 🛠️ Practical exposure to how proxy patterns work under the hood
- 📁 A starter portfolio for open-source contributions
- 🤝 A chance to collaboratively build a modular and scalable resource for the Web3 ecosystem
The goal is not just to teach upgradeability — it’s to demystify it and make it accessible to everyone.
Smart contracts are immutable by default — once deployed, their code can't be changed. But in real-world applications, bugs, feature requests, or protocol upgrades require a way to update logic without losing user data or starting over.
So how do we change an unchangeable contract?
“If you can’t change the logic of a smart contract, change the smart contract.”
— But keep the storage persistent and the user interface the same.
This is made possible by proxy patterns:
Contracts that delegate calls to other contracts, enabling logic upgrades while preserving state.
Key Components:
- Storage Contract: Holds state variables as
mapping(bytes32 => uint256)(key-value pairs) - Logic Contract(s): Contains logic to interact with the storage
- Proxy Contract: Routes user interaction to the logic contract
Flow:
User → Proxy → Logic → Eternal Storage
Purpose: Keeps storage persistent even if logic changes. Useful when you want logic flexibility without losing data.
Key Components:
- Proxy Contract
- Implementation Contract (holds business logic & storage)
- Admin (manages upgrades)
How it works:
- Proxy stores implementation and admin addresses in specific EVM storage slots (defined by EIP-1967).
- Only the admin can upgrade the contract.
- Regular users can only access the implementation logic.
EIP-1967 Storage Slots:
// Implementation
bytes32(uint256(keccak256("eip1967.proxy.implementation")) - 1)
// Admin
bytes32(uint256(keccak256("eip1967.proxy.admin")) - 1)Benefit: Separation of concerns — clear distinction between admin and user.
Difference from Transparent Proxy:
- Upgrade function is placed inside the implementation (not in the proxy).
- Only one storage slot for implementation is required.
- Cheaper deployment compared to Transparent Proxy.
Warning: Implementation contracts must include upgrade logic. If omitted or implemented incorrectly, further upgrades will be blocked.
Key Components:
- Beacon Contract: Stores the address of the implementation
- Proxy Contract(s): Refer to the beacon for logic
- Implementation Contract: Contains business logic
Flow:
Multiple Proxies → Beacon → Implementation
Benefit: A single beacon can update logic for multiple proxies, saving gas and simplifying upgrades in systems with many instances (like DeFi protocols or NFTs).
The most modular and complex pattern.
Key Concepts:
- Diamond (Proxy): Routes function selectors to multiple implementation contracts
- Facets (Implementations): Contain chunks of logic (functions)
- DiamondCut: Mechanism to add/replace/remove facets
Why use it?
- Split logic into modules
- Upgrade and manage large contracts without storage collisions
- Used in projects like Aavegotchi, Uniswap V3, etc.
Upgradeability isn’t just a theoretical concept — it powers real, large-scale Web3 projects:
- OpenZeppelin provides production-ready upgradable contracts
- Uniswap used proxy patterns to evolve V2 → V3 without users losing funds
- DAO governance and decentralized upgradability are based on these patterns
Understanding and mastering proxy patterns prepares you for building scalable, secure, and maintainable smart contracts in the real world.
- Star ⭐ the repo
- Go to contributing tab(https://github.com/GHexxerBrdv/Upgrade-Proxy?tab=contributing-ov-file)
This project is for learners, by learners. Whether you're new to Solidity or want to deepen your knowledge of proxy patterns — your contributions and curiosity are welcome.
Let’s collaborate, explore the EVM together, and contribute meaningfully to the open-source Web3 space.