Add single contract tutorial docs (#135)

* rename wasm script

* add wasm build to CI

* fix deployment imports on counter

* re-export tokio when daemon feature is enabled

* formatting

* pass --all-features to docs.rs when building docs

* default state file to `state.json`

* update docs and add anchors

* update further docs

* format

* update sections and add workspace placeholder.

* format our stuff

* fix doctest

* bump tx query retries

* add deny(missing_docs)

* formatting

* add #![deny(missing_docs)] and fix all the missing docs

* fix deploy mod comment

* update prelude doc comment

* format

* fix doc comment

* remove bin folder from gitignore

* remove unused deps and move executable to examples

* fix docs

* compile to wasm

* format

* group imports

* fmt

* add doc comment to re-exports

* remove mdbook from test job

* add mdbook-keeper to just install-docs command

* build docs and add to gitattributes

* fix git attribute

* improve doc structure and reference

* update html settings

* formatting

* fix edit url

* build the docs

* fix edit url

Author: CyberHoward

.gitattributes

@@ -0,0 +1 @@
+docs/book linguist-generated=true

.github/workflows/check.yml

@@ -91,3 +91,24 @@ jobs:
           toolchain: ${{ matrix.msrv }}
       - name: cargo +${{ matrix.msrv }} check
         run: cargo check
+
+  build-artifacts:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: Install latest stable
+        uses: ATiltedTree/setup-rust@v1
+        with:
+          rust-version: stable
+      - name: Setup Docker Buildx
+        uses: docker/setup-buildx-action@v2
+      - name: Generate Cargo.lock
+        run: |
+          cargo fetch --verbose
+      - name: Build Artifacts
+        run: |
+          docker run --rm -v "$(pwd)":/code \
+          --mount type=volume,source="$(basename "$(pwd)")_cache",target=/code/target \
+          --mount type=volume,source=registry_cache,target=/usr/local/cargo/registry \
+          cosmwasm/workspace-optimizer:0.12.13
+          tar -zcvf cosmwasm-artifacts.tar.gz artifacts

.github/workflows/test.yml

@@ -46,12 +46,6 @@ jobs:
         run: cargo generate-lockfile
       - name: cargo test --doc
         run: cargo test --doc --locked --all-features
-      - name: install mdbook
-        run: cargo install mdbook
-      - name: install mdbook-keeper
-        run: cargo install mdbook-keeper
-      - name: mdbook build
-        run: mdbook build docs
 
   coverage:
     runs-on: ubuntu-latest

.gitignore

@@ -19,5 +19,4 @@ Cargo.lock
 **/profraw_data/
 gen_cov_test
 
-**/bin/
 **/logs/

Cargo.toml

@@ -1,6 +1,7 @@
 [workspace]
 members = ["cw-orch", "packages/*", "contracts/*"]
 version = "0.11.4"
+resolver = "2"
 
 [workspace.package]
 authors = ["CyberHoward <[email protected]>"]

artifacts/checksums.txt

@@ -0,0 +1,5 @@
+ec347443a5ed4442b2cc166bce53ebab18d8a881543acc11fbca68a9bb092362  counter_contract-aarch64.wasm
+ed55bd2c18c7fbd20e9b15f56ff619a986a47a363c66358382c4c2fcf16e6389  mock_contract-aarch64.wasm
+bf962e11fdb38c2825c24046ae96577f23db422954165562c5ad80e499cfeabe  mock_contract.wasm
+48856f5a5c169089cf289d31c14fd41d35bb298530577ff3c77ce08725f96496  mock_contract_u64-aarch64.wasm
+ab53bcea2fb6ef40a4df1c24640c8daa910b294b1ff185126b00b13b7fc700ee  mock_contract_u64.wasm

artifacts/checksums_intermediate.txt

@@ -0,0 +1,3 @@
+eb5428b2c02c3e3950b0e8c3ab72d29b6f8163bf843fe03f21e8ffc448061d7e  target/wasm32-unknown-unknown/release/counter_contract.wasm
+656026cb517e45bb0eee4545a2bf64406e18fc1c15391e1b6f1a6ee9d6e12107  target/wasm32-unknown-unknown/release/mock_contract.wasm
+906f015f89d79893f430bff8c7dc3168035aa4e0a2682987adc294bc11c371e9  target/wasm32-unknown-unknown/release/mock_contract_u64.wasm

artifacts/counter_contract-aarch64.wasm

@@ -4,7 +4,6 @@ version = "0.11.0"
 description = "counter constract"
 keywords = ["cosmwasm", "blockchain"]
 edition = { workspace = true }
-
 exclude = [".env"]
 
 [lib]
@@ -22,13 +21,14 @@ cw2 = "1.0"
 cosmwasm-schema = "1.2"
 schemars = "0.8.10"
 thiserror = { version = "1.0.21" }
-anyhow = { workspace = true }
 serde = { workspace = true }
 serde_json = "1.0.79"
-log = "0.4.14"
-
 cw-orch = { path = "../../cw-orch", optional = true }
 
 [dev-dependencies]
 cw-multi-test = { workspace = true }
 counter-contract = { path = ".", features = ["interface"] }
+# Deps for deployment
+dotenv = { version = "0.15.0" }
+env_logger = { version = "0.10.0" }
+cw-orch = { path = "../../cw-orch", features = ["daemon"] }

artifacts/mock_contract-aarch64.wasm

@@ -0,0 +1,22 @@
+use counter_contract::{msg::InstantiateMsg, CounterContract};
+use cw_orch::{anyhow, prelude::*, tokio};
+use tokio::runtime::Runtime;
+
+/// Script that registers the first Account in abstract (our Account)
+pub fn main() -> anyhow::Result<()> {
+    dotenv::dotenv().ok();
+    env_logger::init();
+
+    let rt = Runtime::new()?;
+    let network = networks::LOCAL_JUNO;
+    let chain = DaemonBuilder::default()
+        .handle(rt.handle())
+        .chain(network)
+        .build()?;
+
+    let counter = CounterContract::new("counter_contract", chain);
+
+    counter.upload()?;
+    counter.instantiate(&InstantiateMsg { count: 0 }, None, None)?;
+    Ok(())
+}

artifacts/mock_contract_u64-aarch64.wasm

@@ -1,16 +1,21 @@
-use cosmwasm_std::entry_point;
-use cosmwasm_std::{to_binary, Binary, Deps, DepsMut, Env, MessageInfo, Response, StdResult};
+use cosmwasm_std::{
+    entry_point, to_binary, Binary, Deps, DepsMut, Env, MessageInfo, Response, StdResult,
+};
 use cw2::set_contract_version;
 
-use crate::{error::*, msg::*, state::*};
+use crate::{error::*, execute, msg::*, query, state::*};
 
 // version info for migration info
 pub const CONTRACT_NAME: &str = "crates.io:counter";
 const CONTRACT_VERSION: &str = env!("CARGO_PKG_VERSION");
 
 // ANCHOR: interface_entry
+// ANCHOR: entry_point_line
 #[cfg_attr(feature = "export", entry_point)]
+// ANCHOR_END: entry_point_line
+// ANCHOR: interface_line
 #[cfg_attr(feature = "interface", cw_orch::interface_entry_point)]
+// ANCHOR_END: interface_line
 pub fn instantiate(
     deps: DepsMut,
     _env: Env,
@@ -43,31 +48,6 @@ pub fn execute(
         ExecuteMsg::Reset { count } => execute::reset(deps, info, count),
     }
 }
-// ANCHOR_END: interface_entry
-
-pub mod execute {
-    use super::*;
-
-    pub fn increment(deps: DepsMut) -> Result<Response, ContractError> {
-        STATE.update(deps.storage, |mut state| -> Result<_, ContractError> {
-            state.count += 1;
-            Ok(state)
-        })?;
-
-        Ok(Response::new().add_attribute("action", "increment"))
-    }
-
-    pub fn reset(deps: DepsMut, info: MessageInfo, count: i32) -> Result<Response, ContractError> {
-        STATE.update(deps.storage, |mut state| -> Result<_, ContractError> {
-            if info.sender != state.owner {
-                return Err(ContractError::Unauthorized {});
-            }
-            state.count = count;
-            Ok(state)
-        })?;
-        Ok(Response::new().add_attribute("action", "reset"))
-    }
-}
 
 #[cfg_attr(feature = "export", entry_point)]
 #[cfg_attr(feature = "interface", cw_orch::interface_entry_point)]
@@ -77,27 +57,20 @@ pub fn query(deps: Deps, _env: Env, msg: QueryMsg) -> StdResult<Binary> {
     }
 }
 
-pub mod query {
-    use super::*;
-
-    pub fn count(deps: Deps) -> StdResult<GetCountResponse> {
-        let state = STATE.load(deps.storage)?;
-        Ok(GetCountResponse { count: state.count })
-    }
-}
-
 #[cfg_attr(feature = "export", entry_point)]
 #[cfg_attr(feature = "interface", cw_orch::interface_entry_point)]
 pub fn migrate(_deps: DepsMut, _env: Env, _msg: MigrateMsg) -> Result<Response, ContractError> {
-    // TODO: Migrate state
     Ok(Response::default().add_attribute("action", "migrate"))
 }
+// ANCHOR_END: interface_entry
 
 #[cfg(test)]
 mod tests {
     use super::*;
-    use cosmwasm_std::testing::{mock_dependencies, mock_env, mock_info};
-    use cosmwasm_std::{coins, from_binary};
+    use cosmwasm_std::{
+        coins, from_binary,
+        testing::{mock_dependencies, mock_env, mock_info},
+    };
 
     #[test]
     fn proper_initialization() {

contracts/counter/Cargo.toml

@@ -0,0 +1,23 @@
+use cosmwasm_std::{DepsMut, MessageInfo, Response};
+
+use crate::{error::*, state::*};
+
+pub fn increment(deps: DepsMut) -> Result<Response, ContractError> {
+    STATE.update(deps.storage, |mut state| -> Result<_, ContractError> {
+        state.count += 1;
+        Ok(state)
+    })?;
+
+    Ok(Response::new().add_attribute("action", "increment"))
+}
+
+pub fn reset(deps: DepsMut, info: MessageInfo, count: i32) -> Result<Response, ContractError> {
+    STATE.update(deps.storage, |mut state| -> Result<_, ContractError> {
+        if info.sender != state.owner {
+            return Err(ContractError::Unauthorized {});
+        }
+        state.count = count;
+        Ok(state)
+    })?;
+    Ok(Response::new().add_attribute("action", "reset"))
+}

contracts/counter/examples/deploy.rs

@@ -0,0 +1,71 @@
+#![allow(unused)]
+// ANCHOR: custom_interface
+use cw_orch::{
+    anyhow::Result,
+    interface,
+    prelude::{queriers::Node, *},
+};
+
+use crate::{
+    contract::CONTRACT_NAME,
+    msg::{ExecuteMsg, InstantiateMsg, MigrateMsg, QueryMsg},
+    CounterContract,
+};
+
+#[interface(InstantiateMsg, ExecuteMsg, QueryMsg, MigrateMsg)]
+pub struct Counter;
+
+impl<Chain: CwEnv> Uploadable for Counter<Chain> {
+    // Return the path to the wasm file
+    fn wasm(&self) -> WasmPath {
+        let crate_path = env!("CARGO_MANIFEST_DIR");
+        let wasm_path = format!("{}/../artifacts/{}", crate_path, "mock.wasm");
+
+        WasmPath::new(wasm_path).unwrap()
+    }
+    // Return a CosmWasm contract wrapper
+    fn wrapper(&self) -> Box<dyn MockContract<Empty>> {
+        Box::new(
+            ContractWrapper::new_with_empty(
+                crate::contract::execute,
+                crate::contract::instantiate,
+                crate::contract::query,
+            )
+            .with_migrate(crate::contract::migrate),
+        )
+    }
+}
+// ANCHOR_END: custom_interface
+
+// ANCHOR: daemon
+impl Counter<Daemon> {
+    /// Deploys the counter contract at a specific block height
+    pub fn await_launch(&self) -> Result<()> {
+        let daemon = self.get_chain();
+        let rt = daemon.rt_handle.clone();
+
+        rt.block_on(async {
+            // Get the node query client, there are a lot of other clients available.
+            let node = daemon.query_client::<Node>();
+            let mut latest_block = node.latest_block().await.unwrap();
+
+            while latest_block.header.height.value() < 100 {
+                // wait for the next block
+                daemon.next_block().unwrap();
+                latest_block = node.latest_block().await.unwrap();
+            }
+        });
+
+        let contract = CounterContract::new(CONTRACT_NAME, daemon.clone());
+
+        // Upload the contract
+        contract.upload().unwrap();
+
+        // Instantiate the contract
+        let msg = InstantiateMsg { count: 1i32 };
+        contract.instantiate(&msg, None, None).unwrap();
+
+        Ok(())
+    }
+}
+// ANCHOR_END: daemon

contracts/counter/src/contract.rs

@@ -1,12 +1,21 @@
 pub mod contract;
 mod error;
+pub(crate) mod execute;
 pub mod msg;
+pub(crate) mod query;
 pub mod state;
 
 pub use crate::error::ContractError;
 // ANCHOR: interface_reexport
 #[cfg(feature = "interface")]
 pub use crate::contract::CounterContract;
 // ANCHOR_END: interface_reexport
+// ANCHOR: fn_re_export
 #[cfg(feature = "interface")]
 pub use crate::msg::{ExecuteMsgFns as CounterExecuteMsgFns, QueryMsgFns as CounterQueryMsgFns};
+// ANCHOR_END: fn_re_export
+
+// ANCHOR: custom_interface
+#[cfg(feature = "interface")]
+mod interface;
+// ANCHOR_END: custom_interface

contracts/counter/src/execute.rs

@@ -5,27 +5,31 @@ pub struct InstantiateMsg {
     pub count: i32,
 }
 
+// ANCHOR: exec_msg
 #[cw_serde]
-#[cfg_attr(feature = "interface", derive(cw_orch::ExecuteFns))]
+#[cfg_attr(feature = "interface", derive(cw_orch::ExecuteFns))] // Function generation
 pub enum ExecuteMsg {
     Increment {},
     Reset { count: i32 },
 }
+// ANCHOR_END: exec_msg
 
+// ANCHOR: query_msg
 #[cw_serde]
-#[cfg_attr(feature = "interface", derive(cw_orch::QueryFns))]
+#[cfg_attr(feature = "interface", derive(cw_orch::QueryFns))] // Function generation
 #[derive(QueryResponses)]
 pub enum QueryMsg {
     // GetCount returns the current count as a json-encoded number
     #[returns(GetCountResponse)]
     GetCount {},
 }
 
-// We define a custom struct for each query response
+// Custom response for the query
 #[cw_serde]
 pub struct GetCountResponse {
     pub count: i32,
 }
+// ANCHOR_END: query_msg
 
 #[cw_serde]
 pub struct MigrateMsg {

contracts/counter/src/interface.rs

@@ -0,0 +1,8 @@
+use cosmwasm_std::{Deps, StdResult};
+
+use crate::{msg::GetCountResponse, state::STATE};
+
+pub fn count(deps: Deps) -> StdResult<GetCountResponse> {
+    let state = STATE.load(deps.storage)?;
+    Ok(GetCountResponse { count: state.count })
+}