First Attempt in DAML: Understand Template, Contract, and Transaction

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.

Read KC’s full article here and check out the rest of his research here.


Great article @kctam!

I really enjoyed the part where you explained the Template, Contract and Transaction in DAML with the examples :clap:


Thanks @andreolf. I’m still learning this interesting language and will share more when I practice more.


I really enjoyed your article KC Tam. Thanks for the straightforward and easy to follow breakdowns of the technology and terms!


What are your next DAML topics that you are working on?

1 Like

Great intro article @kctam :slight_smile: Easy to follow with concrete examples, enjoyed reading it :slight_smile:


Yes, good article , not quite finished and I bumped into something that perhaps somebody can clear up for me. The article states that:

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.

So it seems that state changes up to the current state of the contract are NOT on the ledger. If so how does one go about retrieving the "audit trail " i.e. the set of transactions and corresponding state changes leading up to the current contract state ?



1 Like

Contracts in DAML never change: a contract is created with a given state, and thereafter the only thing that can happen to it is to get archived. If you’re using a contract to track the state of something that changes over time, you will in fact archive the existing contract and create a brand new one on each “change”.

So how do you keep track of the “continuity” in that case? How do you know that contract 2 is in fact the next state of contract 1 and not something completely unrelated? To some extent that’s up to your application; one suggestion could be to use a UUID (generated outside DAML) that you keep in some “ID” type of field. DAML does have a language feature meant to help with that sort of tracking: contract keys. Unless there’s a more natural key for the contract you want to track, the set of involved parties + a UUID is a good starting point for a key.

The audit trail question is a bit different. Through the Ledger API (the gRPC one), you can actually access the entire tree of transactions (though see caveat in next paragraph), and therefore verify how the system got there. So archived contracts are accessible for review in that sense. However, archived contracts are not accessible through DAML itself (i.e. DAML code cannot use them) and they are also not available through the JSON API.

The caveat here is that the ledger operator is allowed, under the DAML Ledger model, to truncate its history to some extent. So, in general, especially if you are not the ledger operator, you should strive to:

  • Keep data around in active contracts if that data is still useful to the logic of your application. There is no rule against keeping track of previous states in a contract, say as a list of values.
  • Keep your own copy of the entire transaction history if you believe you may need it later, i.e. set up a Ledger API client that listens to the transaction stream and persists it to a place under your control, if you do not trust your ledger operator to keep enough of it for you.

but isn’t it part of the DLT promise the “verifiability” of an activity path to a certain outcome ?
Even if I monitored and persisted ledger state can I actually prove the “origin” state of the contract and that a certain state was the actual succession to another ? I believe Merkle trees do that but not entirely sure or whether DAML implements these or if there are other mathematically proven mechanisms.

I admit to being confused. I’m not sure whether a universal truth can be claimed and therefore if not whether disputes can be resolved as to what a contract state should be.

Still quite new at DAML you would think that if it can sit on top of Corda , Fabric etc that the answer is then that these DLT are the providers of the DLT universal truth i.e. that trustless ecosystem. Furthermore, perhaps one falls out of DAML and into the specific DLT API for some of these answers.

1 Like

I’m not the best person to discuss the details here, but I believe you are assuming a bit too much about DLTs/blockchains. A blockchain will allow you to verify that block A comes before block B, but not necessarily any kind of semantic link between line item 46 in block A and line item 93 in block B.

In a DAML system, you have DAML transactions. They may or may not map directly to the transactions in the underlying storage mechanism (e.g. perhaps you can store multiple DAML transactions inside one Corda or Fabric transaction). The underlying storage may give you some additional guarantees or properties, but let’s focus on the DAML level for now.

In the DAML code itself, you cannot access archive contracts, as I mentioned previously. You also cannot ask a contract for its “previous” values, as there is no implicit link between contracts. (Though of course you can write your DAML code such that the new contract does save previous values, as explained above. It’s just not automatic/implicit.) This is just not something DAML can do for you, as a single exercise of a choice could conceivably archive many contracts and create many contracts.

That does not mean you have no provenance information, however. Every DAML transaction is a tree of Create and Exercise nodes, where each node is signed by the relevant parties. So the information of how you got to the current state is there: you can see the transaction that archived the “previous” contract and created the “new” one, with all appropriate signatures, as well as a unique (hash-based) reference to the exact DAML code that was run. If your transaction does more than archive a single contract and create a single other contract, there may not be such an obvious lineage, but you can still map the before/after states and the code to understand/verify what happened.

Does that help?

1 Like

Well, it does if I understood it correctly , and its akin to Corda transactions , although you do not mention how that it can be done i.e. API which would be appreciated. What I have gathered is that there’s indeed a transaction tree which I assume one can walk done and at every node one can find “state” values e.g. assigned collateral to a trade etc

1 Like

Taking a step back: while your DAML code can be executed in scenarios for simple test cases, in a real system the DAML code is not driving the application, it is only reacting to parties exercising choices. Those parties have to interact with the DAML system through the Ledger API (perhaps reaching that API through another layer, such as the JSON API).

That API is documented here; the specific section about reading transaction trees is this one.

We provide code examples and a convenience wrapping library for Java, but this is a gRPC API, which means you can access it from pretty much any language.

1 Like

Hi @amiracam, first of all, thanks for you questions!

In DAML you absolutely have the full audit trail of how things evolved to the current state. Similar to Corda or even bitcoin, we separate two parts of any audit trail:

  1. Audit of the event log, i.e. some data structure which records all events that happened in the system, together with a time stamp or any other way to sequence the events, and a cryptographic mechanism to commit to this data structure (usually Merkle trees). In bitcoin or Ethereum for example these are the blocks
  2. Audit of the transaction graph, i.e. the logical dependencies between transactions

The DAML data model addresses #2 directly regardless of what ledger you are using. DAML uses the underlying ledger to take care of #1, so if you’re using DAML for VMware blockchain, DAML for QLDB, DAML for Corda, etc, you get the #1 audit assurances as well. If you use DAML for Postgres, DAML for Aurora, DABL, etc (databases which don’t have a cryptographic audit trail) you only get #2 and not #1