| Continuous Integration |     Test Coverage    |  Documentation   |      Crates.io       |
|:----------------------:|:--------------------:|:----------------:|:--------------------:|
| [![ci][1]][2]          | [![codecov][5]][6]   | [![docs][9]][10] | [![crates][11]][12]  |

[1]: https://github.com/casper-network/casper-wasmi/workflows/Rust%20-%20Continuous%20Integration/badge.svg?branch=master
[2]: https://github.com/casper-network/casper-wasmi/actions?query=workflow%3A%22Rust+-+Continuous+Integration%22+branch%3Amaster
[5]: https://codecov.io/gh/casper-network/casper-wasmi/branch/master/graph/badge.svg
[6]: https://codecov.io/gh/casper-network/casper-wasmi/branch/master
[9]: https://docs.rs/wasmi/badge.svg
[10]: https://docs.rs/wasmi
[11]: https://img.shields.io/crates/v/wasmi.svg
[12]: https://crates.io/crates/wasmi

[license-mit-badge]: https://img.shields.io/badge/license-MIT-blue.svg
[license-apache-badge]: https://img.shields.io/badge/license-APACHE-orange.svg

# `casper-wasmi`- WebAssembly (Wasm) Interpreter

`wasmi` was originally conceived as a component of [parity-ethereum](https://github.com/paritytech/parity-ethereum) (ethereum-like contracts in wasm) and [substrate](https://github.com/paritytech/substrate). These projects are related to blockchain and require a high degree of correctness. The project is not trying to be involved in any implementation of any 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.

The crate `casper-wasmi` is a fork of a wasmi project with additional fixes and security hardening.

# 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. |

[`mutable-global`]: https://github.com/WebAssembly/mutable-global
[`saturating-float-to-int`]: https://github.com/WebAssembly/nontrapping-float-to-int-conversions
[`sign-extension`]: https://github.com/WebAssembly/sign-extension-ops
[`multi-value`]: https://github.com/WebAssembly/multi-value
[`reference-types`]: https://github.com/WebAssembly/reference-types
[`bulk-memory`]: https://github.com/WebAssembly/bulk-memory-operations
[`simd` ]: https://github.com/webassembly/simd
[`tail-calls`]: https://github.com/WebAssembly/tail-call

# 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:

  ```toml
  [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.