SolMath

Deterministic fixed-point mathematics and quantitative finance for Rust and Solana.

SolMath is a no_std, zero-dependency library for deterministic decimal math, probability functions, derivatives pricing, and DeFi calculations. Heavily CU optimised to fit on Solana and all functions thoroughly verified against at least 100k quantlib vectors for accuracy. Runtime code uses integer arithmetic with 12 decimal places; there is no floating point, heap allocation, network access, or off-chain pricing service.

The crate spans the complete path from arithmetic primitives to on-chain pricing engines:

• checked fixed-point multiply, divide, square root, rounding, and U256-backed intermediate arithmetic;
• ln, ln(1+x), exp, exp(x)-1, powers, trigonometry, and high-precision variants;
• normal PDF/CDF/inverse CDF, bivariate normal probabilities, and two-asset rainbow options;
• Black–Scholes prices and Greeks, implied volatility, barrier options, arithmetic-Asian/TWAP settlement, American options, exponential NIG, deterministic Heston, and SABR;
• weighted-pool swaps, token conversion, and explicit settlement rounding.

no_std · zero dependencies · pure integer runtime · SCALE = 1e12

Quick start

[dependencies]
solmath = "0.2"

Values are integers scaled by 1_000_000_000_000. The parsing helpers are useful in tests and clients; Solana instructions normally receive encoded integers directly.

use solmath::{fp, fp_div, fp_mul, fp_sqrt};

let amount = fp("1250.50")?;
let rate = fp("0.035")?;

let interest = fp_mul(amount, rate)?;          // 43.7675
let one_third = fp_div(fp("1")?, fp("3")?)?; // 0.333333333333
let root_two = fp_sqrt(fp("2")?)?;            // 1.414213562373

Pricing models use the same representation:

use solmath::{bs_full_hp, SCALE};

let greeks = bs_full_hp(
    100 * SCALE,          // spot
    105 * SCALE,          // strike
    50_000_000_000,       // rate = 5%
    200_000_000_000,      // volatility = 20%
    SCALE,                // one year
)?;

// greeks.call, greeks.put, greeks.call_delta, greeks.gamma, greeks.vega, ...

What is included

Feature selection

The default is core arithmetic plus transcendental. Financial models and complex arithmetic are opt-in so downstream programs compile only the capabilities they use.

# Core arithmetic only
solmath = { version = "0.2", default-features = false }

# Black–Scholes and Greeks
solmath = { version = "0.2", default-features = false, features = ["bs"] }

# Fully on-chain American pricing
solmath = { version = "0.2", default-features = false, features = ["american-kbi"] }

# Fully on-chain exponential NIG pricing
solmath = { version = "0.2", default-features = false, features = ["nig"] }

# All stable runtime modules
solmath = { version = "0.2", features = ["full"] }

table-gen and pade-iv are intentionally outside full. For size-sensitive Solana programs, prefer default-features = false with one or two explicit capabilities. Final linked size also depends on which functions the downstream program actually calls and what LTO removes.

On-chain pricing engines

American options: Kim Boundary Integration

american_kbi_price accepts only (S, K, r, q, sigma, T) and the option side. It reconstructs the smooth-pasting exercise boundary and evaluates Kim's early-exercise-premium integral inside the program. The embedded artifact is parameter-independent quadrature geometry and normal-kernel coefficients—not a grid of prices or per-contract lookup data.

use solmath::{american_kbi_price, AmericanKbiKind, SCALE};

let put = american_kbi_price(
    100 * SCALE,
    100 * SCALE,
    50_000_000_000,
    30_000_000_000,
    300_000_000_000,
    SCALE,
    AmericanKbiKind::Put,
)?;

The production corpus measured maximum call/put errors of $0.002744 / $0.003264 per $100 strike against QuantLib QdFp. The deployed quote instructions maxed at 390,628 / 390,786 CU. See Kim Boundary Integration.

Exponential NIG

nig_price_certified prices the smaller out-of-the-money leg through an embedded 15/7 Gauss–Kronrod density integral, obtains the other leg by exact fixed-point put-call parity, and returns the quote's numerical allowance and execution tier.

use solmath::{nig_price_certified, NigParams, SCALE};

let quote = nig_price_certified(
    100 * SCALE,
    100 * SCALE,
    50_000_000_000,
    20_000_000_000,
    SCALE,
    NigParams {
        alpha: 15 * SCALE,
        beta: -2 * SCALE as i128,
        delta_per_year: SCALE,
    },
    5_000_000_000, // requested absolute error = 0.005
)?;

// quote.call, quote.put, quote.max_abs_error, quote.tier

Across the production/adversarial reference campaigns, maximum normalized errors were $0.000565 / $0.001397 per $100. The deployed instruction maxed at 382,441 CU. See Exponential NIG.

Arithmetic-Asian and TWAP settlement

twap_option_price combines the authenticated fixed portion of an in-progress average with exact continuous-GBM first and second moments for the remaining window, then prices the moment-matched distribution. It handles unseasoned, partially fixed, and fully fixed averages through one API. The practical deployed sweep maxed at 182,458 math CU. See Arithmetic-Asian / TWAP.

The rest of the model surface

• bs_full provides a compact standard-precision price-and-Greeks path; bs_full_hp provides the highest-accuracy European path.
• implied_vol combines a rational initializer, bracketed Halley refinement, and a normalized-space fallback.
• barrier_option_with_state prices continuous down/up, in/out barriers while incorporating the contract's persisted breach state.
• best_of_call and worst_of_call implement the two-asset Stulz formulas.
• certify_sabr_surface validates a complete strike/maturity grid and returns typed certified quote nodes for execution.
• heston_price implements the exact deterministic-variance (xi = 0) reduction to high-precision Black–Scholes.

Performance and footprint

Measurements below are from deployed SBF artifacts; CU figures refer to the math call or benchmark instruction stated, not an application's entire transaction.

Isolated linked SBF footprints against the same 184,848-byte Anchor baseline:

Run scripts/measure_sbf_footprint.sh and the composite harness against the exact downstream program before setting deployment and transaction budgets.

Accuracy and numerical design

SolMath uses range reduction, low-degree minimax/piecewise kernels, compensated fixed-point arithmetic, and widened intermediates. Parameter-independent coefficients and quadrature geometry are generated offline and embedded as integers; option prices remain functions of live inputs.

Representative release evidence:

The detailed corpora, commands, certificate identities, and model-specific domains are indexed in VALIDATION.md and PROOFS.md.

Runtime contract

• Public computations are infallible or return Result<_, SolMathError>.
• DomainError, Overflow, DivisionByZero, and NoConvergence make the numerical outcome explicit.
• The crate forbids unsafe Rust, has no runtime dependencies, and does not allocate.
• U256-backed paths preserve results whose final value fits even when a u128 × u128 intermediate does not.
• Validated input types such as EuropeanInputs, TwapInputs, and PoolSwapInputs let programs establish model bounds once at the instruction boundary.
• Settlement helpers expose floor and ceiling explicitly so protocols can choose their economic rounding policy.

See SECURITY.md for the precise arithmetic and model contracts, and INTEGRATION.md for Anchor patterns and compute-budget guidance.

Documentation

• Usage guide — worked examples for the runtime APIs.
• Solana integration — validated inputs, Anchor error mapping, account examples, rounding, and CU budgets.
• Architecture — precision tiers, modules, generated kernels, feature gates, and rounding conventions.
• Kim Boundary Integration — method, domain, QuantLib accuracy, CU, and artifact identity.
• Exponential NIG — model convention, API, domain, accuracy, and compute tiers.
• Arithmetic-Asian / TWAP — settlement state, moment equations, validation, and usage.
• Validation — release matrix and reproducibility commands.
• Security model — arithmetic guarantees and integration boundaries.
• API reference — generated Rust documentation.

License

MIT OR Apache-2.0