Struct EngineCtx 

pub struct EngineCtx {

    pub orderbooks: HashMap<String, OrderBook>,
    pub next_order_id: u64,
    pub next_trade_id: u64,
    pub l2_update_seq: Arc<AtomicI64>,
    pub expired_instruments: HashMap<String, bool>,
    pub spot_prices: HashMap<String, Decimal>,
    pub iv_surfaces: HashMap<String, VolatilitySurface>,
    pub iv_source_timestamps: HashMap<String, i64>,
    pub instrument_trading_modes: HashMap<String, TradingModes>,
    pub order_index: EngineOrderIndex,
    pub engine_positions: HashMap<(WalletAddress, String), EnginePosition>,
    pub balance_ledger: BalanceLedger,
    pub deposit_update_watermarks: HashMap<WalletAddress, DepositUpdateWatermark>,
    pub applied_deposit_source_event_hashes: BTreeSet<FixedBytes<32>>,
    pub pm_settlement_state: PmSettlementState,
    pub mmp_state: HashMap<(WalletAddress, String), EngineMmpState>,
    pub agent_authorizations: HashMap<WalletAddress, HashMap<WalletAddress, Option<u64>>>,
    pub nonce_sets: HashMap<WalletAddress, BoundedNonceSet>,
    pub rsm_signer_nonces: HashMap<WalletAddress, u64>,
    pub deps: EngineDeps,
    pub db: Option<DatabaseHandler>,
}

All mutable + immutable shared state that managers need to access.

Kept as a single struct field on UnifiedEngine to enable split borrows between self.ctx and self.<manager>.

Fields

orderbooks: HashMap<String, OrderBook>

Active orderbooks keyed by symbol.

next_order_id: u64

Next order ID to allocate (global monotonic counter).

next_trade_id: u64

Next trade ID to allocate (global monotonic counter).

l2_update_seq: Arc<AtomicI64>

L2 sequence counter for orderbook snapshots.

expired_instruments: HashMap<String, bool>

symbol → expired flag (shared between engine and ExpiryManager).

spot_prices: HashMap<String, Decimal>

Canonical spot prices per underlying, updated only by PriceUpdate commands. Margin checks read from here instead of external caches, making the engine deterministic and replayable.

iv_surfaces: HashMap<String, VolatilitySurface>

Canonical IV surfaces per underlying, updated only by IvUpdate commands. The SpanMarginService reads from these instead of external vol oracles.

iv_source_timestamps: HashMap<String, i64>

Source timestamps for IV surfaces (from the upstream oracle snapshot). Used for change detection to skip ingestion when the oracle hasn’t updated.

instrument_trading_modes: HashMap<String, TradingModes>

Per-instrument trading mode (orderbook-only, rfq-only, or both).

order_index: EngineOrderIndex

engine_positions: HashMap<(WalletAddress, String), EnginePosition>

Engine-owned option positions, updated from fills inside apply(). Single source of truth for margin checks. PortfolioService is a downstream projection, not consulted during apply(). Perp positions are in deps.perp_positions (fed by HypercorePositionUpdate).

balance_ledger: BalanceLedger

Engine-owned cash balances per wallet. Updated from fill side effects (realized PnL + premium deltas) and deposits. Margin checks read from here instead of the async Ledger.

deposit_update_watermarks: HashMap<WalletAddress, DepositUpdateWatermark>

Last applied deposit update per wallet. This prevents an older post-balance command from rolling balance_ledger backward after a newer deposit has already applied.

applied_deposit_source_event_hashes: BTreeSet<FixedBytes<32>>

Applied cash DepositUpdate source event hashes.

This is intentionally an incident-stabilization tradeoff, not the target architecture. Cash DepositUpdate is now an additive delta, so the old single per-wallet sequence watermark can under-credit if sequence 11 is applied before an unseen sequence 10. The source_event_hash is the deterministic idempotency key, and tracking it here makes duplicate replay safe without dropping out-of-order lower-sequence deltas.

The cost is that this set grows with every applied cash deposit and is serialized in EngineStateSnapshot. That is unacceptable long-term. The intended replacement is a bounded engine-owned cash sequencer, similar in spirit to BoundedNonceSet but gap-buffered for ordered deltas: store only applied_through plus a small pending window, require a per-wallet cash sequence, apply contiguous deltas, and fail closed when the gap window is exceeded. A DB-owned cash queue would also fix ordering, but it moves authority away from the engine and back toward projection-driven cash mutation, which is the wrong architectural direction.

pm_settlement_state: PmSettlementState

Engine-owned PM settlement-pool authority.

Projection tables are downstream audit surfaces and must never hydrate this state on startup or rebuild.

mmp_state: HashMap<(WalletAddress, String), EngineMmpState>

Engine-internal MMP fill tracking per (wallet, currency). Updated synchronously inside apply() so the matching loop never performs async reads against the external MmpCache.

agent_authorizations: HashMap<WalletAddress, HashMap<WalletAddress, Option<u64>>>

Engine-owned agent authorizations: owner wallet → (agent wallet → optional expiry ms). None = never expires. Updated by ApproveAgent/RevokeAgent commands. Read via EngineSnapshot for lock-free API access.

nonce_sets: HashMap<WalletAddress, BoundedNonceSet>

Per-signer bounded nonce sets (HL model). The engine stores the N highest nonces per signer. A new nonce must be greater than the smallest in the set and not already used. Shared across orders, agent auth, and QP handshakes. Keyed by signer address (api_wallet for orders, recovered signer for agent auth, QP wallet for handshakes).

rsm_signer_nonces: HashMap<WalletAddress, u64>

Canonical RSM signer nonce allocation. Directive-producing commands allocate here during apply(), then append a NeedsRsmSignature outbox item carrying the allocated nonce.

deps: EngineDeps

db: Option<DatabaseHandler>

Implementations

impl EngineCtx

fn symbol_is_expired_by_wall_clock(symbol: &str) -> Option<bool>

pub fn restore_from_snapshot(&mut self, snapshot: &EngineStateSnapshot)

Restore engine state from a persistent snapshot.

Sets counters, restores orderbook orders, rebuilds the order index, and restores expired instruments. Called during startup before delta replay to skip full journal replay.

Trait Implementations

impl<'a> RestartStateComponent<EngineRecoveryCapture<'a>, EngineCtx, EngineCommand, EngineStateDigest> for AuthNonceComponent

const NAME: RestartComponentName = RestartComponentName::AuthNonce

type Snapshot = EngineStateSnapshot

fn capture(ctx: &EngineRecoveryCapture<'a>) -> Self::Snapshot

fn restore(ctx: &mut EngineCtx, snapshot: &Self::Snapshot)

fn digest(ctx: &EngineRecoveryCapture<'a>) -> EngineStateDigest

fn replay(_command: &EngineCommand, _ctx: &mut EngineCtx) -> ReplayDisposition

fn mutation_sources() -> &'static [MutationSource]

fn descriptor() -> RestartComponentDescriptor

impl<'a> RestartStateComponent<EngineRecoveryCapture<'a>, EngineCtx, EngineCommand, EngineStateDigest> for CashLedgerComponent

const NAME: RestartComponentName = RestartComponentName::CashLedger

type Snapshot = EngineStateSnapshot

fn capture(ctx: &EngineRecoveryCapture<'a>) -> Self::Snapshot

fn restore(ctx: &mut EngineCtx, snapshot: &Self::Snapshot)

fn digest(ctx: &EngineRecoveryCapture<'a>) -> EngineStateDigest

fn replay(_command: &EngineCommand, _ctx: &mut EngineCtx) -> ReplayDisposition

fn mutation_sources() -> &'static [MutationSource]

fn descriptor() -> RestartComponentDescriptor

impl<'a> RestartStateComponent<EngineRecoveryCapture<'a>, EngineCtx, EngineCommand, EngineStateDigest> for HypercoreStateComponent

const NAME: RestartComponentName = RestartComponentName::HypercoreState

type Snapshot = EngineStateSnapshot

fn capture(ctx: &EngineRecoveryCapture<'a>) -> Self::Snapshot

fn restore(ctx: &mut EngineCtx, snapshot: &Self::Snapshot)

fn digest(ctx: &EngineRecoveryCapture<'a>) -> EngineStateDigest

fn replay(_command: &EngineCommand, _ctx: &mut EngineCtx) -> ReplayDisposition

fn mutation_sources() -> &'static [MutationSource]

fn descriptor() -> RestartComponentDescriptor

impl<'a> RestartStateComponent<EngineRecoveryCapture<'a>, EngineCtx, EngineCommand, EngineStateDigest> for MarketCatalogComponent

const NAME: RestartComponentName = RestartComponentName::MarketCatalog

type Snapshot = EngineStateSnapshot

fn capture(ctx: &EngineRecoveryCapture<'a>) -> Self::Snapshot

fn restore(ctx: &mut EngineCtx, snapshot: &Self::Snapshot)

fn digest(ctx: &EngineRecoveryCapture<'a>) -> EngineStateDigest

fn replay(_command: &EngineCommand, _ctx: &mut EngineCtx) -> ReplayDisposition

fn mutation_sources() -> &'static [MutationSource]

fn descriptor() -> RestartComponentDescriptor

impl<'a> RestartStateComponent<EngineRecoveryCapture<'a>, EngineCtx, EngineCommand, EngineStateDigest> for MmpLiquidationComponent

const NAME: RestartComponentName = RestartComponentName::MmpLiquidation

type Snapshot = EngineStateSnapshot

fn capture(ctx: &EngineRecoveryCapture<'a>) -> Self::Snapshot

fn restore(ctx: &mut EngineCtx, snapshot: &Self::Snapshot)

fn digest(ctx: &EngineRecoveryCapture<'a>) -> EngineStateDigest

fn replay(_command: &EngineCommand, _ctx: &mut EngineCtx) -> ReplayDisposition

fn mutation_sources() -> &'static [MutationSource]

fn descriptor() -> RestartComponentDescriptor

impl<'a> RestartStateComponent<EngineRecoveryCapture<'a>, EngineCtx, EngineCommand, EngineStateDigest> for OrderbookStateComponent

const NAME: RestartComponentName = RestartComponentName::OrderbookState

type Snapshot = EngineStateSnapshot

fn capture(ctx: &EngineRecoveryCapture<'a>) -> Self::Snapshot

fn restore(ctx: &mut EngineCtx, snapshot: &Self::Snapshot)

fn digest(ctx: &EngineRecoveryCapture<'a>) -> EngineStateDigest

fn replay(_command: &EngineCommand, _ctx: &mut EngineCtx) -> ReplayDisposition

fn mutation_sources() -> &'static [MutationSource]

fn descriptor() -> RestartComponentDescriptor

impl<'a> RestartStateComponent<EngineRecoveryCapture<'a>, EngineCtx, EngineCommand, EngineStateDigest> for PersistentEngineStateComponent

const NAME: RestartComponentName = RestartComponentName::PersistentEngineStateEnvelope

type Snapshot = EngineStateSnapshot

fn capture(ctx: &EngineRecoveryCapture<'a>) -> Self::Snapshot

fn restore(ctx: &mut EngineCtx, snapshot: &Self::Snapshot)

fn digest(ctx: &EngineRecoveryCapture<'a>) -> EngineStateDigest

fn replay(_command: &EngineCommand, _ctx: &mut EngineCtx) -> ReplayDisposition

fn mutation_sources() -> &'static [MutationSource]

fn descriptor() -> RestartComponentDescriptor

impl<'a> RestartStateComponent<EngineRecoveryCapture<'a>, EngineCtx, EngineCommand, EngineStateDigest> for PmSettlementStateComponent

const NAME: RestartComponentName = RestartComponentName::PmSettlementState

type Snapshot = EngineStateSnapshot

fn capture(ctx: &EngineRecoveryCapture<'a>) -> Self::Snapshot

fn restore(ctx: &mut EngineCtx, snapshot: &Self::Snapshot)

fn digest(ctx: &EngineRecoveryCapture<'a>) -> EngineStateDigest

fn replay(_command: &EngineCommand, _ctx: &mut EngineCtx) -> ReplayDisposition

fn mutation_sources() -> &'static [MutationSource]

fn descriptor() -> RestartComponentDescriptor

impl<'a> RestartStateComponent<EngineRecoveryCapture<'a>, EngineCtx, EngineCommand, EngineStateDigest> for PriceIvInputsComponent

const NAME: RestartComponentName = RestartComponentName::PriceIvInputs

type Snapshot = EngineStateSnapshot

fn capture(ctx: &EngineRecoveryCapture<'a>) -> Self::Snapshot

fn restore(ctx: &mut EngineCtx, snapshot: &Self::Snapshot)

fn digest(ctx: &EngineRecoveryCapture<'a>) -> EngineStateDigest

fn replay(_command: &EngineCommand, _ctx: &mut EngineCtx) -> ReplayDisposition

fn mutation_sources() -> &'static [MutationSource]

fn descriptor() -> RestartComponentDescriptor

impl<'a> RestartStateComponent<EngineRecoveryCapture<'a>, EngineCtx, EngineCommand, EngineStateDigest> for TierRiskLimitsComponent

const NAME: RestartComponentName = RestartComponentName::TierRiskLimits

type Snapshot = EngineStateSnapshot

fn capture(ctx: &EngineRecoveryCapture<'a>) -> Self::Snapshot

fn restore(ctx: &mut EngineCtx, snapshot: &Self::Snapshot)

fn digest(ctx: &EngineRecoveryCapture<'a>) -> EngineStateDigest

fn replay(_command: &EngineCommand, _ctx: &mut EngineCtx) -> ReplayDisposition

fn mutation_sources() -> &'static [MutationSource]

fn descriptor() -> RestartComponentDescriptor