storage-plus: Introduction and Basics

src/pages/cw-storage-plus.md

@@ -1,4 +1,45 @@
 # Introduction
 
-TODO: Describe what low-level interface `cw-storage-plus` builds on, and how it
-provides typed abstractions on top of it
+Not being able to persist data across calls would limit the utility of smart
+contracts. Think of these problems:
+
+- How could a smart contract implement a token if it could not keep track of
+  balances?
+- How could a smart contract implement a voting system if it could not keep
+  track of votes?
+- How could a smart contract implement a game if it could not keep track of
+  scores?
+
+This is why a _CosmWasm_ smart contract has access to the storage facilities
+offered by the [_Cosmos SDK_](https://docs.cosmos.network/). These facilities
+are essentially a binary key-value store, with records stored on-chain.
+
+## Storage limits
+
+While developing smart contracts, it's important to remember on-chain storage
+is, as always, pricey. Conventionally, developers often draw the line at a
+"small logo image" (think a few KBs). If you need to store bigger things, it's
+likely time to consider off-chain storage (like IPFS or some centralized
+storage). Techniques for securely and reliably storing large data off-chain are
+beyond the scope of this document.
+
+Trying to minimize bloat is always good practice when it comes to on-chain
+storage.
+
+## What _cw-storage-plus_ builds on
+
+The smart contract framework itself (`cosmwasm-std`) provides a simple API for
+storing and retrieving data. If you're curious, you can check it out right
+[here](https://docs.rs/cosmwasm-std/2.0.3/cosmwasm_std/trait.Storage.html).
+
+This API is raw in that it exposes the **binary** key-value store. While you're
+free to use it directly, you're likely to find that finicky and error-prone.
+`cw-storage-plus` is a library that builds on top of this API to do the
+following:
+
+- eliminate the need to manually serialize and deserialize data
+- provide a type-safe interface for storing and retrieving data
+- help manage keys
+- provide featureful persistent data structures
+
+Let's explore!

src/pages/cw-storage-plus/_meta.json

@@ -1,7 +1,6 @@
 {
   "basics": "Basics",
   "containers": "Containers",
-  "key-collisions": "Key collisions",
   "iteration": "Iteration",
   "snapshots": "Snapshots",
   "multi-indexes": "Multi index collections"

src/pages/cw-storage-plus/basics.mdx

@@ -0,0 +1,84 @@
+import { Callout } from "nextra/components";
+
+# 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.
+
+<Callout>
+  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.
+</Callout>
+
+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.
+
+<Callout type="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!
+</Callout>
+
+## 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.
+
+<Callout>
+  *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.
+</Callout>