cairo-fp

A fixed-point math library in 64.64 and 32.32 representation built for Cairo & Starknet.

Credits

This project is a fork and enhancement of Cubit by Unstoppable Games, Inc. The original library laid the foundation for fixed-point arithmetic in Cairo and we are grateful for their pioneering work.

Original Authors: Unstoppable Games, Inc. / Influence

Cubit itself was the successor to cairo-math-64x61.

What's New in cairo-fp

• DeFi Primitives: Interest calculations, AMM pool math, ratio utilities
• Cube Root (cbrt): Essential for 3-asset pool calculations
• Enhanced Precision Tests: DeFi-typical value ranges validated
• Gas Benchmarks: Documented gas costs for all operations
• JavaScript Utilities: Off-chain computation helpers for frontend integration
• Modern Toolchain: Updated for Cairo 2.15+ and Scarb

Installation

Add to your Scarb.toml:

[dependencies]
cairo_fp = { git = "https://github.com/ametel01/cairo-fp" }

Fixed-Point Number Formats

| Format | Type | Range | Precision | |--------|------|-------|-----------| | 64.64 | f128::Fixed | -2^64 to 2^64 | ~1e-20 | | 32.32 | f64::Fixed | -2^32 to 2^32 | ~1e-9 |

A signed 64.64-bit fixed-point number is a fraction where the numerator is a signed 128-bit integer and the denominator is 2^64. The denominator is implicit, eliminating storage overhead.

Usage

use cairo_fp::f128::types::fixed::{Fixed, FixedTrait};

// Create fixed-point numbers
let a = FixedTrait::new_unscaled(5, false);  // 5.0
let b = FixedTrait::new(9223372036854775808, false);  // 0.5 (0.5 * 2^64)

// Arithmetic
let sum = a + b;      // 5.5
let product = a * b;  // 2.5
let quotient = a / b; // 10.0

// Math functions
let exp_val = a.exp();    // e^5
let ln_val = a.ln();      // ln(5)
let sqrt_val = a.sqrt();  // sqrt(5)
let pow_val = a.pow(b);   // 5^0.5

Core Library

All functions are available under cairo_fp::f64 or cairo_fp::f128.

Operators

| Operator | Trait | |----------|-------| | +, += | Add, AddEq | | -, -= | Sub, SubEq | | *, *= | Mul, MulEq | | /, /= | Div, DivEq | | ==, != | PartialEq | | >, >=, <, <= | PartialOrd |

Math Functions (math::ops)

| Function | Description | Gas (f128) | |----------|-------------|------------| | ceil | Round up to nearest integer | ~34k | | floor | Round down to nearest integer | ~34k | | round | Round to nearest integer | ~34k | | sqrt | Square root | ~33k | | cbrt | Cube root | ~217-363k | | exp | Natural exponential (e^x) | ~176k | | exp2 | Base-2 exponential (2^x) | ~17k | | ln | Natural logarithm | ~40k | | log2 | Base-2 logarithm | ~190k | | log10 | Base-10 logarithm | ~201k | | pow | Power function | ~75-362k |

Trigonometry (math::trig)

| Function | Fast Version | Description | |----------|--------------|-------------| | sin | sin_fast | Sine | | cos | cos_fast | Cosine | | tan | tan_fast | Tangent | | asin | asin_fast | Inverse sine | | acos | acos_fast | Inverse cosine | | atan | atan_fast | Inverse tangent |

Hyperbolic (math::hyp)

• sinh, cosh, tanh
• asinh, acosh, atanh

DeFi Primitives

Interest Calculations (math::interest)

use cairo_fp::f128::math::interest::{compound_interest, continuous_interest, linear_interpolate};

let principal = FixedTrait::new_unscaled(1000, false);
let rate = FixedTrait::new(922337203685477580, false);  // 5% = 0.05
let periods = FixedTrait::new_unscaled(12, false);

let amount = compound_interest(principal, rate, periods);

AMM Pool Math (math::pool)

use cairo_fp::f128::math::pool::{constant_product_price, liquidity_share, geometric_mean};

let reserve_a = FixedTrait::new_unscaled(1000000, false);
let reserve_b = FixedTrait::new_unscaled(2000000, false);

let price = constant_product_price(reserve_a, reserve_b);
let k = geometric_mean(reserve_a, reserve_b);

Ratio Utilities (math::ratio)

use cairo_fp::f128::math::ratio::{proportion, percentage_change, weighted_average};

let change = percentage_change(old_price, new_price);

JavaScript Utilities

For frontend integration, use the JS utilities to convert between JavaScript numbers and Cairo fixed-point representation:

import f128 from 'cairo-fp/src/f128/utils.js';

// Convert JS number to Fixed
const fixed = f128.toFixed(3.14159);
// { mag: 57952155664616982739n, sign: false }

// Convert Fixed back to JS number
const num = f128.fromFixed(fixed);
// 3.14159

// DeFi math helpers
const result = f128.exp(0.05);      // e^0.05
const sqrt = f128.sqrt(2);          // sqrt(2)
const cbrt = f128.cbrt(27);         // cbrt(27) = 3

Run JS tests:

bun test

Development

# Build
scarb build

# Run Cairo tests
snforge test

# Run JS tests
bun test

Gas Benchmarks

See inline documentation in src/f128/math/defi_precision.cairo and src/f64/math/defi_precision.cairo for detailed gas costs.

License

MIT

Original Cubit License: MIT © Unstoppable Games, Inc.