> For the complete documentation index, see [llms.txt](https://knox-fi.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://knox-fi.gitbook.io/docs/pool-configuration-and-parameters.md).

# Pool Configuration & Parameters

Every Knox pool is configured with a set of parameters that define its risk profile, duration, fee structure, and collateralization requirements.

## Core Parameters

### Rate Configuration

#### `rSenior`

* **Type:** `uint128` (basis points)
* **Range:** 0.50% - 20.00% (50 - 2000 bps)
* **Description:** Guaranteed annualized return for the senior tranche
* **Example:** `rSenior = 500` means 5.00% APY
* **Impact:**
  * Higher senior rate → Less yield left for spectrum/junior
  * Lower senior rate → More yield available for risk tranches

#### `rMaxSpectrum`

* **Type:** `uint128` (basis points)
* **Range:** `(rSenior + spectrumGridStep)` - 50.00% (5000 bps)
* **Description:** Maximum APY cap for the highest spectrum tranche
* **Constraint:** Must be greater than `rSenior`
* **Example:** With `rSenior = 500` (5%), `rMaxSpectrum = 2000` (20%)
* **Impact:** Defines the upper bound of the spectrum grid

#### `spectrumGridStep`

* **Type:** `uint128` (basis points)
* **Range:** 0.25% - 5.00% (25 - 500 bps)
* **Description:** APY increment between spectrum grid points
* **Constraint:** `(rMaxSpectrum - rSenior)` must be evenly divisible by `spectrumGridStep`
* **Example:** With `rSenior = 500`, `rMaxSpectrum = 1000`, `gridStep = 100`:
  * Available rates: 6%, 7%, 8%, 9%, 10%
* **Impact:**
  * Smaller step → More granular risk selection (more possible tranches)
  * Larger step → Coarser grid (fewer tranches, simpler waterfall)

**Grid Size Formula:**

```
numGridPoints = (rMaxSpectrum - rSenior) / spectrumGridStep
```

**Example Grids:**

| rSenior | rMax | Step | Grid Points | Tranches              |
| ------- | ---- | ---- | ----------- | --------------------- |
| 3%      | 10%  | 0.5% | 14          | 3.5%, 4.0%, ... 10.0% |
| 5%      | 20%  | 1.0% | 15          | 6%, 7%, ... 20%       |
| 2%      | 8%   | 2.0% | 3           | 4%, 6%, 8%            |

### Period & Timing

#### `dPeriod`

* **Type:** `uint128` (seconds)
* **Range:** 7 days - 365 days (604800 - 31536000 seconds)
* **Description:** Pool duration from deployment to maturity

**Common Values:**

* 30 days: `2_592_000`
* 90 days: `7_776_000`
* 180 days: `15_552_000`
* 365 days: `31_536_000`

**Impact:**

* Longer period → More compounding, higher absolute returns
* Shorter period → Less time risk, faster capital turnover

**Maturity Calculation:**

```
maturityTimestamp = tStart + dPeriod
```

**Compounding Effect (5% APY):**

| Period   | Holding Full Period | Absolute Return |
| -------- | ------------------- | --------------- |
| 7 days   | 7/365 = 1.92%       | 0.096%          |
| 30 days  | 30/365 = 8.22%      | 0.41%           |
| 90 days  | 90/365 = 24.66%     | 1.23%           |
| 365 days | 100%                | 5.00%           |

### Fee Configuration

#### `cProtocolFee`

* **Type:** `uint128` (basis points)
* **Range:** 0.00% - 30.00% (0 - 3000 bps)
* **Description:** Fee on total pool yield, collected at settlement
* **Default:** Typically 5-10% (500-1000 bps)

**Calculation:**

```
totalYield = max(0, withdrawnAssets - totalDeposits)
protocolFee = totalYield × cProtocolFee / 10000
```

**When Applied:** Only if `factory.applyProtocolFees() == true` (global switch)

**Impact:**

* Fee reduces distributable amount before waterfall
* Effectively borne by riskiest positions (spectrum/junior)
* No fee if pool has no profit

**Example:**

* Deposits: $1M
* Withdrawals: $1.1M
* Fee: 10% (1000 bps)
* Protocol takes: `($1.1M - $1M) × 10% = $10k`
* Distributable: $1.09M

#### `protocolFeeBeneficiary`

* **Type:** `address`
* **Description:** Receives protocol fees at settlement
* **Set At:** Pool deployment (parameter to `SpectrumFactory.deploy()`)

### Collateralization

#### `cCollateralFactorFirst`

* **Type:** `uint128` (basis points)
* **Range:** 5.00% - 100.00% (500 - 10000 bps)
* **Description:** Collateral factor for the first (lowest) spectrum grid point
* **Meaning:** Percentage of spectrum value pledged as backing for senior deposits
* **Example:** `cCollateralFactorFirst = 5000` (50%)
  * `$100` in the 5.5% spectrum tranche backs `$10` of senior deposits
* **Impact:**
  * Higher CF → More senior capacity per unit of spectrum
  * Lower CF → Safer for spectrum holders (less loss absorption)

#### `cCollateralFactorJunior`

* **Type:** `uint128` (basis points)
* **Range:** `cCollateralFactorFirst` - 100.00% (10000 bps)
* **Description:** Collateral factor for junior tranche (and upper bound for interpolation)
* **Typical Value:** 100% (10000 bps)
* **Meaning:** Junior pledges entire value as senior backing
* **Constraint:** Must be `≥ cCollateralFactorFirst`
* **Example:** `cCollateralFactorJunior = 10000` (100%)
  * `$100` in junior backs `$20` of senior deposits (at 5% senior APY, 365d period)

#### Collateral Factor Interpolation

Spectrum tranches between first and junior have CFs interpolated linearly:

```
CF(position) = cCollateralFactorFirst + ((cCollateralFactorJunior - cCollateralFactorFirst) × position / numGridPoints)
```

Where `position` is 0-indexed (`0 = first spectrum`, `N = last spectrum before junior`).

**Example:**

* `cCollateralFactorFirst = 5000` (50%)
* `cCollateralFactorJunior = 10000` (100%)
* Grid: 5.5%, 7.5%, 9.5%, 11.5%, 13.5% (5 tranches)

| Tranche | Position | CF Calculation    | CF    |
| ------- | -------- | ----------------- | ----- |
| 5.5%    | 0/4      | 50% + (50% × 0/4) | 50%   |
| 7.5%    | 1/4      | 50% + (50% × 1/4) | 62.5% |
| 9.5%    | 2/4      | 50% + (50% × 2/4) | 75%   |
| 11.5%   | 3/4      | 50% + (50% × 3/4) | 87.5% |
| 13.5%   | 4/4      | 50% + (50% × 4/4) | 100%  |

### Capacity Constraints

#### `cMaxTotalDeposits`

* **Type:** `uint256`
* **Range:** 0 - `type(uint256).max`
* **Description:** Hard cap on total pool deposits across all tranches
* **Special:** If set to `0` at initialization, becomes `type(uint256).max` (unlimited)
* **Example:** `cMaxTotalDeposits = 10_000_000e6` (10M USDC for a 6-decimal token)
* **Impact:** Prevents pool from growing beyond manageable size

#### Senior Capacity (Dynamic)

* **Computed:** Not a configuration parameter — calculated dynamically

**Formula:**

```
seniorCapacity = (Σ(spectrumValue_i × CF_i) + (juniorValue × CF_junior)) × SECONDS_PER_YEAR / (dPeriod × rSenior)
```

* **Recalculates:** On every senior deposit, based on current waterfall values

**Example (365d period, 5% senior):**

| Subordinate Tranche | Value | CF   | Contribution | Senior Backing   |
| ------------------- | ----- | ---- | ------------ | ---------------- |
| Spectrum 5.5%       | $100k | 50%  | $50k         | $50k × 20 = $1M  |
| Spectrum 10%        | $200k | 75%  | $150k        | $150k × 20 = $3M |
| Junior              | $300k | 100% | $300k        | $300k × 20 = $6M |
| Total               |       |      | $500k        | $10M             |

**Divisor:**

```
dPeriod × rSenior / SECONDS_PER_YEAR = 365 × 0.05 = 18.25 days of senior yield per $1 collateral
```

**Inverted:** Each `$1` of collateral backs `$20` of senior deposits (`$1 / 0.05 = $20`)

## Validation Constraints

### At Deployment

```solidity
// Rate hierarchy
require(rSenior < rMaxSpectrum, "Senior must be below max spectrum");

// Grid divisibility
require((rMaxSpectrum - rSenior) % spectrumGridStep == 0, "Grid must divide evenly");

// Grid step positive
require(spectrumGridStep > 0, "Grid step must be positive");

// Collateral factor ordering
require(cCollateralFactorFirst <= cCollateralFactorJunior, "First CF must be ≤ junior CF");

// Period bounds
require(dPeriod >= 7 days && dPeriod <= 365 days, "Period out of range");
```

### At Deposit

```solidity
// Total deposits cap
require(totalDeposits + amount <= cMaxTotalDeposits, "Exceeds total cap");

// Senior capacity (senior deposits only)
require(seniorDeposits + amount <= seniorCapacity(), "Exceeds senior capacity");

// Spectrum grid alignment
require(apyBps > rSenior && apyBps <= rMaxSpectrum, "Rate out of range");
require((apyBps - rSenior) % spectrumGridStep == 0, "Rate not on grid");

// No deposits after maturity
require(block.timestamp < tStart + dPeriod, "Pool matured");
```

## Parameter Examples

### Conservative Pool

```
{rSenior: 200, // 2% senior
 rMaxSpectrum: 600, // 6% max spectrum
 spectrumGridStep: 100, // 1% step → 3%, 4%, 5%, 6%
 dPeriod: 15552000, // 180 days
 cProtocolFee: 500, // 5% fee
 cCollateralFactorFirst: 3000, // 30% first spectrum
 cCollateralFactorJunior: 8000, // 80% junior
 cMaxTotalDeposits: 5000000e6 // 5M cap}
```

**Profile:** Low-risk, longer duration, heavy senior allocation

### Aggressive Pool

```
{rSenior: 600, // 6% senior
 rMaxSpectrum: 2500, // 25% max spectrum
 spectrumGridStep: 200, // 2% step → 8%, 10%, ..., 24%, 25%
 dPeriod: 2592000, // 30 days
 cProtocolFee: 1000, // 10% fee
 cCollateralFactorFirst: 7000, // 70% first spectrum
 cCollateralFactorJunior: 10000, // 100% junior
 cMaxTotalDeposits: 0 // Unlimited (becomes max uint256)}
```

**Profile:** High-risk, short duration, spectrum-focused

### Balanced Pool

```
{rSenior: 300, // 3% senior
 rMaxSpectrum: 1000, // 10% max spectrum
 spectrumGridStep: 50, // 0.5% step → 3.5%, 4%, ..., 10%
 dPeriod: 7776000, // 90 days
 cProtocolFee: 500, // 5% fee
 cCollateralFactorFirst: 5000, // 50% first spectrum
 cCollateralFactorJunior: 10000, // 100% junior
 cMaxTotalDeposits: 10000000e6 // 10M cap}
```

**Profile:** Moderate risk, standard duration, fine-grained spectrum grid

## Key Takeaways

* **Rate hierarchy:** `rSenior < spectrum_i < rMaxSpectrum`, with `spectrumGridStep` spacing
* **Grid divisibility:** `(rMaxSpectrum - rSenior) % gridStep == 0` enforced
* **Collateral interpolation:** Linear from `cCollateralFactorFirst` to `cCollateralFactorJunior`
* **Senior capacity:** Dynamic, recalculated on each senior deposit based on subordinate values
* **Protocol fee:** Only on total yield, global on/off switch via factory
* **Period:** Fixed duration, compounding pro-rated to holding time
* **Validation:** Strict at deployment and deposit to prevent misconfiguration