Back to all stories
An Introduction to the Cairo Programming Language

The landscape of Ethereum Layer 2 scaling solution is rapidly evolving. Broadly speaking, Layer 2 solutions include two main types: optimistic rollups and ZK (Zero Knowledge) rollups.

Within ZK rollups, the two primary ZK proof systems are ZK-SNARK (which stands for Zero-Knowledge Succinct Non-Interactive Argument of Knowledge) and ZK-STARK (Zero-Knowledge Scalable Transparent Argument of Knowledge).

StarkNet is a general purpose ZK-Rollup built using the STARK proof system. It uses the Cairo programming language for both its infrastructure and its smart contracts.

In this article, we provide an overview of the Cairo language, including some of its unique features. Note that Cairo is a relatively new language and is rapidly evolving. This article is based on the current version of Cairo (0.10.0) and its features might change in the future.

An Introduction to the Cairo Programming Language

Starknet Architecture

It is helpful to have a general understanding of the architecture of Starknet before diving into the Cairo language. Exhibit 1 shows the main components of Starknet, its relationship with Ethereum, and a general transaction sequence. In this section we focus on the Sequencer, Prover, and Verifier which are indispensable in understanding how Starknet works.

image (2) Exhibit 1: Starknet Architecture

The Sequencer is responsible for ordering, validating and bundling transactions into blocks. Currently, the sequencer is run by Starkware in a centralized manner, but the company plans to decentralize the sequencer in the future.

The Prover and the Verifier work closely together. The Prover generates a cryptographic proof on the validity of the execution trace from the Sequencer. Currently, this job is performed by a single prover, the “Shared Prover" or “SHARP”. The Verifier is a smart contract on Ethereum L1 that verifies the proof generated by the Starknet Prover, and if successful, updates the state on Ethereum L1 for record keeping.

As such, other users can then query the state of the Starknet Core smart contract on Ethereum L1 and verify that a certain transaction on Starknet has been executed successfully. It is worth noting that certain Cairo instructions can only be seen by the Prover, and not the Verifier. These are called “hint” – which is a piece of Python code embedded in a Cairo program.

Such asymmetry between the Prover and the Verifier enables some zero-knowledge applications. For example, a user can prove that he has the solution to a cryptographic problem, without disclosing the solution from the perspective of the Verifier on the Ethereum base layer.

Cairo Overview

In this section, we provide an overview of the Cairo language, including its building blocks such as its data types and memory model, as well as some unique features such as builtins, implicit arguments, hint, and embedded test functions.

Cairo Programs and Cairo Contracts

In Starknet, there is a clear distinction between Cairo programs and Cairo contracts. Cairo programs are stateless. As an example, a Cairo program can perform a hash operation on a given input, and prove that the output matches a specific target output. This does not require any state variable to persist on Starknet.

On the other hand, Cairo contracts are stateful. With Cairo contracts, state variables persist on the blockchain, enabling applications such as ERC20 tokens, automated market makers, etc. on the Starknet L2.

Data Types

The primitive data type in Cairo is “felt”, which stands for “field element”. The felt is an integer in the range −P/2 < x<P/2 where P is a very large prime number (currently a 252-bit number). Cairo does not have built-in overflow protection on arithmetic operations using “felt”. When there is an overflow, and the appropriate multiple of P is added or subtracted to bring the result back into this range, or effectively modulo P. Using felt as a building block, Cairo supports other data types including tuples, structs, and arrays. As a low level programming language, Cairo also uses pointers extensively. The brackets [x] are used to return the value in memory location x, whereas the ampersand sign &x is used to return the memory address of variable x. In the example shown in Exhibit 2, an array is declared with memory allocation, and the pointer returned is used along with offsets to indicate the memory location of different elements in the array.

image (13) Exhibit 2: Arrays in Cairo

More complex data types such as hashmaps can be implemented as a function with the storage_var decorator, which allows read and write operations.

image (4) Exhibit 3: Hashmap in Cairo

Memory Model

Cairo has read-only non-deterministic memory, which means that the value in each memory cell can only be written once, and cannot change afterwards during a Cairo program execution. As such, depending on whether a value has been written to a memory location, the instruction that asserts [x] == 7 can mean either:

  1. Read the value from the memory location x and verify the value is 7, or
  2. Write the value 7 to memory cell x, if memory cell x hasn’t been written to yet

There are three “registers" used in Cairo for low level memory access, namely “ap”, “fp”, and “pc”:

  • ap: the allocation pointer, to show where unused memory starts
  • fp: the frame pointer that points to the current function
  • pc: the program counter that points to the current instruction

Using the definition above, an expression such as [ap] = [ap-1] * [fp] would take the value in the previous allocation pointer, multiply it by the value in the frame pointer, and write the result to the memory location of the current allocation pointer.

Cairo commonly uses recursion instead of for loops, due to its read-only memory feature. As an example, the function shown in Exhibit 4 uses recursion to calculate the n’th fibonacci number:

image (5) Exhibit 4: A Recursive Fibonacci Function

Built-Ins and Implicit Arguments

Similar to precompiled contracts in EVM, Cairo contains builtins which are optimized low-level execution units that perform predefined computations, such as hash functions, syscalls, and range-checks. Any function that uses the builtin is required to get the pointer to the builtin as an argument and return an updated pointer to the next unused instance. Since this pattern is so common, Cairo has created a syntactic sugar for it, called “Implicit arguments”. As shown in Exhibit 5 below, the curly braces declare hash_ptr0 as an “implicit argument”, allowing the function to call the predefined hash2() function. This automatically adds an argument and a return value to the function, so the programmer does not have to manually add them for every function that utilizes low-level execution units.

image (6) Exhibit 5: Built-Ins and Implicit Arguments


“Hint” is a unique feature in the Cairo language. A hint is a block of Python code that is executed by the Starknet Prover right before the next instruction. The hint can interact with a Cairo program’s variables / memory, allowing the programmer to utilize Python’s extensive functionalities in a Cairo program. In order to use this feature, the Python code needs to be surrounded by %{ and %}, as shown in Exhibit 6 below. Note that the Starknet Verifier does not see “hints” at all in a Cairo program execution, which allows a user to generate a proof without providing any secret information to the Verifier on the Ethereum base layer. Additionally, “hints” should not be used in Cairo contracts (only use in Cairo programs), unless the contract is whitelisted by Starknet.

image (7) Exhibit 6: Hint in Cairo

Test Functions

External functions with names that begin with test_ are interpreted as unit tests in Cairo. This allows programmers to integrate unit tests in Cairo directly, without having to write separate test files. As an example, Exhibit 7 shows a test function that verifies the result of a simple arithmetic operation.

image (8) Exhibit 7: Test Functions in Cairo

Writing Smart Contracts in Cairo

Writing smart contracts in Cairo requires familiarity with some of its basic design patterns. This section introduces a few common (non-exhaustive) patterns, and compares them with Solidity where applicable.

Library Import Instead of Contract Inheritance

The Cairo language does not support inheritance like Solidity does. In order to use the logic or storage variable from another Cairo contract, the programmer needs to import the other contract (often called a “library”), and use the contract’s namespace followed by the relevant function or state variables instead. The libraries define reusable logic and storage variables which can then be exposed by contracts. As an example, the ERC20 library in Exhibit 8 contains implementation of the transfer function but cannot be called directly (functions without any decorator are by default internal), and the ERC20 contract in Exhibit 9 exposes the transfer function by using the “ERC20” namespace followed by the function name, along with the external decorator.

image (9) Exhibit 8: transfer() Function in ERC20 Library

image (10) Exhibit 9: transfer() Function in ERC20 Contract

Access Control

The Cairo language does not support modifiers like Solidity does. In order to implement access control on privileged functions, the programmer needs to extract the caller (equivalent to the msg.sender in Solidity) of a contract via the built-in get_caller_address() function, and check if the caller has the necessary privilege. An example is the ownership check in the Ownable library, shown in Exhibit 10 below.

image (11) Exhibit 10: Access Control in Cairo

Upgradeable Contracts

Upgradeable contract is possible in Cairo, and it utilizes a proxy contract and an implementation contract, similar to the proxy pattern in Solidity. In Cairo, the proxy contract contains a __default__ function, as shown in Exhibit 11 below, similar to the fallback() function in Solidity. The implementation contract should import the “proxy” namespace and initialize the proxy, and include a mechanism for contract upgrade with proper access control, similar to the UUPS proxy pattern in Solidity. To deploy an upgradeable contract, one first needs to declare an implementation contract class and calculate its class hash. Then, the proxy contract can be deployed with the implementation contract’s class hash, and with inputs describing the call to initialize the proxy contract.

image (12) Exhibit 11: Proxy Contract default Function

Cairo Roadmap

The Cairo language is under active development. A major upgrade of the Cairo language (Cairo 1.0) is scheduled for early 2023, and Starkware has very recently open-sourced the first version of Cairo 1.0 compiler.

Cairo 1.0 introduces “Sierra”, a Safe Intermediate Representation between Cairo 1.0 and Cairo bytecode that proves every Cairo run. Additionally, Cairo 1.0 will contain simplified syntax and easier to use language constructs. For example, “for” loops will be possible in Cairo, and there will be support for boolean expressions. Native uint256 data type will be introduced, along with regular integer division, and overflow protection for relevant types.

Cairo 1.0 will also include improved type safety guarantee, and more intuitive libraries such as dictionaries and arrays. There are indeed many exciting features to look forward to in Cairo 1.0 that aim to alleviate some developer pain points of the current version.


We hope this article has provided a useful introduction to the Cairo language and some of its unique features. Each programming language potentially introduces new security vulnerabilities. In future articles, we plan to explore the security aspects of the Cairo programming language, and provide our recommendations on how to write secure code in Cairo.