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

IFIFv2

  • Purpose: Enhanced crowdfunding project contract with advanced vesting and automatic stage transitions
  • Key Features: Vested fund claiming, enhanced purchase controls, dynamic distributor configuration, automatic timing
  • Location: contracts/src/core/IFIFv2.sol
  • Dependencies: Extends IFIF, Vesting library, enhanced multi-signature validation

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

SignatureNonceManager

  • Purpose: Abstract contract providing signature nonce management to prevent replay attacks
  • Key Features: Independent nonce tracking per signature type and signer, sequential nonce validation, nonce skipping for batch invalidation
  • Location: contracts/src/core/SignatureNonceManager.sol
  • Usage: Inherited by IFIF and IFIFv2 for EIP-712 signature replay attack prevention

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 with nonce support
  • Key Features: Domain separator creation, nonce-aware config digest functions, deterministic address prediction, support for all signature types (Config, NextConfig, FundClaimConfig, DistributorConfig)
  • Location: contracts/src/libs/SignatureHelper.sol
  • Usage: Used across deployment scripts and test files for signature operations with replay attack prevention

Vesting

  • Purpose: Mathematical library for linear time-based asset release calculations
  • Key Features: Linear vesting schedules, period-based claiming, precision handling, edge case management
  • Location: contracts/src/libs/Vesting.sol
  • Usage: Core component of IFIFv2 for fund claiming and token distribution vesting schedules

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
  • Signature Replay Attack Prevention: Nonce-based system prevents reuse of old signatures across all configuration types
  • Nonce Skipping Mechanism: Allows intentional invalidation of multiple pending signatures at once
  • Independent Nonce Tracking: Separate nonce sequences for each signature type (NextConfig, FundClaimConfig, DistributorConfig)
  • Time-based Vesting Security: Linear vesting prevents premature asset claims (IFIFv2)
  • Multi-signature Authorization: Enhanced signature requirements for sensitive operations with nonce validation
  • Automatic Stage Transitions: Eliminates manual timing manipulation (IFIFv2)
  • Purchase Limit Controls: Hard and soft caps prevent abuse and ensure fair distribution
  • Comprehensive Testing: Full test coverage with edge case and security testing including 6 dedicated nonce system tests

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
  • Enhanced IFIFv2 test coverage for vesting mechanisms and automatic transitions
  • 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.