Aviv Eyal edited this page Nov 29, 2018 · 45 revisions


This repo contains the design docs and a high level overview of sm-wasm. SpacemeshOS is a blockmesh operating system designed to run a base cryptocurrency (Spacemesh Coins), smart contracts and tokens. sm-wasm is the technology included in Spacemesh to enable programmable money. Our goal is to provide a modern and robust smart contracts toolchain and VM based on wasm.

About WASM

WebAssembly (abbreviated Wasm) is a binary instruction format for a stack-based virtual machine. Wasm is designed as a portable target for compilation of high-level languages like C/C++/Rust, enabling deployment on the web for client and server applications.

Generally speaking, wasm tech includes the various wasm specifications as well as open source dev toolchains and wasm interpreters / VMs

Wasm tech for modern smart contracts - pros

  1. Extensive programming languages support - rust, AssemblyScript, c, c++. Developers can choose any language and toolset that supports compilation to wasm. Developers are not limited to domain-specific languages such as Solidity and can use their fave general purpose programming language
  2. Lower gas costs - many ops will cost less in terms of estimated CPU cycles compared to the EVM CPU cycles due to better use of variable types beyond int256 for most operations.
  3. Large ecosystem - wasm interpreters, jit compilers, plugins, tools and backends for various programming languages
  4. Wasm tech is not controlled by any one entity and is patent-free - it is a consortium based standard with support of all browser makers. Wasm is lead by a W3C working group with lots of participants.
  5. Good industry momentum behind wasm - all major browsers support it. The tech is mature to a level that real complex apps can run in wasm in the browser. e.g. Unreal gaming engine 4
  6. 2 JIT VMs in production supported by large organizations - V8 and SpiderMonkey
  7. Opens the door for a whole world of languages, analyzers, debuggers, optimizers and frameworks
  8. Good for research - Nice extensibility story via pre-compiled wasm contracts which run at native code speeds and can be used by any client. Moves pre-compiles native client implementations to a shared module. Precompiled examples - ec pairing method, ec signatures, hash functions - sha256, and more...

wasm tech for modern smart contracts - cons

  1. Wasm is a relative young tech and likely introduces new smart contract attack surfaces
  2. Metering injection to wasm code and code validation at deploy time is complex and may introduce new security risks
  3. JIT runtimes may perform code optimizations that introduce new security vulnerabilities that malicious code may take advantage of, as they are designed to optimize for the end user experience over execution correctness. This means that it is highly-likely that a blockchain-first JIT VM needs to be developed from scratch, and non-blockchain-first-vms may not be reused.

Design rational

Define a portable, size and load-time-efficient binary format to serve as a compilation target which can be compiled to execute at native speed by taking advantage of common hardware capabilities available on a wide range of platforms, including mobile and IoT.

Please read the wasm design docs and the full design rationale.

SM-WASM High Level Goals

  1. Design a DSL (domain specific languages) that makes it easy to write smart contracts in c or in Rust programming languages
  2. Design the std library that enables devs to interact with the Spacemesh global computer state and deployed functions
  3. Build a security and determinism focused JIT compiler and VM for wasm smart contracts execution
  4. Work closely with other blockchain projects on common shared functionality and capabilities such as a blockchain-first JIT VM for wasm and metered code runtime enforcement injection.

Spacemesh VM Requirements

  • Must provide JIT/AOT compilation of wasm code to native assembly code
  • Must provide 100% deterministic and correct execution on all supported native desktop OSs (Windows, Linux, OS X). This includes not performing any compilation optimizations that may introduce non-determinism or ignore thrown exceptions
  • Must be optimized for security performance above the end user experience
  • Must support metered code execution

Issues with Browser-focused VMs

  • Non-deterministic behavior due to compilation optimizations
  • May silently handle some exceptional conditions as they are optimized for the user experience


  • wasm - Web assembly specs - the common instruction set, the binary format, and runtime binding to external libs
  • sm-wasm - a deterministic subset of the wasm instructions set. e.g. excluding floating points ops and possible NaN floating points ops results which have an undefined sign bit. sm-wasm is the language of sm-applets. sm-wasm can also be described as a DSL (domain specific language)
  • sm-applets - aka smart contracts or just applets. Blockmesh programs callable by users and other programs using code transections. The Spacemesh global computer is formed by users calling methods on deployed sm-applets. Applets can be coded with any high-level language such as Rust that supports compiling to sm-wasm binary code and binding to methods in the sm-std library at runtime
  • sm-applet interface - the structure of every sm-applet module. e.g. what imported namespaces are allowed, what symbols should be exported and what exception handler should be called on an exception.
  • Code Transactions - transactions calling sm-applets deployed on the Spacemesh global computer by users or by other sm-applets
  • sm-vm - The Spacemesh virtual machine. It is a metered sm-wasm interpreter supporting metered execution of code transactions
  • sm-rust - a subset of the Rust programming language that produces valid sm-wasm when compiled to wasm
  • Metered Execution - Runtime sm-applets methods execution that implements gas metering and determines the amount of gas used by a method execution at runtime
  • Gas Injection - The process of injecting metered execution wasm code to sm-applets. The injection transforms compiled sm-wasm code to deployable sm-wasm code for metered execution
  • sm-deployer - A runtime component which is a part of the Spacemesh full node software package that: (1) validates that wasm code is a valid sm-wasm code, (2) injects gas metering code to sm-applets and (3) creates a deployable sm-wasm binary for blockmesh deployment (4) possibly remove debugging code from production deployments
  • sm-toolchain - The developers tools that enable writing, debugging, testing and deploying sm-applets
  • sm-std - The spacemesh standard runtime library. Provides bindings to the programs and accounts runtime state and utility functions. Provided in wasm and is bindable from higher-level languages such as rust and c as part of the supported toolchain
  • sm-std-interface - The interface definitions for the methods provided by and implemented by sm-std
  • sm-debug - a runtime library for debugging sm-applets in testnets
  • applet interface - The interface definition of a sm-applet
  • Spacemesh App - The Spacemesh client app (Wallet, Dashboard and Smart Con)

Project Detailed Goals

  • Fully specify sm-wasm opcodes, injected metered code, the vm, the metering process, the std-library and the various tools used in the main dev workflows
  • Provide tutorials, walkthroughs and examples for coding, testing and deploying smart contracts in rust to the Spacemesh testnet and mainnet
  • Specify a substet of wasm to remove some local non-determinism. e.g. floating points ops

Resources and Relevant Projects

The following projects employ slightly different design decisions but are otherwise mostly similar in their scope:

Get up to speed on WASM smart contracts tech

Use Cases

Developer Main Use Case

  1. Write an applet in ANY high-level language that can (1) compile to wasm (2) bind to sm-std (and possibly sm-debug) library
  2. Deploy the applet to a testnet
  3. Debug the applet - read state and execute code transactions
  4. Deploy the applet to mainent
  5. Perform additional tests on mainent - read state and execute code transactions
  • Deployment involves (1) sm-wasm code validation, (2) metering code injection (and possibly debug code removal). Code validation includes conformance with the DSL spec and linkable external libs rule. e.g. Code may only link to sm-std and to sm-debug. Code injection involves adding metering to each code execution bunch and loops with runtime defined number of iterations.
  • Reading applet state and code transactions execution should be done via the Spacemesh App or via the Spacemesh API which is provided by a full node or via the Spacemesh Gateway endpoint.
  • Execution of applet code by full node is implemented by loading an applet sm-wasm code to a wasm-vm, binding it with the node's sm-std library and, providing transaction data to callable methods, executing callable methods, checking gas availability, handling exceptions, etc...

User Main Use Case

  1. Read applet current state. e.g. Users token balance in an applet which manages a token ledger
  2. Execute a programmed-transaction
  • The user use cases will be implemented in the Spacemesh App.
  • The App need to be able to accept an applet's interface and deployed address to generate the UI to work with the contract until the Spacemesh SDK ships with full support for smart contracts.


  • Specify sm-wasm instructions-set. This involves specific unsupported wasm opcodes

  • Specify sm-std-interface api

    • Read blockmesh state
    • R/W applet state
    • Concrete types (big int, hash, address, etc...)
  • Implement sm-std lib in Spacemesh node

  • Specify the common sm-applets interface

  • Specify sm-applet interface

    • Canonical format
    • Representation of exported readable state
    • Definition of exported transactional methods
  • Specify state initialization in sm-wasm

    • e.g. Deployer() method to initialize state. a.k,a construction
  • Specify local vars and memory usage in sm-wasm

    • e.g. GetLocal() and SetLocal()
    • Runtime memory allocation pattern
  • Build sm-wasm metered execution gas costs model

    • Cost for each opcode
    • Cost for each sm-std method call
    • Cost for local variables
    • Cost for additional ram allocation
    • Out of gas exception handling
    • Cost for store i/o (reading applet state and writhing applet state)
  • Design and implement sm-debug `lib in Spacemesh node

  • Design and implement sm-deployer in Spacemesh node

    • Validate sm-wasm instructions set
    • Implement gas-injection into Applet's sm-wasm code
    • Create deployable applet wasm module and deploy it (including applet state initialization)
    • Create the applet's sm-applet interface
  • Design and implement sm-vm metered execution of code transactions

  • Specify sm-applets module format

    • exported shared memory
    • exported entry points
  • Specify sm-rust, sm-c, sm-c++, sm-typescript, etc... dialects

    • Subset of a higher-level language that is compiled to valid sm-wasm instruction set
    • Spec must exclude language features which produces invalid sm-wasm instructions
    • Spec canonical format for writing an applet in each of these languages. e.g. constructions, public methods, etc...
  • Specify sm-toolchain components

    • Supported high-level languages - in theory, most languages that don't rely on garbage collection and have a good wasm compiler can be supported
    • Supported wasm compilers for each supported high-level language - in theory most robust wasm compilers can be supported
    • Deploy applet via Spacemesh App flow (debug and productions deployments)
    • Debug and log info in a Spacemesh full node
    • Execute code transactions from the Spacemesh App

Additional Resources

WASM VMs - JIT/AOT compilers

Wasm interpreters

  • Wagon

Research notes

  • JIT/AOT VMs can be x100 faster than AST interrupters
Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.