This tutorial introduces the basic claim constructors and shows how to use them to describe a payoff in terms of the future cashflows between the claim’s owner and their counterparty. At the end of this section, you should be able to model payoffs such as fixed rate bonds and FX forwards.
You can use the
PayoffBuilder module to follow along and test the claims described
When you run the
runCreateAndLifecycle script, it will
- create a Daml Finance Generic instrument wrapping your input claim
- lifecycle the instrument at the specified dates
- print out pending cashflows
zero constructor is used to indicate the absence of cashflows. We can setup this very simple
initial payoff as follows
c = zero acquisitionDate = date 2023 Aug 01
The acquisition date is used to track the date at which two parties enter the contract and it is a required input to each claim.
one constructor is used to deliver to the owner of the contract one unit of a specified
instrument. For instance, the claim
c = one "USD" acquisitionDate = date 2023 Aug 01
gives the owner an “immediate” right to receive one unit of the
We can verify that by lifecycling the claim: we define a set of lifecycle dates
lifecycleDates = [ date 2023 Aug 01 , date 2023 Aug 03 ]
and run the script to obtain
"--- EFFECT on 2023-08-01 ---" "TARGET INSTRUMENT : MyClaim version 0" "RECEIVING" " => 1.0 USD" "GIVING"
When we lifecycle as of
01 Aug 2023 a payment of 1
USD is received by the owner. This
is recorded in the corresponding
The claim then becomes worthless (it becomes the
zero claim) and any subsequent
lifecycling yields no additional effects.
scale constructor is used to multiply a claim’s cashflows by a certain factor.
c = scale (Const 100.0) $ one "USD" acquisitionDate = date 2023 Aug 01
As expected, lifecycling now yields
"--- EFFECT on 2023-08-01 ---" "TARGET INSTRUMENT : MyClaim version 0" "RECEIVING" " => 100.0 USD" "GIVING"
and constructor is used to sum cashflows from multiple sub-claims.
give is used to exchange rights and obligations, flipping the direction of cashflows.
We can define a very simple FX trade as follows, where the owner receives
EUR in exchange
c1 = scale (Const 90.0) $ one "EUR" c2 = scale (Const 100.0) $ one "USD" c = c1 `and` (give c2) acquisitionDate = date 2023 Aug 01
When the claim is lifecycled, we obtain
"--- EFFECT on 2023-08-01 ---" "TARGET INSTRUMENT : MyClaim version 0" "RECEIVING" " => 90.0 EUR" "GIVING" " => 100.0 USD"
When you want to additively combine more than two claims, you can use the
when constructor is used to introduce a time shift, delaying the acquisition of another claim
to a point in the future when a certain predicate is met. For instance, the claim
maturity = date 2023 Aug 31 c = when (at maturity) $ one "USD" acquisitionDate = date 2023 Aug 01
USD once the maturity date is reached, but not before.
When this is lifecycled before maturity, no effect is generated. On the other hand, once we reach maturity we observe
"--- EFFECT on 2023-08-31 ---" "TARGET INSTRUMENT : MyClaim version 0" "RECEIVING" " => 1.0 USD" "GIVING"
at function is used to construct a predicate which becomes
True exactly at the
input date, triggering the acquisition of the sub-claim
Structuring financial instruments¶
Equipped with these basic claim builders, we can already structure a variety of real-world financial instruments.
Fixed Rate Bond¶
A fixed rate bond pays a fixed interest rate over its term and repays the principal amount at maturity. This can be represented as follows
interestAmount = Const 50.0 principal = Const 100000.0 c = andList [ when (at d1) $ scale interestAmount $ one "USD" , when (at d2) $ scale interestAmount $ one "USD" , when (at maturity) $ scale (interestAmount + principal) $ one "USD" ]
d1 ≤ d2 ≤ maturity.
As an exercise, try to model an FX Forward, which is a contractual agreement between two parties to exchange a pair of currencies at a set rate on a future date.
You have learned the basic claim constructors and are now able to structure some real-world
financial instruments. The next tutorial will introduce
Observations, which are used to model
time-dependent market observables, such as stock prices and interest rates fixings.