Skip to main content

DisperseFactory Documentation

Overview​

The DisperseFactory is the central deployment and management contract for the TokenOps Disperse Protocol. It provides a factory pattern implementation that allows users to deploy custom disperse contracts with tailored fee structures, while maintaining centralized control over default fees and fee collection.

Key Features:

  • Factory Pattern: Deploy multiple disperse contracts with custom configurations
  • Fee Management: Configure default and custom fees for different users
  • Access Control: Owner-controlled settings with fee collector role separation
  • Event Tracking: Complete audit trail of all deployments and configuration changes

Contract Details​

License: BUSL-1.1 Solidity Version: 0.8.28

Inheritance​

  • IDisperseFactory - Standard factory interface
  • Ownable - OpenZeppelin access control

Dependencies​

  • DisperseGasFee - Gas-based fee disperse contract
  • DisperseTokenFee - Token-based fee disperse contract
  • Errors - Centralized error library

Architecture​

Constants​

uint256 public constant BASIS_POINTS = 10000;

State Variables​

Public Variables​

address public feeCollector;
uint256 public defaultGasFee;
uint256 public defaultTokenFee;
ITypes.FeeType public defaultFeeType;

Private Variables​

mapping(address campaignCreator => CustomFee customFee) private _customFees;

Fee Structure​

The factory manages two types of fees:

Default Fees​

Applied to all new disperse contracts unless overridden:

uint256 public defaultGasFee;    // Fixed fee per recipient in wei
uint256 public defaultTokenFee;  // Percentage fee in basis points (max 10000)

Custom Fees​

User-specific fee overrides:

struct CustomFee {
    bool enabled;                    // Whether custom fees are active
    ITypes.FeeType preferredFeeType; // Preferred fee type for this user
    uint256 gasFee;                  // Custom gas fee per recipient
    uint256 tokenFee;                // Custom token fee in basis points
}

Deployment​

Constructor​

constructor(
    address feeCollector_,
    uint256 defaultGasFee_,
    uint256 defaultTokenFee_
)

Parameters:

  • feeCollector_: Address that will collect fees (cannot be zero)
  • defaultGasFee_: Default gas fee per recipient in wei
  • defaultTokenFee_: Default token fee in basis points (max 10000)

Requirements:

  • feeCollector_ cannot be zero address
  • defaultTokenFee_ cannot exceed 10000 basis points

⚠️ Important:

  • The deployer becomes the owner with full administrative privileges
  • Fee collector cannot be zero address
  • Token fee cannot exceed 10000 basis points (100%)

Core Functions​

Factory Functions​

newDisperseGasFee()​

Deploy a new gas-based fee disperse contract.

function newDisperseGasFee() external returns (address)

Returns: Address of the deployed DisperseGasFee contract

Events Emitted: DisperseGasFeeCreated

newDisperseTokenFee()​

Deploy a new token-based fee disperse contract.

function newDisperseTokenFee() external returns (address)

Returns: Address of the deployed DisperseTokenFee contract

Events Emitted: DisperseTokenFeeCreated

Configuration Functions​

setFeeCollector(address)​

function setFeeCollector(address newFeeCollector) external onlyOwner

Updates the fee collector address.

Parameters:

  • newFeeCollector: New fee collector address (cannot be zero)

Access: Owner only

Events Emitted: FeeCollectorSet

setDefaultGasFee(uint256)​

function setDefaultGasFee(uint256 newGasFee) external onlyOwner

Updates the default gas fee for new deployments.

Parameters:

  • newGasFee: New default gas fee per recipient in wei

Access: Owner only

Events Emitted: SetDefaultGasFee

setDefaultTokenFee(uint256)​

function setDefaultTokenFee(uint256 newTokenFee) external onlyOwner

Updates the default token fee for new deployments.

Parameters:

  • newTokenFee: New default token fee in basis points (max 10000)

Requirements:

  • newTokenFee cannot exceed 10000 basis points

Access: Owner only

Events Emitted: SetDefaultTokenFee

setDefaultFeeType(ITypes.FeeType)​

function setDefaultFeeType(ITypes.FeeType feeType) external onlyOwner

Sets the default fee type for new deployments.

Parameters:

  • feeType: Fee type (Gas or DistributionToken)

Access: Owner only

Events Emitted: ChangeDefaultFeeType

setCustomFee(address, ITypes.FeeType, uint256, uint256)​

function setCustomFee(
    address campaignCreator,
    ITypes.FeeType feeType,
    uint256 gasFee,
    uint256 tokenFee
) external onlyOwner

Sets custom fees for a specific user.

Parameters:

  • campaignCreator: Address to set custom fees for (cannot be zero)
  • feeType: Preferred fee type for this user
  • gasFee: Custom gas fee per recipient in wei
  • tokenFee: Custom token fee in basis points (max 10000)

Requirements:

  • campaignCreator cannot be zero address
  • tokenFee cannot exceed 10000 basis points

Access: Owner only

Events Emitted: SetCustomFee

disableCustomFee(address)​

function disableCustomFee(address campaignCreator) external onlyOwner

Disables custom fees for a specific user.

Parameters:

  • campaignCreator: Address to disable custom fees for

Requirements:

  • Custom fees must be currently enabled for the user

Access: Owner only

Events Emitted: SetCustomFee (with enabled=false)

View Functions​

getCustomFee(address)​

function getCustomFee(address campaignCreator)
    external view returns (CustomFee memory)

Retrieves custom fee configuration for a user.

Parameters:

  • campaignCreator: Address to query

Returns: CustomFee struct with user's configuration

Events​

Deployment Events​

DisperseGasFeeCreated​

event DisperseGasFeeCreated(
    address indexed disperse,
    ITypes.FeeType feeType,
    uint256 gasFee,
    address feeCollector,
    address creator
);

Emitted when a new gas-fee disperse contract is deployed.

Parameters:

  • disperse: Address of the deployed contract
  • feeType: Always ITypes.FeeType.Gas
  • gasFee: Fee per recipient in wei
  • feeCollector: Fee collector address
  • creator: Address that deployed the contract

DisperseTokenFeeCreated​

event DisperseTokenFeeCreated(
    address indexed disperse,
    ITypes.FeeType feeType,
    uint256 tokenFee,
    address feeCollector,
    address creator
);

Emitted when a new token-fee disperse contract is deployed.

Parameters:

  • disperse: Address of the deployed contract
  • feeType: Always ITypes.FeeType.DistributionToken
  • tokenFee: Fee percentage in basis points
  • feeCollector: Fee collector address
  • creator: Address that deployed the contract

Configuration Events​

FeeCollectorSet​

event FeeCollectorSet(address admin, address indexed newFeeCollector);

SetDefaultGasFee​

event SetDefaultGasFee(address admin, uint256 oldGasFee, uint256 newGasFee);

SetDefaultTokenFee​

event SetDefaultTokenFee(address admin, uint256 oldTokenFee, uint256 newTokenFee);

ChangeDefaultFeeType​

event ChangeDefaultFeeType(address admin, ITypes.FeeType newFeeType);

SetCustomFee​

event SetCustomFee(
    address admin,
    bool enabled,
    address indexed campaignCreator,
    ITypes.FeeType feeType,
    uint256 gasFee,
    uint256 tokenFee
);

Error Handling​

Common Errors​

InvalidAddress()​

Description: Zero address provided Common Causes:

  • Zero address in constructor parameters
  • Zero address for fee collector
  • Zero address for campaign creator

FeeTooHigh()​

Description: Fee percentage exceeds 100% Common Causes:

  • Token fee > 10000 basis points
  • Invalid fee configuration

CustomFeeNotSet()​

Description: Custom fee not configured Common Causes:

  • Trying to disable non-existent custom fee
  • Querying unconfigured custom fee

Security Considerations​

🔒 Security Notes:

  • Owner Role: Has complete control over factory settings
  • Fee Collector: Can only collect fees from deployed contracts
  • Custom Fees: Owner can set any fee structure for users
  • Fee Limits: Token fees capped at 100% (10000 basis points)

Access Control​

  • Owner Functions: All configuration and custom fee management
  • Public Functions: Only deployment functions
  • No Upgradability: Factory is immutable once deployed

Next Steps​