How upgradable contracts work in Solidity
A guide to the various ways you can have upgradable smart contracts, and the pros and cons about them
Table of Contents for How upgradable contracts work in Solidity
Smart contracts are immutable. Once you have deployed it, the code can’t change. You can however change the data stored in the smart contract (storage data), and you can use clever tricks to change what code is executed.
This is known as upgrading your smart contract.
There are a few well known and well used patterns when it comes to upgrading your smart contracts.
Split into two layers: Proxy layer (storage) & Implementation layer (code)
A basic upgradable smart contract pattern that you often see is where one smart contract just acts as a proxy, and forwards all calls to an actual implementation contract.
Proxy (storage layer)
The proxy smart contract is initially deployed with a variable pointing to the (first) implementation contract address.
Implementation (code layer)
All function calls gets proxied through the proxy, and are called on the implementation contract address.
This will often use delegatecall so the code executes in the context of the proxy.
Then when it is time to upgrade, a new implementation is deployed, and new calls to the proxy will run the new implementation code. There are a few ways the upgrade often happens, described below.
Transparent vs UUPS proxy
- Transparent proxies were the original ones seen in smart contracts
- “Universal Upgradeable Proxy” or just UUPS, were introduced in EIP-1822
- In UUPS the upgrading of implementation is handled by the (current) implementation, and also has an option of being removed.
- Transparent proxies handle the upgrade in the proxy (not implementation).
- Because in UUPS the implementations handle the upgrading, it is important that every upgraded smart contract has logic in the new implementation to allow future upgrades. This means more complex implementations.
- transparent proxy deployments are more expensive, as they hold more logic about upgrading
- transparent proxies are also easier to work with, and if you are reading this as an introduction to upgrading smart contracts I’d recommend you play with transparent proxies first.
This post is incomplete and a work-in-progress
I'll update it soon and flesh it out with more info!
Spotted a typo or have a suggestion to make this crypto dev article better? Please let me know!
📙 Solidity Auditing online quiz
Learn how to audit smart contracts by looking at some example code and trying to find the bugs
⛽ Solidity Gas Optimizations Guide
How to optimize and reduce gas usage in your smart contracts in Solidity
🧪 Guide to testing with Foundry
Guide to adding testing for your Solidity contracts, using the Foundry and Forge tools
📌 Guide to UTXO
UTXO and the UTXO set (used by blockchains such as Bitcoin) explained
📐 Solidity Assembly Guide
Introduction guide to using assembly in your Solidity smart contracts
📦 Ethereum EOF format explained
Information explaining what the upcoming Ethereum EOF format is all about