@osmonauts/math

OsmosJS 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

Table of Contents

• @osmonauts/math
  • install
  • Table of Contents
  • Calculations
    • Pool Calculations
      • calcPoolLiquidity
      • calcCoinsNeededForValue
      • calcMaxCoinsForPool
      • calcShareOutAmount
      • calcPoolAprs
    • Swap Calculations
      • getRoutesForTrade
      • calcAmountWithSlippage
      • calcPriceImpactGivenIn
      • calcPriceImpactGivenOut
  • Publishing
  • Credits
  • Disclaimer

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.

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

Related

Checkout these related projects:

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

Credits

🛠 Built by Cosmology — if you like our tools, please consider delegating to our validator ⚛️

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.