API Reference

Complete reference documentation for all TokenOps Airdrop V2 contracts and interfaces.

Overview

The TokenOps Airdrop V2 system consists of several interconnected contracts that provide a comprehensive solution for token distribution using Merkle trees. The architecture is designed for flexibility, security, and gas efficiency.

Contract Architecture

Core Contracts

Base Implementation

• BaseTokenOpsMerkleDistributor
  • Abstract base contract providing core functionality
  • Merkle proof verification and claim tracking
  • Grace period management and access control
  • Foundation for all distributor implementations

Distributor Implementations

• TokenOpsMerkleDistributor

  • ERC20 token distribution with staking integration
  • Supports both gas fees and token fees
  • Claim-and-stake functionality with bonus rewards
  • Comprehensive admin and fee management

• TokenOpsMerkleDistributorNative

  • Native token distribution (ETH, MATIC, etc.)
  • Gas-only fee structure for simplicity
  • Optimized for native token transfers
  • Streamlined administration

Factory Contract

• TokenOpsMerkleDistributorFactory
  • Centralized deployment and configuration
  • Custom fee management per campaign creator
  • Support for both ERC20 and native distributions
  • Standardized distributor creation

Audit Reports

You can find the audit reports for this project here.

Interface Definitions

The TokenOps Airdrop V2 system utilizes several key interfaces to ensure consistency and interoperability:

Core Interfaces

• ITokenOpsMerkleDistributorBase

  • Base interface for all distributors
  • Common functionality across implementations
  • Time management and claim status
  • Access control patterns

• ITokenOpsMerkleDistributor

  • ERC20 distributor interface
  • Staking integration definitions
  • Comprehensive event and error definitions
  • Fee management functions

• ITokenOpsMerkleDistributorNative

  • Native token distributor interface
  • Simplified functionality for native tokens
  • Gas-only fee structure
  • Efficient native token handling

Supporting Interfaces

• ITokenOpsMerkleDistributorFactory

  • Factory contract interface
  • Deployment and configuration functions
  • Custom fee management
  • Event definitions for tracking

• ITokenOpsStaking

  • Staking integration interface
  • Used by ERC20 distributors
  • Fee configuration for staking
  • Direct staking operations

• ITypes

  • Shared type definitions
  • FeeType enumeration
  • Used across all contracts
  • Type safety and consistency

Feature Matrix

Feature	ERC20 Distributor	Native Distributor	Factory
Token Support	ERC20 tokens	Native tokens	Both
Fee Types	Gas or Token fees	Gas fees only	Configurable
Staking Integration	✅ Full support	❌ Not available	✅ Configurable
Claim	✅ Yes	✅ Yes	❌ Not supported
Claim and Stake	✅ Yes	❌ Not available	❌ Not supported
Bonus Rewards	✅ Configurable	❌ Not available	✅ Per deployment
Grace Period	✅ 7-day protection	✅ 7-day protection	✅ All deployments
Custom Fees	❌ Factory controlled	❌ Factory controlled	✅ Per creator
Admin Separation	✅ Owner + Fee Collector	✅ Owner + Fee Collector	✅ Owner + Fee Collector

Quick Reference

Common Operations

Creating a Distributor

// ERC20 distributor
const erc20Distributor = await factory.newMerkleDistributor(
    tokenAddress,
    merkleRoot,
    startTime,
    endTime,
    stakingContract,
    rewardOwner,
    bonusPercentage
);

// Native distributor
const nativeDistributor = await factory.newMerkleDistributorNative(
    merkleRoot,
    startTime,
    endTime,
    { value: totalAmount }
);

Claiming Tokens

// Basic claim
await distributor.claim(index, account, amount, proof, { value: fee });

// Claim and stake (ERC20 only)
await distributor.claimAndStake(index, account, amount, proof, { value: fee });

Admin Operations

// Withdraw remaining tokens
await distributor.withdraw();

// Withdraw fees (fee collector only)
await distributor.withdrawGasFee(recipient, amount);
await distributor.withdrawTokenFee(recipient, amount); // ERC20 only

Security Considerations

Access Control

• Owner Role: Contract deployer, manages withdrawals
• Fee Collector Role: Separate role for fee management
• Role Transfer: Fee collector role can be transferred

Time Management

• Start/End Times: Enforced claim windows
• Grace Period: 7-day protection after first claim
• Expiration Handling: Proper cleanup after campaigns end

Proof Validation

• Merkle Proofs: Cryptographically secure validation
• Single Claims: Each index can only be claimed once
• Tamper Protection: Invalid proofs are rejected

Gas Optimization

Efficient Patterns

• Bitmap Claims: Gas-efficient claim tracking
• Packed Storage: Optimized storage layouts
• Batch Operations: Multiple operations in single transaction
• Native Token Transfers: Direct transfers for native tokens

Error Reference

Common Errors

Error	Contract	Cause	Solution
InvalidProof()	All Distributors	Invalid Merkle proof	Generate correct proof
ClaimWindowFinished()	All Distributors	Past end time	Check timing
InsufficientFee()	All Distributors	Insufficient fee paid	Pay correct amount
NoWithdrawDuringClaim()	All Distributors	Claim period active	Wait for end time
NotEnoughTokens()	ERC20 Distributor	Insufficient balance	Fund contract
StakingNotEnabled()	ERC20 Distributor	Staking not configured	Check staking setup

Deployment Checklist

Pre-Deployment

• Merkle tree generated and validated
• Start and end times configured
• Fee structure determined
• Admin and fee collector addresses set
• Token contracts deployed (if ERC20)

Deployment

• Factory contract deployed
• Distributor contracts created via factory
• Contract verification on block explorer
• Initial funding completed
• Access controls configured

Post-Deployment

• Claims tested with sample proofs
• Event monitoring setup
• Admin functions tested
• Fee collection tested
• Documentation updated