Document storage compatibility (#1384)

* document storage compatibility

* more clarity on storage restriction

* fix spelling

* ignore code snippets in docs

* formatting

* Apply suggestions from Michi's code review

Co-authored-by: Michael Müller <[email protected]>
Co-authored-by: Andrew Jones <[email protected]>

* Apply suggestions from code review

Co-authored-by: Michael Müller <[email protected]>
Co-authored-by: Andrew Jones <[email protected]>

Author: 3 people

crates/env/src/api.rs

@@ -630,6 +630,74 @@ where
 /// # Errors
 ///
 /// `ReturnCode::CodeNotFound` in case the supplied `code_hash` cannot be found on-chain.
+///
+/// # Storage Compatibility
+///
+/// When the smart contract code is modified,
+/// it is important to observe an additional virtual restriction
+/// that is imposed on this procedure:
+/// you should not change the order in which the contract state variables
+/// are declared, nor their type.
+///
+/// Violating the restriction will not prevent a successful compilation,
+/// but will result in the mix-up of values or failure to read the storage correctly.
+/// This can result in severe errors in the application utilizing the contract.
+///
+/// If the storage of your contract looks like this:
+///
+/// ```ignore
+/// #[ink(storage)]
+/// pub struct YourContract {
+///     x: u32,
+///     y: bool,
+/// }
+/// ```
+///
+/// The procedures listed below will make it invalid:
+///
+/// Changing the order of variables:
+///
+/// ```ignore
+/// #[ink(storage)]
+/// pub struct YourContract {
+///     y: bool,
+///     x: u32,
+/// }
+/// ```
+///
+/// Removing existing variable:
+///
+/// ```ignore
+/// #[ink(storage)]
+/// pub struct YourContract {
+///     x: u32,
+/// }
+/// ```
+///
+/// Changing type of a variable:
+///
+/// ```ignore
+/// #[ink(storage)]
+/// pub struct YourContract {
+///     x: u64,
+///     y: bool,
+/// }
+/// ```
+///
+/// Introducing a new variable before any of the existing ones:
+///
+/// ```ignore
+/// #[ink(storage)]
+/// pub struct YourContract {
+///     z: Vec<u32>,
+///     x: u32,
+///     y: bool,
+/// }
+/// ```
+///
+/// Please refer to the
+/// [Open Zeppelin docs](https://docs.openzeppelin.com/upgrades-plugins/1.x/writing-upgradeable#modifying-your-contracts)
+/// for more details and examples.
 pub fn set_code_hash(code_hash: &[u8; 32]) -> Result<()> {
     <EnvInstance as OnInstance>::on_instance(|instance| instance.set_code_hash(code_hash))
 }

examples/upgradeable-contracts/README.md

@@ -20,3 +20,10 @@ more information on proxy patterns.
   This effectively replaces the code which is executed for the contract address.
 * The other contract (`updated-incrementer`) needs to be deployed on-chain.
 * State is stored in the storage of the originally instantiated contract (`incrementer`).
+
+## Storage Compatibility
+
+When working on the contract upgradeability, it is important to observe additional rules that are imposed on
+the modifications of storage:
+
+Please refer to the section of [Storage Compatibility](https://paritytech.github.io/ink/ink_env/fn.set_code_hash.html) in the ink! crate documentation.