BullionVault course · Lesson 0002

Lesson 0002 · matching

Price, Time, Priority

Four rules for matching orders, three of them broken, and one bug that costs the client money on every trade.

Lesson 0001 made the numbers trustworthy. This one is about the thing those numbers are for: BullionVault's order board, where clients deal directly with each other rather than against a dealer's quote.¹ That is the actual product, and matching is its core.

Do this now

cd ~/Desktop/training/bullionvault/exercise/commodities-service
JAVA_HOME=$(/usr/libexec/java_home -v 25) ~/.local/maven/bin/mvn test

The failures, in full:

buyerDealsAtTheRestingOfferPrice     expected USD 96000.000000/kg  but was USD 99000.000000/kg
sellerDealsAtTheRestingBidPrice      expected USD 96200.000000/kg  but was USD 90000.000000/kg
eachFillKeepsItsOwnRestingPrice      expected [96000, 96100]       but was [99000, 99000]
fillKnowsItsConsideration            expected USD 24000.00         but was USD 24750.00
earlierOfTwoEqualOffersDealsFirst    expected [early]              but was [late]
sweepsEqualPricesInArrivalOrder      expected [first,second,third] but was [third,second,first]
smallOrderTakesPartOfALargeRestingOffer          expected [250g]   but was []
remainderOfAPartlyFilledRestingOrderStaysOnBoard expected [750g]   but was [250g, 1000g]

Rule 1 · price priority — already correct

Both tests in this group pass. Worth a moment anyway, because it is the only rule the code got right and you should be able to say why:

incomingSide == Side.BID
    ? Comparator.comparing(Order::limit)              // cheapest offer first
    : Comparator.comparing(Order::limit).reversed();  // highest bid first

The asymmetry is the domain, not a trick: a buyer wants the lowest number and a seller wants the highest, so "best" reverses with the side.

Rule 2 · time priority — and two ways to make it green

This failure is the most legible thing in the suite:

sweepsEqualPricesInArrivalOrder
    expected: [first, second, third]
    but was:  [third, second, first]

Exactly reversed. Not scrambled, not off by one — reversed. That is the signature of a stack, and there is one hiding in the code:

resting.addFirst(incoming.withQuantity(remaining));

Orders are pushed onto the front of the list. The comparator sorts on price alone, and Stream.sorted is a stable sort — it preserves the existing order of equal elements. So equal prices come out newest-first, and the client who has been waiting longest gets served last.

Comparator<Order> byPrice = incomingSide == Side.BID
        ? Comparator.comparing(Order::limit)
        : Comparator.comparing(Order::limit).reversed();
return byPrice.thenComparingLong(Order::sequence);

Rule 3 · price improvement — the bug that costs real money

BullionVault says it plainly: "you will deal at a better price than your limit price if someone is still quoting a price which is better than your limit when your order is received."²

The code does the opposite:

fills.add(new Fill(incoming.id(), r.id(), r.quantity(), incoming.limit()));

Your limit is the worst price you will accept. Filling at it means every client always pays their worst case. In the test, a buyer willing to go to 99,000 meets a seller resting at 96,000 — and is charged 99,000.

Three per cent, silently, on every trade — and note which test caught the consequence: fillKnowsItsConsideration, which runs your lesson 0001 Pricing.consideration over the fill. The money code was right. It was handed the wrong price.

The fix is one identifier: r.limit().

Rule 4 · partial fills

Two failures, one line:

if (r.quantity().compareTo(remaining) > 0) {
    continue;   // resting order is bigger than what I want — skip it entirely
}

A 250 g buyer meets a 1 kg offer and walks away with nothing. Note the direction: an incoming order larger than a resting one fills fine, so this only breaks when you want less than is on the board — which, on a market that lets people deal in single grams against kilobars, is most of the time.

What it should do: deal the smaller of the two, and put back whatever is left of the resting order.

long dealt = Math.min(remaining.grams(), r.quantity().grams());
fills.add(new Fill(incoming.id(), r.id(), Quantity.ofGrams(dealt), r.limit()));
remaining = Quantity.ofGrams(remaining.grams() - dealt);

resting.remove(r);
long unfilled = r.quantity().grams() - dealt;
if (unfilled > 0) {
    resting.add(r.withQuantity(Quantity.ofGrams(unfilled)));
}

BullionVault's own description matches: some or all executes, and what is left is posted back as an active limit — and only the unexecuted part can be cancelled, because the filled part is a done deal.²

Say it out loud

• “Exact reversal — that's a stack, not a comparator problem.”
• “Filling at the incoming limit means every client always pays their worst case.”
• “I could make this green by changing the append, but then the rule isn't written down anywhere.”

Read this

References

• 1. BullionVault, Markets & order board FAQ — clients deal directly with each other, choosing their own price.
• 2. BullionVault, Using the order panel — in detail — price improvement, partial matches resting as active limits, and cancelling only the unexecuted part.
• 3. CME Group, CME Globex Matching Algorithms — FIFO price–time priority, and priority loss on modification.

Carry on

• Reference card: Bullion & order-board glossary — price improvement, partial match, price–time priority
• Reference card: BigDecimal & money survival card
• Back to: Lesson 0001 — Money That Doesn't Leak
• Next: Lesson 0003 — Two Buyers, One Bar (the shared mutable board, and the lost update)

Bring me your OrderBook.place when it's green — I'll review it the way a peer reviewer at BullionVault would, since peer code review is one of the three responsibilities in their spec. And if you think one of these tests encodes the wrong rule, say so: two of them are judgement calls, not facts.