Integration Guide

This guide shows developers how to integrate with Knox Protocol: depositing, querying positions, and withdrawing.

Quick Start

1

Find a Pool

Pools are deployed via SpectrumFactory. Query deployment events or maintain an off-chain index.

// Listen for pool deployments
event PoolDeployed(
    address indexed accountant,
    address indexed seniorVault,
    address indexed juniorVault,
    address allocator,
    address underlyingMarket
);

2

Check Pool Parameters

ISpectrumAccountant accountant = ISpectrumAccountant(accountantAddress);

// Core parameters
uint128 seniorAPY = accountant.rSenior(); // e.g., 500 = 5%
uint128 maxSpectrumAPY = accountant.rMaxSpectrum(); // e.g., 2000 = 20%
uint128 gridStep = accountant.spectrumGridStep(); // e.g., 50 = 0.5%
uint128 period = accountant.dPeriod(); // seconds
uint256 maturity = accountant.tStart() + period;

// Capacity
uint256 seniorCap = accountant.seniorCapacity();
uint256 maxTotal = accountant.cMaxTotalDeposits();

// Fee
uint128 protocolFee = accountant.cProtocolFee(); // e.g., 500 = 5%

3

Choose Your Tranche

Decision Tree:

Want guaranteed returns? → Senior

Want a specific cap with downside protection? → Spectrum (choose APY on grid)

Want maximum upside? → Junior

Depositing

Via Router (Recommended)

The KnoxRouter provides the cleanest UX:

Senior Deposit

// Standard ERC20 approval
IERC20(asset).approve(address(router), amount);
router.depositSeniorSpectrum(accountant, amount, receiver);

// OR with Permit2 (no approval needed)
router.depositSeniorSpectrumPermit2(
    accountant,
    amount,
    receiver,
    permit2Signature
);

Spectrum Deposit

// Choose an APY on the grid
uint128 desiredAPY = 700; // 7%

// Validate it's on the grid
require(desiredAPY > seniorAPY && desiredAPY <= maxSpectrumAPY);
require((desiredAPY - seniorAPY) % gridStep == 0);

// Deposit
IERC20(asset).approve(address(router), amount);
router.depositSpectrumTranche(accountant, desiredAPY, amount, receiver);

// OR with Permit2
router.depositSpectrumTranchePermit2(
    accountant,
    desiredAPY,
    amount,
    receiver,
    permit2Signature
);

Junior Deposit

IERC20(asset).approve(address(router), amount);
router.depositJuniorSpectrum(accountant, amount, receiver);

// OR with Permit2
router.depositJuniorSpectrumPermit2(
    accountant,
    amount,
    receiver,
    permit2Signature
);

Via Accountant (Direct)

// Senior
IERC20(asset).approve(address(accountant), amount);
accountant.depositSenior(amount, receiver);

// Spectrum
IERC20(asset).approve(address(accountant), amount);
accountant.depositSpectrum(apyBps, amount, receiver);

// Junior
IERC20(asset).approve(address(accountant), amount);
accountant.depositJunior(amount, receiver);

Via Vault (ERC4626)

Only for existing vaults (cannot create new spectrum vaults):

address seniorVault = accountant.seniorTranche();
address juniorVault = accountant.juniorTranche();

// For spectrum, query existing vault
address spectrumVault = accountant.spectrumVaults(apyBps);
require(spectrumVault != address(0), "Vault doesn't exist yet");

// Deposit
IERC20(asset).approve(vaultAddress, amount);
IERC4626(vaultAddress).deposit(amount, receiver);

Querying Positions

Tranche Shares

// Get vault addresses
address seniorVault = accountant.seniorTranche();
address juniorVault = accountant.juniorTranche();
address spectrumVault = accountant.spectrumVaults(apyBps);

// Check balances
uint256 seniorShares = IERC4626(seniorVault).balanceOf(user);
uint256 juniorShares = IERC4626(juniorVault).balanceOf(user);
uint256 spectrumShares = IERC4626(spectrumVault).balanceOf(user);

Current Tranche Values

// Senior value (compounded)
uint256 seniorValue = accountant.seniorTrancheCurrentValue();

// Spectrum value (compounded to cap)
uint256 spectrumValue = accountant.spectrumTrancheCurrentValue(apyBps);

// Junior value (residual after waterfall)
uint256 juniorValue = accountant.juniorTrancheCurrentValue();

User Share Value

// Senior
uint256 seniorAssets = (seniorShares * seniorValue) / IERC4626(seniorVault).totalSupply();

// Spectrum
uint256 spectrumAssets = (spectrumShares * spectrumValue) / IERC4626(spectrumVault).totalSupply();

// Junior
uint256 juniorAssets = (juniorShares * juniorValue) / IERC4626(juniorVault).totalSupply();

Pool State

enum PoolState { DEPLOYED, ACTIVE, REDEEMED, SETTLED }

PoolState state = accountant.poolState();

// Check if matured
bool matured = block.timestamp >= accountant.tStart() + accountant.dPeriod();

// Check async redemptions
if (state == PoolState.REDEEMED) {
    uint256 pendingExits = accountant.pendingExitCount();
    uint256 latestUnlock = accountant.maxPendingExitUnlockAt();
}

Underlying Asset Value

// Total pool value from underlying market
uint256 underlyingValue = accountant.underlyingAssetCurrentValue();

// Asset address
address asset = accountant.asset();

Withdrawing

After Settlement

Once the pool is in SETTLED state:

require(accountant.poolState() == PoolState.SETTLED, "Not settled yet");

// Redeem all shares from a tranche
uint256 shares = IERC4626(vaultAddress).balanceOf(user);
uint256 assets = IERC4626(vaultAddress).redeem(
    shares,
    receiver, // receives assets
    owner     // owns the shares
);

Note: The last redeemer of a tranche gets the entire remaining balance (not a calculated proportion) to prevent dust.

Before Settlement

Withdrawals are blocked. However, tranche tokens are ERC-20s and can be:

• Transferred to another address

• Sold on secondary markets

• Used as collateral

// Transfer shares
IERC20(vaultAddress).transfer(recipient, shares);

// Approve for trading
IERC20(vaultAddress).approve(dexRouter, shares);

Monitoring Settlement

Check Redemption Progress

// Pool state
PoolState state = accountant.poolState();

if (state == PoolState.ACTIVE && block.timestamp >= maturity) {
    // Matured but not yet redeemed
    // Anyone can call redeemShares()
}

if (state == PoolState.REDEEMED) {
    // Redemption in progress
    uint256 pending = accountant.pendingExitCount();
    if (pending > 0) {
        // Async redemptions pending
        uint256 unlock = accountant.maxPendingExitUnlockAt();
        // Cooldown expires at `unlock` timestamp
        // Anyone can call claimRedeemedAssets() after cooldowns
    }
}

if (state == PoolState.SETTLED) {
    // Settlement complete, withdrawals open
}

Trigger Redemption (Permissionless)

// After maturity, anyone can call
accountant.redeemShares(0); // 0 = redeem all

// For async allocators, claim when ready
accountant.claimRedeemedAssets();

Advanced: Reading Waterfall Results

Per-Tranche Payouts

// Only available after SETTLED
require(accountant.poolState() == PoolState.SETTLED);

// Each vault's balance is its final payout
uint256 seniorPayout = IERC20(asset).balanceOf(seniorVault);
uint256 juniorPayout = IERC20(asset).balanceOf(juniorVault);
uint256 spectrumPayout = IERC20(asset).balanceOf(spectrumVault);

Protocol Fee Collected

// Protocol fee beneficiary balance increased by fee amount
address feeBeneficiary = accountant.protocolFeeBeneficiary();
uint256 feeBalance = IERC20(asset).balanceOf(feeBeneficiary);

Common Patterns

Deposit & Track Pattern

contract MyVaultIntegration {
    struct Position {
        address vault;
        uint256 shares;
        uint256 depositTimestamp;
    }

    mapping(address => Position[]) public userPositions;

    function depositAndTrack(address accountant, uint128 apyBps, uint256 amount) external {
        // Deposit
        IERC20(asset).transferFrom(msg.sender, address(this), amount);
        IERC20(asset).approve(router, amount);

        address vault;
        if (apyBps == 0) {
            // Senior
            router.depositSeniorSpectrum(accountant, amount, address(this));
            vault = ISpectrumAccountant(accountant).seniorTranche();
        } else {
            // Spectrum
            router.depositSpectrumTranche(accountant, apyBps, amount, address(this));
            vault = ISpectrumAccountant(accountant).spectrumVaults(apyBps);
        }

        // Track
        uint256 shares = IERC4626(vault).balanceOf(address(this));
        userPositions[msg.sender].push(Position({
            vault: vault,
            shares: shares,
            depositTimestamp: block.timestamp
        }));
    }
}

Auto-Withdraw Pattern

function autoWithdraw(address accountant, address user) external {
    require(ISpectrumAccountant(accountant).poolState() == PoolState.SETTLED, "Not settled");

    Position[] memory positions = userPositions[user];
    for (uint256 i = 0; i < positions.length; i++) {
        uint256 shares = IERC4626(positions[i].vault).balanceOf(address(this));
        if (shares > 0) {
            IERC4626(positions[i].vault).redeem(shares, user, address(this));
        }
    }

    delete userPositions[user];
}

Error Handling

Common Errors

// Capacity exceeded
if (amount + currentSeniorDeposits > accountant.seniorCapacity()) {
    revert("Senior capacity exceeded");
}

// Spectrum rate not on grid
if ((apyBps - seniorAPY) % gridStep != 0) {
    revert("Rate not on grid");
}

// Pool matured
if (block.timestamp >= accountant.tStart() + accountant.dPeriod()) {
    revert("Pool has matured");
}

// Total deposits cap
if (totalDeposits + amount > accountant.cMaxTotalDeposits()) {
    revert("Total deposits cap exceeded");
}

Frontend Integration Example

React Hook

import { useContractRead } from 'wagmi';

function usePoolInfo(accountantAddress: string) {
    const { data: seniorAPY } = useContractRead({
        address: accountantAddress,
        abi: accountantABI,
        functionName: 'rSenior',
    });

    const { data: maxSpectrumAPY } = useContractRead({
        address: accountantAddress,
        abi: accountantABI,
        functionName: 'rMaxSpectrum',
    });

    const { data: gridStep } = useContractRead({
        address: accountantAddress,
        abi: accountantABI,
        functionName: 'spectrumGridStep',
    });

    const { data: seniorCapacity } = useContractRead({
        address: accountantAddress,
        abi: accountantABI,
        functionName: 'seniorCapacity',
    });

    // Compute spectrum grid
    const spectrumGrid = React.useMemo(() => {
        if (!seniorAPY || !maxSpectrumAPY || !gridStep) return [];
        const rates = [];
        for (let rate = seniorAPY + gridStep; rate <= maxSpectrumAPY; rate += gridStep) {
            rates.push(rate);
        }
        return rates;
    }, [seniorAPY, maxSpectrumAPY, gridStep]);

    return { seniorAPY, maxSpectrumAPY, gridStep, seniorCapacity, spectrumGrid };
}

Key Takeaways

• Use the router for deposits — cleaner UX, handles approvals

• Permit2 variants eliminate approval transactions

• Tranche tokens are ERC-20s — transferable before settlement

• Withdrawals only after SETTLED — monitor pool state

• Permissionless redemption — anyone can trigger after maturity

• Async markets may have cooldown periods — check maxPendingExitUnlockAt()

• Last redeemer gets dust — no rounding issues