Smart Contract Versioning

How to Write Upgradable Smart Contracts Smart contracts are , by design. On the other hand, software quality heavily depends on the ability to upgrade and patch source code to produce iterative releases. Even though blockchain-based software profits significantly from the technology’s immutability, still a certain degree of mutability is needed for bug fixing and potential product improvements. immutable In this post, we are going to learn: Why do we need to upgrade smart contracts? Understanding how upgrades work under the hood? Using to easily write/manage "upgradable" smart contracts. OpenZeppelin CLI Upgrading Contracts Programmatically using the library. OpenZeppelin Upgrades A few Limitations & Workarounds of Upgradable Contracts If you are just looking for a way to write upgradable contracts and don't want to go through "how this all works", then just head over to the . 3rd section In case you get stuck somewhere or have any doubts, let us know . here Why do we need to upgrade? Smart contracts in Ethereum are by default. Once you create them there is no way to alter them, effectively acting as an unbreakable contract among participants. immutable However, there are several scenarios where we wish if there was a way to upgrade the contracts. There are a lot of examples in which , which could be saved if we could update the smart contracts. millions of dollars worth of Ether were stolen/hacked How do upgrades work under the hood? There can be several ways we can upgrade our contracts. The most obvious way will be something like this: Create & deploy a new version of the contract. Manually migrate all states from the old contract to the new contract. This seems to work, but has several problems. Migrating the contract state can be expensive. As we create & deploy a new contract, the will change. So you would need to update all contracts that interacted with the old contract to use the address of the new version. contract address You would also have to reach out to all your users and convince them to start using the new contract and handle both contracts being used simultaneously, as users are slow to migrate. A better way is to use a contract with an where each method to the contract (which contains all the logic). proxy interface delegates implementation A is similar to a regular call, except that all code is executed in the context of the caller ( ), of the callee ( ). Because of this, a transfer in the implementation contract’s code will transfer the proxy’s balance, and any reads or writes to the contract storage will read or write from the proxy’s storage. delegate call proxy not implementation This approach is better because the users only interact with the contract and we can change the contract while keeping the same contract. proxy implementation proxy This seems better than the previous approach, but if we need to make any changes to the contract methods, we would need to update the contract's methods too (as the proxy contract has interface methods). Hence, users will need to change the proxy address. implementation proxy To solve this problem, we can use a function in the proxy contract. The function will execute on any request, redirecting the request to the and returning the resulting value (using ). This is similar to the previous approach, but here the proxy contract doesn’t have interface methods, only a fallback function, so there is no need to change the proxy address if contract methods are changed. fallback fallback implementation opcodes This was a basic explanation which is enough for us to work with upgradable contracts. In case, you want to dig deep into proxy contract code and different proxy patterns, then check out this post. How Upgradable Smart Contracts Work Under the Hood OpenZeppelin Upgrades As we saw above, there are a lot of things you need to manage while writing upgradeable contracts. Fortunately, projects like have built , which provide an easy to use, simple, robust, and opt-in upgrade mechanism for smart contracts that OpenZeppelin CLI tools & libraries can be controlled by any type of governance, be it a multi-sig wallet, a simple address or a complex DAO. Let's first build a basic upgradeable contract using the OpenZeppelin CLI tool. You can find the . code for the below implementation here In case you get stuck somewhere or have any doubts, let us know . here OpenZeppelin Upgrades CLI Working with OpenZeppelin CLI requires for development. If you don't have it already, install node using whatever package manager you prefer or . Node.js using the official installer Project Setup Create a folder named upgradable-smart-contracts and go inside the folder. $ mkdir upgradable-smart-contracts && cd upgradable-smart-contracts Throughout this tutorial, we use the character to indicate your terminal’s shell prompt. When following along, don’t type the character, or you’ll get some weird errors. $ $ We will use a local blockchain for this tutorial. The most popular local blockchain is . To install and run it on your project, run: Ganache $ npm install --save-dev ganache-cli && npx ganache-cli --deterministic Now, start a new shell/terminal in the same folder run the following command to install the CLI tool: $ npm install --save-dev @openzeppelin/cli To manage your deployed contracts, you need to create a new CLI project. Run the following command, and provide it with a name and version number for your project when prompted: $ npx openzeppelin init Two things will happen during initialization. First, an `.openzeppelin` directory will be created, holding project-specific information. This directory will be managed by the CLI: you won’t need to manually edit anything. You should, however, commit to Git. some of these files Second, the CLI will store network configuration in a file called networks.js. For convenience, it is already populated with an entry called development, with configuration matching 's default. Ganache You can see all the unlocked accounts by running the following command: $ npx openzeppelin accounts Writing & deploying contracts Now, let's create a contract named TodoList in the contracts folder. pragma solidity ^ . ; contract TodoList { ; event ; add public { .push(newItem); emit ; } get public view returns ( memory item) { return ; } } // contracts/TodoList.sol 0.6 3 string [] private list // Emitted when the storeda new item is added to the list ItemAdded( ) string item // Adds a new item in the list function Item( ) string memory newItem list ItemAdded( ) newItem // Gets the item from the list according to index function ListItem( ) uint256 index string list [ ] index Now, let's deploy this contract on the local blockchain. $ npx openzeppelin create As we can see our contract is deployed at 0xD833215cBcc3f914bD1C9ece3EE7BF8B14f841bb. Let's add an item ("responding to emails") to the list array using the addItem() function by running npx openzeppelin send-tx. Now, let's suppose we need to add a new function named getListSize() to get the size of the list. Just add a new function inside the TodoList contract. pragma solidity ^ ; contract TodoList { { .length; } } // contracts/TodoList.sol 0.6 .3 // ... // Gets the size of the list function getListSize () public view returns (uint256 size) return list After changing the Solidity file, we can now just upgrade the instance we had deployed earlier by running the openzeppelin upgrade command. Done! Our TodoList instance has been upgraded to the latest version of the code . We didn’t need to create & deploy the contract or link the to the TodoList. All that is done under the hood! while keeping its state and the same address as before proxy proxy Let’s try it out by invoking the new getListSize() function, and checking the size of the list in the new contract: That’s it! Notice how the size of the list was preserved throughout the upgrade, as well as its address. And this process is the same regardless of whether you are working on a local blockchain, a testnet, or the main network. Upgrading Contracts Programmatically If you want to create and upgrade contracts from your JavaScript code instead of via the command line, you can use the library instead of the CLI. OpenZeppelin Upgrades The CLI does not just manage contract upgrades, but also compilation, interaction, and source code verification. The Upgrades library takes care of creating and upgrading. The library also does keep track of the contracts you have already deployed, nor runs any initializer or storage layout validations, as the CLI does. Nevertheless, these capabilities may be added to the Upgrades library in the near future. only not You can find the . code for the below implementation here In case you get stuck somewhere or have any doubts, let us know . here In case you have not followed the above OpenZeppelin CLI part, you need to . install NodeJs & Ganache as instructed here Your first step will be to install the library in your project, and you will also probably want to install web3 to interact with our contracts using JavaScript, and @openzeppelin/contract-loader to load the contracts from the JSON artifacts. $ npm install web3 @openzeppelin/upgrades @openzeppelin/contract-loader Now, create a file index.js inside upgradable-smart-contracts folder and paste this boilerplate code. Web3 = ( ); { ZWeb3, Contracts, ProxyAdminProject } = ( ); { web3 = Web3( ); ZWeb3.initialize(web3.currentProvider); loader = setupLoader({ : web3 }).web3; } main(); // index.js const require "web3" const require "@openzeppelin/upgrades" async ( ) function main // Set up web3 object, connected to the local development network, initialize the Upgrades library const new "http://localhost:8545" const provider Here we set up web3 object, connected to the local development network, initialize the Upgrades library via ZWeb3.initialize, and initialize the contract loader. Now, add this following snippet in the main() to create a new project, to manage our upgradeable contracts. { = ZWeb3.defaultAccount(); project = ProxyAdminProject( , , , { , : , : }); } async ( ) function main // ... //Fetch the default account const from await //creating a new project, to manage our upgradeable contracts. const new "MyProject" null null from gas 1e6 gasPrice 1e9 Now, using this project, we can create an instance of any contract. The project will take care of deploying it in such a way it can be upgraded later. Let's create 2 contracts, TodoList1 and its updated version TodoList2 inside upgradable-smart-contracts/contracts folder. pragma solidity ^ . ; contract TodoList1 { ; event ; add public { .push(newItem); emit ; } get public view returns ( memory item) { return ; } } // contracts/TodoList1.sol 0.6 3 string [] private list // Emitted when the storeda new item is added to the list ItemAdded( ) string item // Adds a new item in the list function Item( ) string memory newItem list ItemAdded( ) newItem // Gets the item from the list according to index function ListItem( ) uint256 index string list [ ] index To create TodoList2, just add a new getListSize() function in the above contract. pragma solidity ^ . ; contract TodoList2 { ; event ; add public { .push(newItem); emit ; } get public view returns ( memory item) { return ; } get public view returns (uint256 size) { return .length; } } // contracts/TodoList2.sol 0.6 3 string [] private list // Emitted when the storeda new item is added to the list ItemAdded( ) string item // Adds a new item in the list function Item( ) string memory newItem list ItemAdded( ) newItem // Gets the item from the list according to index function ListItem( ) uint256 index string list [ ] index // Gets the size of the list function ListSize() list Now, we need to compile these 2 contracts using: $ npx openzeppelin compile This will create JSON contract artifacts in the build/contracts folder. These artifacts files contain all the information about the contracts that we would need to deploy and interact with the contracts. Now, let's create an instance of TodoList1 using the project we created above. { TodoList1 = Contracts.getFromLocal( ); instance = project.createProxy(TodoList1); address = instance.options.address; .log( , address); } async ( ) function main //... //Using this project, we can now create an instance of any contract. //The project will take care of deploying it in such a way it can be upgraded later. const "TodoList1" const await const console "Proxy Contract Address 1: " Here we get the TodoList1 contract details from the contract artifacts we created above using Contracts.getFromLocal. Then we create & deploy a pair of & (TodoList1) contracts and link the proxy contract to the TodoList1 via project.createProxy method. Finally, we print out the address of our proxy contract. proxy implementation Now, let's add an item to the list using addItem() method and then fetch the added item using getListItem(). { todoList1.methods .addItem( ) .send({ : , : , : }); item = todoList1.methods.getListItem( ).call(); .log( , item); } async ( ) function main //... // Send a transaction to add a new item in the TodoList1 await "go to class" from from gas 100000 gasPrice 1e6 // Call the getListItem() function to fetch the added item from TodoList1 var await 0 console "TodoList1: List Item 0: " Now, let's update our TodoList1 contract to TodoList2. { TodoList2 = Contracts.getFromLocal( ); updatedInstance = project.upgradeProxy(address, TodoList2); .log( , updatedInstance.options.address); } async ( ) function main //... //After deploying the contract, you can upgrade it to a new version of //the code using the upgradeProxy method, and providing the instance address. const "TodoList2" const await console "Proxy Contract Address 2: " Here we get the TodoList2 contract details from the contract artifacts. Then we update our contract via project.upgradeProxy method which takes 2 parameters, the address of the proxy contract that we deployed in the previous step, and the TodoList2 contract object. We then print out the address of the proxy contract after the update. Now, let's add a new item to the TodoList2 and fetch the items. { todoList2.methods .addItem( ) .send({ : , : , : }); item0 = todoList2.methods.getListItem( ).call(); item1 = todoList2.methods.getListItem( ).call(); .log( , item0); .log( , item1); } async ( ) function main //... // Send a transaction to add a new item in the TodoList2 await "code" from from gas 100000 gasPrice 1e6 // Call the getListItem() function to fetch the added items from TodoList2 var await 0 var await 1 console "TodoList2: List Item 0: " console "TodoList2: List Item 1: " Now, let's run the index.js using node index.js. Here we can observe 2 things: The address of the contract did not change even after we updated TodoList1 to TodoList2. proxy As we got 2 items from the TodoList2, this shows that the state was preserved throughout the update. Hence we can say that TodoList1 instance has been upgraded to the latest version of the code (TodoList2), . while keeping its state and the same address as before In case you get stuck somewhere or have any doubts, let us know . here Now, as we have seen how to upgrade contracts, let's see a few limitations & workarounds that you need to know about when writing more complex contracts. A few things to keep in mind: limitations & workarounds When working with upgradeable contracts using OpenZeppelin Upgrades, there are a few minor caveats to keep in mind when writing your Solidity code. It’s worth mentioning that these restrictions have their roots in how the works, and apply to all projects that work with upgradeable contracts, not just OpenZeppelin Upgrades. Ethereum VM If your contract is not compatible for upgrades, the CLI will warn you when you try to upgrade. This feature is not there yet in the OpenZeppelin Upgrades libraries. In order to understand the limitations & workarounds, let's take an Example contract, explore the limitations in the contract and add some workarounds to make the contract upgradable. pragma solidity ^ ; ; contract Example { 256 _cap = ; ERC20Capped token; constructor( 8 cap) { _cap = cap; token = new ERC20Capped(_cap); } } // contracts/Example.sol 0.6 .0 import "github.com/OpenZeppelin/openzeppelin-contracts/blob/master/contracts/token/ERC20/ERC20Capped.sol" uint private 1000000000000000000 public uint public Limitation 1: No Constructors Due to a requirement of the proxy-based upgradeability system, no constructors can be used in upgradeable contracts. To learn about the reasons behind this restriction, head to this . post Workaround: Initializer A workaround is to replace the constructor with a function, typically named initialize, where you run constructor logic. pragma solidity ^ ; contract Example { uint256 _cap = ; ERC20Capped token; { _cap = cap; token = ERC20Capped(_cap); } } // contracts/Example.sol 0.6 .0 "github.com/OpenZeppelin/openzeppelin-contracts/blob/master/contracts/token/ERC20/ERC20Capped.sol"; import private 1000000000000000000 public function initialize (uint8 cap) public new Now, as the constructor is called only once when the contract is initialized, we need to add a check to ensure that the initialize function gets called only once. solidity ^ .0; ; contract Example { uint256 _cap = ; ERC20Capped token; _initialized = ; initialize(uint8 cap) { require(!_initialized); _initialized = ; _cap = cap; token = ERC20Capped(_cap); } } // contracts/Example.sol pragma 0.6 import "github.com/OpenZeppelin/openzeppelin-contracts/blob/master/contracts/token/ERC20/ERC20Capped.sol" private 1000000000000000000 public bool private false function public true new Since this will be a common thing to do when writing upgradeable contracts, OpenZeppelin Upgrades provides an Initializable base contract that has an initializer modifier that takes care of this: pragma solidity ^ ; contract Example Initializable { uint256 _cap = ; ERC20Capped token; { _cap = cap; token = ERC20Capped(_cap); } } // contracts/Example.sol 0.6 .0 "github.com/OpenZeppelin/openzeppelin-contracts/blob/master/contracts/token/ERC20/ERC20Capped.sol"; import "@openzeppelin/upgrades/contracts/Initializable.sol"; import is private 1000000000000000000 public function initialize (uint8 cap) public initializer new Another difference between a constructor and a regular function is that Solidity takes care of automatically invoking the constructors of all ancestors of a contract. When writing an initializer, you need to take special care to manually call the initializers of all parent contracts: pragma solidity ^ ; contract BaseExample Initializable { uint256 createdAt; { createdAt = block.timestamp; } } contract Example BaseExample { uint256 _cap = ; ERC20Capped token; { _cap = cap; token = ERC20Capped(_cap); } } // contracts/Example.sol 0.6 .0 "github.com/OpenZeppelin/openzeppelin-contracts/blob/master/contracts/token/ERC20/ERC20Capped.sol"; import "@openzeppelin/upgrades/contracts/Initializable.sol"; import is public function initialize () initializer public is private 1000000000000000000 public function initialize (uint8 cap) initializer public new Keep in mind that this restriction affects not only your contracts, but also the contracts you import from a library. Consider for example ERC20Capped from OpenZeppelin Contracts: the contract initializes the token’s cap in its constructor. pragma solidity ^ ; ; contract ERC20Capped ERC20 { 256 _cap; constructor ( 256 cap) { require(cap > , ); _cap = cap; } } 0.6 .0 import "./ERC20.sol" /** * @dev Extension of {ERC20} that adds a cap to the supply of tokens. */ is uint private /** * @dev Sets the value of the `cap`. This value is immutable, it can only be * set once during construction. */ uint public 0 "ERC20Capped: cap is 0" //... This means you should not be using these contracts in your OpenZeppelin Upgrades project. Instead, make sure to use @openzeppelin/contracts-ethereum-package, which is an official fork of OpenZeppelin Contracts that has been modified to use initializers instead of constructors. Take a look at how looks in @openzeppelin/contracts-ethereum-package: ERC20Capped pragma solidity ^ ; contract ERC20Capped Initializable, ERC20Mintable { uint256 _cap; { ERC20Mintable.initialize(sender); require(cap > , ); _cap = cap; } } 0.5 .0 "@openzeppelin/upgrades/contracts/Initializable.sol"; import "./ERC20Mintable.sol"; import /** * @dev Extension of {ERC20Mintable} that adds a cap to the supply of tokens. */ is private /** * @dev Sets the value of the `cap`. This value is immutable, it can only be * set once during construction. */ function initialize (uint256 cap, address sender) public initializer 0 "ERC20Capped: cap is 0" //... Whether using OpenZeppelin Contracts or another Ethereum Package, always make sure that the package is set up to handle upgradeable contracts. pragma solidity ^ ; contract BaseExample Initializable { uint256 createdAt; { createdAt = block.timestamp; } } contract Example BaseExample { uint256 _cap = ; ERC20Capped token; { _cap = cap; token = ERC20Capped(_cap); } } // contracts/Example.sol 0.6 .0 "@openzeppelin/contracts-ethereum-package/contracts/token/ERC20/ERC20Capped.sol"; import "@openzeppelin/upgrades/contracts/Initializable.sol"; import is public function initialize () initializer public is private 1000000000000000000 public function initialize (uint8 cap) initializer public new Limitation 2: Initial Values in Field Declarations Solidity allows defining initial values for fields when declaring them in a contract. contract Example BaseExample { 256 _cap = ; } is uint private 1000000000000000000 //... This is equivalent to setting these values in the constructor, and as such, will not work for upgradeable contracts. Workaround: Initializer Make sure that all initial values are set in an initializer function as shown below; otherwise, any upgradeable instances will not have these fields set. contract Example BaseExample { uint256 _cap; ERC20Capped token; { _cap = ; _cap = cap; token = ERC20Capped(_cap); } } //... is private public function initialize (uint8 cap) initializer public 1000000000000000000 new Note that it still is fine to set constants here, because the compiler , and every occurrence is replaced by the respective constant expression. So the following still works with OpenZeppelin Upgrades: does not reserve a storage slot for these variables contract Example BaseExample { 256 constant _cap = ; } //... is uint private 1000000000000000000 //... Limitation: Creating New Instances From Your Contract Code When creating a new instance of a contract from your contract’s code, these creations are handled directly by Solidity and not by OpenZeppelin Upgrades, which means that . these contracts will not be upgradeable For instance, in the following example, even if Example is upgradeable (if created via openzeppelin create Example), the token contract created is not: contract Example BaseExample { uint256 _cap = ; ERC20Capped token; { _cap = cap; token = ERC20Capped(_cap); } } //... is private 1000000000000000000 public function initialize (uint8 cap) initializer public new Workaround: Inject a pre-deployed contract from CLI The easiest way around this issue is to avoid creating contracts on your own altogether: instead of creating a contract in an initialize function, simply accept an instance of that contract as a parameter, and inject it after creating it from the OpenZeppelin CLI: contract Example BaseExample { ERC20Capped token; { token = _token; } } //... is public function initialize (ERC20Capped _token) initializer public $ TOKEN=$(npx openzeppelin create TokenContract) $ npx oz create Example --init --args $TOKEN Workaround: OpenZeppelin App Contract An advanced alternative, if you need to create upgradeable contracts on the fly, is to keep an instance of your OpenZeppelin project’s App in your contracts. The is a contract that acts as the entrypoint for your OpenZeppelin project, which has references to your logic implementations, and can create new contract instances: App pragma solidity ^ ; ; ; contract BaseExample is Initializable { } contract Example is BaseExample { App private app; { app = _app; } { app.create( , ); } } // contracts/Example.sol 0.6 .0 import "@openzeppelin/upgrades/contracts/Initializable.sol" import "@openzeppelin/upgrades/contracts/application/App.sol" //... ( ) function initialize App _app initializer public ( ) ( ) function createNewToken public returns address return "@openzeppelin/contracts-ethereum-package" "ERC20Capped" Potentially Unsafe Operations When working with upgradeable smart contracts, you will always interact with the proxy contract instance, and never with the underlying logic (implementation) contract. However, nothing prevents a malicious actor from sending transactions to the logic contract directly. This does not pose a threat, since any changes to the state of the logic contracts do not affect your proxy contract instances, as the storage of the logic contracts is never used in your project. There is, however, an exception. If the direct call to the logic contract triggers a selfdestruct operation, then the logic contract will be destroyed, and all your contract instances will end up delegating all calls to an address without any code. This would effectively break all contract instances in your project. A similar effect can be achieved if the logic contract contains a delegatecall operation. If the contract can be made to delegatecall into a malicious contract that contains a selfdestruct, then the calling contract will be destroyed. pragma solidity ^ ; contract Example { { malicious.delegatecall(abi.encodeWithSignature( )); } } contract Malicious { { address payable addr = address(uint160(address( ))); selfdestruct(addr); } } 0.6 .0 // The Exmaple contract makes a `delegatecall` to the Malicious contract. Thus, even if the Malicious contract runs the `selfdestruct` function, it is run in the context of the Example contract, thus killing the Example contract. function testFunc (address malicious) public "kill()" function kill () public 0x4Bf8c809c898ee52Eb7fc6e1FdbB067423326B2A As such, it is strongly recommended to avoid any usage of either selfdestruct or delegatecall in your contracts. If you need to include them, make absolutely sure they cannot be called by an attacker on an uninitialized logic contract. Modifying Your Contracts When writing new versions of your contracts, either due to new features or bugfixing, there is an additional restriction to observe: you cannot change the order in which the contract state variables are declared, nor their type. You can read more about the reasons behind this restriction by learning about . Proxies Violating any of these storage layout restrictions will cause the upgraded version of the contract to have its storage values mixed up, and can lead to critical errors in your application. This means that if you have an initial contract that looks like this: pragma solidity ^ ; contract Example { tokenName; 8 decimals; } 0.6 .3 string public uint public Then you cannot change the type of a variable: pragma solidity ^ ; contract Example { tokenName; decimals; } 0.6 .3 string public uint public Or change the order in which they are declared: pragma solidity ^ ; contract Example { decimals; tokenName; } 0.6 .3 uint public string public Or introduce a new variable before existing ones: pragma solidity ^ ; contract Example { tokenSymbol; tokenName; decimals; } 0.6 .3 string public string public uint public Or remove an existing variable: pragma solidity ^ ; contract Example { tokenName; } 0.6 .3 string public If you need to introduce a new variable, make sure you always do so at the end: pragma solidity ^ ; contract Example { tokenName; decimals; tokenSymbol; } 0.6 .3 string public uint public string public Keep in mind that if you rename a variable, then it will keep the same value as before after upgrading. This may be the desired behaviour if the new variable is semantically the same as the old one: pragma solidity ^ ; contract Example { tokenName; decimalCount; } 0.6 .3 string public uint public // starts with the value of `decimals` And if you remove a variable from the end of the contract, note that the storage will not be cleared. A subsequent update that adds a new variable will cause that variable to read the leftover value from the deleted one. pragma solidity ^ ; contract Example1 { tokenName; decimals; } contract Example2 { tokenName; } contract Example3 { tokenName; decimalCount; } 0.6 .3 string public uint public // Updating Example1 --> Example2 string public // Updating Example2 --> Example3 string public uint public // starts with the value of `decimals` Note that you may also be inadvertently changing the storage variables of your contract by changing its parent (base) contracts. For instance, if you have the following contracts: pragma solidity ^0.6.3; contract { uint256 createdAt; } { string version; } , {} BaseExample1 contract BaseExample2 contract Example is BaseExample1 BaseExample2 Then modifying Example by swapping the order in which the base contracts are declared, or adding new base contracts or removing base contracts, will change how the variables are actually stored: pragma solidity ^ ; contract BaseExample1 { 256 createdAt; } contract BaseExample2 { version; } contract Example BaseExample2, BaseExample1 {} contract Example BaseExample1 {} contract BaseExample3 {} contract Example BaseExample1, BaseExample2, BaseExample3 {} 0.6 .3 uint string //swapping the order in which the base contracts are declared is //Or... //removing base contract(s) is //Or... //adding new base contract is You also cannot add new variables to base contracts, if the child has any variables of its own. Given the following scenario: pragma solidity ^ ; contract BaseExample {} contract Example BaseExample { tokenName; } contract BaseExample { version; } contract Example BaseExample { tokenName; } 0.6 .3 is string //Now, if the BaseExample is updated to the following string // takes the value of `tokenName` is string Then the variable version would be assigned the slot that tokenName had in the previous version. You also remove a variable from the base contract, if the child has any variables of its own. For example: pragma solidity ^ ; contract BaseExample { 256 createdAt; version; } contract Example BaseExample { tokenName; } contract BaseExample { 256 createdAt; } contract Example BaseExample { tokenName; } 0.6 .3 uint string is string //Now, if the BaseExample is updated to the following uint is string //takes the value of `version` Here, as we remove the version variable from the BaseExample, the memory slot for version (before update) will now be used by tokenName (after update). A workaround for this is to declare unused variables on base contracts that you may want to extend in the future, as a means of "reserving" those slots. So, basically, keeping the number and order of the variables in the parent and child contracts same for all the updates. pragma solidity ^ ; contract BaseExample { someVar1; someVar2; someVar3; } 0.6 .3 string string string //... Note that this trick does involve increased gas usage. not In case you get stuck somewhere or have any doubts, let us know . here Credits We have copied some of the text from these amazing docs from & . OpenZeppelin NuCypher NuCypher’s Approaches to Upgradeable Contracts Upgrading Smart Contracts Writing Upgradeable Contracts This article was first published on our open-source platform, . If you are interested in IPFS, Libp2p, Ethereum, Zero-knowledge Proofs, Defi, CryptoEconomics, IPLD, Multi formats, and other Web 3.0 projects, concepts and interactive tutorials, then be sure to check out . SimpleAsWater.com SimpleAsWater