Move wasmvm/spec and cosmwasm/SEMANTICS.md here
#167
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
The latest updates on your projects. Learn more about Vercel for Git ↗︎
|
This was referenced Oct 17, 2024
kulikthebird
force-pushed
the
tkulik/wasmvm_docs_and_cw_semantics
branch
from
ff6c07a to
c329d7b
Compare
kulikthebird
force-pushed
the
tkulik/wasmvm_docs_and_cw_semantics
branch
from
c329d7b to
f36ded1
Compare
kulikthebird
force-pushed
the
tkulik/wasmvm_docs_and_cw_semantics
branch
from
f36ded1 to
01be56a
Compare
|
Most of the |
kulikthebird
force-pushed
the
tkulik/wasmvm_docs_and_cw_semantics
branch
from
01be56a to
81a80e6
Compare
kulikthebird
force-pushed
the
tkulik/wasmvm_docs_and_cw_semantics
branch
from
81a80e6 to
8a8d402
Compare
kulikthebird
force-pushed
the
tkulik/wasmvm_docs_and_cw_semantics
branch
from
8a8d402 to
8d5d90f
Compare
kulikthebird
force-pushed
the
tkulik/wasmvm_docs_and_cw_semantics
branch
from
8d5d90f to
aae2896
Compare
kulikthebird
force-pushed
the
tkulik/wasmvm_docs_and_cw_semantics
branch
from
aae2896 to
ef97851
Compare
kulikthebird
force-pushed
the
tkulik/wasmvm_docs_and_cw_semantics
branch
from
ef97851 to
9802f58
Compare
kulikthebird
force-pushed
the
tkulik/wasmvm_docs_and_cw_semantics
branch
from
9802f58 to
45a6837
Compare
kulikthebird
force-pushed
the
tkulik/wasmvm_docs_and_cw_semantics
branch
from
45a6837 to
61c02d3
Compare
kulikthebird
force-pushed
the
tkulik/wasmvm_docs_and_cw_semantics
branch
from
61c02d3 to
335fab2
Compare
kulikthebird
force-pushed
the
tkulik/wasmvm_docs_and_cw_semantics
branch
from
6df1d8c to
3497f37
Compare
kulikthebird
force-pushed
the
tkulik/wasmvm_docs_and_cw_semantics
branch
from
3497f37 to
4a36b61
Compare
|
There's a PR with tests that checks the order of messages execution, |
kulikthebird
force-pushed
the
tkulik/wasmvm_docs_and_cw_semantics
branch
from
4a36b61 to
f401d10
Compare
kulikthebird
force-pushed
the
tkulik/wasmvm_docs_and_cw_semantics
branch
from
f401d10 to
1a22bdc
Compare
kulikthebird
force-pushed
the
tkulik/wasmvm_docs_and_cw_semantics
branch
from
1a22bdc to
80e0264
Compare
DariuszDepta
approved these changes
Dec 10, 2024
chipshort
reviewed
Dec 16, 2024
There was a problem hiding this comment.
Nice, looks like this contains all the important info of SEMANTICS.md while staying away from rotting inline code blocks.
I would only like to see this more tightly integrated with the rest of the docs (see some of my comments). Potentially, this could even be split up into multiple pages.
I really like the sequence diagram to show how the depth first execution works.
src/pages/core/semtantics.mdx
Outdated
Comment on lines
98
to
104
| With [`DepsMut`](https://docs.rs/cosmwasm-std/latest/cosmwasm_std/struct.DepsMut.html), this can | ||
| read and write to the | ||
| [`Storage`](https://docs.rs/cosmwasm-std/latest/cosmwasm_std/trait.Storage.html), as well as use the | ||
| [`Api`](https://docs.rs/cosmwasm-std/latest/cosmwasm_std/trait.Api.html) to validate addresses, and | ||
| use [`QuerierWrapper`](https://docs.rs/cosmwasm-std/latest/cosmwasm_std/struct.QuerierWrapper.html) | ||
| to query the state of other contracts or native modules. Once it is done, it returns either | ||
| `Ok(Response)` or `Err(ContractError)`. |
There was a problem hiding this comment.
Maybe this should be incorporated into core/entrypoints.mdx and just add a reference to that here?
Like "For information on how to define an entrypoint and how the function signature works, see the [entrypoints documentation]."
src/pages/core/semtantics.mdx
Outdated
Comment on lines
145
to
189
| What are the semantics of a submessage execution? First, we create a sub-transaction context around | ||
| the state, allowing it to read the latest state written by the caller, but write to yet-another | ||
| cache. If `gas_limit` is set, it is sandboxed to how much gas it can use until it aborts with | ||
| `OutOfGasError`. This error is caught and returned to the caller like any other error returned from | ||
| contract execution (unless it burned the entire gas limit of the transaction). | ||
|
|
||
| If it return success, the temporary state is committed (into the caller's cache), and the | ||
| [`Response`](https://docs.rs/cosmwasm-std/latest/cosmwasm_std/struct.Response.html) is processed as | ||
| normal. Once the response is fully processed, this may then be intercepted by the calling contract | ||
| (for `ReplyOn::Always` and `ReplyOn::Success`). On an error, the subcall will revert any partial | ||
| state changes due to this message, but not revert any state changes in the calling contract. The | ||
| error may then be intercepted by the calling contract (for `ReplyOn::Always` and `ReplyOn::Error`). | ||
| In this case, the messages error doesn't abort the whole transaction. | ||
|
|
||
| Note, that error doesn't abort the whole transaction _if and only if_ the `reply` is called - so in | ||
| case of `ReplyOn::Always` and `ReplyOn::Error`. If the submessage is called with `ReplyOn::Success` | ||
| or `ReplyOn::Never`, the error in subsequent call would result in failing whole transaction and not | ||
| commit the changes for it. The rule here is as follows: if for any reason you want your message | ||
| handling to succeed on submessage failure, you always have to reply on failure. | ||
|
|
||
| #### Handling the reply | ||
|
|
||
| Let's introduce a new entry-point: | ||
|
|
||
| ```rust filename="contract.rs" template="core" | ||
| #[cfg_attr(not(feature = "library"), entry_point)] | ||
| pub fn reply(deps: DepsMut, env: Env, reply: Reply) -> StdResult<Response> { | ||
| // [...] | ||
| Ok(Response::new()) | ||
| } | ||
| ``` | ||
|
|
||
| Once the submessage handling is finished, the caller will get a chance to handle the result. It will | ||
| get the original `id` of the subcall and the `Result` of the execution, both success and error. Note | ||
| that it includes all events returned by the submessage, which applies to native sdk modules (like | ||
| Bank) as well as the contracts. If you need more state, you must save some local context to the | ||
| store (under the `id`) in the `execute` entry-point, and load it in `reply`. | ||
|
|
||
| The `reply` call may return `Err` itself, in which case it is treated like the caller errored, and | ||
| aborting the sub-transaction. However, on successful processing, `reply` may return a normal | ||
| [`Response`](https://docs.rs/cosmwasm-std/latest/cosmwasm_std/struct.Response.html), which will be | ||
| processed as normal - events added to the `EventManager`, and all `messages` dispatched as described | ||
| above. When `Err` is returned by a message handler, all changes made by the handler up to the reply | ||
| entry-point that returns the `Ok` response are reverted. More information can be found in the | ||
| following section. |
There was a problem hiding this comment.
This is a really nice write-up, but it overlaps a lot with core/entrypoints/reply.mdx and core/architecture/transactions.mdx. Can we unify that somehow to avoid duplicating the information?
src/pages/core/semtantics.mdx
Outdated
Comment on lines
220
to
222
| **Note1:** The field `data` of the submessages field in the response are not forwarded down the call | ||
| path. It means that for e.g. if `Contract2` will not explicitly handle response from `Contract3` and | ||
| forward any data, then `Contract1` will never learn about results from `Contract3`. |
There was a problem hiding this comment.
I think this would benefit from some context. Maybe link to the data field code docs or explain what the data field is for (or do we have that already here in the docs somewhere? In that case, just link to it)
kulikthebird
force-pushed
the
tkulik/wasmvm_docs_and_cw_semantics
branch
from
80e0264 to
9704e4d
Compare
kulikthebird
force-pushed
the
tkulik/wasmvm_docs_and_cw_semantics
branch
from
6d688db to
ebf3052
Compare
kulikthebird
force-pushed
the
tkulik/wasmvm_docs_and_cw_semantics
branch
from
ebf3052 to
4822fea
Compare
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Any relevant information from
wasmvm/specshould be added to the main docs by this PR. The information from the filecosmwasm/SEMANTICS.mdshould be updated and placed here as well. PRs related:specto cosmwasm documentation wasmvm#566 - spec removed from wasmvmMerging this PR solves this issue (and every sub-issue): CosmWasm/cosmwasm#1963