Trade Versioning

Table of Contents

1. Summary

A trade is not replaced when it changes. Each change produces a new version, and the history of versions is what the firm can be held to.

A trade carries two version numbers, because two audiences ask different questions of it, and they move at different rates. Confirmations depend on one of them; trade activity supplies the causes that move either.

2. The two-version rule

A trade carries two version numbers.

  • The internal version moves on every recorded change to the trade. It is the audit trail. It answers "what did we hold, and when". It is the version column every generated entity carries, so the rules in optimistic concurrency versioning govern who may move it and what a writer must claim to be allowed to.
  • The external version moves only when the terms the customer has agreed to change. It is the commercial record. It answers "what has the customer agreed to".

The rule in one sentence: a trade changes version only if the agreement with the customer has changed.

The external version is the handle the customer's records match. When a client queries a trade, they quote the version they hold. A system that bumps the external version for internal reasons forces a confirmation the customer never agreed to and never asked for.

Two consequences are worth stating plainly:

  1. Operational authorisation does not bump either version. It is our workflow state, not a term of the trade. Treating it as a term would make the firm issue confirmations for its own internal approvals. Operational authorisation is metadata on the trade.
  2. An economic change is normally confirmable, and a non-economic change normally is not. The two properties are close, but they are not the same property, and the next section separates them.

3. Where the classification comes from

Amendments are classified on four orthogonal axes. They are not values of one enumeration, and an amendment sits on all four at once.

Axis Values What it decides
Economic Economic / non-economic Whether the trade must be revalued
Confirmable Confirmable / non-confirmable Whether a new confirmation is issued
Real Real / null Whether anything at all feeds downstream
Customer-visible External version moves / does not move Whether the customer sees a change

Two combinations deserve a note.

A null amend is real on none of the axes. The value entered equals the value held, so nothing changed. The record of the attempt is worth keeping for the audit trail, but a null amend must not move the external version and must not raise a confirmation.

A misbooking correction is real and economic, and it is confirmable, even though it is not a change of mind. It corrects an error in the original booking terms, so the confirmed terms change, and the customer must agree them again.

4. One activity per version

Each version carries one activity record that states why it exists. Where several causes land at once, the system records them in a fixed priority order and the highest-priority cause names the version. The priority order exists because one-activity-per-version is an aim, not a guarantee: a batch may deliver a rate reset and a correction together.

Trade activity sets out the four axes an amendment sits on, and which combinations move which version.

5. The reason for update

Every version carries a reason for update, drawn from an enumeration rather than typed as free text, so that changes can be reported on rather than only read.

Two attributes qualify it. The action type distinguishes a human change from a system one, and the action name says which change it was. Separating them answers "how much of yesterday's activity was automatic" without inspecting each reason in turn.

5.1. The enumeration

The reasons observed span four groups, and the groups are worth keeping distinct because they answer different questions.

Group Examples
Provisional Pre Live Created, Pre Live Amendment
Lifecycle Automated Fixing, Manual Fixing, Expiry, Fixing, Termination, Coupon Payment
Amendment Amendment: Direction, Rate, Notional, Yield Basis; Amended Counterparty; Amendment: Single-sided; Dummy Amendment
Structural Novation, Partial Assignment, Partial Tear Up, Book Closure, Brokerage Payout, Confo Dates

The provisional group is the one that shows the enumeration is not merely a label. Pre Live Created and Pre Live Amendment record a version produced while a trade was still in draft, which means the provisional stage is versioned and audited exactly like any other. A draft is not outside the versioning model; it is inside it, carrying its own reasons.

The amendment group is what makes the confirmable decision tractable. Because the reasons already partition changes by what was changed — direction, rate, notional, counterparty — whether a version is confirmable is a lookup on the reason rather than a field-by-field diff of the trade. Trade activity covers that classification.

5.2. The reason constrains the change

A reason is not a comment attached after the fact. The interface should permit only changes consistent with the stated reason: a user who selects an economics amendment should not be able to modify fields unrelated to trade economics.

That inverts the usual order. The reason is chosen first and bounds what may be edited, rather than being supplied afterwards to describe whatever was done.

5.3. When several causes coincide

One activity per version is an aim rather than a guarantee, since a batch may deliver a fixing and a correction together. A priority order decides which reason names the version:

  1. Book moves
  2. Funding roll or reserve
  3. CEM charge or contra revenue
  4. Close outs
  5. Triggered
  6. Exercised or expired
  7. Fixing
  8. Misbooking

Some reasons additionally require escalation, where a head of desk must approve the change rather than the usual approver. The operational authorisation queue covers that side, along with the operational error flag that separates a change made for a business reason from one made because the booking was wrong.

6. The forms an amendment takes

6.1. Normal amendment

When a trade's terms are amended (e.g. Restructure, Novation, Upsize), ORE Studio does not create a new trade record. Instead, it uses temporal versioning:

  • The existing trade row's valid_to is set to the current timestamp.
  • A new row is inserted with the same id, valid_from set to now, and valid_to set to infinity.
  • The new temporal version carries status booked, pending re-confirmation of the amended terms.
  • On confirmation, the status transitions to live.

This preserves the full amendment history of the trade under a single id. 

trade_id = X
─────────────────────────────────────────────────────────────────
 valid_from    valid_to       status   terms
─────────────────────────────────────────────────────────────────
 2026-01-10    2026-03-01     live     notional=10M
 2026-03-01    ∞              new      notional=15M   ◀ upsize
─────────────────────────────────────────────────────────────────

6.2. Cancel and rebook

The successor_trade_id field is used exclusively for cancel and rebook scenarios, where a trade is cancelled and an entirely new trade is created to replace it. This is distinct from a normal amendment:

  • The original trade is moved to cancelled status.
  • A new trade with a fresh id is created (entering booked status).
  • The new trade's successor_trade_id is set to the original trade's id for traceability.

Use cases: Misbooking correction, administrative re-booking.

6.3. Misbooking correction

A misbooking creates a correction trade with successor_trade_id pointing to the erroneous original:

  1. Original erroneous trade: status → cancelled.
  2. Correction trade created: fresh id, successor_trade_id = original id.
  3. Correction trade status begins at booked, and reaches live through verification and, where the trade faces a counterparty, confirmation.

7. Undoing an event

Most confirmable events have a mirror. A cancellation is undone by a reinstatement, a restructure by a reversion, a confirmation by an un-confirm. Two rules govern the family:

  1. Never delete a version. Post the mirror event and let the record show both.
  2. A matched pair is P&L neutral. The mirror event restores the prior state exactly, so the pair moves no value.

The second rule is the test of a correct implementation. If undoing an event changes the P&L, the undo is not a mirror; it is a second event.

8. See also

  • Trade — the structure note that orders this cluster, and where to read this page in it.
  • Trade Lifecycle — the states a trade moves through; an amendment leaves the state unchanged.
  • Trade Activity — the taxonomy of causes, and which move a version.
  • Confirmations — what the external version is confirmed as of.
  • Optimistic Concurrency Versioning — how the internal version is assigned and guarded, and what a writer must send.
  • Knowledge — the hub of all knowledge notes.

Emacs 29.3 (Org mode 9.6.15)