Reading Daml Smart Contracts for Non-Programmers

How do you read a programming language? And what do we mean by read, is reading just the words on the page or the comprehension of what the program intends, or the ability to reason about whether or not the program does what it intends.

How do you read a programming language?

For most people they simply can’t reasonably read, comprehend, or reason about a program unless they spend a few months learning the programming language they’re trying to read. Even then programming is such a nuanced thing that programmers will often write tests just to ensure that the code they themselves wrote actually does what they think it does.

It stands to reason then that even an experienced programmer cannot be perfectly informed about what a program does or doesn’t do unless they not only read the code but read/write the tests for that code, and have a reasonably strong knowledge of the language they’re reading and writing. This limits the total amount of people who can validate any piece of code, and we regularly rely on others to make these assurances for us.

But no matter how hard we try our understanding of any program ultimately falls short of perfect. So there is no magic solution that will suddenly allow any non-programmer to read and comprehend any program. Rather it’s an improvement.

We shouldn’t need to depend solely on our faith in the provider of a service even if we’re not programmers or well versed in the language. Daml provides a benefit here by making many portions of a program highly explicit, especially the portion that governs agreement. In a standard general purpose programming language you can very easily agree to an action without knowing that you are, whereas in Daml you simply cannot.

This is best to demonstrate though so let’s take a look at a contract I wrote a while back, it’s my favorite.

Weighing in at just 10 lines of code we can read quite a lot of it with just a short explanation as to how Daml contracts create the assurances I mentioned. But once you understand the structure of this one contract you understand the structure of all Daml contracts.

Firstly we have a contract (we call it a template) named Beer, simple enough. Then indented under it we have a structured series of keywords (with, where, signatory, choice, controller). Here our contract is saying that the template Beer comes with a giver, and a recipient. At this point we may have some idea of what the contract does, but really what we have is knowledge of what the contract concerns.

What the contract does is covered under the where clause. Here, indented under the where clause, we have a keyword that says “signatory”. Much like a paper contract may have signatories that sign off on it, Daml (although not a legal contract) has a similar notion when it comes to executing a contract. Can you take a guess at who must sign the contract in order for it to be valid? 

So we have two signatories, giver and recipient, who were specified earlier under the with section of the contract. This tells us that, unless both parties sign this contract it won’t be a contract and won’t do anything.

Once the contract is signed both the giver and receiver can see that one owes a beer, and the other is owed a beer, respectively.

Now we can see that there is a choice on the contract called “Beer_Received” and it has the recipient as a controller. Can you guess who can and who cannot use the Beer_Received choice?

And now that we can see the recipient can exercise the Beer_Received choice we can see it does something under the do clause. Ultimately this is where our understanding would come to an end if we haven’t learned Daml. However we now know substantial portions of how this contract behaves, without any programming knowledge, and can make much more informed decisions about the programs we’re interacting with.

Interested in learning more? Try running a Daml program in your web browser:


Learn Daml online