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);}
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! 𓅃
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.
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.
