Opertus

Vault reference

Perpetual vault entry points, views, events, and custom errors.

Each market is one OpertusPerpVault, which inherits its HyperCore reads and CoreWriter actions from CoreHedgeModule. External calls go only to the USDC token, CoreWriter, and the HyperCore read precompiles. There are no callbacks into user code, and state is written before any token transfer. Every entry point is nonReentrant. USDC amounts use 6 decimals.

Clone entry points

These use msg.sender as the position's clone. Call them through an unshield with calldata, as described in trading.

requestOpen

function requestOpen(
    int256 sizeDelta,        // positive for a long, negative for a short
    uint256 collateral,      // pays the trade fee; the rest is margin
    uint256 acceptablePrice  // most a long pays, least a short receives
) external returns (uint256 id);

Blocked while paused. The clone must be unused, sizeDelta nonzero and within int128, and collateral and acceptablePrice above zero. At the current mark, notional must be between $10 and maxPositionNotionalUsdc, and collateral at most notional. Pulls collateral from the clone and locks it. An acceptablePrice above the uint128 maximum is stored as that maximum, which also means no limit.

requestClose

function requestClose(uint256 closeSize, uint256 acceptablePrice)
    external returns (uint256 id);

Allowed while paused. Requires an open position, no pending request, 0 < closeSize ≤ |size|, a price above zero, and MIN_HOLD_TIME since opening unless the position is liquidatable.

addMargin and claim

function addMargin(uint256 amount) external;
function claim() external returns (uint256 amount);

Both are allowed while paused. addMargin charges the accrued borrow fee, then adds margin up to entry notional. claim pays the smaller of claimable and freeVaultUsdc(), and leaves the rest claimable.

Permissionless entry points

FunctionPausedBounds
execute(uint256[] ids)Opens cancelAt most 100 ids. Skips unknown, finished, and same-block ids, and cancels requests past the window. One request never reverts the batch
cancelExpired(id)AllowedKnown, not finished, and past REQUEST_EXPIRY_BLOCKS
liquidate(clone)AllowedOpen and liquidatable at the current mark; cancels the clone's pending request
hedge() returns int256 orderSizeAllowedHyperCore account activated; cooldown passed; gap at least $10; order at most $250,000
fundCorePerp()AllowedHyperCore account activated; once per block with rebalanceCoreMargin; moves only the deficit
rebalanceCoreMargin()AllowedHyperCore account activated; once per block with fundCorePerp; moves only the surplus
bridgeSpotUsdcToEvm()AllowedHyperCore account activated; free spot USDC at least $10
fundCoreHype() payableAllowedmsg.value above zero and a multiple of 1e10
depositInsuranceBuffer(amount)Allowedamount above zero; only adds money

Administration

FunctionCallerEffect
proposeParameters(p)ProtocolValidates p and starts the one-day delay
applyParameters()ProtocolApplies the proposal after the delay, checkpointing the borrow index
proposeInsuranceWithdrawal(to, amount)ProtocolQueues a withdrawal from the buffer; to nonzero and amount above zero
applyInsuranceWithdrawal()ProtocolAfter the delay, pays out if the amount is within the buffer and free USDC, and equity stays above the floor
pause() / unpause()ProtocolStops or resumes opens only

Admin calls are restricted to the protocol multisig through OpenZeppelin Ownable2Step (onlyOwner).

Types

struct Position {
    int256 size;           // positive for a long, negative for a short
    uint256 margin;
    uint256 entryNotional;
    uint64 openedAt;       // timestamp
    uint64 lastBorrowAt;   // timestamp of the last borrow charge
    bool isOpen;
    uint256 borrowIndex;   // borrow index at the last charge
}

struct OrderRequest {
    address clone;
    int256 sizeDelta;
    uint256 collateral;    // 0 for a close
    uint256 acceptablePrice;
    uint64 requestBlock;
    bool isClose;
    bool done;
}

struct LeverageTier {
    uint256 maxOpenInterestUsdc;
    uint256 maxLeverage;
}

enum CancelReason {
    Price, Paused, Leverage, PositionCap, EquityFloor,
    OpenInterestCap, UnhedgedCap, Remainder, Expired, Liquidated
}

Parameters holds the twelve protocol-tunable values listed in parameters, with leverageTiers as LeverageTier[3].

Remainder cancels a partial close that would leave less than $10. Liquidated cancels a pending request when its position is liquidated.

Views

ViewReturns
positions(clone)size, margin, entryNotional, openedAt, lastBorrowAt, isOpen
getRequest(id)The OrderRequest
pendingRequestOf(clone)The clone's pending request id, or 0
usedClones(clone)Whether the clone has opened a position
claimable(clone)USDC credited to the clone and not yet claimed
quote(sizeDelta)The fill price and fee at the current mark
getParameters()The live Parameters
protocolEquity()Protocol equity, signed
unhedgedUsdc()The gap between net size and szi, valued at the mark
freeVaultUsdc()HyperEVM USDC not backing margin or locked collateral
getRequiredCoreMarginUsdc(markPrice)The HyperCore account value the hedge needs
markPriceUsdc(), coreNetSize(), coreAccountValue(), withdrawableUsdc(), coreUserExists()HyperCore reads: mark, szi, account value, withdrawable USDC, and whether the account is activated

Public state includes USDC, LEVERAGE_CEILING, internalNetSize, netEntryNotional, grossOpenSize, totalIsolatedMargin, totalLockedCollateral, totalClaimable, insuranceBuffer, nextRequestId, parametersEta, lastHedgeTime, and lastCoreMarginBlock.

Events

EventFieldsEmitted when
OrderRequestedid (indexed), clone (indexed), sizeDelta, collateral, acceptablePrice, isCloseAn open or close is requested
OrderExecutedid (indexed), clone (indexed), price, feeA request fills
OrderCancelledid (indexed), clone (indexed), reason, refundedA request is cancelled with a refund
PositionOpenedclone (indexed), size, margin, entryNotionalAn open fills
PositionClosedclone (indexed), closedSize, realizedPnl, payoutA close fills
MarginAddedclone (indexed), amountaddMargin succeeds
Liquidatedclone (indexed), liquidator (indexed), equity, penalty, reward, badDebtA position is liquidated
FeeChargedclone (indexed), amountA borrow fee is charged
Claimedclone (indexed), amount, remainingclaim pays out
HedgedunhedgedSize, orderSize, cloidhedge sends an IOC order
InsuranceBufferUpdatedoldBalance, newBalanceThe buffer changes
InsuranceWithdrawalProposedto (indexed), amount, etaThe protocol queues a withdrawal
CoreMarginRebalancedbridgedToCore, withdrawnFromCorefundCorePerp or rebalanceCoreMargin moves margin
CoreHypeFundedsender (indexed), evmHypeAmountfundCoreHype sends HYPE
ParametersProposedparameters, etaThe protocol proposes parameters
ParametersUpdatedparametersParameters are applied

Errors

Requests and positions

ErrorCause
ZeroAmount()A zero collateral, margin, deposit, or HYPE amount
ZeroSize()sizeDelta is zero
InvalidPrice()acceptablePrice is zero
SizeTooLarge(absSize)The size does not fit in int128
OrderBelowMinNotional(notionalUsdc, minNotionalUsdc)Notional is below $10
NotionalTooLarge(notional, maxNotional)Notional is above maxPositionNotionalUsdc
CollateralAboveNotional(collateral, notional)Collateral exceeds notional
MarginAboveNotional(margin, entryNotional)addMargin would take margin above entry notional
CloneAlreadyUsed(clone)The clone already opened a position
RequestPending(clone, id)The clone already has a pending request
NoOpenPosition(clone)The clone has no open position
InvalidCloseSize(closeSize, positionSize)closeSize is zero or above the position size
HoldTimeNotMet(readyAt)A close came before MIN_HOLD_TIME on a healthy position
NothingToClaim(clone)The clone's claimable is zero
InsufficientFreeVaultUsdc(requested, available)No free HyperEVM USDC to pay a claim or withdrawal

Execution and liquidation

ErrorCause
BatchTooLarge(length, maxLength)execute was given more than 100 ids
RequestNotFound(id)cancelExpired was given an unknown or finished id
RequestNotExpired(expiresAtBlock)cancelExpired was called inside the window
PositionHealthy(clone, marginRatioBps, maintenanceMarginBps)liquidate was called on a healthy position
InvalidOraclePrice()HyperCore returned a zero mark price

HyperCore

ErrorCause
CoreAccountNotActivated()The vault's HyperCore account does not exist yet
HedgeCooldown(readyAt)hedge was called within HEDGE_COOLDOWN
CoreMarginMovedThisBlock()HyperCore margin already moved in this block
InsufficientCoreHypeGas(availableWei, requiredWei)The HyperCore account lacks HYPE for a transfer back to HyperEVM
PrecisionLossHypeDust(evmHypeAmount)fundCoreHype was sent an amount that is not a multiple of 1e10

Administration

ErrorCause
InvalidParameters()Proposed parameters are out of bounds, or a withdrawal has a zero address or amount
ChangeNotReady(eta, currentTimestamp)A proposal is missing or its delay has not passed
InsufficientInsuranceBuffer(requested, available)A withdrawal exceeds the buffer
ProtocolEquityTooLow(equityUsdc, minEquityUsdc)A withdrawal would take equity below the floor

On this page