diff --git a/content/2.developers/4.cosmwasm-documentation/4.smart-contracts/1.contract-semantics.md b/content/2.developers/4.cosmwasm-documentation/4.smart-contracts/1.contract-semantics.md index ff82e0b3..4988c7c0 100644 --- a/content/2.developers/4.cosmwasm-documentation/4.smart-contracts/1.contract-semantics.md +++ b/content/2.developers/4.cosmwasm-documentation/4.smart-contracts/1.contract-semantics.md @@ -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 @@ -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 } ``` @@ -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.