From 7570523e53d16f35fddacad0ab50f4de54e2b0e3 Mon Sep 17 00:00:00 2001 From: aumetra Date: Wed, 26 Jun 2024 15:21:49 +0200 Subject: [PATCH 1/3] Expand entrypoint docs --- docs-test-gen/Cargo.lock | 1 + docs-test-gen/Cargo.toml | 1 + src/pages/core/entrypoints.mdx | 100 +++++++++++++++++++++++++++++++-- 3 files changed, 98 insertions(+), 4 deletions(-) diff --git a/docs-test-gen/Cargo.lock b/docs-test-gen/Cargo.lock index 25f0f8df..9c7b58d4 100644 --- a/docs-test-gen/Cargo.lock +++ b/docs-test-gen/Cargo.lock @@ -429,6 +429,7 @@ dependencies = [ "cw2", "glob", "phf", + "schemars", "serde", "sha2 0.10.8", "strum", diff --git a/docs-test-gen/Cargo.toml b/docs-test-gen/Cargo.toml index 8f77c380..cfdb23fe 100644 --- a/docs-test-gen/Cargo.toml +++ b/docs-test-gen/Cargo.toml @@ -20,3 +20,4 @@ cosmos-sdk-proto = { version = "0.21.1", default-features = false } cw-storage-plus = "*" serde = "*" cw-storey = "*" +schemars = "0.8.21" # Used in entrypoint example diff --git a/src/pages/core/entrypoints.mdx b/src/pages/core/entrypoints.mdx index e4e4d460..d8a36fc4 100644 --- a/src/pages/core/entrypoints.mdx +++ b/src/pages/core/entrypoints.mdx @@ -14,6 +14,16 @@ these entrypoints, each one different from the last. In this section we want to give you a quick overview over all the entrypoints and when they are called. + + In our examples, we will always refer to `StdResult` as the error type. + This is just for convenience since every type that implements the `ToString` type can be used as an error type! + +Meaning, as long as it implements `ToString`, nothing is stopping you from +defining `Result`. This can reduce your code complexity, +especially if you want to use the try operator. + + + ## Defining entrypoints While you will learn all about entrypoints in the next sections, we want to give @@ -27,16 +37,16 @@ VM: "Hey! This is an entrypoint, please use it when needed!" When defining an entrypoint, it is important to use the correct types for the parameters and return type. Incorrect types will cause errors when trying to call the contract. -
In the following sections we will take a look at all possible entrypoints, - including the correct function signature. +
In the following sections we will take a look at all possible + entrypoints, including the correct function signature. Even though the sections will show you to use `#[entry_point]`, it is recommended to define your endpoints as `#[cfg_attr(not(feature = "library"), entry_point)]`. -
The reason behind that is that it allows you to reuse your contract as a - library. +
The reason behind that is that it allows you to reuse your contract as + a library. ```rust template="core" @@ -51,3 +61,85 @@ pub fn instantiate( Ok(Response::default()) } ``` + +## Entrypoint parameters + +Entrypoints have a few parameters (as you can see above), some of them are +predefined by `cosmwasm-std`, others are defined by the user themselves. + +Here we go over the different predefined types the standard library provides, +and how you can define your own types. + +### Predefined types + +#### `Deps`/`DepsMut` + +These structs provide you access to the: + +- Storage +- VM API +- Querier + +The big difference is that `DepsMut` gives you _mutable_ access to the storage. +This design is deliberate since you, for example, can't mutate the state in the +`query` endpoint. Instead of relying on runtime errors, this is made +_irrepresentable_ through Rust's type system. + +#### `Env` + +This struct provides you with some information of the current state of the +environment your contract is executed in. + +The information provided is, for example, the block height, chain ID, +transaction info, etc. Basically anything you'd ever want to know about the +current state of the execution environment! + +#### `MessageInfo` + +This struct isn't provided to every endpoint, only to a select few. + +It provides you with some information that might be crucial to you, depending on +the operation you want to perform. It contains the sender of the message you +just received, and the funds that were transferred along with it to your +contract. + +### Defining your own messages + +In our examples, you might have seen messages such as `InstantiateMsg`. These +messages are actually _user-defined_, meaning each contract developer has to +define them themselves. + +To make this easier our `cosmwasm-schema` crate provides the `cw_serde` +attribute macro, to define an instantiate message, you simply write this: + +```rust filename="instantiate.rs" template="core" +#[cw_serde] +struct CustomInstantiateMsg { + initial_admins: Vec, +} +``` + + + This macro actually just expands into a bunch of `derive` attributes. + We provide this simply for your convenience, otherwise you'd have to keep track of all of these derives yourself. + +
+ Without `#[cw_serde]` + +```rust filename="instantiate.rs" template="core" +#[derive( + serde::Serialize, + serde::Deserialize, + Clone, + Debug, + PartialEq, + schemars::JsonSchema +)] +#[serde(deny_unknown_fields)] +struct CustomInstantiateMsg { + initial_admins: Vec, +} +``` + +
+ From 3541dbe0629362347b4a4921bc35d2ebf7c70894 Mon Sep 17 00:00:00 2001 From: aumetra Date: Wed, 26 Jun 2024 17:31:54 +0200 Subject: [PATCH 2/3] Document QueryResponses macro --- src/pages/core/entrypoints/query.mdx | 38 +++++++++++++++++++++++++--- 1 file changed, 35 insertions(+), 3 deletions(-) diff --git a/src/pages/core/entrypoints/query.mdx b/src/pages/core/entrypoints/query.mdx index d84d7924..1df2639e 100644 --- a/src/pages/core/entrypoints/query.mdx +++ b/src/pages/core/entrypoints/query.mdx @@ -6,12 +6,44 @@ import { Callout } from "nextra/components"; # Query -In the previous section we talked about the [`execute` endpoint]. The `query` -endpoint is actually pretty similar to its sibling `execute`, but with one key -difference: The storage is only accessible immutably. +In the previous section we talked about the [`execute` endpoint]. The `query` endpoint +is actually pretty similar to its sibling `execute`, but with one key difference: +The storage is only accessible immutably. This means you can only _read_ from the storage but not _write_ to it. +## Properly defining a message + +When defining a message for queries, you always return some value. To properly +document these return values, you'll want to define them in your schema. + +This is where the `cosmwasm_schema::QueryResponses` derive macro comes in. + +```rust filename="contract.rs" +#[cw_serde] +struct GreetResponse { + message: String, +} + +#[cw_serde] +struct GoodbyeResponse { + message: String, +} + +#[cw_serde] +#[derive(QueryResponses)] +enum CustomQueryMsg { + #[returns(GreetResponse)] + Greet, + #[returns(GoodbyeResponse)] + Goodbye, +} +``` + +The macro then defines the required code to document the responses in your code +properly so you can easily generate, for example, TypeScript types for your +contract clients. + ## Definition ```rust filename="contract.rs" template="core" From e5f940b8a7ffa4bb0919770a0bed1b3dd166f498 Mon Sep 17 00:00:00 2001 From: Aumetra Weisman Date: Thu, 27 Jun 2024 18:53:12 +0200 Subject: [PATCH 3/3] Update wording --- src/pages/core/entrypoints.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/pages/core/entrypoints.mdx b/src/pages/core/entrypoints.mdx index d8a36fc4..9a5c9ec4 100644 --- a/src/pages/core/entrypoints.mdx +++ b/src/pages/core/entrypoints.mdx @@ -15,7 +15,7 @@ In this section we want to give you a quick overview over all the entrypoints and when they are called. - In our examples, we will always refer to `StdResult` as the error type. + In our examples, we will always refer to `StdResult` as the return type (and therefore `StdError` as the error type). This is just for convenience since every type that implements the `ToString` type can be used as an error type! Meaning, as long as it implements `ToString`, nothing is stopping you from @@ -37,16 +37,16 @@ VM: "Hey! This is an entrypoint, please use it when needed!" When defining an entrypoint, it is important to use the correct types for the parameters and return type. Incorrect types will cause errors when trying to call the contract. -
In the following sections we will take a look at all possible - entrypoints, including the correct function signature. +
In the following sections we will take a look at all possible entrypoints, + including the correct function signature. Even though the sections will show you to use `#[entry_point]`, it is recommended to define your endpoints as `#[cfg_attr(not(feature = "library"), entry_point)]`. -
The reason behind that is that it allows you to reuse your contract as - a library. +
The reason behind that is that it allows you to reuse your contract as a + library. ```rust template="core"