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
May 12, 2022
Director of Engineering
The Powers of Clarity

I am now 6 months into my time at Hiro, where I manage the developer experience and developer tools as the Director 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.

This post is also inspired by a conversation I had with Marvin Janssen, the Tech Lead from the Stacks Foundation. We sat down at Bitcoin Unleashed, the Stacks event in Miami last month to discuss Clarity. Some of the ideas below are his, others are mine. If you’re curious, you can watch our conversation here.

Why A New Programming Language?

Inventing a <code-rich-text>programming language<code-rich-text> 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 that a bit further.

Clarity is an interpreted language.

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?

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 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 with which to build and innovate.

Clarity is decidable.

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.

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.

Learn more about Clarity and how it compares to Ethereum's Solidity in a workshop led by Hiro's Developer Advocate Max Efremov:

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 innovative use cases with the blockchain’s consensus mechanism (in Arkadiko’s self-repaying loans or CityCoins’, well, city coins) to fully decentralized and non-custodial NFT marketplaces (STXNFT).

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

Catamaran Swaps

Catamaran swaps introduce native Bitcoin swaps to the Stacks ecosystem and allow users to swap Bitcoin for Stacks (STX) as well as other assets in the future. Through a catamaran swap, users can trustlessly swap assets. There is no 3rd party or custodial service. There is no KYC, no counter-party risk.

Clarity can read Bitcoin’s global state, and you can program smart contracts that react to it. What’s fascinating about these swaps is that you can verify the BTC transaction from the Clarity smart contract.

Clarity can read Bitcoin’s global state, and you can program smart contracts that react to it.

In a catamaran swap, a user sends BTC to a specific address, the smart contract checks whether BTC was sent to the right address in the right amount and whether that transaction has been mined, and if those conditions are true, it sends STX to a specified address.


Boom’s project Boomboxes is interesting to me because they have leveraged Stacks’ Proof of Transfer (PoX) consensus mechanism in a unique way. Boomboxes are NFTs with an underlying STX collateral, and they generate yield through PoX. 

Effectively, these NFTs allow users to participate in “delegated stacking,” and the NFTs act as a claim certificate for the rewards generated by the STX collateral. If the NFT is transferred to someone else, the rewards are transferred too. So whoever is holding the asset at the time PoX rewards are issued will receive the payout.

Yield-bearing NFTs. This unlocks new possibilities for real world applications, and developers can take this concept to build novel NFT use cases. Pretty cool if you ask me.

Where Do Developers Get Started?

The Stacks Foundation has a number of programs for developers to get up to speed on Clarity through Clarity Universe, which includes the following components.:

  • Clarity Camp: a 6-week educational course to learn Clarity with access to experts and leaders in the Stacks ecosystem.
  • Clarity Starters: a library of ready-to-use templates and smart contracts
  • Clarity Talent: a marketplace of Clarity-related jobs
  • Clarity Lab: a new incubator that aims to push the boundaries of what’s possible in Clarity, exploring a range of cutting-edge topics like DAOs, semi-fungible tokens, signed messages, native-wrapped BTC and more.

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

One of our most popular tools is Clarinet, which is the go-to tool for local smart contract development and lets developers easily test and debug their contracts. It comes with several powerful features, such as the check checker, which checks code for untrusted sources of data, as well as an inline debugger, which has a static analysis tool and allows you to step in and out of the code as you go through the debugging process.

These features are both in the CLI version of Clarinet. We plan to release the inline debugger to the VSCode version of Clarinet this quarter. 

The VSCode extension is more powerful than the CLI and populates error highlights. It comes with the typical ID plugin you’d see in other languages to help you in the development process.


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. Learn more about how Clarity compares to Solidity.

Ready to kickstart your Web3 development journey? Download our free guide to developing smart contracts.

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

Related stories