Skip to content

Architecture

Jump to bottom
Eugene Palchukovsky edited this page Jul 23, 2026 · 12 revisions

Architecture

Public architecture of OpenPit and its integration model.

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

Public API Areas

  • Domain values: prices, quantities, pnl, cash flow, volume, side, leverage Go: openpit/param Python: openpit.param C++: openpit::param Rust: openpit::param C: OpenPitParam* value handles and structs
  • Core entities: order, execution report, account adjustment, instrument, engine Go: package root openpit Python: package root and openpit.core C++: openpit::model and openpit::Engine Rust: crate root and openpit::core C: OpenPitOrder, OpenPitExecutionReport, and OpenPitEngine
  • Pre-trade pipeline: policies, rejects, requests, reservations, reports Go: openpit/pretrade Python: openpit.pretrade C++: openpit::pretrade Rust: openpit::pretrade C: OpenPitPretrade* handles and functions

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.
  • Threading capability of the engine handle follows from the chosen sync policy. See Threading Contract.
  • A deferred request or reservation depends on the engine instance that created it.
  • Account-adjustment batch validation is atomic: the 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:

  • C++ exposes fixed model value types and client-payload adapter templates: openpit::model::Order, openpit::model::ExecutionReport, and openpit::pretrade::StartPolicyAdapter / openpit::pretrade::PolicyAdapter. Adapter policies choose an explicit cast mode so dynamic-boundary checks are visible at the call site.
  • Go exposes fixed public model records plus generic policy interfaces for caller-defined payloads.
  • Python exposes fixed public record models: openpit.Order, openpit.ExecutionReport, and openpit.AccountAdjustment.
  • 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.
  • C exposes POD views and opaque handles for ABI-stable embedders.

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

Language-specific custom-payload guidance is documented in the corresponding Custom Go Types, Custom Python Types, Custom JS Types, Custom Cpp Types, and Custom Rust Types pages.

Two-Stage Pipeline

OpenPit separates early admission checks from main-stage checks that may reserve state. The start stage stops at the first reject; the main stage evaluates every registered policy, aggregates rejects, and rolls back collected mutations if any reject is produced.

See Pre-trade Pipeline for the full lifecycle, return types, and code examples.

Account Adjustment Pipeline

Account adjustment validation runs as an atomic batch: deterministic traversal by batch and policy registration order, first reject aborts, all-or-nothing outcome.

See Account Adjustments for the data model and rollback rules.

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:

  • 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.
  • Built-in policies may participate in the start, main, post-trade, and account-adjustment stages according to their state and reconciliation needs.

Related Pages

Clone this wiki locally