# Rewarder Module

### Core Data Structures

**RewarderManager**

The main controller that manages all rewarders for a pool:

```rust
struct RewarderManager {
    rewarders: vector<Rewarder>,      // Up to 5 rewarders
    points_released: u128,             // Total points released over time
    points_growth_global: u128,        // Global points growth rate
    last_updated_time: u64,           // Last settlement timestamp
}
```

**Rewarder**

Individual rewarder configuration for a specific reward token:

```rust
struct Rewarder {
    reward_coin: TypeName,            // Type of reward token
    emissions_per_second: u128,       // Emission rate (tokens per second)
    growth_global: u128,              // Accumulated growth factor
}
```

**RewarderGlobalVault**

Centralized storage for all reward token balances:

```rust
struct RewarderGlobalVault {
    id: UID,
    balances: Bag,                    // Stores Balance<T> for each reward token
}
```

### Core Functionality

#### Initialization

The module automatically creates a shared `RewarderGlobalVault` during initialization:

```rust
fun init(ctx: &mut TxContext)
```

This vault serves as the central repository for all reward tokens across all pools.

#### Rewarder Management

**Adding a New Rewarder**

```rust
public(friend) fun add_rewarder<CoinType>(manager: &mut RewarderManager)
```

* Adds a new rewarder for the specified `CoinType`
* Validates that the coin type doesn't already exist
* Enforces the maximum limit of 5 rewarders per pool
* Initializes with zero emissions (must be configured separately)

**Updating Emission Rates**

```rust
public(friend) fun update_emission<CoinType>(
    vault: &RewarderGlobalVault,
    manager: &mut RewarderManager,
    liquidity: u128,
    new_emissions: u128,
    current_time: u64
)
```

* Updates the emission rate for a specific rewarder
* Automatically settles pending rewards before updating
* Validates sufficient balance for 24 hours of rewards at the new rate
* Requires vault balance ≥ `86400 * new_emissions` for rate increases

#### Reward Distribution

**Settlement Process**

```rust
public(friend) fun settle(
    manager: &mut RewarderManager,
    liquidity: u128,
    current_time: u64
)
```

The settlement process:

1. **Time Validation**: Ensures time progression is valid
2. **Liquidity Check**: Skips settlement if no liquidity or no time passed
3. **Growth Calculation**: For each rewarder with non-zero emissions:

   ```
   growth_increase = (time_delta * emissions_per_second) / liquidity
   ```
4. **Points Update**: Updates global points tracking using a constant multiplier

#### Token Management

**Depositing Rewards**

```rust
public fun deposit_reward<CoinType>(
    global_config: &GlobalConfig,
    vault: &mut RewarderGlobalVault,
    reward: Balance<CoinType>
) : u64
```

* Adds reward tokens to the global vault
* Creates new balance entry if token type doesn't exist
* Emits `DepositEvent` for tracking
* Returns the final balance amount

**Emergency Withdrawal**

```rust
public fun emergent_withdraw<CoinType>(
    _admin_cap: &AdminCap,
    global_config: &GlobalConfig,
    vault: &mut RewarderGlobalVault,
    amount: u64
) : Balance<CoinType>
```

* Admin-only function for emergency token withdrawal
* Requires `AdminCap` authorization
* Emits `EmergentWithdrawEvent` for auditability

### API Reference

#### Query Functions

**Balance Queries**

```rust
// Get balance of specific token type in vault
public fun balance_of<CoinType>(vault: &RewarderGlobalVault) : u64

// Get reference to all balances
public fun balances(vault: &RewarderGlobalVault) : &Bag
```

**Rewarder Information**

```rust
// Get rewarder index for a coin type
public fun rewarder_index<CoinType>(manager: &RewarderManager) : Option<u64>

// Get all rewarders
public fun rewarders(manager: &RewarderManager) : vector<Rewarder>

// Get growth values for all rewarders
public fun rewards_growth_global(manager: &RewarderManager) : vector<u128>
```

**Individual Rewarder Data**

```rust
// Access specific rewarder (read-only)
public fun borrow_rewarder<CoinType>(manager: &RewarderManager) : &Rewarder

// Get emission rate
public fun emissions_per_second(rewarder: &Rewarder) : u128

// Get growth global value
public fun growth_global(rewarder: &Rewarder) : u128

// Get reward coin type
public fun reward_coin(rewarder: &Rewarder) : TypeName
```

**Manager State**

```rust
// Get last update timestamp
public fun last_update_time(manager: &RewarderManager) : u64

// Get global points data
public fun points_growth_global(manager: &RewarderManager) : u128
public fun points_released(manager: &RewarderManager) : u128
```

#### Friend Functions

These functions are restricted to the `ferra_clmm::pool` module:

```rust
// Create new manager
public(friend) fun new() : RewarderManager

// Add rewarder
public(friend) fun add_rewarder<CoinType>(manager: &mut RewarderManager)

// Access mutable rewarder
public(friend) fun borrow_mut_rewarder<CoinType>(manager: &mut RewarderManager) : &mut Rewarder

// Settle rewards
public(friend) fun settle(manager: &mut RewarderManager, liquidity: u128, current_time: u64)

// Update emissions
public(friend) fun update_emission<CoinType>(/*...*/)

// Withdraw rewards
public(friend) fun withdraw_reward<CoinType>(vault: &mut RewarderGlobalVault, amount: u64) : Balance<CoinType>
```

### Events

#### RewarderInitEvent

Emitted during module initialization:

```rust
struct RewarderInitEvent {
    global_vault_id: ID,
}
```

#### DepositEvent

Emitted when rewards are deposited:

```rust
struct DepositEvent {
    reward_type: TypeName,
    deposit_amount: u64,
    after_amount: u64,
}
```

#### EmergentWithdrawEvent

Emitted during emergency withdrawals:

```rust
struct EmergentWithdrawEvent {
    reward_type: TypeName,
    withdraw_amount: u64,
    after_amount: u64,
}
```

### Error Codes

* **Error 1**: Maximum number of rewarders exceeded (limit: 5)
* **Error 2**: Rewarder for this coin type already exists
* **Error 3**: Invalid time progression (current\_time < last\_updated\_time)
* **Error 4**: Insufficient balance in vault for new emission rate
* **Error 5**: Rewarder not found for the specified coin type

### Mathematical Formulas

#### Growth Calculation

For each rewarder during settlement:

```rust
growth_increase = mul_div_floor(time_delta, emissions_per_second, liquidity)
new_growth_global = old_growth_global + growth_increase
```

#### Points Calculation

Using a constant multiplier (2^64 \* 10^6):

```rust
multiple = 18446744073709551616000000
points_released += time_delta * multiple
points_growth_global += mul_div_floor(time_delta, multiple, liquidity)
```

#### Balance Validation

For emission rate increases:

```rust
required_balance = 86400 * new_emissions  // 24 hours worth
current_balance_scaled = balance << 64     // Scaled for precision
assert(current_balance_scaled >= required_balance)
```

### Best Practices

1. **Regular Settlement**: Settle rewards before major pool operations
2. **Sufficient Funding**: Maintain adequate vault balances for sustained rewards
3. **Gradual Rate Changes**: Avoid sudden large emission rate changes
4. **Monitor Events**: Track all reward-related events for proper accounting
5. **Emergency Procedures**: Have clear protocols for emergency withdrawals


---

# 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.ferra.ag/integration/clmm/smart-contract/rewarder-module.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.