Understanding instrument lifecycle events emitted by LUSID

LUSID can automatically emit lifecycle events for supported term instruments, enabling you to handle those events in a seamless and consistent manner.

Important: To enable instrument events, register a recipe with every portfolio you wish events to impact. More information.

For example, LUSID automatically emits a BondCouponEvent each time a bond coupon is due. No user input is required, providing you have mastered the underlying instrument as either type Bond, ComplexBond or InflationLinkedBond in the LUSID Security Master. In addition:

LUSID provides a BondCouponEvent default transaction template that automatically generates a transaction representing each coupon amount on its ex-date. You can override this default template if you wish, but it is not necessary.
You must implement a BondCoupon transaction type to confer a suitable economic impact on automatically-generated bond coupon transactions. We provide a recommendation, which you can either implement as-is or change if desired.

Note: Instruments of type Equity do not have a lifecycle in the normal sense but you can load a stream of corporate actions and trigger LUSID to emit appropriate events. More information.

With the BondCoupon transaction type in place, for each portfolio with a holding in the bond instrument on the ex-date of each coupon, LUSID automatically:

Generates an output transaction scaled to your holding in that portfolio, and enriched with extra information such as gain/loss or a tax calculation.
Implements the economic impact prescribed by the transaction type, for example adding the bond coupon amount to a particular cash balance.

Recommended reading: Handling bond coupon, principal and maturity events.

The following lifecycle events are available. For more information, start by calling the GetTransactionTemplate API for that event.

LUSID instrument type	Lifecycle events emitted by LUSID	Transaction types requiring implementation (click for recommendations)	Notes (see also Troubleshooting)
Bond, ComplexBond, InflationLinkedBond	`BondCouponEvent`	BondCoupon	For a `Bond` example, see this tutorial. To override a particular coupon or principal amount, manually load an appropriate event. More information coming soon. To handle early redemption and terminate lifecycle events, manually load an `EarlyRedemptionEvent`. To handle a bond default and terminate lifecycle events, manually load a `BondDefaultEvent`. To convert a bond, manually load a `ConversionEvent`. More information coming soon.
	`BondPrincipalEvent`	BondPrincipal
	`BondPrincipalEvent`	BondPrincipal
	`MaturityEvent`	Maturity
MBS (modelled as a `ComplexBond`)	`MbsCouponEvent`	MbsCoupon
	`MbsPrincipalEvent`	MbsPrincipal
	`MbsPrincipalWriteOffEvent`	MbsPrincipalWriteOff
	`MbsInterestShortfallEvent`	MbsInterestShortfall
	`MbsInterestDeferralEvent`	MbsInterestDeferral
	`MaturityEvent`	Maturity
`CapFloor`	`CapletFloorletCashFlowEvent`	`CapletFloorletCashFlow`
`CapFloor`	`MaturityEvent`	Maturity
CdsIndex, CreditDefaultSwap	`CreditPremiumCashFlowEvent`	CreditPremiumCashFlow	Note `ProtectionPayoutCashFlowEvent` is not automatically emitted by LUSID and must instead be triggered by manually loading a different event.
	`ProtectionPayoutCashFlowEvent`	ProtectionPayoutCashFlow
	`MaturityEvent`	Maturity
`ContractForDifference`	`MaturityEvent`	Maturity
EquityOption, ExchangeTradedOption, `InterestRateSwaption`	`OptionExerciseCashEvent`	CashSettledOptionExercise (if cash settled)	Note the following: For an ETO, the underlying must be an `Equity` or a `Future`. Other underlyings do not support instrument events. `OptionExerciseCashEvent` and `OptionExercisePhysicalEvent` are not automatically emitted by LUSID and must instead be triggered by manually loading an event instruction. If you choose to exercise, `ExpiryEvent` is not emitted. More information.
	`OptionExercisePhysicalEvent`	PhysicallySettledOptionExercise (if physically settled) CallOptionPhysicalExercise (if physically settled call option) PutOptionPhysicalExercise (if physically settled put option)
	`ExpiryEvent`	Expiry
`EquitySwap`	`MaturityEvent`	Maturity
`FlexibleDeposit`	`DepositInterestPaymentEvent`	`DepositInterestPayment` `DepositInterestPaymentBalanceAdjustment`
	`UpdateDepositAmountEvent`	`UpdateDepositAmount`
	`DepositCloseEvent`	`DepositCloseInterestPayment` `DepositCloseFinalBalanceRepayment` `DepositClose`
`FlexibleLoan`	`LoanInterestRepaymentEvent`	`LoanInterestRepayment`
`FlexibleLoan`	`LoanPrincipalRepaymentEvent`	`LoanBalanceReduction` `LoanLimitReduction` (if term loan) `TermLoanFacilityLimitDecrease` (if term loan) `RevolvingLoanFacility` (if revolving loan)
FlexibleRepo	`FlexibleRepoCashFlowEvent`	FlexibleRepoCashTransfer	See this tutorial. To partially close a term repo, manually load a `FlexibleRepoPartialClosureEvent`. To close an open repo early, manually load a `FlexibleRepoFullClosureEvent`.
	`FlexibleRepoCollateralEvent`	FlexibleRepoCollateralTransfer
	`FlexibleRepoInterestPaymentEvent`	FlexibleRepoInterestPayment
	`MaturityEvent`	Maturity
`ForwardRateAgreement`	`MaturityEvent`	Maturity
Future	`FutureMarkToMarketEvent`	FutureMarkToMarket	See this tutorial.
Future	`FutureExpiryEvent`	FutureCashSettlement	See this tutorial.
FxForward	`FxForwardSettlementEvent`	FxForwardDomPrincipal and FxForwardFgnPrincipal (if deliverable) `NdfSettlement` (if NDF)	For a deliverable `FxForward` example, see this tutorial. To close position(s) early, manually load an `EarlyCloseOutEvent`.
FxForward	`MaturityEvent`	Maturity
`FxSwap`	`FxForwardSettlementEvent`	`FxForwardPrincipal`
`FxSwap`	`MaturityEvent`	Maturity
`InflationSwap`	`SwapCashFlowEvent`	SwapCashFlow
`InflationSwap`	`MaturityEvent`	Maturity
`InterestRateSwap`	`SwapCashFlowEvent`	SwapCashFlow
	`SwapPrincipalEvent`	SwapPrincipal
	`MaturityEvent`	Maturity
`LoanFacility`	`ContractInitialisationEvent`	`InitialiseContract`
	`AdjustGlobalCommitmentEvent`	`AdjustGlobalCommitment`
	`DrawdownEvent`	`DrawdownFacilityBalance` `IncreaseContractBalance`
	`LoanInterestRepaymentEvent`	`LoanInterestRepayment` (if not lapsed)
`TermDeposit`	`TermDepositInterestEvent`	`TermDepositInterest`
	`TermDepositPrincipalEvent`	`TermDepositPrincipal`
	`MaturityEvent`	Maturity
`TotalReturnSwap`	`MaturityEvent`	Maturity