In the sample project of the finance library, the Transfer.daml file declares the USD instrument like so:
-- Bank creates the cash instrument
instrumentId = Id "USD"
instrumentVersion = "0"
now <- getTime
cashInstrumentCid <- toInterfaceContractId @Instrument.I <$> submit bank do
depository = bank
issuer = bank
id = instrumentId
description = "Instrument representing units of USD"
version = instrumentVersion
observers = empty
validAsOf = now
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).
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.
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.
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.
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!