First Attempt in DAML: Understand Template, Contract and Transaction
Introduction
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.
If you are like me, beginning the blockchain journey with platforms like Hyperledger Fabric and Ethereum, you may get confused by some overlapping terms and preexisted concepts when you first read DAML. In order to get a better picture, I begin my learning with hands-on on DAML. There are good tutorials in DAML, and more importantly, DAML comes with a convenient environment for new learners like me.
The purpose of this article is to document some of my understanding in DAML. I begin with a quick overview, using my wording to describe what DAML is through exploring some concepts in DAML, namely, the template, contract and transaction. Illustration is made with DAML Studio as it comes with a user friendly testing environment. Finally I make a quick comparison on those terms between DAML and other blockchain platforms. Hope this article contributes a bit in your learning journey.
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.
The use of DAML is not only limited to digital assets. This capability can be extended to more transactional practice in the business world. You can refer to some examples when it is used outside the digital asset or finance areas here.
The first-class citizen in DAML is contract, representing a specific digital asset in the ledger. Each contract keeps the necessary detail of this digital asset, and actions that authorized parties can act upon it. Contract is created from a template, which contains the schema of digital asset and all rules binding applied to this type of asset. Contract in the ledger is either active or archived: the active contract is the current state of a digital asset, while the archived ones are simply history. It is a transaction causing the change of contracts. These are the three concepts we are exploring in this article through an example.
In this article we do not cover another important element, ledger, where the contracts are deployed. DAML first comes with its own ledger. Recently they put more effort in working with existing ledger platforms and databases. They currently support some cloud databases such as Amazon Aurora and Amazon QLDB, ledger platform Corda, and some open source integration work with Hyperledger Fabric and Hyperledger Sawtooth. You can see the latest ledger supported here.
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.
DAML comes with a very convenient way to show how things work. The DAML Studio supports scenario simulation and from which we can take a glimpse on the contract instance and transactions in sequence. The screenshots in this article are taken from the DAML Studio.
In this scenario we have four parties: one bank and three customers. The simulation is done in four tasks, namely.
- Task #1: 1-Bank issues an IOU to Alice
- 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
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.
Each specific digital asset (contract) begins with a template.
Here are some rules defined in a template about the digital asset
- The schema of an asset (how to describe this asset).
- 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.
What are NOT included in the template
- The actual parties (who they are)
- The actual data (what they are)
They are specified later when a contract is created.
In our example, for an IOU as an asset.
This is how we read this IOU template.
- The data of an IOU asset includes the issuer and the owner, and an amount of this IOU, defined in with block (line 5–7).
- 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.
So we see how the template looks. We don’t see the actual players like which Bank is issuing an IOU, at what amount, and to whom. This information is needed when we are referring to a real asset (a contract or a contract instance). Here is how our IOU template looks like (left hand side).
In the template It is important to define rules to reflect the real business world. For example, in IOU only the owner is allowed to make a transfer of the IOU. The issuer, despite its authority, cannot make this transfer. This reflects the real business world: you will not allow your Bank to transfer your money to others without your authority.
A template can be used to issue many digital assets, as long as these assets follow the same schema and rule sets. In fact in theory this template can be used by different banks as long as the digital assets share the same nature.
Now we can create contract instances from the template, by providing the required data.
Contract
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.
The right hand side of this diagram is a sample contract instance, created from the IOU template we defined before. We see the actual data: the real issuer, owner, and the amount of IOU. The choices become something actionable in this contract. The authority required to perform these actions is still governed by the rules in the template.
Active Contract and Archived Contract
As mentioned above, we see there are two states in a contract instance.
A contract instance is created by the signatories required, from a template with given data. It is an active contract instance. An active contract instance is made visible and usable following the rules defined in the template.
This active contract instance will remain active until it is archived. An archived contract instance is no longer accessible and usable in the ledger. A contract instance can be made archived explicitly by the signatories, or implicitly when during a data update is made. In such a case, a new and active contract instance is created, while the current one is made archived.
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.
We first define the four parties in our scenario: 1-Bank, Alice, Bob and Charlie.
Task #1: The 1-Bank issues an IOU of 100.0 to Alice (line 22–26). Here we see 1-Bank submits a transaction to create an IOU with the IOU data required about this digital asset. Note that 1-Bank is the issuer, having the authority to create a contract instance with the data provided based on the template. After this action, a contract instance is running in the ledger. As we need to refer to this contract instance later, we keep this contract ID to iou1.
Task #2: Alice transfers this IOU to Bob (line 28–30). Here we see Alice submits a transaction to exercise the choice Transfer specified in the template. The choice Transfer requires the iou contract instance specified (here it is iou1) and the new owner (here it is Bob). Alice has the authority to exercise this choice as she is the owner (controller) of this iou1. The result is that a new IOU contract instance is created, with the owner now set to Bob. The original contract instance is archived implicitly. If anyone can take a look on the current active contract instance, he sees Bob as the owner. Again we are specifying this new iou contract later, we keep this new contract ID to iou2.
Task #3: 1-Bank transfers this IOU to Charlie (line 32–34). This is to simulate an authority error as 1-Bank as an issuer has no authority to exercise Transfer. Note that we use submitMustFail instead of submit, as the failure of transfer will cause scenario stop when using submit.
Task #4: Bob transfers this IOU to Charlie (line 36–38). Similar to task #2, now Bob is the one exercising the choice Transfer, and new owner as Charlie. Bob has the authority as he is the owner. The result, again, is a new IOU contract instance, with the owner now updated to Charlie.
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.
Contract Instances
There are a total of three contract instances in the ledger. Two are archived, while one is active. We are safely convinced that it is the result of our tasks in sequence.
- id #0.0 is the result of task #1: 1-Bank issues an IOU to Alice. It was active when it was created. Note that in this instance, both Bob and Charlie are not yet involved.
- 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.
- 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.
Note that task #3 does not create a new contract instance, as no change in the data. We will see what happens in the transactions.
Transactions
DAML Studio gives us the detail of each transaction recorded in the ledger of our scenario.
We saw a total of four transactions recorded here. This follows the flow of our four tasks. We inspect this one by one, and the relationship with others
TX #0 is for task 1. In #0:0 we see the data of this newly created contract instance.
This corresponds to the #0:0 row in the contract instance table shown above. We see this transaction is “consumed by #1:0”. We will see it in the next transaction.
TX #1 is for task 2. In #1:0 it is the choice Transfer Alice exercised and made Bob as the new owner. This action archives the contract instance of #0:0 (as we see #0:0 is consumed by #1:0). And this is why we see the #0:0 in the table is already archived.
Besides, we also see #1:1, which is the transaction creating a new IOU. The data is the same as the previous one except the owner is now updated to Bob.
TX #2 is for task 3. Here we see nothing happens in the contract instance. We use submitMustFail to bypass the error in the output. Again, 1-Bank as issuer cannot transfer an IOU on behalf of someone, per our design in the template.
TX #3 is for task 4. The logic is the same as previous. #3:0 records the choice Transfer exercised by Bob. As a result, the #1.1 is archived (consumed by #3:0). The result is #3:1, that owner of this IOU is now updated to Charlie. And this #3:1 is the active contract instance shown in the table.
Now we have a better understanding of how contract instances and transactions are processed inside DAML ledger.
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.
We take Hyperledger Fabric as an example. The contract (chaincode) is deployed (committed) once and can be referred. States are kept in a worldstate database. When we invoke functions specified in the chaincode, state can be retrieved from the worldstate database. If the result is an update of state, the worldstate gets updated accordingly.
DAML sees contract differently. In DAML, a contract is a contract instance with state data inside. We trust the system as the data in this active contract instance is immutable and following all the rules defined in a template. Once a change is needed in this digital asset, the contract instance is made archived, and a new contract instance is created (made active) with the updated state.
Besides, the term ledger used in DAML is also different from the commonly known distributed ledger in blockchain platforms. As blockchain is a type of distributed ledger technology, blockchain platforms always come with a network of nodes and the ledger is the common shared data across these nodes through consensus algorithms. For example in Hyperledger Fabric contract code execution is done by a number of selected peers in chaincode containers, and the result is to update the ledger in all peers. We can say that smart contracts (chaincode) in Hyperledger Fabric relies on the infrastructure (like chaincode container and worldstate database to execute a chaincode invocation (transaction), and cannot work outside the Hyperledger Fabric infrastructure. Of course this is not a problem, as no one will use chaincode outside the Hyperledger Fabric environment. But DAML gives another possible architecture.
In DAML, ledger is just a place to keep the contract instances. It can be simply a database, or in a distributed ledger setup. As a language DAML comes with the processing engine, it does not rely on the infrastructure. And this also matches their current effort in running DAML with various databases or ledger platforms.
We cannot say good or bad, right or wrong, between these two approaches. Both have different starting points and development roadmaps. While we see overlapping use cases that we may need to make a choice, we are also seeing both are now finding a way to work together. It is important to understand these different approaches, in order to make good recommendation on which platform can better solve our business problems.
Hope this helps you understand more about DAML.
