# Chiss Dynamic Fee Implementation

Chiss protocol utilizes a **dynamic fee mechanism** that adjusts swap fees based on pool imbalance. The fee is computed from a balance ratio, derived from the `harmonic` and `arithmetic` means of virtual token balances.

Dynamic fee is calculated based on the imbalance between balances of the pools as `Xv` and `Yv`.

#### At the core, the Fee Increase Due to Imbalance caused by the `feeMultiplier`

> **`feeMultiplier`** is **the key control Multiplier** that determines **how steeply** the dynamic fee grows as imbalance increases.
----------------------------

## Key Formulae
### Balance Ratio

The **balance ratio** is defined as:

Balance Ratio = (4 * Xv * Yv) / (Xv + Yv)^2

Where:

* `Xv` and `Yv` are the **virtual balances** of the two tokens in the pool (scaled by their respective oracle prices and decimal multipliers).

### Harmonic & Arithmetic Mean

This formula is mathematically equivalent to:

Balance Ratio =  (Harmonic Mean) / (Arithmetic Mean)

Let:

* `H = 2XY / (X + Y)` be the **harmonic mean**
* `A = (X + Y)/2` be the **arithmetic mean**

Then:

Balance Ratio = (H / A)

This metric is:

* **1.0** when `Xv = Yv` (perfectly balanced)
* Approaches **0** when either `Xv` or `Yv` approaches 0 (extreme imbalance)

---

## Dynamic Fee Calculation

The **effective swap fee** is scaled using the `balanceRatio` as follows:

function calculateDynamicFee(uint256 Xv, uint256 Yv, uint256 baseFee) internal pure returns (uint256 dynamicFee) {
    uint256 sumSquared = (Xv + Yv) * (Xv + Yv);
    uint256 numerator = feeMultiplier * baseFee;
    uint256 balanceRatio = (4 * Xv * Yv * 1e18) / sumSquared;
    uint256 denominator = ((feeMultiplier - FEE_DENOMINATOR) * balanceRatio) + FEE_DENOMINATOR;
    dynamicFee = (numerator * 1e18) / denominator;
}

### Constants:

baseFee = 100_000                 // 0.001% in 1e10 scale
FEE_DENOMINATOR = 10_000_000_000  // Precision for fee calculations (1e10)
feeMultiplier = 20_000_000_000    // 2.0 in 1e10 scale

---
## Mathematical Derivatives

### 1. Harmonic Mean (H) and Arithmetic Mean (A)

* Harmonic mean is a better metric when averaging **rates** or **ratios**, such as `Xv` and `Yv`.
* It penalizes **extreme imbalances** heavily.

Given:

H = 2 * Xv * Yv / (Xv + Yv)
A = (Xv + Yv) / 2

The harmonic-to-arithmetic ratio is:

H / A = (4 * Xv * Yv) / (Xv + Yv)^2 = Balance Ratio

This is dimensionless, symmetric, and ranges from (0,1].

### 2. Dynamic Fee Formula

From the Solidity code:

dynamicFee = (feeMultiplier * baseFee) / [ (feeMultiplier - 1) * balanceRatio + 1 ]

This is a **rational function** of `balanceRatio`, with the following properties:

* `balanceRatio = 1` → dynamicFee = baseFee
* `balanceRatio → 0` → dynamicFee → feeMultiplier × baseFee

Ensuring a **smooth interpolation** between low and high fees based on imbalance.

---

## Visualizing Balance Ratio and Fee

Let’s use virtual balances:

| Scenario | Xv | Yv | Ratio | Balance Ratio | Fee (%) |
| -------- | ------- | ----- | ----- | ------------- | --------- |
| Equal | 1,000 | 1,000 | 1.00 | 1.0000 | 0.0010 |
| Slight | 1,500 | 1,000 | 1.50 | 0.96 | \~0.00104 |
| Moderate | 2,000 | 1,000 | 2.00 | 0.89 | \~0.00106 |
| High | 10,000 | 1,000 | 10.0 | 0.33 | \~0.00178 |
| Extreme | 100,000 | 1,000 | 100.0 | 0.039 | \~0.00196 |

This shows how the **fee ramps up** as imbalance increases, disincentivizing arbitrage unless rewards are high enough to cover the cost.

----
## How `feeMultiplier` Influences Fee Behavior

The more imbalanced the pool becomes (i.e., `Xv ≫ Yv` or vice versa), the smaller the `bRatio` becomes:
--When **`Xv ≈ Yv*, `bRatio ≈ 1e18`, so dynamic fee ≈ baseFee
--When **high imbalance**, `bRatio → 0`, so fee grows toward `feeMultiplier × baseFee`

* **Low imbalance** → `bRatio ≈ 1e18`
→ Dynamic fee \~ baseFee
* **High imbalance** → `bRatio → 0`
→ Dynamic fee \~ `feeMultiplier × baseFee`

The`feeMultiplier` defines the **maximum multiplier** of the base fee during extreme imbalance.
It controls how aggressively fee increases with imbalance and defines the **max multiple of the base fee** when the pool is imbalanced.