Appearance

Accounts ​

On-chain account structures for the Jetty Protocol.

Account Overview ​

AccountTypeDescription
PoolPDA ["pool", shares_mint]Liquidity vault, risk parameters
MarketKeypairSwap instrument with curve engine, caps, fees
MarginKeypairUser collateral + embedded positions
RateOracleKeypairCumulative funding index
OracleHistoryPDA ["oracle_history", oracle, tree_index]Merkle tree of historical oracle snapshots

Pool ​

The Pool is the protocol's central liquidity vault and acts as the dealer (counterparty) for every trade. LPs deposit quote tokens (e.g., USDC) and receive LP shares representing their proportional claim on pool equity. The pool takes the opposite side of all trader positions: when a trader goes long, the pool goes short, and vice versa. Pool equity backs all open positions and determines how much risk the protocol can accept, governed by DV01-based reserve requirements and utilization curves that scale available depth as risk increases.

The pool holds references to its quote mint, quote vault (token account), and LP shares mint. It tracks total trader collateral across all margin accounts for LP NAV calculation, and maintains a registry of up to 16 markets.

Risk is bounded by configurable parameters: a max rate move (bps) for DV01 reserve calculation, utilization kink and max thresholds that control depth scaling, pool-wide OI and DV01 caps, and a maximum LP equity cap (AUM ceiling). The pool also allocates liquidity and DV01 budget across markets using per-market weights.

PDA Seeds: ["pool", shares_mint.key()]

Market ​

Swap instrument defined by (asset, venue). Each market is a rolling-perpetual with no fixed maturity date. Instead, positions expire into discrete time buckets within a continuously advancing window. As time passes, the window rolls forward and expired buckets are recycled, making the market perpetual while still supporting fixed-tenor positions (e.g., 7-day, 30-day, or 1-year swaps).

Curve Engine ​

Each market embeds an 8-knot curve engine that maintains a term structure of integrated funding values across maturities from 1 to 180 days. Rates for any tenor are produced by interpolating between bracketing knots. Trade execution is handled by a stateless 3-tranche Impact Kernel (Core, Mezzanine, Tail) that determines price impact using concentrated liquidity mechanics. The engine supports negative rates via a configurable rate offset.

Pool Counterparty State ​

The market tracks the pool's cumulative rate payments, net notional exposure (negative of trader sum), weighted-average entry rate, and funding index snapshot.

Fee Parameters ​

The base swap fee defaults to 10 bps with a 25% protocol / 75% LP split. Six dynamic fee components (utilization, deviation, oracle staleness, inventory, volatility) each have configurable maximums, and asymmetric multipliers allow risk-increasing trades to be charged more than risk-reducing trades. A hard fee cap bounds the total.

Margin Parameters ​

Initial and maintenance margin requirements (in bps), liquidation penalty, and floor-based margin parameters (rate floor, IM/MM multipliers) that prevent margin from collapsing at low rates or near expiry.

Capacity Caps ​

Gross OI cap, per-position notional cap, gross DV01 cap, and a risk weight that determines how the market counts against pool-level caps. Each market also has a minimum time floor for DV01 calculation, and liquidity/DV01 weights for pool budget allocation.

Mark TWAP ​

Each of the 8 knots maintains its own independent Mark TWAP with a ring buffer of observations for manipulation-resistant mark rate computation. Key parameters include the minimum notional to be eligible, deviation band factor, bucket duration, window duration, and a ring buffer of up to 256 observations per knot. The mark rate at any tenor is interpolated from the two bracketing knot marks.

MarketStatus ​

ValueNameDescription
0NormalAll trades allowed
1ClosingOnlyOnly risk-reducing trades
2HaltedOnly liquidations

Margin ​

Cross-margin account linked to a single pool. A user can create multiple margin accounts. Each holds collateral (quote tokens) and up to 16 embedded positions across different markets. Collateral is shared across all positions within the account, so a single deposit backs the entire portfolio. Health is computed as equity (collateral + realized PnL + unrealized mark-to-market) minus maintenance margin requirements. When health drops below zero, the account becomes eligible for liquidation.

Each position tracks the market it belongs to, its signed notional exposure, weighted-average entry rate, oracle index at last settlement, accumulated realized PnL, and open/update timestamps. Empty slots have a default market pubkey.

Sign Convention ​

notional > 0  →  PAY FIXED / RECEIVE FLOATING
                 Profits when rates rise

notional < 0  →  RECEIVE FIXED / PAY FLOATING
                 Profits when rates fall

Funding Settlement ​

funding_delta = notional × (F_now - F_last)

Where F(t) is the oracle's cumulative funding index.

RateOracle ​

Cumulative funding rate index that tracks the floating rate for settlement. Each oracle maintains a monotonically-advancing rate index. The difference between two index snapshots gives the realized floating rate over that period. Updates can be permissioned or permissionless depending on the funding source, and are subject to sanity bounds that limit the maximum rate change per second and per update, preventing erroneous or malicious data from propagating through the protocol.

The oracle also tracks an EWMA variance of rate changes (λ = 0.95), used for volatility-scaled fees, and enforces a configurable staleness window.

OracleHistory ​

Append-only Merkle tree that stores historical oracle snapshots. Each time the oracle is updated, a leaf is appended containing the timestamp range and rate index delta for that period. This enables trustless verification of historical rates without storing the full history on-chain. Trees have configurable depth (3–16, determining capacity from 8 to 65,536 leaves) and canopy depth (0–7, caching upper tree levels to reduce proof size). When a tree fills, it is sealed and a new tree is created, and the oracle tracks the active tree index for seamless rotation.

PDA Seeds: ["oracle_history", oracle_pubkey, tree_index_le_bytes]

Account Relationships ​

Pool
 │
 ├── quote_mint (SPL Token Mint)
 ├── quote_vault (SPL Token Account)
 ├── shares_mint (SPL Token Mint)
 │
 ├── Market[0..16]
 │    ├── oracle (RateOracle)
 │    │    └── OracleHistory[0..N] (PDA, Merkle trees)
 │    ├── curve_engine (8-knot term structure + impact config)
 │    └── mark_twap_knots[8] (per-knot MarkTwapState)
 │
 └── Margin[] (per user)
      └── Position[0..16] (embedded)
           └── market → Market

Jetty Protocol