Skip to content
Home » Blockchain » Full Guide to Clarity | Smart Contract Programming Language

Full Guide to Clarity | Smart Contract Programming Language

clarity lang blockchain programming logo

If you are confused about the Clarity programming language, what layer it fits and how it came into being, you’ve found the right resource. In this blog you’ll be introduced to just that along with the history of Clarity. Additionally, we will discuss the language’s design, its characteristics, and how it, together with Stacks, managed to challenge the Ethereum blockchain.

Let’s start, shall we?

Introduction to Clarity

First things first, Clarity is a smart contract programming language. It is designed for the Stacks blockchain which is integrated as a layer solution into the Bitcoin blockchain.

Clarity was introduced by Blockstack, a decentralized identity system, which is talked about later in the blog. It is currently being developed by Blockstack and Algorand, both of which will have projects including Clarity Virtual Machines (VMs)

The Clarity programming language’s primary purpose is to make it easier for developers to write secure smart contracts. Its most important feature has to be that it does not have room for reentrancy attacks in smart contracts.

On the contrary, Solidity contracts on Ethereum face re-entrancy attacks which make it a critical vulnerability capable of rendering great losses to the blockchain.

What is the Stacks blockchain?

As mentioned earlier on, Stacks is a Bitcoin layer for smart contracts and dApps. It enables projects built atop it to use Bitcoin as an asset and settle transactions on its blockchain.

Despite being the blockchain pioneer, Bitcoin was way behind in providing any resources and functionalities to create NFTs and build dApps. By ‘way behind’ we mean there were no such activities taking place over Bitcoin. This was partly because of its known design limitations. Bitcoin, as a renowned blockchain, also did not find it feasible to go through a hard fork or consider flippening. This paved the way for Ethereum to get ahead in the game by offering building functionalities.

But Stacks changed it for Bitcoin. It enabled the creation of smart contracts and dApps on the blockchain by becoming a hybrid layer solution of sorts.

stacks github image
Source: Stacks Github

Stacks follows a proof-of-transfer (PoX) consensus mechanism which leverages the security of the proof-of-work (PoW) consensus mechanism of the Bitcoin blockchain. Some Bitcoin functions that the Stacks blockchain shares are hash rate, immutability, and limited token size (there can only be 1 billion STX compared to 21 million BTC).

While these are some essential factors of the Stacks blockchain, what makes it even more interesting is its overall desirability and versatility when competing with a blockchain like Ethereum.

So how was Stacks able to create a space in a market that Ethereum had a monopoly over? To understand this, we will have to go back in time.


The history of the Stacks blockchain goes back to 2013 when two co-founders, Muneeb Ali, and Ryan Shea, co-founded Blockstack (formerly known as Onename). Blockckstack is a decentralized computing platform that enables users to control their identity and data and that’s where the Stacks blockchain gets its name from. In the following years, Blockstack gained prominence and raised a total of $52.3 million, supported largely by the Gaia protocol.

hiro web3 tools company linkedin cover
Source: Hiro/Linkedin

Stacks was launched in 2017 to enable the creation and deployment of dApps on the Bitcoin blockchain via PoX. Its native currency was named STX. In 2020, Blockstack got rebranded as Hiro and in 2021 we saw the launch of Stacks 2.0 with more robust and diverse features and functionalities.

Ethereum’s DAO mistake

Now, in order to understand why the Stacks and Bitcoin duo makes such a good competitor to Ethereum, we will have to again go back to the year 2016-17. This is the year when Ethereum introduced a new DAO (decentralized autonomous organization) called “The DAO” which immediately gained immense popularity and caught everyone’s eye.

The DAO from the very beginning had foundational vulnerabilities. And shortly after, attackers were able to exploit those shortcomings through the smart contract. As a result, Ethereum suffered losses of over USD 60 million.

The hack was a big blow to the Ethereum ecosystem. It was now facing challenges on both the security and financial fronts because it failed to separate the both. Due to this the blockchain went through a hard fork, leading a division into Ethereum Classic and Ethereum, two different blockchains.

On the other hand, Bitcoin, instead of repeating Ethereum’s mistakes, saw an opportunity in the Stacks blockchain. Stacks was integrated into Bitcoin to perform functions like writing smart contracts, creating dApps and minting tokens like ERC-20, hence the money and the programming layers both got separated.

By doing so, Bitcoin funds remain on the Bitcoin chain but all of its complexity and smart contract functionality are handled differently on a different chain i.e. Stacks.

Had Ethereum bifurcated its role as the main chain and delegated the programming complexity to its Layer-2 solutions, perhaps you would not have been reading about “The DAO” hack. Sadly, Ethereum did not have well-defined roles for its main and L2 chains. This wreaked havoc.

Ethereum vs Bitcoin + Stacks (BitStacks)?

There is no doubt in the fact that while it been around since 2017, the Stacks blockchain had always been waiting for the perfect moment. It is as if it knew that it will have its time sooner or later.

The fact that maximalist Muneeb Ali betted on Stacks gives us a glimpse of the foreseeable future – a future where the Bitcoin-Stacks duo reigns. In fact, in May 2022 when ETH plunged to 13% and Bitcoin holders remained unfazed, Ethereum founder Vitalik Buterin tweeted this:

While we don’t know the inside story, this tweet from Buterin, in which he categorically mentions that he “desires” to see Ethereum become more Bitcoin-like, shows that the Bitcoin-Stacks duo has overcome the challenges. In fact, it is soon going to be Bitcoin’s world and we are probably just going to living in it.

Moreover, with the Clarity programming language by their side to provide security, efficiency and scalability, the marriage between Bitcoin and Stacks knows no bounds. Clarity’s overall position also makes it more desirable. It has positioned itself in a way that it sells itself as a protection from reentrancy attacks, something that cost Ethereum a hard fork. Solidity, Ethereum’s native language, has still not been able to provide a substantive solution to this problem.

Why does the Stacks blockchain have its own language?

As mentioned, Solidity contracts have bugs and can be more prone to attacks. In fact, hunting for smart contracts bugs or bounty hunting happens to be quite a lucrative and in-demand web3 job as well.

When blockchain developers were working on Stacks, they realized that there is a need for a separate smart contract language for it. It was called Clarity. The programming language is not only a one-stop solution to all the problems being faced by other smart contract languages, it is also an optimized one. By that, we mean it is specially prepped for the vulnerabilities of smart contracts we have seen exposed in the past.

Design and structure of the Clarity programming language

Clarity has some essential features that also make up its base design. For example, its basic parts are data spaces and functions. A List Processing Language (LISP), Clarity’s syntax has quite some parentheses, symbols, phrases, and values. People may be intimidated by the syntax first. However, once you familiarize yourself with it, your intimidation decreases.

The structure of the Clarity programming language is such that its basic building blocks are atoms and lists. Atoms are numbers or strings of contagious characters. Lists, on the other hand, are atoms enclosed with parentheses ().

Data typesClarity supports a variety of data types, including integers, floats, strings, and Booleans. Integers can be used to store whole numbers, floats can be used to store decimal numbers, strings can be used to store text, and Booleans can be used to store values of true or false.
VariablesVariables can be declared using the var keyword. The var keyword is followed by the name of the variable and the data type of the variable.
FunctionsFunctions are used to encapsulate code and can be called from other parts of the program. Functions are declared using the function keyword. The function keyword is followed by the name of the function, the data types of the arguments, and the data type of the return value.
Control flowClarity supports a variety of control flow statements, such as if, else, while, and for. The if statement is used to execute code if a condition is met. The else statement is used to execute code if the condition in the if statement is not met. The while statement is used to execute code repeatedly while a condition is met. The for statement is used to execute code a specific number of times.
OperatorsClarity supports a variety of operators, such as arithmetic operators, logical operators, and comparison operators. Arithmetic operators are used to perform mathematical operations, such as addition, subtraction, multiplication, and division. Logical operators are used to combine Boolean values, such as and, or, and not. Comparison operators are used to compare values, such as greater than, less than, and equal to.
CommentsComments can be used to explain the code and are not executed by the compiler. Comments are enclosed in // symbols.
Error handlingClarity supports error handling using the try and catch statements. The try statement is used to execute code that may throw an error. The catch statement is used to handle errors that are thrown by the try statement.
LibrariesClarity has a number of built-in libraries that can be used to perform common tasks, such as working with data, storing data, and interacting with the blockchain. The data library can be used to work with data, the storage library can be used to store data, and the blockchain library can be used to interact with the blockchain.

More details about the design of the language are attainable via the Clarity book.

How is Clarity different from other smart contract languages?

A plethora of reasons make Clarity different from the others, but we’re going to graze over the top ones and mention them.

1. Programmatic control over digital assets

This means that developers can use Clarity to create smart contracts that can manage digital assets in a variety of ways. For example, Clarity can be used to create smart contracts that can:

  • Create new digital assets
  • Transfer digital assets between users
  • Burn digital assets
  • Revoke access to digital assets

Clarity’s support for programmatic control over digital assets makes it a powerful tool for developers who want to create decentralized applications that can manage digital assets.

2. Statically typed

The other reason is that since it involves static analysis, coding with Clarity is an absolute joy. This means that the types of variables and expressions are known when it’s time to compile. Because a blockchain developer will automatically learn about the potential bugs within their code in Clarity, they would not need external help, time, or resources to do the debugging for them.

Other smart contract languages, such as Solidity, are dynamically typed languages, which means that the types of variables and expressions are not known at compile time. This can make it more difficult to find errors in code and can also lead to performance problems.

3. Clear syntax

The language also happens to have a clear and exceptional syntax (albeit riddled with parentheses and symbols which one generally gets a hang of) which yet again makes it different from other smart contract languages.

For example, Clarity’s keywords are short and easy to remember, such as contractfunction, and data. Solidity’s keywords are longer and sometimes cryptic, such as pragmalibrary, and event. Moreover, operators in Clarity are simple and straightforward, such as +-, and *. Solidity’s operators can be complex and difficult to remember, such as &&||, and ?:.

4. Run-time costs and data usage

Finally, Clarity hits the nail on the head by easing the determination of run-time costs and data usage. Not many languages like Solidity and Vyper allow for that.

  • Cost annotation: Clarity allows developers to annotate their code with cost annotations, which specify the estimated run-time costs of specific operations. This information can be used to get a more accurate estimates.
  • Cost analysis tools: There are a number of cost analysis tools available for Clarity, which can be used to estimate the run-time costs and data usage of smart contracts. These tools can be used to help developers optimize their smart contracts for performance and cost efficiency.

In contrast, both Solidity and Vyper are dynamically typed languages, which makes it more difficult to estimate the run-time costs of smart contracts written in them. Additionally, they also do not have cost annotations or cost analysis tools, which makes it even more difficult to determine the run-time costs and data usage of contracts.

Clarity tools, libraries and frameworks that you can use

The Clarity programming language has a number of tools, libraries and frameworks that developers can use to code more efficiently.


In programming, tools help you provide an environment, help you streamline your instructions, and test and implement the program. Here are some tools that you can use while coding in Clarity.

1. Clarity Compiler

This is the official compiler for the Clarity programming language. It can be used to compile Clarity code into native code or JavaScript.

2. Clarity IDE:

This is an integrated development environment (IDE) for the Clarity programming language. It provides features such as syntax highlighting, code completion, and debugging.

3. Clarity REPL

This is a Read-Eval-Print Loop (REPL) for the Clarity programming language. It allows you to interactively enter and execute Clarity code.


In programming, libraries greatly help to optimize a developer’ coding. Libraries have pre-written codes that developers can put into use. Here are some Clarity libraries:

1. Clarity Standard Library

This is the standard library for the Clarity programming language. It provides a number of classes and functions that are commonly used in Clarity code.

2. Clarity JSON Library

This library provides support for working with JSON data in Clarity code.

3. Clarity WebSocket Library

This library provides support for working with WebSockets in Clarity code.


The role of frameworks is to essentially assist in the development of, say, a token or a smart contract. Here are some Clarity frameworks that you can use:

1. Clarity MVC Framework

The Clarity MVC framework provides a way to organize Clarity code into MVC components.

2. Clarity Web Application Framework

The Clarity Web Application Framework provides a way to create web applications using Clarity code.

3. Clarity RESTful API Framework

This framework provides a way to create RESTful APIs using Clarity code.

How to write a simple smart contract in Clarity

Here are the three simple steps that you can use to write a simple smart contract in Clarity:

  1. Create a new Clarity file. You can use any text editor to create a new Clarity file. The file extension for Clarity files is .clar.
  2. Write your smart contract code.
  3. Compile your smart contract. Once you have written your smart contract code, you need to compile it into bytecode. The Clarity compiler can be used to compile Clarity code into bytecode. Once your smart contract has been compiled, you can deploy it to the Clarity network.

Here is an example of a simple smart contract that increments a counter by 1 every time it is called:

contract Counter {

// This is the constructor function.
constructor() {

// Initialize the counter to 0.
this.counter = 0;


// This is a function that can be called by other contracts.
function increment() {

// Increment the counter by 1.
this.counter = this.counter + 1;



Benefits of Clarity

Apart from Clarity’s no-reentrancy rule, there are a bunch of characteristics that are pretty cool and have been incorporated to make it a safe, secure, and fast language. They are as follows:

1. Turing-Incomplete

Clarity is a Turing-Incomplete language. In easy words, a Turing-complete blockchain language is one that can do everything that a Turing machine can do. A Turing machine is a theoretical concept that has certain conditions such as infinite RAM, programming that dictates under what conditions it must terminate, etc.

Turing-Incomplete means that a language does not allow for the aforementioned things. For a Turing-Incomplete language like Clarityit is known what a program can do without having to actually execute it.

In Solidity which is a Turing complete language, you can’t be sure, say, how much gas you would need when a contract is going to be used. So, room for pre-analysis in a Turing-Complete language is little to none.

2. Decidable

If Clarity is not Turing-Complete, what exactly is it? Clarity is a decidable language. Decidability hints at the fact that you know what is coming and that you have done clear forecasting.You know exactly where your code will crash once you have run it. Clarity also has the ability of static analysis (successful examination of the source code without running it).

Moreover, the language does not perform unbounded loops. Looping is only performed via map, filter, and fold. Lastly, decidability reduces debugging to a great extent because a developer can pinpoint the possible bugs while statically analyzing the code and remove them accordingly.

3. Interpreted

Similar to Python, which too is used in blockchain development, Clarity is an interpreted language. This means that a code is not compiled before it is run unlike the case with a language like Solidity.

And what does compilation mean in layman’s language? In compilation, a human-readable code is converted into a machine-readable code. When it is converted into machine-readable code, debugging becomes a little tricky. However, it is not like that with the Clarity programming language. In Clarity, you get what you see and that sets it apart.

Interpreted languages have a multitude of benefits. They tend to be more flexible. Moreover, the interpreters in an interpreted language execute the source code themselves. This makes the code platform independent.

Demerits of Clarity

While the benefits and strong characteristics of the Clarity programming language have already been discussed, it is important to touch upon some of the demerits of the language.

1. No action without commands

This particular aspect of Clarity can be both a benefit and a drawback. It’s a benefit because it won’t perform any functions unless you call for it. But it can be considered a drawback because it requires absolute precision. The coders and developers must spell out their commands for the programming language to perform a function.

2. Post-condition

In post-condition, Clarity won’t let you run a code unless you fix the bugs from it. This can be a problem if you want the bugs in the code to use as a tutorial for teaching or learning purposes.

3. Default permissions

Since Clarity is a different programming language altogether, it can take one time to adjust to its workings after switching from a language like Solidity. In a language like Solidity, the functions are usually public and any external contract can call them.

In Clarity, however, one has to decide what functions will be public because all are private by default. No external contract can call into a Clarity contract and this can be a challenge when the external contract is trustworthy.

How does Clarity help blockchain developers?

To reiterate, Clarity makes the creation of complex smart contracts an easy and achievable process. Not that other languages don’t do that. But realistically speaking, it provides a much cheaper, faster, and more diverse alternative to languages like Move and Solidity.

An independent blockchain developer can easily use an open-source language like Clarity to build dApps. There are no exogenous costs involved in Clarity. You pay for the resources that you use and the transactions that you make.

More importantly, with Clarity, you will know exactly how much time you’ll have to put into creating a smart contract and how much amount you want to utilize in carrying out a transaction. That hasn’t been the case before with other languages, right? It’s refreshing. So we can say Clarity helps blockchain developers by providing an easy to work with environment.

To conclude

The Clarity programming language is a great option to write smart contracts on Stacks. Its characteristics like Turing-Incompleteness, decidability, interpretability, and robust security measures make it an ideal language to develop decentralized products with.

By being a statically-typed language, Clarity makes great use of forecasting and analysis which helps developers speed up their development process. Lastly, the Clarity programming language does not put barriers in the way of those who are only starting out due to its open-source nature. All of this makes it a language opting for.


What is the the native token of the Stacks blockchain?

The native token of the Stacks blockchain is STX.

Is Stacks a Layer 1 or a Layer 2 blockchain?

Stacks is neither a Layer 1 nor a Layer 2 blockchain. It shares the characteristics of both layers. Founder Muneeb Ali says that Stacks follows a Layer 1.5 model.