Sheet: the engine contract
The @criee/marche API, guarantees and known limits, on one page.
Reference5 min
By the end of this lesson
- Recall the signature and guarantees of each engine function
- Recall the known limits of the teaching engine, each one to test
In this lesson7
The public API of @criee/marche, what it guarantees and what it does not. Prices and quantities are integers; limite: null denotes a market order.
Types
type Sens = 'achat' | 'vente'
interface Ordre { id: string; sens: Sens; quantite: number; limite: number | null; rang: number; auteur?: string }
interface Execution { achat: string; vente: string; prix: number; quantite: number }
interface Niveau { prix: number; quantite: number; ordres: number }
interface VueCarnet { achats: Niveau[]; ventes: Niveau[] }
interface PointCourbe { prix: number; demande: number; offre: number; volume: number; desequilibre: number }
interface ResultatFixing {
prix: number | null; volume: number; courbe: PointCourbe[]; executions: Execution[]
regle: 'volume' | 'desequilibre' | 'pression' | 'reference' | 'aucun-echange'
}
Continuous trading: Carnet
new Carnet(prixReference = null): empty book; the reference price serves as the initial last price.passer(ordre):ordrewithoutrang(assigned automatically) or with one. Returns the executions triggered, in priority order. Throws ifquantiteis not a strictly positive integer.annuler(id): removes the resting order;falseif it no longer exists.prix: last execution price, or the reference price, ornull.ordres(): resting orders on both sides, sorted by priority.vue(profondeur = 5): aggregated price levels, market orders excluded.fourchette():{ achat, vente, ecart }, each fieldnullif a side is empty.
Auction: fixing(ordres, prixReference = null)
A pure function. Candidates are the limits present (the reference price only if there are none). Tie-breaks in order: maximum volume, smallest absolute imbalance, pressure, closeness to the reference price. Allocation by price then time priority, at the single price. No cross: prix: null, regle: 'aucun-echange'.
Utilities
trierCote(ordres, sens): a copy sorted by price then time priority; market orders first.agreger(ordres): groups already sorted orders into price levels.
Guarantees
For inputs that are valid in the sense of lesson 2:
- Execution at the price of the order already in the book (continuous); at the single price (auction).
- No execution outside either order's limit.
- The book is never crossed after
passer. - Same sequence of inputs, same sequence of outputs: no clock and no randomness in the engine.
Known limits of the teaching engine
Each one deserves a test, then a decision:
ordres()returns the internal objects: changing a returned order changes the book.limiteis not validated: negative, decimal orNaNvalues are accepted.- Identifiers are not checked: two orders can share an
id, andannulerremoves them all. - A rejected order still consumes a rank; a
rangsupplied by the caller is not checked. - The remainder of a market order disappears at once, whereas the BVMAC General Rules 2025 remove it "on expiry".
fixingdoes not validate quantities (zero or negative are accepted).fixingdoes not add the reference price to the candidates when limit orders exist: market orders that only cross each other do not trade at the reference price, unlike the Euronext manual.- Without a reference price, the
'reference'rule takes the median candidate: undocumented behaviour.
What the engine does not provide
Three absences shape the code around it:
- No amendment. It is written with
annulerthenpasser, re-submitting the oldrangwhen priority is kept (Amending and cancelling an order). Validate before cancelling, or the order is lost. - No log and no exposed counter. A restored book numbers again from 1: a log meant to be replayed from a snapshot must carry each order's rank (Logging and replaying a session).
- No execution identifier.
Executionhas neither number nor time: the reference that makes an import idempotent comes from outside (From an execution to entries).
From memory: what does fixing() return when no price allows a trade?
Read next: Euronext Trading Manual, 5 juillet 2021
A question? Ask your teacher, or an AI assistant, giving it the title of this lesson.