How To Model and Lifecycle Generic Instruments¶
To follow the script used in this tutorial, you can
clone the Daml Finance repository. In particular,
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
Election by the holder. This is described in detail in
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.