Implement storage (revision 2) module

README.md

@@ -16,6 +16,8 @@
 [f2]: https://paritytech.github.io/ink/ink_core
 [h1]: https://img.shields.io/badge/docs-abi-blue.svg
 [h2]: https://paritytech.github.io/ink/ink_abi
+[i1]: https://img.shields.io/badge/docs-prelude-blue.svg
+[i2]: https://paritytech.github.io/ink/ink_prelude
 
 **IMPORTANT NOTE:** WORK IN PROGRESS! Do not expect this to be working.
 
@@ -25,9 +27,9 @@ For more information please visit [the ink! tutorial](https://substrate.dev/subs
 
 ## Developer Documentation
 
-| `ink_abi`     | `ink_core`    |
-| ------------- | ------------- |
-| [![][h1]][h2] | [![][f1]][f2] |
+| `ink_abi`     | `ink_core`    | `ink_prelude` |
+| ------------- | ------------- | ------------- |
+| [![][h1]][h2] | [![][f1]][f2] | [![][i1]][i2] |
 
 ### Interaction with Substrate
 

core/Cargo.toml

@@ -23,13 +23,13 @@ ink_prelude = { version = "2.1.0", path = "../prelude/", default-features = fals
 
 scale = { package = "parity-scale-codec", version = "1.3", default-features = false, features = ["derive", "full"] }
 derive_more = { version = "0.99", default-features = false, features = ["from", "display"] }
-smallvec = { version = "1.2", default-features = false, features = ["union"] }
-cfg-if = "0.1"
 num-traits = { version = "0.2", default-features = false, features = ["i128"] }
+cfg-if = "0.1"
+array-init = "0.1"
+generic-array = "0.14.1"
 paste = "0.1"
 
 # Hashes for the off-chain environment.
-byteorder = { version = "1.3", optional = true }
 blake2-rfc = { version = "0.2", optional = true }
 sha2 = { version = "0.8", optional = true }
 tiny-keccak = { version = "2.0", optional = true }
@@ -63,7 +63,6 @@ std = [
     "rand/std",
     "num-traits/std",
     # Enables hashing crates for off-chain environment.
-    "byteorder",
     "blake2-rfc",
     "sha2",
     "tiny-keccak",

core/src/env/call/mod.rs

@@ -18,6 +18,8 @@ mod builder;
 mod instantiate;
 mod utils;
 
+/// The compile-time states of builder for calls and instantiations.
+#[doc(hidden)]
 pub mod state {
     pub use crate::env::call::{
         instantiate::state::{

core/src/env/engine/off_chain/test_api.rs

@@ -257,11 +257,17 @@ pub struct DefaultAccounts<T>
 where
     T: EnvTypes,
 {
+    /// The predefined `ALICE` account holding substantial amounts of value.
     pub alice: T::AccountId,
+    /// The predefined `BOB` account holding some amounts of value.
     pub bob: T::AccountId,
+    /// The predefined `CHARLIE` account holding some amounts of value.
     pub charlie: T::AccountId,
+    /// The predefined `DJANGO` account holding no value.
     pub django: T::AccountId,
+    /// The predefined `EVE` account holding no value.
     pub eve: T::AccountId,
+    /// The predefined `FRANK` account holding no value.
     pub frank: T::AccountId,
 }
 

core/src/hash/builder.rs

@@ -111,20 +111,22 @@ pub trait Finalize<H>
 where
     H: Hasher,
 {
-    fn finalize_using(&self, output: &mut <H as Hasher>::Output);
-    fn finalize(&self) -> <H as Hasher>::Output;
+    fn finalize_using(&mut self, output: &mut <H as Hasher>::Output);
+    fn finalize(&mut self) -> <H as Hasher>::Output;
 }
 
 impl<H, S> Finalize<H> for HashBuilder<H, S>
 where
     H: Hasher,
     S: Accumulator,
 {
-    fn finalize_using(&self, output: &mut <H as Hasher>::Output) {
-        <H as Hasher>::finalize_immediate(self.strategy.as_slice(), output)
+    fn finalize_using(&mut self, output: &mut <H as Hasher>::Output) {
+        let output = <H as Hasher>::finalize_immediate(self.strategy.as_slice(), output);
+        self.strategy.reset();
+        output
     }
 
-    fn finalize(&self) -> <H as Hasher>::Output {
+    fn finalize(&mut self) -> <H as Hasher>::Output {
         let mut output = <<H as Hasher>::Output as Default>::default();
         Self::finalize_using(self, &mut output);
         output

core/src/hash/hasher.rs

@@ -34,6 +34,7 @@ macro_rules! impl_hasher_for {
         struct $ty_name:ident($fn_name:ident, $output_len:literal);
     ) => {
         $( #[$doc] )*
+        #[derive(Debug, Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
         pub enum $ty_name {}
 
         impl Hasher for $ty_name {
@@ -47,21 +48,17 @@ macro_rules! impl_hasher_for {
 }
 impl_hasher_for! {
     /// SHA2 256-bit hasher.
-    #[derive(Debug)]
     struct Sha2x256Hasher(sha2_256, 32);
 }
 impl_hasher_for! {
     /// KECCAK 256-bit hasher.
-    #[derive(Debug)]
     struct Keccak256Hasher(keccak_256, 32);
 }
 impl_hasher_for! {
     /// BLAKE2 256-bit hasher.
-    #[derive(Debug)]
     struct Blake2x256Hasher(blake2_256, 32);
 }
 impl_hasher_for! {
     /// BLAKE2 128-bit hasher.
-    #[derive(Debug)]
     struct Blake2x128Hasher(blake2_128, 16);
 }

core/src/lib.rs

@@ -22,7 +22,9 @@
 
 #![cfg_attr(not(feature = "std"), no_std)]
 #![deny(
+    missing_docs,
     bad_style,
+    bare_trait_objects,
     const_err,
     improper_ctypes,
     non_shorthand_field_patterns,
@@ -49,6 +51,7 @@ extern crate ink_alloc;
 pub mod env;
 pub mod hash;
 pub mod storage;
+pub mod storage2;
 
 // Needed for derive macros of `core/derive` sub crate.
 pub(crate) use crate as ink_core;

core/src/storage2/alloc/allocation.rs

@@ -0,0 +1,87 @@
+// Copyright 2019-2020 Parity Technologies (UK) Ltd.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+use crate::hash::{
+    Blake2x256,
+    Wrap,
+};
+use ink_primitives::Key;
+
+/// A unique dynamic allocation.
+///
+/// This can refer to a dynamically allocated storage cell.
+/// It has been created by a dynamic storage allocator.
+/// The initiator of the allocation has to make sure to deallocate
+/// this dynamic allocation again using the same dynamic allocator
+/// if it is no longer in use.
+///
+/// # Note
+///
+/// Normally instances of this type are not used directly and instead
+/// a [`storage::Box`](`crate::storage2::Box`) is used instead.
+#[derive(
+    Debug, Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, scale::Encode, scale::Decode,
+)]
+pub struct DynamicAllocation(pub(super) u32);
+
+impl DynamicAllocation {
+    /// Returns the allocation identifier as `u32`.
+    pub(super) fn get(self) -> u32 {
+        self.0
+    }
+
+    /// Returns the storage key associated with this dynamic allocation.
+    pub fn key(self) -> Key {
+        // We create a 25-bytes buffer for the hashing.
+        // This is due to the fact that we prepend the `u32` encoded identifier
+        // with the `b"DYNAMICALLY ALLOCATED"` byte string which has a length
+        // 21 bytes. Since `u32` always has an encoding length of 4 bytes we
+        // end up requiring 25 bytes in total.
+        // Optimization Opportunity:
+        // Since ink! always runs single threaded we could make this buffer
+        // static and instead reuse its contents with every invocation of this
+        // method. However, this would introduce `unsafe` Rust usage.
+        #[rustfmt::skip]
+        let mut buffer: [u8; 25] = [
+            b'D', b'Y', b'N', b'A', b'M', b'I', b'C', b'A', b'L', b'L', b'Y',
+            b' ',
+            b'A', b'L', b'L', b'O', b'C', b'A', b'T', b'E', b'D',
+            b'_', b'_', b'_', b'_',
+        ];
+        // Encode the `u32` identifier requires a 4 bytes buffer.
+        let mut hash_buffer = Wrap::from(&mut buffer[21..25]);
+        <u32 as scale::Encode>::encode_to(&self.0, &mut hash_buffer);
+        let mut output = [0x00_u8; 32];
+        <Blake2x256>::hash_bytes_using(&buffer, &mut output);
+        Key::from(output)
+    }
+}
+
+#[test]
+fn get_works() {
+    let expected_keys = [
+        b"\
+            \x0A\x0F\xF5\x30\xBD\x5A\xB6\x67\
+            \x85\xC9\x74\x6D\x01\x33\xD7\xE1\
+            \x24\x40\xC4\x67\xA9\xF0\x6D\xCA\
+            \xE7\xED\x2E\x78\x32\x77\xE9\x10",
+        b"\
+            \x11\x5A\xC0\xB2\x29\xA5\x34\x10\
+            \xB0\xC0\x2D\x47\x49\xDC\x7A\x09\
+            \xB9\x6D\xF9\x51\xB6\x1D\x4F\x3B\
+            \x4E\x75\xAC\x3B\x14\x57\x47\x96",
+    ];
+    assert_eq!(DynamicAllocation(0).key(), Key(*expected_keys[0]));
+    assert_eq!(DynamicAllocation(1).key(), Key(*expected_keys[1]));
+}

core/src/storage2/alloc/allocator.rs

@@ -0,0 +1,83 @@
+// Copyright 2019-2020 Parity Technologies (UK) Ltd.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+use super::DynamicAllocation;
+use crate::storage2::{
+    collections::BitStash,
+    traits::{
+        KeyPtr,
+        SpreadLayout,
+    },
+};
+
+/// The dynamic allocator.
+///
+/// Manages dynamic storage allocations in a very efficient and economic way.
+#[derive(Debug, Default, PartialEq, Eq)]
+pub struct DynamicAllocator {
+    allocations: BitStash,
+}
+
+impl SpreadLayout for DynamicAllocator {
+    const FOOTPRINT: u64 = <BitStash as SpreadLayout>::FOOTPRINT;
+
+    fn pull_spread(ptr: &mut KeyPtr) -> Self {
+        Self {
+            allocations: SpreadLayout::pull_spread(ptr),
+        }
+    }
+
+    fn push_spread(&self, ptr: &mut KeyPtr) {
+        SpreadLayout::push_spread(&self.allocations, ptr);
+    }
+
+    fn clear_spread(&self, ptr: &mut KeyPtr) {
+        SpreadLayout::clear_spread(&self.allocations, ptr);
+    }
+}
+
+impl DynamicAllocator {
+    /// Returns a new dynamic storage allocation.
+    ///
+    /// # Panics
+    ///
+    /// If the dynamic allocator ran out of free dynamic allocations.
+    pub fn alloc(&mut self) -> DynamicAllocation {
+        DynamicAllocation(self.allocations.put())
+    }
+
+    /// Frees the given dynamic storage allocation.
+    ///
+    /// This makes the given dynamic storage allocation available again
+    /// for new dynamic storage allocations.
+    ///
+    /// # Panics
+    ///
+    /// Panics if the given dynamic allocation is invalid.
+    /// A dynamic allocation is invalid if it is not represented as occupied
+    /// in the `free` list.
+    pub fn free(&mut self, allocation: DynamicAllocation) {
+        let index = allocation.get();
+        if !self
+            .allocations
+            .take(index)
+            .expect("invalid dynamic storage allocation")
+        {
+            panic!(
+                "encountered double free of dynamic storage: at index {}",
+                index
+            )
+        }
+    }
+}