- Notifications
You must be signed in to change notification settings - Fork0
➗ Useful bigint math libraries to ease the journey through off-chain fixed-point arithmetics
License
Rubilmax/evm-maths
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
➗ Useful bigint math libraries to ease your journey through off-chain fixed-point arithmetics
npm install evm-maths
yarn add evm-maths
Just import the module and you'll benefit from an augmented, and typed,BigInt class!
import"evm-maths";constWAD=BigInt.pow10(18);BigInt.from(1).wadMul(WAD);// 1BigInt.from(WAD*2n).rayMul(0.5e27);// WAD
If you choose to avoid prototype pollution, you can always import specific utilities:
import*asWadMathfrom"evm-maths/lib/wad";import*asRayMathfrom"evm-maths/lib/ray";import*asPercentMathfrom"evm-maths/lib/percent";
- Scale-agnostic utilities
- Scale constants
- Wad-based utilities
- Ray-based utilities
- Percent-based utilities
Returns whether the BigNumber is approximately close to the given BigNumber, within the given tolerance
// only if you want to avoid BigNumber prototype pollutionimport{approxEqAbs}from"evm-maths/lib/utils";// Returns whether the BigNumber is approximately close to the given BigNumber, within the given tolerance: trueapproxEqAbs(0,1,"1");BigNumber.approxEqAbs(0,1,"1");BigNumber.from(0).approxEqAbs(1,"1");
Returns the minimum between input BigNumberish, as a BigInt
// only if you want to avoid BigInt prototype pollutionimport{min}from"evm-maths/lib/utils";// Returns the minimum between input BigNumberish, as a BigInt: 0min(0,1,"2", ...);BigInt.min(0,1,"2", ...);BigInt.from(0).min(1,"2", ...);
Returns the maximum between input BigNumberish, as a BigInt
// only if you want to avoid BigInt prototype pollutionimport{max}from"evm-maths/lib/utils";// Returns the maximum between input BigNumberish, as a BigInt: 2max(0,1,"2", ...);BigInt.max(0,1,"2", ...);BigInt.from(0).max(1,"2", ...);
Returns the sum of input BigNumberish array, as a BigInt
// only if you want to avoid BigInt prototype pollutionimport{sum}from"evm-maths/lib/utils";// Returns the sum of input BigNumberish array, as a BigInt: 3sum([0,1,"2"]);BigInt.sum([0,1,"2"]);BigInt.from(0).sum([1,"2"]);
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.01BigInt.from(19).format(3,2);
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 parsingNaN (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.01BigInt.from(19).toFloat(3,2);
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 pollutionimport{pow10}from"evm-maths/lib/utils";// Returns a 1 followed by the input number of zeros: 100pow10(2);BigInt.pow10(2);
Performs a multiplication followed by a division, rounded half up
// only if you want to avoid BigInt prototype pollutionimport{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);
Performs a multiplication followed by a division, rounded up
// only if you want to avoid BigInt prototype pollutionimport{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);
Performs a multiplication followed by a division, rounded down
// only if you want to avoid BigInt prototype pollutionimport{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);
Returns the common WAD unit, which is also known asether in Solidity
Most commonly used as the ERC20 token unit
// only if you want to avoid BigInt prototype pollutionimport{WAD}from"evm-maths/lib/constants";// Returns a 1 followed by 18 zeros: 1000000000000000000WAD;BigInt.WAD;
Returns the common RAY unit, which is also known as1e9 ether in Solidity
Most commonly used as Aave's index unit
// only if you want to avoid BigInt prototype pollutionimport{RAY}from"evm-maths/lib/constants";// Returns a 1 followed by 27 zeros: 1000000000000000000000000000RAY;BigInt.RAY;
Returns the common PERCENT unit, which is also known as100% in basis points
Most commonly used as Aave'sPERCENTAGE_FACTOR
// only if you want to avoid BigInt prototype pollutionimport{PERCENT}from"evm-maths/lib/constants";// Returns a 1 followed by 4 zeros: 10000PERCENT;BigInt.PERCENT;
Returns half of the common WAD unit, which is also known as0.5 ether in Solidity
// only if you want to avoid BigInt prototype pollutionimport{HALF_WAD}from"evm-maths/lib/constants";// Returns a 1 followed by 18 zeros: 1000000000000000000HALF_WAD;BigInt.HALF_WAD;
Returns half of the common RAY unit, which is also known as0.5e9 ether in Solidity
// only if you want to avoid BigInt prototype pollutionimport{HALF_RAY}from"evm-maths/lib/constants";// Returns a 1 followed by 27 zeros: 1000000000000000000000000000HALF_RAY;BigInt.HALF_RAY;
Returns the common PERCENT unit, which is also known as50% in basis points
Most commonly used as Aave'sHALF_PERCENTAGE_FACTOR
// only if you want to avoid BigInt prototype pollutionimport{HALF_PERCENT}from"evm-maths/lib/constants";// Returns a 1 followed by 4 zeros: 10000HALF_PERCENT;BigInt.HALF_PERCENT;
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)
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)
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)
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)
Returns the weighted average of 2 BigNumberishs, using a wad-based weight (18 decimals), rounded half up
BigInt.WAD.wadAvg(BigInt.WAD*2n,// 2 WADBigInt.HALF_WAD,// 50% in WAD);// 1.0 * (1.0 - 0.5) + 2.0 * 0.5 = 1.5 (in wad)
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)
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)
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)
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
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)
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)
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)
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)
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
Returns a float representation of the BigInt's value, parsed as a wad-based number.
Note: parsing a too large value may result in parsingNaN (because the BigInt's value may still be too large to fit in a JS floating-point number)
BigInt.WAD.toWadFloat();// 1.0
Scales the wad-based BigInt down to the percent scale (losing 14 decimals)
BigInt.WAD.wadToPercent();// 1 PERCENT
Scales the wad-based BigInt up to the ray scale (adding 9 decimals)
BigInt.WAD.wadToRay();// 1 RAY
Scales the wad-based BigInt up or down to the given scale defined by its number of decimals
BigInt.WAD.wadToDecimals(27);// 1 RAY
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)
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)
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)
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)
Returns the weighted average of 2 BigNumberishs, using a ray-based weight (27 decimals), rounded half up
BigInt.RAY.rayAvg(BigInt.RAY*2n,// 2 RAYBigInt.HALF_RAY,// 50% in RAY);// 1.0 * (1.0 - 0.5) + 2.0 * 0.5 = 1.5 (in ray)
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)
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)
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)
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
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)
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)
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)
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)
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
Returns a float representation of the BigInt's value, parsed as a ray-based number.
Note: parsing a too large value may result in parsingNaN (because the BigInt's value may still be too large to fit in a JS floating-point number)
BigInt.RAY.toRayFloat();// 1.0
Scales the ray-based BigInt down to the percent scale (losing 23 decimals)
BigInt.RAY.rayToPercent();// 1 PERCENT
Scales the ray-based BigInt down to the wad scale (losing 9 decimals)
BigInt.RAY.rayToWad();// 1 WAD
Scales the ray-based BigInt up or down to the given scale defined by its number of decimals
BigInt.RAY.rayToDecimals(18);// 1 WAD
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)
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)
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)
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)
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 percentBigInt.HALF_PERCENT,// 50% in percent);// 1.0 * (1.0 - 0.5) + 2.0 * 0.5 = 1.5 (in percent)
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)
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)
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)
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
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)
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)
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)
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)
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
Returns a float representation of the BigInt's value, parsed as a percent-based number.
Note: parsing a too large value may result in parsingNaN (because the BigInt's value may still be too large to fit in a JS floating-point number)
BigInt.PERCENT.toPercentFloat();// 1.0
Scales the percent-based BigInt up to the wad scale (adding 14 decimals)
BigInt.PERCENT.percentToWad();// 1 WAD
Scales the percent-based BigInt up to the ray scale (adding 23 decimals)
BigInt.PERCENT.percentToRay();// 1 RAY
Scales the percent-based BigInt up or down to the given scale defined by its number of decimals
BigInt.RAY.percentToDecimals(27);// 1 RAY
About
➗ Useful bigint math libraries to ease the journey through off-chain fixed-point arithmetics
Topics
Resources
License
Uh oh!
There was an error while loading.Please reload this page.
Stars
Watchers
Forks
Uh oh!
There was an error while loading.Please reload this page.
Contributors2
Uh oh!
There was an error while loading.Please reload this page.