Lifecycling with Daml Finance

Editor’s note: Ian Woodgate is a Technical Sales Engineer at Digital Asset. This is Part I in a series on asset tokenization. Don't miss the Introduction.

Lifecycling refers to the evolution of financial instruments over their lifetime. This includes processing of contractual events, like interest payments or coupon cash flows, as well as discretionary events, like dividends and other corporate actions. Daml Finance provides a standard mechanism for processing such events across different instruments.

Having capabilities such as lifecycling built in to tokenized assets is key to leveraging tokenization to streamline processes, retire legacy systems, and reduce costs. As discussed in our previous post, tokens lacking these capabilities simply add another layer of complexity and cost to operations.

Drilling into a bit more detail, there are three challenges that we have to solve to manage our lifecycling effectively:

  1. Instrument representation

  2. Keeping track of what stage of its lifecycle our instrument is at

  3. Applying the outcomes (or effects) of a lifecycling event in a consistent manner to all instrument holders

Instrument representation

Our first challenge is how to represent different instrument types in a way that allows us to take the same approach to lifecycling them all. Daml Finance solves this problem with the use of trees of contingent claims. It turns out this is a very powerful representation, and more information is in the documentation, but I will illustrate it here with a simple example of a fixed-rate bond.

Our bond is a series of fixed, annual coupon payments followed by the final redemption payment, all at fixed dates. As an aside, Daml Finance can also handle variably timed events based on external inputs (such as a dividend distribution), but this is a detail we won’t worry about in this post. If we have a five-year bond paying an annual coupon, our tree looks like this:


When the bond is lifecycled, the “AND” at the top means all branches are evaluated. The first five branches are the annual coupon payments and the last branch is the redemption. We can see that the payments are made when each date is reached.

Next we’ll look at how we keep track of which branches have “run”, before seeing how the outcomes of each lifecycling activity are handled.

Instrument versioning

The second challenge is this: How can we know which lifecycle events have been processed on a given investor’s holding and which have not? In the world of dividends, this is solved through the use of an “ex-dividend” date, where shareholders before that date get the dividend and shareholders after do not. But this “big-bang” approach creates much complexity in identifying all the correct dividend recipients on a given day.

Daml Finance delivers a more efficient and flexible operating model. All instruments are versioned so that for a given version, you know what lifecycle events have or have not occurred. This means that it is perfectly safe for multiple versions to co-exist at the same time, and it allows for a gradual transition from one version to another.

Using our bond as an example, let’s say the date is now 2023-02-10 and the issuer is going to lifecycle our bond. The first branch will execute and will result in the requirement to make a coupon payment. But something else is needed as well: A new representation, or version, of our bond that reflects that the coupon has been paid. This is easily achieved by trimming off the first branch, so the version change looks like this:

The Outcome is used to create a Lifecycle Effect. This describes the distribution of assets per unit of Version 1 of our bond.

A Lifecycle Effect also specifies a target instrument, which is the version of the instrument that can be used to claim the outcome of a Distribution Event. Being tied to a specific instrument version prevents holders from claiming a particular effect twice.

Let’s see how the Lifecycle Effect looks for our bond:

Applying Lifecycle Effects to instrument holders

Our final challenge is to apply Lifecycle Effects to instrument holders. In the case of our bond, this means paying the coupon amount. In Daml Finance, this process is known as “Claiming an Effect”. It applies a Lifecycle Effect to a holding, whilst guaranteeing that this can only happen once, and that the asset movements all occur in their entirety so that consistency is maintained.

To do this, another feature of Daml Finance, a Settlement Batch, is used. A Settlement Batch is a set of settlement steps, and each step is the movement of an asset from one owner to another.

To illustrate this with our bond example, let’s say an investor holds 800,000 bonds. To be more specific, they actually are holding 800,000 of Version 1 of our bond. The issuer has lifecycled the bond, so the Lifecycle Effect for the first coupon payment has been created, but it has not yet been applied to our investor’s holding.

When this happens (i.e., when the Effect is claimed) the following Settlement Batch is created:





















We can see that executing this settlement batch requires that the investor return their Version 1 bonds and receive both Version 2 bonds and the coupon payment. Daml Finance ensures that this process happens atomically.

Note that it is not necessary for all investors to simultaneously perform this activity. It is perfectly acceptable for a mixture of different instrument versions to be held by different investors at the same time (or even for one investor to hold a mixture of versions if so desired).


In this post, we have seen:

  • Daml Finance allows complex, real-world assets to be fully represented “on chain”, as opposed to creating bearer instruments and managing other aspects elsewhere

  • How instrument lifecycles are modeled and applied to investor holdings

  • That the Daml Finance lifecycling approach simplifies the processing of lifecycle events and provides more flexibility in application of lifecycle events to all holdings

More information on lifecycling in Daml Finance can be found here, or you can contact us to learn more and speak with an expert.

You can also watch the recording of our recent webinar presenting the concepts in this post.