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 | |
Explicit or implicit? | Leg object hierarchy if explicit | ||||
| 1 |
| Cash flows representing the pay or receive leg. | Explicit | |
| 1 |
| Payments made by the protection seller in case of default across all CDS instruments in the index. | Implicit | N/A |
2 |
| The premium payments made by the protection buyer across all CDS instruments in the index. | |||
| 1 |
| Cash flows occurring in the case of default. | Implicit | N/A |
2 |
| The premium payments made by the protection buyer. | |||
| 1 |
| Cash flows relating to the performance of the underlying equity. | Implicit | N/A |
2 |
| The funding leg of the swap. | Explicit | ||
3 |
| Cash flows relating to dividend payments on the underlying equity (optional). | Implicit | N/A | |
| 1 |
| Cash flows representing the pay or receive leg | Explicit | |
| 1 |
| Cash flows in the domestic currency of the forward. | Implicit | N/A |
2 |
| Cash flows in the foreign currency of the forward (not present for non-deliverable forwards). | |||
| 1 |
| Cash flows in the domestic currency for the far forward. | Implicit | N/A |
2 |
| Cash flows in the foreign currency for the far forward (not present for non-deliverable forwards). | |||
3 |
| Cash flows in the domestic currency for the near forward. | |||
4 |
| Cash flows in the foreign currency for the near forward (not present for non-deliverable forwards). | |||
| 1 |
| Cash flows with a rate relating to an underlying inflation index. | Explicit | |
2 |
| Cash flows with a fixed rate. | |||
(also | 1 |
| Cash flows representing the pay or receive leg. | Explicit | Legs 1 and 2 can |
2 |
| Cash flows representing the opposite receive or pay leg. | |||
3 |
| Cash flows relating to any additional payments (optional). | Implicit | N/A | |
| 1 |
| Cash flows relating to the returns generated by an underlying bond. | Explicit | |
2 |
| The funding leg of the swap. |
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:
| 1 |
| Cash flows in the domestic currency of the forward. |
2 |
| 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 table with 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 toTrue
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 acollectionType
ofArray
.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
andAverage
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: