Four contracts, one state of truth.

1. 01ElystaCollateralVault.sol

   Collateral Vault

   Holds the settlement collateral and keeps the one canonical ledger: available, reserved and locked per account, the insurance fund and the PnL pool.

   Authoritative for every balance.

2. 02ElystaMarketRegistryOracle.sol

   Market Registry & Oracle

   Lists markets with their execution, risk, fee and session parameters, and turns adapter observations into one validated index price with freshness and deviation rules.

   Authoritative for configuration and the index.

3. 03ElystaOrderBookEngine.sol

   Order Book & Matching

   The on-chain limit order book: tick-indexed levels, FIFO queues and deterministic price-time matching inside a bounded gas budget.

   Authoritative for which orders fill, and at what price.

4. 04ElystaPerpRiskEngine.sol

   Perpetual Risk Engine

   Positions, isolated margin, leverage limits, mark price, funding, permissionless liquidation and the loss waterfall into the insurance fund.

   Authoritative for positions and settlement.

Supporting code is libraries and one interface: ElystaTypes (shared enums, structs and the WAD convention), FixedPointMath (18-decimal arithmetic with explicit rounding), TickBitmap (price-level discovery), and IOracleAdapter, behind which the keeper adapter sits. None of them holds protocol state.

The binding between the two engines is permanent: setOrderEngine can be called once, grants ORDER_ENGINE_ROLE to the order book, and reverts afterwards. The vault accepts ledger instructions only from RISK_ENGINE_ROLE, held by the risk engine contract. Every ledger primitive moves an amount between two terms of one equation, which is why the whole vault can be checked at any block:

The status page reads solvency() and reports whether the equation holds. The PnL pool is a signed accumulator, always equal to minus the sum of unrealized PnL over every open position: a gain paid out subtracts from it, a loss taken adds to it, and the dust left by rounding lands in it.

1. 01

   Placement

   Order book

   placeOrder(PlaceOrderParams) checks the market with the registry (isTradingOpen: status Active or ReduceOnly, session open, valid index), refuses non-reduce-only orders on a ReduceOnly market, enforces the open-order cap, the expiry, and the quantity (a multiple of the lot between the minimum and maximum). A limit price must be a tick multiple inside priceBandBps of the index; a market order is turned into an immediate limit at the mark moved by maxImpactBps, tightened by the trader’s protectionPrice.

2. 02

   Risk reservation

   Risk engine

   reserveForOrder moves notional × initialMarginFraction + notional × takerFee from the trader’s available to reserved collateral, for the full quantity at the limit price, so a later fill can never fail for lack of collateral. A reduce-only order reserves nothing; it must shrink a position that already holds margin, on the opposite side and within its size.

3. 03

   Matching

   Order book

   The incoming order walks the opposing side from the best level while that level crosses its limit, oldest order first. Each fill is settled before the next is attempted. If the risk engine rejects the resting (maker) side, that order is cancelled with reason RiskRejected and matching moves on; if it rejects the taker, the whole transaction reverts and the book never shows a trade that did not settle. A resting order of the taker’s own is cancelled (SelfTrade); an expired maker is cancelled on contact. The walk stops at 24 fills or 12 levels per transaction.

4. 04

   Settlement

   Risk engine and vault

   applyFill computes a plan for each side before writing anything: the share of the reservation to release, the quantity that closes existing exposure and the quantity that opens new exposure, the PnL realized at the fill price, the margin to lock, the fee. Then it writes the vault: release the reservation, pay a gain to available or take a loss from margin (and, past the margin, from the insurance fund), lock new margin, charge the fee split between insurance fund and protocol fees, and update the position and open interest. Every step is an event.

5. 05

   Remainder

   Order book

   A fully filled order emits OrderFilled. A GTC or post-only limit remainder rests (OrderRested) with its reservation. An IOC or market remainder is cancelled (Remainder). A FOK that could not fill entirely reverts (FillOrKillNotFilled), as does a post-only order that would have crossed (PostOnlyWouldCross). A GTC remainder that still crosses the book when the budget runs out is cancelled rather than rested, because resting it would leave the book crossed; the trader resubmits.

What a filled order leaves in the log

In order: OrderPlaced; for each fill, Fill from the book, two PositionChanged from the risk engine and the vault’s ledger events (Released, MarginLocked, FeeCharged, and AvailableCredited or LockedDebited when PnL is realized); then OrderFilled, OrderRested or OrderCancelled. A trader can reconstruct every figure the terminal shows from these events alone, and the indexer does exactly that.

Position lifecycle

A position is a signed quantity per account and market with an average entry price and its own margin. A fill on the same side increases it and raises the margin by the new quantity’s initial margin, averaging the entry price. A fill on the opposite side closes quantity first, releasing margin in proportion and realizing PnL at the fill price; any quantity beyond the position opens the other way at the fill price. Funding is settled whenever a position is touched. Margin can be added or removed by its owner while the position stays above its initial requirement. Liquidation is described on the risk methodology page.

• One sequence per market. OrderPlaced.seq and Fill.seq share a counter, so placements and fills are totally ordered without relying on log position. sequence() returns the next order id and the last sequence number for reconciliation.
• Reasons travel with changes. OrderCancelled carries a CancelReason, MarketStatusChanged a StatusReason, PositionChanged a numeric reason (fill, liquidated, liquidator), and every vault settlement a SettlementKind.
• Prices are recorded on acceptance and on rejection. IndexPriceUpdated names the adapter and whether the secondary was used; PriceRejected names the reason: no price, stale, or deviation.
• Indexed arguments are the query keys. Account, market id and order id are indexed wherever they appear, so a wallet’s whole history is a handful of topic filters.

The event specification lists every event of the four contracts with its parameters, when it is emitted and which indexer table it lands in.

What no role can do

Edit a balance

The vault's ledger functions are callable only by the risk engine contract, and each one moves an amount between two terms of the vault equation (available, reserved, locked, insurance fund, protocol fees, PnL pool). There is no function that sets a balance.

Force a fill

placeOrder, cancelOrder and replaceOrder act on msg.sender's orders. applyFill is callable only by the order book, which only calls it while matching a trader's own order against resting orders.

Override the price a position settles at

Fills settle at the resting order's price; liquidation and funding settle at the mark price, which the risk engine derives from the validated index and the live book. An administrator can change oracle parameters and clear a halt, but cannot write a price.

Withdraw the insurance fund

fundInsurance adds to it; coverFromInsurance pays a shortfall into the PnL pool; lockedToInsurance and chargeFee add penalties and fee shares. No function pays it out in this version.

Hold withdrawals indefinitely

pauseWithdrawals accepts an end time at most three days ahead. Deposits can be paused outright; withdrawals cannot.

The governance page lists who holds each role today and the path to a multisig and timelock before mainnet.