Primary trader entry point for opening positions with margin, increasing notional with weighted-average strike, adding/removing margin as rescue or optimization, and routing closures and reductions to SettlementEngine
PositionManager handles the full position lifecycle: open, increase, reduce, and margin adjustments. It is the primary entry point for traders interacting with the protocol.
Every position is stored onchain as a Position struct (see Types Reference for full definition):
struct Position { address account; // Owner address bytes32 pairId; // Currency pair identifier (e.g., keccak256("EUR/USD")) Side side; // LONG or SHORT uint256 notional; // Position size in USDC (6 decimals) Tenor tenor; // Maturity tenor (ONE_DAY, ONE_WEEK, ONE_MONTH) uint32 tenorSeconds; // Tenor duration in seconds uint64 openTimestamp; // Block timestamp when opened uint64 fixingTimestamp; // Maturity date (business day adjusted) int256 entryStrike; // Forward price at open (18 decimals) uint64 entryOracleRoundId; // Oracle round ID at open uint256 imLocked; // Locked initial margin (mutable via add/remove) uint256 mmThreshold; // Maintenance margin liquidation threshold PositionStatus status; // OPEN or CLOSED CloseReason closeReason; // Why it was closed (NONE while open) uint64 closeTimestamp; // When closed (0 while open) int256 closePrice; // Settlement price at close (18 decimals) int256 realizedPnl; // Capped PnL used for accounting int256 marketPnl; // Uncapped true mathematical PnL uint16 snapshotImBps; // IM factor at time of open uint16 snapshotMmBps; // MM factor at time of open uint16 snapshotTradingFeeBps; // Trading fee rate at time of open uint16 snapshotLiquidationPenaltyBps; // Liquidation penalty at time of open uint256 snapshotOracleFee; // Oracle fee at time of open MarginMode marginMode; // ISOLATED (M2 only)}
The imLocked field is the only mutable economic field on an open position. It changes when the trader adds or removes margin. All snapshot* fields are immutable after position creation.
function increasePosition(uint256 positionId, uint256 additionalNotional)
Increases an existing position’s notional. Only allowed in NORMAL mode.Preconditions: Owner only, OPEN status, not matured, not liquidatable.The increase uses a weighted average entry strike:
function reducePosition(uint256 positionId, uint256 reductionNotional)
Partially reduces the position. PnL on the reduced portion is settled immediately. Remaining notional must stay above minPositionNotional. Routes to SettlementEngine.
