HELIX protocol documentation. — invariants, mechanics, surface.

tl;dr

HELIX is a perp DEX on Base L1 implemented as a single immutable contract pair (HelixPerps + HelixHook) that runs over a Uniswap v4 AMM hook. There's no orderbook, no off-chain matcher, no upgrade path, and no admin keys past the deploy-time market registry.

• 24 perp markets · cross-margin USDC · 25× max leverage on majors / 10× on alts
• Mark price is the live AMM pool price, smoothed via 10-min TWAP + Chainlink median
• HLP vault is the counterparty to every position — LPs earn 49% of fees + take residuals
• $HELIX token captures the other 49% (stakers) + perpetual buyback&burn

invariants

The following are enforced at the contract level — no admin can change any of them post-deploy:

• No admin role. No onlyOwner, no proxy, no upgrade path. The INIT_ADMIN address can only call addMarket + lockMarkets until the registry is frozen.
• Market registry is one-shot. Once lockMarkets() fires, no new markets can be added — ever.
• $HELIX supply is fixed. 1B total minted at deploy, no mint function exists. Buybacks burn into 0xdead — supply only decreases.
• HLP drawdown gate. If HLP drops > 8% off peak NAV, withdrawals pause until recovery.
• Founder seed lock. 90 days after deploy, enforced via hlpWithdraw check.
• Reentrancy guard. All user entry points are nonReentrant.

perp engine

positions

Each (trader, marketId) pair owns at most one position. Opening more in the same direction stacks margin and notional; opening opposite reduces or flips the position. Margin moves between the trader's free balance and the position via open() and close().

fees

Maker 0.025%, taker 0.045%. Charged in USDC against the trader's margin on open/close/liquidation.

leverage / margin

funding

Continuous funding rate, settled hourly:

rate = (mark − oracle) / oracle × k
clamp at ±0.05%/hour

Positive rate = longs pay shorts. Negative = shorts pay longs. k is a tunable proportional constant per-market (set at deploy). Settlements run on every beforeSwap via the v4 hook, so funding is always current with the latest mark.

liquidation

A position is liquidatable when its margin ratio (MMR) exceeds 100% — i.e., the maintenance margin requirement consumes more than the current equity. Any wallet can call liquidate(trader, marketId) and receive a 1.0% bounty of seized notional.

Loss waterfall:

1. Liquidator gets 1% bounty (capped at remaining equity).
2. Any positive equity after bounty refunds to the trader's margin account.
3. Negative equity (residual loss) hits the insurance fund first.
4. Anything still uncovered drains HLP.

oracle

2-source mark price: Chainlink aggregator + AMM pool 10-min TWAP, taken as median. If the two diverge by more than 1.5%, the closer source wins (anti-manipulation). All in WAD scaling.

HLP vault

The HELIX Liquidity Pool is the protocol's counterparty. LPs deposit USDC, receive HLP shares minted at the current share price, and earn:

• 49% of every protocol fee (split with $HELIX stakers and the insurance fund)
• The opposite side of every trader's PnL (NAV ticks down when traders win, up when they lose)
• Bonus $HELIX during the bootstrap window (see bootstrap)

HLP withdrawals pause when the vault is > 8% off its peak. Resumed automatically on new high water mark. No admin override.

insurance fund

Capped at $1M USDC. Accrues 2% of every fee until full. Acts as the first buffer for liquidation residuals before HLP. Once capped, overflow routes to HLP. There is no admin withdrawal — funds drain only via liquidation absorption.

bootstrap

Full spec at contract/BOOTSTRAP.md. Summary:

$HELIX token

v4 hook

HelixHook is the Uniswap v4 hook bound to each market's pool. Permissions: beforeSwap + afterSwap only — every other callback reverts at the contract level.

• beforeSwap — settle funding for the bound market + sweep up to 3 flagged liquidations
• afterSwap — record cleared mark price + donate 5 bps of quote to HLP

Bindings are one-shot: bindMarket can only be called by INIT_ADMIN until lockBindings() fires, after which the registry is frozen forever.

contract surface

HelixPerps · trader entries

deposit(amount)
withdraw(amount)
open(marketId, side, marginAdd, notional)
close(marketId, notional)
liquidate(trader, marketId)
hlpDeposit(assets)
hlpDepositWithReferral(assets, referrer)
hlpWithdraw(shares)
bootstrapClaim()
bootstrapClaimable(addr) view
stake(amount) / unstake(amount) / claim()
executeBuyback()
seedFounderDeposit(assets)  // founder only, one-shot
lockMarkets()               // INIT_ADMIN only, one-shot

HelixPerps · hook entries (onlyHook)

settleFunding(marketId, markPriceWad)
sweepLiquidations(marketId, max)
recordMark(marketId, markPriceWad)
donateHLP(marketId, usdcAmount)

risks

• Trader streak. Sustained trader-favorable PnL drains HLP. The 8% drawdown gate caps the speed but not the depth.
• Oracle. Chainlink + AMM TWAP median is robust but not infallible. Manipulation of both sources simultaneously is the worst case.
• Smart contract. Pre-audit code. ToB / Spearbit / Cantina reviews queued. Use sparingly until audits land.
• Liquidity. The protocol assumes deep AMM liquidity on the underlying pairs. Thin markets = wide mark drift = bad funding rates.

audits

Queued: Trail of Bits, Spearbit, Cantina. Reports will be linked here on completion. Nothing is mainnet until at least one independent audit lands.