diff --git a/src/pages/cw-multi-test/getting-started/counter/counter-cosmwasm.mdx b/src/pages/cw-multi-test/getting-started/counter/counter-cosmwasm.mdx index b423137..e8ff573 100644 --- a/src/pages/cw-multi-test/getting-started/counter/counter-cosmwasm.mdx +++ b/src/pages/cw-multi-test/getting-started/counter/counter-cosmwasm.mdx @@ -2,7 +2,7 @@ tags: ["multitest", "getting started", "counter", "CosmWasm"] --- -import { Callout, Card, Cards } from "nextra/components"; +import { Card, Cards } from "nextra/components"; # Counter written in CosmWasm @@ -16,7 +16,7 @@ feel free to check the detailed explanations provided for each code snippet. ### Cargo.toml -```toml showLineNumbers filename="Cargo.toml" copy +```toml copy showLineNumbers filename="Cargo.toml" [package] name = "counter" version = "0.1.0" @@ -42,10 +42,8 @@ serde = "1.0" cw-multi-test = { version = "2", features = ["cosmwasm_2_0"] } ``` -**Detailed explanation** - - + `Cargo.toml` file is a configuration file for a Rust project, in our case for a smart contract @@ -53,50 +51,52 @@ written in Rust. Here's a detailed explanation of each section and what it's doi **\[package\]** -```toml showLineNumbers{1} filename="Cargo.toml" copy +```toml copy showLineNumbers{1} filename="Cargo.toml" [package] name = "counter" version = "0.1.0" edition = "2021" ``` -- `[package]` section provides metadata about the Rust package (smart contract library in our case). -- `name = "counter"` specifies the name of the package, it's named **counter** like our smart +- **`[package]`** section provides metadata about the Rust package (smart contract library in our + case). +- **`name = "counter"`** specifies the name of the package, it's named **counter** like our smart + contract. +- **`version = "0.1.0"`** indicates the current version of the package and the counter smart contract. -- `version = "0.1.0"` indicates the current version of the package and the counter smart contract. -- `edition = "2021"` specifies the Rust edition being used; editions in Rust are sets of language - and compiler improvements, with 2021 being one of the latest editions at the time, providing the - latest features and enhancements. +- **`edition = "2021"`** specifies the Rust edition being used; editions in Rust are sets of + language and compiler improvements, with 2021 being one of the latest editions at the time, + providing the latest features and enhancements. **\[lib\]** -```toml showLineNumbers{8} filename="Cargo.toml" copy +```toml copy showLineNumbers{8} filename="Cargo.toml" [lib] crate-type = ["cdylib", "rlib"] ``` -- `[lib]` section specifies settings for building the library. -- `crate-type` enumerates types of libraries to be produced during compiling. -- `"cdylib"` specifies that the package will be compiled as a C-compatible dynamic library; which is - required for smart contracts to run on the CosmWasm runtime. -- `"rlib"` specifies a Rust library file that can be used as a dependency for other Rust projects, - in our case for other smart contracts. +- **`[lib]`** section specifies settings for building the library. +- **`crate-type`** enumerates types of libraries to be produced during compiling. +- **`"cdylib"`** specifies that the package will be compiled as a C-compatible dynamic library; + which is required for smart contracts to run on the CosmWasm runtime. +- **`"rlib"`** specifies a Rust library file that can be used as a dependency for other Rust + projects, in our case for other smart contracts. **\[features\]** -```toml showLineNumbers{11} filename="Cargo.toml" copy +```toml copy showLineNumbers{11} filename="Cargo.toml" [features] # use library feature to disable all instantiate/execute/query exports library = [] ``` -- `[features]` section defines optional features for the Rust package. -- `library = []` defines a feature named "library", which by convention disables exporting smart - contract entry-points when set. +- **`[features]`** section defines optional features for the Rust package. +- **`library = []`** defines a feature named **library**, which when set, disables exporting smart + contract entry-points. **\[dependencies\]** -```toml showLineNumbers{15} filename="Cargo.toml" copy +```toml copy showLineNumbers{15} filename="Cargo.toml" [dependencies] cosmwasm-schema = "2" cosmwasm-std = { version = "2" } @@ -105,56 +105,85 @@ schemars = "0.8" serde = "1.0" ``` -- `[dependencies]` section lists the libraries that the package depends on. -- `cosmwasm-schema` is used for generating JSON schemas from Rust data structures, which is useful - for documentation and ensuring compatibility of messages and queries. -- `cosmwasm-std` is the standard library for CosmWasm contracts, providing common types and +- **`[dependencies]`** section lists the libraries that the package depends on. +- **`cosmwasm-schema`** is used for generating JSON schemas from Rust data structures, which is + useful for documentation and ensuring compatibility of messages and queries. +- **`cosmwasm-std`** is the standard library for CosmWasm contracts, providing common types and utilities needed for interacting with the CosmWasm runtime. -- `cw-storage-plus` is a library that provides advanced storage abstractions and utilities on top of - the basic storage capabilities in CosmWasm, making it easier to manage state within contracts. -- `schemars` is a library for generating JSON schemas, which complements `cosmwasm-schema` by +- **`cw-storage-plus`** is a library that provides advanced storage abstractions and utilities on + top of the basic storage capabilities in CosmWasm, making it easier to manage state within + contracts. +- **`schemars`** is a library for generating JSON schemas, which complements `cosmwasm-schema` by providing additional features for schema generation. -- `serde` is a widely used serialization library in Rust, allowing easy conversion of Rust data +- **`serde`** is a widely used serialization library in Rust, allowing easy conversion of Rust data structures to and from formats like JSON, which is crucial for data interchange in smart contracts. **\[dev-dependencies\]** -```toml showLineNumbers{22} filename="Cargo.toml" copy +```toml copy showLineNumbers{22} filename="Cargo.toml" [dev-dependencies] cw-multi-test = { version = "2", features = ["cosmwasm_2_0"] } ``` -- `[dev-dependencies]` section lists dependencies that are only needed for development and testing. -- `cw-multi-test` is a name of **`MultiTest`** library, and should **ALWAYS** 🚨 be placed in +- **`[dev-dependencies]`** section lists dependencies that are only needed for development and + testing. +- **`cw-multi-test`** is a name of **`MultiTest`** library, and should **ALWAYS** 🚨 be placed in `[dev-dependencies]` section. -Overall, this Cargo.toml file configures a Rust project for a CosmWasm-based smart contract. It sets -up the basic package details, specifies how the contract should be compiled, defines dependencies -for core functionality and testing, and includes features to enable or disable certain parts of the -contract code. This setup ensures the contract can be developed, tested, and deployed effectively -within the CosmWasm ecosystem. +Overall, this `Cargo.toml` file configures a Rust project for a CosmWasm-based smart contract. It +sets up the basic package details, specifies how the contract should be compiled, defines +dependencies for core functionality and testing, and includes features to enable or disable certain +parts of the contract code. This setup ensures the contract can be developed, tested, and deployed +effectively within the CosmWasm ecosystem. --- ### lib.rs -```rust filename="lib.rs" copy +```rust copy showLineNumbers filename="lib.rs" pub mod contract; pub mod msg; ``` -**Detailed explanation** - - + -(todo: extremely detailed explanation) +The `lib.rs` file in a Rust project serves as the main entry point for defining the structure of a +library. In the context of our example **counter** smart contract, the `lib.rs` file is defining and +organizing the modules that make up the contract. Recall the **counter** project file structure: + +```ansi {4,6} filename="counter (directory)" +. +├── Cargo.toml +└── src + ├── contract.rs + ├── lib.rs + └── msg.rs +``` + +We have two modules in our project `contract.rs` and `msg.rs`, so in the `lib.rs` file: + +- **`pub mod contract;`** line declares a public module named **contract**; tells Rust to include + the code from a file named `contract.rs` located in the same directory and makes the module + publicly accessible (`pub` keyword), this means other modules or external code can access the + entry-points of our smart contract. +- **`pub mod msg;`** line declares a public module named **msg**; includes the code from a file + named `msg.rs` and also makes this module public which allows other parts of the code (especially + our **counter** smart contract) to access the messages defined here. + +Overall, this `lib.rs` file is setting up the main structure of the smart contract by defining its +key components as separate modules. This organization helps in keeping the code clean, modular, and +maintainable by separating the core contract logic (`contract.rs`) from the message and query +definitions (`msg.rs`). This modular approach makes the smart contract easier to understand, extend, +and test. + +--- ### msg.rs -```rust filename="msg.rs" copy +```rust copy showLineNumbers filename="msg.rs" use cosmwasm_schema::cw_serde; #[cw_serde] @@ -181,17 +210,37 @@ pub struct CounterResponse { } ``` -**Detailed explanation** - - + -(todo: extremely detailed explanation) +The **msg** module in file `msg.rs` typically defines the messages and queries that the smart +contract accepts and responds to. Messages are usually structured as Rust enums or structs and +define the input and output interfaces of the contract. In our example this includes: + +- **`CounterInitMsg{:rust}`** enumeration, used to initialize the contract. + `CounterInitMsg::Zero{:rust}` variant initializes the counter with zero value, and + `CounterInitMsg::Set{:rust}` variant initializes the counter with an arbitrary value in range 0 + to 255. This message is passed to `instantiate{:rust}` entry-point of the counter smart contract. +- **`CounterActionMsg{:rust}`** enumeration, used to perform various actions within the contract, + especially incrementing (the `CounterActionMsg::Inc{:rust}` variant), decrementing (the + `CounterActionMsg::Dec{:rust}` variant) and setting an arbitrary counter value (the + `CounterActionMsg::Set{:rust}` variant). This message is passed to `execute{:rust}` entry-point of + the counter smart contract. +- **`CounterQuery{:rust}`** enumeration, with its single variant `CounterQuery::Value{:rust}`, used + to query the state of the contract, in our case to retrieve the current counter value. This + message is passed to `query{:rust}` entry-point of the counter smart contract. +- **`CounterResponse{:rust}`** struct with single field `value{:rust}`, used to pass the responses + (results) to queries. + +Overall, this `msg.rs` file is basically setting up the contract’s _social skills_, defining how it +interacts with the outside world by initializing, taking actions, and answering questions. Each +message type is a different way of communicating with the counter, making it an easy-going, +versatile _contract_ ready for action. ### contract.rs -```rust filename="contract.rs" copy +```rust copy showLineNumbers filename="contract.rs" #[cfg(not(feature = "library"))] use cosmwasm_std::entry_point; @@ -245,13 +294,14 @@ pub fn query(deps: Deps, _env: Env, msg: CounterQuery) -> Result - + -(todo: extremely detailed explanation) +Typically, in a smart contract project, the **contract** module ‒ placed in the `contract.rs` file ‒ +contains the core logic of the contract, including functions (entry-points) for instantiation, +execution, querying and migrating. This is where the main functionality of the smart contract is +implemented. And this is also the case for our **counter** smart contract. ## What next?