Securities Daml DLT

Settlement with Daml Finance

author by Ian Woodgate January 18, 2024

In this last post in this series on Daml Finance, we’ll take a look at how settlement is achieved.

Let’s start by defining some of the requirements for settlement. We want to:

  • Ensure that a settlement is atomic (ie all settlement legs happen or none of them do).
  • Lock assets prior to actual settlement, so we can ensure their availability at settlement time.
  • Work with settlement hierarchies and custodial chains.
  • Support complex multi-party atomic settlement, not just bilateral settlement.
  • Have fine grained privacy within a settlement transaction, i.e. within a transaction it should not be the case that everyone sees everything. For example, if paying out to multiple parties in a single transaction, each party should not see the amount being paid to other parties.
  • Support both on-chain and off-chain settlement legs. For example in a DvP we might have a tokenized instrument but the cash payment is off-chain, using a network such as SWIFT. Similarly we could have legs on other blockchains.

Note that settlement does not have to be instantaneous (although it can be). There are some scenarios where there are sound business reasons to delay settlement - for example if additional checks or any kind of netting needs to occur. Daml Finance therefore provides for transaction atomicity, but whether or not to make settlement instantaneous is an implementation decision.

A Real-World DvP

To illustrate how settlement works in Daml Finance, we’ll use the classic DvP example. Although this is a fairly simple example, the same approach can be applied to arbitrarily complex scenarios. We actually saw another scenario in the earlier post on lifecycling. For our DvP though, let’s say at the outset:

  • Investor1 holds 1,000 shares at CustodianA
  • Investor1 has an empty account for cash at BankA
  • Investor2 has an empty account for assets at CustodianB
  • Investor2 holds $10,000 at BankB
  • Custodian1 and Custodian2 each have accounts with a CSD
  • BankA and BankB each have accounts with a Central Bank

We can represent this graphically as follows:

NotAllEqual 04 Settlement - image 1

Now, let’s say that Investor1 and Investor2 agree on a trade at a venue (we’ll call it the Exchange) where Investor1 sells 500 shares to Investor2 for $5,000. What happens in Daml Finance in preparation for settlement and when it’s time for settlement?
To start with we’ll take the case where the DvP is entirely on-ledger. We can identify two steps in our DvP:

  1. Investor1 sends 500 shares to Investor2
  2. Investor2 sends $5,000 to Investor1

We now need to define our routed steps, which are the means by which the steps are achieved and are as follows:

  1. 500 shares from Investor1 to CustodianA
  2. 500 shares from CustodianA to CustodianB (via the CSD)
  3. 500 shares from CustodianB to Investor2
  4. $5,000 from Investor2 to BankB
  5. $5,000 from BankB to BankA (via the Central Bank)
  6. $5,000 from BankA to Investor1

Optionally the routed steps could be found with the help of a route provider in Daml Finance, as explained in more detail in the documentation.

In Daml Finance, the routed steps are converted into a list of settlement instructions (one instruction for each routed step) and a settlement batch that is used to atomically execute all the instructions.

Before settlement can actually happen though, the parties to the transaction have to act on the settlement instructions. In preparation for sending, parties must allocate their holdings and in preparation for receiving they must approve receipt. So for our DvP example, setting it out in a table for clarity:

Instruction Party Action Asset
Instruction1 Investor1 Allocate 500 Shares
Instruction1 CustodianA Approve 500 Shares
Instruction2 CustodianA Allocate 500 Shares
Instruction2 CustodianB Approve 500 Shares
Instruction3 CustodianB Allocate 500 Shares
Instruction3 Investor2 Approve 500 Shares
Instruction4 Investor2 Allocate $5,000
Instruction4 BankB Approve $5,000
Instruction5 BankB Allocate $5,000
Instruction5 BankA Approve $5,000
Instruction6 BankA Allocate $5,000
Instruction6 Investor1 Approve $5,000

The above 12 actions can happen in any order, and in real world scenarios they are usually automated. They are preparatory to the atomic settlement actually happening - settlement can only occur when all of them are completed.

As shares and cash are allocated they become locked. The holder is no longer able to transfer them or allocate them elsewhere.

Our final step is the actual settlement. In our example this is performed by the Exchange. The Canton protocol guarantees that this is atomic, so we can be certain that the DvP occurs in its entirety or not at all. Furthermore, Canton’s sub-transaction privacy ensures that parties only see the parts of the transaction that they need to: in this example the Central Bank, BankA and BankB do not see the shares movement and conversely the CSD, CustodianA and CustodianB do not see the cash movement.

Finally, let’s consider off-chain settlement legs. Within Daml Finance, it is possible to specify that some of the allocations and approvals actions are occurring off-chain. Obviously in this scenario, it is down to the implementation as to how the off-chain activities are achieved, and to what extent transaction atomicity can be preserved. As with any blockchain, off-chain activities are coordinated through API integrations and bridges. These come with complexity and risk, so should be used only where necessary to meet a business need.


The open source Daml Finance library provides a mechanism for fast and efficient atomic settlement of arbitrarily complex transactions. Assets are allocated and locked in advance of settlement, helping ensure their availability at settlement time. Daml Finance supports the real-world scenarios of settlement hierarchies and custodial chains, and the sub-transaction privacy provided by the Canton Blockchain ensures that transaction participants only have visibility of the parts of the transaction that they need to. Off-chain legs are supported with a flexible model that can be integrated as needed with other systems, such as SWIFT, other blockchains, or LoB applications.

More information on settlement in Daml Finance can be found here. There are some good tutorials here and the source code test scripts are also a good reference. In addition, you can contact us to learn more and speak with an expert.