> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gains.trade/llms.txt
> Use this file to discover all available pages before exploring further.

# IReferralsUtils

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

## initializeReferrals

```solidity theme={null}
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 theme={null}
function updateAllyFeeP(uint256 _value) external
```

*Updates allyFeeP*

### Parameters

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

## updateStartReferrerFeeP

```solidity theme={null}
function updateStartReferrerFeeP(uint256 _value) external
```

*Updates startReferrerFeeP*

### Parameters

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

## updateReferralsTargetVolumeUsd

```solidity theme={null}
function updateReferralsTargetVolumeUsd(uint256 _value) external
```

*Updates targetVolumeUsd*

### Parameters

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

## whitelistAllies

```solidity theme={null}
function whitelistAllies(address[] _allies) external
```

*Whitelists ally addresses*

### Parameters

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

## unwhitelistAllies

```solidity theme={null}
function unwhitelistAllies(address[] _allies) external
```

*Unwhitelists ally addresses*

### Parameters

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

## whitelistReferrers

```solidity theme={null}
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 theme={null}
function unwhitelistReferrers(address[] _referrers) external
```

*Unwhitelists referrer addresses*

### Parameters

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

## registerPotentialReferrer

```solidity theme={null}
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 theme={null}
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 theme={null}
function claimAllyRewards() external
```

*Claims pending GNS ally rewards of caller*

## claimReferrerRewards

```solidity theme={null}
function claimReferrerRewards() external
```

*Claims pending GNS referrer rewards of caller*

## getReferrerFeeProgressP

```solidity theme={null}
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 theme={null}
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 theme={null}
function getTraderActiveReferrer(address _trader) external view returns (address)
```

*Returns active referrer of trader*

### Parameters

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

## getReferrersReferred

```solidity theme={null}
function getReferrersReferred(address _ally) external view returns (address[])
```

*Returns referrers referred by ally*

### Parameters

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

## getTradersReferred

```solidity theme={null}
function getTradersReferred(address _referrer) external view returns (address[])
```

*Returns traders referred by referrer*

### Parameters

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

## getReferralsAllyFeeP

```solidity theme={null}
function getReferralsAllyFeeP() external view returns (uint256)
```

*Returns ally fee % of total referral fee*

## getReferralsStartReferrerFeeP

```solidity theme={null}
function getReferralsStartReferrerFeeP() external view returns (uint256)
```

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

## getReferralsTargetVolumeUsd

```solidity theme={null}
function getReferralsTargetVolumeUsd() external view returns (uint256)
```

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

## getAllyDetails

```solidity theme={null}
function getAllyDetails(address _ally) external view returns (struct IReferrals.AllyDetails)
```

*Returns ally details*

### Parameters

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

## getReferrerDetails

```solidity theme={null}
function getReferrerDetails(address _referrer) external view returns (struct IReferrals.ReferrerDetails)
```

*Returns referrer details*

### Parameters

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

## UpdatedAllyFeeP

```solidity theme={null}
event UpdatedAllyFeeP(uint256 value)
```

*Emitted when allyFeeP is updated*

### Parameters

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

## UpdatedStartReferrerFeeP

```solidity theme={null}
event UpdatedStartReferrerFeeP(uint256 value)
```

*Emitted when startReferrerFeeP is updated*

### Parameters

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

## UpdatedOpenFeeP

```solidity theme={null}
event UpdatedOpenFeeP(uint256 value)
```

*Emitted when openFeeP is updated*

### Parameters

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

## UpdatedTargetVolumeUsd

```solidity theme={null}
event UpdatedTargetVolumeUsd(uint256 value)
```

*Emitted when targetVolumeUsd is updated*

### Parameters

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

## AllyWhitelisted

```solidity theme={null}
event AllyWhitelisted(address ally)
```

*Emitted when an ally is whitelisted*

### Parameters

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

## AllyUnwhitelisted

```solidity theme={null}
event AllyUnwhitelisted(address ally)
```

*Emitted when an ally is unwhitelisted*

### Parameters

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

## ReferrerWhitelisted

```solidity theme={null}
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 theme={null}
event ReferrerUnwhitelisted(address referrer)
```

*Emitted when a referrer is unwhitelisted*

### Parameters

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

## ReferrerRegistered

```solidity theme={null}
event ReferrerRegistered(address trader, address referrer)
```

*Emitted when a trader has a new active referrer*

## AllyRewardDistributed

```solidity theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
error NoPendingRewards()
```

## AlreadyActive

```solidity theme={null}
error AlreadyActive()
```

## AlreadyInactive

```solidity theme={null}
error AlreadyInactive()
```

## AllyNotActive

```solidity theme={null}
error AllyNotActive()
```