new cosmwasm doc

docs/CAPABILITIES.md

@@ -1,27 +1,19 @@
-# Capabilities
-
-Capabilities are a mechanism to negotiate functionality between a contract and
-an environment (i.e. the chain that embeds cosmwasm-vm/[wasmvm]) in a very
-primitive way. The contract defines required capabilities. The environment
-defines it's capabilities. If the required capabilities are all available, the
-contract can be used. Doing this check when the contract is first stored ensures
-missing capabilities are detected early and not when a user tries to execute a
-certain code path.
-
-## Origin and Disambiguation
-
-Before August 2022, we had two types of "features": app level features in the
-CosmWasm VM and Cargo's build system features. In order to avoid the confusion,
-the former have been renamed to capabilities.
-
-Capabilities can be implemented in any language that compiles to Wasm whereas
-features are Rust build system specific.
-
-## Required capabilities
-
-The contract defines required capabilities using marker export functions that
-take no arguments and return no value. The name of the export needs to start
-with "requires\_" followed by the name of the capability.
+# Overview
+**Capabilities** in CosmosWasm are a fundamental concept, designed to facilitate the interaction between a smart contract and its operational environment (i.e., the blockchain implementing the cosmwasm-vm or [wasmvm]). This mechanism operates by matching the capabilities required by a contract with those offered by the environment.
+
+# The Essence of Capabilities
+**Purpose:** They serve as a negotiation tool, ensuring that a contract only operates in an environment where all its necessary functionalities are present.
+**Early Detection:** By verifying capabilities when a contract is first stored, any discrepancies or missing capabilities are identified early. This preemptive approach prevents potential runtime failures during execution.
+
+# Historical Context: Origin and Disambiguation
+**Prior to August 2022:** The term "features" was used ambiguously to describe both app-level features in the CosmWasm VM and features in Cargo's build system.
++**Redefinition:** To mitigate this confusion, app-level features in the CosmWasm VM were renamed to "capabilities", distinguishing them from Cargo's build system features.
++**Language Independence:** Unlike Rust-specific features, capabilities can be implemented in any language that compiles to Wasm, broadening their applicability.
+
+# Defining Required Capabilities
+## Implementation
+**Marker Export Functions:** Contracts specify required capabilities using these functions, which have no arguments and return no value.
+**Naming Convention:** The export name begins with "requires\_" followed by the capability name, establishing a clear and standardized method for declaration.
 
 An example of such markers in cosmwasm-std are those:
 

docs/STORAGE_KEYS.md

@@ -1,17 +1,21 @@
 # Storage keys
 
-CosmWasm provides a generic key value store to contract developers via the
-`Storage` trait. This is powerful but the nature of low level byte operations
-makes it hard to use for high level storage types. In this document we discuss
-the foundations of storage key composition all the way up to cw-storage-plus.
-
-In a simple world, all you need is a `&[u8]` key which you can get e.g. using
-`&17u64.to_be_bytes()`. This is an 8 bytes key with an encoded integer. But if
-you have multiple data types in your contract, you want to prefix those keys in
-order to avoid collisions. A simple concatenation is not sufficient because you
-want to avoid collisions when part of the prefixes and part of the key overlap.
-E.g. `b"keya" | b"x"` and `b"key" | b"ax"` (`|` denotes concatenation) must not
-have the same binary representation.
+CosmWasm introduces a versatile key-value store accessible to contract developers
+through the `Storage` trait. This low-level byte operation-based system, while powerful, 
+can be challenging for managing high-level storage types. This documentation explores 
+the evolution of storage key composition in CosmWasm, leading up to the current 
+implementation in cw-storage-plus.
+
+# The Challenge of Key Composition
+
+The fundamental requirement for storage keys in CosmWasm is a `&[u8]` key, which
+can be obtained from basic types like integers (e.g., `&17u64.to_be_bytes()`). 
+However, when handling various data types within a contract, it's crucial to 
+use prefixed keys to prevent data collisions. 
+Simple concatenation of keys is insufficient due to potential overlap issues. 
+For instance, `b"keya" | b"x"` and `b"key" | b"ax"` should not yield the same binary representation, where | denotes concatenation.
+
+# Evolution of Key Namespacing
 
 In the early days, multiple approaches of key namespacing were discussed and
 were documented here: https://github.com/webmaster128/key-namespacing. The "0x00
@@ -39,12 +43,11 @@ pub fn to_length_prefixed_nested(namespaces: &[&[u8]]) -> Vec<u8>
 fn concat(namespace: &[u8], key: &[u8]) -> Vec<u8>
 ```
 
-With the emerging cw-storage-plus we see two additions to that approach:
+# Transition to `cw-storage-plus`
+With the introduction of cw-storage-plus, there were significant enhancements:
 
-1. Manually creating the namespace and concatenating it with `concat` makes no
-   sense anymore. Instead `namespace` and `key` are always provided and a
-   composed database key is created.
-2. Using a multi component namespace becomes the norm.
+1. **Simplified Key Composition:** The manual creation of namespaces followed by concatenation using concat was replaced by a more integrated approach, where namespace and key are provided together to create a composed database key.
+2. **Multi-component Namespaces:** Using multiple components in a namespace became commonplace.
 
 This led to the following addition in cw-storage-plus:
 
@@ -68,14 +71,10 @@ With the deprecation if cosmwasm-storage and the adoption of the system in
 cw-storage-plus, it is time to do a few changes to the Length-prefixed keys
 standard, without breaking existing users.
 
-1. Remove the single component `to_length_prefixed` implementation and fully
-   commit to the multi-component version. This shifts focus from the recursive
-   implementation to the compatible iterative implementation.
-2. Rename "namespaces" to just "namespace" and let one namespace have multiple
-   components.
-3. Adopt the combined namespace + key encoder `namespaces_with_key` from
-   cw-storage-plus.
-4. Add a decomposition implementation
+1. **Removal of Single Component Implementation:** The `to_length_prefixed` single-component version will be deprecated in favor of the multi-component `to_length_prefixed_nested` approach.
+2. **Terminology Adjustment:** The term "namespaces" will be simplified to "namespace", encompassing multiple components.
+3. **Adoption of Combined Encoder:** The `namespaces_with_key` function from `cw-storage-plus` will be the standard for key encoding.
+4. **Decomposition Feature:** Introduction of a feature to decompose keys for enhanced flexibility.
 
 Given the importance of Length-prefixed keys for the entire CosmWasm ecosystem,
 those implementations should be maintained in cosmwasm-std. The generic approach

packages/std/src/addresses.rs

@@ -249,7 +249,8 @@ impl fmt::Display for CanonicalAddr {
         Ok(())
     }
 }
-
+/// Errors related to the instantiation of contracts and generation of addresses.
+/// Ensures the integrity and validity of newly created contracts.
 #[derive(Error, Debug, PartialEq, Eq)]
 pub enum Instantiate2AddressError {
     /// Checksum must be 32 bytes

packages/std/src/deps.rs

@@ -15,13 +15,13 @@ pub struct OwnedDeps<S: Storage, A: Api, Q: Querier, C: CustomQuery = Empty> {
     pub querier: Q,
     pub custom_query_type: PhantomData<C>,
 }
-
+/// A mutable version of `Deps` that allows changes to the dependencies.
 pub struct DepsMut<'a, C: CustomQuery = Empty> {
     pub storage: &'a mut dyn Storage,
     pub api: &'a dyn Api,
     pub querier: QuerierWrapper<'a, C>,
 }
-
+/// Represents dependencies required by a contract for execution, like storage and API access.
 #[derive(Clone)]
 pub struct Deps<'a, C: CustomQuery = Empty> {
     pub storage: &'a dyn Storage,

packages/std/src/errors/recover_pubkey_error.rs

@@ -4,7 +4,8 @@ use cosmwasm_crypto::CryptoError;
 
 use super::BT;
 use thiserror::Error;
-
+/// Errors encountered during the recovery of a public key.
+/// Typically arises from operations involving signatures or encrypted data.
 #[derive(Error, Debug)]
 pub enum RecoverPubkeyError {
     #[error("Invalid hash format")]

packages/std/src/errors/std_error.rs

@@ -393,12 +393,12 @@ impl From<DivideByZeroError> for StdError {
     }
 }
 
-/// The return type for init, execute and query. Since the error type cannot be serialized to JSON,
-/// this is only available within the contract and its unit tests.
-///
-/// The prefix "Std" means "the standard result within the standard library". This is not the only
-/// result/error type in cosmwasm-std.
+/// `StdResult` is typically used in scenarios where a function within the contract needs to return a result or indicate an error
+/// that is specific to the contract's internal operations. Since the error component of `StdResult` is not meant for JSON serialization,
+/// it should be used with caution when designing functions that interact with external systems or data formats.
 pub type StdResult<T> = core::result::Result<T, StdError>;
+/// Indicates operations that are prone to overflow.
+/// Used to mark numerical operations where overflow checks are necessary.
 
 #[derive(Error, Debug, PartialEq, Eq)]
 pub enum OverflowOperation {
@@ -415,7 +415,7 @@ impl fmt::Display for OverflowOperation {
         write!(f, "{self:?}")
     }
 }
-
+/// An error struct used when a numeric operation results in an overflow.
 #[derive(Error, Debug, PartialEq, Eq)]
 #[error("Cannot {operation} with given operands")]
 pub struct OverflowError {
@@ -449,7 +449,7 @@ impl ConversionOverflowError {
         }
     }
 }
-
+///An error struct used when a division operation in a contract attempts to divide by zero.
 #[derive(Error, Debug, Default, PartialEq, Eq)]
 #[error("Cannot divide by zero")]
 pub struct DivideByZeroError;
@@ -468,7 +468,8 @@ pub enum DivisionError {
     #[error("Overflow in division")]
     Overflow,
 }
-
+/// Errors that occur when multiplying a value by a [Fraction](crate::Fraction) in a checked manner.
+/// Ensures overflow safety in the operation.
 #[derive(Error, Debug, PartialEq, Eq)]
 pub enum CheckedMultiplyFractionError {
     #[error("{0}")]
@@ -480,7 +481,8 @@ pub enum CheckedMultiplyFractionError {
     #[error("{0}")]
     Overflow(#[from] OverflowError),
 }
-
+/// Represents errors during safe multiplication of a number by a fraction.
+/// Ensures accuracy and overflow prevention in calculations.
 #[derive(Error, Debug, PartialEq, Eq)]
 pub enum CheckedMultiplyRatioError {
     #[error("Denominator must not be zero")]
@@ -489,7 +491,8 @@ pub enum CheckedMultiplyRatioError {
     #[error("Multiplication overflow")]
     Overflow,
 }
-
+/// Errors that occur when safely converting from a ratio type.
+/// Ensures mathematical accuracy and prevents potential overflow issues.
 #[derive(Error, Debug, PartialEq, Eq)]
 pub enum CheckedFromRatioError {
     #[error("Denominator must not be zero")]
@@ -506,7 +509,8 @@ pub struct RoundUpOverflowError;
 #[derive(Error, Debug, PartialEq, Eq)]
 #[error("Round down operation failed because of overflow")]
 pub struct RoundDownOverflowError;
-
+/// General errors related to operations with coins,
+/// such as invalid amounts or unsupported denominations.
 #[derive(Error, Debug, PartialEq, Eq)]
 pub enum CoinsError {
     #[error("Duplicate denom")]
@@ -518,7 +522,8 @@ impl From<CoinsError> for StdError {
         Self::generic_err(format!("Creating Coins: {value}"))
     }
 }
-
+/// Errors encountered when parsing coin values from strings.
+/// Ensures that coin strings are in the correct format and valid.
 #[derive(Error, Debug, PartialEq, Eq)]
 pub enum CoinFromStrError {
     #[error("Missing denominator")]
@@ -786,4 +791,4 @@ mod tests {
             err => panic!("Unexpected error: {err:?}"),
         }
     }
-}
+}

packages/std/src/hex_binary.rs

@@ -6,6 +6,7 @@ use serde::{de, ser, Deserialize, Deserializer, Serialize};
 
 use crate::{Binary, StdError, StdResult};
 
+/// A wrapper around a vector (Vec) for hex-encoded binary data, supporting encoding and decoding operations.
 /// This is a wrapper around Vec<u8> to add hex de/serialization
 /// with serde. It also adds some helper methods to help encode inline.
 ///

packages/std/src/ibc.rs

@@ -13,8 +13,8 @@ use crate::results::{Attribute, CosmosMsg, Empty, Event, SubMsg};
 use crate::serde::to_json_binary;
 use crate::timestamp::Timestamp;
 
-/// These are messages in the IBC lifecycle. Only usable by IBC-enabled contracts
-/// (contracts that directly speak the IBC protocol via 6 entry points)
+/// Messages pertaining to the IBC lifecycle, specifically for contracts with IBC capabilities.
+/// Manages cross-chain communications and other IBC protocol interactions.
 #[non_exhaustive]
 #[derive(Serialize, Deserialize, Clone, Debug, PartialEq, Eq, JsonSchema)]
 #[serde(rename_all = "snake_case")]
@@ -50,7 +50,7 @@ pub enum IbcMsg {
     /// Port is auto-assigned to the contract's IBC port
     CloseChannel { channel_id: String },
 }
-
+///Details about an IBC endpoint, including its port and channel information.
 #[derive(Serialize, Deserialize, Clone, Debug, PartialEq, Eq, JsonSchema)]
 pub struct IbcEndpoint {
     pub port_id: String,
@@ -147,9 +147,9 @@ impl IbcChannel {
     }
 }
 
-/// IbcOrder defines if a channel is ORDERED or UNORDERED
+/// Enumerates the ordering of messages in an IBC channel, such as ORDERED or UNORDERED.
+/// Based on the IBC specifications for message sequencing.
 /// Values come from https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/ibc/core/channel/v1/channel.proto#L69-L80
-/// Naming comes from the protobuf files and go translations.
 #[derive(Serialize, Deserialize, Clone, Debug, PartialEq, Eq, JsonSchema)]
 pub enum IbcOrder {
     #[serde(rename = "ORDER_UNORDERED")]
@@ -192,7 +192,7 @@ impl Ord for IbcTimeoutBlock {
         }
     }
 }
-
+///Struct representing an IBC packet, which contains data transferred across different blockchains.
 #[derive(Serialize, Deserialize, Clone, Debug, PartialEq, Eq, JsonSchema)]
 #[non_exhaustive]
 pub struct IbcPacket {
@@ -225,7 +225,7 @@ impl IbcPacket {
         }
     }
 }
-
+///Represents an acknowledgement message in the IBC protocol.
 #[derive(Serialize, Deserialize, Clone, Debug, PartialEq, Eq, JsonSchema)]
 #[non_exhaustive]
 pub struct IbcAcknowledgement {
@@ -246,7 +246,8 @@ impl IbcAcknowledgement {
     }
 }
 
-/// The message that is passed into `ibc_channel_open`
+/// Message used to establish a connection in an IBC channel.
+/// Initiates the setup for cross-chain or inter-module communication.  
 #[derive(Serialize, Deserialize, Clone, Debug, PartialEq, Eq, JsonSchema)]
 #[serde(rename_all = "snake_case")]
 pub enum IbcChannelOpenMsg {
@@ -304,12 +305,14 @@ impl From<IbcChannelOpenMsg> for IbcChannel {
 pub type IbcChannelOpenResponse = Option<Ibc3ChannelOpenResponse>;
 
 #[derive(Serialize, Deserialize, Clone, Debug, PartialEq, Eq, JsonSchema)]
+///A response format for IBC channel open queries, providing details about the channel's status.
 pub struct Ibc3ChannelOpenResponse {
     /// We can set the channel version to a different one than we were called with
     pub version: String,
 }
 
-/// The message that is passed into `ibc_channel_connect`
+/// Message used to establish a connection in an IBC channel.
+/// Initiates the setup for cross-chain or inter-module communication.
 #[derive(Serialize, Deserialize, Clone, Debug, PartialEq, Eq, JsonSchema)]
 #[serde(rename_all = "snake_case")]
 pub enum IbcChannelConnectMsg {
@@ -410,8 +413,7 @@ impl IbcPacketReceiveMsg {
         Self { packet, relayer }
     }
 }
-
-/// The message that is passed into `ibc_packet_ack`
+/// Message format used when acknowledging the receipt of an IBC packet.
 #[derive(Serialize, Deserialize, Clone, Debug, PartialEq, Eq, JsonSchema)]
 #[non_exhaustive]
 pub struct IbcPacketAckMsg {
@@ -454,7 +456,8 @@ impl IbcPacketTimeoutMsg {
 ///
 /// Callbacks that have return values (like receive_packet)
 /// or that cannot redispatch messages (like the handshake callbacks)
-/// will use other Response types
+/// will use other Response types.
+/// A general response structure for IBC handler operations, used when a specific response format isn't required.
 #[derive(Serialize, Deserialize, Clone, Debug, PartialEq, Eq, JsonSchema)]
 #[non_exhaustive]
 pub struct IbcBasicResponse<T = Empty> {

packages/std/src/math/fraction.rs

@@ -31,7 +31,8 @@ impl<T: Copy + From<u8> + PartialEq> Fraction<T> for (T, T) {
         }
     }
 }
-
+//Adds a function to a type that allows you to multiply instances of that type by a fraction.
+//It's useful for calculations involving fractional multiplication.
 #[macro_export]
 macro_rules! impl_mul_fraction {
     ($Uint:ident) => {

packages/std/src/math/signed_decimal.rs

@@ -26,7 +26,7 @@ use super::Int128;
 pub struct SignedDecimal(#[schemars(with = "String")] Int128);
 
 forward_ref_partial_eq!(SignedDecimal, SignedDecimal);
-
+///Similar to `SignedDecimal256RangeExceeded`, but for standard `SignedDecimal` operations.
 #[derive(Error, Debug, PartialEq, Eq)]
 #[error("SignedDecimal range exceeded")]
 pub struct SignedDecimalRangeExceeded;

packages/std/src/math/signed_decimal_256.rs

@@ -31,7 +31,7 @@ use super::Int256;
 pub struct SignedDecimal256(#[schemars(with = "String")] Int256);
 
 forward_ref_partial_eq!(SignedDecimal256, SignedDecimal256);
-
+/// Indicates an error when a SignedDecimal256 operation exceeds its range.
 #[derive(Error, Debug, PartialEq, Eq)]
 #[error("SignedDecimal256 range exceeded")]
 pub struct SignedDecimal256RangeExceeded;