First Attempt in DAML: Understand Template, Contract and Transaction


DAML is first positioned as a language modeling digital asset in a ledger, and recently evolved into a platform ready for building full stack applications, and working with many distributed ledger technologies (DLTs) and databases.

Quick Overview of DAML

In real life we refer to something of value as an asset, and digital assets are assets in digital form. When assets are presented in digital form, we are more concerned about the detail and accuracy of the asset, like ownership, terms and conditions about the assets, what can be done upon the assets are the focus. etc. DAML is modeling the lifecycle of assets in the digital world.

Template, Contract and Transaction in DAML

Begin with an Example

We are using an example to illustrate these concepts in DAML in this article. The asset is an IOU. This IOU can be made transferrable. We simulate a scenario that a bank issues an IOU to someone, and someone transfers this IOU to others.

  • Task #2: Alice transfers this IOU to Bob
  • Task #3: 1-Bank tries to transfer Bob’s IOU to Charlie but fails
  • Task #4: Bob transfers this IOU to Charlie


Template is “the blueprint of a contract”. Although contract is the element in the ledger, it is the blueprint defining how a digital asset looks like and what rules are applied to this type of assets. Therefore we first take a look into the template.

  • The parties who have the authority to create this asset in the ledger (i.e. make a contract instance active) and inactivate it (i.e. make it archived and no longer usable).
  • The role of parties who can interact and/or make observations on a digital asset.
  • The actions (called choices in DAML) these parties can exercise, and the logic in each of the actions.
  • The actual data (what they are)
Template of IOU contracts
  • The rules are collectively defined in where block (line 9–14)
  • Issuer is the signatory, having the authority to create and archive this IOU.
  • This IOU is visible by the owner (observer).
  • There is one action (choice) defined in this template: Transfer, exercisable by the owner (controller). The owner makes a transfer of IOU through exercising this choice (Transfer).
  • When the owner makes a transfer, he/she specifies which IOU contract instance (contract ID) and a new party as the new owner.
  • The actual logic in this choice (Transfer) is to create a new IOU contract instance, with owner data updated with the new owner given. The original contract instance is implicitly archived.
The Left Hand Side is a template for IOU. We will see the Contract Instance in next session.


A contract represents a digital asset in the ledger. It is born from a template, and hence bears all the rules defined in the template. The data required in the template is also filled with meaningful data in a contract. Each contract in DAML is therefore an instance of a template. As a result we always use the term contract instance to represent a contract. They are the same thing in DAML.

Contract Instance is born from a template, with actual data about this digital asset.

Active Contract and Archived Contract

As mentioned above, we see there are two states in a contract instance.

Scenario: A Simulation of our Example

The best way to illustrate how the contract lifecycle looks is through examples. We create the scenario in DAML Studio with the four tasks described above.

Scenario defined in DAML Studio for testing and illustration

Observation: What is in the Ledger

We use the scenario shown above and inspect what happens inside the ledger. The DAML Studio comes with good illustration and we are going to inspect the output of the scenario result, step by step.

Scenario showing contract instances
  1. id #1:1 is the result of task #2: Alice transfers this IOU to Bob. This transaction has made the first #0.0 archived, as a new contract instance becomes active with owner changed to Bob. In this case, the 1-Bank, Alice and Bob are relevant in this contract, while Charlie again is not involved.
  2. id #3:1 is the result of task #4: Bob transfers this IOU to Charlie. Similarly, this makes #1:1 archived, and becomes a new contract instance. In this contract instance Alice is not involved as it is only the business of 1-Bank, Bob and Charlie.

Smart Contract and Ledger: in DAML and in Blockchain Platforms

DAML is a smart contract language for digital assets. Although it is not official, “smart contract” is always associated with blockchain platforms as an integral element implementing business logic. It is quite common for new learners, when they hear about smart contracts in DAML, they will think of this term in the context of blockchain platforms.

Visit for all my works. Reach me on or follow me @kctheservant in Twitter.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store