Unverified Commit 17ec5fa5 authored by German's avatar German Committed by GitHub
Browse files

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's avatarMichael Müller <mich@elmueller.net>
Co-authored-by: Andrew Jones's avatarAndrew Jones <ascjones@gmail.com>

* Apply suggestions from code review

Co-authored-by: Michael Müller's avatarMichael Müller <mich@elmueller.net>
Co-authored-by: Andrew Jones's avatarAndrew Jones <ascjones@gmail.com>
parent a314b349
Pipeline #214350 passed with stages
in 19 minutes and 54 seconds
......@@ -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))
}
......@@ -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.
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment