Skip to main content

Setting Up Filecoin FVM Localnet for Smart Contract Development

· 3 min read
Pourya Bagheri
Pourya Bagheri
Quantum Computing | Blockchain Soloution | MERN

Filecoin FVM Localnet is a Docker-based solution that simplifies the process of deploying a local Filecoin network for smart contract development. This setup supports testing of Filecoin Virtual Machine (FVM) smart contracts and features such as replication between storage providers (SPs).

System Requirements​

To run Filecoin FVM Localnet, you’ll need:

  • Processor Architecture: ARM64 (e.g., MacBook M1/M2) or AMD64 (e.g., x86 Linux, Windows, macOS).

  • Docker: Ensure Docker is installed on your system.

Installation​

Step 1: Clone the Repository​

Run the following command to clone the Filecoin FVM Localnet repository:

git clone https://github.com/filecoin-project/filecoin-fvm-localnet.git

Step 2: Navigate to the Repository​

cd filecoin-fvm-localnet

Step 3: Configure the Environment​

To use the default configuration with 2k sectors:

cp .env.example .env

To configure an 8MiB sector network, edit the .env file to enable the relevant settings.

Step 4: Start the Localnet​

To run a single miner instance:

alt text

docker compose up

To run two miners with replication capabilities:

docker compose --profile replication up

Stop the network using Ctrl+C.

Step 5: Access the Boost UI​

Once the localnet is running, you can access the Boost UI:

Setting Up Metamask​

Configuring Metamask​

  1. Open Metamask and click on the network dropdown at the top.

  2. Click Add a network manually and enter the following details:

Funding a Wallet​

  1. Retrieve the t4 address for your wallet using the following command :
docker compose exec lotus lotus evm stat [wallet]
  1. Send test funds (tFIL) to your wallet using:
docker compose exec lotus lotus send <t4_address> 1000

Funds will appear in Metamask within approximately 45 seconds.

Usage Notes​

Sector Sizes and Block Time​

  • Default sector size: 2KiB (maximum storage deal size).

  • Optional: Configure for 8MiB sectors by editing .env and restarting the localnet.

  • Block time: 15 seconds (half the time of the Filecoin mainnet).

Resetting the Localnet​

If the network takes a long time to sync, delete the data/ directory and restart the localnet to reset the state.

Common Commands for Filecoin FVM Localnet​

Packing Files for Deals​

  1. Pack files into CAR format:
ipfs-car pack [file] --output [filename].car
  1. Generate CommP for the packed CAR file:
boostx commp [file.car]

Creating a Storage Deal​

boost deal --verified=false \
           --provider=[minerId] \
           --http-url=[file-address-on-server] \
           --commp=<commp_value> \
           --car-size=<car_file_size> \
           --piece-size=<piece_size> \
           --payload-cid=<payload_cid> \
           --storage-price=[estimate-number] \
           --duration=[time]

Checking Deal Status​

Retrieve the status of a deal:

boost deal-status --provider=<provider_id> --deal-uuid=<deal_uuid>

Retrieving Stored Data​

To retrieve stored data:

boost retrieve --provider=<provider_id> --output=/path/to/output/file.car <payload_cid>