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.

Additionally, it specifies the instrument’s holding standard or properties, which is described in more detail in the Holding Standards section.

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 instrument’s holdingStandard

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 (i.e., the amount) of an instrument and against which party (i.e., 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.

Holding Standards

A holding implementation can have specific properties such as being fungible and/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 letting a holding template implement the corresponding interfaces (Fungible and Transferable, respectively).

The library distinguishes four types of holdings, referred to as Holding Standards, namely:

1. Fungible: Holdings that are fungible only.
2. Transferable: Holdings that are transferable only.
3. TransferableFungible: Holdings that are both transferable and fungible.
4. BaseHolding: Holdings that are neither transferable nor fungible.

Interfaces

Holding interfaces are defined in the Daml.Finance.Interface.Holding package. It consists of the interfaces holding, transferable, and fungible.

Implementations

Daml.Finance.Holding provides implementations for each holding standard:

• fungible only
• transferable only
• both transferable and fungible
• 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 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 owner is the sole member the outgoing and incoming 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 the custodian be the sole member of outgoing and incoming 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). Our examples typically let accounts be owners-controlled, i.e., both the current owner and the new owner must authorize transfers.

The account also implements the Lockable interface, enabling the freezing of an account, thus disabling credits and debits.

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 transferable and fungible holding at the Commercial Bank (i.e., the custodian in the contract). The holding references the currency instrument and the account.

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.

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.