ethers-maths
Advanced tools
➗ Useful ethers-based math libraries to ease the journey through off-chain fixed-point arithmetics
➗ Useful ethers-based math libraries to ease your journey through off-chain fixed-point arithmetics
npm install ethers-maths
yarn add ethers-maths
Just import the module and you'll benefit from an augmented, and typed, BigInt class!
import "ethers-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 "ethers-maths/lib/wad";
import * as RayMath from "ethers-maths/lib/ray";
import * as PercentMath from "ethers-maths/lib/percent";
approxEqAbsReturns 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 "ethers-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");
minReturns the minimum between input BigNumberish, as a BigInt
// only if you want to avoid BigInt prototype pollution
import { min } from "ethers-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", ...);
maxReturns the maximum between input BigNumberish, as a BigInt
// only if you want to avoid BigInt prototype pollution
import { max } from "ethers-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", ...);
sumReturns the sum of input BigNumberish array, as a BigInt
// only if you want to avoid BigInt prototype pollution
import { sum } from "ethers-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"]);
formatReturns a string representation of the BigInt's value, formatted according to:
// Returns a string representation of the BigInt's value: 0.01
BigInt.from(19).format(3, 2);
toFloatReturns 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);
pow10Returns 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 "ethers-maths/lib/utils";
// Returns a 1 followed by the input number of zeros: 100
pow10(2);
BigInt.pow10(2);
mulDivPerforms a multiplication followed by a division, rounded half up
// only if you want to avoid BigInt prototype pollution
import { mulDivHalfUp } from "ethers-maths/lib/utils";
// 1.0 (in wad) * 1 / 1 = 1.0 (in wad)
mulDivHalfUp(BigInt.WAD, 1, 1);
BigInt.WAD.mulDiv(1, 1);
mulDivUpPerforms a multiplication followed by a division, rounded up
// only if you want to avoid BigInt prototype pollution
import { mulDivUp } from "ethers-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);
mulDivDownPerforms a multiplication followed by a division, rounded down
// only if you want to avoid BigInt prototype pollution
import { mulDivDown } from "ethers-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);
WADReturns 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 "ethers-maths/lib/constants";
// Returns a 1 followed by 18 zeros: 1000000000000000000
WAD;
BigInt.WAD;
RAYReturns 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 "ethers-maths/lib/constants";
// Returns a 1 followed by 27 zeros: 1000000000000000000000000000
RAY;
BigInt.RAY;
PERCENTReturns 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 "ethers-maths/lib/constants";
// Returns a 1 followed by 4 zeros: 10000
PERCENT;
BigInt.PERCENT;
HALF_WADReturns 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 "ethers-maths/lib/constants";
// Returns a 1 followed by 18 zeros: 1000000000000000000
HALF_WAD;
BigInt.HALF_WAD;
HALF_RAYReturns 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 "ethers-maths/lib/constants";
// Returns a 1 followed by 27 zeros: 1000000000000000000000000000
HALF_RAY;
BigInt.HALF_RAY;
HALF_PERCENTReturns 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 "ethers-maths/lib/constants";
// Returns a 1 followed by 4 zeros: 10000
HALF_PERCENT;
BigInt.HALF_PERCENT;
wadMulReturns 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)
wadDivReturns 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)
wadAddReturns 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)
wadSubReturns 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)
wadAvgReturns 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)
wadPowReturns the integer power of a BigInt, calculated using wad-based multiplications (18 decimals precision), rounded half up
BigInt.WAD *
2n // 2 WAD
.wadPow(2); // 2.0 ** 2 = 4.0 (in wad)
wadPowUpReturns the integer power of a BigInt, calculated using wad-based multiplications (4 decimals precision), rounded up
BigInt.PERCENT *
2n // 200% in wad
.wadPowUp(2); // 2.0 ** 2 = 4.0 (in wad)
wadPowDownReturns the integer power of a BigInt, calculated using wad-based multiplications (4 decimals precision), rounded down
BigInt.PERCENT *
2n // 200% in wad
.wadPowDown(2); // 2.0 ** 2 = 4.0 (in wad)
wadExpNReturns the N-th order Taylor polynomial approximation of the integer exp of a BigInt, calculated using wad-based multiplications (4 decimals precision), rounded down
BigInt.PERCENT.wadExpN(3); // ~exp(1.0) ~= exp (in wad), using third-order Taylor polynomial
wadMulUpReturns 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)
wadMulDownReturns 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)
wadDivUpReturns 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)
wadDivDownReturns 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)
formatWadReturns 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
toWadFloatReturns 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
wadToPercentScales the wad-based BigInt down to the percent scale (losing 14 decimals)
BigInt.WAD.wadToPercent(); // 1 PERCENT
wadToRayScales the wad-based BigInt up to the ray scale (adding 9 decimals)
BigInt.WAD.wadToRay(); // 1 RAY
wadToDecimalsScales the wad-based BigInt up or down to the given scale defined by its number of decimals
BigInt.WAD.wadToDecimals(27); // 1 RAY
rayMulReturns 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)
rayDivReturns 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)
rayAddReturns 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)
raySubReturns 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)
rayAvgReturns 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)
rayPowReturns the integer power of a BigInt, calculated using ray-based multiplications (27 decimals precision), rounded half up
(BigInt.RAY * 2n) // 2 RAY
.rayPow(2); // 2.0 ** 2 = 4.0 (in ray)
rayPowUpReturns the integer power of a BigInt, calculated using ray-based multiplications (4 decimals precision), rounded up
BigInt.PERCENT *
2n // 200% in ray
.rayPowUp(2); // 2.0 ** 2 = 4.0 (in ray)
rayPowDownReturns the integer power of a BigInt, calculated using ray-based multiplications (4 decimals precision), rounded down
BigInt.PERCENT *
2n // 200% in ray
.rayPowDown(2); // 2.0 ** 2 = 4.0 (in ray)
rayExpNReturns the N-th order Taylor polynomial approximation of the integer exp of a BigInt, calculated using ray-based multiplications (4 decimals precision), rounded down
BigInt.PERCENT.rayExpN(3); // ~exp(1.0) ~= exp (in ray), using third-order Taylor polynomial
rayMulUpReturns 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)
rayMulDownReturns 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)
rayDivUpReturns 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)
rayDivDownReturns 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)
formatRayReturns 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
toRayFloatReturns 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
rayToPercentScales the ray-based BigInt down to the percent scale (losing 23 decimals)
BigInt.RAY.rayToPercent(); // 1 PERCENT
rayToWadScales the ray-based BigInt down to the wad scale (losing 9 decimals)
BigInt.RAY.rayToWad(); // 1 WAD
rayToDecimalsScales the ray-based BigInt up or down to the given scale defined by its number of decimals
BigInt.RAY.rayToDecimals(18); // 1 WAD
percentMulReturns 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)
percentDivReturns 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)
percentAddReturns 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)
percentSubReturns 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)
percentAvgReturns 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)
percentPowReturns the integer power of a BigInt, calculated using percent-based multiplications (4 decimals precision), rounded half up
BigInt.PERCENT *
2n // 200% in percent
.percentPow(2); // 2.0 ** 2 = 4.0 (in percent)
percentPowUpReturns the integer power of a BigInt, calculated using percent-based multiplications (4 decimals precision), rounded up
BigInt.PERCENT *
2n // 200% in percent
.percentPowUp(2); // 2.0 ** 2 = 4.0 (in percent)
percentPowDownReturns the integer power of a BigInt, calculated using percent-based multiplications (4 decimals precision), rounded down
BigInt.PERCENT *
2n // 200% in percent
.percentPowDown(2); // 2.0 ** 2 = 4.0 (in percent)
percentExpNReturns 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.percentExpN(3); // ~exp(1.0) ~= exp (in percent), using third-order Taylor polynomial
percentMulUpReturns 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)
percentMulDownReturns 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)
percentDivUpReturns 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)
percentDivDownReturns 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)
formatPercentReturns 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
toPercentFloatReturns 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
percentToWadScales the percent-based BigInt up to the wad scale (adding 14 decimals)
BigInt.PERCENT.percentToWad(); // 1 WAD
percentToRayScales the percent-based BigInt up to the ray scale (adding 23 decimals)
BigInt.PERCENT.percentToRay(); // 1 RAY
percentToDecimalsScales the percent-based BigInt up or down to the given scale defined by its number of decimals
BigInt.RAY.percentToDecimals(27); // 1 RAY
FAQs
➗ Useful ethers-based math libraries to ease the journey through off-chain fixed-point arithmetics
We found that ethers-maths demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
TypeScript is porting its compiler to Go, delivering 10x faster builds, lower memory usage, and improved editor performance for a smoother developer experience.
Research
Security News
The Socket Research Team has discovered six new malicious npm packages linked to North Korea’s Lazarus Group, designed to steal credentials and deploy backdoors.
Security News
Socket CEO Feross Aboukhadijeh discusses the open web, open source security, and how Socket tackles software supply chain attacks on The Pair Program podcast.