Operations

Documentation Index

Fetch the complete documentation index at: https://docs.arcium.com/llms.txt

Use this file to discover all available pages before exploring further.

​

Quick Summary

​

Table of contents

• Expression support
  • Binary expressions
  • Casts
  • Literals
  • Methods
  • Paths
• Item support
• Pattern support

​

Expression support

​

Binary expressions

​

Cast expressions

​

Function calls

• user-defined function calls (without recursion)
• ArcisRNG::bool() to generate a boolean.
• ArcisRNG::gen_uniform::<T>() to generate a uniform value of type T (bool, integer, or combination). Requires explicit type parameter.
• ArcisRNG::gen_integer_from_width(width: usize) -> u128. Generates a secret integer between 0 and 2^width - 1 included.
• ArcisRNG::gen_public_integer_from_width(width: usize) -> u128. Generates a public integer between 0 and 2^width - 1 included.
• ArcisRNG::gen_integer_in_range(min: u128, max: u128, n_attempts: usize) -> (u128, bool). Generates a random integer in [min, max] using rejection sampling. n_attempts must be compile-time known. Returns (result, success) where success=false indicates all attempts were rejected. With n_attempts=24, failure probability is <2^-24.
• ArcisRNG::shuffle(slice) on slices. Complexity is in O(n*log³(n) + n*log²(n)*sizeof(T)).
• Mxe::get() to be able to create MXE-owned secret data.
• Shared::new(arcis_public_key) to share private data with arcis_public_key.
• ArcisX25519Pubkey::from_base58(base58_byte_string) to create a public key from a base58-encoded address.
• ArcisX25519Pubkey::from_uint8(u8_byte_slice) to create a public key from a Uint8 array.
• SolanaPublicKey::from_serialized(value) to create a Solana public key from serialized form.
• SolanaPublicKey::from_base58(byte_string) to create a Solana public key from base58.
• ArcisMath::sigmoid(x) for the sigmoid activation function.
• LogisticRegression::new(coef, intercept) for logistic regression models.
• LinearRegression::new(coef, intercept) for linear regression models.
• Pack::new(value) to bit-pack data for onchain storage (multiple small values fit into fewer field elements).
• ArcisX25519Pubkey::new_from_x(x: BaseField25519) to create a public key from its Curve25519 Montgomery X-coordinate.
• ArcisX25519Pubkey::to_x() -> BaseField25519 to extract the Montgomery X-coordinate from a public key.
• BaseField25519::from_u8(x) … BaseField25519::from_u128(x) to convert unsigned integers to field elements. Signed variants (from_i8 … from_i128) and from_bool, from_usize, from_isize also available.
• BaseField25519::power_of_two(exp) to compute 2^exp as a field element.

​

Literal expressions

​

Macros

• debug_assert!, debug_assert_ne!, debug_assert_eq! to assert conditions during debugging. They do not change instruction behavior.
• eprint!, eprintln!, print!, println! to print debug output. They do not change instruction behavior.
• arcis_static_panic!(message) to fail compilation when the branch is reached. Useful for enforcing constraints that must be known before circuit generation.
• include_bytes!("file_path") to include raw bytes from a file in Arcis circuits.
• include!("file_path") to include a file in item position (not expression position).
• assert_current_module!(crate::path::to::module) to enable crate:: absolute paths within the current module. Place at the top of any module that needs to reference items via absolute paths.
• encrypted_mod!("path/to/module.rs") or encrypted_mod!("path/to/module.rs", alias_name) to use another file as a module within an #[encrypted] module. The target file must use the #[encrypted_library] attribute. Items are accessible via the filename stem (or alias) as a namespace, e.g., module_name::ITEM.

const ARRAY_LEN: usize = 3; // Change to 1 and the example will not compile.

fn second_element(arr: &[u8]) -> u8 {
    if arr.len() < 2 {
        arcis_static_panic!("Array must have at least 2 elements");
    }
    arr[1]
}

#[instruction]
fn reveal_second_element(input: Enc<Shared, Pack<[u8; ARRAY_LEN]>>) -> u8 {
    let array = input.to_arcis().unpack();
    second_element(&array).reveal()
}

​

Method calls

• user-defined method calls (with generics but without recursion)
• .clone() on all Clone objects.
• .len(), .is_empty(), .swap(a, b), .fill(value), .reverse(), .iter(), .iter_mut(), .into_iter(), .windows(width), .copy_from_slice(src), .clone_from_slice(src), .split_at(mid), .split_at_mut(mid), .rotate_left(mid), .rotate_right(mid), .contains(item), .starts_with(needle), .ends_with(needle) on arrays and slices.
• .sort() on arrays of integers. Complexity is in O(n*log²(n)*bit_size).
• .enumerate(), .chain(other), .cloned(), .copied(), .count(), .rev(), .zip(other), .map(func), .for_each(func), .fold(init, func), .sum(), .product() on iterators.
• .take(n), .skip(n), .step_by(n) on iterators when n is compile-time known.
• .reveal() if not inside an if or else block where the condition is not a compile-time constant
• .to_arcis() on Encs
• .from_arcis(x) on Owners (objects of types Mxe or Shared) if not inside an if or else block where the condition is not a compile-time constant
• .abs(), .min(x), .max(x) on integers and floats
• .abs_diff(other), .is_positive(), .is_negative(), .div_ceil(other) on integers
• .to_le_bytes(), .to_be_bytes() on typed integers (does not work on integers whose type the interpreter does not know)
• .exp(), .exp2(), .ln(), .log2(), .sqrt() on floats.
• .unpack() on Pack<T> to extract the original value from packed storage.
• .to_arcis_with_pubkey_and_nonce(pubkey, nonce) on EncData<T> to decrypt when the key is shared across inputs (avoids duplicate decryption gates). See EncData for details.
• .data on Enc<Owner, T> to extract only the EncData<T> ciphertext for smaller callback payloads.
• .safe_inverse() on BaseField25519 to get the field inverse (returns 0 for inverse of 0).
• .field_division(divisor) on BaseField25519 for field division (returns 0 for division by 0).
• .euclidean_division(divisor) on BaseField25519 for signed Euclidean division (panics on division by 0).
• .to_u8_unchecked() … .to_u128_unchecked() on BaseField25519 to extract as unsigned int. Silently produces incorrect results if value exceeds target range. Signed variants (to_i8_unchecked … to_i128_unchecked) and to_bool_unchecked also available.

​

Paths

• IntType::BITS, IntType::MIN and IntType::MAX where IntType is an integer type.
• Paths to user-defined constants, functions and structs, as long as they are inside the #[encrypted] area. Both super:: paths and crate:: paths (when assert_current_module! is declared) are supported.
• std::mem::replace and std::mem::swap
• Box::leak, Box::new, Cell::new, Cell::from_mut

​

Code Organization with Modules

use arcis::*;

#[encrypted]
mod my_mxe {
    use arcis::*;
    assert_current_module!(crate::my_mxe);

    const THRESHOLD: u64 = 1000;

    // No assert_current_module! needed — this module only uses super::, not crate::
    mod validation {
        use arcis::*;

        pub fn is_above_threshold(val: u64) -> bool {
            val > super::THRESHOLD  // Access parent constant via super::
        }
    }

    mod processing {
        use arcis::*;
        assert_current_module!(crate::my_mxe::processing);

        // #[instruction] works in nested modules
        #[instruction]
        pub fn process(vals: [u64; 3]) -> [u64; 3] {
            let mut result = [0u64; 3];
            for i in 0..3 {
                // Use crate:: to reference a sibling module's function
                let valid = crate::my_mxe::validation::is_above_threshold(vals[i]);
                result[i] = if valid { vals[i] * 2 } else { vals[i] };
            }
            result
        }
    }
}

// encrypted-ixs/src/lib.rs
use arcis::*;

#[encrypted]
mod my_mxe {
    use arcis::*;

    encrypted_mod!("helpers.rs");

    type Config = helpers::Config;

    #[instruction]
    fn compute(cfg: Config) -> u64 {
        cfg.value * helpers::MULTIPLIER
    }
}

// encrypted-ixs/src/helpers.rs
use arcis::*;

#[encrypted_library]
mod arcis_library {
    pub const MULTIPLIER: u64 = 42;

    pub struct Config {
        pub value: u64,
    }
}

​

Item support

​

Pattern support

• simple idents: let ident = ...;
• mutable idents: let mut ident = ...;
• ref idents: let ref ident = ...;
• mutable ref idents: let ref mut ident = ...;
• parentheses around a supported pattern: let (...) = ...;
• reference of a supported pattern: let &... = ...;
• array of supported patterns: let [...] = ...;
• struct of supported patterns: let MyStruct { ... } = ...;
• tuple of supported patterns: let (...) = ...;
• tuple struct of supported patterns: let MyStruct(...) = ...;
• type pattern of a supported pattern: let ...: ty = ...;
• wild pattern: let _ = ...;

​

Generics

​

Generic Functions

#[encrypted]
mod generics_example {
    use arcis::*;

    // Use a pre-built optimized circuit by name
    // The empty function body is intentional - the circuit implementation is built-in
    #[arcis_circuit = "zero"]
    fn make_zero<T: ArcisType>(a: T) -> T {}

    fn set_zero<T: ArcisType + Copy>(a: &mut T) {
        *a = make_zero(*a);
    }

    #[instruction]
    fn zero_any_type(mut arr: [u8; 10], mut val: u64) -> ([u8; 10], u64) {
        set_zero(&mut arr);
        set_zero::<u64>(&mut val);  // Turbofish syntax works
        (arr, val)
    }
}

​

Generic Structs

struct Wrapper<T>(T);

impl<T> Wrapper<T> {
    fn new(value: T) -> Self {
        Wrapper(value)
    }

    fn into_inner(self) -> T {
        self.0
    }
}

#[instruction]
fn use_generic_struct(a: u8) -> u8 {
    Wrapper::new(a).into_inner()
}

​

Custom Traits

trait Processable {
    type Output;
    fn process(&self) -> Self::Output;
}

impl Processable for u8 {
    type Output = u16;
    fn process(&self) -> u16 {
        *self as u16 * 2
    }
}

fn apply_process<T: Processable>(val: &T) -> T::Output {
    val.process()
}

#[instruction]
fn trait_example(x: u8) -> u16 {
    apply_process(&x)
}

​

Generic Constraints

​

Iterators

​

Supported Iterator Methods

#[instruction]
fn iterator_examples(arr: [u8; 10]) -> u16 {
    // Basic iteration
    let mut sum = 0u16;
    for val in arr.iter() {
        sum += *val as u16;
    }

    // Method chaining
    arr.iter()
       .map(|x| *x as u16)
       .map(|x| x * 2)
       .sum()
}

​

Complete Iterator Support

​

Filter Alternative

// ✗ Not supported
arr.iter().filter(|x| **x > threshold).sum()

// ✓ Manual filter pattern
#[instruction]
fn filter_sum(arr: [u8; 10], threshold: u8) -> u16 {
    let mut sum = 0u16;
    for val in arr.iter() {
        if *val > threshold {
            sum += *val as u16;
        }
    }
    sum
}

​

What’s next?