npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

evm-maths

v7.0.1

Published

➗ Useful bigint math libraries to ease the journey through off-chain fixed-point arithmetics

Downloads

3,915

Readme

evm-maths

npm package Build Status Test Status Downloads Issues Commitizen Friendly Semantic Release

➗ Useful bigint math libraries to ease your journey through off-chain fixed-point arithmetics

Install

npm install evm-maths
yarn add evm-maths

Usage

Just import the module and you'll benefit from an augmented, and typed, BigInt class!

import "evm-maths";

const WAD = BigInt.pow10(18);

BigInt.from(1).wadMul(WAD); // 1
BigInt.from(WAD * 2n).rayMul(0.5e27); // WAD

If you choose to avoid prototype pollution, you can always import specific utilities:

import * as WadMath from "evm-maths/lib/wad";
import * as RayMath from "evm-maths/lib/ray";
import * as PercentMath from "evm-maths/lib/percent";

Book


Scale-agnostic utilities

approxEqAbs

Returns whether the BigNumber is approximately close to the given BigNumber, within the given tolerance

// only if you want to avoid BigNumber prototype pollution
import { approxEqAbs } from "evm-maths/lib/utils";

// Returns whether the BigNumber is approximately close to the given BigNumber, within the given tolerance: true
approxEqAbs(0, 1, "1");
BigNumber.approxEqAbs(0, 1, "1");
BigNumber.from(0).approxEqAbs(1, "1");

min

Returns the minimum between input BigNumberish, as a BigInt

// only if you want to avoid BigInt prototype pollution
import { min } from "evm-maths/lib/utils";

// Returns the minimum between input BigNumberish, as a BigInt: 0
min(0, 1, "2", ...);
BigInt.min(0, 1, "2", ...);
BigInt.from(0).min(1, "2", ...);

max

Returns the maximum between input BigNumberish, as a BigInt

// only if you want to avoid BigInt prototype pollution
import { max } from "evm-maths/lib/utils";

// Returns the maximum between input BigNumberish, as a BigInt: 2
max(0, 1, "2", ...);
BigInt.max(0, 1, "2", ...);
BigInt.from(0).max(1, "2", ...);

sum

Returns the sum of input BigNumberish array, as a BigInt

// only if you want to avoid BigInt prototype pollution
import { sum } from "evm-maths/lib/utils";

// Returns the sum of input BigNumberish array, as a BigInt: 3
sum([0, 1, "2"]);
BigInt.sum([0, 1, "2"]);
BigInt.from(0).sum([1, "2"]);

format

Returns a string representation of the BigInt's value, formatted according to:

  • the input number of decimals the BigInt value holds (default: 0)
  • the input number of digits expected after the unit, truncating the trailing digits if any (default: keep all digits after the decimal point)
// Returns a string representation of the BigInt's value: 0.01
BigInt.from(19).format(3, 2);

toFloat

Returns a float representation of the BigInt's value, parsed according to the input number of decimals the BigInt value holds (default: 0)

Note: parsing a too large value may result in parsing NaN (because the BigInt's value may still be too large to fit in a JS floating-point number)

// Returns a string representation of the BigInt's value: 0.01
BigInt.from(19).toFloat(3, 2);

pow10

Returns a 1 followed by the input number of zeros (10 raised to the power of the input)

// only if you want to avoid BigInt prototype pollution
import { pow10 } from "evm-maths/lib/utils";

// Returns a 1 followed by the input number of zeros: 100
pow10(2);
BigInt.pow10(2);

mulDiv

Performs a multiplication followed by a division, rounded half up

// only if you want to avoid BigInt prototype pollution
import { mulDivHalfUp } from "evm-maths/lib/utils";

// 1.0 (in wad) * 1 / 1 = 1.0 (in wad)
mulDivHalfUp(BigInt.WAD, 1, 1);
BigInt.WAD.mulDiv(1, 1);

mulDivUp

Performs a multiplication followed by a division, rounded up

// only if you want to avoid BigInt prototype pollution
import { mulDivUp } from "evm-maths/lib/utils";

// 0.999999999999999999 * 1 / WAD = 1.0 (in wad, rounded up)
mulDivUp(BigInt.WAD - 1n, 1, BigInt.WAD);
(BigInt.WAD - 1n).mulDivUp(1, BigInt.WAD);

mulDivDown

Performs a multiplication followed by a division, rounded down

// only if you want to avoid BigInt prototype pollution
import { mulDivDown } from "evm-maths/lib/utils";

// 1.000000000000000001 * 1 / WAD = 1.0 (in wad, rounded down)
mulDivDown(BigInt.WAD + 1n, 1, BigInt.WAD);
(BigInt.WAD + 1n).mulDivDown(1, BigInt.WAD);

Scale constants

WAD

Returns the common WAD unit, which is also known as ether in Solidity

Most commonly used as the ERC20 token unit

// only if you want to avoid BigInt prototype pollution
import { WAD } from "evm-maths/lib/constants";

// Returns a 1 followed by 18 zeros: 1000000000000000000
WAD;
BigInt.WAD;

RAY

Returns the common RAY unit, which is also known as 1e9 ether in Solidity

Most commonly used as Aave's index unit

// only if you want to avoid BigInt prototype pollution
import { RAY } from "evm-maths/lib/constants";

// Returns a 1 followed by 27 zeros: 1000000000000000000000000000
RAY;
BigInt.RAY;

PERCENT

Returns the common PERCENT unit, which is also known as 100% in basis points

Most commonly used as Aave's PERCENTAGE_FACTOR

// only if you want to avoid BigInt prototype pollution
import { PERCENT } from "evm-maths/lib/constants";

// Returns a 1 followed by 4 zeros: 10000
PERCENT;
BigInt.PERCENT;

HALF_WAD

Returns half of the common WAD unit, which is also known as 0.5 ether in Solidity

// only if you want to avoid BigInt prototype pollution
import { HALF_WAD } from "evm-maths/lib/constants";

// Returns a 1 followed by 18 zeros: 1000000000000000000
HALF_WAD;
BigInt.HALF_WAD;

HALF_RAY

Returns half of the common RAY unit, which is also known as 0.5e9 ether in Solidity

// only if you want to avoid BigInt prototype pollution
import { HALF_RAY } from "evm-maths/lib/constants";

// Returns a 1 followed by 27 zeros: 1000000000000000000000000000
HALF_RAY;
BigInt.HALF_RAY;

HALF_PERCENT

Returns the common PERCENT unit, which is also known as 50% in basis points

Most commonly used as Aave's HALF_PERCENTAGE_FACTOR

// only if you want to avoid BigInt prototype pollution
import { HALF_PERCENT } from "evm-maths/lib/constants";

// Returns a 1 followed by 4 zeros: 10000
HALF_PERCENT;
BigInt.HALF_PERCENT;

Wad-based utilities

wadMul

Returns the result of the wad-based multiplication (18 decimals precision), rounded half up

BigInt.WAD.wadMul(BigInt.WAD); // 1.0 * 1.0 = 1.0 (in wad)

wadDiv

Returns the result of the wad-based division (18 decimals precision), rounded half up

BigInt.WAD.wadDiv(BigInt.WAD); // 1.0 / 1.0 = 1.0 (in wad)

wadAdd

Returns the result of the addition of a BigNumberish and a wad-based percentage of it (18 decimals), rounded half up

BigInt.WAD.wadAdd(
  BigInt.HALF_WAD, // 50% in wad
); // 1.0 * (1.0 + 0.5) = 1.5 (in wad)

wadSub

Returns the result of the subtraction of a BigNumberish and a wad-based percentage of it (18 decimals), rounded half up

BigInt.WAD.wadSub(
  BigInt.HALF_WAD, // 50% in wad
); // 1.0 * (1.0 - 0.5) = 0.5 (in wad)

wadAvg

Returns the weighted average of 2 BigNumberishs, using a wad-based weight (18 decimals), rounded half up

BigInt.WAD.wadAvg(
  BigInt.WAD * 2n, // 2 WAD
  BigInt.HALF_WAD, // 50% in WAD
); // 1.0 * (1.0 - 0.5) + 2.0 * 0.5 = 1.5 (in wad)

wadPow

Returns the integer power of a BigInt, calculated using wad-based multiplications (18 decimals precision), rounded half up

BigInt.WAD *
  2n // 2 WAD
    .wadPow(2n); // 2.0 ** 2 = 4.0 (in wad)

wadPowUp

Returns the integer power of a BigInt, calculated using wad-based multiplications (4 decimals precision), rounded up

BigInt.PERCENT *
  2n // 200% in wad
    .wadPowUp(2n); // 2.0 ** 2 = 4.0 (in wad)

wadPowDown

Returns the integer power of a BigInt, calculated using wad-based multiplications (18 decimals precision), rounded down

BigInt.PERCENT *
  2n // 200% in wad
    .wadPowDown(2n); // 2.0 ** 2 = 4.0 (in wad)

wadExpTaylorN

Returns the N-th order Taylor polynomial approximation of the integer exp of a BigInt, calculated using wad-based multiplications (18 decimals precision), rounded down

BigInt.PERCENT.wadExpTaylorN(3n); // ~exp(1.0) ~= exp (in wad), using third-order Taylor polynomial

wadMulUp

Returns the result of the wad-based multiplication (18 decimals precision), rounded up

(BigInt.WAD - 1n).wadMulUp(BigInt.WAD - 1n); // 0.999999999999999999 * 0.999999999999999999 = 0.999999999999999999 (in wad, rounded up)

wadMulDown

Returns the result of the wad-based multiplication (18 decimals precision), rounded down

(BigInt.WAD - 1n).wadMulDown(BigInt.WAD - 1n); // 0.999999999999999999 * 0.999999999999999999 = 0.999999999999999998 (in wad, rounded down)

wadDivUp

Returns the result of the wad-based division (18 decimals precision), rounded up

BigInt.WAD.wadDivUp(BigInt.WAD - 1n); // 1.0 * 0.999999999999999999 = 1.000000000000000002 (in wad, rounded up)

wadDivDown

Returns the result of the wad-based division (18 decimals precision), rounded down

BigInt.WAD.wadDivDown(BigInt.WAD - 1n); // 1.0 * 0.999999999999999999 = 1.000000000000000001 (in wad, rounded down)

formatWad

Returns a string representation of the BigInt's value, formatted to 18 decimals and with the input number of digits expected after the unit, truncating the trailing digits if any (default: keep all digits after the decimal point)

BigInt.WAD.formatWad(3); // 1.000

toWadFloat

Returns a float representation of the BigInt's value, parsed as a wad-based number.

Note: parsing a too large value may result in parsing NaN (because the BigInt's value may still be too large to fit in a JS floating-point number)

BigInt.WAD.toWadFloat(); // 1.0

wadToPercent

Scales the wad-based BigInt down to the percent scale (losing 14 decimals)

BigInt.WAD.wadToPercent(); // 1 PERCENT

wadToRay

Scales the wad-based BigInt up to the ray scale (adding 9 decimals)

BigInt.WAD.wadToRay(); // 1 RAY

wadToDecimals

Scales the wad-based BigInt up or down to the given scale defined by its number of decimals

BigInt.WAD.wadToDecimals(27); // 1 RAY

Ray-based utilities

rayMul

Returns the result of the ray-based multiplication (27 decimals precision), rounded half up

BigInt.RAY.rayMul(BigInt.RAY); // 1.0 * 1.0 = 1.0 (in ray)

rayDiv

Returns the result of the ray-based division (27 decimals precision), rounded half up

BigInt.RAY.rayDiv(BigInt.RAY); // 1.0 / 1.0 = 1.0 (in ray)

rayAdd

Returns the result of the addition of a BigNumberish and a ray-based percentage of it (27 decimals), rounded half up

BigInt.RAY.rayAdd(
  BigInt.HALF_RAY, // 50% in ray
); // 1.0 * (1.0 + 0.5) = 1.5 (in ray)

raySub

Returns the result of the subtraction of a BigNumberish and a ray-based percentage of it (27 decimals), rounded half up

BigInt.RAY.raySub(
  BigInt.HALF_RAY, // 50% in ray
); // 1.0 * (1.0 - 0.5) = 0.5 (in ray)

rayAvg

Returns the weighted average of 2 BigNumberishs, using a ray-based weight (27 decimals), rounded half up

BigInt.RAY.rayAvg(
  BigInt.RAY * 2n, // 2 RAY
  BigInt.HALF_RAY, // 50% in RAY
); // 1.0 * (1.0 - 0.5) + 2.0 * 0.5 = 1.5 (in ray)

rayPow

Returns the integer power of a BigInt, calculated using ray-based multiplications (27 decimals precision), rounded half up

(BigInt.RAY * 2n) // 2 RAY
  .rayPow(2n); // 2.0 ** 2 = 4.0 (in ray)

rayPowUp

Returns the integer power of a BigInt, calculated using ray-based multiplications (4 decimals precision), rounded up

BigInt.PERCENT *
  2n // 200% in ray
    .rayPowUp(2n); // 2.0 ** 2 = 4.0 (in ray)

rayPowDown

Returns the integer power of a BigInt, calculated using ray-based multiplications (27 decimals precision), rounded down

BigInt.PERCENT *
  2n // 200% in ray
    .rayPowDown(2n); // 2.0 ** 2 = 4.0 (in ray)

rayExpTaylorN

Returns the N-th order Taylor polynomial approximation of the integer exp of a BigInt, calculated using ray-based multiplications (27 decimals precision), rounded down

BigInt.PERCENT.rayExpTaylorN(3n); // ~exp(1.0) ~= exp (in ray), using third-order Taylor polynomial

rayMulUp

Returns the result of the ray-based multiplication (27 decimals precision), rounded up

(BigInt.RAY - 1n).rayMulUp(BigInt.RAY - 1n); // 0.999999999999999999999999999 * 0.999999999999999999999999999 = 0.999999999999999999999999999 (in ray, rounded up)

rayMulDown

Returns the result of the ray-based multiplication (27 decimals precision), rounded down

(BigInt.RAY - 1n).rayMulDown(BigInt.RAY - 1n); // 0.999999999999999999999999999 * 0.999999999999999999999999999 = 0.999999999999999999999999998 (in ray, rounded down)

rayDivUp

Returns the result of the ray-based division (27 decimals precision), rounded up

BigInt.RAY.rayDivUp(BigInt.RAY - 1n); // 1.0 * 0.999999999999999999999999999 = 1.000000000000000000000000002 (in ray, rounded up)

rayDivDown

Returns the result of the ray-based division (27 decimals precision), rounded down

BigInt.RAY.rayDivDown(BigInt.RAY - 1n); // 1.0 * 0.999999999999999999999999999 = 1.000000000000000000000000001 (in ray, rounded down)

formatRay

Returns a string representation of the BigInt's value, formatted to 27 decimals and with the input number of digits expected after the unit, truncating the trailing digits if any (default: keep all digits after the decimal point)

BigInt.RAY.formatRay(3); // 1.000

toRayFloat

Returns a float representation of the BigInt's value, parsed as a ray-based number.

Note: parsing a too large value may result in parsing NaN (because the BigInt's value may still be too large to fit in a JS floating-point number)

BigInt.RAY.toRayFloat(); // 1.0

rayToPercent

Scales the ray-based BigInt down to the percent scale (losing 23 decimals)

BigInt.RAY.rayToPercent(); // 1 PERCENT

rayToWad

Scales the ray-based BigInt down to the wad scale (losing 9 decimals)

BigInt.RAY.rayToWad(); // 1 WAD

rayToDecimals

Scales the ray-based BigInt up or down to the given scale defined by its number of decimals

BigInt.RAY.rayToDecimals(18); // 1 WAD

Percent-based utilities

percentMul

Returns the result of the percent-based multiplication (4 decimals precision), rounded half up

BigInt.PERCENT.percentMul(BigInt.PERCENT); // 1.0 * 1.0 = 1.0 (in percent)

percentDiv

Returns the result of the percent-based division (4 decimals precision), rounded half up

BigInt.PERCENT.percentDiv(BigInt.PERCENT); // 1.0 / 1.0 = 1.0 (in percent)

percentAdd

Returns the result of the addition of a BigNumberish and a percent-based percentage of it (4 decimals), rounded half up

BigInt.PERCENT.percentAdd(
  BigInt.HALF_PERCENT, // 50% in percent
); // 1.0 * (1.0 + 0.5) = 1.5 (in percent)

percentSub

Returns the result of the subtraction of a BigNumberish and a percent-based percentage of it (4 decimals), rounded half up

BigInt.PERCENT.percentSub(
  BigInt.HALF_PERCENT, // 50% in percent
); // 1.0 * (1.0 - 0.5) = 0.5 (in percent)

percentAvg

Returns the weighted average of 2 BigNumberishs, using a percent-based weight (4 decimals), rounded half up

BigInt.PERCENT.percentAvg(
  BigInt.PERCENT * 2n, // 200% in percent
  BigInt.HALF_PERCENT, // 50% in percent
); // 1.0 * (1.0 - 0.5) + 2.0 * 0.5 = 1.5 (in percent)

percentPow

Returns the integer power of a BigInt, calculated using percent-based multiplications (4 decimals precision), rounded half up

BigInt.PERCENT *
  2n // 200% in percent
    .percentPow(2n); // 2.0 ** 2 = 4.0 (in percent)

percentPowUp

Returns the integer power of a BigInt, calculated using percent-based multiplications (4 decimals precision), rounded up

BigInt.PERCENT *
  2n // 200% in percent
    .percentPowUp(2n); // 2.0 ** 2 = 4.0 (in percent)

percentPowDown

Returns the integer power of a BigInt, calculated using percent-based multiplications (4 decimals precision), rounded down

BigInt.PERCENT *
  2n // 200% in percent
    .percentPowDown(2n); // 2.0 ** 2 = 4.0 (in percent)

percentExpTaylorN

Returns the N-th order Taylor polynomial approximation of the integer exp of a BigInt, calculated using percent-based multiplications (4 decimals precision), rounded down

BigInt.PERCENT.percentExpTaylorN(3n); // ~exp(1.0) ~= exp (in percent), using third-order Taylor polynomial

percentMulUp

Returns the result of the percent-based multiplication (4 decimals precision), rounded up

(BigInt.PERCENT - 1n).percentMulUp(BigInt.PERCENT - 1n); // 0.9999 * 0.9999 = 0.9999 (in percent, rounded up)

percentMulDown

Returns the result of the percent-based multiplication (4 decimals precision), rounded down

(BigInt.PERCENT - 1n).percentMulDown(BigInt.PERCENT - 1n); // 0.9999 * 0.9999 = 0.9998 (in percent, rounded down)

percentDivUp

Returns the result of the percent-based division (4 decimals precision), rounded up

BigInt.PERCENT.percentDivUp(BigInt.PERCENT - 1n); // 1.0 * 0.9999 = 1.0002 (in percent, rounded up)

percentDivDown

Returns the result of the percent-based division (4 decimals precision), rounded down

BigInt.PERCENT.percentDivDown(BigInt.PERCENT - 1n); // 1.0 * 0.9999 = 1.0001 (in percent, rounded down)

formatPercent

Returns a string representation of the BigInt's value, formatted to 4 decimals and with the input number of digits expected after the unit, truncating the trailing digits if any (default: keep all digits after the decimal point)

BigInt.PERCENT.formatPercent(3); // 1.000

toPercentFloat

Returns a float representation of the BigInt's value, parsed as a percent-based number.

Note: parsing a too large value may result in parsing NaN (because the BigInt's value may still be too large to fit in a JS floating-point number)

BigInt.PERCENT.toPercentFloat(); // 1.0

percentToWad

Scales the percent-based BigInt up to the wad scale (adding 14 decimals)

BigInt.PERCENT.percentToWad(); // 1 WAD

percentToRay

Scales the percent-based BigInt up to the ray scale (adding 23 decimals)

BigInt.PERCENT.percentToRay(); // 1 RAY

percentToDecimals

Scales the percent-based BigInt up or down to the given scale defined by its number of decimals

BigInt.RAY.percentToDecimals(27); // 1 RAY