Coin.sol
The Coin
contract is the core contract for the Zora Coins Protocol. It is an non-upgradeable ERC20 contract that allows for the creation of media coins.
Overview
The Coin
contract implements the ICoin
interface, which extends several standard interfaces:
IERC165
: Standard interface detectionIERC721Receiver
: Enables receiving ERC721 tokens (for LP tokens)IERC7572
: Standard for protocol-specific metadata
Each coin is created with a Uniswap V3 liquidity pool, enabling immediate trading functionality.
Key Features
- ERC20 Functionality: Basic token transfers, approvals, and balance tracking
- Trading: Built-in buy and sell functions with Uniswap V3 integration. Allows for owners to trade without approvals on uniswap.
- Reward Distribution: Mechanisms for distributing rewards to creators, referrers, and the protocol
- Metadata Management: Updatable contract metadata via URI
- Multi-Ownership: Support for multiple owners with permission control
Core Functions
Trading
Buy
function buy(
address recipient,
uint256 orderSize,
uint256 minAmountOut,
uint160 sqrtPriceLimitX96,
address tradeReferrer
) external payable returns (uint256, uint256);
This function allows users to buy coins using ETH or the configured trading currency (typically WETH). The buyer sends the currency and receives newly minted coins in return.
Parameters:
recipient
: The address that will receive the purchased coinsorderSize
: The amount of currency to spend (in wei)minAmountOut
: Minimum amount of coins to receive (slippage protection)sqrtPriceLimitX96
: Price limit for the UniswapV3 swap (0 for no limit)tradeReferrer
: Address that receives a portion of the trading fee (optional)
Returns:
- The actual amount of currency spent and coins purchased
Sell
function sell(
address recipient,
uint256 orderSize,
uint256 minAmountOut,
uint160 sqrtPriceLimitX96,
address tradeReferrer
) external returns (uint256, uint256);
This function allows users to sell their coins in exchange for ETH or the configured trading currency. The coins are burned during the sale.
Parameters:
recipient
: The address that will receive the currency proceedsorderSize
: The amount of coins to sellminAmountOut
: Minimum amount of currency to receive (slippage protection)sqrtPriceLimitX96
: Price limit for the UniswapV3 swap (0 for no limit)tradeReferrer
: Address that receives a portion of the trading fee (optional)
Returns:
- The actual amount of coins sold and currency received
Burn
function burn(uint256 amount) external;
Allows users to burn their own tokens, permanently removing them from circulation.
Management Functions
setContractURI
function setContractURI(string memory newURI) external onlyOwner;
Updates the coin's metadata URI. This can only be called by an owner of the coin.
setPayoutRecipient
function setPayoutRecipient(address newPayoutRecipient) external onlyOwner;
Updates the address that receives creator rewards. This can only be called by an owner of the coin.
Query Functions
function tokenURI() external view returns (string memory);
function platformReferrer() external view returns (address);
These functions provide access to key coin information:
tokenURI
: Returns the coin's metadata URIplatformReferrer
: Returns the address of the platform referrer who earns fees from trades
Events
The contract emits various events to track important actions:
CoinBuy
event CoinBuy(
address indexed buyer,
address indexed recipient,
address indexed tradeReferrer,
uint256 coinsPurchased,
address currency,
uint256 amountFee,
uint256 amountSold
);
Emitted when coins are purchased, tracking the buyer, recipient, trade referrer, amount of coins purchased, currency used, fees paid, and total amount spent.
CoinSell
event CoinSell(
address indexed seller,
address indexed recipient,
address indexed tradeReferrer,
uint256 coinsSold,
address currency,
uint256 amountFee,
uint256 amountPurchased
);
Emitted when coins are sold, tracking the seller, recipient, trade referrer, amount of coins sold, currency received, fees paid, and total amount received.
CoinTransfer
event CoinTransfer(
address indexed sender,
address indexed recipient,
uint256 amount,
uint256 senderBalance,
uint256 recipientBalance
);
Emitted on any token transfer, providing detailed information about the transfer including updated balances.
CoinTradeRewards
event CoinTradeRewards(
address indexed payoutRecipient,
address indexed platformReferrer,
address indexed tradeReferrer,
address protocolRewardRecipient,
uint256 creatorReward,
uint256 platformReferrerReward,
uint256 traderReferrerReward,
uint256 protocolReward,
address currency
);
Emitted when trade rewards are distributed, tracking all reward recipients and amounts.
CoinMarketRewards
event CoinMarketRewards(
address indexed payoutRecipient,
address indexed platformReferrer,
address protocolRewardRecipient,
address currency,
MarketRewards marketRewards
);
Emitted when market rewards (from liquidity pool fees) are distributed.
ContractMetadataUpdated
event ContractMetadataUpdated(
address indexed caller,
string newURI,
string name
);
Emitted when the contract metadata URI is updated.
CoinPayoutRecipientUpdated
event CoinPayoutRecipientUpdated(
address indexed caller,
address indexed prevRecipient,
address indexed newRecipient
);
Emitted when the payout recipient is updated.
Error Handling
The contract defines several custom errors that provide specific information about failed operations:
AddressZero
: Operation attempted with a zero addressInsufficientFunds
: Insufficient funds for the operationInsufficientLiquidity
: Insufficient liquidity for a transactionSlippageBoundsExceeded
: Slippage bounds exceeded during a transactionInitialOrderSizeTooLarge
: Initial order size too largeEthAmountMismatch
: ETH value doesn't match the currency amountEthAmountTooSmall
: ETH amount too small for the transactionERC20TransferAmountMismatch
: Unexpected ERC20 transfer amountEthTransferInvalid
: Invalid ETH transferEthTransferFailed
: ETH transfer failedOnlyPool
: Operation only available to the Uniswap poolOnlyWeth
: Operation only available to WETHMarketNotGraduated
: Market hasn't graduated yetMarketAlreadyGraduated
: Market has already graduatedInvalidCurrencyLowerTick
: Invalid tick configurationInvalidWethLowerTick
: Invalid WETH tick configuration