Using the Carry movement types to configure an A2B report

In an A2B report, income and expense activity is reported in the Carry column. This is the component of P&L that is not classed as capital gains.

Carry activity is captured in LUSID when transactions are assigned a transaction type that includes a movement type of either Carry or CarryAsPnl.

Using the Carry movement type

The Carry movement type should be used for dividends, coupons and other interest payments where the income can be considered 'a flow out of the instrument'.

For example, imagine we have a holding in MSFT worth $1000 and we pay a dividend of $50. After the dividend the price of MSFT changes to reflect the dividend, and the value of the holding is now $950.

We could book the $50 dividend transaction with a transaction type that includes a single CashAccrual movement type, for example the built-in Dividend transaction type:

Transaction type component		Value	Effect
Alias	Type	`Dividend`	Defines the name of the transaction type
Movement #1	Side	`Side2`	Uses the built-in side designed for cash holdings
	Direction	`1`	Increases the number of units in the holding
	Movement type	`CashAccrual`	Updates the cash balance on the settlement date

The A2B report would look like this:

Instrument |    A | Flows | Gains | Carry |   B 
===========|======|=======|=======|=======|=====
      MSFT | 1000 |       |   -50 |       | 950
       USD |      |    50 |       |       |  50

There is no connection between the appearance of the $50 and the dividend from MSFT.
Net flows are $50; it appears as though we've added cash to the portfolio.
It looks like we have a loss of $50 on our MSFT holding.

It might be better to create a new transaction type to record this transaction as a 'flow of value' out of the instrument and into cash. Here, the first movement is retained from Dividend; the second movement uses the Carry movement type and the built-in side Side1 to target the instrument and generate two entries in the A2B report, a positive carry and a negative flow.

Note: These flows are of the amount of Side1. The units field is unused by LUSID and so typically records the quantity of the instrument being held.

Transaction type component		Value	Effect
Alias	Type	`DividendWithCarry`	Defines the name of the transaction type
Movement #1	Side	`Side2`	Uses the built-in side designed for cash holdings
	Direction	`1`	Increases the number of units in the holding
	Movement type	`CashAccrual`	Updates the cash balance on the settlement date
Movement #2	Side	`Side1`	Uses the built-in side designed for instrument (non-cash) holdings
	Direction	`1`	Uses the amount as-is (a value of `-1` would negate the amount)
	Movement type	`Carry`	Captures income or expense for an instrument

The A2B report would look like this:

Instrument |    A | Flows | Gains | Carry |   B 
===========|======|=======|=======|=======|=====
      MSFT | 1000 |   -50 |   -50 |    50 | 950
       USD |      |    50 |       |       |  50

The net flows are now zero; the dividend is a flow out of MSFT and into USD.
The total P&L for MSFT is now zero. The change in the unrealised gain (Gains column) is now offset by the dividend (Carry column).
The A2B report maintains balance because the carry amount of +$50 has been offset by a flow of -$50.

Using the CarryAsPnl movement type

The CarryAsPnl movement type should be used for capital expenses where the carry activity is offset not by a flow but by a gain.

For example, imagine we have $1000 and wish to buy MSFT. The broker's commission is $20, so we can only buy equity worth $980.

We record the $20 by attaching a Commission property to the transaction, and then book it with a transaction type that includes the CarryAsPnl movement type:

Transaction type component		Value	Effect
Alias	Type	`BuyWithCommission`	Defines the name of the transaction type
Movement #1	Side	`Side1`	Uses the built-in side designed for instrument holdings
	Direction	`1`	Increases the number of units in the holding
	Movement type	`StockSettlement`	Updates the number of units
Movement #2	Side	`Side2`	Uses the built-in side designed for cash holdings
	Direction	`-1`	Decreases the number of units in the holding
	Movement type	`CashCommitment`	Updates the cash balance on the settlement date
Movement #3	Side	`Commission`	Custom side set up to read the `Commission` property
	Direction	`-1`	Decreases the number of units in the holding
	Movement type	`CarryAsPnl`	Registers a flow out of an instrument

The A2B report would look like this:

Instrument |    A | Flows | Gains | Carry |   B 
===========|======|=======|=======|=======|=====
       USD | 1000 | -1000 |       |       |   0
      MSFT |      |  1000 |     0 |   -20 | 980

Expanding the gain of 0 would show a breakdown of -$20 market gain and +$20 commission.
The commission expense of -$20 has been offset by the commission in the Gains column instead of the Flows column.