fintech-algorithms

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

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