Question regarding the Instrument in Finance Library

Questions
,
1

G-d willing

Hi guys,
In the sample project of the finance library, the Transfer.daml file declares the USD instrument like so:

  -- Bank creates the cash instrument
  -- ISSUE_CASH_INSTRUMENT_BEGIN
  let
    instrumentId = Id "USD"
    instrumentVersion = "0"
  now <- getTime

  cashInstrumentCid <- toInterfaceContractId @Instrument.I <$> submit bank do
    createCmd Instrument
      with
        depository = bank
        issuer = bank
        id = instrumentId
        description = "Instrument representing units of USD"
        version = instrumentVersion
        observers = empty
        validAsOf = now
  -- ISSUE_CASH_INSTRUMENT_END

Why do we need this instrument contract? Where do we use it, or when do we need to use it?
When creating holdings, we use the instrumentId and the `instrumentVersion (which are properties of the instrument).

Thanks

1 Like
2

An instrument contract encodes the economic terms and lifecycle logic of a financial instrument (cf. here).

We use the instrument primarily to manage the lifecycle of more complex instruments, for example to distribute cashflows (coupons, dividends, etc.) a holder is entitled to.

You are correct that in the simple case of a cash instrument, there’s no lifecycle associated with it. Therefore, technically it’s not strictly needed for you to transact in the asset (eg. do transfers, settlement, etc.). But it is strongly advised that your workflows do actually enforce the existence of the instrument nevertheless (by eg. fetching it by key when creating holdings), as the convention is that all holdings should refer to a live instrument contract. This is primarily because one can add lifecycle rules for an instrument after the fact, in which case you’ll need the instrument contract after all.

2 Likes
3

G-d willing

Thank you @georg for your response.
Is there a good example where I can see this lifecycle you mention?
I am constructing a system where it might be needed, however, I don’t see how to put it together.

Thanks

4

G-d willing

Is there an example showing the use of the instrument along with its instrument key? I would like to learn the lifecycle of an instrument during several finance transactions.

5

Hi @cohen.avraham,

The Daml Finance quick-start template that comes with the Daml SDK includes a life-cycling example. This is slightly outdated, but showcases the core concepts in a simple example. A new version will be shipped with the SDK 2.5.0.

If you then want to see how specific instruments are implemented and lifecycled, I encourage you to take a look at the instrument tests in Daml Finance.

In addition to the lifecycle workflow in the quick-start template, you can also have a look at, e.g., this test script, where

  • an instrument is created for a cash-settled forward contract
  • a holding on the instrument is created for an investor at the bank
  • the instrument is lifecycled
  • the lifecycle effect is used to process the investor’s holding and claim the due amount

I hope this helps!

Matteo

1 Like