Maximum-Executable-Volume Auction

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

export type JsonObject = Record<string, any>;

function num(name: string, value: unknown, positive = false, nonnegative = 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`);
  if (nonnegative && value < 0) throw new RangeError(`${name} must be nonnegative`);
  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 onTick(value: number, tick: number): boolean {
  return Math.abs(value / tick - Math.round(value / tick)) <= 1e-8;
}
function parseOrders(raw: unknown, tick: number): JsonObject[] {
  if (!Array.isArray(raw) || raw.length === 0) throw new RangeError("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(`orders[${index}] must be an object`);
    const order = item as JsonObject, orderId = text(`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(`orders[${index}].side`, order.side);
    if (!["buy", "sell"].includes(side)) throw new RangeError("order side must be buy or sell");
    const orderType = text(`orders[${index}].order_type`, order.order_type);
    const sequence = integer(`orders[${index}].arrival_sequence`, order.arrival_sequence, true);
    if (sequences.has(sequence)) throw new RangeError("arrival_sequence values must be unique"); sequences.add(sequence);
    const quantity = num(`orders[${index}].quantity`, order.quantity, true);
    let price: number | null = null;
    if (["market", "MOO", "MOC"].includes(orderType)) {
      if (order.price != null) throw new RangeError("market-style auction orders must not carry a price");
    } else if (["limit", "LOO", "LOC", "DAY"].includes(orderType)) {
      price = num(`orders[${index}].price`, order.price, true);
      if (!onTick(price, tick)) throw new RangeError("order price must align with tick_size");
    } else throw new RangeError(`unsupported auction order_type: ${orderType}`);
    return {order_id: orderId, side, order_type: orderType, price, quantity, arrival_sequence: sequence};
  });
}
function evaluationAt(price: number, orders: JsonObject[]): JsonObject {
  const buy = orders.filter(order => order.side === "buy" && (order.price == null || order.price >= price)).reduce((sum, order) => sum + order.quantity, 0);
  const sell = orders.filter(order => order.side === "sell" && (order.price == null || order.price <= price)).reduce((sum, order) => sum + order.quantity, 0);
  const executable = Math.min(buy, sell), imbalance = buy - sell;
  return {price, buy_quantity: buy, sell_quantity: sell, executable_quantity: executable, imbalance_quantity: imbalance, absolute_imbalance: Math.abs(imbalance), imbalance_side: imbalance > 0 ? "buy" : imbalance < 0 ? "sell" : "none"};
}
function evaluateBook(ordersRaw: unknown, referenceRaw: unknown, tickRaw: unknown, low: number | null = null, high: number | null = null): [JsonObject[], number, number, JsonObject[]] {
  const reference = num("reference_price", referenceRaw, true), tick = num("tick_size", tickRaw, true);
  if (!onTick(reference, tick)) throw new RangeError("reference_price must align with tick_size");
  const orders = parseOrders(ordersRaw, tick), priceSet = new Set<number>([reference]);
  orders.forEach(order => { if (order.price != null) priceSet.add(order.price); });
  const candidates = [...priceSet].filter(price => (low == null || price >= low - 1e-12) && (high == null || price <= high + 1e-12)).sort((a, b) => a - b);
  if (!candidates.length) throw new RangeError("no candidate price remains inside the declared collar");
  return [orders, reference, tick, candidates.map(price => evaluationAt(price, orders))];
}

export function maximumExecutableVolumeAuction(ordersRaw: unknown, referenceRaw: unknown, tickRaw: unknown): JsonObject {
  const [orders, reference, tick, evaluations] = evaluateBook(ordersRaw, referenceRaw, tickRaw);
  const maximum = Math.max(...evaluations.map(row => row.executable_quantity)), winners = evaluations.filter(row => row.executable_quantity === maximum);
  return {model: "maximum-executable-volume-candidate-set", reference_price: reference, tick_size: tick, order_count: orders.length, maximum_executable_quantity: maximum, maximum_volume_prices: winners.map(row => row.price), unique_price: winners.length === 1 ? winners[0].price : null, candidate_evaluations: evaluations, state: maximum === 0 ? "no-cross" : winners.length === 1 ? "unique-maximum" : "maximum-volume-tie"};
}

export function minimumImbalanceTieBreak(ordersRaw: unknown, referenceRaw: unknown, tickRaw: unknown): JsonObject {
  const [orders, reference, tick, evaluations] = evaluateBook(ordersRaw, referenceRaw, tickRaw);
  const maximum = Math.max(...evaluations.map(row => row.executable_quantity));
  const volumeWinners = evaluations.filter(row => row.executable_quantity === maximum);
  const minimum = Math.min(...volumeWinners.map(row => row.absolute_imbalance));
  const winners = volumeWinners.filter(row => row.absolute_imbalance === minimum);
  return {model: "maximum-volume-then-minimum-imbalance", reference_price: reference, tick_size: tick, order_count: orders.length, maximum_executable_quantity: maximum, minimum_absolute_imbalance: minimum, volume_winner_prices: volumeWinners.map(row => row.price), minimum_imbalance_prices: winners.map(row => row.price), selected_price: winners.length === 1 ? winners[0].price : null, candidate_evaluations: evaluations, state: maximum === 0 ? "no-cross" : winners.length === 1 ? "tie-resolved" : "tie-remains"};
}

function crossPrice(session: string, ordersRaw: unknown, referenceRaw: unknown, tickRaw: unknown, lowRaw: unknown, highRaw: unknown): JsonObject {
  const reference = num("reference_price", referenceRaw, true), tick = num("tick_size", tickRaw, true), low = num("collar_low", lowRaw, true), high = num("collar_high", highRaw, true);
  if (low > reference || high < reference || low > high) throw new RangeError("collar must contain the reference price");
  if (![reference, low, high].every(value => onTick(value, tick))) throw new RangeError("reference and collar prices must align with tick_size");
  const parsed = parseOrders(ordersRaw, tick), allowed = new Set(session === "opening" ? ["MOO", "LOO", "DAY"] : ["MOC", "LOC", "DAY"]);
  if (parsed.some(order => !allowed.has(order.order_type))) throw new RangeError(`unsupported order type for ${session} cross`);
  const [, , , evaluations] = evaluateBook(parsed, reference, tick, low, high);
  const maximum = Math.max(...evaluations.map(row => row.executable_quantity));
  if (maximum === 0) return {model: `declared-${session}-cross`, session, reference_price: reference, collar_low: low, collar_high: high, selected_price: null, executed_quantity: 0, imbalance_quantity: 0, selection_trace: ["no candidate price executes both sides"], candidate_evaluations: evaluations, state: "no-cross"};
  let stage = evaluations.filter(row => row.executable_quantity === maximum);
  const trace = [`maximize executable quantity at ${maximum}`];
  const minimum = Math.min(...stage.map(row => row.absolute_imbalance));
  stage = stage.filter(row => row.absolute_imbalance === minimum); trace.push(`minimize absolute imbalance at ${minimum}`);
  let selected: JsonObject;
  if (stage.length > 1) {
    const signs = new Set(stage.map(row => row.imbalance_side));
    if (signs.size === 1 && signs.has("buy")) {
      selected = stage.reduce((a, b) => a.price > b.price ? a : b); trace.push("buy surplus selects the highest remaining price");
    } else if (signs.size === 1 && signs.has("sell")) {
      selected = stage.reduce((a, b) => a.price < b.price ? a : b); trace.push("sell surplus selects the lowest remaining price");
    } else {
      selected = [...stage].sort((a, b) => Math.abs(a.price - reference) - Math.abs(b.price - reference) || a.price - b.price)[0];
      trace.push("mixed or zero surplus selects the price nearest the reference");
    }
  } else { selected = stage[0]; trace.push("the objective hierarchy leaves one price"); }
  return {model: `declared-${session}-cross`, session, reference_price: reference, collar_low: low, collar_high: high, eligible_order_count: parsed.length, selected_price: selected.price, executed_quantity: selected.executable_quantity, buy_quantity: selected.buy_quantity, sell_quantity: selected.sell_quantity, imbalance_quantity: selected.imbalance_quantity, imbalance_side: selected.imbalance_side, selection_trace: trace, candidate_evaluations: evaluations, state: "crossed"};
}

export function openingCrossPrice(orders: unknown, previousClose: unknown, tick: unknown, low: unknown, high: unknown): JsonObject {
  return crossPrice("opening", orders, previousClose, tick, low, high);
}
export function closingCrossPrice(orders: unknown, reference: unknown, tick: unknown, low: unknown, high: unknown): JsonObject {
  return crossPrice("closing", orders, reference, tick, low, high);
}

export function volatilityAuctionReopening(inputs: JsonObject): JsonObject {
  const reference = num("reference_price", inputs.reference_price, true);
  const dynamicRef = num("dynamic_reference", inputs.dynamic_reference, true), dynamicPct = num("dynamic_band_pct", inputs.dynamic_band_pct, true);
  const staticRef = num("static_reference", inputs.static_reference, true), staticPct = num("static_band_pct", inputs.static_band_pct, true);
  const potential = num("potential_continuous_price", inputs.potential_continuous_price, true), indicative = num("indicative_auction_price", inputs.indicative_auction_price, true);
  const multiplier = num("extended_band_multiplier", inputs.extended_band_multiplier, true);
  if (multiplier < 1) throw new RangeError("extended_band_multiplier must be at least one");
  const executable = num("executable_quantity", inputs.executable_quantity, false, true);
  const dynamicLow = dynamicRef * (1 - dynamicPct), dynamicHigh = dynamicRef * (1 + dynamicPct);
  const staticLow = staticRef * (1 - staticPct), staticHigh = staticRef * (1 + staticPct);
  const dynamicBreach = potential < dynamicLow || potential > dynamicHigh, staticBreach = potential < staticLow || potential > staticHigh, triggered = dynamicBreach || staticBreach;
  const expandedDynamicLow = dynamicRef * (1 - dynamicPct * multiplier), expandedDynamicHigh = dynamicRef * (1 + dynamicPct * multiplier);
  const expandedStaticLow = staticRef * (1 - staticPct * multiplier), expandedStaticHigh = staticRef * (1 + staticPct * multiplier);
  const inside = indicative >= expandedDynamicLow && indicative <= expandedDynamicHigh && indicative >= expandedStaticLow && indicative <= expandedStaticHigh;
  let state: string, reopened: boolean, reopenPrice: number | null, reason: string;
  if (!triggered) { state = "continuous"; reopened = false; reopenPrice = null; reason = "potential price remains inside both active corridors"; }
  else if (executable === 0) { state = "auction-no-cross"; reopened = false; reopenPrice = null; reason = "volatility auction has no executable quantity"; }
  else if (inside) { state = "reopened"; reopened = true; reopenPrice = indicative; reason = "indicative auction price is executable and inside both expanded corridors"; }
  else { state = "extended-volatility-auction"; reopened = false; reopenPrice = null; reason = "indicative auction price remains outside an expanded corridor"; }
  return {model: "dual-corridor-volatility-auction-reopening", reference_price: reference, potential_continuous_price: potential, dynamic_corridor: [dynamicLow, dynamicHigh], static_corridor: [staticLow, staticHigh], dynamic_breach: dynamicBreach, static_breach: staticBreach, triggered, indicative_auction_price: indicative, executable_quantity: executable, expanded_dynamic_corridor: [expandedDynamicLow, expandedDynamicHigh], expanded_static_corridor: [expandedStaticLow, expandedStaticHigh], inside_reopening_corridor: inside, reopened, reopen_price: reopenPrice, reason, state};
}

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-F02-A01") return maximumExecutableVolumeAuction(inputs.orders, inputs.reference_price, inputs.tick_size);
  if (topicId === "D12-F02-A02") return minimumImbalanceTieBreak(inputs.orders, inputs.reference_price, inputs.tick_size);
  if (topicId === "D12-F02-A03") return openingCrossPrice(inputs.orders, inputs.previous_close, inputs.tick_size, inputs.collar_low, inputs.collar_high);
  if (topicId === "D12-F02-A04") return closingCrossPrice(inputs.orders, inputs.closing_reference, inputs.tick_size, inputs.collar_low, inputs.collar_high);
  if (topicId === "D12-F02-A05") return volatilityAuctionReopening(inputs);
  throw new RangeError(`unsupported topic_id: ${topicId}`);
}