Views:

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 typeLeg indexLeg identifierDescriptionEconomic definition
Explicit or implicit?Leg object hierarchy if explicit
CapFloor1Pay or ReceiveCash flows representing the pay or receive leg.ExplicitFloatingLegLegDefinition
CdsIndex1ProtectionLegPayments made by the protection seller in case of default across all CDS instruments in the index.ImplicitN/A
2PremiumLegThe premium payments made by the protection buyer across all CDS instruments in the index.
CreditDefaultSwap1ProtectionLegCash flows occurring in the case of default.ImplicitN/A
2PremiumLegThe premium payments made by the protection buyer.
EquitySwap1EquityLegCash flows relating to the performance of the underlying equity.ImplicitN/A 
2FundingLegThe funding leg of the swap.ExplicitFundingLegLegDefinition
3EquityDividendLegCash flows relating to dividend payments on the underlying equity (optional).ImplicitN/A
FundingLeg1Pay or ReceiveCash flows representing the pay or receive legExplicitLegDefinition
FxForward1DomesticLegCash flows in the domestic currency of the forward.ImplicitN/A
2ForeignLegCash flows in the foreign currency of the forward (not present for non-deliverable forwards).
FxSwap1FarDomesticLegCash flows in the domestic currency for the far forward.ImplicitN/A
2FarForeignLegCash flows in the foreign currency for the far forward (not present for non-deliverable forwards).
3NearDomesticLegCash flows in the domestic currency for the near forward.
4NearForeignLegCash flows in the foreign currency for the near forward (not present for non-deliverable forwards).
InflationSwap1InflationLegCash flows with a rate relating to an underlying inflation index.ExplicitInflationLeg
2FixedLegCash flows with a fixed rate.FixedLegLegDefinition

InterestRateSwap

(also InterestRateSwaption)

1Pay or ReceiveCash flows representing the pay or receive leg.Explicit

Legs 1 and 2 can both be FixedLeg, both be FloatingLeg, or one of each.

2Receive or PayCash flows representing the opposite receive or pay leg.
3AdditionalPaymentsCash flows relating to any additional payments (optional).ImplicitN/A
TotalReturnSwap1AssetLegCash flows relating to the returns generated by an underlying bond.ExplicitAssetLeg
2FundingLegThe funding leg of the swap. FundingLegLegDefinition
 

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:

FxForward1DomesticLegCash flows in the domestic currency of the forward.
2ForeignLegCash 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:

  1. Loaded suitable market data into a LUSID market data store. More information.
  2. 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:

  1. Loaded suitable market data into a LUSID market data store. More information.
  2. Created a recipe nominating a pricing model and rules for retrieving that market data. More information.
  3. 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: