Bucket Architecture

Buckets segment deposits into 6‑hour epochs, allowing unlocked liquidity to be recycled quickly and enabling near‑instant withdrawals despite Hyperliquid’s 4‑day lock.

Each new deposit joins the active epoch bucket. Funds remain locked for 4 days, but older buckets expire continuously—so most users exit in minutes, not days.

Why Buckets?

Hyperliquid enforces a 4‑day lock after every deposit. Without segmentation, a single fresh deposit would freeze the entire vault. Buckets isolate new capital so mature liquidity stays withdrawable.

  • 6‑hour epoch window balances UX and on‑chain cost.
  • Size‑capped at 2 M USDC to avoid whale‑induced freezes.
  • Users withdrawing only tap buckets whose lock expired.

Ring‑Buffer Architecture

Buckets live in a 4 096‑slot ring. `head` points to the oldest live bucket, `tail` to the next free slot. This constant‑time structure lets the contract append new buckets and prune empty ones with minimal gas.

  • Ring full guard prevents deposits if all slots occupied (extremely unlikely).
  • Pruning deletes buckets whose principal & equity are both zero.
  • Helper contract per bucket handles vault interactions, keeping main wrapper stateless.

Withdrawal Flow

When a user requests an exit, the contract walks the ring from `head`, aggregating unlocked principal until the user’s USD goal is met. Any still‑locked buckets are skipped, so exits settle almost instantly if older liquidity suffices.

  • If unlocked liquidity < request, revert — user can retry after more buckets expire.
  • After buckets are drained to zero, `_pruneFront` advances `head` and frees storage.

Bucket Helpers (`_Bucket`)

Each epoch bucket is represented by a minimal clone of the `_Bucket` contract. This helper is the only contract that holds on‑chain state for that bucket.

  • Immutable `WRAPPER` pointer ensures only the main THLP can call it.
  • Handles `vaultDeposit`, `vaultWithdraw`, and `collateralWithdraw` via CoreWriterLib.
  • Keeps main THLP stateless and gas‑efficient—no per‑bucket storage in wrapper.

Performance Fees & Snapshots

To capture vault‐level gains, each bucket records its `lastEq` (vault equity) at creation or last fee claim.

  • On `claimPerfFee`, the wrapper loops up to N buckets, sums positive equity deltas since `lastEq`, then mints owner shares.
  • After minting, each bucket’s `lastEq` is bumped to the current equity snapshot.
  • This per‑bucket approach avoids scanning the entire ring on every deposit or withdrawal.