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

Level-3 Order-by-Order Reconstruction

Install and import#

bash
npm install fintech-algorithms
ts
import { reconstructL3 } from "fintech-algorithms/market-data-engineering/order-book-feed-engineering/level-3-order-by-order-reconstruction";

Signature#

reconstructL3(snapshot_orders)

Rebuilds the book order by order rather than by price level, so each visible order keeps its own identity and quantity through add, reduce, execute, delete, and replace. The emitted priority_rank is the insertion order of visible identities within the reconstructed stream. It is not a venue queue position and carries no information about hidden liquidity, participant identity, or exchange-internal priority changes that the feed does not report.

Parameters#

NameTypeNotes
snapshot_ordersL3Order[]Individual resting orders with their identifiers, side, integer price ticks and quantity. Snapshot order IDs must be non-empty and unique; their listed order fixes the initial insertion ranks. The second argument holds snapshot_sequence, the sequence number the snapshot is anchored at — events at or below it are skipped and the next event must be exactly one greater — and events, the contiguous run of lifecycle messages add, reduce, execute, delete and replace, each carrying a sequence and an order_id.

Returns#

{ snapshot_sequence, last_sequence, order_count, event_count, action_counts, orders, bids, asks, state }

Surviving visible orders sorted by priority_rank, the price levels aggregated from them, per-action counters, and the sequence span covered. state is current.

Errors#

  • When a reduce, execute, delete or replace references an order id not in the book — throws
  • When an event sequence skips the expected next value — throws
  • When a reduction exceeds the resting quantity, an add reuses a live order id, or the action is unrecognised — throws

Complexity: time O(s + e + k log k), for s snapshot orders, e events and k surviving orders: one pass applies the stream, then the survivors are sorted by insertion rank and their price levels are sorted, space O(orders).

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#

snapshot_orders
[
  {
    "order_id": "B1",
    "side": "bid",
    "price_ticks": 10001,
    "quantity": 12
  },
  {
    "order_id": "B2",
    "side": "bid",
    "price_ticks": 10000,
    "quantity": 14
  },
  {
    "order_id": "B3",
    "side": "bid",
    "price_ticks": 10000,
    "quantity": 16
  }
]

Showing 3 of 12 elements.

argument 2
{
  "snapshot_sequence": 800,
  "events": [
    {
      "sequence": 801,
      "action": "add",
      "order_id": "N1",
      "side": "bid",
      "price_ticks": 10001,
      "quantity": 9
    },
    {
      "sequence": 802,
      "action": "execute",
      "order_id": "A1",
      "quantity": 3
    },
    {
      "sequence": 803,
      "action": "reduce",
      "order_id": "B1",
      "quantity": 2
    }
  ]
}

Call#

reconstructL3(snapshot_orders)

Returns#

object with 9 fields: snapshot_sequence, last_sequence, order_count, event_count, action_counts, orders, bids, asks, …

{
  "snapshot_sequence": 800,
  "last_sequence": 820,
  "order_count": 16,
  "event_count": 20,
  "action_counts": {
    "add": 7,
    "reduce": 4,
    "execute": 4,
    "delete": 3,
    "replace": 2
  },
  "orders": [
    {
      "order_id": "B1",
      "side": "bid",
      "price_ticks": 10001,
      "quantity": 10,
      "priority_rank": 1
    },
    {
      "order_id": "B5",
      "side": "bid",
      "price_ticks": 9999,
      "quantity": 17,
      "priority_rank": 5
    },
    {
      "order_id": "B6",
      "side": "bid",
      "price_ticks": 9998,
      "quantity": 22,
      "priority_rank": 6
    }
  ],
  "bids": [
    {
      "price_ticks": 10001,
      "quantity": 22,
      "order_count": 3
    },
    {
      "price_ticks": 10000,
      "quantity": 15,
      "order_count": 1
    },
    {
      "price_ticks": 9999,
      "quantity": 30,
      "order_count": 2
    }
  ],
  "asks": [
    {
      "price_ticks": 10002,
      "quantity": 13,
      "order_count": 2
    },
    {
      "price_ticks": 10003,
      "quantity": 16,
      "order_count": 1
    },
    {
      "price_ticks": 10004,
      "quantity": 31,
      "order_count": 2
    }
  ],
  "state": "current"
}

Other exports#

This module also exports normalizeEvents, reconstructL2, aggregatePriceLevels, recoverSequenceStream, reconcileSnapshotIncrementals, consolidateVenues, 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#

Level-3 Order-by-Order Reconstruction — d11 handoff
Level-3 Order-by-Order Reconstruction — failure map
Level-3 Order-by-Order Reconstruction — sequence boundary
Level-3 Order-by-Order Reconstruction — state transition
Level-3 Order-by-Order Reconstruction — system map

Calculation flow#

Level-3 Order-by-Order Reconstruction system flow 
flowchart LR
    A["Load unique snapshot identities."] --> B["Apply add/reduce/execute/delete to exact IDs."]
    B --> C{"Safe to publish?"}
    C -->|"yes"| D["Remove zero or deleted orders."]
    C -->|"no"| E["Feed order identity is not participant identity or proof of hidden priority."]
    D --> F["Publish current L3 orders plus derived L2"]
    F --> G["Route to the named D11 measurement"]

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-Book Feed Engineering family#