/wasmi

WebAssembly (Wasm) interpreter.

Primary LanguageRustApache License 2.0Apache-2.0

Continuous Integration Test Coverage Documentation Crates.io
ci codecov docs crates

wasmi- WebAssembly (Wasm) Interpreter

wasmi is an efficient WebAssembly interpreter with low-overhead and support for embedded environment such as WebAssembly itself.

At Parity we are using wasmi in Substrate as the execution engine for our WebAssembly based smart contracts. Furthermore we run wasmi within the Substrate runtime which is a WebAssembly environment itself and driven via Wasmtime at the time of this writing. As such wasmi's implementation requires a high degree of correctness and Wasm specification conformance.

Since wasmi is relatively lightweight compared to other Wasm virtual machines such as Wasmtime it is also a decent option for initial prototyping.

Distinct Features

The following list states some of the distinct features of wasmi.

  • Focus on simple, correct and deterministic WebAssembly execution.
  • Can itself run inside of WebAssembly.
  • Low-overhead and cross-platform WebAssembly runtime.
  • Loosely mirrors the Wasmtime API.
  • Resumable function calls.
  • Built-in support for fuel metering.
  • 100% official WebAssembly spec testsuite compliance.

WebAssembly Proposals

The new wasmi engine supports a variety of WebAssembly proposals and will support even more of them in the future.

WebAssembly Proposal Status Comment
mutable-global ✅ Since version 0.14.0.
saturating-float-to-int ✅ Since version 0.14.0.
sign-extension ✅ Since version 0.14.0.
multi-value ✅ Since version 0.14.0.
bulk-memory ✅ Since version 0.24.0. (#628)
reference-types ✅ Since version 0.24.0. (#635)
simd ❌ Unlikely to be supported.
tail-calls ✅ Since version 0.28.0. (#683)
extended-const ✅ Since version 0.29.0. (#707)
WASI 🟡 Experimental support via the wasmi_wasi crate or the wasmi CLI application.

Usage

As CLI Application

Install the newest wasmi CLI version via:

cargo install wasmi_cli

Then run arbitrary wasm32-unknown-unknown Wasm blobs via:

wasmi_cli <WASM_FILE> <FUNC_NAME> [<FUNC_ARGS>]*

As Rust Library

Any Rust crate can depend on the wasmi crate in order to integrate a WebAssembly intepreter into their stack.

Refer to the wasmi crate docs to learn how to use the wasmi crate as library.

Development

Building

Clone wasmi from our official repository and then build using the standard cargo procedure:

git clone https://github.com/paritytech/wasmi.git
cd wasmi
cargo build

Testing

In order to test wasmi you need to initialize and update the Git submodules using:

git submodule update --init --recursive

Alternatively you can provide --recursive flag to git clone command while cloning the repository:

git clone https://github.com/paritytech/wasmi.git --recursive

After Git submodules have been initialized and updated you can test using:

cargo test --workspace

Benchmarks

In order to benchmark wasmi use the following command:

cargo bench

You can filter which set of benchmarks to run:

  • cargo bench translate

    • Only runs benchmarks concerned with WebAssembly module translation.

  • cargo bench instantiate

    • Only runs benchmarks concerned with WebAssembly module instantiation.

  • cargo bench execute

    • Only runs benchmarks concerned with executing WebAssembly functions.

Supported Platforms

Supported platforms are primarily Linux, MacOS, Windows and WebAssembly.
Other platforms might be working but are not guaranteed to be so by the wasmi maintainers.

Use the following command in order to produce a WebAssembly build:

cargo build --no-default-features --target wasm32-unknown-unknown

Production Builds

In order to reap the most performance out of wasmi we highly recommended to compile the wasmi crate using the following Cargo profile:

[profile.release]
lto = "fat"
codegen-units = 1

When compiling for the WebAssembly target we highly recommend to post-optimize wasmi using Binaryen's wasm-opt tool since our experiments displayed a 80-100% performance improvements when executed under Wasmtime and also slightly smaller Wasm binaries.

License

wasmi is primarily distributed under the terms of both the MIT license and the APACHE license (Version 2.0), at your choice.

See LICENSE-APACHE and LICENSE-MIT for details.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in wasmi by you, as defined in the APACHE 2.0 license, shall be dual licensed as above, without any additional terms or conditions.