# KNOX Documentation
Read the one-page explainer below to learn what KNOX Spectrum Vaults are about: {% file src="/files/MhlRE8apjtNBLk2Le8GC" %} ## What is Knox? Knox lets you choose exactly how much risk you want to take on DeFi yield. Every Knox pool takes a single yield source (such as a Morpho vault or Aave market) and splits its returns into a menu of risk/reward positions. You pick the one that matches your appetite: Want safety? Deposit into the senior tranche and lock in a guaranteed fixed rate (e.g., 5% APY). You get paid first, no matter what happens to the market. You only lose money in a catastrophic scenario where even junior and spectrum depositors are fully wiped out. Want moderate risk with the potential to capture surplus upside in a bullish market? Pick a spectrum tranche, say 8% or 12% APY cap. You earn that rate, with downside protection proportional to your position on the risk ladder. Lower caps are safer; higher caps offer more upside but absorb more losses. In strong markets where yield exceeds all caps, Surplus Participation can activate, distributing excess yield to Spectrum depositors proportional to their collateral factor, so your cap is not necessarily the ceiling on your total return. Want maximum upside? Deposit into the junior tranche. You absorb losses first, but you capture a larger share of the excess yield. When Surplus Participation is enabled, Junior earns a defined hurdle rate first, then competes for remaining surplus alongside Spectrum, with the highest collateral factor and therefore the largest participation multiplier. How it works in practice: A pool opens, you deposit into your chosen position, and your capital goes to work in the underlying market. When the pool matures (e.g., after 30 days), the protocol runs a waterfall: senior gets paid first, then spectrum tranches from lowest to highest cap, then junior gets their portion. If surplus participation is enabled and the market significantly outperforms, a third phase distributes excess yield across the stack proportional to the risk each tranche absorbed. You withdraw your share. That's it. Your position is an ERC-20 token, so you can transfer it or trade it on secondary markets before maturity, even though you can't withdraw from the pool early. Use our comprehensive [simulator](https://gashawk-io.github.io/project-knox-contracts/) to explore the behavior of KNOX Spectrum Vaults. #### How it works? At a high level: A pool is created with: * An underlying yield strategy (e.g., Morpho vault, Aave market, Strata/Ethena) * A maturity date * A spectrum grid, a configurable set of capped APY rates sitting between Senior and Junior * Target capacity for Senior, Spectrum, and Junior tranches * Surplus participation parameters, optional configuration that determines how excess yield is shared across tranches in strong markets Users deposit into Senior, a Spectrum tranche of their choice, or Junior. The pool deploys capital into the underlying strategy and accrues yield. At maturity, returns are distributed by the priority waterfall: * Senior gets priority and receives its fixed/defined yield (when possible) * Spectrum tranches are paid next, from lowest cap to highest cap, each up to their rate ceiling * Junior absorbs first loss (if any) and receives their share of residual upside after Senior and Spectrum are satisfied Surplus Participation (when enabled): if yield exceeds all caps, excess is redistributed across the capital stack proportional to each tranche's collateral factor. See the Surplus Participation section below. #### Using Knox: Basic flow * Connect wallet * Choose pool * Choose your tranche — Senior (fixed yield), Spectrum (pick your cap from the grid), or Junior (max upside) * Deposit * Hold to maturity * Redeem principal + yield Key concepts * Tranche = your position in the pool's risk waterfall * Spectrum grid = the configurable set of capped APY rates between Senior and Junior * Maturity date = when the pool unwinds and yield is finalized * Capacity = how much of each tranche the pool can accept at a given time * Surplus Participation = the mechanism that distributes excess yield across all tranches in strong markets, proportional to each tranche's collateral factor, and the mechanism to split principal risk according in scenarios where yields are underperforming #### Senior Deposits Senior deposits are designed for users who want predictable rates, safe outcomes and priority in repayment. Typical characteristics * Fixed rate with absolute priority claim on pool assets (vs. Spectrum and Junior) * Lower risk / lower expected upside than Spectrum or Junior * Capacity-limited: Senior cannot grow unless there is enough Spectrum + Junior cushion * Share pricing uses time-weighted compounding, so earlier deposits earn more shares * Senior does not participate in surplus distribution. Its return is the guaranteed fixed rate. #### Spectrum Deposits Spectrum deposits are designed for users who want more yield than Senior while accepting defined, capped risk. Typical characteristics * “Capped” APY at the rate you choose from the grid (e.g., 7%, 10%, 15%) * Paid after Senior but before higher-cap Spectrum tranches and Junior * Lower caps = safer (closer to Senior protection); higher caps = more upside but absorb more losses * Tranche tokens are ERC-20s, transferable before maturity **Surplus Participation for Spectrum** When surplus participation is enabled on a pool, Spectrum tranches gain a second dimension beyond their capped rate: In base-case and weak markets, your APY cap is the ceiling on what you earn from the waterfall. You receive up to that rate based on how much yield the underlying market generated. In strong markets where yield exceeds all caps, surplus participation activates and layers additional yield on top of your return Your extra share is proportional to your collateral factor. A higher-cap Spectrum position has a higher collateral factor, resulting in a larger participation multiplier and a bigger slice of the surplus. This means choosing a higher cap doesn't just give you more upside in the base case. It also gives you a larger participation unit in strong-market surplus distribution. The Spectrum grid effectively encodes both a downside risk gradient and an upside participation gradient simultaneously. #### Junior Deposits Junior deposits are designed for users who want maximum upside and are willing to take more risk. Typical characteristics * First-loss position that absorbs all shortfalls before Spectrum or Senior are affected * Receives their proportional share of residual yield after Senior and every Spectrum tranche is satisfied * Exposed to leveraged yield through the larger Senior + Spectrum principal base * Unlocks Senior capacity by providing the collateral cushion **Surplus Participation for Junior** When surplus participation is enabled: * Junior earns its hurdle rate (`rJuniorHurdle`, set at or above the maximum spectrum cap) before any surplus is shared with other tranches * After the hurdle is cleared, Junior participates in surplus distribution with the highest collateral factor in the pool (100%), giving it the largest individual participation multiplier * Junior also receives any rounding remainder from the surplus calculation The payoff profile remains highly convex on the upside. Junior no longer holds an exclusive claim on every dollar above the spectrum caps, but its structural advantage from the highest collateral factor means it still captures a proportionally larger share. When surplus participation is disabled (`kSurplusParticipation = 0`), Junior receives all surplus after caps are met, which is the traditional residual position. ## Protocol Mechanism #### Overview Knox pools create a priority waterfall that distributes yield across three tranche layers: * Senior tranche: fixed rate, absolute priority * Spectrum tranches: “capped” yield grids, paid lowest-to-highest cap * Junior tranche: residual upside, first-loss absorption The pool allocates all capital into a single underlying yield strategy. The tranching mechanism transforms one yield stream into a structured menu of risk/return products. Yields can be sourced from multiple chains, underlying vaults/yield protocols, and be accepted & distributed in any asset that Knox chooses to add support for. Specifics of this information will be identifiable within the UI and the underlying markets made available there. Learn more about the internals in our technical protocol overview. #### Yield Split A structured model for splitting yield across three risk/return buckets. * Vault accrues gross yield from underlying strategy. * At maturity, a protocol fee is deducted from total yield (when the fee switch is active). * Senior receives principal + guaranteed APY. Paid first, with absolute priority. * Spectrum tranches are paid next, lowest cap to highest cap, each up to their ceiling. * Junior receives all remaining yield, with unlimited upside in strong market scenarios. * Surplus Participation (when enabled): if yield exceeds all caps, excess is redistributed proportional to collateral factors. See below. If there is a loss/shortfall: * Junior takes losses first (no floor protection when CF = 100%) * Spectrum tranches absorb losses next (high cap → low cap), down to their collateral floor * Senior is only impacted after all subordinate tranches are fully exhausted Parameters (per pool) * Senior target rate / fixed APY * Spectrum grid: range, step size, and collateral factors per tranche * Junior collateral factor (overcollateralization requirement) * Protocol fee rate * Pool duration and total deposit cap * Surplus participation parameters (`kSurplusParticipation`, `nSurplusParticipation`, `rJuniorHurdle`) #### Surplus Participation Surplus Participation is the mechanism that governs how excess yield is distributed when a pool significantly outperforms. Rather than concentrating all strong-market upside into the Junior position, it distributes surplus across the entire capital stack proportional to the risk each tranche absorbed. How it works Settlement runs in three sequential phases: 1. **Phase 1: Fees.** Protocol and curator fees are deducted from total yield upfront, before the waterfall runs. 2. **Phase 2: Priority Distribution (Caps).** Senior receives its guaranteed fixed rate first. Spectrum tranches are paid from lowest cap to highest cap, each up to their ceiling. Junior their proportional share of whatever remains. 3. **Phase 3: Surplus Participation (when enabled).** After all tranche caps are satisfied, remaining surplus is distributed as follows: * **Step 1, Junior Hurdle:** Junior earns its hurdle rate (`rJuniorHurdle`) first. This must be set at or above the maximum spectrum cap. Junior fills this obligation before any surplus is shared with other tranches. * **Step 2, Participation Units:** Once the hurdle is cleared, remaining surplus is split among all Spectrum tranches and Junior using participation units: ``` M_i = 1 + k × (CF_i)^n PU_i = twDeposits_i × M_i share_i = (PU_i / Σ PU) × surplus ``` Where `k = kSurplusParticipation`, `n = nSurplusParticipation`, and `CF_i` is each tranche's collateral factor. Higher-risk tranches have a higher collateral factor, giving them a larger multiplier and therefore a larger share of surplus. Time-weighted deposits: Participation units use time-weighted deposits rather than raw deposit balances. Capital deployed early in the pool's duration receives full weight. Capital deployed late is scaled proportionally to reflect the fraction of the pool duration during which it was at risk. This prevents late capital from extracting a disproportionate share of surplus generated primarily by early depositors. Configuration parameters | Parameter | Role | | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | kSurplusParticipation |

Surplus scaling factor.
0
disables the mechanism entirely, meaning Junior receives all surplus. Higher values distribute surplus more broadly across the capital stack.

| | nSurplusParticipation | Exponent applied to the collateral factor in the participation unit formula. Higher values concentrate surplus toward higher-risk tranches. Must be greater than 0 when the mechanism is enabled. | | rJuniorHurdle |

Junior's minimum return before surplus sharing begins. Must be set at or above
rMaxSpectrum
. Determines how much Junior earns before the pool distributes surplus to other tranches.

| When `kSurplusParticipation = 0`, the protocol operates in its base configuration, where all surplus above the spectrum caps flows to Junior. When enabled, the full mechanism activates. Both configurations are fully supported. Pool deployers select based on their intended risk architecture. #### Vault TVL Availability Pools show capacity available to depositors separately for: * Senior capacity available, dynamically limited by the collateral value of Spectrum + Junior tranches * Spectrum capacity available, per grid rate, limited by total pool cap * Junior capacity available, limited by total pool cap Capacity can be constrained by: * Required Spectrum + Junior cushion (Senior can't grow unless subordinate tranches grow) * Total deposit cap (`cMaxTotalDeposits`) * Maturity window (deposits are blocked after the pool's maturity timestamp) #### Protocol Revenue After a no-fee period, Knox will deduct a protocol fee from total pool yield at settlement (before the waterfall runs) and use it among other things for internal Junior pool bootstrapping in order to open up capacity for Senior deposits at the Junior tranche (first-in-line risk position). ## Documentation Pages [Core Concepts](broken://pages/043b8f8d0e1733660bff205adb2128f6b6f16611) Understand the three tranche types (Senior, Spectrum, Junior), pool lifecycle states, and how holding period affects returns. [Settlement Waterfall](broken://pages/6a872d9bf54cd8a5ad933744362ee722c8ef47bb) Deep dive into the two-phase waterfall: protocol fee deduction, floor-based distribution, and loss absorption hierarchy with detailed scenarios. [Technical Architecture](broken://pages/be79b776b146161e2d42704ffd8d78171b2050dd) Smart contract system overview: KnoxRouter, SpectrumAccountant, TrancheVault, allocators, deposit flows, and lazy vault creation. [Pool Configuration & Parameters](broken://pages/4754553d685206821878a9983a15b206cc45286e) Complete reference for rate configuration, collateral factors, capacity constraints, and validation rules with parameter examples. [Integration Guide](broken://pages/d19566bd8837256dc193b5980bbd3ae442597970) Developer guide: depositing via router/accountant/vault, querying positions, withdrawing after settlement, and common integration patterns. [Advanced Topics](broken://pages/4eb402129130dedebe9ead2f57f9ec65825b09f1) Asynchronous redemptions with cooldown periods, rescue mechanism for edge cases, access control roles, and performance considerations. [Spectrum Simulator](broken://pages/179a536d520ccb8e2086455ac69ad3b881645bbd) Interactive simulator for modeling pool mechanics, testing scenarios, and sharing configurations. Includes presets, charts, and export/import. ## Security #### Risks/Mitigations **Senior Yield Risk (Protocol)** Priority waterfall: Senior is paid first. Spectrum and Junior tranches absorb all yield shortfalls before Senior is affected. Senior is only impaired in extreme scenarios where all subordinate tranches are fully wiped out. **Spectrum Tranche Risk** Each Spectrum tranche has a defined collateral factor that determines how much loss it absorbs. Lower-cap tranches are paid earlier in the waterfall and are safer; higher-cap tranches offer more upside but absorb more downside. **General Yield risk (sources, underperformance, …)** * Allocate only into vetted / qualified yield sources (Morpho, Aave, Strata/Ethena) * Pluggable allocator architecture enables rapid response to market issues * Active monitoring and alerting on underlying positions * Rescue mechanism available 28 days post-maturity for edge case recovery **Smart contract risk / Security** Knox * Audit Knox Smart Contracts * Follow industry standards: ERC-4626, OpenZeppelin, PRBMath * Access control via centralized AccessController with role-based permissions * EIP-1167 minimal proxies for gas-efficient pool deployment * Rescue mechanism with strict safety rails — asset transfers restricted to tranche vaults only Underlying * Only use blue-chip yield sources * Monitor their security incidents #### Audits After a beta testing period, we will have our smart contracts audited by reputable audit firms and security experts. Until then, we'll provide allowlist access enforced through on-chain access control. Please contact us to obtain access. We clearly advise you to only make small investments pre-audit (i.e. before our public launch). ## Rewards & Tokenomics #### Points Program We will introduce a points program that assigns each protocol user points according to the following metrics: * Deposit size * Tranche: Junior (greatest factor), Spectrum higher caps (higher factor), Spectrum lower caps (moderate factor), Senior (lower factor) * Early bird factor: The earlier you are in using Knox, the higher will be the points multiplier #### Knox Token Based on the points assignment, a fraction of the future Knox token will be distributed to early users. Other (long-term vesting) assignments will be made to the team & investors. Knox will also keep distributing the token through enshrined incentives based on vault usage. ## Resources * Terms of Service - * Privacy Policy - ## Links * Website - * X - * Github - N/A --- # 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.knox.finance/knox-documentation.md?ask= ``` 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.