Skip to content
Criée

The domain in ten objects

Order, book, execution, position, cash account, settlement: the market’s objects, their relationships and where the engine stops.

Lesson 110 min

By the end of this lesson

  • Tell an order, an execution and a settlement apart in code
  • Treat the settlement delay as a parameter, since no text fixes it
  • Explain why numbering executions makes an import replayable without duplicates
In this lesson4

A matching engine does not handle "finance". It handles about ten objects with precise relationships. Naming them correctly prevents a whole family of bugs: an order is not an execution, an execution is not a settlement, a position is not a balance.

Before the code, the business view: follow a buy order from place to place, and watch its stamp change at each step.

The life of a buy order1/6

The order is born

Awa decides to buy 40 shares of the fictional company Kapok, paying no more than 10,000 F each: a limit order.

The journey of a purchase

Follow a purchase from end to end. A fictional client wants 40 shares of an invented company.

From an order to a position

1/6Order

The client gives an order to her brokerage firm: buy 40 shares, at 10,100 francs at most.

Each step rests on a text. Only brokerage firms licensed by COSUMAF may trade on the BVMAC (Regulation 01/22, art. 161). Every order is timestamped as soon as the brokerage firm receives it (BVMAC General Rules 2025, art. 150). The BVMAC sends trade data to the central depository, to guarantee delivery of the securities and payment of the price (same text, art. 220 and 231). The BEAC holds this role on a transitional basis (COSUMAF decision of 2019).

Ten objects, ten types

Tap an object: its relationships appear, with their multiplicity (for one object on the left, how many objects on the right).

The domain in ten objectstap an object
  • Executionpairs, on the buy side and the sell side, anOrder1..2
  • Executiongives rise to aSettlement1..1

Execution

A trade concluded between a buy order and a sell order, for a quantity and at a price.

Three distinctions matter more than the others when you write code.

  • Order and execution. An incoming order can produce zero, one or several executions (Euronext Trading Manual, 2021, section 3.2.1). The relationship is therefore "one to many", never "one to one".
  • Execution and settlement. The execution is a commitment made on the market. Settlement is the actual transfer, later, at the central depository.
  • Position and cash account. Two separate quantities, updated together by the same settlement, in opposite directions.

Where the engine stops

The teaching engine @criee/marche covers the left half of the map: orders, book, executions. The rest lives downstream, in the brokerage firm's software.

import type { Execution } from '@criee/marche'

// What the engine produces
const e: Execution = { achat: 'a1', vente: 'v1', prix: 10100, quantite: 40 }

// What the engine ignores: account keeping, on the software side
interface Position { compte: string; titre: string; quantite: number }
interface MouvementEspeces { compte: string; montant: number } // francs, integer

This boundary is a design choice: the engine stays pure, with no database or network, and so can be tested in isolation.

The same story, seen through the types. At each step the object changes nature; the red dashes mark where the engine stops. Look at step 3: one order, two executions.

From type to position1/5
Order
Book
Executions
Movements
Position

red dashes: where the engine stops

Omit<Ordre, 'rang'>

{
id: 'a1'
sens: 'achat'
quantite: 40
limite: 10100
}

received by the brokerage firm

An order: an intention

Awa (fictional) wants 40 shares at 10,100 at most. Nothing is traded yet: the object carries no price paid and no rank.

How many days separate execution from settlement on the BVMAC? No text found sets it. The Official Price List computes accrued interest at T+3, which is only a clue. Do not hard-code this delay: make it a parameter.

From memory: what is the difference between an execution and a settlement?

Going further

An execution with no identifier. The engine's Execution type has no id field. As long as executions stay in memory, that does no harm. As soon as they leave the engine (file, message, database), the software must recognise an execution it has already received, otherwise a replayed import would count the same shares twice. Let us take Awa's journey again, step by step:

const c = new Carnet(10000)
c.passer({ id: 'v1', sens: 'vente', quantite: 25, limite: 10050 }) // []
c.passer({ id: 'v2', sens: 'vente', quantite: 30, limite: 10100 }) // []
const ex = c.passer({ id: 'a1', sens: 'achat', quantite: 40, limite: 10100 })
// [{ achat: 'a1', vente: 'v1', prix: 10050, quantite: 25 },
//  { achat: 'a1', vente: 'v2', prix: 10100, quantite: 15 }]

ex.reduce((s, e) => s + e.quantite, 0)          // 40: the sum equals the order filled
ex.reduce((s, e) => s + e.prix * e.quantite, 0) // 402750: two prices, one amount
  1. The first two calls produce nothing: there is no buyer yet.
  2. The third produces two executions, at two prices: v1's, then v2's.
  3. The quantities add up to 40: the simplest check of the one-to-many relationship.
  4. The amount paid is not 40 × 10,100, but the sum of each execution's amount.

For the identifier, one possible design choice: number each execution as it leaves the engine, in the order the engine returns them, and make that number the import key.

const numerotees = ex.map((e, n) => ({ ...e, ref: `S1-${n + 1}` })) // S1: fictional session
const recues = new Map(numerotees.map((e) => [e.ref, e]))         // re-importing doubles nothing

That number is only stable if the engine is deterministic: the same session must return the same executions in the same order (lesson An engine's invariants). Turning these executions into movements and entries is the subject of the lesson From an execution to entries.

From memory: a buy of 40 is filled by two sells, at 10,050 then at 10,100. How many securities movements for the buyer, and what do they add up to?

Your turn

A buy order for 40 shares can produce...

1A buy order for 40 shares can produce...

Who forwards a client's order to the BVMAC market?

2Who forwards a client's order to the BVMAC market?

What does the settlement of an execution change?

3What does the settlement of an execution change?

How should you code the settlement delay?

4How should you code the settlement delay?

Why number executions as they leave the engine?

5Why number executions as they leave the engine?

Read next: Règlement général de la BVMAC (2025)

A question? Ask your teacher, or an AI assistant, giving it the title of this lesson.

Share:WhatsAppLinkedIn

Going further