FEVM Hardhat Kit

A comprehensive TypeScript-based Hardhat development kit for building smart contracts on the Filecoin EVM (FEVM). This kit includes example contracts, deployment scripts with verification support on blockscout-filfox explorers, and interactive tasks for contract interaction.

Cloning the Repo

Open up your terminal (or command prompt) and navigate to a directory you would like to store this code on. Once there type in the following command:

git clone --recurse-submodules https://github.com/filecoin-project/fevm-hardhat-kit.git
cd fevm-hardhat-kit
yarn install

This will clone the hardhat kit onto your computer, switch directories into the newly installed kit, and install the dependencies the kit needs to work.

Setup Environment Variables

1. Get a private key from a wallet provider such as Metamask.

2. Create your environment file:

   cp .env.example .env

3. Replace your private key in the .env file:

   PRIVATE_KEY=your_private_key_here

⚠️ Security Warning: Never commit .env files containing private keys to version control. The .env file is already gitignored by default - do not remove it from .gitignore.

Get the Deployer Address

Run this command:

yarn hardhat get-address

This will show you the ethereum-style address associated with that private key and the filecoin-style f4 address (also known as t4 address on testnets)! The Ethereum address can now be exclusively used for almost all FEVM tools, including the faucet.

Fund the Deployer Address

Go to the Calibrationnet testnet faucet, and paste in the Ethereum address from the previous step. This will send some calibration testnet FIL to the account.

Deploy the Contracts

Currently the kit deploys 4 main contracts:

• SimpleCoin: A basic ERC20-style token contract demonstrating simple Solidity functionality
• FilecoinMarketConsumer: A contract that demonstrates how to use Filecoin APIs to access storage deal data
• DealRewarder: A bounty contract for incentivizing data storage on Filecoin
• DealClient: A contract that creates Filecoin storage deals within Solidity smart contracts

Type in the following command in the terminal to deploy all contracts:

yarn hardhat deploy

This will compile all the contracts in the contracts folder and deploy them to the Calibrationnet test network. The deployment script automatically attempts to verify contracts on both Blockscout and Filfox explorers. You can skip verification steps by setting these environment variables in your .env file:

IGNORE_FILFOX_VERIFICATION=true
IGNORE_BLOCKSCOUT_VERIFICATION=true

Keep note of the deployed contract addresses for the next step.

Interact with the Contracts

You can interact with contracts via hardhat tasks, found in the 'tasks' folder. The kit includes tasks for all deployed contracts. For example, to interact with the SimpleCoin contract:

Type in the following command in the terminal:

yarn hardhat get-balance --contract 'THE DEPLOYED CONTRACT ADDRESS HERE' --account 'YOUR ETHEREUM ADDRESS HERE'

The console should read that your account has 12000 SimpleCoin!

Filecoin APIs

The primary advantage of the FEVM over other EVM based chains is the ability to access and program around Filecoin storage deals. This can be done in the FEVM via the Filecoin.sol library maintained by Zondax. Note this library is currently in BETA. It is unaudited, and the APIs will likely be changing with time. This repo will be updated as soon as possible when a breaking change occurs.

The library is included in this kit as an NPM package and will automatically be downloaded when you perform the yarn command (don't confuse these with the included mocks)!

Currently you will find a getter contract that calls the getter methods on the MarketAPI to get storage deal data and store that data. To do this you will need dealIDs which you can find here on FilFox.

As an example to store most of the data available for a deal run the store-all command with a specified dealID. Below is an example of using this command below with a deal on Calibrationnet testnet with a dealID of 707.

yarn hardhat store-all --contract "DEPLOYED FILECOIN_MARKET_CONSUMER CONTRACT ADDRESS HERE" --dealid "707"

Preparing Data for Storage

Before storing a file with a storage provider, it needs to be prepared by turning it into a .car file and the metadata must be recorded. To do this, the hardhat kit has a tool submodule, written in the language Go, which can do this for you. You can also use the FVM Data Depot website will automatically convert files to the .car format, output all the necessary metadata, and act as an HTTP retrieval point for the storage providers.

Client Contract - Making Storage Deals in Solidity

Under contracts, within the basic-deal-client sub-directory, you will find a file called DealClient.sol. This is an example contract that uses the Filecoin.sol API's to create storage deals via Solidity smart contracts on Filecoin. This works by emitting a Solidity event that Boost storage providers can listen to. To learn more about this contract feel free to checkout the app kit repo which includes a detailed readme and a frontend.

Bounty Contract

Under contracts, within the filecoin-api-examples sub-directory, you will find a file called deal-rewarder.sol. This is a basic example contract that uses the Filecoin.sol API's to create bounties for specific data to be stored on the Filecoin blockchain. This is intended to be an example to illustrate how you can use the Filecoin APIs to do some cool functionality. To learn more about this contract feel free to checkout the original Foundry project which includes a detailed readme.