Filecoin

Filecoin is a decentralized storage network designed to store humanity's most important information.

This repo contains utilities and libraries to work with the Filecoin Virtual Machine

Packages

fvm_actor_utils

A set of utilities to help write testable native actors for the Filecoin Virtual Machine. Provides abstractions on top of FVM-SDK functionality that can be shimmed or mocked in unit tests. This includes helpers for:

• Universal receiver hooks (as defined in FRC-0046)
• IPLD-compatible blockstore
• Messaging and address resolution

frc42_dispatch

Reference library containing macros for standard method dispatch. A set of CLI utilities to generate method numbers is also available: fvm_dispatch_tools

Specification	Reference Implementation	Examples
FRC-0042	frc42_dispatch	greeter

frc46_token

Reference library for implementing a standard fungible token in native actors

Specification	Reference Implementation	Examples
FRC-0046	frc46_token	basic_token basic_receiver

frc53_nft

Reference library for implementing a standard non-fungible token in native actors

Specification	Reference Implementation	Examples
FRC-0053	frc53_nft	basic_nft basic_receiver

frc46_factory_token

A configurable actor that can be used as a factory to create instances of FRC-0046-compatible tokens, based on frc46_token and implemented here

Release Process

This section documents the release process for actor-utils packages.

Published Packages

The following packages are published to crates.io:

• fvm_actor_utils - Core utilities for FVM native actors
• frc42_dispatch - Method dispatch macros and utilities
• frc42_hasher - FRC-0042 method hashing utilities
• frc42_macros - FRC-0042 procedural macros
• frc46_token - Fungible token reference implementation
• frc53_nft - Non-fungible token reference implementation
• fvm_dispatch_tools - CLI utilities for method dispatch

Release Steps

1. Version Bumping

   # Update version in package Cargo.toml
   # Update workspace dependencies in root Cargo.toml if needed

2. Pre-publish Validation

   # Check compilation
   cargo check -p <package-name>
   
   # Dry run publish
   cargo publish --dry-run -p <package-name>

3. Publishing

   # Authenticate with crates.io
   cargo login <your-token>
   
   # Publish in dependency order:
   # 1. frc42_hasher (base dependency)
   # 2. frc42_macros (depends on frc42_hasher)
   # 3. frc42_dispatch (depends on frc42_hasher and frc42_macros)
   # 4. fvm_actor_utils (depends on frc42_dispatch)
   # 5. frc46_token (depends on frc42_dispatch and fvm_actor_utils)
   # 6. frc53_nft (depends on frc42_dispatch and fvm_actor_utils)
   # 7. fvm_dispatch_tools (depends on frc42_dispatch)
   cargo publish -p <package-name>

4. Post-Release

   # Tag the release
   git tag <package-name>@<version>
   git push origin <package-name>@<version>

Coordination Points

Note: before documenting the coordination points more, we should first see about simplifying this repo by potentially removing unused functionality and moving some of it into actors-utils itself. This is discussed in issue #203.

• FVM Releases: TODO - Document coordination process with FVM releases
• Built-in Actors / Network Upgrade: TODO - Document alignment with built-in actors and Network Upgrades

License

Dual-licensed: MIT, Apache Software License v2.

Testing

The tests require downloading a builtin-actors bundle. Either run the tests with make test or run make test-deps before running tests manually with cargo.

You can change the actors version by changing ACTORS_VERSION in the Makefile. If you want to test with a custom bundle entirely, replace the testing/bundles/builtin-actors.car symlink with the custom bundle. Note, however, that running make test will revert that change, so you'll want to test with cargo test manually.

For local coverage testing, please install the grcov crate.

_{Copyright Protocol Labs, Inc, 2022}