How To Model and Lifecycle Generic Instruments¶

To follow the script used in this tutorial, you can clone the Daml Finance repository. In particular, the file src/test/daml/Daml/Finance/Instrument/Generic/Test/Intermediated/BondCoupon.daml is the starting point of this tutorial.

How To Create a Generic Instrument¶

The Generic extension provides a flexible framework to model generic instruments in Daml Finance. It encapsulates the Contingent Claims library, which allows us to model the economic terms of an instrument.

Define the Claim of a Bond¶

Consider a fixed rate bond which pays a 4% p.a. coupon with a 6M coupon period. Assume there are two coupons remaining until maturity: one today and one in 180 days. This could be modeled in the following way:

    let
      today = toDateUTC now
      expiry = addDays today 180
      bondLabel = "ABC.DE 2% " <> show expiry <> " Corp"
      claims = mapClaimToUTCTime $ mconcat
        [ when (TimeGte $ today) $ scale (Const 0.02) $ one cashInstrument
        , when (TimeGte $ expiry) $ scale (Const 0.02) $ one cashInstrument
        , when (TimeGte $ expiry) $ scale (Const 1.0) $ one cashInstrument
        ]

Keywords like when, TimeGte, scale and one are defined in the Contingent Claims documentation.

Now that we have specified the economic terms we can create a generic instrument:

    instrument <- originateGeneric csd issuer bondLabel "Bond" now claims pp now

This will create an instrument containing the Contingent Claims tree on the ledger.

Define the Claim of a European Option¶

Alternatively, if you want to model a European Option instead:

  let
    exercised = scale (Observe spot - Const strike) $ one ccy
    notExercised = zero
    option = european maturity $ exercised `or` notExercised

This uses the european builder function, which is included in Contingent Claims.

How To Trade and Transfer a Generic Instrument¶

When you have created a holding on the above instrument it can be transferred to another party. This is described in Getting Started: Transfer.

In order to trade the instrument (transfer it in exchange for cash) you can also initiate a delivery versus payment with atomic settlement. This is described in Getting Started: Settlement.

How to Process Lifecycle Events¶

On a coupon payment date of the bond instrument above, the issuer will need to lifecycle the instrument. This will result in a lifecycle effect for the coupon, which can be cash settled. This is described in detail in Getting Started: Lifecycling.

Note: the tutorial mainly describes time-based lifecycling. The European option above requires an active Election by the holder. This is described in detail in src/test/daml/Daml/Finance/Instrument/Generic/Test/EuropeanOption.daml.

How to Redeem a Generic Instrument¶

On the redemption date, both the last coupon and the redemption amount with be paid. This is processed in the same way as a single coupon payment described above.