Custom Types

Boros heavily uses Solidity user-defined value types for gas optimization and type safety. These types use bit-packing to minimize storage costs and provide efficient operations on the EVM.

Core Trading Types

Trade

Definition: type Trade is uint256

Bit Packing: signedSize(128) | signedCost(128)

// Creating trades
Trade memory trade = TradeLib.from(signedSize, signedCost);

Side side = trade.side();
int128 size = trade.signedSize();
int128 cost = trade.signedCost();

Account Types

Account

Definition: type Account is bytes21

Bit Packing: address(160) | accountId(8)

// Creating accounts
Account mainAcc = AccountLib.from(userAddress, 0);  // Main account
Account subAcc = AccountLib.from(userAddress, 1);   // Sub-account 1
Account ammAcc = userAddress.toAMM();               // AMM account 255

// Parsing accounts
address root = account.root();         // Extract root address
uint8 accountId = account.accountId(); // Extract account ID

// Special account types
bool isMain = account.isMain();       // accountId == 0
bool isAMM = account.isAMM();         // accountId == 255

MarketAcc

Definition: type MarketAcc is bytes26

Bit Packing: address(160) | accountId(8) | tokenId(16) | marketId(24)

// Creating market accounts
MarketAcc crossAcc = account.toCross(tokenId);                 // Cross-margin
MarketAcc isolatedAcc = account.toIsolated(tokenId, marketId); // Isolated

// Parsing market accounts
address root = crossAcc.root();
Account account = crossAcc.account();
TokenId tokenId = crossAcc.tokenId();
MarketId marketId = crossAcc.marketId();

// Cross vs isolated margin
bool isCross = isolatedAcc.isCross();
MarketAcc crossAcc = isolatedAcc.toCross();

Order Book Types

OrderId

Definition: type OrderId is uint64

Bit Packing: initialized(1) | reserved(6) | side(1) | encodedTick(16) | orderIndex(40)

// Creating order IDs (done internally by order book)
OrderId orderId = OrderIdLib.from(Side.LONG, tickIndex, orderIndex);

// Parsing order IDs
Side side = orderId.side();
int16 tick = orderId.tickIndex();
uint40 index = orderId.orderIndex();

// Priority comparison (lower unwrapped value = higher priority)
bool higherPriority = orderId1 < orderId2;

Side

Definition: enum Side { LONG, SHORT }

Side opposite = side.opposite();          // LONG ↔ SHORT
bool topDown = side.sweepTickTopDown();   // LONG: true, SHORT: false
int16 endTick = side.endTick();          // Boundary tick values

TimeInForce

Definition: enum TimeInForce { GTC, IOC, FOK, ALO, SOFT_ALO }

• GTC (Good Till Cancel): Standard limit order that remains on the order book until fully filled or manually canceled. With placeSingleOrder, a GTC order can match against existing order book and AMM liquidity; any unfilled remainder stays on the book as a maker order. With bulkOrders, GTC orders are placed directly on the book without AMM matching.
• IOC (Immediate or Cancel): Executes against available liquidity (order book + AMM) immediately, cancels any unfilled portion. Best for taker orders — guarantees no residual maker orders remain on the book.
• FOK (Fill or Kill): Must fill entire order size immediately (from order book + AMM) or the transaction reverts. Use when partial fills are unacceptable.
• ALO (Add Liquidity Only): Also known as Post-Only. Ensures the order is placed as a maker order only — the transaction reverts if it would immediately match against existing orders or the AMM. Ideal for market makers who want to guarantee maker status.
• SOFT_ALO: Similar to ALO (Post-Only), but instead of reverting, it silently skips any portion that would match and places the rest on the book. Useful for market makers who prefer no-revert behavior.

OrderStatus

Definition: enum OrderStatus { NOT_EXIST, OPEN, PENDING_SETTLE, PURGED }

• NOT_EXIST: Order has never been placed or has been cancelled
• OPEN: Active order in the order book, available for matching against incoming orders
• PENDING_SETTLE: Order has been filled
• PURGED: Order was purged because rate is out of bound

Market Types

MarketStatus

Definition: enum MarketStatus { PAUSED, CLO, GOOD }

• PAUSED (0): Market is fully paused — no trading, no order placement, no cancellation
• CLO (1): Close-Only mode — only orders that reduce existing position size are allowed. New position opening is prohibited. Activated when open interest approaches risk limits
• GOOD (2): Normal operating mode — all trading operations are available

Markets transition between states based on risk conditions (e.g., open interest approaching caps). Query the current status via getMarketConfig().

LiqSettings

Definition: struct LiqSettings { uint64 base, uint64 slope, uint64 feeRate }

Parameters governing liquidation incentives:

• base: Base incentive factor for liquidators
• slope: Scaling factor that increases incentive as health ratio decreases
• feeRate: Fee rate charged on liquidated positions (goes to protocol treasury)

See Margin — Liquidation Process for the incentive formula.

TokenId

Definition: type TokenId is uint16

Unique identifier for collateral tokens supported by the protocol.

MarketId

Definition: type MarketId is uint24

Special Value: The value type(uint24).max (16,777,215) is reserved as MarketIdLib.CROSS to indicate cross-margin mode, where collateral is shared across all markets within the same collateral zone.

// Cross-margin constant
MarketId crossMargin = MarketIdLib.CROSS;  // type(uint24).max

// Regular market IDs for isolated margin
MarketId market1 = MarketId.wrap(1);       // Isolated margin for market 1
MarketId market2 = MarketId.wrap(2);       // Isolated margin for market 2

// Checking margin mode
bool isCross = marketId.isCross();         // true if marketId == CROSS

AMMId

Definition: type AMMId is uint24

Advanced Types

FIndex

Definition: type FIndex is bytes26

Bit Packing: fTime(32) | floatingIndex(112) | feeIndex(64)

FIndex fIndex = FIndexLib.from(fTime, floatingIndex, feeIndex);

// Parsing components
uint32 fTime = fIndex.fTime();                  // Funding time
int112 floatingIndex = fIndex.floatingIndex();  // Floating rate index
uint64 feeIndex = fIndex.feeIndex();            // Fee accumulator

// Comparison and checks
bool isZero = fIndex.isZero();
bool same = fIndex1 == fIndex2;

PayFee

Definition: type PayFee is uint256

Bit Packing: payment(128) | fees(128)

Compact representation of a cash payment paired with its associated fees. Used throughout the settlement and liquidation system to bundle payment amounts with their fee components.

PayFee result = PayFeeLib.from(payment, fees);

(int128 payment, uint128 fees) = result.unpack();
int256 netAmount = result.total();   // payment - fees

VMResult

Definition: type VMResult is uint256

Bit Packing: value(128) | margin(128)

Compact representation of a position's value paired with its margin requirement. Used by settleAllAndGet() to return position valuation and margin data in a single value.

VMResult result = VMResultLib.from(positionValue, marginRequired);

(int128 value, uint128 margin) = result.unpack();