> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/provablehq/leo/llms.txt
> Use this file to discover all available pages before exploring further.

# Standard Library

> Built-in functions and utilities available in Leo programs

## Overview

Leo provides a minimal standard library focused on zero-knowledge circuit operations. Most functionality is expressed through built-in operations and Aleo VM primitives.

## Built-in Functions

### Mapping Operations

Mapping operations are available in finalizer functions for interacting with on-chain storage.

#### Mapping::get

Retrieve a value from a mapping by key.

```leo theme={null}
mapping balances: address => u64;

final fn get_balance(user: address) {
    let balance: u64 = Mapping::get(balances, user);
}
```

<Warning>
  If the key doesn't exist, `Mapping::get` will cause the transaction to fail. Use `Mapping::get_or_use` for safe access.
</Warning>

#### Mapping::get\_or\_use

Retrieve a value from a mapping, or return a default if the key doesn't exist.

```leo theme={null}
final fn safe_get_balance(user: address) {
    let balance: u64 = Mapping::get_or_use(balances, user, 0u64);
}
```

**Parameters:**

* `mapping`: The mapping to query
* `key`: The key to look up
* `default`: The value to return if the key doesn't exist

#### Mapping::set

Store a value in a mapping.

```leo theme={null}
final fn update_balance(user: address, amount: u64) {
    Mapping::set(balances, user, amount);
}
```

**Properties:**

* Creates the key if it doesn't exist
* Overwrites the existing value if the key exists
* Changes are committed on-chain

#### Mapping::remove

Remove a key-value pair from a mapping.

```leo theme={null}
final fn delete_balance(user: address) {
    Mapping::remove(balances, user);
}
```

### Random Number Generation

The `ChaCha` namespace provides cryptographically secure randomness.

#### ChaCha::rand\_bool

Generate a random boolean value.

```leo theme={null}
final fn random_winner() {
    let is_winner: bool = ChaCha::rand_bool();
    assert(is_winner);
}
```

<Note>
  Random values are generated deterministically based on the transaction's randomness seed, ensuring reproducibility.
</Note>

#### ChaCha::rand\_u8 / rand\_u16 / rand\_u32 / rand\_u64 / rand\_u128

Generate random unsigned integers.

```leo theme={null}
final fn random_number() {
    let random: u32 = ChaCha::rand_u32();
}
```

#### ChaCha::rand\_i8 / rand\_i16 / rand\_i32 / rand\_i64 / rand\_i128

Generate random signed integers.

```leo theme={null}
final fn random_signed() {
    let random: i32 = ChaCha::rand_i32();
}
```

#### ChaCha::rand\_field

Generate a random field element.

```leo theme={null}
final fn random_field() {
    let random: field = ChaCha::rand_field();
}
```

#### ChaCha::rand\_scalar

Generate a random scalar value.

```leo theme={null}
final fn random_scalar() {
    let random: scalar = ChaCha::rand_scalar();
}
```

### Assertions

#### assert

Assert that a condition is true. If false, the program execution fails.

```leo theme={null}
fn validate_input(amount: u64) {
    assert(amount > 0u64);
    assert(amount <= 1000000u64);
}
```

**Use Cases:**

* Input validation
* Invariant checking
* Access control
* Boundary conditions

#### assert\_eq

Assert that two values are equal.

```leo theme={null}
fn test_equality(a: u32, b: u32) {
    assert_eq(a, b);
}
```

#### assert\_ne

Assert that two values are not equal.

```leo theme={null}
fn test_inequality(a: address, b: address) {
    assert_ne(a, b);
}
```

## Built-in Constants

### Group Constants

#### group::GEN

The generator point of the elliptic curve group.

```leo theme={null}
let generator: group = group::GEN;
```

## Operator Overloading

Leo supports standard operators for built-in types:

### Arithmetic Operators

```leo theme={null}
let a: u32 = 10u32;
let b: u32 = 3u32;

let sum: u32 = a + b;       // Addition
let diff: u32 = a - b;      // Subtraction
let prod: u32 = a * b;      // Multiplication
let quot: u32 = a / b;      // Division
let rem: u32 = a % b;       // Modulo
let pow: u32 = a ** b;      // Exponentiation
```

<Warning>
  Arithmetic operations can overflow. Leo uses safe arithmetic by default, causing the proof to fail on overflow.
</Warning>

### Comparison Operators

```leo theme={null}
let equal: bool = a == b;          // Equality
let not_equal: bool = a != b;      // Inequality
let less: bool = a < b;            // Less than
let less_eq: bool = a <= b;        // Less than or equal
let greater: bool = a > b;         // Greater than
let greater_eq: bool = a >= b;     // Greater than or equal
```

### Logical Operators

```leo theme={null}
let x: bool = true;
let y: bool = false;

let and: bool = x && y;    // Logical AND
let or: bool = x || y;     // Logical OR
let not: bool = !x;        // Logical NOT
```

### Bitwise Operators

```leo theme={null}
let a: u8 = 0b1010u8;
let b: u8 = 0b1100u8;

let and: u8 = a & b;       // Bitwise AND: 0b1000
let or: u8 = a | b;        // Bitwise OR: 0b1110
let xor: u8 = a ^ b;       // Bitwise XOR: 0b0110
let shl: u8 = a << 1u8;    // Shift left: 0b10100
let shr: u8 = a >> 1u8;    // Shift right: 0b0101
```

## Context Variables

### self.caller

The address of the account that invoked the current function.

```leo theme={null}
fn get_caller() -> address {
    return self.caller;
}
```

**Use Cases:**

* Authorization checks
* Tracking function invokers
* Access control

### self.signer

The address of the account that signed the transaction.

```leo theme={null}
fn get_signer() -> address {
    return self.signer;
}
```

### block.height (Finalizers Only)

The current block height, available only in finalizer functions.

```leo theme={null}
final fn check_expiration() {
    assert(block.height <= 1000u32);
}
```

**Use Cases:**

* Time-based logic
* Expiration checks
* Epoch-based features

## Type Conversion

### as Operator

Explicitly cast between compatible types.

```leo theme={null}
let small: u8 = 42u8;
let medium: u32 = small as u32;
let large: u64 = medium as u64;
let field_val: field = large as field;
```

**Supported Conversions:**

* Integer to integer (any size)
* Integer to field
* Integer to scalar
* Field to integer (with potential loss)

## No Standard Library Imports

Unlike many languages, Leo does not require importing standard library functions. All built-in functions are available in the global namespace.

```leo theme={null}
// No imports needed
fn example() {
    assert(true);
    let rand: bool = ChaCha::rand_bool();
}
```

## Limitations

<Warning>
  The following features are NOT available in Leo's standard library:

  * File I/O operations
  * Network operations
  * Dynamic memory allocation
  * Floating-point arithmetic
  * String manipulation (beyond literals)
  * Date/time functions (use `block.height` instead)
  * External library imports
</Warning>

## Future Additions

The Leo standard library is intentionally minimal. Future versions may include:

* Hash functions (Poseidon, SHA-256, etc.)
* Signature verification utilities
* Merkle tree operations
* Additional cryptographic primitives

## Related Resources

<CardGroup cols={2}>
  <Card title="Built-in Types" icon="shapes" href="/reference/built-in-types">
    Complete type reference
  </Card>

  <Card title="Examples" icon="code" href="/examples/overview">
    See standard library in use
  </Card>
</CardGroup>