Hybrid Pro-Rata/Time Matching

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179

export type JsonObject = Record<string, any>;

function num(name: string, value: unknown, positive = false): number {
  if (typeof value !== "number" || !Number.isFinite(value)) throw new TypeError(`${name} must be a finite number`);
  if (positive && value <= 0) throw new RangeError(`${name} must be positive`);
  return value;
}
function integer(name: string, value: unknown, nonnegative = false): number {
  const result = num(name, value);
  if (!Number.isInteger(result)) throw new RangeError(`${name} must be an integer`);
  if (nonnegative && result < 0) throw new RangeError(`${name} must be nonnegative`);
  return result;
}
function text(name: string, value: unknown): string {
  if (typeof value !== "string" || !value.trim()) throw new TypeError(`${name} must be a non-empty string`);
  return value;
}
function multiple(name: string, value: number, lot: number): void {
  if (Math.abs(value / lot - Math.round(value / lot)) > 1e-9) throw new RangeError(`${name} must be an integer multiple of lot_size`);
}
function parseResting(raw: unknown, expectedSide: string | null = null): JsonObject[] {
  if (!Array.isArray(raw) || raw.length === 0) throw new RangeError("resting_orders must be a non-empty list");
  const ids = new Set<string>(), sequences = new Set<number>();
  return raw.map((item, index) => {
    if (!item || typeof item !== "object") throw new TypeError(`resting_orders[${index}] must be an object`);
    const order = item as JsonObject, orderId = text(`resting_orders[${index}].order_id`, order.order_id);
    if (ids.has(orderId)) throw new RangeError("order_id values must be unique"); ids.add(orderId);
    const side = text(`resting_orders[${index}].side`, order.side);
    if (!["buy", "sell"].includes(side)) throw new RangeError("order side must be buy or sell");
    if (expectedSide && side !== expectedSide) throw new RangeError("all resting orders must be on the opposite side");
    const sequence = integer(`resting_orders[${index}].arrival_sequence`, order.arrival_sequence, true);
    if (sequences.has(sequence)) throw new RangeError("arrival_sequence values must be unique"); sequences.add(sequence);
    return {
      order_id: orderId,
      side,
      price: num(`resting_orders[${index}].price`, order.price, true),
      remaining_quantity: num(`resting_orders[${index}].remaining_quantity`, order.remaining_quantity, true),
      arrival_sequence: sequence,
    };
  });
}

export function priceTimePriority(incomingRaw: unknown, restingRaw: unknown): JsonObject {
  if (!incomingRaw || typeof incomingRaw !== "object") throw new TypeError("incoming_order must be an object");
  const incoming = incomingRaw as JsonObject;
  const orderId = text("incoming_order.order_id", incoming.order_id), side = text("incoming_order.side", incoming.side);
  if (!["buy", "sell"].includes(side)) throw new RangeError("incoming side must be buy or sell");
  const orderType = text("incoming_order.order_type", incoming.order_type);
  if (!["market", "limit"].includes(orderType)) throw new RangeError("order_type must be market or limit");
  const quantity = num("incoming_order.quantity", incoming.quantity, true);
  let limitPrice: number | null = null;
  if (orderType === "limit") limitPrice = num("incoming_order.limit_price", incoming.limit_price, true);
  else if (incoming.limit_price != null) throw new RangeError("market order must not carry limit_price");
  const opposite = side === "buy" ? "sell" : "buy";
  const book = parseResting(restingRaw, opposite);
  if (book.some(order => order.order_id === orderId)) throw new RangeError("incoming and resting order IDs must be unique");
  book.sort((a, b) => side === "buy" ? a.price - b.price || a.arrival_sequence - b.arrival_sequence : b.price - a.price || a.arrival_sequence - b.arrival_sequence);
  let remaining = quantity, notional = 0;
  const fills: JsonObject[] = [];
  for (const order of book) {
    const marketable = limitPrice == null || (side === "buy" ? order.price <= limitPrice : order.price >= limitPrice);
    if (!marketable) break;
    const fill = Math.min(remaining, order.remaining_quantity);
    if (fill <= 0) continue;
    order.remaining_quantity -= fill; remaining -= fill; notional += fill * order.price;
    fills.push({resting_order_id: order.order_id, price: order.price, quantity: fill, arrival_sequence: order.arrival_sequence});
    if (remaining <= 1e-12) { remaining = 0; break; }
  }
  const filled = quantity - remaining;
  return {
    model: "single-venue-price-time-priority", incoming_order_id: orderId, requested_quantity: quantity,
    filled_quantity: filled, residual_quantity: remaining, average_fill_price: filled ? notional / filled : null,
    fill_count: fills.length, fills, final_resting_orders: book.filter(order => order.remaining_quantity > 0),
    state: remaining === 0 ? "filled" : filled ? "partially-filled" : "unfilled",
  };
}

function singlePriceInputs(incomingRaw: unknown, priceRaw: unknown, lotRaw: unknown, restingRaw: unknown): [number, number, number, JsonObject[]] {
  const incoming = num("incoming_quantity", incomingRaw, true), price = num("price", priceRaw, true), lot = num("lot_size", lotRaw, true);
  multiple("incoming_quantity", incoming, lot);
  const orders = parseResting(restingRaw), side = orders[0].side;
  orders.forEach(order => {
    if (order.side !== side) throw new RangeError("single-price allocation requires one resting side");
    if (Math.abs(order.price - price) > 1e-12) throw new RangeError("every resting order must be at price");
    multiple("remaining_quantity", order.remaining_quantity, lot);
  });
  return [incoming, price, lot, orders];
}

function proRataUnits(orders: JsonObject[], allocationUnits: number, lot: number): Record<string, number> {
  const capacities: Record<string, number> = {};
  orders.forEach(order => capacities[order.order_id] = Math.round(order.remaining_quantity / lot));
  const totalCapacity = Object.values(capacities).reduce((a, b) => a + b, 0), units = Math.min(allocationUnits, totalCapacity);
  if (units <= 0) return Object.fromEntries(orders.map(order => [order.order_id, 0]));
  const raw: Record<string, number> = {}, allocated: Record<string, number> = {};
  orders.forEach(order => {
    raw[order.order_id] = units * capacities[order.order_id] / totalCapacity;
    allocated[order.order_id] = Math.min(capacities[order.order_id], Math.floor(raw[order.order_id]));
  });
  let remainder = units - Object.values(allocated).reduce((a, b) => a + b, 0);
  const rank = [...orders].sort((a, b) => {
    const fa = raw[a.order_id] - Math.floor(raw[a.order_id]), fb = raw[b.order_id] - Math.floor(raw[b.order_id]);
    return fb - fa || capacities[b.order_id] - capacities[a.order_id] || a.arrival_sequence - b.arrival_sequence;
  });
  while (remainder > 0) {
    let progressed = false;
    for (const order of rank) {
      if (allocated[order.order_id] < capacities[order.order_id]) {
        allocated[order.order_id] += 1; remainder -= 1; progressed = true;
        if (remainder === 0) break;
      }
    }
    if (!progressed) break;
  }
  return allocated;
}

export function proRataMatching(incomingRaw: unknown, priceRaw: unknown, lotRaw: unknown, restingRaw: unknown): JsonObject {
  const [incoming, price, lot, orders] = singlePriceInputs(incomingRaw, priceRaw, lotRaw, restingRaw);
  const executable = Math.min(incoming, orders.reduce((sum, order) => sum + order.remaining_quantity, 0));
  const units = proRataUnits(orders, Math.round(executable / lot), lot);
  const allocations = [...orders].sort((a, b) => a.arrival_sequence - b.arrival_sequence).map(order => {
    const quantity = units[order.order_id] * lot;
    return {order_id: order.order_id, resting_quantity: order.remaining_quantity, allocated_quantity: quantity, remaining_quantity: order.remaining_quantity - quantity, arrival_sequence: order.arrival_sequence};
  });
  const allocated = allocations.reduce((sum, row) => sum + row.allocated_quantity, 0);
  return {model: "single-price-lot-aware-pro-rata", price, lot_size: lot, incoming_quantity: incoming, executable_quantity: executable, allocated_quantity: allocated, unfilled_quantity: incoming - allocated, allocations, state: allocated === incoming ? "fully-allocated" : "partially-allocated"};
}

export function sizeTimePriority(incomingRaw: unknown, priceRaw: unknown, lotRaw: unknown, restingRaw: unknown): JsonObject {
  const [incoming, price, lot, orders] = singlePriceInputs(incomingRaw, priceRaw, lotRaw, restingRaw);
  const ranked = [...orders].sort((a, b) => b.remaining_quantity - a.remaining_quantity || a.arrival_sequence - b.arrival_sequence);
  let remaining = incoming;
  const allocations: JsonObject[] = [];
  for (let index = 0; index < ranked.length; index += 1) {
    const order = ranked[index], quantity = Math.min(remaining, order.remaining_quantity);
    remaining -= quantity;
    allocations.push({rank: index + 1, order_id: order.order_id, resting_quantity: order.remaining_quantity, allocated_quantity: quantity, remaining_quantity: order.remaining_quantity - quantity, arrival_sequence: order.arrival_sequence});
    if (remaining <= 1e-12) { remaining = 0; break; }
  }
  const allocated = incoming - remaining;
  return {model: "single-price-size-then-time-priority", price, lot_size: lot, incoming_quantity: incoming, allocated_quantity: allocated, unfilled_quantity: remaining, ranked_order_ids: ranked.map(order => order.order_id), allocations, state: remaining === 0 ? "fully-allocated" : "partially-allocated"};
}

export function hybridProRataTime(incomingRaw: unknown, priceRaw: unknown, lotRaw: unknown, fractionRaw: unknown, restingRaw: unknown): JsonObject {
  const [incoming, price, lot, orders] = singlePriceInputs(incomingRaw, priceRaw, lotRaw, restingRaw);
  const fraction = num("fifo_fraction", fractionRaw);
  if (fraction < 0 || fraction > 1) throw new RangeError("fifo_fraction must be between zero and one");
  const executable = Math.min(incoming, orders.reduce((sum, order) => sum + order.remaining_quantity, 0));
  const totalUnits = Math.round(executable / lot), fifoUnits = Math.floor(totalUnits * fraction + 1e-12);
  const fifoAlloc: Record<string, number> = Object.fromEntries(orders.map(order => [order.order_id, 0]));
  let fifoRemaining = fifoUnits;
  for (const order of [...orders].sort((a, b) => a.arrival_sequence - b.arrival_sequence)) {
    const capacity = Math.round(order.remaining_quantity / lot), take = Math.min(fifoRemaining, capacity);
    fifoAlloc[order.order_id] = take; fifoRemaining -= take;
    if (fifoRemaining === 0) break;
  }
  const residual = orders.flatMap(order => {
    const residualUnits = Math.round(order.remaining_quantity / lot) - fifoAlloc[order.order_id];
    return residualUnits > 0 ? [{...order, remaining_quantity: residualUnits * lot}] : [];
  });
  const proUnits = totalUnits - fifoUnits, proAlloc = residual.length ? proRataUnits(residual, proUnits, lot) : {};
  const allocations = [...orders].sort((a, b) => a.arrival_sequence - b.arrival_sequence).map(order => {
    const fifoQuantity = fifoAlloc[order.order_id] * lot, proQuantity = (proAlloc[order.order_id] || 0) * lot, total = fifoQuantity + proQuantity;
    return {order_id: order.order_id, resting_quantity: order.remaining_quantity, fifo_quantity: fifoQuantity, pro_rata_quantity: proQuantity, allocated_quantity: total, remaining_quantity: order.remaining_quantity - total, arrival_sequence: order.arrival_sequence};
  });
  const allocated = allocations.reduce((sum, row) => sum + row.allocated_quantity, 0);
  return {model: "single-price-fifo-pro-rata-split", price, lot_size: lot, fifo_fraction: fraction, incoming_quantity: incoming, executable_quantity: executable, fifo_target_quantity: fifoUnits * lot, pro_rata_target_quantity: proUnits * lot, allocated_quantity: allocated, unfilled_quantity: incoming - allocated, allocations, state: allocated === incoming ? "fully-allocated" : "partially-allocated"};
}

export function calculate(topicId: string, inputs: JsonObject): JsonObject {
  if (!inputs || typeof inputs !== "object" || Array.isArray(inputs)) throw new TypeError("inputs must be an object");
  if (topicId === "D12-F01-A01") return priceTimePriority(inputs.incoming_order, inputs.resting_orders);
  if (topicId === "D12-F01-A02") return proRataMatching(inputs.incoming_quantity, inputs.price, inputs.lot_size, inputs.resting_orders);
  if (topicId === "D12-F01-A03") return sizeTimePriority(inputs.incoming_quantity, inputs.price, inputs.lot_size, inputs.resting_orders);
  if (topicId === "D12-F01-A04") return hybridProRataTime(inputs.incoming_quantity, inputs.price, inputs.lot_size, inputs.fifo_fraction, inputs.resting_orders);
  throw new RangeError(`unsupported topic_id: ${topicId}`);
}