Understanding instrument lifecycle events emitted by LUSID

LUSID can 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 event	Automatically emitted?	Generates transaction(s)?	Transaction type recommendation(s) for implementation	Notes (see also troubleshooting)
Bond, ComplexBond, InflationLinkedBond	`BondCouponEvent`	✅ Can also be manually loaded	✅	BondCoupon	Tutorial for a `Bond`
	`BondPrincipalEvent`	✅ Can also be manually loaded	✅	BondPrincipal
	`ConversionEvent`	❌ Must be manually loaded	✅	ConvRemoveExisting ConvAdjustCost ConvReceiveCash ConvReceiveUnits ConvCashInLieu
	`EarlyRedemptionEvent`	❌ Must be manually loaded	✅	BondEarlyRedemption BondEarlyRedemptionAccrued
	`BondDefaultEvent`	❌ Must be manually loaded	❌	N/A
	`MaturityEvent`	✅	✅	Maturity
MBS (modelled as a `ComplexBond`)	`MbsCouponEvent`	✅	✅	MbsCoupon	To convert, default or redeem an MBS early, contact Technical Support.
	`MbsPrincipalEvent`	✅	✅	MbsPrincipal
	`MbsPrincipalWriteOffEvent`	✅	✅	MbsPrincipalWriteOff
	`MbsInterestShortfallEvent`	✅	✅	MbsInterestShortfall
	`MbsInterestDeferralEvent`	✅	✅	MbsInterestDeferral
	`MaturityEvent`	✅	✅	Maturity
`CapFloor`	`CapletFloorletCashFlowEvent`	✅	✅	`CapletFloorletCashFlow`
`CapFloor`	`MaturityEvent`	✅	✅	Maturity
CdsIndex, CreditDefaultSwap	`CreditPremiumCashFlowEvent`	✅	✅	CreditPremiumCashFlow	Tutorial for a `CdsIndex`
	`ProtectionPayoutCashFlowEvent`	❌ Triggered by loading CdxCreditEvent or CdsCreditEvent	✅	ProtectionPayoutCashFlow
	`MaturityEvent`	✅	✅	Maturity
`ContractForDifference`	`MaturityEvent`	✅	✅	Maturity
EquityOption, ExchangeTradedOption, `InterestRateSwaption`	`OptionExerciseCashEvent` (if cash-settled)	❌ Triggered by event instruction	✅	CashSettledOptionExercise	Tutorial for an ETO Note for an ETO the underlying must be an `Equity` or `Future`. Other underlyings do not support instrument events.
	`OptionExercisePhysicalEvent` (if physically-settled)	❌ Triggered by event instruction	✅	PhysicallySettledOptionExercise CallOptionPhysicalExercise (if call option) PutOptionPhysicalExercise (if put option)
	`ExpiryEvent`	✅ Only if unexercised	✅ Only if unexercised	Expiry
`EquitySwap`	`MaturityEvent`	✅	✅	Maturity
`FlexibleDeposit`	`DepositInterestPaymentEvent`	✅	✅	`DepositInterestPayment` `DepositInterestPaymentBalanceAdjustment`
	`UpdateDepositAmountEvent`	❌ Must be manually loaded	✅	`UpdateDepositAmount`
	`DepositRollEvent`	❌ Must be manually loaded	✅	`DecreaseBalance` `IncreaseBalance` `WithdrawInterest` `ReinvestInterest`
	`DepositCloseEvent`	❌ Must be manually loaded	✅	`DepositCloseInterestPayment` `DepositCloseFinalBalanceRepayment` `DepositClose`
`FlexibleLoan`	`LoanInterestRepaymentEvent`	✅ Can also be manually loaded	✅	`LoanInterestRepayment`
`FlexibleLoan`	`LoanPrincipalRepaymentEvent`	✅ Can also be manually loaded	✅	`LoanBalanceReduction` `LoanLimitReduction` `TermLoanFacilityLimitDecrease` `RevolvingLoanFacility`
FlexibleRepo	`FlexibleRepoCashFlowEvent`	✅	✅	FlexibleRepoCashTransfer	Tutorial
	`FlexibleRepoCollateralEvent`	✅	✅	FlexibleRepoCollateralTransfer
	`FlexibleRepoInterestPaymentEvent`	✅	✅	FlexibleRepoInterestPayment
	`FlexibleRepoInterestPaymentEvent`	✅	✅	FlexibleRepoInterestPayment
	`FlexibleRepoPartialClosureEvent`	❌ Must be manually loaded	❌	N/A
	`FlexibleRepoFullClosureEvent`	❌ Must be manually loaded	❌	N/A
	`MaturityEvent`	✅	✅	Maturity
`ForwardRateAgreement`	`MaturityEvent`	✅	✅	Maturity
Future	`FutureMarkToMarketEvent`	✅	✅	FutureMarkToMarket	Tutorial
Future	`FutureExpiryEvent`	✅	✅	FutureCashSettlement	Tutorial
FxForward	`FxForwardSettlementEvent`	✅	✅	FxForwardDomPrincipal and FxForwardFgnPrincipal (if deliverable) `NdfSettlement` (if NDF)	Tutorial for a deliverable `FxForward`
	`EarlyCloseOutEvent`	❌ Must be manually loaded	✅	`EarlyCloseOutSettlement`
	`MaturityEvent`	✅	✅	Maturity
`FxSwap`	`FxForwardSettlementEvent`	✅	✅	`FxForwardPrincipal`
`FxSwap`	`MaturityEvent`	✅	✅	Maturity
`InflationSwap`	`SwapCashFlowEvent`	✅	✅	SwapCashFlow
`InflationSwap`	`MaturityEvent`	✅	✅	Maturity
`InterestRateSwap`	`SwapCashFlowEvent`	✅	✅	SwapCashFlow
	`SwapPrincipalEvent`	✅	✅	SwapPrincipal
	`MaturityEvent`	✅	✅	Maturity
`LoanFacility`	`ContractInitialisationEvent`	❌ Must be manually loaded	✅	`InitialiseContract`
	`AdjustGlobalCommitmentEvent`	❌ Must be manually loaded	✅	`AdjustGlobalCommitment`
	`DrawdownEvent`	❌ Must be manually loaded	✅	`DrawdownFacilityBalance` `IncreaseContractBalance`
	`LoanInterestRepaymentEvent`	✅ Can also be manually loaded	✅	`LoanInterestRepayment`
	`LoanFacilityContractRolloverEvent`	❌ Must be manually loaded	❌	N/A
	`LoanPrincipalRepaymentEvent`	✅ Can also be manually loaded	✅	`LoanBalanceReduction` `LoanLimitReduction` `TermLoanFacilityLimitDecrease` `RevolvingLoanFacility`
`TermDeposit`	`TermDepositInterestEvent`	✅	✅	`TermDepositInterest`
	`TermDepositPrincipalEvent`	✅	✅	`TermDepositPrincipal`
	`MaturityEvent`	✅	✅	Maturity
`TotalReturnSwap`	`MaturityEvent`	✅	✅	Maturity