Phrase Trade Storage

Overview

The PhraseTradeStorage contract is a key component in a decentralized marketplace system, managing various financial metrics and balances associated with trades, shares, and fees. It provides mechanisms to store, update, and retrieve data related to market transactions, including fees, rewards, shares, and their distribution among participants. The contract is designed with a strong focus on access control, ensuring that only authorized entities can modify critical data.

Key Roles

• Administrator: Holds exclusive rights to set fees and control critical updates.

• Controller: Authorized to update storage values, except for fees.

• Owner: The contract deployer, with the ability to assign the administrator and controller roles.

Key Functions and Variables

Variables

• adminstrator: The address with exclusive rights to set fees and control key functions.

• controller: The address with the authority to update storage values, except fees.

• protocolFeeDestination: The address where protocol fees are sent.

• protocolFeePercent, nftMintingFee, ownerFeePercent, creatorFeePercent, rewardFeePercent, reflectionFeePercent: Variables representing different fee percentages and minting fees.

• totalRewardsInHand: Tracks the current total rewards held by the protocol.

• ownerFeesCollected, creatorFeesCollected: Mappings to store fees collected by market owners and creators.

• sharesBalance: Tracks the balance of shares for each market.

• creators: Maps market IDs to creator addresses.

• rewardsPayoutsTo, reflectionPayoutsTo: Mappings for tracking rewards and reflection payouts per share.

• reflectionPerShare, rewardsPerShare: Tracks the per-share balance for reflections and rewards.

• sharesSupply: Stores the total shares for each market.

• marketIdByTokenURI: Maps token URI hashes to market IDs.

Modifiers

• onlyController: Restricts access to functions that only the controller can execute.

• onlyAdmin: Restricts access to functions that only the administrator can execute.

• setFeesUptoE18: Ensures that a fee being set does not exceed a maximum value of 1e18.

• setAllFeesUptoE18OnlyByAdmin: Ensures that multiple fees being set do not exceed a maximum value of 1e18 and can only be set by the administrator.

Functions

• Constructor: Initializes the contract by setting the controller and administrator addresses.

• setController(address controller_): Allows the owner to set the controller.

• setAdmin(address adminstrator_): Allows the owner to set the administrator.

• setFeeDestination(address _feeDestination): Allows the administrator to set the protocol fee destination.

• setNftMintingFee(uint256 _fee): Sets the fee for minting NFTs.

• setProtocolFeePercent(uint256 _feePercent): Sets the protocol fee percentage, with a maximum of 1e18.

• setOwnerFeePercent(uint256 _feePercent): Sets the owner fee percentage, with a maximum of 1e18.

• setCreatorFeePercent(uint256 _feePercent): Sets the creator fee percentage, with a maximum of 1e18.

• setRewardFeePercent(uint256 _feePercent): Sets the reward fee percentage, with a maximum of 1e18.

• setReflectionFeePercent(uint256 _feePercent): Sets the reflection fee percentage, with a maximum of 1e18.

• setAllFees: A more efficient way to set all fees in one function call.

• setTotalRewardsInHand(uint256 _amount): Allows the controller to set the total rewards in hand.

• increaseTotalRewardsInHand(uint256 _amount): Allows the controller to increase the total rewards in hand.

• decreaseTotalRewardsInHand(uint256 _amount): Allows the controller to decrease the total rewards in hand, ensuring there are sufficient rewards.

• setCreatorFeesCollected(address _creator, uint256 _amount): Allows the controller to set the fees collected by a creator.

• increaseCreatorFeesCollected(address _creator, uint256 _amount): Increases the fees collected by a creator.

• decreaseCreatorFeesCollected(address _creator, uint256 _amount): Decreases the fees collected by a creator, ensuring there are sufficient fees.

• setSharesBalance(uint256 _marketId, address _shareHolder, uint256 _amount): Sets the share balance for a specific market and shareholder.

• increaseSharesBalance(uint256 _marketId, address _shareHolder, uint256 _amount): Increases the share balance for a specific market and shareholder.

• decreaseSharesBalance(uint256 _marketId, address _shareHolder, uint256 _amount): Decreases the share balance for a specific market and shareholder, ensuring sufficient balance.

• setCreator(uint256 marketId, address _creator): Sets the creator for a specific market.

• setRewardsPayoutsTo(uint256 _marketId, address _shareHolder, uint256 _amount): Sets the rewards payouts for a specific market and shareholder.

• increaseRewardsPayoutsTo(uint256 _marketId, address _shareHolder, uint256 _amount): Increases the rewards payouts for a specific market and shareholder.

• decreaseRewardsPayoutsTo(uint256 _marketId, address _shareHolder, uint256 _amount): Decreases the rewards payouts for a specific market and shareholder, ensuring sufficient payouts.

• setReflectionPayoutsTo(uint256 _marketId, address _shareHolder, uint256 _amount): Sets the reflection payouts for a specific market and shareholder.

• increaseReflectionPayoutsTo(uint256 _marketId, address _shareHolder, uint256 _amount): Increases the reflection payouts for a specific market and shareholder.

• decreaseReflectionPayoutsTo(uint256 _marketId, address _shareHolder, uint256 _amount): Decreases the reflection payouts for a specific market and shareholder, ensuring sufficient payouts.

• setReflectionPerShare(uint256 _marketId, uint256 _amount): Sets the reflection per share for a specific market.

• increaseReflectionPerShare(uint256 _marketId, uint256 _amount): Increases the reflection per share for a specific market.

• decreaseReflectionPerShare(uint256 _marketId, uint256 _amount): Decreases the reflection per share for a specific market, ensuring sufficient reflection.

• setRewardsPerShare(uint256 _marketId, uint256 _amount): Sets the rewards per share for a specific market.

• increaseRewardsPerShare(uint256 _marketId, uint256 _amount): Increases the rewards per share for a specific market.

• decreaseRewardsPerShare(uint256 _marketId, uint256 _amount): Decreases the rewards per share for a specific market, ensuring sufficient rewards.

• setSharesSupply(uint256 _marketId, uint256 _amount): Sets the total shares supply for a specific market.

• increaseSharesSupply(uint256 _marketId, uint256 _amount): Increases the total shares supply for a specific market.

• decreaseSharesSupply(uint256 _marketId, uint256 _amount): Decreases the total shares supply for a specific market, ensuring sufficient supply.

• setOwnerFeesCollected(address _owner, uint256 _amount): Sets the fees collected by an owner.

• increaseOwnerFeesCollected(address _owner, uint256 _amount): Increases the fees collected by an owner.

• decreaseOwnerFeesCollected(address _owner, uint256 _amount): Decreases the fees collected by an owner, ensuring sufficient fees.

• setMarketIdByTokenURI(bytes32 _tokenURIHash, uint256 _marketId): Maps a token URI hash to a market ID.

Usage Examples

• Setting Fees: The administrator can efficiently set multiple fees at once using the setAllFees function. For example, if the protocol fee is 2%, the administrator would call setAllFees(0.02 * 1e18, ...).

• Managing Rewards: The controller can manage rewards in hand using the increaseTotalRewardsInHand and decreaseTotalRewardsInHand functions, ensuring proper allocation to market participants.

Security Considerations

• Access Control: Critical functions are protected by onlyAdmin, onlyController, and other access modifiers to prevent unauthorized changes.

• Reentrancy Protection: The nonReentrant modifier is used in functions that modify state and transfer funds to protect against reentrancy attacks.

• Fee Limits: The contract enforces a maximum fee of 1e18 to prevent excessive fee settings.

Gas Optimization

• Efficient Updates: The setAllFees function is designed to set multiple fees in a single transaction, reducing gas costs compared to setting each fee individually.

• Unchecked Arithmetic: Where safe, the contract uses unchecked arithmetic (e.g., unchecked { totalRewardsInHand += _amount; }) to save gas by skipping overflow checks.

Best Practices

• Address Validation: Ensure that addresses provided for key roles (controller, administrator, protocol fee destination) are valid and trusted, as these roles have significant control over the contract's functionality.

• Regular Audits: Regularly audit the contract for security vulnerabilities, especially focusing on access control and reentrancy protection mechanisms.

This documentation provides a comprehensive guide for developers interacting with the PhraseTradeStorage contract, ensuring they can do so effectively and securely.