# IReferralsUtils

*Interface for GNSReferrals facet (inherits types and also contains functions, events, and custom errors)*

## initializeReferrals

```solidity
function initializeReferrals(uint256 _allyFeeP, uint256 _startReferrerFeeP, uint256 _targetVolumeUsd) external
```

### Parameters

| Name                | Type    | Description                                                      |
| ------------------- | ------- | ---------------------------------------------------------------- |
| \_allyFeeP          | uint256 | % of total referral fee going to ally                            |
| \_startReferrerFeeP | uint256 | initial % of total referral fee earned when zero volume referred |
| \_targetVolumeUsd   | uint256 | usd opening volume to refer to reach 100% of referral fee        |

## updateAllyFeeP

```solidity
function updateAllyFeeP(uint256 _value) external
```

*Updates allyFeeP*

### Parameters

| Name    | Type    | Description    |
| ------- | ------- | -------------- |
| \_value | uint256 | new ally fee % |

## updateStartReferrerFeeP

```solidity
function updateStartReferrerFeeP(uint256 _value) external
```

*Updates startReferrerFeeP*

### Parameters

| Name    | Type    | Description              |
| ------- | ------- | ------------------------ |
| \_value | uint256 | new start referrer fee % |

## updateReferralsTargetVolumeUsd

```solidity
function updateReferralsTargetVolumeUsd(uint256 _value) external
```

*Updates targetVolumeUsd*

### Parameters

| Name    | Type    | Description              |
| ------- | ------- | ------------------------ |
| \_value | uint256 | new target volume in usd |

## whitelistAllies

```solidity
function whitelistAllies(address[] _allies) external
```

*Whitelists ally addresses*

### Parameters

| Name     | Type       | Description             |
| -------- | ---------- | ----------------------- |
| \_allies | address\[] | array of ally addresses |

## unwhitelistAllies

```solidity
function unwhitelistAllies(address[] _allies) external
```

*Unwhitelists ally addresses*

### Parameters

| Name     | Type       | Description             |
| -------- | ---------- | ----------------------- |
| \_allies | address\[] | array of ally addresses |

## whitelistReferrers

```solidity
function whitelistReferrers(address[] _referrers, address[] _allies) external
```

*Whitelists referrer addresses*

### Parameters

| Name        | Type       | Description                           |
| ----------- | ---------- | ------------------------------------- |
| \_referrers | address\[] | array of referrer addresses           |
| \_allies    | address\[] | array of corresponding ally addresses |

## unwhitelistReferrers

```solidity
function unwhitelistReferrers(address[] _referrers) external
```

*Unwhitelists referrer addresses*

### Parameters

| Name        | Type       | Description                 |
| ----------- | ---------- | --------------------------- |
| \_referrers | address\[] | array of referrer addresses |

## registerPotentialReferrer

```solidity
function registerPotentialReferrer(address _trader, address _referral) external
```

*Registers potential referrer for trader (only works if trader wasn't referred yet by someone else)*

### Parameters

| Name       | Type    | Description      |
| ---------- | ------- | ---------------- |
| \_trader   | address | trader address   |
| \_referral | address | referrer address |

## distributeReferralReward

```solidity
function distributeReferralReward(address _trader, uint256 _volumeUsd, uint256 _referrerFeeUsd, uint256 _gnsPriceUsd) external
```

*Distributes ally and referrer rewards*

### Parameters

| Name             | Type    | Description                            |
| ---------------- | ------- | -------------------------------------- |
| \_trader         | address | trader address                         |
| \_volumeUsd      | uint256 | trading volume in usd (1e18 precision) |
| \_referrerFeeUsd | uint256 | referrer fee in USD (1e18 precision)   |
| \_gnsPriceUsd    | uint256 | token price in usd (1e10 precision)    |

## claimAllyRewards

```solidity
function claimAllyRewards() external
```

*Claims pending GNS ally rewards of caller*

## claimReferrerRewards

```solidity
function claimReferrerRewards() external
```

*Claims pending GNS referrer rewards of caller*

## getReferrerFeeProgressP

```solidity
function getReferrerFeeProgressP(address _referrer) external view returns (uint256)
```

*Returns referrer fee % progress towards earning 100% based on his volume referred (1e10)*

### Parameters

| Name       | Type    | Description      |
| ---------- | ------- | ---------------- |
| \_referrer | address | referrer address |

## getTraderLastReferrer

```solidity
function getTraderLastReferrer(address _trader) external view returns (address)
```

*Returns last referrer of trader (whether referrer active or not)*

### Parameters

| Name     | Type    | Description       |
| -------- | ------- | ----------------- |
| \_trader | address | address of trader |

## getTraderActiveReferrer

```solidity
function getTraderActiveReferrer(address _trader) external view returns (address)
```

*Returns active referrer of trader*

### Parameters

| Name     | Type    | Description       |
| -------- | ------- | ----------------- |
| \_trader | address | address of trader |

## getReferrersReferred

```solidity
function getReferrersReferred(address _ally) external view returns (address[])
```

*Returns referrers referred by ally*

### Parameters

| Name   | Type    | Description     |
| ------ | ------- | --------------- |
| \_ally | address | address of ally |

## getTradersReferred

```solidity
function getTradersReferred(address _referrer) external view returns (address[])
```

*Returns traders referred by referrer*

### Parameters

| Name       | Type    | Description         |
| ---------- | ------- | ------------------- |
| \_referrer | address | address of referrer |

## getReferralsAllyFeeP

```solidity
function getReferralsAllyFeeP() external view returns (uint256)
```

*Returns ally fee % of total referral fee*

## getReferralsStartReferrerFeeP

```solidity
function getReferralsStartReferrerFeeP() external view returns (uint256)
```

*Returns start referrer fee % of total referral fee when zero volume was referred*

## getReferralsTargetVolumeUsd

```solidity
function getReferralsTargetVolumeUsd() external view returns (uint256)
```

*Returns target volume in usd to reach 100% of referral fee*

## getAllyDetails

```solidity
function getAllyDetails(address _ally) external view returns (struct IReferrals.AllyDetails)
```

*Returns ally details*

### Parameters

| Name   | Type    | Description     |
| ------ | ------- | --------------- |
| \_ally | address | address of ally |

## getReferrerDetails

```solidity
function getReferrerDetails(address _referrer) external view returns (struct IReferrals.ReferrerDetails)
```

*Returns referrer details*

### Parameters

| Name       | Type    | Description         |
| ---------- | ------- | ------------------- |
| \_referrer | address | address of referrer |

## UpdatedAllyFeeP

```solidity
event UpdatedAllyFeeP(uint256 value)
```

*Emitted when allyFeeP is updated*

### Parameters

| Name  | Type    | Description    |
| ----- | ------- | -------------- |
| value | uint256 | new ally fee % |

## UpdatedStartReferrerFeeP

```solidity
event UpdatedStartReferrerFeeP(uint256 value)
```

*Emitted when startReferrerFeeP is updated*

### Parameters

| Name  | Type    | Description              |
| ----- | ------- | ------------------------ |
| value | uint256 | new start referrer fee % |

## UpdatedOpenFeeP

```solidity
event UpdatedOpenFeeP(uint256 value)
```

*Emitted when openFeeP is updated*

### Parameters

| Name  | Type    | Description    |
| ----- | ------- | -------------- |
| value | uint256 | new open fee % |

## UpdatedTargetVolumeUsd

```solidity
event UpdatedTargetVolumeUsd(uint256 value)
```

*Emitted when targetVolumeUsd is updated*

### Parameters

| Name  | Type    | Description              |
| ----- | ------- | ------------------------ |
| value | uint256 | new target volume in usd |

## AllyWhitelisted

```solidity
event AllyWhitelisted(address ally)
```

*Emitted when an ally is whitelisted*

### Parameters

| Name | Type    | Description  |
| ---- | ------- | ------------ |
| ally | address | ally address |

## AllyUnwhitelisted

```solidity
event AllyUnwhitelisted(address ally)
```

*Emitted when an ally is unwhitelisted*

### Parameters

| Name | Type    | Description  |
| ---- | ------- | ------------ |
| ally | address | ally address |

## ReferrerWhitelisted

```solidity
event ReferrerWhitelisted(address referrer, address ally)
```

*Emitted when a referrer is whitelisted*

### Parameters

| Name     | Type    | Description      |
| -------- | ------- | ---------------- |
| referrer | address | referrer address |
| ally     | address | ally address     |

## ReferrerUnwhitelisted

```solidity
event ReferrerUnwhitelisted(address referrer)
```

*Emitted when a referrer is unwhitelisted*

### Parameters

| Name     | Type    | Description      |
| -------- | ------- | ---------------- |
| referrer | address | referrer address |

## ReferrerRegistered

```solidity
event ReferrerRegistered(address trader, address referrer)
```

*Emitted when a trader has a new active referrer*

## AllyRewardDistributed

```solidity
event AllyRewardDistributed(address ally, address trader, uint256 volumeUsd, uint256 amountGns, uint256 amountValueUsd)
```

*Emitted when ally rewards are distributed for a trade*

### Parameters

| Name           | Type    | Description                              |
| -------------- | ------- | ---------------------------------------- |
| ally           | address | address of ally                          |
| trader         | address | address of trader                        |
| volumeUsd      | uint256 | trade volume in usd (1e18 precision)     |
| amountGns      | uint256 | amount of GNS reward (1e18 precision)    |
| amountValueUsd | uint256 | USD value of GNS reward (1e18 precision) |

## ReferrerRewardDistributed

```solidity
event ReferrerRewardDistributed(address referrer, address trader, uint256 volumeUsd, uint256 amountGns, uint256 amountValueUsd)
```

*Emitted when referrer rewards are distributed for a trade*

### Parameters

| Name           | Type    | Description                              |
| -------------- | ------- | ---------------------------------------- |
| referrer       | address | address of referrer                      |
| trader         | address | address of trader                        |
| volumeUsd      | uint256 | trade volume in usd (1e18 precision)     |
| amountGns      | uint256 | amount of GNS reward (1e18 precision)    |
| amountValueUsd | uint256 | USD value of GNS reward (1e18 precision) |

## AllyRewardsClaimed

```solidity
event AllyRewardsClaimed(address ally, uint256 amountGns)
```

*Emitted when an ally claims his pending rewards*

### Parameters

| Name      | Type    | Description                |
| --------- | ------- | -------------------------- |
| ally      | address | address of ally            |
| amountGns | uint256 | GNS pending rewards amount |

## ReferrerRewardsClaimed

```solidity
event ReferrerRewardsClaimed(address referrer, uint256 amountGns)
```

*Emitted when a referrer claims his pending rewards*

### Parameters

| Name      | Type    | Description                |
| --------- | ------- | -------------------------- |
| referrer  | address | address of referrer        |
| amountGns | uint256 | GNS pending rewards amount |

## NoPendingRewards

```solidity
error NoPendingRewards()
```

## AlreadyActive

```solidity
error AlreadyActive()
```

## AlreadyInactive

```solidity
error AlreadyInactive()
```

## AllyNotActive

```solidity
error AllyNotActive()
```


---

# 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.gains.trade/developer/technical-reference/contracts/interfaces/libraries/ireferralsutils.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.