Skip to main content

Disperse Overview

Overview​

The TokenOps Disperse Protocol is a comprehensive smart contract system designed for efficient batch distribution of cryptocurrencies (ETH and ERC20 tokens) to multiple recipients. The protocol features a factory pattern architecture that allows users to deploy custom disperse contracts with tailored fee structures.

🏗️ Architecture​

The protocol consists of three main components:

1. Factory Contract​

  • DisperseFactory - Central deployment and management contract
  • Deploys custom disperse contracts with configurable fees
  • Manages default and custom fee structures
  • Provides access control and fee collection management

2. Disperse Contracts​

3. Shared Libraries​

  • Errors - Centralized error definitions and handling

Audit Reports​

You can find the audit reports for this project here.

🎯 Key Features​

Multi-Asset Support​

  • ETH Dispersion: Batch transfer of Ether to multiple recipients
  • ERC20 Token Dispersion: Batch transfer of any ERC20 token
  • Mixed Operations: Support for both assets in a single deployment

Flexible Fee Structures​

  • Gas-Based Fees: Fixed fee charged in ETH per transaction
  • Token-Based Fees: Percentage-based fees charged in the distributed token
  • Custom Fee Configuration: Per-user custom fee settings
  • Fee Deduction Options: Pay fees on top or deduct from recipient amounts

Advanced Management​

  • Role-Based Access Control: Owner and fee collector role separation
  • Fee Collection: Secure withdrawal mechanisms for accumulated fees
  • Per-Token Accounting: Separate fee tracking for each token type
  • Emergency Controls: Owner-controlled emergency withdrawal functions

📊 Fee Structure Comparison​

FeatureDisperseGasFeeDisperseTokenFee
Fee TypeFixed gas fee (ETH)Percentage-based (tokens)
Payment MethodETH alongside distributionTokens (on top or deducted)
Use CaseETH distributions, gas sponsorshipToken distributions, proportional fees
Fee CalculationgasFee per transaction(amount * feePercentage) / 10000
Minimum FeeSet gas fee amountBased on distributed amounts

🔐 Security Features​

Access Control​

  • Owner Role: Deploy contracts, emergency controls, configuration updates
  • Fee Collector Role: Withdraw accumulated fees, role management
  • Creator Role: Individual contract ownership after deployment

Safety Mechanisms​

  • Address Validation: Zero address protection throughout
  • Array Length Validation: Prevents mismatched recipient/amount arrays
  • Balance Checks: Ensures sufficient funds before operations
  • Safe Transfer: OpenZeppelin SafeERC20 implementation
  • Reentrancy Protection: Secure transfer patterns

Fee Protection​

  • Reserved Fee Tracking: Separate accounting prevents accidental withdrawals
  • Fee Bounds: Maximum fee limits prevent excessive charges
  • Role Separation: Fee collection isolated from owner functions

🔄 Workflow Examples​

Standard Distribution Workflow​

  1. Deploy: Use factory to create disperse contract
  2. Configure: Set custom fees if needed (factory owner)
  3. Prepare: Approve tokens (for token distributions)
  4. Distribute: Call disperse function with recipients and amounts
  5. Collect: Fee collector withdraws accumulated fees

Custom Fee Configuration​

  1. Set Custom Fee: Factory owner configures per-user fees
  2. Deploy Contract: User deploys with custom fee structure
  3. Operate: Contract uses custom fees instead of defaults

🛠️ Contract Interfaces​

Core Interfaces​

  • IDisperseFactory - Factory contract interface
  • IDisperseGasFee - Gas-based disperse interface
  • IDisperseTokenFee - Token-based disperse interface
  • ITypes - Shared type definitions

Events​

All contracts emit comprehensive events for:

  • Distribution operations
  • Fee collection
  • Role changes
  • Configuration updates

⚡ Gas Optimization​

Batch Operations​

  • Single transaction for multiple transfers
  • Reduced gas costs compared to individual transfers
  • Optimized loops with minimal external calls

Storage Optimization​

  • Immutable variables for deployment-time constants
  • Efficient mapping structures for fee tracking
  • Minimal storage updates during operations

📝 Error Handling​

The protocol uses a centralized error library providing:

  • Descriptive Error Messages: Clear failure reasons
  • Standardized Errors: Consistent error handling across contracts
  • Gas Efficient: Custom errors instead of revert strings

🎨 Best Practices​

For Users​

  1. Always validate recipient addresses and amounts before distribution
  2. Use appropriate fee type based on your distribution needs
  3. Monitor gas prices for ETH distributions
  4. Batch operations to minimize transaction costs

For Integrators​

  1. Implement proper error handling for all contract calls
  2. Use events for tracking distribution history
  3. Validate contract addresses before operations
  4. Test with small amounts before large distributions

🔍 Contract Addresses​

Note: Contract addresses will be updated after deployment to respective networks.

ContractNetworkAddress
DisperseFactoryMainnetTBD
DisperseFactoryPolygonTBD
DisperseFactoryArbitrumTBD