3 releases (breaking)

0.3.0 Jun 28, 2023
0.2.0 Jan 14, 2023
0.1.0 Dec 7, 2022

#798 in Data structures

Download history 107/week @ 2023-12-18 5/week @ 2023-12-25 6/week @ 2024-01-01 167/week @ 2024-01-08 98/week @ 2024-01-15 155/week @ 2024-01-22 262/week @ 2024-01-29 306/week @ 2024-02-05 36/week @ 2024-02-12 34/week @ 2024-02-19 109/week @ 2024-02-26 84/week @ 2024-03-04 40/week @ 2024-03-11 252/week @ 2024-03-18 82/week @ 2024-03-25 165/week @ 2024-04-01

543 downloads per month


2.5K SLoC

Reference Filecoin VM implementation (v4; dev)

Continuous integration

This repository contains the reference implementation of the Filecoin VM (specs). It is written in Rust, and intended to be integrated via FFI into non-Rust clients (e.g. Lotus, Fuhon), or directly into Rust clients (e.g. Forest). FFI bindings for Go are provided in-repo, and developers are encouraged to contribute bindings for other languages.

See the Project Website for details.

Build requirements

Build instructions

$ git clone https://github.com/filecoin-project/ref-fvm.git
$ cd ref-fvm
$ make

Code structure

Here's what you'll find in each directory:

  • /fvm
    • The core of the Filecoin Virtual Machine. The key concepts are:
      • Machine: an instantiation of the machine, anchored at a specific state root and epoch, ready to intake messages to be applied.
      • Executor: an object to execute messages on a Machine.
      • CallManager: tracks and manages the call stack for a given message.
      • Invocation container (conceptual layer, not explicitly appearing in code): the WASM instance + sandbox under which a given actor in the call stack runs.
      • Kernel: the environment attached to an invocation container for external interactions.
    • There are two API boundaries in the system:
      1. the boundary between the actor code and the Kernel, which is traversed by invoking Syscalls.
      2. the boundary between the FVM and the host node, represented by Externs.
    • Some parts of the FVM are based on the Forest implementation.
  • /sdk
    • Reference SDK implementation to write Filecoin native actors, used by the canonical built-in actors through the Actors FVM Runtime shim.
    • User-defined FVM actors written in Rust can also use this SDK, although it is currently quite rough around the edges. In the next weeks, we expect to sweeten it for improved developer experience.
    • Alternative SDKs will emerge in the community. We also expect community teams to develop SDKs in other WASM-compilable languages such as Swift, Kotlin (using Kotlin Native), and even Go (via the TinyGo compiler).
  • /shared
    • A crate of core types and primitives shared between the FVM and the SDK.
  • /ipld
    • IPLD libraries. Some of which are based on, and adapted from, the Forest implementation.
  • /testing/conformance
    • Contains the test vector runner, as well as benchmarking utilities on top of it.
    • The conformance test runner feeds the test vector corpus located at https://github.com/filecoin-project/fvm-test-vectors into ref-fvm, in order to validate spec conformance.
    • The benchmarking utilities use the criterion Rust library to measure the performance and overhead of ref-fvm across various facets.
    • See the instructions about how to run the tests and the benchmarks.
    • Disclaimers
      • Benchmarks are currently very slow to run, setup and teardown. This is due to using default WASM cache, and will be fixed soon.


Dual-licensed: MIT, Apache Software License v2, by way of the Permissive License Stack.

actors and vm forked from ChainSafe/forest commit: 73e8f95a108902c6bef44ee359a8478663844e5b


KAMT crate for use as rust IPLD data structure, which stands for "fixed size Keyed AMT" and is basically a copy of the HAMT with some extra features that were deemed to be too complex to add there.

The original purpose of the features that gave birth to the KAMT was to optimize the HAMT for the EVM/Solidity storage layout, which uses hashing+offset for keys to co-locate array items in a contiguous address space. While the HAMT allowed the hashing strategy to work this way, it resulted in very deep parts of the tree where only the leaves contained key-value pairs. The main feature of this data structure then is to skip the empty levels and point straight to the next data bearing node.

The other difference is that to emphasize this the KAMT doesn't do any hashing on its own, it works with fixed size byte arrays as keys.

Data structure reference


~71K SLoC