Skip to main content
Kimia relies on two Rust crates for on-chain math: perps-math (perps engine) and kimia-math (everything else). Both use 9-decimal fixed-point internally and always round down.

​
Constants

ConstantValueMeaning
PRICE_PRECISION1_000_0006-decimal prices
BASE_PRECISION1_000_000_0009-decimal base (SOL lamports)
QUOTE_PRECISION1_000_0006-decimal quote (USDC)
FUNDING_PRECISION1_000_000_0009-decimal funding
MARGIN_PRECISION10_000100%
BPS_PRECISION10_000100%
FUNDING_PERIOD_SECONDS36001h
PERIODS_PER_DAY24
FUNDING_RATE_OFFSET_DENOMINATOR50000.02%/period carry cost
FUNDING_RATE_MAX_DENOMINATOR33±3.03% clamp
LIQUIDATION_FEE_BPS5005%
DEFAULT_TAKER_FEE_BPS100.1%
DEFAULT_MAKER_FEE_BPS50.05%
ORACLE_STALENESS_THRESHOLD60seconds
ORACLE_CONFIDENCE_MAX_BPS2502.5%

​
perps-math

​
funding

  • calculate_funding_rate(mark_twap, oracle_twap, oracle_price) → i128
  • calculate_funding_payment(base, funding_delta) → i64
  • update_twap(twap, price, elapsed, period) → u64

​
margin

  • calculate_margin_requirement(base, price, margin_ratio) → u64
  • calculate_health(collateral, pnl, maint_req) → i64
  • has_sufficient_initial_margin(...)
  • max_position_size(collateral, price, initial_margin_ratio) → u64
  • calculate_liquidation_price(base, entry, collateral, maint_margin_ratio) → u64

​
pnl

  • calculate_unrealized_pnl(base, mark, quote_entry) → i64
  • settle_close(base, quote_entry, close_amount, close_price) → (realized_pnl, new_base, new_quote)

​
safe_math

All returning Option<T>, no panics:
  • mul_div_down / mul_div_up
  • apply_bps_down / apply_bps_up
  • base_to_quote(base, price)
  • normalize_pyth_price(pyth_price, pyth_expo, target_expo)

​
kimia-math

​
Fixed-point

  • mul_fp(a, b) = a · b / ONE, u128 intermediate
  • div_fp(a, b) = a · ONE / b
  • ONE = 1_000_000_000
  • signed_delta(new, old), for yield deltas (negative means no yield)

​
exp / ln (exp_ln.rs)

  • ln_fp(x), range-reduced to [0.5, 2.0) via Taylor on z = (x-1)/(x+1)
  • exp_fp(x), range-reduced via powers of 2
  • pow_frac(base, exponent), exp(exponent · ln(base)) for exponent ∈ [0, ONE]
Validated precision: < 0.05% error across the full yield-AMM operating range.

​
insurance

  • process_positive_funding(funding, skim_bps) → (insurance_skim, vault_yield)
  • process_negative_funding(fund_balance, loss) → (new_balance, uncovered_loss)