Need help understanding Bitcoin DeFi?
Need help understanding Bitcoin DeFi?
Need help understanding Bitcoin DeFi?
Need help understanding Bitcoin DeFi?
Need help understanding Bitcoin DeFi?

Write Better Smart Contracts With the Programming Language Clarity

The Stacks ecosystem has its own smart contract programming language called Clarity. In this post, I’ll explain why the Stacks ecosystem launched a new programming language, as well as explore some of the innovation being built with Clarity, and what resources Clarity developers have at their disposal.

Deep dive
March 1, 2024
Head of Engineering
Is Clarity the best programming language for smart contracts?

I am now 2 and a half years into my time at Hiro, where I manage the engineering team as the VP of Engineering. One of the questions I often get asked by new developers is “why does Stacks have its own programming language?”

In fact, I knew about Clarity before I learned about Stacks, and the language was an influential part of my decision making process to join this ecosystem. I wanted to put some thoughts down as to why I think Clarity is such a powerful force and a valuable asset for the entire ecosystem.

Note: this blog was originally published two years ago and was inspired by a conversation I had with Marvin Janssen, the CTO of Ryder. With this update, I’ve added more context on the state of Clarity today.

Why A New Programming Language?

Inventing a programming language takes a lot of work. When you decide to undertake that work, you have to have a good reason to do so. A number of brilliant minds working on Stacks saw a need for a new programming language because there wasn’t a programming language that was optimized for the realities of smart contracts and blockchain technology. That’s where Clarity comes in.

Amongst the many benefits of Clarity, these are my three favorites:

  1. It is interpreted and not compiled.
  2. The language is decidable.
  3. It does not allow reentrancy.

Let’s unpack each a bit further.

Clarity is an interpreted language.

Human-readable langauges are superior

Many popular smart contract programming languages are compiled, meaning the human-readable code is compiled into machine language, and I have always found that a strange design principle in a space that preaches “trust, but verify.” How can you verify if you can’t read the code?

Clarity is an interpreted language, which means the code is human-readable. By design, Clarity also requires smart contracts to publish their source code on the blockchain. This choice brings a number of benefits.

It gives users confidence that the smart contract code is the same as the source code (in a compiled language, this is harder to verify), it allows users to easily verify that code (it’s human-readable), and it makes the Stacks blockchain a ‘GitHub for smart contracts.’ With the readable source code of every smart contract on the blockchain, developers have far more tools, references, and samples with which to build and innovate.

Clarity is decidable.

Predictable code is safer code.

In short, decidability means you know what’s coming. Before executing the code, you know where it will terminate. The logic is decidable. This ability of static analysis also lets you determine runtime costs and data usage in the code.

This is in stark contrast to Turing-complete languages like Solidity where the code execution can take paths that you cannot predetermine. This makes your code less secure and easier to hack. Clarity avoids this Turing-complexity on purpose, which makes it much more secure. For instance, recursion is illegal, and looping is only performed via `map`, `filter`, and `fold`.

This decidability makes it much easier to debug smart contracts. In a test environment, you have REPL, print loop, and other features of a decidable language that make it easier to reason with the code and iron out any issues.

Clarity doesn’t allow reentrancy.

That's one less backdoor for exploitation.

Reentrancy is an aspect of a programming language where any call being executed can execute additional threads or graphs within the calling contract. This introduces a type of insecurity that Clarity avoids altogether.

In a very basic example, reentrancy allows the following situation: Contract A calls into Contract B, and Contract B simultaneously calls back into Contract A. That’s reentrancy. A contract reentering and doing the same function again.

If you are not very careful with your order of operations in Contract A, reentrancy can make your code do things it shouldn’t have. For example, if contract A is a simple transfer function, its order of operations would be something like 1) assess user balance 2) deduct tokens to be transferred from that balance 3) transfer tokens.

Now you can imagine scenarios where Contract B can call back into Contract A and disrupt that order of operations if that order isn’t carefully set up. For example, it could cause the tokens to get deducted from a user twice. Or maybe the tokens haven’t been deducted yet, but Contract B is able to trigger an action that is supposed to occur only after that deduction.

Clarity doesn’t let you do this by design. If the language detects reentrancy, it aborts the transaction, and the reason it can detect reentrancy is because the language is decidable.

You can learn more about how Clarity is unique in this post comparing Clarity to Solidity, Ethereum’s programming language.

Innovations in Clarity

I’ve listed a few examples of how powerful the Clarity language is, but let’s take a look at some of those powers in practice. What are developers doing with this language?

We are seeing tons of innovation on Stacks, from identity systems that settle on Bitcoin in BNS to fully decentralized and non-custodial NFT marketplaces in Gamma.

It’s too much to name everyone, but I will highlight two projects that are pushing the boundaries of what’s possible with Clarity.

Stacking DAO

Stacking DAO introduces a liquid stacking protocol to Stacks that allows users to benefit from the yield of stacking (where users can lock up STX and earn BTC yield) but remain liquid in the process. This is similar to liquid staking protocols and what Lido has brought to Ethereum.

What interests me about this project is that not only is it a major liquidity unlock for DeFi (in just a few months, the project has grown to $72M in TVL), but it has an elegant design. Stacking DAO is broken into several different Clarity contracts that cover stacking, DAOs, NFT mints and burns, Bitcoin transactions, and more. There’s a lot developers can learn from this project.

And since Clarity has the ability to read Bitcoin’s global state, you can actually use Clarity to audit Stacking DAO’s stacking rewards by tracing the corresponding Bitcoin transactions, increasing transparency of the protocol and a great example of the values we hope to embody while building on Bitcoin.

Arkadiko Finance

Arkadiko is interesting to me because it uniquely leverages Stacks’ Proof of Transfer consensus mechanism. Arkadiko is a collateralized debt protocol in which the collateral is locked in Proof of Transfer, enabling self-repaying loans.

Effectively, Arkadiko enables users to deposit STX and mint the USDA stablecoin, and their deposited STX are locked in PoX. This removes the need for monthly payments, and a user’s deposit will ultimately pay off their loan.

This is an innovative approach to debt protocols that can only be built on Stacks with Clarity and proof of transfer. Self-repaying loans. Pretty cool if you ask me.

Where Do Developers Get Started?

For developers looking to learn Clarity and start building Bitcoin apps, there are a number of resources to help you get started:

And of course, in order to build, developers need tools, and that’s where Hiro comes in. We focus on all things developer tools across the entire stack.

We offer 3 different APIs to give you access to the on-chain data you need. We built the Hiro Platform, so you can manage your projects and deploy contracts in a matter of minutes. We have Clarinet, the go-to tool for local smart contract development.

These tools have a number of features to make it easier to write Clarity code, including inline debuggers, static analysis tools, error highlighting, and more.


I believe Clarity is one of the biggest strengths of the Stacks ecosystem, and any developer should be exploring the benefits of this programming language. In the world of smart contracts, I think you’ll find that you want a language that is optimized for transparency and security. If you’re looking for more resources to get started, check out Clarity documentation here, as well as Hiro’s documentation here.

Copy link
Hiro news & product updates straight to your inbox
Only relevant communications. We promise we won’t spam.

Related stories