Asset Model¶
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.
Instrument¶
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.
Signatories¶
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 issuer
from
potentially acting maliciously.
Keys and Versioning¶
Instruments are keyed by an InstrumentKey, which comprises:
- the instrument
issuer
- the instrument
depository
- a textual
id
- a textual
version
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.
Interfaces¶
Instrument interfaces are defined in the Daml.Finance.Interface.Instrument.*
packages.
All instruments must implement the base interface, defined in Daml.Finance.Interface.Instrument.Base.
Implementations¶
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.
Holding¶
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.
Signatories¶
Every holding must have an owner
party and a custodian
party,
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).
Interfaces¶
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¶
Implementations are provided in Daml.Finance.Holding
for:
- a fungible and transferable holding
- a holding which is transferable but not fungible
- a holding which is neither transferable nor fungible
Account¶
Account contracts are used as proof of a relationship between a custodian
and an owner
.
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 transfersincoming
: 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
owner
is the sole member theoutgoing
andincoming
controllers 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
incoming
controllers of Bob’s account, it is enough that Alice authorizes the transfer alone. - custodian-controlled: If, as often is the case, the
custodian
needs to control what is being transferred, we can instead let thecustodian
be the sole member ofoutgoing
andincoming
controllers 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).
Signatories¶
An account is co-signed by the account owner
and the custodian
.
Keys¶
Accounts are keyed by an AccountKey, which comprises:
- the account
owner
- the account
custodian
- a textual
id
Interfaces¶
The account interface is defined in the Daml.Finance.Interface.Account package.
Implementations¶
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.
Example setups¶
We can now look at a few examples of how real-world rights and obligations can be modeled using the Daml Finance asset model.
Currency¶
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 custodian
.
Finally, the Retail Client is owner
of a
fungible holding at the Commercial Bank
(the custodian
in the contract). The holding references the currency instrument, as well as the
account.
![Currency asset setup.](../../_images/asset_model_currency.png)
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
Equity¶
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
as 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.
![Equity asset setup.](../../_images/asset_model_stock.png)
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
lifecycling section.
OTC Swap¶
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.
![OTC Swap asset setup.](../../_images/asset_model_otc.png)