Eclipse Software, Inc. Transaction Operations


Key Links

It is natural when talking about application systems of the type we are discussing to focus on the core transactions: buys, sells, repos, loans, etc. Most of the references that publish models for this domain follow just such an approach. There is rarely any discussion of transaction operations such as cancellations and corrections, fails, repricings, or rate changes.

This leads to two problems from a systems point of view. First, these other operations are crucial to subsequent processing such as the computation of trading P&L or bond interest income. Second, these other operations do not extend easily from a model that does not include them from the start. This renders many of the published models less useful than they might otherwise be. Extensive (and painful) experience with both problems led to the Framework we are discussing.

In the Framework the focus is on transaction operations, such as entering a Buy or repricing a repo, rather than transactions per se. In Processing Context we discuss the two major components of the transaction processing framework, but the easiest way to understand the approach is to work through the Examples.

Processing Context

Transaction operation information is stored in two Data Structure entities, Register and Association. Each has a related entity in the Knowledge Base: Register Type and Association Type. It is the interaction of the Knowledge Base and Data Structure entities that make possible the present Framework.

In brief, the Register is concerned with distributions and the Association with open and closed items.

As we are most concerned with the how transaction operations are recorded in the database, we won't look at the control components of the Knowledge Base in detail. We will summarize them here.

Register Type

The Knowledge Base for the Register controls the following information:

Association Type

Though the Association entity has many fewer fields than the Register, the processing of them is considerably more involved. These are the major categories of fields of the Association Type.

Input Processing

Input processing parameters associated with the activities are primarily filters on:

Output Processing

Output processing can be quite involved. Components include:

Considered as a process (e.g., entering a transaction, correcting one, doing a pair-off or other settlement), there are two broad categories of activity represented by the Association Type:
FunctionsThese are activities that apply to a single transaction (Register entry). They include cancellations, corrections, and loan-type activities such as repo rate changes and repricings.
KeyoffsThese are activities that include several Register entries or are performed in bulk. Pair-offs by definition require more than one input record. The most common bulk function is automatic generation of settlement entries.

Regardless of Association Type, the results are recorded in the same Register and Association entities we've been describing (see Data Structures).


The easiest way to understand transaction operations is by first going through a series of examples. It should become apparent that the myriad operations are really just variations on a few core concepts.

It may be helpful to refer to the Knowledge Base for the explanations there of the various codes used here.

Framework Example

Our first example is the one presented in the Framework Example. The transaction operations, processing, and representation in the Framework are discussed in some detail in Data Structures. We won't repeat that information here, but present an abbreviated version for discussing the key points of transaction processing. In this presentation we focus on distributions and open/closed amounts, so we are omitting:

This is the Framework example:
Register Entries
Key Type Security M Money Distribution
121 BUY TBill 985 GBUP C7334
122 REV TBill 985 C7334 GBUP
123 BUY TBill 995 GBUP C7334
391 REC TBill 995 C7334 GCSH
Key Type KO M
72 121 ADD 0
103 121 CORR -985
103 122 CORR 985
103 123 CORR 0
186 123 SETL -995
186 391 SETL 995

After this processing there are no open items, which is determined by applying the Association keyoff amounts to the Register counterparty distributions. Our trial balance is created by adding up the distributions from the Register entries. It has the following values:

Trial Balance
Account Debit Credit
G BUP 995
G CSH 995

Some of the important aspects of the Framework illustrated by this example include:

Open and Closed Status

The open/closed status of a Register entry is not a flag on the transaction. It is derived from the association of the Register entry with another, offsetting Register entry. This applies to almost all Register entries, not just normal transactions (we will discuss self-closing entries, such as certain journal entries, later). See Settlement as Trade status.

The initial operation, the entry of the Buy, resulted in writing one Register entry (R12-1) and one Association entry (A72-12-1). The Register entry is open at that time because the keyoff amount on the Association entry is 0.

The correction resulted in two new Register entries and in a new Association having three entries. The Association entry associated with the original Buy record (R12-1) has a keyoff amount of -985. The counterparty side of the Register distribution is a credit (a negative value, in trial balance format). Subtracting the keyoff amount from the distribution amount leaves zero. The Register entry is thus closed.

Register entry 12-2 is also closed by its Association record's keyoff amount, 985. It's a positive number because the counterparty side of the distribution is a debit.

Register entry 12-3, the new value of the Buy, is open because doing the subtraction results in an open amount of -995.

When created, the Receive (R39-1) was open, just as was the original Buy (R12-1), because there was no keyoff amount. The SETL Association (A186) provides the keyoff amount of 995. That Association also closes out the open Buy (R12-3).

Partial Settlement

If only a portion of the securities required for settlement are available, we may elect to accept partial settlement. The trade remains open until the settlement is completed. In this example we assume 800 of the securities are available and they settle for $788.

Register Entries
Key Type Security M Money Distribution
11121 BUY TBill 985 GBUP C7334
11391 REC TBill 788 C7334 GCSH
11531 REC TBill 197 C7334 GCSH
Key Type KO M
1172 11121 ADD 0
1186 11121 SETL -788
1186 11391 SETL 788
1193 11121 SETL -197
1193 11531 SETL 197

After the initial settlement (A1186), the REC is closed and the BUY has 197 open (plus the 200 quantity, of course). Our trial balance has the following values:

Trial Balance
Account Debit Credit
G BUP 985
C 7334 197
G CSH 788

The second REC introduces a second settlement Association. The BUY is closed because the total amount keyed off is -985.

At this point there are no open items. Our trial balance has the following values:

Trial Balance
Account Debit Credit
G BUP 985
G CSH 985

Settlement with Money Difference

Sometimes a trade goes to settlement and there's agreement on quantity but not the money. Rather than fail the trade you may elect to go ahead with settlement and address the money difference later.

We will look at our Buy where we think the money is 985 but the counterparty thinks it's 995. Settlement takes place with our wiring out the 995 (and receiving the full quantity).

Register Entries
Key Type Security M Money Distribution
12121 BUY TBill 985 GBUP C7334
12391 REC TBill 995 C7334 GCSH
12531 JNL-MDIF TBill G C7334
Key Type KO M
1272 12121 ADD 0
1286 12121 SETL -985
1286 12391 SETL 995
1286 12531 SETL -10

At this point there is one open item: R1253-1, for 10. Our trial balance has the following values:

Trial Balance
Account Debit Credit
G BUP 985
C 7334 10
G CSH 995

One important thing to note is that the generated money difference entry (R1253-1) has an open amount, 10, but no distribution. The firm believes we should get $10 back from the counterparty. If you add the distributions of the earlier items (R1212 and R1239) the books and records show a $10 counterparty receivable. Since it's already on the books you can't assign a distribution to the money difference.

Cleaning up the open money difference depends on the outcome of discussions with the counterparty: either you receive the $10 or you write it off.

Counterparty Wires the $10

In this case we have a WIRE-IN Register entry and an Association to close out the open items. The following table has only the additional entries.

Register Entries
Key Type Security M Money Distribution
12651 WIRE-IN TBill 10 GCSH C7334
Key Type KO M
1290 12531 SETL 10
1290 12651 SETL -10

There is a new Register entry for the wire (R1265) and an Association (A1290) for keying it off against the money difference (R1253). Note that the money difference is now closed: take the original distribution amount (0) and subtract all the keyoff amounts (-10 and 10). This gives the open amount, which is zero.

Our trial balance has the following values:

Trial Balance
Account Debit Credit
G BUP 985
G CSH 985

The $10 is Written Off

In this case we don't receive the cash. It's as if the original Buy were for 995, not 985.

Register Entries
Key Type Security M Money Distribution
12711 JNL-OTHR TBill 10 GBUP C7334
Key Type KO M
1294 12531 SETL 10
1294 12711 SETL -10

All the open items have now been closed.

Our trial balance has the following values:

Trial Balance
Account Debit Credit
G BUP 995
G CSH 995

As you would expect, the settlement of the money difference results in the original trade appearing to be for either 985 or 995, depending on the case above. One difference from handling it as a partial settlement is that in that case BUP always has 995. As BUP is crucial for P&L processing (Inventory and Trading P&L), how the $10 difference is resolved has implications beyond simple settlement.

Backing out an Association

There are many situations where you want to reverse an Association. For example, a settlement was set up incorrectly, a mistake was made on a pair-off, or a wire was attributed to the wrong counterparty.

We start with the original Framework Example and decide to back out the Association that settled the receive and the buy (A186).

Register Entries
Key Type Security M Money Distribution
Key Type KO M
1334 123 BKO 995
1334 391 BKO -995

No new Register entries are created, and thus there is no change to the trial balance. The Buy (R12-3) and receive (R39-1) are open. This can be seen by adding up all the keyoff amounts for each item.

Note that this operation was focused on the existing Association, not re-opening one of the Register entries. Re-opening R12-3, for instance, could lead to reversing the correction (A103) as well.


Cancellations require a degree of precision as to what the business intent is. It really is a matter of cases.

Canceling an Open Item

This is the simplest case. A1403 is the original entry of the Buy, which generates R1412-1. A1472 is the cancellation, which generates the reversal, R1412-2.

Register Entries
Key Type Security M Money Distribution
14121 BUY TBill 985 GBUP C7334
14122 REV TBill 985 C7334 GBUP
Key Type KO M
1403 14121 ADD 0
1472 14121 CXL -985
1472 14122 CXL 985

At this point there are no open items and we've reversed all distribution entries, so the trial balance is all zeroes.

The cancellation is of course the first two rows of the correction Association, A103, from the Framework Example. This is all controlled by the entries in the Knowledge Base's Association Type.

Canceling a Closed Item

Though the mechanics aren't difficult, it's important to set up the appropriate kinds of entries in the Knowledge Base. They can all be handled through a combination of Backing out an Association and Canceling an Open Item. There are a number of cases.

Operation in Error

What if in the Framework Example the Buy was settled by mistake? What you want to do is back out the Association (A186) and cancel the receive (R39-1). You could of course have the user do these two operations in sequence, or you could build an entry in the Association Type table to perform both actions.

Entry in Error

Or, you realize that the Buy (R12-3) is in error and needs be canceled. It is similar to the preceding situation, except that you want to cancel all opened Register entries.


In this situation we have a number of transactions (buys, sells, the opens and closes of repos and reverses) in one security with a particular counterparty. We want to net them so that we are left with just a single item to settle.

The first three Register entries are the open transactions we want to net. A1513 is the pair-off, and R1548 is the generated pair-off difference.

Register Entries
Key Type Security M Money Distribution
15121 BUY TBill 900 GBUP C7334
15231 SELL TBill 800 C7334 GSEP
15441 BUY TBill 400 GBUP C7334
15481 JNL-PODF TBill 0 G C7334
Key Type KO M
1513 15121 P/O -900
1513 15231 P/O 800
1513 15441 P/O -400
1513 15481 P/O 500

This is exactly the same situation as the money difference. It was included here to highlight the fact that the important issue is the offsetting counterparty distributions, not whether the other side of the distribution is cash or inventory.

At this point only the pair-off difference (R1548-1) is open. It is important to note that it is exactly like any other open item:

The trial balance looks like:

Trial Balance
Account Debit Credit
G BUP 1300
G SEP 800
C 7334 500

Because the pair-off difference has no distribution, this trial balance is exactly the same as that which existed before the pair-off was done.

It is important that separate long inventory (BUP) and short inventory (SEP) accounts be used, rather than a single account. The reason is the calculation of realized P&L, which we will discuss in Inventory and Trading P&L.

Bond Maturity

In this situation one or more traders have positions in a bond that is maturing. We'll take trader 9012 long 100 bonds and 9168 short 75. Note that this is position-based, so there are no outstanding open transactions to close out.

Register Entries
Key Type Security M Money Distribution
16721 JNL-RELO TBill 100 GCSH GBUP
Key Type KO M

We've taken the approach that the Fed will be good about redeeming the TBill. These two journals would be set up in the Register Type table as being self-closing.

Another approach is to set up the distribution with the G-CSH replaced by C-FED, and then going through the pair-off type of settlement we saw above. Presence of a counterparty in the distribution pretty much defines a transaction not to be self-closing.

These entries would normally be automatically generated at start of day on maturity date.

Repurchase Agreements

There isn't much new for repurchase agreements, other than to recognize that there are separate Register entries (and Types) for the open and close. The example below shows the situation after the opening side settles.

Register Entries
Key Type Security M Money Distribution
17621 REVE-OPEN TBill 900 GRVP C7334
17622 REVE-CLOS TBill 900 C7334 GRVP
17921 REC TBill 900 GCSH C7334
Key Type KO M
1729 17621 SETL -900
1729 17921 SETL 900

It is important to treat the open and the close separately. They certainly settle completely separately. The closing side may be amended (e.g., a rate change or close-out date change) independently of the open. The Knowledge Base is set up to enforce the necessary restrictions, e.g., that you can't change the counterparty on just one side.

In the above example the REVE-CLOS is still open. The trial balance depends on whether we are looking at trade date or settlement date (see Date Bases), which we've been able to side-step so far.


Few things distinguish systems more than how they treat fails (we are being loose with our terminology here, referring to both true broker/dealer fails and customer receivable/payables). This is how the fail of a Buy would appear in the Framework:

Register Entries
Key Type Security M Money Distribution
18121 BUY TBill 900 GBUP
Key Type KO M

Fails really are this simple.

You may well ask how is this any different from a Buy that has not reached settlement date. The answer: there is none. What makes the Buy a fail is the passage of time (reaching settlement date) and the absence of any type of settlement (receive, pair-off, etc.). A fail is not an event, but a non-event. Specifically, there is nothing intrinsic to the Buy per se affected by its failing.

It is extremely common for a fail to be considered a trade status. This is a vestige of system design decisions, not a reflection of the business reality. Some of the problems with the status flag approach are:

See Settlement as Trade Status.

Another point to note is that any Register item with an open amount can fail, not just "trades". Money and pair-off differences can fail. Coupon and dividend payments can fail. Collateral substitutions can fail. What makes a fail is an item past settlement date that has an open amount (which is a function of offsetting Register entries linked through Associations, not a function of the item itself).

Settlement as Trade Status

In discussions of trade settlement it is very common to see it presented as an update to the trade record. Such discussions, of course, are usually at a more general level and rarely have the focus we have here, which is explicitly on an IT implementation. In this section we clarify the business and technical reasons why you probably want to avoid the trade status approach if possible.

We stress at the beginning that this is not a criticism of those references that use the trade status approach — in fact, we highly recommend a number of them on Links — but a reflection of the fact that the purposes and audiences are different. Those references need a generally understandable way to discuss the topic, of course. The approach we are presenting is more abstract and is almost certainly not the one best suited to a general audience.

We have discussed some of the problem with the trade status attribute in earlier sections. We recap and extend them here.

Business Considerations

Following is a summary of limitations with the trade status attribute approach. First, and most importantly, is a list of business reasons.

Technical Considerations

In addition to the business reasons mentioned above, there a number of purely technical limitations with the trade status approach.

Final Thoughts

We have discussed most of the salient features of the transaction operations component of the Framework in the comments on the examples, particularly the first one, the Framework Example. In summary we can make the following points:

Another point is that all of the codes uses above (Register Types, Association Types, accounts) are "soft" in the sense that they are entries set up in the Knowledge Base tables. They could be called anything (you could call the "JNL-MDIF" just "MDIF", for instance). The examples give some idea of how the Knowledge Base can be tailored to the business needs at hand.

An interesting case is the large number of pair-off Association Types (early, late, etc.) in the Knowledge Base. Many of them have identical parameters, but simply different names. This particular user firm organized their pair-off activities along these lines, so that's what was set up.

This particular firm also wanted many hard-wired journal entry types (all the Register Types starting "JNL-"). They could have had one journal type and allowed the user to enter the distribution to achieve the same effect. Again, a user choice.

Copyright 2005-2021, Eclipse Software, Inc (ESI).  E-mail: