How does LUSID handle instrument legs?

Views:

Related resources:

Many types of instrument supported by LUSID have one or more cash flow legs. You may find it useful to view the cash flows from an individual leg, or to see the contribution of a particular leg to the overall valuation of your holding in an instrument. You can also add properties to store extra information about legs; these properties are independent of any added to the instrument as a whole.

For some types of instrument, legs are explicitly defined when you master an instrument of that type in LUSID. For others, there are no explicit leg objects in economic definitions, but LUSID implicitly creates legs for the purpose of categorising cash flows.

Whether explicitly defined or implicitly created, all instruments with cash flow legs have a leg identifier that describes the purpose of the leg, and a leg index that defines the order. The order is significant if you want to view cash flows for, individually value, or add properties to a particular leg.

Instrument type	Leg index	Leg identifier	Description	Economic definition
Instrument type	Leg index	Leg identifier	Description	Explicit or implicit?	Leg object hierarchy if explicit
`CapFloor`	1	`Pay` or `Receive`	Cash flows representing the pay or receive leg.	Explicit	FloatingLeg→LegDefinition
`CdsIndex`	1	`ProtectionLeg`	Payments made by the protection seller in case of default across all CDS instruments in the index.	Implicit	N/A
`CdsIndex`	2	`PremiumLeg`	The premium payments made by the protection buyer across all CDS instruments in the index.	Implicit	N/A
`CreditDefaultSwap`	1	`ProtectionLeg`	Cash flows occurring in the case of default.	Implicit	N/A
`CreditDefaultSwap`	2	`PremiumLeg`	The premium payments made by the protection buyer.	Implicit	N/A
`EquitySwap`	1	`EquityLeg`	Cash flows relating to the performance of the underlying equity.	Implicit	N/A
	2	`FundingLeg`	The funding leg of the swap.	Explicit	FundingLeg→LegDefinition
	3	`EquityDividendLeg`	Cash flows relating to dividend payments on the underlying equity (optional).	Implicit	N/A
`FundingLeg`	1	`Pay` or `Receive`	Cash flows representing the pay or receive leg	Explicit	LegDefinition
`FxForward`	1	`DomesticLeg`	Cash flows in the domestic currency of the forward.	Implicit	N/A
`FxForward`	2	`ForeignLeg`	Cash flows in the foreign currency of the forward (not present for non-deliverable forwards).	Implicit	N/A
`FxSwap`	1	`NearDomesticLeg`	Cash flows in the domestic currency for the near forward.	Implicit	N/A
	2	`NearForeignLeg`	Cash flows in the foreign currency for the near forward (not present for non-deliverable forwards).
	3	`FarDomesticLeg`	Cash flows in the domestic currency for the far forward.
	4	`FarForeignLeg`	Cash flows in the foreign currency for the far forward (not present for non-deliverable forwards).
`InflationSwap`	1	`InflationLeg`	Cash flows with a rate relating to an underlying inflation index.	Explicit	InflationLeg
`InflationSwap`	2	`FixedLeg`	Cash flows with a fixed rate.	Explicit	FixedLeg→LegDefinition
`InterestRateSwap` (also `InterestRateSwaption`)	1	`Pay` or `Receive`	Cash flows representing the pay or receive leg.	Explicit	Legs 1 and 2 can both be FixedLeg, both be FloatingLeg, or one of each.
	2	`Receive` or `Pay`	Cash flows representing the opposite receive or pay leg.	Explicit
	3	`AdditionalPayments`	Cash flows relating to any additional payments (optional).	Implicit	N/A
`TotalReturnSwap`	1	`AssetLeg`	Cash flows relating to the returns generated by an underlying bond.	Explicit	AssetLeg
`TotalReturnSwap`	2	`FundingLeg`	The funding leg of the swap.	Explicit	FundingLeg→LegDefinition

Example: A 6m EUR/USD FxForward

Consider the example of a FxForward instrument mastered in LUSID with the following economic definition:

{
  "startDate": "2023-01-20T00:00:00.0000000+00:00",
  "maturityDate": "2023-07-22T00:00:00.0000000+00:00",
  "domAmount": 1000000,
  "domCcy": "EUR",
  "fgnAmount": -1215520.25,
  "fgnCcy": "USD",
  "isNdf": false,
  "instrumentType": "FxForward"
}

As per the table above, LUSID implicitly creates two cash flow legs for a non-deliverable FxForward:

`FxForward`	1	`DomesticLeg`	Cash flows in the domestic currency of the forward.
`FxForward`	2	`ForeignLeg`	Cash flows in the foreign currency of the forward (not present for non-deliverable forwards).

Viewing leg-level cash flows

You can view leg-level cash flows for the FxForward providing you have:

Loaded suitable market data into a LUSID market data store. More information.
Created a recipe nominating a pricing model and rules for retrieving that market data. More information.

To view cash flows, call the GetInstrumentPaymentDiary API, or sign in to the LUSID web app, navigate to Data Management > Instruments, locate the FxForward and open the Payments screen. Here, the response is transformed to a Pandas dataframe, and some columns renamed or removed, for clarity:

Viewing leg-level valuation results

You can view leg-level valuation results for a holding in the FxForward providing you have:

Loaded suitable market data into a LUSID market data store. More information.
Created a recipe nominating a pricing model and rules for retrieving that market data. More information.
Set the produceSeparateResultForLinearOtcLegs option to True in that recipe. More information.

To perform a valuation, call the GetValuation API, or sign in to the LUSID web app and navigate to Dashboard > Valuations. You can specify the Valuation/LegIdentifier and Valuation/LegIndex metrics in order to confirm which leg is which:

Adding leg-level properties

You can add properties to legs to extend the data model. Note the following:

The underlying property type must be a multi-value string property type in the Leg domain with a collectionType of Array.
The order in which property values are specified in the array must match the leg index order.

The first step is to create a suitable property type using the CreatePropertyDefinition API, for example with a 3-stage property key of Leg/ExampleScope/Region:

curl -X POST "https://<your-domain>.lusid.com/api/api/propertydefinitions"
 -H "Authorization: Bearer <your-API-access-token>"
 -H "Content-Type: application/json-patch+json"
 -d '{
   "domain": "Leg",
   "scope": "ExampleScope",
   "code": "Region",
   "displayName": "Leg region property type for FxForwards",
   "dataTypeId": {"scope": "system", "code": "string"},
   "lifeTime": "Perpetual",
   "constraintStyle": "Collection",
   "collectionType": "Array",
}'

Then, you can add property values of this type to the FxForward using the BatchUpsertInstrumentProperties API:

curl -X POST "https://<your-domain>.lusid.com/api/api/instruments/$batchupsertproperties?scope=default&successMode=Partial'"
 -H "Authorization: Bearer <your-API-access-token>"
 -H "Content-Type: application/json-patch+json"
 -d '{
  "1": {
    "identifierType": "LusidInstrumentId",
    "identifier": "LUID_00003DPG",
    "properties": [
      {
        "key": "Leg/ExampleScope/Region",
        "value": {
          "labelValueSet": {
            "values": [
              "Europe",
              "United States"
            ]
          }
        }
      }
    ]
  }
}'

LUSID assigns the first value in the array (Europe) to the first leg (DomesticLeg), and similarly the second value to the second leg. If the property values in the array were reversed, the wrong regions would be assigned to legs. Note if you add more property values than there are legs, LUSID ignores the extra values.

If you perform a valuation using a recipe with produceSeparateResultForLinearOtcLegs option set to True and choose to include properties in the results, then leg-level property values are split but instrument-level property values are not. For example, here the FxForward has both a leg-level Leg/ExampleScope/Region property with split values and an instrument-level Instrument/ExampleScope/Region property with the same values unsplit:

Note: You can group valuation results by property values, or perform operations such as Sum, Proportion and Average on numeric property values, in the same way as metrics.

With produceSeparateResultForLinearOtcLegs set to False, neither leg-level nor instrument-level property values are split. Note also the Valuation/LegIdentifier and Valuation/LegIndex metrics do not return values: