Cairo Numeric Types

Overview

Guide implementing production-quality custom numeric types (fixed-point, big integers, signed integers) in Cairo following Ekubo-style patterns.

Quick Use

• •Read references/numeric-types.md before answering.
• •Study Ekubo's i129 - the gold standard for signed integers in Cairo.
• •Use constructor functions to enforce invariants (e.g., no negative zero).
• •Provide both checked (returns Option) and unchecked (panics) API variants.
• •Implement standard traits: PartialEq, PartialOrd, Add, Sub, Mul, Neg, Zero, One.

Response Checklist

Invariant Enforcement

• •Use a private constructor function that enforces invariants (Ekubo i129 pattern).
• •Example: fn i256_new(mag: U256, neg: bool) -> I256 { I256 { mag, neg: neg && !u256_is_zero(mag) } }
• •Never allow invalid states like negative zero.

Defensive Normalization

• •In eq, cmp, and Hash, normalize inputs defensively to handle potentially invalid states.
• •Example: let a_neg = a.neg && !u256_is_zero(a.mag); before comparing.

API Safety

• •Name unsafe functions explicitly: from_raw_unchecked, not just from_raw.
• •Provide from_raw_checked returning Option<T> for untrusted input.
• •Document safety requirements with /// # Safety sections.

Checked vs Panicking Arithmetic

• •Implement checked versions first (return Option<T>).
• •Panicking versions should be thin wrappers: checked_op(...).expect('error msg').
• •Handle edge cases: Neg on MIN value overflows (returns None in checked).

Standard Trait Implementations

• •PartialEq: Takes @Self (snapshot) parameters, dereference with *.
• •PartialOrd: Implement lt, le, gt, ge for full ordering.
• •Add, Sub, Mul: Return owned values, panic on overflow.
• •Neg: Must handle MIN value overflow.
• •Zero, One, Default: Return constant values.
• •Into<SourceType>: For converting from smaller types.
• •Hash: Must be consistent with Eq (normalize before hashing).
• •Use #[derive(Copy, Drop, Serde, Debug)] for automatic implementations.

Limb-Based Arithmetic

• •Prefer 64-bit limbs for Cairo (U256 = 4 x u64, U512 = 8 x u64).
• •Use helper functions for limb access instead of copy-paste branches.
• •For division by 2^64, use value / TWO_POW_64 (Cairo lacks >> operator).
• •Loop-based operations reduce code size vs unrolled branches.

Code Organization

• •Keep checked arithmetic as the core implementation.
• •Panicking wrappers call checked versions with .expect().
• •Group related operations: constructors, arithmetic, traits, tests.

Cairo-Specific Quirks

• •No >> bit shift operator - use division by power-of-2 constant.
• •Can't index fixed-size arrays with runtime index - use .span().
• •use statements cannot appear inside functions.
• •Unary negation parsing issues - use 0_i32 - value instead of -value in some contexts.
• •Ambiguous unwrap - use OptionTrait::unwrap(result) to disambiguate.

Example Requests

• •"How do I implement a signed integer type in Cairo?"
• •"How do I enforce invariants like no negative zero?"
• •"How do I implement operator overloading for my numeric type?"
• •"How do I handle overflow in custom arithmetic?"

Reference Implementations

• •Ekubo i129 - Production signed integer (the gold standard)

Cairo by Example

• •Operator Overloading
• •Traits
• •Derive