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

Cancel/Replace Priority Rule

Install and import#

bash
npm install fintech-algorithms
ts
import { cancelReplacePriority } from "fintech-algorithms/matching-engines-and-venue-logic/order-lifecycle-and-queue-state/cancel-replace-priority-rule";

Signature#

cancelReplacePriority(originalRaw, replacementRaw)

Decides whether an amendment keeps queue position. Reducing quantity usually keeps it; raising quantity or changing price loses it. This one rule determines whether an amend is nearly free or extremely expensive.

Parameters#

NameTypeNotes
originalRawOrderThe resting order before amendment.
replacementRawOrderThe requested replacement.

Returns#

{ priority_retained, reason, new_sequence, … }

Whether priority survives and the reason — the reason is what a participant needs to design around.

Errors#

  • When the replacement changes side or instrument — throws

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

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#

originalRaw
{
  "order_id": "O-1",
  "order_type": "displayed-limit",
  "price": 100,
  "remaining_quantity": 1000,
  "priority_sequence": 42
}
replacementRaw
{
  "order_id": "O-2",
  "price": 100,
  "remaining_quantity": 600,
  "replace_sequence": 80
}

Call#

cancelReplacePriority(originalRaw, replacementRaw)

Returns#

object with 14 fields: model, original_order_id, replacement_order_id, original_price, replacement_price, original_remaining_quantity, replacement_remaining_quantity, same_price, …

{
  "model": "nasdaq-style-displayed-limit-priority-rule",
  "original_order_id": "O-1",
  "replacement_order_id": "O-2",
  "original_price": 100,
  "replacement_price": 100,
  "original_remaining_quantity": 1000,
  "replacement_remaining_quantity": 600,
  "same_price": true,
  "decrease_only": true,
  "priority_preserved": true,
  "original_priority_sequence": 42,
  "effective_priority_sequence": 42,
  "reason": "same-price quantity decrease preserves canonical displayed-order priority",
  "state": "priority-preserved"
}

Other exports#

This module also exports limitOrderLifecycle, 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#

Cancel/Replace Priority Rule — system map

Calculation flow#

Cancel/Replace Priority Rule calculation flow 
flowchart LR
    S1["Validate original displayedlimit scope"]
    S2["Compare original and replacement price"]
    S3["Compare replacement quantity with current leaves"]
    S4["Preserve only when both canonical conditions pass"]
    S5["Return effective sequence and reason"]
    S1 --> S2
    S2 --> S3
    S3 --> S4
    S4 --> S5
    S5 --> D{"venueordertype eligibility for the preserve exception"}
    D --> O["priority_preserved + diagnostics"]
    O --> A["Audit: A newpriority result uses the later replace sequence"]

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#