reference-docs: Start `state` and mention well known keys (#7037)

Closes: https://github.com/paritytech/polkadot-sdk/issues/7033

Cargo.lock

@@ -19202,6 +19202,7 @@ dependencies = [
  "sp-runtime 31.0.1",
  "sp-runtime-interface 24.0.0",
  "sp-std 14.0.0",
+ "sp-storage 19.0.0",
  "sp-tracing 16.0.0",
  "sp-version 29.0.0",
  "sp-weights 27.0.0",

docs/sdk/Cargo.toml

@@ -110,6 +110,7 @@ sp-offchain = { workspace = true, default-features = true }
 sp-runtime = { workspace = true, default-features = true }
 sp-runtime-interface = { workspace = true, default-features = true }
 sp-std = { workspace = true, default-features = true }
+sp-storage = { workspace = true, default-features = true }
 sp-tracing = { workspace = true, default-features = true }
 sp-version = { workspace = true, default-features = true }
 sp-weights = { workspace = true, default-features = true }

docs/sdk/src/reference_docs/mod.rs

@@ -111,3 +111,6 @@ pub mod custom_runtime_api_rpc;
 
 /// The [`polkadot-omni-node`](https://crates.io/crates/polkadot-omni-node) and its related binaries.
 pub mod omni_node;
+
+/// Learn about the state in Substrate.
+pub mod state;

docs/sdk/src/reference_docs/state.rs

+//! # State
+//!
+//! The state is abstracted as a key-value like database. Every item that
+//! needs to be persisted by the [State Transition
+//! Function](crate::reference_docs::blockchain_state_machines) is written to the state.
+//!
+//! ## Special keys
+//!
+//! The key-value pairs in the state are represented as byte sequences. The node
+//! doesn't know how to interpret most the key-value pairs. However, there exist some
+//! special keys and its values that are known to the node, the so-called
+//! [`well-known-keys`](sp_storage::well_known_keys).

substrate/primitives/storage/src/lib.rs

@@ -191,11 +191,15 @@ pub mod well_known_keys {
 	/// Wasm code of the runtime.
 	///
 	/// Stored as a raw byte vector. Required by substrate.
+	///
+	/// Encodes to `0x3A636F6465`.
 	pub const CODE: &[u8] = b":code";
 
 	/// Number of wasm linear memory pages required for execution of the runtime.
 	///
 	/// The type of this value is encoded `u64`.
+	///
+	/// Encodes to `0x307833413633364636343635`
 	pub const HEAP_PAGES: &[u8] = b":heappages";
 
 	/// Current extrinsic index (u32) is stored under this key.