Skip to content

Smart Contracts

The ifif protocol consists of a modular set of smart contracts designed for secure and efficient operation. All contracts are built using Solidity 0.8.19 and leverage OpenZeppelin's battle-tested libraries for security and standardization.

Contract Architecture

Core Contracts

The protocol's core functionality is implemented through the following contracts:

IFIF

  • Purpose: Main crowdfunding project contract with multi-stage sale system
  • Key Features: ERC721 allocation NFTs, whitelist integration, funding token support, token distribution
  • Location: contracts/src/core/IFIF.sol
  • Dependencies: Solady libraries, OpenZeppelin standards, custom interfaces

IFIFFactory

  • Purpose: Factory contract for deploying and managing IFIF projects
  • Key Features: Clone-based deployment, implementation management, shared resources, token deployment
  • Location: contracts/src/utils/IFIFFactory.sol
  • Dependencies: LibClone, Role-based access control, IFIF/token implementations

Roles

  • Purpose: Three-tier role-based access control system
  • Key Features: Hierarchical permissions (Admin → Manager → Distributor), secure ownership transfer, admin role protection
  • Location: contracts/src/core/Roles.sol
  • Dependencies: OpenZeppelin AccessControl, Ownable2Step

Whitelist

  • Purpose: Merkle tree-based whitelist system with multiple sections
  • Key Features: Gas-efficient verification, batch operations, role-based management, UUPS upgradeable
  • Location: contracts/src/core/Whitelist.sol
  • Dependencies: Solady MerkleProofLib, UUPS, Role contract integration

Utility Contracts

IFIFToken

  • Purpose: ERC20 token implementation for successful IFIF projects
  • Key Features: Mintable by project contract, standard ERC20 functionality, project-specific metadata
  • Location: contracts/src/utils/IFIFToken.sol
  • Usage: Deployed automatically by factory for successful projects

Calculations

  • Purpose: Mathematical operations library for fee calculations, token distributions, and earnings
  • Key Features: Fee distribution calculations, token supply calculations with proportional buffers, user weight calculations with bonus applications, scaled arithmetic for precision preservation
  • Location: contracts/src/libs/Calculations.sol
  • Usage: Core mathematical functions used by IFIF contracts for all financial calculations and token distributions

SignatureHelper

  • Purpose: Centralized library for EIP-712 signature creation and verification
  • Key Features: Domain separator creation, config digest functions, deterministic address prediction
  • Location: contracts/src/libs/SignatureHelper.sol
  • Usage: Used across deployment scripts and test files for signature operations

Role (Abstract)

  • Purpose: Base contract providing role-based access control integration
  • Key Features: Modifier functions, role validation, role helper management
  • Location: contracts/src/utils/Role.sol
  • Usage: Inherited by contracts requiring role-based permissions

Helper (Library)

  • Purpose: Utility functions and constants for the protocol
  • Key Features: Role constants, validation functions, custom errors
  • Location: contracts/src/libs/Helper.sol
  • Usage: Imported by contracts needing common utilities

Security Features

All contracts implement multiple layers of security:

  • Role-based Access Control: Fine-grained permissions using OpenZeppelin's AccessControl
  • Two-step Ownership Transfer: Prevents accidental ownership loss using Ownable2Step
  • Ownership Renunciation Protection: Critical roles cannot be accidentally renounced
  • UUPS Upgradeable Pattern: Secure contract upgrades with admin-only authorization
  • Merkle Tree Verification: Cryptographically secure whitelist verification
  • Input Validation: Comprehensive validation of all function inputs
  • Custom Errors: Gas-efficient error reporting with descriptive messages
  • Comprehensive Testing: Full test coverage with edge case and security testing

Development Standards

Code Quality

  • NatSpec documentation for all public interfaces
  • Comprehensive unit tests with 100% coverage for core contracts
  • Security-focused development practices
  • Gas optimization with efficient algorithms and libraries
  • Modular architecture with reusable components
  • Custom errors for gas-efficient error handling

Testing Framework

  • Built with Foundry for fast, reliable testing
  • Unit tests for all contract functions
  • Integration tests for cross-contract interactions
  • Security tests for access control and edge cases
  • 100% test coverage for Whitelist and Roles contracts
  • Comprehensive test suites following established patterns

Deployment

Contracts are designed for deployment on multiple EVM-compatible networks with consistent addresses across chains where possible.

Verification

All deployed contracts include:

  • Source code verification on block explorers
  • Comprehensive deployment documentation
  • Post-deployment validation tests

Getting Started

To interact with the contracts:

  1. Development: Clone the repository and run pnpm install
  2. Testing: Run pnpm contracts:test for the full test suite
  3. Deployment: Use the provided deployment scripts in contracts/script/

For detailed information about specific contracts, see their individual documentation pages.