fintech-algorithms

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

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