> 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/spectrum-simulator.md).
# Spectrum Simulator
Click [here](https://simulator.knox.finance/) to simulate your risk using our comprehensive **Knox Vault Simulator**!
## Quick Guide
### What is this?
Knox Spectrum Vaults split yield from an underlying market into **tranches**. **Senior** gets a guaranteed fixed rate. **Spectrum** tranches sit in the middle — each has a capped rate, and they're paid out lowest-rate-first. **Junior** gets the residual: all upside in good scenarios, but absorbs losses first. The protocol takes a fee from junior profits.
This simulator lets you configure a pool, set up deposits at different days, and see exactly how settlement distributes value across all tranches.
### Try a Preset
Click any preset button in the header bar (e.g., **Balanced**, **Stress Test**, **Surplus**). The pool config, deposit schedule, and scenario all load instantly. The results panel updates in real time. The active preset's description is shown below the buttons.
### Read the Results
The right panel has three tabs:
* **Results** (bar chart icon) — Stat cards (deposited, value, P\&L, fee, capacity), charts (deposit timeline, pool composition, APY comparison), and per-deposit/per-tranche tables
* **Settlement** (line chart icon) — Sankey flow diagram showing how deposits flow through the underlying market and distribute to tranches at settlement
* **Protection** (shield icon) — How protected each tranche is: loss buffers, breakeven & cap APYs, scenario sweep chart (payout/yield/APY), and tranche protection table with status badges
### Tweak It
Use the left panel to adjust:
* **Pool parameters** — Senior APY, spectrum grid, period, collateral factors
* **Deposit schedule** — Add/remove/edit individual deposits, pick a schedule template, or use a game-theoretic market profile
* **Scenario** — Underlying return (market performance), time elapsed
### Share
Click **Export** to copy your full scenario (config + deposits) as JSON. Others can click **Import** to paste it and reproduce your exact setup.
***
## Detailed Functionality
### 1. The Settlement Waterfall
At maturity, the pool's total value is distributed in a strict order:
{% stepper %}
{% step %}
### Senior
Senior gets paid first — principal plus accrued interest at the guaranteed rate, pro-rated by each deposit's holding period.
{% endstep %}
{% step %}
### Spectrum
Spectrum tranches are paid next, starting from the lowest rate up to the highest. Each tranche is capped at its rate. If there isn't enough value to fully pay a spectrum tranche, it receives whatever remains.
{% endstep %}
{% step %}
### Junior
Junior gets whatever is left after senior and all spectrum tranches are satisfied. In good scenarios this is the largest return; in bad scenarios junior absorbs losses first.
{% endstep %}
{% step %}
### Protocol fee
Protocol fee is taken from junior profits (not principal) before the junior payout.
{% endstep %}
{% endstepper %}
**Loss absorption** works in reverse: Junior is wiped first, then spectrum tranches from highest-rate down, then senior. Senior is only impaired in extreme loss scenarios.
**Holding period matters**: A deposit made on day 45 of a 90-day pool earns approximately half the annualized rate compared to a day-0 deposit, since it compounds for fewer days.
### 2. Pool Parameters
| Parameter | Range | Step | Description |
| ----------------------- | ------------------------ | ----- | --------------------------------------------------------------------------------- |
| Senior APY | 0.50% – 20.00% | 0.50% | Guaranteed annualized return for the senior tranche |
| Max Spectrum APY | (Senior + Step) – 50.00% | 0.50% | Highest rate in the spectrum grid |
| Grid Step | 0.25% – 10.00% | 0.10% | Spacing between spectrum tranches |
| Period | 7 – 365 days | 1 day | Pool duration — all compounding is pro-rated to this |
| Protocol Fee | 0.00% – 30.00% | 0.50% | Fee on junior profits, collected at settlement |
| CF First Spectrum | 1.00% – 100.00% | 1.00% | Collateral factor for the first spectrum tranche |
| CF Junior | CF First – 100.00% | 1.00% | Collateral factor for junior relative to senior |
| Cap Reduction Factor | 0.00% – 100.00% | 1.00% | Reduces deposit caps for late deposits that earn a shorter compounding period |
| Spectrum Deposit Cutoff | 0.00% – 100.00% | 1.00% | Elapsed duration fraction at which spectrum deposits are cut off (0% = no cutoff) |
| Junior Deposit Cutoff | 0.00% – 100.00% | 1.00% | Elapsed duration fraction at which junior deposits are cut off (0% = no cutoff) |
**Grid Step example**: With Senior APY at 3% and Max Spectrum at 10% with a 2% grid step, the spectrum tranches are: 5%, 7%, 9%.
**Collateral factors** determine senior capacity — how much senior deposit the pool can support given the junior and spectrum collateral. Higher CFs mean more collateral is required relative to the senior tranche.
Surplus Participation
An optional section (collapsed by default) that controls whether spectrum tranches share in excess junior profits:
| Parameter | Range | Step | Description |
| ------------- | --------------- | ----- | ------------------------------------------------------------------------------ |
| k (Scale) | 0 – 1000 | 10 | Scale factor — 0 disables surplus sharing |
| Junior Hurdle | 0.00% – 100.00% | 0.50% | Minimum junior APY before surplus sharing kicks in |
| Exponent (n) | 0 – 5 | 0.1 | Curvature of sharing function (1 = linear, higher = more to high-APY tranches) |
When enabled and the underlying outperforms enough to clear the junior hurdle, surplus is distributed to spectrum tranches weighted by their collateral factors. Higher-CF tranches (higher APY) receive proportionally more surplus. Try the **Surplus** preset to see this in action.
### 3. Deposit Schedule
#### Schedule Templates & Market Profiles
The schedule editor offers two types of preset schedules:
**Static templates:**
| Template | Description |
| ---------- | ----------------------------------------------------------------------------- |
| Day 0 Flat | All deposits at day 0 — $500k senior, split spectrum, $200k junior |
| Random | 10 random deposits with uniform random tranches, days, and $10k–$100k amounts |
**Game-theoretic market profiles** — these model realistic depositor behavior using actor archetypes (bootstrap, conservative, moderate, aggressive, late followers, whales) with incentive-driven timing and tranche selection:
| Profile | Description |
| --------------- | ------------------------------------------------------------------------ |
| Bull Market | Aggressive actors pile into junior/spectrum early, front-loaded timing |
| Cautious Market | Risk-averse depositors — mostly senior with small spectrum positions |
| Whale Pool | Few large deposits dominate the pool composition |
| Retail Frenzy | Many small deposits (\~30) with strong spectrum grid interest |
| Late Rush | Slow start, most deposits arrive in the back half of the period |
| Balanced Mix | Even mix of actor types — conservative, moderate, aggressive, and whales |
Market profiles are **sentiment-aware**: they adjust tranche preferences based on the current underlying return. When the underlying outperforms, actors shift toward junior/spectrum; when it underperforms, they favor senior.
**Live recalculation**: Enable the "Live recalc on underlying APY change" checkbox (in the schedule details section) to have the deposit schedule automatically regenerate as you move the underlying return slider. This lets you see how depositor behavior would change under different market conditions.
#### Manual Editing
Expand the **Edit Schedule & Details** section to see and modify individual deposits:
* **Tranche** — Select Senior, Spectrum, or Junior
* **Spectrum Rate** — If Spectrum, pick a rate from the grid (dropdown)
* **Day** — When the deposit enters the pool (0 to period - 1)
* **Amount** — Dollar amount of the deposit
* **Delete** (x) — Remove the deposit
Use **+ Add Deposit** to append a new row. **Clear** removes all deposits. **Sort by Day** reorders chronologically.
#### Random Generator
Generate randomized deposit schedules:
* **Count** — Number of deposits (1–50)
* **Min / Max** — Amount range per deposit
* Click **Generate Random** to create a new random schedule (replaces current)
### 4. Scenario Controls
#### Underlying Return
The **Underlying Return (ann.)** slider sets the assumed annualized return on the pool's total assets. This is the market performance assumption:
* **Positive** values = profit scenario (green)
* **Negative** values = loss scenario (red)
* The **min/max** fields control the slider's range (useful for exploring extreme scenarios)
Each deposit's value at settlement is: `amount * (1 + rate)^(holdingDays / 365)`
#### Time Elapsed
The **Time Elapsed** slider sets a mark-to-market reference point. Charts display a "Now" line at this day, showing how the pool looks at that moment. This does not affect settlement calculations — it's purely for visualization.
### 5. Scenario Presets
Five built-in presets load a complete scenario (config + deposits). The active preset's description is shown below the buttons.
| Preset | Senior | Max Spectrum | Period | Return | Notable |
| ------------- | ------ | ------------ | ------ | ------- | ---------------------------------------------- |
| Balanced | 3.00% | 10.00% | 90d | +6.00% | Moderate risk/return mix |
| Stress Test | 3.00% | 10.00% | 90d | -14.00% | Loss scenario — junior + spectrum wiped |
| Surplus | 2.50% | 4.75% | 90d | +12.00% | Surplus participation demo (k=400, hurdle=20%) |
| Simple Case | 5.00% | 6.00% | 30d | +15.00% | Minimal testing setup |
| Simple Case 2 | 5.00% | 6.00% | 30d | +20.00% | Higher return with mid-period deposit |
Clicking a preset replaces all parameters and the deposit schedule. The active preset is highlighted; changing any parameter switches to "Custom".
### 6. Results — Stat Cards
 
Five summary cards at the top of the results panel:
| Card | What it shows |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Total Deposited** | Sum of all deposits across all tranches |
| **Underlying Value** | Mark-to-market pool value after applying the underlying return to each deposit's holding period. Green if profit, red if loss. Shows the absolute P\&L below. |
| **Total Tranche P\&L** | Sum of all tranche payouts minus deposits. Warns "Senior impaired" or "Loss scenario" when applicable. |
| **Protocol Fee** | Fee collected from junior profits. Shows the fee rate and any surplus swept. |
| **Senior Capacity** | Maximum senior deposits allowed given junior collateral and collateral factors. Warns "EXCEEDED" if actual senior deposits surpass this. |
### 7. Results — Charts
#### Deposit Timeline
Stacked bar chart showing deposits by day, colored by tranche. The "Now" reference line marks the elapsed day.
#### Pool Composition Over Time
Shows how each tranche's value evolves during the pool period. Two sets of controls:
* **Stacked / Separate** — Stacked areas vs individual lines
* **Mode** — Four view modes:
* **Value** — Total valuation per tranche over time
* **Yield** — Pure profit/loss per tranche (subtracts deposits)
* **Capacity** — Deposit capacity per tranche over time
* **APY** — Per-deposit or per-tranche annualized return over time
The "Now" line shows the current mark-to-market point. Hover for detailed tooltips.
#### Realized vs Target APY
Bar chart comparing each tranche's actual realized APY against its target cap. Useful for seeing which tranches hit their cap and which underperformed.
### 8. Results — Tables
#### Per-Deposit Results
Every deposit with its settlement outcome:
| Column | Description |
| ------- | -------------------------------------- |
| # | Original position in the schedule |
| Tranche | Senior / Spectrum (with rate) / Junior |
| Day | Deposit day |
| Amount | Deposit size |
| Payout | Amount returned at settlement |
| P\&L | Payout minus amount (green/red) |
| Return | Percentage return (payout/amount - 1) |
| APY | Annualized return |
**Sorting**: Toggle between chronological (Time) and grouped by tranche then time (Tranche, Time).
**Precise mode**: Toggle to show full 6-decimal precision instead of abbreviated values.
A footer row shows the protocol fee if applicable.
#### Per-Tranche Results
Aggregated view — one row per active tranche:
| Column | Description |
| -------- | --------------------------------------------------------------- |
| Tranche | Senior / Spectrum rate / Junior |
| Deposits | Total deposited in this tranche |
| Shares | Total shares issued |
| Cap | Tranche capacity (senior cap or spectrum cap; Junior shows "—") |
| Payout | Total payout from this tranche |
| P\&L | Payout minus deposits |
| Avg APY | Average annualized return across all deposits in this tranche |
### 9. Settlement Tab
The **Settlement** tab (line chart icon) displays a Sankey flow diagram that visualizes the full settlement waterfall:
* **Left side** — Deposits flowing into the underlying market, broken down by tranche
* **Center** — The underlying market value (yield or loss)
* **Right side** — Payouts distributed to each tranche, protocol fee, and any unallocated value
The diagram decomposes each tranche's payout into principal return and yield (or loss). It also shows per-tranche collateral factors and capacity utilization. Toggle between compact and detailed views.
### 10. Protection Tab
The **Protection** tab (shield icon) shows how protected each tranche is and what market conditions would cause losses. It only computes when active — switching to other tabs pauses the protection analysis.
#### Summary Cards
Three cards at the top:
| Card | What it shows |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Senior Buffer** | How much the underlying APY can drop before senior loses principal. Green if > 10%, amber if < 10%, red if impaired. |
| **Junior Breakeven APY** | The minimum underlying APY needed for junior to break even. Also shows the underlying APY at which junior outperforms the highest spectrum tranche. |
| **Subordination** | Total capital below senior in the waterfall (spectrum + junior, weighted by collateral factors). Shown as $ amount and as a ratio to senior deposits. |
#### Scenario Sweep Chart
Line chart showing how each tranche's outcome changes across a range of underlying returns. Three view modes:
| Mode | Y-axis | Description |
| ---------- | ------ | ------------------------------------------------------------------------------------------------------------------ |
| **Payout** | $ | Total payout per tranche. Horizontal dashed lines mark each tranche's deposit amount (breakeven reference). |
| **Yield** | +/- $ | Payout minus deposits (profit/loss). Zero line shown. |
| **APY** | % | Realized annualized return per tranche. Senior/spectrum flatten at their cap rate; junior curves upward unbounded. |
Vertical markers on the chart:
| Marker style | Meaning |
| ----------------------------- | ------------------------------------------------------- |
| Solid dashed (blue) | Current scenario ("You are here") |
| Medium dashed (tranche color) | Breakeven - underlying APY where payout equals deposits |
| Short dotted (tranche color) | Cap (senior/spectrum) or Outperform (junior) threshold |
The x-axis is a true numeric scale. The chart always includes the current scenario value and all threshold markers as data points so markers render precisely.
#### Tranche Protection Table
One row per active tranche with progressive columns (narrower screens hide lower-priority columns):
| Column | Always visible | Description |
| -------------------- | -------------- | ----------------------------------------------------------------------------------------------------------- |
| **Tranche** | Yes | Tranche name with color indicator |
| **Loss Buffer** | Yes | How much the underlying can drop (%) before impairment. 0% for junior (first-loss). |
| **APY** | Yes | Realized annualized return, computed consistently with the sweep chart |
| **Status** | Yes | Badge — At Cap, Below Cap, At Risk, Impaired, Top (junior outperforming), First Loss |
| **Breakeven** | 380px+ | Underlying APY at which payout equals deposits |
| **Deposits** | 440px+ | Total deposited in this tranche |
| **Cap / Outperform** | 595px+ | Senior/Spectrum: underlying APY to reach max payout. Junior: underlying APY to outperform highest spectrum. |
| **Protection** | 690px+ | Subordinated capital / tranche deposits (e.g., 1.85x) |
| **Subordinated** | 790px+ | Dollar amount of capital below this tranche in the waterfall |
Column headers with (?) show explanatory tooltips on hover (desktop) or tap (mobile).
#### Status Definitions
| Status | Meaning |
| -------------- | ------------------------------------------------ |
| **At Cap** | Earning full guaranteed/capped rate |
| **Below Cap** | Profitable but APY is below the promised rate |
| **At Risk** | Loss buffer under 10% |
| **Impaired** | Losing principal |
| **Top** | Junior APY exceeds highest spectrum tranche rate |
| **First Loss** | Junior at or below breakeven (no profit) |
### 11. Import / Export
#### Scenario (Full)
* **Export**: Click the Export button in the header. Copies the entire scenario as JSON to your clipboard — pool config, scenario settings, and the deposit schedule.
* **Import**: Click Import, paste the JSON, and click Apply. All parameters and deposits are restored.
#### Schedule Only
* **Export**: In the schedule editor section, click the copy button. Copies just the deposit schedule.
* **Import**: Click the import button in the schedule editor, paste the JSON, and apply.
#### JSON Format
Scenario format:
```json
{
"v": 1,
"rSenior": 300,
"rMaxSpectrum": 1000,
"gridStep": 200,
"dPeriodDays": 90,
"protocolFeeBps": 500,
"cfFirst": 500,
"cfJunior": 2000,
"capReductionFactor": 5000,
"cSpectrumDepositCutoffBps": 10000,
"cJuniorDepositCutoffBps": 10000,
"kSurplus": 0,
"rJuniorHurdle": 2000,
"nSurplus": 2,
"underlyingReturnBps": 600,
"returnRangeMin": -2000,
"returnRangeMax": 1500,
"schedule": [
{ "id": 1, "tranche": "senior", "day": 0, "amount": 500000 },
{ "id": 2, "tranche": "spectrum", "spectrumRate": 500, "day": 0, "amount": 100000 },
{ "id": 3, "tranche": "junior", "day": 0, "amount": 200000 }
]
}
```
Schedule-only format:
```json
{
"v": 1,
"type": "dynamic-schedule",
"schedule": [
{ "id": 1, "tranche": "senior", "day": 0, "amount": 500000 },
{ "id": 2, "tranche": "spectrum", "spectrumRate": 500, "day": 0, "amount": 100000 }
]
}
```
All rate values are in **basis points** (e.g., `300` = 3.00%). The `v: 1` field is required for validation.