Skip to content

Architecture

Jump to bottom
Eugene Palchukovsky edited this page May 16, 2026 · 8 revisions

Architecture

This page describes the current public architecture of OpenPit.

Design Goals

  • Embeddable: no separate service, no network hop, no runtime requirement
  • Deterministic: the same order, policy state, and policy set produce the same decision
  • Fail-safe by default: unfinalized reservations roll back automatically
  • Financially precise: domain values use exact decimal semantics through param types

Current SDKs

Public API Areas

  • Domain values: prices, quantities, pnl, cash flow, volume, side, leverage Go: openpit/param Python: openpit.param Rust: openpit::param
  • Core entities: order, execution report, account adjustment, instrument, engine Go: package root openpit Python: package root and openpit.core Rust: crate root and openpit::core
  • Pre-trade pipeline: policies, rejects, requests, reservations, reports Go: openpit/pretrade Python: openpit.pretrade Rust: openpit::pretrade

Engine

Engine coordinates the public pre-trade lifecycle:

  1. Build an engine.
  2. Run the start stage.
  3. Execute the deferred request.
  4. Finalize the reservation.
  5. Apply post-trade feedback.
  6. Optionally validate non-trade operation (NTO) batches through apply account adjustments.

Current engine behavior:

  • Policy names must be unique across both stages.
  • Engine handle threading capability follows from the chosen sync policy. Full sync supports concurrent invocation on the same handle; Local sync keeps the handle single-threaded; Account sync supports sequential cross-thread access with caller-pinned per-account chains. See Threading Contract.
  • A deferred request or reservation depends on the engine instance that created it.
  • Account-adjustment batch validation is atomic: first reject aborts the whole batch.

Order, Execution Report and Account Adjustment Contracts

OpenPit currently exposes public integration models for orders, execution reports, and non-trading account adjustments:

  • Rust can evaluate caller-defined order and execution-report types directly when they implement the required capability traits. Order traits include HasTradeAmount, HasOrderPrice, HasInstrument, and HasSide. Report traits include HasPnl, HasFee, and HasInstrument. Policies declare only the traits they actually use, so a policy that only inspects trade amount and price requires O: HasTradeAmount + HasOrderPrice and is compatible with any order type that provides those two capabilities.
  • Python exposes fixed public record models: openpit.Order, openpit.ExecutionReport, and openpit.AccountAdjustment.

Both SDKs use the same staged flow and the same standard reject shape.

Rust-specific guidance for manual trait implementations and derive-based wrapper composition is documented in Custom Rust Types.

Two-Stage Pipeline

OpenPit separates early admission checks from main-stage checks that may reserve state.

Order
  │
  ▼
Start stage
  │
  ├─ Reject
  ▼
Pre-trade request
  │
  ▼
Execute request
  │
  ├─ Reject list
  ▼
Pre-trade reservation
  │
  ├─ Commit
  └─ Rollback

Stage semantics:

  • Start stage stops at the first reject.
  • Main stage evaluates all configured policies.
  • If any main-stage policy rejects, accumulated mutations roll back before the reject list is returned.

Account Adjustment Pipeline

Account adjustment is validated through a dedicated atomic batch flow:

Account adjustment batch
  │
  ▼
Batch validation
  │
  ├─ Accepted batch
  └─ Rejected batch { failed index, reject reason }

Semantics:

  • Deterministic traversal by batch order and policy registration order
  • First reject stops evaluation
  • All-or-nothing batch outcome

State Changes

Main-stage policies do not finalize state directly. They emit Pre-trade mutation pairs that the engine applies later.

Current public mutation kinds are:

  • Reserve notional for a settlement asset
  • Set a kill-switch state

Current Boundaries

OpenPit is intentionally narrow in scope:

  • It is a pre-trade engine, not an OMS or EMS.
  • It does not provide persistence or external data sources.
  • It does not provide venue connectivity.
  • The current built-in policies are all start stage policies.

Related Pages

Clone this wiki locally