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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.javsphere.com/engineering/smart-contracts/leveragex/javreferrals.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.