Added StoragePlus chapters.

Author: DariuszDepta

docs/storage-plus/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "StoragePlus",
+  "position": 6,
+  "link": {
+    "type": "doc",
+    "id": "introduction"
+  }
+}

docs/storage-plus/basics.md

@@ -0,0 +1,81 @@
+---
+sidebar_position: 1
+---
+
+# Basics
+
+## Containers
+
+`cw-storage-plus` provides several storage containers that can be used to store data on the
+blockchain. The fundamental ones are:
+
+- [`Item`](containers/item)
+- [`Map`](containers/map)
+- [`Deque`](containers/deque)
+
+An [`Item`](containers/item) is a simple container that stores a single value. The other two are a
+little more involved - they are collections capable of storing multiple values, and provide several
+methods to interact with them.
+
+## Keys and prefixes
+
+One task of a storage library like `cw-storage-plus` is to manage the namespace of keys provided by
+the blockchain.
+
+When constructing a container, you must provide a key of type `&'static str` (or use
+[`new_dyn`](https://docs.rs/cw-storage-plus/latest/cw_storage_plus/struct.Item.html#method.new_dyn)).
+This usually means you'll be providing a string literal or some constant.
+
+In the case of an [`Item`](containers/item), the provided string is the exact key (a standard UTF-8
+string) under which the value will be saved. In the case of collections, the provided string is a
+prefix (sometimes called `namespace` in the code); the collection will use this prefix to generate
+keys (by appending to it) for the individual values it stores.
+
+As a contract dev, it is your responsibility to ensure that the keys you provide are unique and do
+not conflict with keys used by other parts of the contract.
+
+:::tip
+
+Over time, we've learned that using long keys hurts storage performance. If you _gotta go fast_, a
+good approach might be to only provide single-character ASCII prefixes for your containers, like
+_"a"_, _"b"_, _"c"_, etc.
+
+:::
+
+Generally speaking, we tried to make it so that as long as you use a unique prefix for each
+container, you shouldn't have to worry about key conflicts.
+
+TODO: Research the key collisions in the warning below more! Then we can provide better advice.
+
+:::warning
+
+...yet there's a small _but_. A `Map`'s prefix is length-prefixed. An `Item` is saved without any
+sort of length-prefixing of the key. It is, in theory, possible for an `Item`'s key to conflict
+with one of the keys generated by a `Map` or `Deque`. In practice, this is unlikely unless you use
+very long prefixes or start your `Item`'s key with the null byte. Probably don't do that!
+
+:::
+
+## Values
+
+In `cw-storage-plus`, every value is saved using JSON serialization. For that to be possible, only
+types that implement [`serde::Serialize`](https://docs.rs/serde/1.0.201/serde/trait.Serialize.html)
+and [`serde::Deserialize`](https://docs.rs/serde/1.0.201/serde/trait.Deserialize.html) are allowed.
+
+Most of the Rust standard library types already implement these traits. Additionally, types you'll
+find in `cosmwasm_std` (like
+[`Addr`](https://docs.rs/cosmwasm-std/2.0.3/cosmwasm_std/struct.Addr.html),
+[`Decimal`](https://docs.rs/cosmwasm-std/2.0.3/cosmwasm_std/struct.Decimal.html),
+[`Binary`](https://docs.rs/cosmwasm-std/2.0.3/cosmwasm_std/struct.Binary.html) or
+[`Coin`](https://docs.rs/cosmwasm-std/2.0.3/cosmwasm_std/struct.Coin.html)) often do as well.
+
+If you're writing a custom type and wish to send it across call or put it in storage, you'll have to
+derive these traits.
+
+:::tip
+
+*cw-storage-plus* uses [*serde-json-wasm*](https://github.com/CosmWasm/serde-json-wasm) under the hood.
+This provides determinism in some corners - [*serde_json*](https://github.com/serde-rs/json)
+would not be suited for the blockchain world! On top of that, `serde-json-wasm` is just smaller.
+
+:::

docs/storage-plus/containers/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "Containers",
+  "position": 2
+}

docs/storage-plus/containers/deque.md

@@ -0,0 +1,185 @@
+---
+sidebar_position: 3
+---
+
+# Deque
+
+A `Deque` is a container that imitates a traditional double-ended queue. It's designed for efficient
+pushes and pops from either the beginning or end of the queue, making it suitable for use as a queue or stack.
+However, it's not optimized for insertions or deletions from the middle.
+
+:::tip
+
+More information can be found in the [API docs].
+
+:::
+
+## Deque operations
+
+The main operations available for a `Deque` are [`push_back`], [`push_front`], [`pop_back`], and
+[`pop_front`]. It is also possible to check the [`len`]gth of the deque, [`get`] an element by
+index, and [`iter`]ate over the elements.
+
+[`push_back`]: https://docs.rs/cw-storage-plus/latest/cw_storage_plus/struct.Deque.html#method.push_back
+[`push_front`]: https://docs.rs/cw-storage-plus/latest/cw_storage_plus/struct.Deque.html#method.push_front
+[`pop_back`]: https://docs.rs/cw-storage-plus/latest/cw_storage_plus/struct.Deque.html#method.pop_back
+[`pop_front`]: https://docs.rs/cw-storage-plus/latest/cw_storage_plus/struct.Deque.html#method.pop_front
+[`len`]: https://docs.rs/cw-storage-plus/latest/cw_storage_plus/struct.Deque.html#method.len
+[`get`]: https://docs.rs/cw-storage-plus/latest/cw_storage_plus/struct.Deque.html#method.get
+[`iter`]: https://docs.rs/cw-storage-plus/latest/cw_storage_plus/struct.Deque.html#method.iter
+
+- `push_back`: Adds an element to the end of the deque. O(1) time complexity.
+- `push_front`: Adds an element to the beginning of the deque. O(1) time complexity.
+- `pop_back`: Removes and returns the last element. Returns `None` if the deque is empty. O(1) time complexity.
+- `pop_front`: Removes and returns the first element. Returns `None` if the deque is empty. O(1) time complexity.
+- `len`: Returns the number of elements in the deque. O(1) time complexity.
+- `is_empty`: Returns `true` if the deque contains no elements. O(1) time complexity.
+- `get`: Retrieves an element by index. Returns `None` if the index is out of bounds. O(1) time complexity.
+- `front`: Returns a reference to the first element without removing it. Returns `None` if the deque is empty.
+- `back`: Returns a reference to the last element without removing it. Returns `None` if the deque is empty.
+- `iter`: Returns an iterator over the elements of the deque.
+
+:::warning
+
+The maximum capacity of a `Deque` is `u32::MAX - 1` elements. Attempting to push more elements
+is considered **Undefined Behavior**.
+  
+:::
+
+## Deque lifecycle
+
+Creating a `Deque` doesn't immediately commit anything to storage. To add elements to the deque, you
+need to use the `push_back` or `push_front` methods.
+
+Values in a `Deque` must implement the `Serialize` and `Deserialize` traits from the [`serde`] crate
+to be stored.
+
+### Lifecycle example
+
+```rust
+use cw_storage_plus::Deque;
+
+// Create a new deque. It doesn't exist in storage yet.
+let deque: Deque<u32> = Deque::new("d");
+assert_eq!(deque.len(&storage).unwrap(), 0);
+
+// Add elements to the deque
+deque.push_back(&mut storage, &2).unwrap();
+deque.push_back(&mut storage, &3).unwrap();
+deque.push_front(&mut storage, &1).unwrap();
+
+// Check the length
+assert_eq!(deque.len(&storage).unwrap(), 3);
+
+// Remove elements
+assert_eq!(deque.pop_back(&mut storage).unwrap(), Some(3));
+assert_eq!(deque.pop_front(&mut storage).unwrap(), Some(1));
+
+// Check the final state
+assert_eq!(deque.len(&storage).unwrap(), 1);
+assert_eq!(deque.get(&storage, 0).unwrap(), Some(2));
+```
+
+## Usage examples
+
+### Using Deque as a queue
+
+```rust
+use cw_storage_plus::Deque;
+
+let queue: Deque<String> = Deque::new("q");
+
+// Enqueue elements
+queue.push_back(&mut storage, &"first".to_string()).unwrap();
+queue.push_back(&mut storage, &"second".to_string()).unwrap();
+
+// Dequeue elements
+assert_eq!(queue.pop_front(&mut storage).unwrap(), Some("first".to_string()));
+assert_eq!(queue.pop_front(&mut storage).unwrap(), Some("second".to_string()));
+assert_eq!(queue.pop_front(&mut storage).unwrap(), None);
+```
+
+### Using Deque as a stack
+
+```rust
+use cw_storage_plus::Deque;
+
+let stack: Deque<u32> = Deque::new("s");
+
+// Push elements
+stack.push_back(&mut storage, &1).unwrap();
+stack.push_back(&mut storage, &2).unwrap();
+stack.push_back(&mut storage, &3).unwrap();
+
+// Pop elements
+assert_eq!(stack.pop_back(&mut storage).unwrap(), Some(3));
+assert_eq!(stack.pop_back(&mut storage).unwrap(), Some(2));
+assert_eq!(stack.pop_back(&mut storage).unwrap(), Some(1));
+assert_eq!(stack.pop_back(&mut storage).unwrap(), None);
+```
+
+### Iterating over elements
+
+```rust
+use cw_storage_plus::Deque;
+
+let deque: Deque<u32> = Deque::new("d");
+
+deque.push_back(&mut storage, &1).unwrap();
+deque.push_back(&mut storage, &2).unwrap();
+deque.push_back(&mut storage, &3).unwrap();
+
+let sum: u32 = deque.iter(&storage).unwrap().map(|r| r.unwrap()).sum();
+assert_eq!(sum, 6);
+```
+
+### Maintaining a log store
+
+It is possible to use a `Deque` to maintain a store of log events or transaction records. This is
+useful when you want to keep a history of production level events to ease in debugging a deployed
+instance of a contract.
+
+```rust
+use cw_storage_plus::Deque;
+use serde::{Serialize, Deserialize};
+use cosmwasm_std::testing::*;
+use cosmwasm_std::Addr;
+
+#[derive(Serialize, Deserialize, Clone, Debug, PartialEq)]
+struct Log {
+    block_height: u64,
+    sender_addr: String,
+    event: String,
+}
+
+// Initialize the Deque for storing logs
+let logs: Deque<Log> = Deque::new("logs");
+
+// Simulating contract execution context
+let env = mock_env();
+let info = message_info(&Addr::unchecked("sender"), &[]);
+let event = "funds_transferred".to_string();
+
+// Add a new log entry
+logs.push_front(
+    &mut storage,
+    &Log {
+        block_height: env.block.height,
+        sender_addr: info.sender.to_string(),
+        event: event.clone(),
+    },
+).unwrap();
+
+// Optionally, limit the number of stored logs
+const MAX_LOGS: u32 = 100;
+if logs.len(&storage).unwrap() > MAX_LOGS {
+    logs.pop_back(&mut storage).unwrap();
+}
+
+// Retrieve the most recent log
+let latest_log = logs.get(&storage, 0).unwrap().unwrap();
+assert_eq!(latest_log.event, "funds_transferred");
+```
+
+[`serde`]: https://serde.rs/
+[API docs]: https://docs.rs/cw-storage-plus/latest/cw_storage_plus/struct.Deque.html