Factory

The CoinFactory contract is an upgradeable contract which is the canonical factory for coins.

The contract is upgradable by the freee.fun team to update coin features, but any deployed coins are immutable and cannot be updated.

Overview

The CoinFactory implements the ICoinFactory interface and serves as the entry point for creating new coins in the freee.fun Coins Protocol. It handles the deployment of coin contracts, their associated Uniswap V3 pools, and the initial setup of liquidity.

Key Methods

deploy

function deploy(
    address payoutRecipient,
    address[] memory owners,
    string memory uri,
    string memory name,
    string memory symbol,
    bytes memory poolConfig,
    address platformReferrer,
    uint256 orderSize
) public payable nonReentrant returns (address, uint256);

This function creates a new coin contract with the specified parameters and its associated Uniswap V3 liquidity pool.

While the currency field can be set to any ERC20, only WETH/ETH pairs are supported by our user interface and indexer at this time.

Parameters:

• payoutRecipient: The recipient of creator reward payouts; this can be updated by any owner later on

• owners: An array of addresses that will have permission to manage the coin's payout address and metadata URI. Owners can update the list of approved owners as well.

• uri: The coin metadata URI (should be an IPFS URI). See Metadata for more information.
• name: The name of the coin (e.g., "horse galloping").

• symbol: The trading symbol for the coin (e.g., "HORSE")

• poolConfig: The configuration parameters for the Uniswap V3 pool, encoded as abi.encode(uint8 version, address currency, int24 tickLower, int24 tickUpper, uint16 numDiscoveryPositions, uint256 maxDiscoverySupplyShare)

• platformReferrer: The address of the platform referrer who will receive a portion of trading fees

• orderSize: The order size for the first buy; must match msg.value for ETH/WETH pairs

Returns:

• The address of the deployed coin contract

• The amount of currency used for the initial purchase (if any)

• Note: When creating a coin, the return values are not accessible and the TokenCreated event needs to be parsed from the logs to find the resulting address.

Notes:

• When creating a coin with ETH/WETH, you must send ETH with the transaction equal to the orderSize parameter

• For other currencies, the factory will pull the specified amount from your wallet (requires approval)

• While the currency field in poolConfig can be set to any ERC20, only WETH/ETH pairs are fully supported by the user interface and indexer at this time

Events

TokenCreated

event TokenCreated(
    address indexed caller,
    address indexed payoutRecipient,
    address indexed platformReferrer,
    address currency,
    string uri,
    string name,
    string symbol,
    address coin,
    address pool,
    string version
);

Emitted when a new coin is created through the factory.

Event Parameters:

• caller: The address that called the deploy function

• payoutRecipient: The address of the creator payout recipient

• platformReferrer: The address of the platform referrer

• currency: The address of the trading currency

• uri: The metadata URI of the coin

• name: The name of the coin

• symbol: The symbol of the coin

• coin: The address of the newly created coin contract

• pool: The address of the associated Uniswap V3 pool

• version: The version string of the coin implementation

Error Handling

The factory defines custom errors to provide specific information about failed operations:

• ERC20TransferAmountMismatch: The amount of ERC20 tokens transferred does not match the expected amount

• EthTransferInvalid: ETH is sent with a transaction but the currency is not WETH

Advanced Configuration

Currency Options

When creating a coin, you have two options for the trading currency:

1. ETH/WETH: Use address(0) for the currency parameter. This is the most common option, allowing users to buy and sell coins with ETH.

2. ERC20 Token: Specify the address of an ERC20 token. This creates a coin that trades against that specific token.

Initial Purchase

The orderSize parameter determines the initial purchase amount when creating a coin:

• Setting this to a non-zero value creates initial liquidity in the pool

• For ETH/WETH coins, this amount must be sent with the transaction

• For ERC20 coins, the factory must be approved to spend this amount

Tick Configuration

The tickLower parameter affects the price curve for the Uniswap V3 pool:

• For ETH/WETH pairs, this is ignored and set to a default value

• For other currencies, this can be customized to affect the price range of the liquidity position

Security Considerations

• The factory is the only contract allowed to create official freee.fun protocol coins

• Platform referrer addresses are permanently set at creation and cannot be changed

• Owner addresses have some control over the coin (metadata, payout recipient)

• Initial purchases are processed through Uniswap V3 pools, subject to their slippage and price impact mechanics