DAML Example: Collateral Management
This example demonstrates how the collateral management process can be modeled in DAML.
- Introduction to collateral management provides background on a few functions of the complex topic of collateral management
- A simple model delineates which parts of the processes are modeled
- DAML implementation explains the key design decisions behind the DAML model
- Sample workflow gives a brief overview of the included test scenario
Special emphasis is put on composability, reference data, settling compound transactions atomically, different ways of thinking about contracts on the ledger, and the maintenance of an operational state, which allows for easy integration with external systems.
Introduction to Collateral Management
Collateral is used widely across the financial markets to manage various types of risk. It represents the group of assets pledged or transferred to a counterparty as part of a financial transaction to protect one party against another.
An example of a type of trade requiring the exchange of collateral is a repurchase agreement (or repo), in which a dealer (also known as the borrower or collateral provider) sells or lends securities to an investor (also known as the lender or collateral receiver) that buys or receives the securities and agrees to sell or deliver them back at a later date. The money used to buy the securities can be considered as "borrowed” money, and the securities for which the cash is exchanged is the collateral. If the dealer does not buy back the securities on the agreed upon date, the securities (or collateral) are now the property of the investor. In this scenario, collateral is used to mitigate the cash lending risk of the investor.
While repo is one type of financial transaction requiring the exchange of collateral, there are many other types of trades, including derivatives, that require the exchange of collateral based on the underlying value of the trade. As the value of the securities rises and falls throughout the lifecycle of the trade, more collateral may need to be delivered to fulfill the full value of the obligation or collateral may be returned based on the movement of the market. The collateral provider parties may also decide to substitute different securities for the already posted collateral. In many cases, it is not only the change in value of the collateral that leads to further deliveries and returns, but also other types of risk defined in the eligibility schedule between the counterparties (i.e., securities credit risk, segment risk, concentration risk, securities index risk, etc.).
Transactions that require the posting of collateral are often governed by a collateral agreement between the counterparties. Collateral agreements are typically bilateral or triparty (where an agent is involved) contracts that determine, amongst other terms, the types and amounts of assets that are eligible as collateral, the frequency of collateral valuations, the process by which collateral is valued, and how often collateral is transferred. Two counterparties may have multiple collateral agreements governing their various underlying transactions.
The portion of the collateral agreement that contains the types and amounts of assets that are eligible as collateral is known as the eligibility schedule. The eligibility schedule describes what assets may be posted as collateral, how their fair market value has to be adjusted to calculate their value as collateral, and how much of one particular asset may be used as collateral. One common way to specify the conversion from market value to collateral value is using a discount (also known as haircut), which is a percentage that is deducted from the market value of a security to adjust for its assumed risk exposure. For example, a U.S. government bond (also known as a U.S. Treasury) with a AA+ rating may be eligible with a low haircut given the perceived stability of the U.S. government as an issuer, but a corporate bond with rating A or above might have a haircut of 10% and only constitute at most 50% of the total obligation. Facts like market price or rating are taken from specified third parties. Such external information is collectively called reference data.
Collateral is often exchanged on a daily basis. The parties or their agreed upon collateral agent determine the value of collateral that needs to be posted by evaluating the risk of the underlying trade(s). This value or obligation can be referred to as the margin or Required Value (RQV) depending on the underlying trade type, and represents either Initial Margin (IM) or Variation Margin (VM).
To determine the value of the daily obligation, the parties compare the new obligation against the previous day’s obligation, and determine the amount of collateral that needs to be exchanged, either in the form of a delivery or a return. The counterparty is informed about the required transfer of collateral via a margin call or RQV (nomenclature dependent on the underlying trade type) that reflects the obligation. If the amount is agreed, it becomes legally binding, and a transfer of assets is instructed and settled later in the business day. Such a transfer can either take the form of a true title transfer, in which case the counterparty takes full control over the delivered assets or it can involve a pledge of the assets held at a custodian as collateral for the repo buyer. Traditionally, the substitution of collateral that has already been pledged or transferred is facilitated by over-delivering eligible collateral and, in turn, returning previously pledged or transferred collateral once the delivery is settled. Since transfers and settlements are not instant, and delivery and return cannot be settled atomically, the party is over collateralized during a substitution.
In some cases, the two parties involved in the underlying trade may disagree on the obligation amount. This is known as a dispute, and may be, among other reasons, due to the fact that the parties are using different pricing methodologies. The parties may reconcile this dispute immediately if the different is not materially different, or they may follow dispute protocols as set forth in the collateral agreement.
A simple model
The model is based on two concepts: off-ledger accounts and assets and on-ledger accounts and assets.
Participants have off-ledger accounts with providers. Off-ledger assets in these accounts can be converted to on-ledger assets and vice versa. On-ledger assets are simple agreements in which a provider promises an owner to transfer, on demand, the corresponding security off-ledger. The off-ledger accounts are mirrored by on-ledger accounts to keep track of who has an account with who and facilitate the issuance and settlement of assets. On-ledger assets are fully fungible and transferable between parties with accounts at the same issuer.
Simple asset holding
The terminology used in this example model was chosen to be as descriptive as possible of the workflows involved, and is a mixture of the nomenclatures used in bilateral repo and derivatives trading. The party called borrower is the one with an obligation to the lender and requests for deliveries, returns, or substitutions of assets are made via a call.
A collateral agreement specifies how the fair market value (or price) of an asset is determined, as well as which assets are eligible in terms of their classification and rating. To enter into such an agreement, the lender proposes the agreement to the borrower, who may either accept or reject the proposal.
Sample collateral agreement
Only asset price, classification, and rating are available as reference data on the ledger in this example. Any party is able to publish these attributes, so lender and borrower must agree on the providers of reference data as part of the collateral agreement. Issuers of reference data are able to change the values, for example, to update the rating or price of an asset. Any checks of market value or eligibility by borrower or ledger have to be made against the most up to date reference data.
The lender can make delivery calls to the borrower, and the borrower can make return and substitution calls to the lender under the agreement. The calls can either be agreed or disputed by the receiver, but note that disputes are not covered in this model beyond being indicated on the ledger. Agreed calls can be settled by pledging or transferring an eligible asset. The following rules govern the call types:
An asset can only be used to settle an obligation if it can be shown to be eligible under the collateral agreement and valuable enough to meet the required value of the obligation.
The asset used to settle the return call must match the one specified on the return call.
A substitution of collateral must be pre-allocated with an eligible asset under the collateral agreement at the time the call is made. Both assets are exchanged atomically at the time of settlement.
Disputed and settled obligations remain on the ledger until the caller archives them.
Choices are indicated by diamonds, stakeholders / owners by position above or below the dashed line.
Each collateral agreement has an associated collateral schedule on the ledger that keeps track of the total assets currently pledged or transferred under the agreement.
DAML modules should be designed in a composable fashion so that adding more functionality will not require modification of already existing functionality. It is easy to add new templates to an already running ledger application, but modifying existing templates requires all parties on the ledger to agree to an upgrade.
In this example, four main concerns build up on top of each other:
Templates should be kept as independent from each other as possible. DAML does not support circular dependencies between modules so too much interdependence between templates results in unwieldy modules.
It is worth looking at the asset holding model presented in Simple asset holding in a few different ways.
Looking at it from the perspective of relational databases, there are two types of entities that need to be stored on the ledger -- accounts and account balances:
Primary and foreign key constraints are not enforced automatically in DAML. The uniqueness constraints on primary keys are difficult to realize so it is advisable to build models that do not require them. In this example, duplicate account tokens simply replicate the link between off- and on-ledger accounts and are therefore not a problem. Duplicate balances represent pieces of the overall balance. They are therefore not stored as account balances, but as
Asset tokens, which can be managed via
Merge choices. The foreign key constraint has to be enforced through choices. Asset holding is set up in such a way that the provider can only issue assets to an existing account and transfers can only be accepted with reference to the target account.
Note: A malicious provider and owner could extend the DAML model with further contracts that do allow them to create
Assetcontracts without a corresponding account. This would technically break the foreign key constraint that the model is trying to enforce, but both provider and owner have to agree to this explicitly, so there is no danger to other ledger participants.
Contracts and obligations
At first glance, only the provider appears to be in an obligable position. Unless the on-ledger owner of an asset settles it, there are no off-ledger consequences. The provider could therefore be the sole
Asset contracts, with owners merely appearing as controllers of choices. This would not be in the spirit of DAML. DAML contracts are designed to represent real legal agreements digitally, and the issuance and settlement mechanisms merely provide a workable interface to off-ledger financial infrastructure. Thus, the
Asset contract should not only capture the provider's obligation to convert from on-ledger to off-ledger assets, but also the owners assumption of responsibility for a held asset.
It is important to consider the model in terms of workflows. When a new asset holder joins the ledger, new
Account contracts need to be created. They each require two signatures, so they have to be created through a choice. It would be possible to manage this through intermediate
IssuanceRequest contracts, but that would be cumbersome and make it difficult to ensure that all assets are associated to an existing account. It would also be possible to only issue
Account contracts that way and then issue
Asset contracts via an
Issue choice on
Account. This would work, but create a circular dependency between
TransferRequest that would require all templates to reside in one module. An easy way to circumvent such problems is the use of a role contract as demonstrated in this example. New asset holders are on-boarded through an
AssetOwnerInvitation, and all issuance is managed through the
AssetOwner role contract. This way,
Account is a pure token without any choices, thus avoiding any circularities.
One more important design choice worth highlighting is how asset transfers work. If
TransferRequest had a reference back to the
ContractId Asset of the asset that is to be transferred, the asset would stay with the sender as an
Asset until the receiver accepts the transfer. The downside of that model is that the sender could execute another choice between sending the
TransferRequest and the receiver accepting it, in which case the transfer fails. One could say that the transfer request has gone stale. To avoid race conditions of this kind, the
Asset is consumed by the
RequestTransfer choice in this example, and a new
Asset is created upon acceptance, cancellation or rejection. There is a trade-off, which is that the
Asset is consumed by the
TransferRequest. If a party wanted to keep track of their holdings, they would now have to combine information from
Note: There is another reasonable option, which is to do transfers in three steps.
1. The sender requests a transfer via a non-consuming choice on an asset. The request only contains the value of the asset, not the reference. 2. The receiver accepts or declines. 3. The sender settles the transfer by supplying the asset contract.
This scheme still does not fully solve the problem of stale transfers. A sender could initiate multiple transfers from one asset, but not have the assets to settle them all. This is not as bad, as we end up with choices that cannot be executed due to missing inputs rather than failing choices, but it is no silver bullet for the issue described above.
The result of all these considerations is the following data, signatory and workflow schema. Signatories are highlighted in red. The DAML implementation of the below is found in files
Possible workflows in the simple asset holding model. Note that the the issuance and use of BankB's account has not been shown.
Reference data is represented by simple single-signatory contracts. Anyone can issue such data, so it is up to consumers to agree on which reference data is acceptable. Section Agreeing on complex facts shows how to reach such agreements. The same considerations as for asset holding apply.
In terms of data, reference data is very simple:
All DAML contracts are as private as possible by default, meaning only the issuer can see a piece of reference data. The issuer therefore needs a way to publish their contract to other parties. This can either be done by setting an observer or by divulging the contract via choice. The latter has the disadvantage that divulgence is not preserved when the reference data is updated, and parties that can see the contract through divulgence are not considered stakeholders and do not get notified of any changes. The use of observers is therefore preferable in almost all cases and used in this example.
The only possible workflows on reference data are updates and invalidation, which is simply a removal from the ledger. While they are simple choices to implement, they have considerable impact on how the workflows in Agreeing on complex facts and Collateral agreements work. The purpose of reference data is for other parties to come to agreement on some facts. If the reference data issuer updates the value, any agreements based upon the old value should be voided or otherwise indicate that they are based on an outdated reference data contract. Any attempted use of such agreements should fail gracefully. One way to stop use of outdated agreements is to reference the
ContractId of the reference data used. However, DAML has no try-catch blocks, so the transaction will fail when
fetch is called on the reference data. It would be difficult to distinguish outdated from otherwise invalid agreements and impossible to fail gracefully. A better solution, showcased in this example, is to version reference data. Agreeing on complex facts explains how this allows for graceful failure or helpful error messages.
Agreeing on complex facts
Based on published reference data, agreeing on facts like asset classification and rating is easy in principle as it boils down to a reference to the provider and value of the respective reference data contract. An eligibility rule like "The asset is a Equity with rating at least A by 'RatingAgency'", can be expressed in a function
ContractId Asset -> ContractId AssetRefDataCid -> Update Bool:
Functions are not valid field types for templates. To store the above function as an eligibility criterion on a collateral agreement contract, it would be necessary to make it part of the template, thereby destroying the generic nature of the agreement. Every possible eligibility schedule would require its own template. It is also not possible to evaluate functions specified in the DAML model outside of transactions. Maintaining a state table of agreed facts like asset eligibilities would require reimplementation of logic off-ledger, which is highly undesirable.
Both of these issues are solved by encapsulating the above function in an
AEquityRule template that evaluates it and stores the evaluation arguments and result in a
RuleResult. This provides a relatively uniform output. Many different
Rule templates can all generate
RuleResult contracts as output that allows their consumption by the collateral agreement without fixing what kind of rule was applied. It is also possible to keep an overview of all currently agreed or agreeable facts by making sure there is a valid
RuleResult contract for each
Rule on the ledger.
RuleResult contract above is determined by the signature of the function
ContractId Asset -> ContractId AssetRefDataCid -> Update Bool for which it stores the evaluation result. To agree on price, we need a function
ContractId Asset -> ContractId PriceRefDataCid -> Update Decimal so the rule how to agree on price has to return a
PriceResult rather than a
Note: For more complex applications, it is possible to implement a single kind of
RefDatacontract that stores its payload in a key-value store. Instead of taking a single ref-data contract, the rules (and results) could be adapted to take lists. The type of the result contract for the evaluation of some function on an asset and some reference data then only depends on the return type of the function, which means that only few different types or result have to be dealt with.
One could further reduce the number of templates required by keeping rules very simple and combining them through some kind of algebra like propositional calculus. Rather than having one template for "Type = Bond And Rating = AAA Or Rating = AA Or Rating = A", we would have one template for equality comparison and a way to combine them with "And" and "Or" operators.
From a relational databases perspective, there are two entity types for facts:
RuleResult for boolean facts on assets and
PriceResult for decimal ones. Facts are always established bilaterally in the model, meaning that all rules and results have two parties and signatories on them. Rules are identified by a field
ruleId. It is left to the two parties to ensure that there is no double-use of identifiers.
The contracts perspective does not add much to the considerations. The rules and agreed facts need the signatures of both parties and both parties are obligable in the sense that the other party can use the rule to establish a fact and can use that fact in other workflows.
The key issue with the workflow was already touched upon in Reference data. Parties to a fact need to be able to check its ongoing validity. Since reference data is versioned, this is accomplished by providing the most up-to-date reference data to the result and checking whether the version has changed.
Note: There is no provision for rules to be changed or archived, so the ongoing existence of a rule does not need to be checked in the
Checkchoice of the results.
For the purpose of this example, three rules are provided:
A rule to check that an asset is a AAA bond
A rule to check that an asset is an equity with rating >=A. It is easy to see how the :ref:
example-ca-function-aEquityis encapsulated in the template
A rule to establish a price based on a given provider's reference data.
Note: The ratings
A, and the asset type
Bondare hard-coded in this example. The model would gain some genericity if ratings and types were parameterized on the template. The evaluation result is decoupled from any consumers via the
RuleResultcontract, so this would not require changes elsewhere in the model.
With rules and facts modeled as they are, the collateral agreement pictured in Sample collateral agreement is easy to model by referencing a
ruleId for a pricing agreement and a
ruleId together with a haircut for each eligibility criterion.
The eligibility of an asset under a collateral agreement is agreed bilaterally through a process similar to that for rule or price results. It is modeled the same way. Instead of a
Rule generating a
RuleResult, the collateral agreement itself generates an
EligibilityProof, taking the
AssetRefData contracts for each
EligibilityCriterion as inputs. The
EligibilityProof contracts keep track of which eligibility criteria are applicable to which assets and the effective haircut for each asset. As with the rules, this model allows a participant to keep all the information about eligibility on-ledger in a uniform way. In this example, if multiple criteria are applicable, the minimum haircut is applicable.
The data model and workflow of the process shown in Margin call need some thought. Recall that there are three types of call - Delivery, Return, and Substitution - and four states of a call - Outstanding, Disputed, Agreed, and Settled. The possible actions on each of the 12 possible type / state combinations might be different, but creating 12 contract templates would make maintenance of the model expensive and it would be more difficult to get an overview of all calls. This example therefore only implements one
Call template which keeps track of both type and state, checking for transition validity in the choices.
Calls are made through non-consuming choices on the collateral agreement contract and then advanced from state to state through choices on the call itself. The eligibility check is performed when the request for a substitution is made or upon settlement for deliveries.
The collateral schedule, which keeps track of the pledged or transferred collateral, can be considered the state of the collateral agreement. Since only this state and not the agreement itself changes when collateral is pledged, transferred or returned, it makes sense to keep it in a separate contract of type
CollateralAgreementState. This state is created together with the
CollateralAgreement contract from a
CollateralAgreementProposal and has to be supplied in any of the
Settle choices on
Note: To avoid an intermediate state-change request for every update to the schedule, we allow the borrower to remove tracked collateral, effectively gifting them to the lender. The lender can add tracked collateral, gifting them to the borrower. In a full-fledged collateral management application, this type of unilateral state-change would not be permitted.
Test.daml includes a scenario for a complete workflow using the templates created in this example.