Class CmmmCalculations

Implements the pool invariant and local swap, liquidity, and validity math.

The formulas mirror the pool Move package. This implementation uses JavaScript number values internally, so it is useful for estimates and input validation but can differ from on-chain results at large values or near rounding boundaries. Coin amounts in the public methods use smallest units. Pool weights, fees, balances, and fixed ratios use the pool's fixed scalars unless a parameter is documented as a decimal number.

Example

const amountOut = CmmmCalculations.calcOutGivenIn(
	pool,
	"0x2::sui::SUI",
	"0x<package>::coin::USDC",
	1_000_000_000n,
);

Constructors

constructor

new CmmmCalculations(): CmmmCalculations

Returns CmmmCalculations

Methods

`Static`calcAllCoinDeposit

calcAllCoinDeposit(pool: PoolObject, amountsIn: CoinsToBalance): CoinsToBalance
Scales a requested all-coin deposit by its smallest normalized proportion.

The result keeps the input map's keys and multiplies every requested amount by the smallest amount / pool balance ratio. This produces the proportional, dust-free portion used by the direct all-coin deposit path. Amounts use smallest units. The helper does not build a transaction.
Parameters
- pool: PoolObject
  The pool state supplying balances and decimal scalars.
- amountsIn: CoinsToBalance
  Requested deposit amounts keyed by coin type.
Returns CoinsToBalance
The proportional deposit amounts keyed by the same coin types.
- Defined in packages/pools/utils/cmmmCalculations.ts:1206

`Static`calcAllCoinWithdraw

calcAllCoinWithdraw(
pool: PoolObject,
amountsOut: CoinsToBalance,
): CoinsToBalance
Scales a requested all-coin withdrawal by its largest normalized proportion.

The result keeps the input map's keys and multiplies every requested amount by the largest amount / pool balance ratio. This produces a proportional vector that covers the requested direction. It does not build a transaction or apply protocol and DAO fees.
Parameters
- pool: PoolObject
  The pool state supplying balances and decimal scalars.
- amountsOut: CoinsToBalance
  Requested output amounts keyed by coin type.
Returns CoinsToBalance
The proportionally scaled output amounts keyed by the same coin types.
- Defined in packages/pools/utils/cmmmCalculations.ts:1253

`Static`calcDepositFixedAmounts

calcDepositFixedAmounts(pool: PoolObject, amountsIn: CoinsToBalance): bigint
Calculates the LP ratio produced by a fixed-amount liquidity deposit.

The result is an on-chain fixed-point ratio. 1_000_000_000_000_000_000n represents a ratio of 1. Pool.getDepositLpAmountOut converts this ratio to a decimal and derives the minted LP amount from the current supply. Amounts use each coin's smallest unit.
Parameters
- pool: PoolObject
  The pool state used for the invariant.
- amountsIn: CoinsToBalance
  Deposit amounts keyed by coin type, in smallest units.
Returns bigint
The fixed-point LP ratio.

Throws
Error when the calculated deposit fails invariant validation or Newton iteration diverges.
- Defined in packages/pools/utils/cmmmCalculations.ts:725

`Static`calcInGivenOut

calcInGivenOut(
    pool: PoolObject,
    coinTypeIn: string,
    coinTypeOut: string,
    amountOut: bigint,
): bigint
Calculates the exact input for a one-dimensional exact-output swap.

amountOut and the return value use the respective coin's smallest unit. The calculation applies the pool's input and output swap fees. Protocol and DAO fees are applied by the higher-level Pool wrapper.
Parameters
- pool: PoolObject
  The pool state used for the invariant.
- coinTypeIn: string
  The coin type entering the pool.
- coinTypeOut: string
  The coin type leaving the pool.
- amountOut: bigint
  The required output in coinTypeOut smallest units.
Returns bigint
The input amount in coinTypeIn smallest units.

Throws
Error when the coin types match, the swap is disabled for a non-zero output, or the calculated swap is invalid.
- Defined in packages/pools/utils/cmmmCalculations.ts:378

`Static`calcInvariant

calcInvariant(pool: PoolObject): number
Calculates the pool invariant from normalized balances, weights, and flatness.

Swaps preserve this value before fees. Liquidity changes alter it and are therefore related to LP value. The result is a local floating-point value, not an on-chain fixed-point integer.
Parameters
- pool: PoolObject
  The pool state containing normalized balances and fixed-point parameters.
Returns number
The invariant in normalized decimal units.
- Defined in packages/pools/utils/cmmmCalculations.ts:90

`Static`calcInvariantComponents

calcInvariantComponents(
pool: PoolObject,
index: string,
): [prod: number, sum: number, p0: number, s0: number, h: number]
Returns invariant components with one coin removed for one-dimensional math.

The tuple is [prod, sum, p0, s0, h]. prod and sum include every coin. p0 and s0 omit index. h is the full pool invariant.
Parameters
- pool: PoolObject
  The pool state used for the calculation.
- index: string
  The coin type whose contribution p0 and s0 omit.
Returns [prod: number, sum: number, p0: number, s0: number, h: number]
The weighted product, weighted sum, reduced product, reduced sum, and invariant.
- Defined in packages/pools/utils/cmmmCalculations.ts:144

`Static`calcInvariantQuadratic

calcInvariantQuadratic(prod: number, sum: number, flatness: number): number
Solves the invariant's quadratic equation for a weighted product and sum.

Pass decimal values produced by FixedUtils.directCast, not raw on-chain fixed-point integers.
Parameters
- prod: number
  The weighted product of normalized balances.
- sum: number
  The weighted sum of normalized balances.
- flatness: number
  The decimal flatness value in the inclusive range 0 to 1.
Returns number
The invariant solution h.
- Defined in packages/pools/utils/cmmmCalculations.ts:122

`Static`calcOutGivenIn

calcOutGivenIn(
    pool: PoolObject,
    coinTypeIn: string,
    coinTypeOut: string,
    amountIn: bigint,
): bigint
Calculates the exact output for a one-dimensional exact-input swap.

amountIn and the return value use the respective coin's smallest unit. The calculation applies the pool's input and output swap fees. Protocol and DAO fees are applied by the higher-level Pool wrapper, not here.
Parameters
- pool: PoolObject
  The pool state used for the invariant.
- coinTypeIn: string
  The coin type entering the pool.
- coinTypeOut: string
  The coin type leaving the pool.
- amountIn: bigint
  The input amount in coinTypeIn smallest units.
Returns bigint
The output amount in coinTypeOut smallest units. Returns 0n when either swap fee disables the pair.

Throws
Error when the coin types match or the calculated swap is invalid.
- Defined in packages/pools/utils/cmmmCalculations.ts:296

`Static`calcSpotPrice

calcSpotPrice(pool: PoolObject, coinTypeIn: string, coinTypeOut: string): number
Calculates the fee-free spot price from one pool coin to another.

The result is the normalized coinIn amount per normalized coinOut amount. Pool.getSpotPrice applies decimal scalars when it exposes this value to callers.
Parameters
- pool: PoolObject
  The pool state used for the invariant.
- coinTypeIn: string
  The input coin type.
- coinTypeOut: string
  The output coin type.
Returns number
The fee-free normalized spot-price ratio.
- Defined in packages/pools/utils/cmmmCalculations.ts:197

`Static`calcSpotPriceWithFees

calcSpotPriceWithFees(
    pool: PoolObject,
    coinTypeIn: string,
    coinTypeOut: string,
    ignoreFees?: boolean,
): number
Calculates a spot price with optional pool fee terms.

The result is the normalized coinIn amount per normalized coinOut amount. Set ignoreFees to true to omit swap and DAO fee terms.
Parameters
- pool: PoolObject
  The pool state used for the invariant and fee metadata.
- coinTypeIn: string
  The input coin type.
- coinTypeOut: string
  The output coin type.
- OptionalignoreFees: boolean
  Whether to omit the fee terms. The default is false.
Returns number
The normalized spot-price ratio.
- Defined in packages/pools/utils/cmmmCalculations.ts:216

`Static`calcSwapFixedIn

calcSwapFixedIn(
    pool: PoolObject,
    amountsIn: CoinsToBalance,
    amountsOutDirection: CoinsToBalance,
): bigint
Solves a vector swap with fixed inputs and a proportional output direction.

The return value is an on-chain fixed-point scalar t. Multiply each value in amountsOutDirection by t to get the output vector. Amount maps use each coin's smallest unit, and 1_000_000_000_000_000_000n represents t = 1.
Parameters
- pool: PoolObject
  The pool state used for the invariant.
- amountsIn: CoinsToBalance
  Input amounts keyed by coin type, in smallest units.
- amountsOutDirection: CoinsToBalance
  Non-zero output direction amounts, in smallest units.
Returns bigint
The fixed-point scalar for the output direction.

Throws
Error when a requested coin is disabled, the vector is invalid, or Newton iteration diverges.
- Defined in packages/pools/utils/cmmmCalculations.ts:463

`Static`calcSwapFixedOut

calcSwapFixedOut(
    pool: PoolObject,
    amountsInDirection: CoinsToBalance,
    amountsOut: CoinsToBalance,
): bigint
Solves a vector swap with fixed outputs and a proportional input direction.

The return value is an on-chain fixed-point scalar t. Multiply each value in amountsInDirection by t to get the input vector. Amount maps use each coin's smallest unit, and 1_000_000_000_000_000_000n represents t = 1.
Parameters
- pool: PoolObject
  The pool state used for the invariant.
- amountsInDirection: CoinsToBalance
  Non-zero input direction amounts, in smallest units.
- amountsOut: CoinsToBalance
  Fixed output amounts keyed by coin type, in smallest units.
Returns bigint
The fixed-point scalar for the input direction.

Throws
Error when an output coin is disabled, the vector is invalid, or Newton iteration diverges.
- Defined in packages/pools/utils/cmmmCalculations.ts:613

`Static`calcWithdrawFlpAmountsOut

calcWithdrawFlpAmountsOut(
    pool: PoolObject,
    amountsOutDirection: CoinsToBalance,
    lpRatio: number,
): CoinsToBalance
Calculates output amounts for a fixed LP withdrawal direction.

lpRatio is the fraction of the original pool balance retained after the withdrawal. For example, 0.9 means that 10% of the LP position is burned. Non-zero entries in amountsOutDirection define the output direction. The returned map contains scaled smallest-unit amounts for every pool coin.
Parameters
- pool: PoolObject
  The pool state used for the invariant.
- amountsOutDirection: CoinsToBalance
  Desired output direction keyed by coin type, in smallest units.
- lpRatio: number
  Decimal fraction of the pool retained after the withdrawal.
Returns CoinsToBalance
Output amounts keyed by pool coin type, in smallest units.

Throws
Error when the requested direction drains a coin, fails validation, or Newton iteration diverges.
- Defined in packages/pools/utils/cmmmCalculations.ts:930

`Static`checkValid1dSwap

checkValid1dSwap(
    pool: PoolObject,
    coinTypeIn: string,
    coinTypeOut: string,
    amountInB: bigint,
    amountOutB: bigint,
): boolean
Checks a one-input, one-output swap against pool constraints.

Amounts use the input and output coins' smallest units. This helper returns false for equal coin types, drained balances, or an invariant mismatch.
Parameters
- pool: PoolObject
  The pool state used for the invariant.
- coinTypeIn: string
  The input coin type.
- coinTypeOut: string
  The output coin type.
- amountInB: bigint
  The input amount in smallest units.
- amountOutB: bigint
  The output amount in smallest units.
Returns boolean
true when the swap is valid within the math tolerances.
- Defined in packages/pools/utils/cmmmCalculations.ts:1527

`Static`checkValidDeposit

checkValidDeposit(
    pool: PoolObject,
    amountsIn: CoinsToBalance,
    lpRatioRaw: bigint,
): boolean
Checks a fixed-amount deposit and its claimed LP ratio.

lpRatioRaw is an on-chain fixed-point ratio. 1_000_000_000_000_000_000n represents 1. The check models the intermediate swap and all-coin investment used by the pool contract.
Parameters
- pool: PoolObject
  The pool state used for the invariant.
- amountsIn: CoinsToBalance
  Deposit amounts keyed by coin type, in smallest units.
- lpRatioRaw: bigint
  Claimed LP ratio in on-chain fixed-point units.
Returns boolean
true when the deposit and ratio satisfy pool constraints.
- Defined in packages/pools/utils/cmmmCalculations.ts:1656

`Static`checkValidSwap

checkValidSwap(
    pool: PoolObject,
    amountsIn: CoinsToBalance,
    amountsInScalar: number,
    amountsOut: CoinsToBalance,
    amountsOutScalar: number,
): boolean
Checks a vector swap against pool balance, fee, and invariant constraints.

The two scalar parameters allow callers to reuse direction vectors. A scalar of 1 applies the vector as supplied. The method rejects a coin that is both input and output, rejects a drained balance, and checks the fee-adjusted invariant within the implementation tolerances.
Parameters
- pool: PoolObject
  The pool state used for the invariant.
- amountsIn: CoinsToBalance
  Input direction amounts in smallest units.
- amountsInScalar: number
  Decimal scalar applied to amountsIn.
- amountsOut: CoinsToBalance
  Output direction amounts in smallest units.
- amountsOutScalar: number
  Decimal scalar applied to amountsOut.
Returns boolean
true when the scaled swap is valid. Returns false for an invalid vector or balance.
- Defined in packages/pools/utils/cmmmCalculations.ts:1410

`Static`checkValidWithdraw

checkValidWithdraw(
    pool: PoolObject,
    amountsOutSrc: CoinsToBalance,
    lpRatio: number,
): boolean
Checks a fixed LP withdrawal and its output direction.

lpRatio is the decimal fraction of the pool balance retained before the final swap. Amounts use smallest units. The check rejects ratios above 1, overdrawn balances, and fee-adjusted invariant mismatches.
Parameters
- pool: PoolObject
  The pool state used for the invariant.
- amountsOutSrc: CoinsToBalance
  Requested output direction keyed by coin type.
- lpRatio: number
  Decimal fraction of the pool retained after the proportional withdrawal.
Returns boolean
true when the withdrawal is valid within the math tolerances.
- Defined in packages/pools/utils/cmmmCalculations.ts:1772

`Static`getEstimateDepositFixedAmounts

getEstimateDepositFixedAmounts(
pool: PoolObject,
amountsIn: CoinsToBalance,
): number
Estimates the LP ratio for a fixed-amount deposit using a tangent-plane approximation.

The return value is a decimal retained ratio. The approximation is most accurate for small deposits. Use calcDepositFixedAmounts for the invariant solve used by transaction preparation.
Parameters
- pool: PoolObject
  The pool state used for spot prices and fee metadata.
- amountsIn: CoinsToBalance
  Deposit amounts keyed by coin type, in smallest units.
Returns number
The decimal LP ratio estimate.
- Defined in packages/pools/utils/cmmmCalculations.ts:2059

`Static`getEstimateInGivenOut

getEstimateInGivenOut(
    pool: PoolObject,
    coinTypeIn: string,
    coinTypeOut: string,
    amountOut: bigint,
): bigint
Estimates exact-output cost by dividing the desired output by the fee-aware spot price.

This is a fast linear estimate. It does not solve the invariant and becomes less accurate as the requested output consumes more pool balance.
Parameters
- pool: PoolObject
  The pool state used for the spot price.
- coinTypeIn: string
  The input coin type.
- coinTypeOut: string
  The output coin type.
- amountOut: bigint
  The desired output amount in smallest units.
Returns bigint
The estimated input in smallest units.
- Defined in packages/pools/utils/cmmmCalculations.ts:1917

`Static`getEstimateOutGivenIn

getEstimateOutGivenIn(
    pool: PoolObject,
    coinTypeIn: string,
    coinTypeOut: string,
    amountIn: bigint,
): bigint
Estimates exact-input output by multiplying the amount by the fee-aware spot price.

This is a fast linear estimate. It does not solve the invariant and becomes less accurate as the trade consumes more pool balance.
Parameters
- pool: PoolObject
  The pool state used for the spot price.
- coinTypeIn: string
  The input coin type.
- coinTypeOut: string
  The output coin type.
- amountIn: bigint
  The input amount in smallest units.
Returns bigint
The estimated output in smallest units.
- Defined in packages/pools/utils/cmmmCalculations.ts:1894

`Static`getEstimateSwapFixedIn

getEstimateSwapFixedIn(
    pool: PoolObject,
    amountsIn: CoinsToBalance,
    amountsOutDirection: CoinsToBalance,
): number
Estimates the fixed-input vector-swap scalar from the current spot prices.

The return value is a decimal number, not an on-chain fixed-point scalar. Multiply amountsOutDirection by it to get the linear output estimate. Use calcSwapFixedIn when an invariant solve is required.
Parameters
- pool: PoolObject
  The pool state used for spot prices and fee metadata.
- amountsIn: CoinsToBalance
  Input direction amounts in smallest units.
- amountsOutDirection: CoinsToBalance
  Output direction amounts in smallest units.
Returns number
The decimal output-direction scalar estimate.
- Defined in packages/pools/utils/cmmmCalculations.ts:1940

`Static`getEstimateSwapFixedOut

getEstimateSwapFixedOut(
    pool: PoolObject,
    amountsInDirection: CoinsToBalance,
    amountsOut: CoinsToBalance,
): number
Estimates the fixed-output vector-swap scalar from the current spot prices.

The return value is a decimal number, not an on-chain fixed-point scalar. Multiply amountsInDirection by it to get the linear input estimate. Use calcSwapFixedOut when an invariant solve is required.
Parameters
- pool: PoolObject
  The pool state used for spot prices and fee metadata.
- amountsInDirection: CoinsToBalance
  Input direction amounts in smallest units.
- amountsOut: CoinsToBalance
  Fixed output amounts in smallest units.
Returns number
The decimal input-direction scalar estimate.
- Defined in packages/pools/utils/cmmmCalculations.ts:2000

`Static`getEstimateWithdrawFlpAmountsOut

getEstimateWithdrawFlpAmountsOut(
    pool: PoolObject,
    amountsOutDirection: CoinsToBalance,
    lpRatio: number,
): number
Estimates the output-direction scalar for a fixed LP withdrawal.

The return value is a decimal number. Multiply amountsOutDirection by it to get the estimated output vector. lpRatio is the decimal retained pool ratio. The approximation is most accurate when lpRatio is close to 1. Use calcWithdrawFlpAmountsOut for the invariant solve.
Parameters
- pool: PoolObject
  The pool state used for spot prices and fee metadata.
- amountsOutDirection: CoinsToBalance
  Output direction amounts in smallest units.
- lpRatio: number
  Decimal fraction of the pool retained after withdrawal.
Returns number
The decimal output-direction scalar estimate.
- Defined in packages/pools/utils/cmmmCalculations.ts:2135

Class CmmmCalculations

Example

Index

Constructors

Methods

Constructors

constructor

Returns CmmmCalculations

Methods

StaticcalcAllCoinDeposit

Parameters

Returns CoinsToBalance

StaticcalcAllCoinWithdraw

Parameters

Returns CoinsToBalance

StaticcalcDepositFixedAmounts

Parameters

Returns bigint

Throws

StaticcalcInGivenOut

Parameters

Returns bigint

Throws

StaticcalcInvariant

Parameters

Returns number

StaticcalcInvariantComponents

Parameters

Returns [prod: number, sum: number, p0: number, s0: number, h: number]

StaticcalcInvariantQuadratic

Parameters

Returns number

StaticcalcOutGivenIn

Parameters

Returns bigint

Throws

StaticcalcSpotPrice

Parameters

Returns number

StaticcalcSpotPriceWithFees

Parameters

Returns number

StaticcalcSwapFixedIn

Parameters

Returns bigint

Throws

StaticcalcSwapFixedOut

Parameters

Returns bigint

Throws

StaticcalcWithdrawFlpAmountsOut

Parameters

Returns CoinsToBalance

Throws

StaticcheckValid1dSwap

Parameters

Returns boolean

StaticcheckValidDeposit

Parameters

Returns boolean

StaticcheckValidSwap

Parameters

Returns boolean

StaticcheckValidWithdraw

Parameters

Returns boolean

StaticgetEstimateDepositFixedAmounts

Parameters

Returns number

StaticgetEstimateInGivenOut

Parameters

Returns bigint

StaticgetEstimateOutGivenIn

Parameters

Returns bigint

StaticgetEstimateSwapFixedIn

Parameters

Returns number

StaticgetEstimateSwapFixedOut

Parameters

`Static`calcAllCoinDeposit

`Static`calcAllCoinWithdraw

`Static`calcDepositFixedAmounts

`Static`calcInGivenOut

`Static`calcInvariant

`Static`calcInvariantComponents

`Static`calcInvariantQuadratic

`Static`calcOutGivenIn

`Static`calcSpotPrice

`Static`calcSpotPriceWithFees

`Static`calcSwapFixedIn

`Static`calcSwapFixedOut

`Static`calcWithdrawFlpAmountsOut

`Static`checkValid1dSwap

`Static`checkValidDeposit

`Static`checkValidSwap

`Static`checkValidWithdraw

`Static`getEstimateDepositFixedAmounts

`Static`getEstimateInGivenOut

`Static`getEstimateOutGivenIn

`Static`getEstimateSwapFixedIn

`Static`getEstimateSwapFixedOut

`Static`getEstimateWithdrawFlpAmountsOut