Actor Bundler

A standalone tool for bundling IPC (InterPlanetary Consensus) FVM (Filecoin Virtual Machine) actors with their initialization states.

Overview

This repository provides a bundler that compiles custom FVM actors, generates their initialization states, and packages everything into a bundle for deployment. The bundler is designed to work with user-implemented actors that follow the IPC actor pattern.

Key Features

1. Bundle IPC FVM Actors - Compiles and packages multiple custom actors into a single bundle
2. State Initialization - Automatically generates default initialization states for each actor
3. WASM Blob Management - Builds WASM binaries and stores them in a blockstore alongside their states
4. Flexible Configuration - Supports custom actor workspaces with configurable build and output options

Project Structure

actor-bundler/
├── bundler/              # Main bundler tool
│   ├── src/
│   │   ├── lib.rs       # Core bundler logic
│   │   └── bin/
│   │       └── actor-bundler.rs  # CLI entry point
│   └── Cargo.toml
└── example-actors/       # Sample user-implemented actors
    ├── actors/          # Individual actor implementations
    │   ├── activity-tracker/
    │   ├── chainmetadata/
    │   ├── eam/
    │   └── gas_market/
    └── Cargo.toml       # Workspace configuration

Example Actors

The example-actors/ folder contains sample actors implemented by users to demonstrate the actor pattern. Each actor must:

• Implement the required actor interface (using ActorCode trait)
• Define a default_state_bytes() function that returns the serialized initial state
• Export the initialization state for the bundler to collect

These example actors serve as:

• Reference implementations for custom actor development
• Test cases for the bundler
• Templates for building new IPC actors

How the Bundler Works

The bundler follows a systematic process to create the final bundle:

1. Detect Example Actors Workspace

• Scans the provided --actors-dir for a Cargo workspace
• Parses Cargo.toml to identify all actor packages in the workspace
• Validates that each actor package is properly configured

2. Build the Actors

• Compiles each actor with wasm32-unknown-unknown target
• Generates optimized WASM blobs for each actor
• Ensures all actors build successfully before proceeding

3. Dynamically Create State Initialization Project

• Creates a temporary Rust project that imports all actors
• Generates code that calls each actor's default_state_bytes() function
• Links this project against all actor crates to collect their initialization states

4. Build the WASM Blobs

• Compiles the WASM binaries for each actor
• Optimizes the WASM for size and performance
• Validates the WASM modules are valid FVM bytecode

5. Store in Blockstore

• Creates an IPLD blockstore (content-addressed storage)
• Stores each WASM blob with its CID (Content Identifier)
• Stores the corresponding initialization state for each actor
• Links actors, their code, and their states in the blockstore

6. Output Files

• Generates the final bundle file containing all actors
• Outputs individual state files for each actor
• Creates a manifest mapping actor names to their CIDs
• Writes everything to the specified --output directory

Usage

Prerequisites

• Rust toolchain with wasm32-unknown-unknown target
• Cargo workspace with actor implementations

Running the Bundler

cd bundler
cargo run --release --bin actor-bundler -- \
  --actors-dir `pwd`/../example-actors/actors \
  --output ./output

Command-line Options

• --actors-dir - Path to the actors directory containing Cargo.toml (required)
• --output - Output directory for the bundle and states (required)
• --generate-states - Generate default states for all actors (default: true)
• --build - Build actors before bundling (default: true)

The bundle will be inside ./output and ready for deployment to an IPC subnet.

Actor Requirements

For an actor to be compatible with this bundler, it must:

1. Define initialization state - Implement a default_state_bytes() function:

   #[cfg(not(target_arch = "wasm32"))]
   pub fn default_state_bytes<BS: fvm_ipld_blockstore::Blockstore>(
       store: &BS
   ) -> anyhow::Result<Vec<u8>> {
       let state = State::new(store)?;
       Ok(fvm_ipld_encoding::to_vec(&state)?)
   }

2. Use the actor macro - Enable FVM actor features:

   #[cfg(feature = "fil-actor")]
   fil_actors_runtime::wasm_trampoline!(YourActorName);

3. Be part of a workspace - Listed in the actors workspace Cargo.toml