@osmonauts/math

OsmosJS (opens in a new tab) makes it easy to compose and broadcast Osmosis and Cosmos messages, with all of the proto and amino encoding handled for you.

install

npm install @osmonauts/math

@osmonauts/math

Calculations

Pool Calculations

`calcPoolLiquidity`

Calculate a pool's liquidity.

import { calcPoolLiquidity } from "@osmonauts/math";
 
const liquidity = calcPoolLiquidity(pool, prices);

Pool liquidity is calculated using the formula below: $liquidity=\dfrac{tokenA}{10^{exponentA}}\times priceA + \dfrac{tokenB}{10^{exponentB}}\times priceB$ For pools with multiple tokens, just add more tokens to the end.

`calcCoinsNeededForValue`

Calculate the coins needed in a pool for the given dollar value.

import { calcCoinsNeededForValue } from "@osmonauts/math";
 
const coinsNeeded = calcCoinsNeededForValue(prices, poolInfo, value);

The amount of either of the tokens needed in a pool is calculated using the formula below:

$amountNeeded=\dfrac{tokenWeight}{totalWeight}\times value \div price\times 10^{exponent}$

`calcMaxCoinsForPool`

Calculate the maximum coins affordable in the balance for a given pool.

import { calcMaxCoinsForPool } from "@osmonauts/math";
 
const maxCoins = calcMaxCoinsForPool(prices, poolInfo, balances);

`calcShareOutAmount`

Once you have the coins needed from either calcCoinsNeededForValue or calcMaxCoinsForPool, you can use calcShareOutAmount to get the shareOutAmount for the pool:

import { calcShareOutAmount } from "@osmonauts/math";
 
const shareOutAmount = calcShareOutAmount(poolInfo, coinsNeeded);

`calcPoolAprs`

Calculate a pool's APR which consists of three parts: superfluid APR, gauge APR and fees APR.

import { calcPoolAprs } from "@osmonauts/math";
 
const poolApr = calcPoolAprs({
  activeGauges, // all the active gauges of a pool
  pool, // pool info
  prices, // priceHash
  superfluidPools, // all the superfluid pools
  aprSuperfluid, // apr of superfluid staking
  lockupDurations, // all the lockup durations
  volume7d, // 7 day trading volume of the pool
  swapFee, // percentage value, e.g. 0.002
  lockup = "14", // optional, specify the lockup duration
  includeNonPerpetual = true, // optional, whether to include non-perpetual gauges
})

For superfluid APR, you can get all the pools' APRs from this endpoint (opens in a new tab).

The formula for calculating the gauge APR:

$gaugeAPR=\dfrac{totalCoins-distributedCoins}{10^{exponent}}\times price\div liquidity\times 36500$

Fees APR works in a similar way:

$feesAPR=\dfrac{tradingVolume7d}{7}\times swapFee\div liquidity\times 36500$

Swap Calculations

`getRoutesForTrade`

Find the available routes for trade given sell token and buy token, as well as pool pairs.

import { getRoutesForTrade, makePoolPairs } from "@osmonauts/math";
 
const pairs = makePoolPairs(pools, prices);
 
const routes = getRoutesForTrade({
  trade: {
    sell, // token to sell
    buy, // token to buy
  },
  pairs,
});

`calcAmountWithSlippage`

Calculates the tokenOut amount after slippage, slippage is the number without the "%" part, e.g. if slippage is "1%", then pass in 1 as slippage, rather than 0.01.

import { calcAmountWithSlippage } from "@osmonauts/math";
 
const tokenOutMinAmount = calcAmountWithSlippage(tokenOutAmount, slippage);

`calcPriceImpactGivenIn`

Calculates price impact given the tokenIn info and the tokenOutDenom.

import { calcPriceImpactGivenIn } from "@osmonauts/math";
 
const priceImpact = calcPriceImpactGivenIn(
  tokenIn, // tokenIn info
  tokenOutDenom,
  pool // the pool that contains both tokenIn and tokenOut as poolAssets
);

`calcPriceImpactGivenOut`

Calculates price impact given the tokenOut info and the tokenInDenom.

import { calcPriceImpactGivenOut } from "@osmonauts/math";
 
const priceImpact = calcPriceImpactGivenOut(
  tokenOut, // tokenOut info
  tokenInDenom,
  pool // the pool that contains both tokenIn and tokenOut as poolAssets
);

Publishing

Build the types and then publish:

yarn build:ts
yarn publish

Checkout these related projects:

@cosmology/telescope (opens in a new tab) Your Frontend Companion for Building with TypeScript with Cosmos SDK Modules.
@cosmwasm/ts-codegen (opens in a new tab) Convert your CosmWasm smart contracts into dev-friendly TypeScript classes.
chain-registry (opens in a new tab) Everything from token symbols, logos, and IBC denominations for all assets you want to support in your application.
cosmos-kit (opens in a new tab) Experience the convenience of connecting with a variety of web3 wallets through a single, streamlined interface.
create-cosmos-app (opens in a new tab) Set up a modern Cosmos app by running one command.
interchain-ui (opens in a new tab) The Interchain Design System, empowering developers with a flexible, easy-to-use UI kit.
starship (opens in a new tab) Unified Testing and Development for the Interchain.

Credits

🛠 Built by Cosmology — if you like our tools, please consider delegating to our validator ⚛️ (opens in a new tab)

Disclaimer

AS DESCRIBED IN THE LICENSES, THE SOFTWARE IS PROVIDED “AS IS”, AT YOUR OWN RISK, AND WITHOUT WARRANTIES OF ANY KIND.

No developer or entity involved in creating this software will be liable for any claims or damages whatsoever associated with your use, inability to use, or your interaction with other users of the code, including any direct, indirect, incidental, special, exemplary, punitive or consequential damages, or loss of profits, cryptocurrencies, tokens, or anything else of value.

Introduction