yann-sjtu / wasmi

WebAssembly (Wasm) interpreter.

Continuous Integration	Test Coverage	Documentation	Crates.io

wasmi- WebAssembly (Wasm) Interpreter

wasmi was conceived as a component of parity-ethereum (ethereum-like contracts in wasm) and substrate. These projects are related to blockchain and require a high degree of correctness. The project is not trying to be be involved in any implementation of any of work-in-progress Wasm proposals. Instead the project tries to be as close as possible to the specification, therefore avoiding features that are not directly supported by the specification.

With all that said wasmi should be a good option for initial prototyping and there shouldn't be a problem migrating from wasmi to another specification compliant execution engine later on.

Distinct Features

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

• Primarily concerned about
  • correct and deterministic WebAssembly execution.
  • WebAssembly specification compliance.
• Can itself be compiled to WebAssembly.
• Low-overhead and cross-platform WebAssembly runtime.
• New experimental v1 engine allows to be used as a drop-in solution for Wasmtime.

Wasm Proposals

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

Wasm Proposal	Status	Comment
mutable-global	✅
saturating-float-to-int	✅
sign-extension	✅
multi-value	✅
reference-types	❌	No support is planned for wasmi.
bulk-memory	⌛	Planned but not yet implemented. Low priority.
simd	❌	No support is planned for wasmi.
tail-calls	⌛	Not yet part of the Wasm standard but support in wasmi is planned. Low priority.

Developer Notes

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

If you want to test the entire wasmi workspace using all features we recommend

cargo test --all-features --workspace

This tests both wasmi engines using all features available to them.

Note

It is recommended to test using --release since compiling and testing without optimizations usually is a lot slower compared to compiling and testing with optimizations.

Platforms

Supported platforms are primarily Linux, MacOS, Windows and WebAssembly.

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

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

Features

Virtual Memory

On 64-bit platforms we further provide cross-platform suppport for virtual memory usage. For this build wasmi using:

cargo build --features virtual_memory

New Engine

We are currently building an experimental new wasmi engine that mirrors the Wasmtime APIs and has an improved performance and decreased overhead compared to the old wasmi engine.

You can enable and start using it today by using the wasmi_v1 workspace package:

cargo build --package wasmi_v1

Note

• The new v1 implementation is experimental and therefore not recommended for production usage, yet.

• Be sure to use the following Cargo profile to gain the maximum performance using the v1 engine:

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

Benchmarks

In order to benchmark wasmi use the following command:

cargo bench

Note: Benchmarks can be filtered by compile_and_validate, instantiate and execute flags given to cargo bench. For example cargo bench execute will only execute the benchmark tests that test the performance of WebAssembly execution.

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.