Private perps hold a position on the on-chain engine as a note. The owner is hidden. Size and price stay public, because the vault's solvency depends on them.
How it works
The engine does not care whether a position's owner is a person or a contract. It makes no callbacks, and every payout names a receiver, so an adapter can send proceeds straight to custody.
PerpAdapter owns every position on the engine and exposes each one as a single share, held in custody the way a DLMM bin share is. So a position is a note, the join-split circuit proves who owns it, and it can move to another key with a private transfer.
A proof binds its outputs before anything runs, and the engine numbers positions as they open. So a note cannot name the engine's id. Its share id is random and chosen by the note's owner, and positionOf maps it to the position.
| Action | Spends | Comes back |
|---|---|---|
| Open | A USDG note, all of it margin | The position note |
| Add margin | Any USDG note | Nothing but change. It can only help whoever holds the position |
| Increase | The position note | The position note |
| Decrease | The position note | The position note and a USDG note |
| Close | The position note | A USDG note |
claimLiquidated | The position note | A USDG note with what a liquidation left |
emergencyClose | The position note | A USDG note with the margin, once a market's feed has died |
| Hand over | The position note | A position note for another key, by private transfer. Nothing on the engine changes |
Only the share released in that very action can be acted on. More margin and more size together take two proofs.
An open, an increase, a close or a change of size takes its limit from the oracle's price and slippageBps, 100 by default, unless you pass a limitPrice. limitPrice: 0n says no limit. With no oracle price to go by, the call throws.
Fees
A share of 1 is too small for a protocol fee to round above zero. So a position pays the 0.10 % once, on the margin going in, at the open and on any margin you add. Close, decrease, increase, the claims and a hand-over pay no 0.10 %. The engine's open and close fees apply as on any position.
A position note pays a relayer only from private WETH, so keep a small WETH note. Otherwise the spend goes from a fresh address with no relayer fee.
In the app
The on-chain perps ticket on Trade has a public or private switch, and position notes sit in the Positions tab. Manage on a note opens a drawer with Close, Reduce, Add size, Margin and Hand over. A liquidated note offers its claim, and a dead market its emergency close. Lighter stays public.
What the chain shows
The market, the direction, the size, the entry, the margin and every later change, as with any position on the engine. ShareOpened ties the share id to the engine's position, so anyone can follow one position through its changes. What is missing is the wallet behind it. What each lane shows has the table.
Keeping it working
Liquidation, funding and closed-market rules are the engine's, so a private position behaves like a public one. Nothing in the adapter can block a liquidation, and what it leaves waits for the share's holder. A private position that is close to liquidation needs a proof to add margin, and your browser has to build it, so keep some room.
Leaving without an action
A position note released to any address but the adapter settles on the spot, the way a bin share pays its tokens: the position closes at the oracle, or takes its margin out of a dead market, or claims what a liquidation left, and that address gets the payout. That is the exit for a plain withdrawal and for a tree too full to hold an action's leaves.
Funding Lighter privately
Lighter stays as the public perp and hedge venue. A private withdrawal can fund it from a fresh address, so your Lighter account does not lead back to your main wallet. See Perps on Lighter.
contracts/src/shielded/adapters/PerpAdapter.solshares, operations and settling on releasecontracts/src/perps/PerpEngine.solthe engine it runs onpackages/zk/src/lanes.tsprivatePerpOpen and the rest, from the browser