From ccab08d25880a06298a92a09d6e2b036688fa005 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20Wo=C5=BAniak?= Date: Thu, 1 Aug 2024 13:32:34 +0200 Subject: [PATCH 1/5] Sylvia: Remove custom from entry_points --- src/pages/sylvia/macros/entry-points.mdx | 13 ------------- 1 file changed, 13 deletions(-) diff --git a/src/pages/sylvia/macros/entry-points.mdx b/src/pages/sylvia/macros/entry-points.mdx index cbb009ff..b30b1c7d 100644 --- a/src/pages/sylvia/macros/entry-points.mdx +++ b/src/pages/sylvia/macros/entry-points.mdx @@ -127,16 +127,3 @@ with concrete types passed in brackets. Remember to pass the types in the order reflecting the order of generics defined on the contract. - -If the contract uses generic custom types we have to do some more work. - -```rust -#[cfg_attr(not(feature = "library"), entry_points(generics, custom(msg=SvCustomMsg, query=SvCustomQuery)))] -``` - -After coma we have to pass another parameter `custom`, and in the paranthesis specify which types -should be used in place of custom message and custom query. The syntax reflects one used in the -[`custom`](../attributes/custom). - -This is required as, for at least now, Sylvia is unable to determine which concrete types are -supposed to be used in place of generic custom types. From fbe54ff52b23b206a38c873ef5860599c8ed4e10 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20Wo=C5=BAniak?= Date: Thu, 1 Aug 2024 15:25:00 +0200 Subject: [PATCH 2/5] Sylvia: Describe forwarding attributes to message variants --- src/pages/sylvia/attributes/_meta.json | 3 +- src/pages/sylvia/attributes/attr.mdx | 57 ++++++++++++++++++++++++++ 2 files changed, 59 insertions(+), 1 deletion(-) create mode 100644 src/pages/sylvia/attributes/attr.mdx diff --git a/src/pages/sylvia/attributes/_meta.json b/src/pages/sylvia/attributes/_meta.json index 0b18a388..73752f02 100644 --- a/src/pages/sylvia/attributes/_meta.json +++ b/src/pages/sylvia/attributes/_meta.json @@ -3,5 +3,6 @@ "error": "Error", "message": "Message", "msg": "Msg", - "override-entry-point": "Override_entry_point" + "override-entry-point": "Override_entry_point", + "attr": "Attribute forwarding" } diff --git a/src/pages/sylvia/attributes/attr.mdx b/src/pages/sylvia/attributes/attr.mdx new file mode 100644 index 00000000..8729409e --- /dev/null +++ b/src/pages/sylvia/attributes/attr.mdx @@ -0,0 +1,57 @@ +--- +tags: ["sylvia", "attributes"] +--- + +import { Callout } from "nextra/components"; + +# `sv::attr` attribute + +Use `sv::attr` to forward an external attribute to the generated message variant. + +## Macros + +List of macros supporting the `sv::attr` attribute: + +- [`contract`](../macros/contract) +- [`interface`](../macros/interface) + +## Usage + +Use the `sv::attr` above any of the methods marked with +[`#[sv::msg(exec|sudo|query)]`](../attributes/msg) attribute. + +```rust {19} +use sylvia::contract; +use sylvia::cw_std::{Response, StdResult}; +use sylvia::types::{ExecCtx, InstantiateCtx}; + +pub struct ReplyContract; + +#[contract] +impl ReplyContract { + pub fn new() -> Self { + Self + } + + #[sv::msg(instantiate)] + fn instantiate(&self, ctx: InstantiateCtx) -> StdResult { + Ok(Response::new()) + } + + #[sv::msg(exec)] + #[sv::attr(serde(rename = "execute"))] + fn exec(&self, ctx: ExecCtx) -> StdResult { + Ok(Response::new()) + } +} +``` + +The [`contract`](../macros/contract) and [`interface`](../macros/interface) macros will decorate the +message variant with the attribute provided in `sv::attr`. + +```rust {2} +pub enum ExecMsg { + #[serde(rename = "execute")] + Exec {}, +} +``` From 36968506e20253391e083a578681167f8a750768 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20Wo=C5=BAniak?= Date: Thu, 1 Aug 2024 15:45:46 +0200 Subject: [PATCH 3/5] Sylvia: Describe forwarding attributes to messages --- src/pages/sylvia/attributes/_meta.json | 3 +- src/pages/sylvia/attributes/attr.mdx | 4 +- src/pages/sylvia/attributes/msg_attr.mdx | 63 ++++++++++++++++++++++++ 3 files changed, 67 insertions(+), 3 deletions(-) create mode 100644 src/pages/sylvia/attributes/msg_attr.mdx diff --git a/src/pages/sylvia/attributes/_meta.json b/src/pages/sylvia/attributes/_meta.json index 73752f02..54a2b66d 100644 --- a/src/pages/sylvia/attributes/_meta.json +++ b/src/pages/sylvia/attributes/_meta.json @@ -4,5 +4,6 @@ "message": "Message", "msg": "Msg", "override-entry-point": "Override_entry_point", - "attr": "Attribute forwarding" + "attr": "Attr", + "msg_attr": "MsgAttr" } diff --git a/src/pages/sylvia/attributes/attr.mdx b/src/pages/sylvia/attributes/attr.mdx index 8729409e..b3ebbb2b 100644 --- a/src/pages/sylvia/attributes/attr.mdx +++ b/src/pages/sylvia/attributes/attr.mdx @@ -25,10 +25,10 @@ use sylvia::contract; use sylvia::cw_std::{Response, StdResult}; use sylvia::types::{ExecCtx, InstantiateCtx}; -pub struct ReplyContract; +pub struct MyContract; #[contract] -impl ReplyContract { +impl Contract { pub fn new() -> Self { Self } diff --git a/src/pages/sylvia/attributes/msg_attr.mdx b/src/pages/sylvia/attributes/msg_attr.mdx new file mode 100644 index 00000000..ae41aa25 --- /dev/null +++ b/src/pages/sylvia/attributes/msg_attr.mdx @@ -0,0 +1,63 @@ +--- +tags: ["sylvia", "attributes"] +--- + +import { Callout } from "nextra/components"; + +# `sv::msg_attr` attribute + +Use `sv::msg_attr` to forward an external attribute to the generated message. + +## Macros + +List of macros supporting the `sv::msg_attr` attribute: + +- [`contract`](../macros/contract) +- [`interface`](../macros/interface) + +## Usage + +Use the `sv::msg_attr` above any of the methods marked with [`#[sv::msg(..)]`](../attributes/msg) +attribute. + +```rust {19} +use sylvia::contract; +use sylvia::cw_std::{Response, StdResult}; +use sylvia::types::InstantiateCtx; + +pub struct MyContract; + +#[contract] +#[sv::msg_attr(instantiate, derive(MyDeriveMacro))] +#[sv::msg_attr(instantiate, MyAttributeMacro(param))] +#[sv::msg_attr(instantiate, AttributeForMacro(param1, param2))] +impl MyContract { + pub fn new() -> Self { + Self + } + + #[sv::msg(instantiate)] + fn instantiate(&self, ctx: InstantiateCtx) -> StdResult { + Ok(Response::new()) + } +} +``` + +The [`contract`](../macros/contract) and [`interface`](../macros/interface) macros will decorate the +message with the attributes/macros provided in `sv::msg_attr`. + +```rust {8, 10-11} +#[derive( + sylvia::serde::Serialize, + sylvia::serde::Deserialize, + Clone, + Debug, + PartialEq, + sylvia::schemars::JsonSchema, + MyDeriveMacro, +)] +#[MyAttributeMacro(param)] +#[AttributeForMacro(param1, param2)] +#[serde(rename_all = "snake_case")] +pub struct InstantiateMsg {} +``` From 94a08a7447f6d3e2e46ec921f09231ced680c3d5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20Wo=C5=BAniak?= Date: Thu, 1 Aug 2024 17:51:54 +0200 Subject: [PATCH 4/5] Sylvia: Describe forwarding attributes to message fields --- .../sylvia/basics/contract-structure.mdx | 27 +++++++------- src/pages/sylvia/macros/contract.mdx | 36 +++++++++++++++++-- src/pages/sylvia/macros/interface.mdx | 25 +++++++++++++ 3 files changed, 72 insertions(+), 16 deletions(-) diff --git a/src/pages/sylvia/basics/contract-structure.mdx b/src/pages/sylvia/basics/contract-structure.mdx index 7149b2fc..9cafea9b 100644 --- a/src/pages/sylvia/basics/contract-structure.mdx +++ b/src/pages/sylvia/basics/contract-structure.mdx @@ -65,17 +65,18 @@ In the first two lines, we see the usage of two macros: point collision. - [`contract`](../macros/contract) - Parses every method inside the `impl` block marked with the - `[sv::msg(...)]` attribute and create proper messages and utilities like helpers for - [`MultiTest`](../../cw-multi-test). + [`[sv::msg(...)]`](../attributes/msg) attribute and create proper messages and utilities like + helpers for [`MultiTest`](../../cw-multi-test). -This simple example also has the `sv::msg(...)` attributes. Sylvia macros distinguish the if message -should be generated from the marked method and of what type. +This simple example also has the [`sv::msg(...)`](../attributes/msg) attributes. Sylvia macros +distinguish the if message should be generated from the marked method and of what type. CosmWasm contract requires the `instantiate` message, and it is mandatory to specify it for the -`contract` macro. We have to provide it with the proper context type: +[`contract`](../macros/contract) macro. We have to provide it with the proper context type: [`InstantiateCtx`](https://docs.rs/sylvia/latest/sylvia/types/struct.InstantiateCtx.html). Another -mandatory method is the `new`, as contract fields are out of scope for the `contract` macro, and -otherwise we wouldn't be able to create the contract object in message dispatching. +mandatory method is the `new`, as contract fields are out of scope for the +[`contract`](../macros/contract) macro, and otherwise we wouldn't be able to create the contract +object in message dispatching. Context gives us access to the blockchain state, information about our contract, and the sender of the message. We return the @@ -85,16 +86,16 @@ standard CosmWasm error [`Response`](https://docs.rs/cosmwasm-std/latest/cosmwasm_std/struct.Response.html). The template contract also contains a query and an exec messages. Each type of message in CosmWasm -supports different contexts. F.e. the -[`QueryCtx`](https://docs.rs/sylvia/latest/sylvia/types/struct.QueryCtx.html) exposes to the user an +supports different contexts. F.e. the [`QueryCtx`](../types/context) exposes to the user an immutable [`Deps`](https://docs.rs/cosmwasm-std/latest/cosmwasm_std/struct.Deps.html) as by design, -queries should never mutate the state. This is not the case for the -[`ExecCtx`](https://docs.rs/sylvia/latest/sylvia/types/struct.ExecCtx.html) and `InstantiateCtx` -which exposes the [`DepsMut`](https://docs.rs/cosmwasm-std/latest/cosmwasm_std/struct.DepsMut.html). +queries should never mutate the state. This is not the case for the [`ExecCtx`](../types/context) +and `InstantiateCtx` which exposes the +[`DepsMut`](https://docs.rs/cosmwasm-std/latest/cosmwasm_std/struct.DepsMut.html). Fell free expanding the macro now and seeing what Sylvia generates. It might be overwhelming, as there will be a lot of things generated that seem not relevant to our code, so for the bare minimum, -check the `InstantiateMsg` and its `impl` block. +check the [`InstantiateMsg`](../macros/generated-types/message-types#contract-messages) and its +`impl` block. Sylvia doesn't generate anything magical, but regular CosmWasm contract types customized based on the provided methods and attributes. This means that the Sylvia contract is fully interoperational diff --git a/src/pages/sylvia/macros/contract.mdx b/src/pages/sylvia/macros/contract.mdx index 9bff9ddf..32f7bc2a 100644 --- a/src/pages/sylvia/macros/contract.mdx +++ b/src/pages/sylvia/macros/contract.mdx @@ -6,13 +6,18 @@ import { Callout } from "nextra/components"; # Contract -Use the `contract` macro to generate contract messages +Use the [`contract`](https://docs.rs/sylvia/latest/sylvia/attr.contract.html) macro to generate +contract messages -Use `contract` macro only on top of struct impl blocks + + Use [`contract`](https://docs.rs/sylvia/latest/sylvia/attr.contract.html) macro only on top of + struct impl blocks + ## Attributes -List of attributes supported by `contract` macro: +List of attributes supported by +[`contract`](https://docs.rs/sylvia/latest/sylvia/attr.contract.html) macro: - [`custom`](../attributes/custom) - [`error`](../attributes/error) @@ -142,6 +147,31 @@ This is a standard way to create generic structs in Rust. Two important things t fulfill their trait bounds. In most cases it's enough to add the `sylvia::types::CustomMsg + \'static` bounds. +## Forwarding attributes to fields + +The [`contract`](https://docs.rs/sylvia/latest/sylvia/attr.contract.html) macro can forward +attributes to the fields of the messages. + +```rust {5} +#[sv::msg(instantiate)] +fn instantiate( + &self, + ctx: InstantiateCtx, + #[serde(default)] value: String, +) -> StdResult { + Ok(Response::new()) +} +``` + +The output of the above code will be: + +```rust {2} +pub struct InstantiateMsg { + #[serde(default)] + pub value: String, +} +``` + ## Good practices ### Prefer generic custom types diff --git a/src/pages/sylvia/macros/interface.mdx b/src/pages/sylvia/macros/interface.mdx index c5546d71..682f4b3a 100644 --- a/src/pages/sylvia/macros/interface.mdx +++ b/src/pages/sylvia/macros/interface.mdx @@ -103,3 +103,28 @@ pub trait Interface { fn interface_exec(&self, ctx: ExecCtx, param: Self::MyType) -> StdResult; } ``` + +## Forwarding attributes to fields + +The [`interface`](https://docs.rs/sylvia/latest/sylvia/attr.interface.html) macro can forward +attributes to the fields of the messages. + +```rust {5} +#[sv::msg(exec)] +fn exec( + &self, + ctx: ExecCtx, + #[serde(default)] value: String, +) -> Result; +``` + +The output of the above code will be: + +```rust {2} +pub enum MyInterfaceExecMsg { + Exec { + #[serde(default)] + value: String, + }, +} +``` From 5c828af55dd2c1a280adce6f9ab5fd945441148a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20Wo=C5=BAniak?= Date: Tue, 6 Aug 2024 13:00:53 +0200 Subject: [PATCH 5/5] Fix highlighting --- src/pages/sylvia/macros/interface.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/sylvia/macros/interface.mdx b/src/pages/sylvia/macros/interface.mdx index 682f4b3a..7c5b740f 100644 --- a/src/pages/sylvia/macros/interface.mdx +++ b/src/pages/sylvia/macros/interface.mdx @@ -120,7 +120,7 @@ fn exec( The output of the above code will be: -```rust {2} +```rust {3} pub enum MyInterfaceExecMsg { Exec { #[serde(default)]