Understanding how LUSID uses transaction types to generate holdings

LUSID is a transaction-based system. It does not maintain a static record of your holdings (positions) in a transaction portfolio but rather generates them on demand from the stored history of transactions, replayed in date order.

Every transaction in a portfolio must resolve to:

• An underlying instrument mastered in LUSID.

• A known transaction type defining the precise economic impact; that is, the effect on your holding in the underlying instrument, and also potentially on holdings in other instruments in the portfolio too (for example, currency holdings).

LUSID has a number of built-in transaction types (such as FundsIn, Buy and Sell) that enable you to get started modeling basic economic activity. These are useful for understanding how transaction types work, but we recommend creating your own universe of custom transaction types for a production system.

Understanding the role of transaction types

Consider the following CSV file containing three input transactions ready for upsert to a portfolio, each with a particular txn_type:

1. The FundsIn transaction deposits £500 in the portfolio. We would expect our cash holding in GBP to increase by £500, but no other holdings to be affected.

2. The Buy transaction purchases 10 BP shares at £10 a share. We would expect our equity holding in BP to increase by 10 units and our cash holding in GBP to decrease by £100.

3. The Sell transaction sells 5 BP shares at £11 a share. We would expect our equity holding in BP to decrease by 5 units and our cash holding in GBP to increase by £55.

When all trades have settled, we would expect LUSID to generate a holdings report for this portfolio with 5 BP shares and £455.

Examining the built-in LUSID transaction types

You can retrieve the definition of the built-in Buy transaction type from the default source and default scope by calling the GetTransactionType API:

{
  "aliases": [
    {
      "type": "Buy",
      "description": "Purchase",
      "transactionClass": "Basic",
      "transactionRoles": "LongLonger",
      "isDefault": false
    },
  ],
  "movements": [
    {
      "movementTypes": "StockMovement",
      "side": "Side1",
      "direction": 1,
      "properties": {},
      "mappings": [],
      "movementOptions": []
    },
    {
      "movementTypes": "CashCommitment",
      "side": "Side2",
      "direction": -1,
      "properties": {},
      "mappings": [],
      "movementOptions": []
    }
  ],
  "properties": {},
  ...
}

The built-in Buy transaction type:

• Is grouped in the default source (data provider) and default scope (logical repository) with all the other built-in transaction types provided with LUSID. More about scopes and sources.

• Has a single alias, which defines the name of the transaction type and other characteristics that allow you to group similar types together for reporting purposes.

• Has two movements, each of which has:

  • A movement type that controls how and when a holding is updated. Allowed values are these built-in movement types. You cannot customise this set.

  • A direction that controls whether the change is an increase or decrease. Allowed values are 1 and -1 respectively.

  • A side that determines which economic attributes of the transaction impact the holding. Allowed values are either the built-in sides or you can create your own custom side.

The following table flattens and explains the definition of the built-in Buy transaction type:

In summary, we can see that the built-in Buy transaction type:

• Impacts one instrument (non-cash) holding and one cash holding.

• Increases the instrument holding.

• Decreases the cash holding.

The built-in Sell transaction type is virtually identical to Buy. The only difference is that the movement directions are reversed:

• The  StockMovement has a direction of -1 to decrease the instrument holding by the number of units.

• The CashCommitment has a direction of 1 to increase the cash holding by the total consideration.

By contrast, the built-in FundsIn transaction type has a single movement, with a type of CashAccrual, a direction of 1, and uses the built-in Side1. This transaction type:

• Impacts a single cash holding.

• On the trade date, creates a temporary separate cash holding (of holding type A) to reflect expected accrual of income.

• On the settlement date, increases the main cash holding (holding type B) by the number of units and removes the temporary holding.

Interpreting the impact of transaction types on holdings

If we load our three transactions into a portfolio and call the GetHoldings API for end-of-day on the trade date (6 June 2022), we can see from the picture below that LUSID generates:

• One holding (with a Holding Type of Position) for the BP equity instrument. Note the number of Settled Units is 0.

• Three holdings for the GBP cash instrument. The first (with a Holding Type of Cash Accrual) records the (unsettled) FundsIn transaction for £500. The last two (both with a Holding Type of Cash Commitment) record the commitment to pay (from the Buy transaction) or receive (from the Sell transaction) GBP on the settlement date:

If we call the GetHoldings API again on or after the settlement date (8 June 2022), we can see from the picture below that LUSID normalises the GBP instrument to a single cash holding (with a Holding Type of Cash Balance), and that all units are now Settled Units:

There are two main reasons to configure transaction types:

• You want to configure aliases in order to group similar or related transaction types together.

• You want to configure movements in order to change the economic impact of transactions on holdings.

For more information, start with the tutorials for the following use cases: