Filfox Verifier

A TypeScript CLI tool and Hardhat plugin for verifying smart contracts on Filfox, supporting both Foundry and Hardhat projects. Filfox is the block explorer for Filecoin networks.

Features

✅ Multi-Framework Support: Works with both Foundry and Hardhat projects
✅ Filecoin Networks: Supports Filecoin mainnet (314) and Calibration testnet (314159)
✅ CLI Tool: Command-line interface for Foundry projects
✅ Hardhat Plugin: Easy integration with Hardhat projects via tasks
✅ Automatic Compilation: Uses forge build for Foundry or Hardhat compilation artifacts
✅ Smart Detection: Automatically finds deployment files and extracts verification data
✅ TypeScript: Full type safety and modern async/await API

Installation

As a Global CLI Tool

npm install -g filfox-verifier

In Your Project

npm install filfox-verifier

Usage

CLI Tool (Foundry Projects)

filfox-verifier forge <address> <contract-path> --chain <chainId>

Example:

# Verify contract on Filecoin mainnet
filfox-verifier forge 0xA148538a450f8517563135A5f7c4ee0a9F54f811 src/MyContract.sol:MyContract --chain 314

# Verify contract on Calibration testnet  
filfox-verifier forge 0xA148538a450f8517563135A5f7c4ee0a9F54f811 src/MyContract.sol:MyContract --chain 314159

Options:

• --chain <chainId>: Chain ID (314 for Filecoin mainnet, 314159 for Calibration testnet)
• --root <path>: Project root directory (default: current directory)

Hardhat Plugin

First, import the plugin in your hardhat.config.js or hardhat.config.ts:

// hardhat.config.js
require("filfox-verifier/hardhat");

// or in hardhat.config.ts
import "filfox-verifier/hardhat";

Then run the verification task:

# Verify a deployed contract
npx hardhat verifyfilfox --address 0xYourContractAddress --network filecoin

# For Calibration testnet
npx hardhat verifyfilfox --address 0xYourContractAddress --network calibration

Requirements for Hardhat:

• Contract must be deployed using hardhat-deploy
• Deployment artifacts should be in ./deployments/[network]/ directory
• The tool automatically finds the contract by matching the deployment address

Supported Networks

| Network | Chain ID | Explorer | |---------|----------|----------| | Filecoin Mainnet | 314 | https://filfox.info | | Calibration Testnet | 314159 | https://calibration.filfox.info |

How It Works

For Foundry Projects

1. Project Detection: Detects Foundry projects by looking for foundry.toml
2. Compilation: Uses forge build to compile the target contract
3. Metadata Extraction: Extracts Solidity metadata from compilation artifacts
4. Source Collection: Gathers all source files including dependencies
5. Verification: Submits to Filfox API with proper formatting

For Hardhat Projects

1. Deployment Detection: Finds deployment files in ./deployments/[network]/
2. Artifact Processing: Extracts solc input and metadata from deployment artifacts
3. Source Preparation: Organizes source files for verification
4. Verification: Submits to Filfox API with Hardhat-specific data

Requirements

For Foundry Projects

• Node.js 20+
• Foundry project with foundry.toml
• Forge installed and accessible in PATH

For Hardhat Projects

• Node.js 20+
• Hardhat project
• hardhat-deploy plugin installed and configured
• Contract deployed with deployment artifacts

API Response Handling

The tool handles all Filfox API response codes:

• 0: ✅ Verification successful
• 1: ⚠️ No source file provided
• 2: ⚠️ Contract initCode not found
• 3: ⚠️ Compiler version format incorrect
• 4: ⚠️ Verification failed - bytecode mismatch
• 5: ⚠️ Unsupported language (Solidity only)
• 6: ℹ️ Contract already verified
• 7: ⚠️ Compilation error in source files

Development

# Install dependencies
npm install

# Build TypeScript
npm run build

# Lint code
npm run lint

# Format code
npm run format

Example Output

$ filfox-verifier forge 0xA148538a450f8517563135A5f7c4ee0a9F54f811 src/MyContract.sol:MyContract --chain 314

✔ Loading Foundry project...
✔ Compiling contract and extracting metadata...
✔ Preparing verification request...
✔ Verifying contract on Filfox...

✅ Contract "MyContract" verified successfully!
🔗 View at: https://filfox.info/en/address/0xA148538a450f8517563135A5f7c4ee0a9F54f811