* First release of Upgrade Safe variant, replacing Ethereum Package variant which is now deprecated.
* First release of Upgradeable variant, replacing Ethereum Package variant which is now deprecated.
### Upgrading from OpenZeppelin Contracts Ethereum Package
* The dependency on `@openzeppelin/contracts-ethereum-package` should be replaced by `@openzeppelin/contracts-upgrade-safe`.
* Previously only contracts were renamed with an `UpgradeSafe` suffix. Now all contracts, interfaces, and libraries have an `UpgradeSafe` suffix. The only exception is the `Initializable` contract which retains its original name.
*`Address` → `AddressUpgradeSafe`
* The dependency on `@openzeppelin/contracts-ethereum-package` should be replaced by `@openzeppelin/contracts-upgradeable`.
* All contracts, interfaces, and libraries now have an `Upgradeable` suffix, instead of the `UpgradeSafe` suffix that only contracts used to have. The only exception is the `Initializable` contract which retains its original name.
*`Address` → `AddressUpgradeable`
*`ERC20UpgradeSafe` → `ERC20Upgradeable`
* This change improves compatibility with the main OpenZeppelin Contracts package, allowing both to be used side by side.
* Solidity files are now also suffixed, to keep the Solidity convention of equal file and contract name.
This repository hosts the Upgrade Safe variant of [OpenZeppelin Contracts], meant for use in upgradeable contracts. This variant is available as separate package called `@openzeppelin/contracts-upgrade-safe`.
This repository hosts the Upgradeable variant of [OpenZeppelin Contracts], meant for use in upgradeable contracts. This variant is available as separate package called `@openzeppelin/contracts-upgradeable`.
Constructors are replaced by internal initializer functions following the naming convention `__{ContractName}_init`. Since these are internal, you must always define your own public initializer function and call the parent initializer of the contract you extend.
If your contract is going to be deployed with upgradeability, such as using the xref:upgrades-plugins::index.adoc[OpenZeppelin Upgrades Plugins], you will need to use the Upgrade Safe variant of OpenZeppelin Contracts.
If your contract is going to be deployed with upgradeability, such as using the xref:upgrades-plugins::index.adoc[OpenZeppelin Upgrades Plugins], you will need to use the Upgradeable variant of OpenZeppelin Contracts.
This variant is available as a separate package called `@openzeppelin/contracts-upgrade-safe`, which is hosted in the repository https://github.com/OpenZeppelin/openzeppelin-contracts-upgrade-safe[OpenZeppelin/openzeppelin-contracts-upgrade-safe].
This variant is available as a separate package called `@openzeppelin/contracts-upgradeable`, which is hosted in the repository https://github.com/OpenZeppelin/openzeppelin-contracts-upgradeable[OpenZeppelin/openzeppelin-contracts-upgradeable].
It follows all of the rules for xref:upgrades-plugins::writing-upgradeable.adoc[Writing Upgradeable Contracts]: constructors are replaced by initializer functions, state variables are initialized in initializer functions, and we additionally check for storage incompatibilities across minor versions.
...
...
@@ -11,19 +11,19 @@ It follows all of the rules for xref:upgrades-plugins::writing-upgradeable.adoc[
Constructors are replaced by internal initializer functions following the naming convention `+__{ContractName}_init+`. Since these are internal, you must always define your own public initializer function and call the parent initializer of the contract you extend.
...
...
@@ -66,6 +66,6 @@ The function `+__{ContractName}_init_unchained+` found in every contract is the
=== Storage Gaps
You may notice that every contract includes a state variable named `+__gap+`. This is empty reserved space in storage that is put in place in Upgrade Safe contracts. It allows us to freely add new state variables in the future without compromising the storage compatibility with existing deployments.
You may notice that every contract includes a state variable named `+__gap+`. This is empty reserved space in storage that is put in place in Upgradeable contracts. It allows us to freely add new state variables in the future without compromising the storage compatibility with existing deployments.
It isn't safe to simply add a state variable because it "shifts down" all of the state variables below in the inheritance chain. This makes the storage layouts incompatible, as explained in xref:upgrades-plugins::writing-upgradeable.adoc#modifying-your-contracts[Writing Upgradeable Contracts]. The size of the `+__gap+` array is calculated so that the amount of storage used by a contract always adds up to the same number (in this case 50 storage slots).
