The library’s asset model is the set of contracts that describe the financial rights and obligations that exist between parties. It is composed of instruments, holdings, and accounts.
An instrument contract describes the economic terms (rights and obligations) of one unit of a financial contract.
It can be as simple as an ISIN code referencing some real-world (off-ledger) security, or it can encode specific on-ledger lifecycling logic.
Every instrument must have an
issuer party and a
depository party, which are both
signatories of the contract.
The terminology is borrowed from the real world. For example, an issuer of a stock instrument deposits the paper certificate at a depository and gets the corresponding amount credited in book-entry form.
On the ledger, the
depository acts as a trusted party that prevents the
potentially acting maliciously.
Keys and Versioning¶
Instruments are keyed by an InstrumentKey, which comprises:
- the instrument
- the instrument
- a textual
- a textual
The version is used to keep track of the linear evolution of an instrument. For example, once a dividend on a share is paid, the version is used to identify the cum-dividend and the ex-dividend share.
Instrument interfaces are defined in the
All instruments must implement the base interface, defined in Daml.Finance.Interface.Instrument.Base.
A base implementation is provided in Daml.Finance.Instrument.Token.
This template does not define any lifecycling logic and is suitable to model contracts that are likely to stay stable, such as currency instruments.
The extension packages provide additional business-specific implementations, such as an Equity instrument (where the issuer can pay dividends) or a Bond instrument (which includes coupon payments).
The expectation is that customers define their own instruments suiting the use-case they are modeling.
A holding contract represents the ownership of a certain amount of an instrument by an owner at a custodian.
Whereas an instrument defines what a party holds (the rights and obligations), a holding defines how much (ie., the amount) of an instrument and against which party (ie., the custodian) the instrument is being held.
It is important to understand that the economic terms of an asset (the instrument) are separated from the representation of an asset holding. This allows centralized management of instruments (e.g. lifecycling) and the reuse of instruments and associated logic across different entities (e.g. custodians). It also avoids the data redundancy of replicating instrument data and logic on every holding contract.
Every holding must have an
owner party and a
which are usually both signatories of the contract.
The terminology is again borrowed from the real world: our cash or shares are usually deposited at a custodian and we have (at least in principle) the right to claim them back from the custodian at any given time.
Properties of Holdings¶
A holding implementation can have specific properties such as being fungible or transferable.
When, for instance, a holding is transferable, the ownership can be transferred to a different party at the same custodian.
These properties are exposed by implementing the corresponding interface (Fungible and Transferable, respectively).
Holding interfaces are defined in the
Daml.Finance.Interface.Holding package. These include a
base holding interface,
as well as interface definitions for the above properties.
Implementations are provided in
- a fungible and transferable holding
- a holding which is transferable but not fungible
- a holding which is neither transferable nor fungible
Account contracts are used as proof of a relationship between a
custodian and an
owner must have an account contract with a
custodian before a holding contract can be
created between the two parties.
This is similar to how, in the real world, you need to open a bank account before you can use the bank’s services.
The account contract also controls which parties are authorized to transfer holdings in and out of the account. To be more precise, the controllers field of the account contains:
outgoing: a set of parties authorizing outgoing transfers
incoming: a set of parties authorizing incoming transfers
This allows for modeling various controllers of transfers between Alice’s and Bob’s accounts. For example:
- owners-controlled: If the
owneris the sole member the
incomingcontrollers for the accounts, a transfer of a holding from Alice’s account to Bob’s account needs to be authorized jointly by Alice and Bob.
- owner-only-controlled: If, instead, there are no
incomingcontrollers of Bob’s account, it is enough that Alice authorizes the transfer alone.
- custodian-controlled: If, as often is the case, the
custodianneeds to control what is being transferred, we can instead let the
custodianbe the sole member of
incomingcontrollers of the accounts.
Accounts also serve to prevent holding transfers to unvetted third parties: a holding of Alice can only be transferred to Bob if Bob has an account at the same Bank (and has therefore been vetted by the Bank).
An account is co-signed by the account
owner and the
Accounts are keyed by an AccountKey, which comprises:
- the account
- the account
- a textual
The account interface is defined in the Daml.Finance.Interface.Account package.
A base account implementation is provided in Daml.Finance.Account.
The account can be created with arbitrary controllers (for incoming and outgoing transfers).
In our examples, we typically let accounts be owners-controlled, i.e., both the current owner and the new owner must authorize transfers.
We can now look at a few examples of how real-world rights and obligations can be modeled using the Daml Finance asset model.
We start by modeling a standard cash bank account. There are three parties involved: a Central Bank, a Commercial Bank, and a Retail Client.
The Central Bank defines the economic terms of the currency asset and is generally a highly trusted
entity, therefore it acts as
issuer as well as
depository of the corresponding instrument.
We can use the Token instrument implementation for a currency asset, as we do not need any lifecycling logic.
The Retail Client has an
Account at the Commercial Bank, with
the former acting as
owner and the latter as
Finally, the Retail Client is
owner of a
fungible holding at the Commercial Bank
custodian in the contract). The holding references the currency instrument, as well as the
In this scenario, we can see how:
- the instrument defines what is held
- the holding defines where the rights and obligations lie, as well as the corresponding amount
We now model units of shares held by an investor. There are three parties involved: an Issuing Entity, a Securities Depository, and an Investor.
The Issuing Entity acts as
issuer of the Equity Instrument. The Securities Depository acts
depository of the instrument, thus preventing the Issuing Entity from single-handedly
modifying details of the instrument (such as the share’s nominal value).
The Institutional Investor holds units of shares against the Securities Depository, through corresponding Account and Holding contracts.
It is worth noting that the
issuer of the Equity Instrument has the right to perform certain
Corporate Actions, such as declaring dividends. This topic is covered in the
Finally, we model an OTC (over-the-counter) fixed vs. floating interest rate swap agreement between two parties, namely Party A and Party B. We can use the Interest Rate Swap instrument template for this purpose.
In this case, all contracts are agreed and co-signed by both parties. In the instrument contract,
it does not really matter whether Party A is the
issuer and Party B the
depository, or the
other way around. However, the role matters in the Holding contract, as it defines the direction of
the trade, i.e., which party receives the fixed leg and which party receives the floating one.