Skip to content

Commit

Permalink
Sylvia tutorial entry points
Browse files Browse the repository at this point in the history
  • Loading branch information
jawoznia committed Jan 7, 2025
1 parent 7ff5a96 commit 5d2c647
Show file tree
Hide file tree
Showing 2 changed files with 42 additions and 34 deletions.
74 changes: 41 additions & 33 deletions src/pages/tutorial/sylvia-contract/entry-points.mdx
Original file line number Diff line number Diff line change
@@ -1,33 +1,38 @@
---
tags: ["tutorial, sylvia"]
---

import { Callout } from "nextra/components";

# Entry points

Typical Rust application starts with the `fn main()` function called by the operating system. Smart
contracts are not significantly different. When the message is sent to the contract, a function
called "entry point" is executed. Unlike native applications, which have only a single `main` entry
point, smart contracts have a couple of them, each corresponding to different message type:
`instantiate`, `execute`, `query`, `sudo`, `migrate` and more.
called [entry point](../../core/entrypoints) is executed. Unlike native applications, which have
only a single `main` entry point, smart contracts have a couple of them, each corresponding to
different message type.

To start, we will go with three basic entry points:

- **`instantiate`** is called once per smart contract lifetime; you can think about it as a
constructor or initializer of a contract.
- **`execute`** for handling messages which can modify contract state; they are used to perform some
actual actions.
- **`query`** for handling messages requesting some information from a contract; unlike
**`execute`**, they can never alter any contract state, and are used in a similar manner to
database queries.
- [instantiate](../../core/entrypoints/instantiate) is called once per smart contract lifetime; you
can think about it as a constructor or initializer of a contract.
- [execute](../../core/entrypoints/execute) for handling messages which can modify contract state;
they are used to perform some actual actions.
- [query](../../core/entrypoints/query) for handling messages requesting some information from a
contract; unlike [execute](../../core/entrypoints/execute), they can never alter any contract
state, and are used in a similar manner to database queries.

## Generate entry points

^Sylvia provides an attribute macro named
[`entry_points`](https://docs.rs/sylvia/latest/sylvia/attr.entry_points.html). In most cases, your
entry point will just dispatch received messages to the handler, so it's not necessary to manually
create them, and we can rely on a macro to do that for us.
Sylvia provides an attribute macro named [`entry_points`](../../sylvia/macros/entry-points). In most
cases, your entry point will just dispatch received messages to the handler, so it's not necessary
to manually create them, and we can rely on a macro to do that for us.

Let's add the **`entry_points`** attribute macro to our contract:
Let's add the [`entry_points`](../../sylvia/macros/entry-points) attribute macro to our contract:

```rust,noplayground
use cosmwasm_std::{Response, StdResult};
use sylvia::types::InstantiateCtx;
```rust {3, 7} copy filename="src/contract.rs" template="sylvia/empty"
use sylvia::ctx::InstantiateCtx;
use sylvia::cw_std::{Response, StdResult};
use sylvia::{contract, entry_points};

pub struct CounterContract;
Expand All @@ -46,28 +51,31 @@ impl CounterContract {
}
```

Note that **`#[entry_points]`** is added above the **`#[contract]`**. It is because
**`#[contract]`** removes attributes like **`#[sv::msg(...)]`** on which both these macros rely.
<Callout>
Note that [`entry_points`](../../sylvia/macros/entry-points) is added above the
[`contract`](../../sylvia/macros/contract). It is because
[`contract`](../../sylvia/macros/contract) removes attributes like
[`sv::msg(...)`](../../sylvia/macros/attributes/msg) on which both these macros rely. Always
remember to place [`entry_points`](../../sylvia/macros/entry-points) first.
</Callout>

Always remember to place **`#[entry_points]`** first.

^Sylvia generates entry points with
[`#[entry_point]`](https://docs.rs/cosmwasm-std/1.3.1/cosmwasm_std/attr.entry_point.html) attribute
Sylvia generates entry points with the [`entry_points`](../../sylvia/macros/entry-points) attribute
macro. Its purpose is to wrap the whole entry point to the form the Wasm runtime understands. The
proper Wasm entry points can use only basic types supported natively by Wasm specification, and Rust
structures and enums are not in this set. Working with such entry points would be overcomplicated,
so CosmWasm creators delivered the `entry_point` macro. It creates the raw Wasm entry point, calling
the decorated function internally and doing all the magic required to build our high-level Rust
arguments from arguments passed by Wasm runtime.
so CosmWasm creators delivered the
[`entry_point`](https://docs.rs/cosmwasm-std/latest/cosmwasm_std/attr.entry_point.html) macro. It
creates the raw Wasm entry point, calling the decorated function internally and doing all the magic
required to build our high-level Rust arguments from arguments passed by Wasm runtime.

Now, when our contract has a proper entry point, let's build it and check if it's correctly defined:

```shell
contract $ cargo build --release --target wasm32-unknown-unknown --lib
Finished release [optimized] target(s) in 0.03s
```shell copy filename="TERMINAL"
cargo build --release --target wasm32-unknown-unknown --lib
```

contract $ cosmwasm-check target/wasm32-unknown-unknown/release/contract.wasm
Available capabilities: {"stargate", "cosmwasm_1_3", "cosmwasm_1_1", "cosmwasm_1_2", "staking", "iterator"}
```shell filename="TERMINAL"
Available capabilities: {"cosmwasm_1_3", "cosmwasm_2_0", "cosmwasm_1_2", "stargate", "iterator", "cosmwasm_1_1", "cosmwasm_1_4", "staking", "cosmwasm_2_1"}

target/wasm32-unknown-unknown/release/contract.wasm: pass

Expand All @@ -76,5 +84,5 @@ All contracts (1) passed checks!

## Next step

Well done! We have now a proper `CosmWasm` contract. Let's add some state to it, so it will actually
Well done! We have now a proper CosmWasm contract. Let's add some state to it, so it will actually
be able to do something.
2 changes: 1 addition & 1 deletion src/pages/tutorial/sylvia-contract/first-messages.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -80,7 +80,7 @@ cosmwasm-check target/wasm32-unknown-unknown/release/contract.wasm
The output should look like this:

```shell filename="TERMINAL"
Available capabilities: {"stargate", "staking", "cosmwasm_1_3", "cosmwasm_2_0", "cosmwasm_1_1", "cosmwasm_1_2", "cosmwasm_1_4", "iterator"}
Available capabilities: {"cosmwasm_1_3", "cosmwasm_2_0", "cosmwasm_1_2", "stargate", "iterator", "cosmwasm_1_1", "cosmwasm_1_4", "staking", "cosmwasm_2_1"}

target/wasm32-unknown-unknown/release/contract.wasm: pass

Expand Down

0 comments on commit 5d2c647

Please sign in to comment.