Basic builders¶

This tutorial introduces the basic claim constructors and shows how to use them to describe a payoff in terms of the future cashflows and other effects 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 below. 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

Builders¶

Zero¶

The zero constructor is used to indicate the absence of cashflows and other contractual events. 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¶

The 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 USD instrument.

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 Effect contract. The claim then becomes worthless (it becomes the zero claim) and any subsequent lifecycling yields no additional effects.

Scale¶

The scale constructor is used to multiply a claim’s effects 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"

Give, And¶

The and constructor is used to sum effects from multiple sub-claims.

give is used to exchange rights and obligations, flipping the direction of effects.

We can define a very simple FX trade as follows, where the owner receives EUR in exchange for USD.

    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 andList constructor.

Warning

By default, the and operator is the function defined in the Daml standard library. To use the claim constructor instead, use a qualified import. Alternatively, you can hide the function from the standard library by using the syntax

import Prelude hiding (and)

The same applies to the or operator, which is not covered in this section.

When¶

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

pays one 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"

The at function is used to construct a predicate which becomes True exactly at the input date, triggering the acquisition of the sub-claim one "USD".

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"
  ]

for d1 ≤ d2 ≤ maturity.

FX Forward¶

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.

Summary¶

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.