Appearance

Mark TWAP (Per-Knot Largest-Wins) ​

Overview ​

The protocol computes its own on-chain reference rate -- the Mark Rate -- from executed trades. No external price oracle is needed for the mark; it is derived entirely from protocol state.

The mark rate serves two purposes:

  1. Deviation checks on risk-increasing trades (circuit breaker against manipulation)
  2. Mark-to-market (MTM) calculations for health, margin, and liquidation

With the 8-knot curve engine, the mark system maintains 8 independent TWAP streams, one per knot. The mark rate at any custom tenor is then interpolated from the two bracketing knot marks, exactly mirroring how the mid-rate is interpolated from the curve.

Per-Knot Architecture ​

Why Per-Knot? ​

The curve engine allows different parts of the term structure to move independently. A surge of trading at the 7-day tenor should update the 7-day mark without distorting the 90-day mark. Per-knot TWAPs achieve this naturally: each knot tracks its own history of post-trade endpoint rates.

What Each Knot Tracks ​

Each of the 8 knots (1d, 3d, 7d, 14d, 30d, 60d, 90d, 180d) maintains:

  • A ring buffer of time-bucketed observations
  • A cumulative rate-time integral (for computing the time-weighted average)
  • The current winner for the active time bucket
  • The latest recorded endpoint rate

The Largest-Wins System ​

The Problem It Solves ​

A naive TWAP that records every trade is vulnerable to dust-trade manipulation: an attacker could submit many tiny trades to push the mark rate without meaningful economic commitment. The Largest-Wins design solves this by requiring that within any given time bucket, only the trade with the largest notional size gets to set the recorded rate.

How It Works ​

Time is divided into fixed-duration buckets (e.g., 60-second windows). Within each bucket:

  1. The first eligible trade sets the initial winner for that bucket.
  2. Subsequent trades in the same bucket only replace the winner if their absolute notional exceeds the current winner's notional.
  3. The winner's endpoint rate (the post-trade marginal rate at that knot, not the execution VWAP) is what gets recorded for the TWAP.

This means:

  • Dust trades are ignored. A 0.01 USDC trade cannot update the mark.
  • The largest trade wins. The market participant with the most skin in the game determines the bucket's contribution to the TWAP.
  • Each bucket contributes at most one rate observation. The TWAP cannot be spammed with rapid-fire updates.

Eligibility Filters ​

Not every trade qualifies to compete for bucket winner status:

  • Minimum notional threshold. Trades below a configurable fraction of the market's depth are filtered out entirely. This prevents small trades from even competing.
  • Maximum notional threshold (optional). If enabled, extremely large trades (above a configurable fraction of depth) are also filtered. This can prevent a single whale from dominating every bucket.

Both thresholds are expressed as basis points of the knot's depth, so they scale automatically with market liquidity.

Rate Clamping (Optional) ​

If enabled, the endpoint rate recorded for a bucket winner is clamped relative to the previous rate. This limits how much the mark can move in a single bucket, providing an additional layer of manipulation resistance:

  • The maximum per-bucket move is configured as a fraction of the current rate level (or a floor value, whichever is larger).
  • This prevents a single large trade from instantaneously jumping the mark by an extreme amount.

Computing the Mark Rate ​

At a Knot ​

The mark rate at a specific knot is a standard time-weighted average over a configurable rolling window:

  1. The system maintains a cumulative integral of rate x time at each observation.
  2. To compute the TWAP, it finds the observation at the start of the window and divides the integral difference by the elapsed time.

If the window is longer than available history (e.g., shortly after market creation), the system uses the oldest available observation as the window start, gracefully degrading to a shorter effective window rather than failing.

At Any Tenor ​

To get the mark rate at an arbitrary tenor (e.g., 45 days):

  1. Identify the two bracketing knots (30d and 60d).
  2. Compute each knot's mark rate from its TWAP.
  3. Convert to integrated mark values.
  4. Interpolate between them using the same linear interpolation as the mid-rate curve.
  5. Convert back to an average rate.

This ensures the mark curve has the same shape and continuity properties as the trading curve.

Deviation Checks ​

When They Apply ​

Deviation checks are enforced only on risk-increasing trades (trades that add exposure to the pool). Risk-reducing trades (exits) are always allowed, regardless of how far the execution price is from the mark. This asymmetry ensures traders can always reduce their positions.

What Gets Checked ​

For a risk-increasing trade, the protocol computes the pre-trade mark rate at the traded tenor and defines a deviation band around it. Two rates must fall within this band:

  1. The execution VWAP -- the volume-weighted average rate the trader actually receives. Checking this prevents a trader from executing at an extreme average rate while ending near the mark.
  2. The endpoint rate -- the post-trade marginal rate. Checking this prevents a trader from ending at an extreme price even if the average execution was reasonable.

Both must pass. If either falls outside the deviation band, the trade is rejected.

Deviation Band Calculation ​

The band width scales with the current rate level:

  • A scale value is determined as the larger of the absolute mark rate or a configured floor (preventing the band from collapsing to zero at low rates).
  • The maximum deviation is this scale value multiplied by a configurable factor (in basis points).

For example, with a 500 bps deviation factor and a mark rate of 8%, the band would be 8% +/- 0.40%, so trades must execute between 7.60% and 8.40%.

Recording After Execution ​

After every trade (regardless of risk direction), the engine attempts to record the endpoint rate at each affected knot. A trade at a 45-day tenor affects the 30-day and 60-day knots:

  1. For each affected knot, the engine computes the post-trade average rate at that knot from the updated curve.
  2. It calls record_endpoint_rate on that knot's TWAP with the trade's pricing notional and the knot's depth as the eligibility reference.
  3. The recording may succeed (trade becomes the bucket winner) or silently decline (trade is not eligible or not the largest in the bucket). Either outcome is fine -- no error is raised.

Key Properties ​

PropertyBehavior
Stores endpoint (marginal) ratesYes -- VWAP is never stored, only computed transiently
Per-knot independenceEach knot has its own TWAP stream
Manipulation resistanceLargest-Wins + min/max notional filters + optional rate clamping
Deviation checksRisk-increasing only; both VWAP and endpoint must be in-band
Mark at custom tenorsInterpolated from bracketing knot marks
Window degradationUses oldest available observation if history is shorter than window

Cross References ​

  • Curve Engine -- how knots are updated and interpolation works (see Curve Engine & Execution)
  • Swap Pipeline -- where mark computation and deviation checks fit in the execution flow (see Swap Pipeline)
  • Margin & Liquidation -- how mark rates feed into MTM and health calculations (see Margin & Liquidation)

Jetty Protocol