cairo-numeric-types

name	cairo-numeric-types
description	Guide implementing custom numeric types in Cairo with invariant enforcement, overflow safety, and standard trait implementations; use when implementing fixed-point, signed integers, or other numeric primitives.

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