Introduction to the Corelib documentation

What is the Corelib?

The Cairo core library, also known as Corelib, provides the foundational building blocks for writing provable programs in Cairo. It offers essential utilities, data structures, mathematical functions, cryptographic tools, and system interactions making it suitable for both onchain and offchain development. Whether you are working on Starknet smart contracts, cryptographic applications, or general-purpose Cairo programs, the corelib provides the fundamental tools needed. The corelib is available to all Cairo packages by default, meaning its features are available by simply importing specific modules into your program as follows:

use core::array::Array;

fn main() {
    let mut arr = Array::new();
    arr.append(42);
}

How to use this documentation?

This documentation serves as a comprehensive reference for all components of the Corelib. It organizes functionality into modules, constants, functions, types, and traits, allowing developers to explore and understand available features efficiently. It is based on the auto-generated documentation of the corelib’s codebase using Scarb, so if you find a bug, have a feature request, or want to improve the documentation, simply report an issue or submit a pull request on either Cairo’s or Scarb’s GitHub repositories. If you already know what you are looking for, the fastest way to find it is to use the search bar at the top of the page. Otherwise, you can take a quick tour of the documentation and start clicking on anything the seems interesting. If this is your first time, we recommend starting with browsing the library’s modules and experimenting with their functionality in your Cairo programs. Happy coding! 𓅃

A quick tour of the documentation

Modules


core::traits	Core traits for various operations. This module provides a collection of essential traits that define common behavior patterns for Cairo types.
core::boolean	Boolean operations. The `bool` type is a primitive type in Cairo representing a boolean value that can be either `true` or `false`.
core::circuit	Efficient modular arithmetic computations using arithmetic circuits. This module provides a type-safe way to perform modular arithmetic operations using arithmetic circuits.
core::blake	—
core::box	`Box` is a smart pointer that allows for heap allocation.
core::nullable	A wrapper type for handling optional values. `Nullable` is a wrapper type that can either contain a value stored in a `Box` or be null.
core::array	A contiguous collection of elements of the same type in memory, written `Array`. Arrays have O(1) indexing, O(1) push and O(1) pop (from the front).
core::dict	A dictionary-like data structure that maps `felt252` keys to values of any type. The `Felt252Dict` provides efficient key-value storage with operations for inserting, retrieving, and updating values.
core::result	Error handling with the `Result` type. `Result` is the type used for returning and propagating errors. It is an enum with the variants, `Ok(T)`, representing success and containing a value, and `Err(E)`, representing error and containing an error value.
core::option	Optional values. The `Option` type represents an optional value: every `Option` is either `Some` and contains a value, or `None`, and does not.
core::clone	The `Clone` trait provides the ability to duplicate instances of types that cannot be ‘implicitly copied’. In Cairo, some simple types are “implicitly copyable”: when you assign them or pass them as arguments, the receiver will get a copy, leaving the original value in place.
core::ec	Functions and constructs related to elliptic curve operations on the STARK curve. This module provides implementations for various elliptic curve operations tailored for the STARK curve.
core::ecdsa	Elliptic Curve Digital Signature Algorithm (ECDSA) for the STARK curve. This module provides implementations for ECDSA signature verification and public key recovery.
core::integer	Integer types and operations. This module provides the built-in integer types and their associated operations.
core::cmp	Utilities for comparing and ordering values. This module contains functions that rely on the `PartialOrd` trait for comparing values.
core::gas	Utilities for handling gas in Cairo code.
core::math	Mathematical operations and utilities. Provides extended GCD, modular inverse, and modular arithmetic operations.
core::num	—
core::ops	Overloadable operators. Implementing these traits allows you to overload certain operators. Note: Other overloadable operators are also defined in the `core::traits` module.
core::panics	Core panic mechanism. This module provides the core panic functionality used for error handling in Cairo. It defines the basic types and functions used to trigger and manage panics, which are used when an unrecoverable error is encountered.
core::hash	Generic hashing support. This module provides a hash state abstraction that can be updated with values and finalized to produce a hash digest.
core::keccak	Keccak-256 cryptographic hash function implementation.
core::pedersen	Pedersen hash related traits implementations. This module provides an implementation of the Pedersen hash function, which is a collision-resistant cryptographic hash function. The `HashState` allows for efficient computation of Pedersen hashes.
core::qm31	Definition for the `qm31` type. Only available for local proofs. The implementations defined in this module can be accessed by using the traits directly.
core::serde	Serialization and deserialization of data structures. This module provides traits and implementations for converting Cairo types into a sequence of `felt252` values and back.
core::sha256	Implementation of the SHA-256 cryptographic hash function. This module provides functions to compute SHA-256 hashes of data. The input data can be an array of 32-bit words, or a `ByteArray`.
core::poseidon	Poseidon hash related traits implementations and functions. This module provides cryptographic hash functions based on the Poseidon permutation.
core::debug	Utilities related to printing of values at runtime. The recommended way of printing values is by using the `Display` and `Debug` traits available in the `fmt` module.
core::fmt	Functionality for formatting values. The main components of this module are the formatting traits and the `Formatter` struct.
core::starknet	Functionalities for interacting with the Starknet network.
core::internal	—
core::zeroable	Types and traits for handling non-zero values and zero checking operations. This module provides the `NonZero` wrapper type which guarantees that a value is never zero.
core::bytes_31	Definitions and utilities for the `bytes31` type. The `bytes31` type is a compact, indexable 31-byte type.
core::byte_array	`ByteArray` is designed to handle large sequences of bytes with operations like appending, concatenation, and accessing individual bytes. It uses a structure that combines an `Array` of `bytes31` chunks with a pending word for efficient storage.
core::string	—
core::iter	Composable external iteration. If you’ve found yourself with a collection of some kind, and needed to perform an operation on the elements of said collection, you’ll quickly run into ‘iterators’.
core::metaprogramming	Metaprogramming utilities.
core::testing	Measurement of gas consumption for testing purpose. This module provides the `get_available_gas` function, useful for asserting the amount of gas consumed by a particular operation or function call.
core::to_byte_array	ASCII representation of numeric types for `ByteArray` manipulation. This module enables conversion of numeric values into their ASCII string representation, which can then be used to build `ByteArray` instances.

Miscellaneous


core::panic_with_felt252	Panics with the given `felt252` as error message.
core::panic_with_const_felt252	Panics with the given const argument `felt252` as error message.
core::assert	Panics if `cond` is false with the given `felt252` as error message.
core::bool	`bool` enum representing either `false` or `true`.
core::never	—
core::usize	`usize` is an alias for `u32` type.
core::RangeCheck	General purpose implicits.
core::SegmentArena	—
core::felt252	`felt252` is the basic field element used in Cairo. It corresponds to an integer in the range 0 ≤ x < P where P is a very large prime number currently equal to 2^251 + 17⋅2^192 + 1.
core::felt252_div	Performs division on `felt252` values in Cairo’s finite field. Unlike regular integer division, `felt252` division returns a field element n that satisfies the equation a = b * n, where a is the dividend and b is the divisor.

​What is the Corelib?

​How to use this documentation?

​A quick tour of the documentation

​Modules

​Miscellaneous

What is the Corelib?

How to use this documentation?

A quick tour of the documentation

Modules

Miscellaneous