What is Filecoin?

Filecoin is a decentralized storage network designed to store humanity's most important information. It uses blockchain technology to enable users to rent unused hard drive space or offer their own storage capacity to others, creating a marketplace for digital storage. Participants are incentivized through FIL, the network's native cryptocurrency.

At its core, Filecoin aims to create a more efficient, robust, and accessible alternative to centralized cloud storage providers. Through cryptographic proofs, it verifies that data is being stored correctly and continuously over time.

Enter the Filecoin Virtual Machine (FVM)

The Filecoin Virtual Machine, launched in March 2023, brings smart contract capabilities to the Filecoin network. FVM introduces programmable storage, allowing developers to create applications that can automatically manage storage deals, access control, and data governance.

Key features of FVM include:

EVM Compatibility: FVM supports Solidity contracts, making it accessible to Ethereum developers
Built-in Storage Primitives: Native functions for interacting with Filecoin's storage marketplace
Actor Model: Uses Filecoin's actor-based programming model for security and scalability
Cross-Chain Potential: Enables communication with other blockchain networks

The Filecoin Network: Beyond Simple Storage

Filecoin is a decentralized storage network that transforms unused storage capacity into an algorithmic market. Unlike centralized storage providers, Filecoin creates a blockchain-based marketplace where:

Storage Providers offer storage space and earn FIL tokens
Clients pay for their data to be stored reliably
Cryptographic Proofs verify data is being stored correctly
Economic Incentives ensure long-term preservation of information

At its core, Filecoin aims to create a more resilient, censorship-resistant storage layer for the internet, where market dynamics determine price and no single entity controls the infrastructure.

The Filecoin Virtual Machine: Bringing Programmability to Storage

While Filecoin initially focused solely on storage deals, the Filecoin Virtual Machine, launched in March 2023, fundamentally expanded these capabilities by introducing programmable storage. The FVM is a runtime environment that enables the execution of smart contracts on the Filecoin blockchain.

Key Architectural Components of FVM

Actor Model: FVM uses an "actor-based" architecture where actors (similar to smart contracts) maintain state and respond to messages. This provides better isolation and security than traditional account-based models.
WASM-Based Execution: Unlike Ethereum's bytecode VM, FVM uses WebAssembly (WASM) as its base layer, offering better performance and support for multiple programming languages.
EVM Compatibility Layer: FVM includes the Filecoin Ethereum Virtual Machine (FEVM), allowing Ethereum-compatible contracts to run directly on Filecoin.
Built-in Actors: System-level contracts that implement core Filecoin functionality like storage markets, token transfers, and power management.

FVM Execution Environment

The FVM execution stack consists of:

Base Layer: WASM runtime with deterministic execution
Built-in Actors: System-level functionalities
User-Defined Actors: Custom smart contracts deployed by users
FEVM: Compatibility layer for Solidity contracts

Adding Filecoin Networks to MetaMask:

Adding Filecoin Calibration Testnet to MetaMask

The first step is setting up your MetaMask wallet to connect to the Filecoin network. Let's start with the testnet:

Open your browser and go to https://chainlist.org/chain/314159
Connect your wallet by clicking the "Connect Wallet" button at the top right of the page. A MetaMask popup will appear asking for permission to connect.
Click "Next" in the MetaMask popup, then click "Connect" to allow ChainList to see your account information.
Add the network by clicking the "Add to MetaMask" button next to Filecoin Calibration.
Approve the network addition when MetaMask prompts you. This will add the Filecoin Calibration testnet to your list of networks.
Confirm success - You should now see "Filecoin Calibration" in your network dropdown list in MetaMask, and the network icon should change to Filecoin's symbol.

Adding Filecoin Mainnet to MetaMask

When you're ready to deploy to the main Filecoin network, follow these steps:

Visit ChainList by going to https://chainlist.org/chain/314
Connect your wallet if it's not already connected, by clicking the "Connect Wallet" button.
Approve the connection in the MetaMask popup.
Add Filecoin Mainnet by clicking the "Add to MetaMask" button.
Confirm in MetaMask by clicking "Approve" when prompted to add the network.
You're all set! Your MetaMask wallet is now configured to work with the Filecoin Mainnet.

Switching Between Networks

After adding both networks, you can easily switch between them:

Click on the network dropdown at the top of your MetaMask extension
Select "Filecoin Calibration" for testing purposes
Select "Filecoin Mainnet" when you're ready to use real FIL tokens

Getting Test Tokens

Before you start developing on the Calibration testnet, you'll need some test tokens:

Make sure you've switched to the "Filecoin Calibration" network in MetaMask
Visit the Filecoin Calibration Faucet
Paste your wallet address and complete the verification
You'll receive test tokens within a few minutes

Now your MetaMask wallet is fully configured for Filecoin development!

Setting Up Your FVM Development Environment

Installing Development Tools

First, ensure you have the necessary tools installed:
in this article we’ll be initializing our project with hardhat so firstly make sure you have node.js installed if not install use the command below

Recommended Way: Use NodeSource (latest stable version)

This is the best way to get the latest LTS (Long Term Support) version.
Step 1: Install curl if you don’t have it

sudo apt update
sudo apt install curl -y

Step 2: Add the NodeSource repo and install Node.js (e.g., 20.x LTS)

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs

This will install both node and npm.

Step3: Verify your installation

node -v
npm -v

Let’s now create and initialize our project


mkdir fvm-project
cd fvm-project
# Initializa a new node.js project
npm init -y

# Install Hardhat and supporting plugins
npm install --save-dev hardhat @nomicfoundation/hardhat-toolbox
npm install --save-dev @nomicfoundation/hardhat-verify dotenv

# Initialize Hardhat
npx hardhat init

Go to the contracts folder and create a file name Counter.sol then paste the code below there

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

contract Counter {
    uint256 public count;

    function increment() public {
        count += 1;
    }

    function decrement() public {
        require(count > 0, "Counter is zero");
        count -= 1;
    }

// add reset function

    function getCount() public view returns (uint256) {
        return count;
    }
}

Setting Up Environment Variables

To keep your private keys secure:

install the dotenv package

npm install --save-dev dotenv

Create the .env file in your project root
Add your private key to your .env file
Make sure to add .env to your .gitignore file to prevent accidentally sharing your private key:

PRIVATE_KEY=your_private_key_here

Important: Replace "your_private_key_here" with the private key from the MetaMask wallet you funded with testnet FIL.

Configuring Hardhat for Filecoin Networks

Let’s now Create an Hardhat configuration that works with all Filecoin networks:
1. Open the hardhat.config.js file in your project root and replace its contents with:

require("dotenv").config();
require("@nomicfoundation/hardhat-toolbox");

/** @type import('hardhat/config').HardhatUserConfig */
module.exports = {
  solidity: "0.8.28",
  networks: {
    calibration: {
      url: "https://api.calibration.node.glif.io/rpc/v1",
      accounts: [process.env.PRIVATE_KEY],
    },
  },
  solidity: {
    version: "0.8.28",
    settings: {
      optimizer: {
        enabled: true,
        runs: 200,
      },
    },
  },
  paths: {
    sources: "./contracts",
    tests: "./test",
    cache: "./cache",
    artifacts: "./artifacts",
  },
  mocha: {
    timeout: 40000,
  },
};

Compiling and Deploying FVM Contracts

Compiling Your Contracts

Compile your contract with this simple command:

npx hardhat compile

If successful, you'll see a message indicating that the compilation was completed.

Creating a Deployment Script

Navigate to the scripts directory and create a file named deploy.js
Add the following code to your deployment script:

const hre = require("hardhat");

async function main() {
  const Counter = await hre.ethers.getContractFactory("Counter");
  const counter = await Counter.deploy();

  // Wait for the contract to be deployed
  await counter.waitForDeployment();


  const counterAddress = await counter.getAddress();

  console.log("Counter deployed to:", counterAddress);
}

main().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});

Deploying to the Filecoin Calibration Testnet

Now, let's deploy your contract to the Filecoin Calibration testnet:

npx hardhat run scripts/deploy.js --network calibration

After successful deployment, you'll see a message like:

Counter deployed to: 0x1234...5678

Save this Contract address as you’ll be needing it for the verification step

Verifying Your Contract on FilScan

Finally, let's verify your contract so others can see the source code:

npx hardhat verify --network calibration YOUR_CONTRACT_ADDRESS

Replace YOUR_CONTRACT_ADDRESS with the address you received from the deployment step.

Once verification is complete, you can visit the Filecoin Calibration explorer (FilScan) to view your verified contract.

Congratulations! You've successfully written, deployed, and verified your first smart contract on the Filecoin blockchain. This is just the beginning of your journey with FVM development!

Understanding Filecoin and the Filecoin Virtual Machine