Phrase Trade Main

Overview

PhraseTradeMain is a smart contract designed to facilitate the trading of NFTs and their associated shares on the Ethereum blockchain. The contract manages the creation and trading of markets based on NFTs, calculates fees, handles dividend distributions, and ensures secure and transparent operations. It relies on other contracts such as Ownable, ReentrancyGuard, PhraseTradeStorage, PhraseTradeNFT, IPhraseTradeMain, and PhraseTradeEIP712 for additional functionality and security.

Table of Contents

  1. Contract State Variables

  2. Modifiers

  3. Constructor

  4. Public and External Functions

    • Setters

    • Fees Calculation Functions

    • Dividend and Rewards Functions

    • Buy and Sell Shares

    • NFT Minting and Market Creation

    • Signature Verification

  5. Fallback and Receive Functions

  6. Events

Contract State Variables

  • PhraseTradeStorage _storage: A reference to the PhraseTradeStorage contract, which handles the storage of market data, including shares and fees.

  • PhraseTradeNFT _nft: A reference to the PhraseTradeNFT contract, which manages the minting and ownership of NFTs.

  • PhraseTradeEIP712 _eip712: A reference to the PhraseTradeEIP712 contract, which handles EIP712-compliant message hashing and signature verification.

  • uint256 public constant E18 = 10 ** 18: A constant representing (10^{18}), typically used for handling token amounts with 18 decimal places (e.g., ETH or ERC-20 tokens).

  • uint256 public constant POWER = 64: A constant used for shifting operations in fee and dividend calculations.

  • address public controller: The address of the controller, who has specific administrative rights over the contract.

Modifiers

  • onlyController(): Ensures that only the controller address can call the function.

  • notZeroAddress(address _address): Ensures that the provided address is not the zero address (0x0).

Constructor

constructor(
    address _phraseTradeStorageAddress,
    address _nftAddress,
    address _controller,
    address _eip712Address
)

Initializes the contract with the addresses of the storage contract, NFT contract, controller, and EIP712 contract.

  • Parameters:

    • _phraseTradeStorageAddress: Address of the PhraseTradeStorage contract.

    • _nftAddress: Address of the PhraseTradeNFT contract.

    • _controller: Address of the controller.

    • _eip712Address: Address of the PhraseTradeEIP712 contract.

Public and External Functions

Setters

  1. setController(address controller_)

    • Description: Sets the controller address.

    • Modifiers: notZeroAddress(controller_), onlyOwner

    • Parameters: controller_: The new controller address.

  2. setPhraseTradeNFTAddress(address _nftAddress)

    • Description: Sets the address of the PhraseTradeNFT contract.

    • Modifiers: notZeroAddress(_nftAddress), onlyController

    • Parameters: _nftAddress: The new NFT contract address.

  3. setPhraseTradeStorageAddress(address _phraseTradeStorageAddress)

    • Description: Sets the address of the PhraseTradeStorage contract.

    • Modifiers: notZeroAddress(_phraseTradeStorageAddress), onlyController

    • Parameters: _phraseTradeStorageAddress: The new storage contract address.

Fees Calculation Functions

  1. calculateFees(uint256 price)

    • Description: Calculates various fees based on the provided price.

    • Returns: A Fees struct containing protocolFee, ownerFee, creatorFee, rewardFee, and reflectionFee.

  2. getPrice(uint256 supply, uint256 qty)

    • Description: Returns the price of a share using a cubic function based on the total supply and quantity of shares.

    • Returns: The calculated price.

  3. getBuyPrice(uint256 marketId, uint256 qty)

    • Description: Returns the price for buying shares in a given market.

    • Returns: The calculated price in wei.

  4. getSellPrice(uint256 marketId, uint256 qty)

    • Description: Returns the price for selling shares in a given market.

    • Returns: The calculated price in wei.

  5. getBuyPriceAfterFee(uint256 marketId, uint256 qty)

    • Description: Returns the price for buying shares after applying all fees.

    • Returns: The final price in wei.

  6. getSellPriceAfterFee(uint256 marketId, uint256 qty)

    • Description: Returns the price for selling shares after applying all fees.

    • Returns: The final price in wei.

Dividend and Rewards Functions

  1. calculateDividendInfo(uint256 marketId, address user, uint256 qty)

    • Description: Calculates the dividends earned by a user and returns detailed information in a DividendInfo struct.

  2. checkEarnedRewards(uint256 marketId, address shareHolder)

    • Description: Checks the rewards earned by a shareholder in a given market.

    • Returns: The total rewards collected.

  3. offerRewards(uint256 marketId, uint256 amount)

    • Description: Offers rewards to the market, allowing shareholders to claim rewards proportional to their shares.

    • Modifiers: onlyController

    • Parameters: marketId: The market ID; amount: The amount of rewards to offer.

  4. claimOwnerFees(address beneficiary)

    • Description: Claims fees collected by the market owner.

    • Modifiers: nonReentrant, notZeroAddress(beneficiary)

  5. claimCreatorFees(address beneficiary)

    • Description: Claims fees collected by the NFT creator.

    • Modifiers: nonReentrant, notZeroAddress(beneficiary)

  6. claimRewards(uint256 marketId, address beneficiary)

    • Description: Claims rewards earned by the user in a given market.

    • Modifiers: nonReentrant, notZeroAddress(beneficiary)

  7. dividendsOf(uint256 marketId, address shareHolder)

    • Description: Retrieves the dividend balance of a market for a given shareholder.

    • Returns: The profit owed to the shareholder.

  8. claimReflectionFees(uint256 marketId, address beneficiary)

    • Description: Claims reflection fees (dividends) for the specified market and beneficiary.

    • Modifiers: nonReentrant, notZeroAddress(beneficiary)

Buy and Sell Shares

  1. buyShares(uint256 marketId, uint256 qty)

    • Description: Buys shares of a market, handling the first share allocation to the NFT creator.

    • Modifiers: nonReentrant

    • Parameters: marketId: The market ID; qty: The quantity of shares to buy.

  2. sellShares(uint256 marketId, uint256 qty, uint256 minExpectedPrice)

    • Description: Sells shares of a market, ensuring the price meets the minimum expected value.

    • Modifiers: nonReentrant

    • Parameters: marketId: The market ID; qty: The quantity of shares to sell; minExpectedPrice: The minimum acceptable price.

NFT Minting and Market Creation

  1. _mintNFTandCreateMarket(string memory tokenURI)

    • Description: Mints a new NFT and creates a market for it.

    • Internal Function

    • Returns: The market ID (NFT token ID).

  2. verifyAndMint(string memory tokenURI, uint256 tillTimestamp, bytes memory signature)

    • Description: Verifies the caller's signature and mints a new NFT.

    • Returns: The market ID (NFT token ID).

    • Parameters: tokenURI: The URI of the token; tillTimestamp: The validity of the signature; signature: The EIP712 signature.

Signature Verification

  1. verifySignature(string memory tokenURI, uint256 tillTimestamp, address creator, bytes memory signature, address expectedSigner)

    • Description: Verifies the validity of a signature using EIP712.

    • Returns: true if the signature is valid, false otherwise.

    • Parameters: tokenURI: The URI of the token; tillTimestamp: The timestamp until which the signature is valid:

      • creator: The address of the creator.

      • signature: The signature to verify.

      • expectedSigner: The address expected to have signed the message.

Fallback and Receive Functions

  1. receive() external payable

    • Description: This function is triggered when the contract receives plain Ether transfers. The contract reverts the transaction with a custom error message to indicate that plain ETH transfers are not accepted.

  2. fallback() external payable

    • Description: This function is triggered when a function call does not match any of the existing functions and carries data. The contract reverts the transaction, indicating that the called function is not supported.

Events

Events are emitted during the execution of key functions to provide transparency and a history of actions. Here are the primary events defined in the contract:

  1. event BuyShare(uint256 marketId, address indexed buyer, uint256 qty, uint256 newSupply, uint256 price, uint256 protocolFee, uint256 ownerFee, uint256 creatorFee, uint256 rewardFee, uint256 reflectionFee)

    • Description: Emitted when shares of a market are purchased.

    • Parameters:

      • marketId: The ID of the market (NFT token ID).

      • buyer: The address of the buyer.

      • qty: The quantity of shares purchased.

      • newSupply: The new total supply of shares in the market.

      • price: The total price paid for the shares.

      • protocolFee: The fee collected by the protocol.

      • ownerFee: The fee collected by the owner.

      • creatorFee: The fee collected by the creator.

      • rewardFee: The fee allocated for rewards.

      • reflectionFee: The fee allocated for reflections.

  2. event SellShare(uint256 marketId, address indexed seller, uint256 qty, uint256 newSupply, uint256 priceReceived, uint256 dividendEarned, uint256 unclaimedReward, uint256 protocolFee, uint256 ownerFee, uint256 creatorFee, uint256 rewardFee, uint256 reflectionFee)

    • Description: Emitted when shares of a market are sold.

    • Parameters:

      • marketId: The ID of the market (NFT token ID).

      • seller: The address of the seller.

      • qty: The quantity of shares sold.

      • newSupply: The new total supply of shares in the market.

      • priceReceived: The amount received by the seller.

      • dividendEarned: The dividend earned by the seller.

      • unclaimedReward: The reward earned but not yet claimed.

      • protocolFee: The fee collected by the protocol.

      • ownerFee: The fee collected by the owner.

      • creatorFee: The fee collected by the creator.

      • rewardFee: The fee allocated for rewards.

      • reflectionFee: The fee allocated for reflections.

  3. event BonusAdded(uint256 amount, uint256 marketId)

    • Description: Emitted when additional rewards are added to the market.

    • Parameters:

      • amount: The amount of bonus added (in wei).

      • marketId: The ID of the market (NFT token ID).

  4. event RewardsOffered(uint256 marketId, uint256 amount, uint256 totalRewardsInHand)

    • Description: Emitted when rewards are offered to a market.

    • Parameters:

      • marketId: The ID of the market (NFT token ID).

      • amount: The amount of rewards offered.

      • totalRewardsInHand: The total rewards in hand after offering.

  5. event ClaimedOwnerFee(address indexed beneficiary, uint256 amount, address indexed claimer)

    • Description: Emitted when owner fees are claimed.

    • Parameters:

      • beneficiary: The address receiving the claimed fees.

      • amount: The amount of fees claimed.

      • claimer: The address that claimed the fees.

  6. event ClaimedCreatorFee(address indexed beneficiary, uint256 amount, address indexed claimer)

    • Description: Emitted when creator fees are claimed.

    • Parameters:

      • beneficiary: The address receiving the claimed fees.

      • amount: The amount of fees claimed.

      • claimer: The address that claimed the fees.

  7. event ClaimedReward(uint256 marketId, address indexed beneficiary, uint256 amount, address indexed claimer)

    • Description: Emitted when rewards are claimed.

    • Parameters:

      • marketId: The ID of the market (NFT token ID).

      • beneficiary: The address receiving the claimed rewards.

      • amount: The amount of rewards claimed.

      • claimer: The address that claimed the rewards.

  8. event ClaimedReflectionFee(uint256 marketId, address indexed beneficiary, uint256 amount, address indexed claimer)

    • Description: Emitted when reflection fees (dividends) are claimed.

    • Parameters:

      • marketId: The ID of the market (NFT token ID).

      • beneficiary: The address receiving the claimed reflection fees.

      • amount: The amount of reflection fees claimed.

      • claimer: The address that claimed the reflection fees.

Summary

The PhraseTradeMain contract is a comprehensive solution for managing the creation, buying, and selling of NFTs and their associated shares. It incorporates multiple layers of fee calculations, rewards distribution, and dividend management to ensure fair and transparent trading within the ecosystem. The contract also emphasizes security and correct usage through the use of various modifiers, such as onlyController, notZeroAddress, and nonReentrant.

The contract is designed to work in conjunction with other contracts like PhraseTradeStorage, PhraseTradeNFT, and PhraseTradeEIP712, each of which provides specific functionality to support the overall trading system. The various events emitted during key operations provide transparency and traceability of actions within the contract.

PreviousPhrase Trade EIP712NextPhrase Trade NFT

Last updated