This repo contains the code for the on-chain built-in actors that power the Filecoin network starting from network version 16.
The build process of this repo compiles every actor into Wasm bytecode and generates an aggregate bundle to be imported by all clients. The structure of this bundle is standardized. Read below for details.
This codebase is on track to be canonicalized in FIP-0031. As a result, this actor implementation will be the only one recognized by the network.
Actors for the following network versions are provided as well:
The main output of this repo is a CARv1 archive bundling all Wasm bytecode for all actors into a single file, with the following characteristics:
Map<Cid, i32>. Every entry represents a built-in actor.
The CARv1 is embedded as a byte slice at the root of the library, and exported
BUNDLE_CAR public const, for easier consumption by Rust code.
Precompiled actor bundles may also be provided as release binaries in this repo, if requested by implementors.
We usually release all actors, the runtime, and the state abstraction at the same time. That means releasing:
We do not publish the "bundle" but instead build it in CI.
To make this easier, we've added some helper scripts to the Makefile. Instructions follow.
jq(with your favorite package manager)
cargo install cargo-edit).
You can bump the runtime, actors, and bundle versions with the
bump-version target. See Versioning to determine the correct version bump.
By default, this bumps the patch version. To bump to a different version, append, e.g.
BUMP=major. Valid options are:
You can also set a specific version with the
make set-version VERSION=7.1.1
Commit the version changes:
git commit -a -m "Release $(make --quiet version)"
Finally, create a PR to commit your changes, make sure your PR is approved and merged before move to the next step!
NOTE: If you're a not a member of the core FVM team, you'll need help with this step. Please make a PR at this point and ask the core team to publish a release.
make publish to publish all crates to crates.io. This will likely take a while as it re-builds
everything from scratch for validation (multiple times).
NOTE: To do this, you'll need to:
https://crates.ioand confirm your email address (if you haven't already).
Finally, bump the versions to the next alpha and commit the changes:
make bump-version BUMP=alpha git commit -a -m "Release $(make --quiet version)"
There are two options:
Instructions to build from source (option 1):
make bundlefrom the workspace root.
The bundle be written to
Both options are compatible with automation via scripts or CI pipelines.
This part is implementation-specific. Options include:
Once the implementation has validated the authenticity of the bundle, it is expected to do the following:
Because every network version may be backed by different actor code, implementations should be ready to load multiple actor bundles and index them by network version.
When instantiating the ref-fvm Machine, both the network version and the corresponding Manifest root CID must be passed.
A fair question is how crate versioning relates to the protocol concept of
ActorVersion. We adopt a policy similar to specs-actors:
Development versions will use qualifiers such as -rc (release candidate).
As an example of application of this policy to a v10 actor version lineage:
This repo supersedes specs-actors, and fulfils two roles:
This codebase was originally forked from the actors v6 implementation of the Forest client, and was adapted to the FVM environment.
Because this codebase is a common good across all Filecoin client implementations, it serves as a convergence area for all Core Devs regardless of the implementation or project they identify with.