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

Iceberg/Reserve-Order Replenishment

Install and import#

bash
npm install fintech-algorithms
ts
import { icebergReplenishment } from "fintech-algorithms/matching-engines-and-venue-logic/order-lifecycle-and-queue-state/iceberg-reserve-order-replenishment";

Signature#

icebergReplenishment(totalRaw, initialRaw, displaySizeRaw, fillsRaw, priorityRaw)

Manages a hidden reserve that refills the displayed quantity as it fills. The trap is priority: on most venues each replenishment goes to the **back** of the queue, which is the cost of hiding size.

Parameters#

NameTypeNotes
totalRawnumberTotal order quantity including the hidden reserve.
min: 1 · integer: true
initialRawnumberInitially displayed quantity.
min: 1 · integer: true
displaySizeRawnumberQuantity displayed on each replenishment.
min: 1 · integer: true
fillsRawFill[]Fills against the displayed portion.
priorityRawstringWhether replenishment retains or loses queue priority.

Returns#

{ tranches, displayed, reserve_remaining, priority_events, … }

Each replenishment tranche with its priority consequence.

Errors#

  • When the displayed size exceeds the total, or the priority rule is unrecognised — throws

Complexity: time O(fills), space O(tranches).

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#

totalRaw
1000
initialRaw
200
displaySizeRaw
200
fillsRaw
[100, 200, 250, 300]
priorityRaw
10

Call#

icebergReplenishment(totalRaw, initialRaw, displaySizeRaw, fillsRaw, priorityRaw)

Returns#

object with 12 fields: model, total_quantity, display_size, executed_quantity, displayed_remaining, reserve_remaining, total_remaining, replenishment_count, …

{
  "model": "zero-displayed-tranche-replenishment",
  "total_quantity": 1000,
  "display_size": 200,
  "executed_quantity": 850,
  "displayed_remaining": 150,
  "reserve_remaining": 0,
  "total_remaining": 150,
  "replenishment_count": 4,
  "current_priority_sequence": 14,
  "unfilled_requested_quantity": 0,
  "events": [
    {
      "type": "fill",
      "fill_request_index": 0,
      "quantity": 100,
      "displayed_remaining": 100,
      "reserve_remaining": 800,
      "priority_sequence": 10
    },
    {
      "type": "fill",
      "fill_request_index": 1,
      "quantity": 100,
      "displayed_remaining": 0,
      "reserve_remaining": 800,
      "priority_sequence": 10
    },
    {
      "type": "replenish",
      "quantity": 200,
      "new_priority_sequence": 11,
      "displayed_remaining": 200,
      "reserve_remaining": 600
    }
  ],
  "state": "displayed-only"
}

Other exports#

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

Iceberg/Reserve-Order Replenishment — system map

Calculation flow#

Iceberg/Reserve-Order Replenishment calculation flow 
flowchart LR
    S1["Initialize displayed and reserve components"]
    S2["Consume the current displayed tranche"]
    S3["When it reaches zero expose the next bounded tranche"]
    S4["Increment displayed priority for every replenishment"]
    S5["Return fillreplenish audit and conserved residuals"]
    S1 --> S2
    S2 --> S3
    S3 --> S4
    S4 --> S5
    S5 --> D{"zerodisplay trigger versus venuespecific replenishment rul"}
    D --> O["replenishment_count + diagnostics"]
    O --> A["Audit: Executed plus total remaining equals original total"]

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#