# JavReferrals

## General Description

The **JavReferrals** contract used for manage a referral system, which incentivizes trading activities through rewards for allies (partners) and referrers. It supports the configuration of fees, reward structures, and ally/referrer whitelisting, while also enabling the distribution and claiming of rewards. Additionally, it provides getter functions to fetch detailed referral-related data.

## Core Functionalities

### **`initializeReferrals`**

* Initializes the referral system with specified parameters.
* **Parameters**:
  * `_allyFeeP`: Fee percentage for allies.
  * `_startReferrerFeeP`: Initial fee percentage for referrers.
  * `_openFeeP`: Fee percentage for open trades.
  * `_targetVolumeUsd`: Target trading volume in USD for additional benefits.
* **Access Control**: `reinitializer(2)`.

### **`updateAllyFeeP`**

* Updates the ally fee percentage.
* **Parameters**:
  * `_value`: New ally fee percentage.
* **Access Control**: `onlyRole(Role.GOV)`.

### **`updateStartReferrerFeeP`**

* Updates the initial referrer fee percentage.
* **Parameters**:
  * `_value`: New initial referrer fee percentage.
* **Access Control**: `onlyRole(Role.GOV)`.

### **`updateReferralsOpenFeeP`**

* Updates the open fee percentage for referrals.
* **Parameters**:
  * `_value`: New open fee percentage.
* **Access Control**: `onlyRole(Role.GOV)`.

### **`updateReferralsTargetVolumeUsd`**

* Updates the target trading volume in USD.
* **Parameters**:
  * `_value`: New target volume in USD.
* **Access Control**: `onlyRole(Role.GOV)`.

### **`whitelistAllies`**

* Adds allies to the whitelist, enabling them to participate in the referral program.
* **Parameters**:
  * `_allies`: Array of ally addresses to whitelist.
* **Access Control**: `onlyRole(Role.GOV)`.

### **`unwhitelistAllies`**

* Removes allies from the whitelist.
* **Parameters**:
  * `_allies`: Array of ally addresses to remove from the whitelist.
* **Access Control**: `onlyRole(Role.GOV)`.

### **`whitelistReferrers`**

* Adds referrers to the whitelist and associates them with specific allies.
* **Parameters**:
  * `_referrers`: Array of referrer addresses.
  * `_allies`: Array of ally addresses corresponding to the referrers.
* **Access Control**: `onlyRole(Role.GOV)`.

### **`unwhitelistReferrers`**

* Removes referrers from the whitelist.
* **Parameters**:
  * `_referrers`: Array of referrer addresses to remove.
* **Access Control**: `onlyRole(Role.GOV)`.

### **`registerPotentialReferrer`**

* Links a trader with a potential referrer.
* **Parameters**:
  * `_trader`: Address of the trader.
  * `_referrer`: Address of the potential referrer.
* **Access Control**: `onlySelf`.

### **`distributeReferralReward`**

* Distributes rewards based on a trader's activity and trading volume.
* **Parameters**:
  * `_trader`: Address of the trader.
  * `_volumeUsd`: Trading volume in USD.
  * `_pairOpenFeeP`: Open fee percentage for the pair.
  * `_javPriceUsd`: Price of JAV token in USD.
* **Returns**: Amount of reward distributed.
* **Access Control**: `onlySelf`.

### **`claimAllyRewards`**

* Allows allies to claim their accrued rewards.
* **Access Control**: Public.

### **`claimReferrerRewards`**

* Allows referrers to claim their accrued rewards.
* **Access Control**: Public.

### **`getReferrerFeeP`**

* Retrieves the referrer fee percentage based on trading volume.
* **Parameters**:
  * `_pairOpenFeeP`: Open fee percentage for the pair.
  * `_volumeReferredUsd`: Trading volume referred in USD.
* **Returns**: Referrer fee percentage.

### **`getTraderLastReferrer`**

* Retrieves the last referrer associated with a trader.
* **Parameters**:
  * `_trader`: Address of the trader.
* **Returns**: Address of the last referrer.

### **`getTraderActiveReferrer`**

* Retrieves the currently active referrer for a trader.
* **Parameters**:
  * `_trader`: Address of the trader.
* **Returns**: Address of the active referrer.

### **`getReferrersReferred`**

* Retrieves all referrers associated with a specific ally.
* **Parameters**:
  * `_ally`: Address of the ally.
* **Returns**: Array of referrer addresses.

### **`getTradersReferred`**

* Retrieves all traders referred by a specific referrer.
* **Parameters**:
  * `_referrer`: Address of the referrer.
* **Returns**: Array of trader addresses.

### **`getReferralsAllyFeeP`**

* Retrieves the current ally fee percentage.
* **Returns**: Ally fee percentage.

### **`getReferralsStartReferrerFeeP`**

* Retrieves the current starting referrer fee percentage.
* **Returns**: Starting referrer fee percentage.

### **`getReferralsOpenFeeP`**

* Retrieves the current open fee percentage for referrals.
* **Returns**: Open fee percentage.

### **`getReferralsTargetVolumeUsd`**

* Retrieves the current target trading volume in USD.
* **Returns**: Target volume in USD.

### **`getAllyDetails`**

* Retrieves detailed information about a specific ally.
* **Parameters**:
  * `_ally`: Address of the ally.
* **Returns**: `AllyDetails` structure containing ally information.

### **`getReferrerDetails`**

* Retrieves detailed information about a specific referrer.
* **Parameters**:
  * `_referrer`: Address of the referrer.
* **Returns**: `ReferrerDetails` structure containing referrer information.