I was recently reading the code for Substrate wasmtime, but I ran into some problems. I don't really understand the difference between runtime and sandbox.

For example, in the runtime.rs file, we can call the call() method of WasmtimeInstance to execute the functions in the wasm instance. Also, in the host.rs file, is the invoke() function implemented for HostContext also executing functions in the wasm instance?

What is the difference between the runtime instance and the sandbox instance?

1 Answer 1


Commonly, "Runtime" refers to something that performs or aids execution. However, historically, what we call a "Runtime" differs from how the word is commonly used. "Runtime" in the context of Substrate is the wasm image that is being executed to instruct how the Substrate client should behave: how to execute block or how to validate a transaction.

Executor is what we picked to refer to the machinery that executes the wasm "Runtime". Substrate has two executors on board: wasmi and wasmtime. Alternatively, you can also see it being referred as "execution engine".

So that is, when Substrate imports a block it executes it by calling into a "Runtime API" called execute_block, by asking either wasmtime or wasmi to create a "Runtime" instance and execute the aforementioned entrypoint.

With that sorted, we can now move on to "sandbox". Substrate supports execution of smart-contracts that are represented by Wasm code. Naive approach to execute Wasm smart-contracts inside Wasm "Runtime" is for example compile wasm interpreter in and use that. A more sophisticated approach is to allow the Wasm "Runtime" to create wasm instances. That feature in Substrate is referred as "Sandbox". We are thinking of changing of how we refer to that feature to Wasm Virtualization.

The logic of the code is a bit convoluted. To understand what happens there we need to learn one more term.

In general, Wasm is a limited and abstract environment. Usually, the Wasm environment supposed to have a certain set of functions that interact with the external environment. Those are called host functions. They are provided by the embedder of the Wasm implementation. In our case we can say that "Runtime" communicates with the Substrate by calling the host functions.

The Sandbox feature is represented by a set of host functions. When a "Runtime" wants to create a sandbox instance it will ask Substrate by calling a specific host function to do that.

Note that since executed Wasm code usually requires a set of host functions to do something useful, the "Runtime" needs to specify those host functions. To be useful and contextualized those host functions are provided by the "Runtime".

Now, let's examine the following example: a "Runtime" executes a transaction that creates a smart-contract through Sandbox which then stores something in storage.

In this case, the "Runtime" will create a sandbox instance by passing in the code of the instantiated Wasm module and the host functions available to the said module. In this case the provided host function is, say, ext_set_storage. Then the "Runtime" passes the control to the smart-contract sandbox instance. It executes code and eventually calls the ext_set_storage function. Then the ext_set_storage gets control within the Runtime and sets the storage.

Now due to the technical limitations, the sandboxed instance cannot directly call the "Runtime". But we smooth it out by providing some trampolines that will convert calls to the sandboxed host to the Runtime. This is exactly the code you stumbled upon.

  • Thank you so much for your answer, it really helped me a lot! Can I understand it this way, "Sandbox" and "Runtime" belong to the same level in code implementation, and "sandboxing execution engine" (wasmi or wasmer) and "runtime execution engine" (wasmi or wasmtime) can be different. Interfaces such as instance_new() or invoke() are provided to the runtime in the form of host functions. For example, in the runtime instance we can call the imported function instance_new() to create a sandbox instance in the host.
    – Emison Lu
    Commented Apr 7, 2022 at 6:32
  • Yeah, I think you can say that @EmisonLu
    – pepyakin
    Commented Apr 7, 2022 at 11:05

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.