Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

correcting the info on messages/submessages ordering in 1.contract-semantics.md #442

Merged
merged 1 commit into from
Jan 18, 2024
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -122,6 +122,8 @@ This may be hard to understand at first, and you may wonder why you cannot just

As of CosmWasm 0.14 (April 2021), they added yet another way to dispatch calls from the contract, due to the common request for the ability to obtain the result from one of the messages you dispatched. For example, it is now possible to create a new contract with **WasmMsg::Instantiate**, and then store the address of the newly created contract in the caller with submessages. It also addresses a similar use case of capturing error results, so if you execute a message from, for example, a cron contract, it can store the error message and mark the message as run, rather than aborting the whole transaction. It also allows for limiting the gas usage of the submessage (this is not intended to be used in most cases, but is needed for, for example, the cron job to protect it from an infinite loop in the submessage, which could burn all gas and abort the transaction).

Submessage is a generalization of the message concept: indeed, a message is simply a submessage that never handles any response.

This makes use of **CosmosMsg** as mentioned above, but it wraps it inside a **SubMsg** envelope:

```rust
Expand All @@ -142,6 +144,8 @@ pub enum ReplyOn {
Error,
/// Only callback if SubMsg was successful, no callback on error case
Success,
/// Never make as callback - equivalent to a message
Never
}
```

Expand Down Expand Up @@ -177,7 +181,7 @@ The one critical difference with reply is that we do not drop data. If reply ret

#### Order and rollback

Submessages (and their replies) are all executed before any messages. They also follow the depth-first rules, as with messages. Here is a simple example: **Contract A** returns submessages **S1** and **S2**, and message **M1**. Submessage **S1** returns message **N1**. The order will be: **S1, N1, reply(S1), S2, reply(S2), M1**.
Submessages follow the same depth first order rules as messages, with their replies considered as an immediate additional message call. Here is a simple example: **Contract A** returns submessages **S1** and **S2**, and message **M1**. Submessage **S1** returns message **N1**. The order will be: **S1, N1, reply(S1), S2, reply(S2), M1**.

Please keep in mind that submessage execution and reply can happen within the context of another submessage. For example, **contract-A--submessage --> contract-B--submessage --> contract-C**. Then, **contract-B** can revert the state for **contract-C** and itself by returning Err in the submessage reply, but not revert **contract-A** or the entire transaction. It just ends up returning Err to **contract-A's** reply function.

Expand Down