fintech-algorithms
/
Using a coding agent? Give it the skill: npx skills add IslamBaraka90/Fintech-Algorithms-Library What it does →

Limit-Order Lifecycle State Machine

Install and import#

bash
npm install fintech-algorithms
ts
import { limitOrderLifecycle } from "fintech-algorithms/matching-engines-and-venue-logic/order-lifecycle-and-queue-state/limit-order-lifecycle-state-machine";

Signature#

limitOrderLifecycle(orderIdRaw, orderQuantityRaw, eventsRaw)

Replays an order's events into its state history — new, partially filled, replaced, cancelled, done. The value is rejecting *invalid* transitions: a fill after a cancel is a bug somewhere upstream, and it must not be absorbed silently.

Parameters#

NameTypeNotes
orderIdRawstringThe order being tracked.
orderQuantityRawnumberOriginal order quantity.
min: 1 · integer: true
eventsRawEvent[]Lifecycle events in sequence.

Returns#

{ states, final_state, invalid_transitions, filled, residual, … }

The state path with any invalid transitions named rather than absorbed.

Errors#

  • When an event references a different order id — throws

Complexity: time O(events), space O(events).

Worked example#

executed Captured by running this function on the input its own test provides. Real output of real code — but not asserted against a published figure.

Input#

orderIdRaw
"L-100"
orderQuantityRaw
1000
eventsRaw
[
  {
    "type": "accept"
  },
  {
    "type": "fill",
    "quantity": 300,
    "price": 100
  },
  {
    "type": "fill",
    "quantity": 500,
    "price": 100.01
  }
]

Showing 3 of 4 elements.

Call#

limitOrderLifecycle(orderIdRaw, orderQuantityRaw, eventsRaw)

Returns#

object with 11 fields: model, order_id, order_quantity, cumulative_quantity, leaves_quantity, average_fill_price, execution_count, status, …

{
  "model": "accepted-order-lifecycle-state-machine",
  "order_id": "L-100",
  "order_quantity": 1000,
  "cumulative_quantity": 1000,
  "leaves_quantity": 0,
  "average_fill_price": 100.009,
  "execution_count": 3,
  "status": "filled",
  "terminal": true,
  "transitions": [
    {
      "event_index": 0,
      "event_type": "accept",
      "before_status": "pending-new",
      "after_status": "new",
      "cumulative_quantity": 0,
      "leaves_quantity": 1000
    },
    {
      "event_index": 1,
      "event_type": "fill",
      "before_status": "new",
      "after_status": "partially-filled",
      "cumulative_quantity": 300,
      "leaves_quantity": 700
    },
    {
      "event_index": 2,
      "event_type": "fill",
      "before_status": "partially-filled",
      "after_status": "partially-filled",
      "cumulative_quantity": 800,
      "leaves_quantity": 200
    }
  ],
  "state": "filled"
}

Other exports#

This module also exports cancelReplacePriority, partialFillResidual, queuePositionAheadVolume, icebergReplenishment, marketableOrderSweep, calculate. Every module additionally exports run as an alias of its primary function, and a meta object carrying its catalog id, domain, family, shape and article URL.

Diagrams#

Limit-Order Lifecycle State Machine — system map

Calculation flow#

Limit-Order Lifecycle State Machine calculation flow 
flowchart LR
    S1["Initialize pendingnew with full leaves"]
    S2["Accept or reject the entry"]
    S3["Apply each liveorder fill to cumulative and notional"]
    S4["Resolve cancel expire replace or complete fill"]
    S5["Emit an audit transition and block postterminal events"]
    S1 --> S2
    S2 --> S3
    S3 --> S4
    S4 --> S5
    S5 --> D{"terminalstate finality and the overfill guard"}
    D --> O["status + diagnostics"]
    O --> A["Audit: Cumulative fill never exceeds original quantity"]

How it works#

This page states the contract — how to call it correctly. The article explains the concept: why it works, and where it breaks.

Read the article →

References#

The rest of the Order Lifecycle and Queue State family#