# 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.