diff --git a/SEMANTICS.md b/SEMANTICS.md index dc6afcb66a..f4862e81af 100644 --- a/SEMANTICS.md +++ b/SEMANTICS.md @@ -215,6 +215,9 @@ intended to be used for most cases, but is needed for eg. the cron job to protect it from an infinite loop in the submessage burning all gas and aborting 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 above, but it wraps it inside a `SubMsg` envelope: @@ -236,6 +239,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, } ``` @@ -324,10 +329,10 @@ JSON string instead of `null` and handled as any other `Some` value. #### 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 +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** +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 @@ -338,8 +343,8 @@ It just ends up returning `Err` to contract-A's `reply` function. Note that errors are not handled with `ReplyOn::Success`, meaning, in such a case, an error will be treated just like a normal `message` returning an error. -This diagram may help explain. Imagine a contract returned two submesssage - (a) -with `ReplyOn::Success` and (b) with `ReplyOn::Error`: +This diagram may help explain. Imagine a contract returned two submesssages - +(a) with `ReplyOn::Success` and (b) with `ReplyOn::Error`: | processing a) | processing b) | reply called | may overwrite result from reply | note | | ------------- | ------------- | ------------ | ------------------------------- | ------------------------------------------------- |