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
| Function | Paused | Bounds |
|---|---|---|
execute(uint256[] ids) | Opens cancel | At most 100 ids. Skips unknown, finished, and same-block ids, and cancels requests past the window. One request never reverts the batch |
cancelExpired(id) | Allowed | Known, not finished, and past REQUEST_EXPIRY_BLOCKS |
liquidate(clone) | Allowed | Open and liquidatable at the current mark; cancels the clone's pending request |
hedge() returns int256 orderSize | Allowed | HyperCore account activated; cooldown passed; gap at least $10; order at most $250,000 |
fundCorePerp() | Allowed | HyperCore account activated; once per block with rebalanceCoreMargin; moves only the deficit |
rebalanceCoreMargin() | Allowed | HyperCore account activated; once per block with fundCorePerp; moves only the surplus |
bridgeSpotUsdcToEvm() | Allowed | HyperCore account activated; free spot USDC at least $10 |
fundCoreHype() payable | Allowed | msg.value above zero and a multiple of 1e10 |
depositInsuranceBuffer(amount) | Allowed | amount above zero; only adds money |
Administration
| Function | Caller | Effect |
|---|---|---|
proposeParameters(p) | Protocol | Validates p and starts the one-day delay |
applyParameters() | Protocol | Applies the proposal after the delay, checkpointing the borrow index |
proposeInsuranceWithdrawal(to, amount) | Protocol | Queues a withdrawal from the buffer; to nonzero and amount above zero |
applyInsuranceWithdrawal() | Protocol | After the delay, pays out if the amount is within the buffer and free USDC, and equity stays above the floor |
pause() / unpause() | Protocol | Stops 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
| View | Returns |
|---|---|
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
| Event | Fields | Emitted when |
|---|---|---|
OrderRequested | id (indexed), clone (indexed), sizeDelta, collateral, acceptablePrice, isClose | An open or close is requested |
OrderExecuted | id (indexed), clone (indexed), price, fee | A request fills |
OrderCancelled | id (indexed), clone (indexed), reason, refunded | A request is cancelled with a refund |
PositionOpened | clone (indexed), size, margin, entryNotional | An open fills |
PositionClosed | clone (indexed), closedSize, realizedPnl, payout | A close fills |
MarginAdded | clone (indexed), amount | addMargin succeeds |
Liquidated | clone (indexed), liquidator (indexed), equity, penalty, reward, badDebt | A position is liquidated |
FeeCharged | clone (indexed), amount | A borrow fee is charged |
Claimed | clone (indexed), amount, remaining | claim pays out |
Hedged | unhedgedSize, orderSize, cloid | hedge sends an IOC order |
InsuranceBufferUpdated | oldBalance, newBalance | The buffer changes |
InsuranceWithdrawalProposed | to (indexed), amount, eta | The protocol queues a withdrawal |
CoreMarginRebalanced | bridgedToCore, withdrawnFromCore | fundCorePerp or rebalanceCoreMargin moves margin |
CoreHypeFunded | sender (indexed), evmHypeAmount | fundCoreHype sends HYPE |
ParametersProposed | parameters, eta | The protocol proposes parameters |
ParametersUpdated | parameters | Parameters are applied |
Errors
Requests and positions
| Error | Cause |
|---|---|
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
| Error | Cause |
|---|---|
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
| Error | Cause |
|---|---|
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
| Error | Cause |
|---|---|
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 |