{"id":15679007,"url":"https://github.com/rubilmax/evm-maths","last_synced_at":"2025-08-16T23:38:40.755Z","repository":{"id":61358405,"uuid":"550102806","full_name":"Rubilmax/evm-maths","owner":"Rubilmax","description":"➗ Useful bigint math libraries to ease the journey through off-chain fixed-point arithmetics","archived":false,"fork":false,"pushed_at":"2024-11-22T11:13:24.000Z","size":585,"stargazers_count":15,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-19T11:41:16.317Z","etag":null,"topics":["aave","bigint","bignumbers","comp","compound","div","ethers","evm","maths","mul","ray","solidity","typescript","utils","viem","wad","wagmi"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Rubilmax.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-10-12T07:57:10.000Z","updated_at":"2025-02-23T11:42:21.000Z","dependencies_parsed_at":"2023-11-29T16:25:16.838Z","dependency_job_id":"c566f21e-30d5-4fbe-94bd-7339dc77fcf5","html_url":"https://github.com/Rubilmax/evm-maths","commit_stats":{"total_commits":66,"total_committers":2,"mean_commits":33.0,"dds":"0.045454545454545414","last_synced_commit":"a88a61ffd578253cb60f19f4fbdf21bfad8a27bd"},"previous_names":["rubilmax/evm-maths","rubilmax/ethers-maths"],"tags_count":42,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Rubilmax%2Fevm-maths","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Rubilmax%2Fevm-maths/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Rubilmax%2Fevm-maths/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Rubilmax%2Fevm-maths/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Rubilmax","download_url":"https://codeload.github.com/Rubilmax/evm-maths/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246034300,"owners_count":20712857,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aave","bigint","bignumbers","comp","compound","div","ethers","evm","maths","mul","ray","solidity","typescript","utils","viem","wad","wagmi"],"created_at":"2024-10-03T16:25:56.087Z","updated_at":"2025-03-30T10:31:14.597Z","avatar_url":"https://github.com/Rubilmax.png","language":"TypeScript","readme":"# evm-maths\n\n[![npm package][npm-img]][npm-url]\n[![Build Status][build-img]][build-url]\n[![Test Status][test-img]][test-url]\n[![Downloads][downloads-img]][downloads-url]\n[![Issues][issues-img]][issues-url]\n[![Commitizen Friendly][commitizen-img]][commitizen-url]\n[![Semantic Release][semantic-release-img]][semantic-release-url]\n\n\u003e ➗ Useful bigint math libraries to ease your journey through off-chain fixed-point arithmetics\n\n## Install\n\n```bash\nnpm install evm-maths\n```\n\n```bash\nyarn add evm-maths\n```\n\n---\n\n## Usage\n\nJust import the module and you'll benefit from an augmented, and typed, `BigInt` class!\n\n```typescript\nimport \"evm-maths\";\n\nconst WAD = BigInt.pow10(18);\n\nBigInt.from(1).wadMul(WAD); // 1\nBigInt.from(WAD * 2n).rayMul(0.5e27); // WAD\n```\n\nIf you choose to avoid prototype pollution, you can always import specific utilities:\n\n```typescript\nimport * as WadMath from \"evm-maths/lib/wad\";\nimport * as RayMath from \"evm-maths/lib/ray\";\nimport * as PercentMath from \"evm-maths/lib/percent\";\n```\n\n---\n\n## Book\n\n- [Scale-agnostic utilities](#scale-agnostic-utilities)\n  - [approxEqAbs](#approxEqAbs)\n  - [min](#min)\n  - [max](#max)\n  - [sum](#sum)\n  - [format](#format)\n  - [toFloat](#toFloat)\n  - [pow10](#pow10)\n  - [mulDiv](#mulDiv)\n  - [mulDivUp](#mulDivUp)\n  - [mulDivDown](#mulDivDown)\n- [Scale constants](#scale-constants)\n  - [WAD](#WAD)\n  - [RAY](#RAY)\n  - [PERCENT](#PERCENT)\n  - [HALF_WAD](#HALF_WAD)\n  - [HALF_RAY](#HALF_RAY)\n  - [HALF_PERCENT](#HALF_PERCENT)\n- [Wad-based utilities](#wad-based-utilities)\n  - [wadMul](#wadMul)\n  - [wadDiv](#wadDiv)\n  - [wadAdd](#wadAdd)\n  - [wadSub](#wadSub)\n  - [wadAvg](#wadAvg)\n  - [wadPow](#wadPow)\n  - [wadPowUp](#wadPowUp)\n  - [wadPowDown](#wadPowDown)\n  - [wadExpTaylorN](#wadExpTaylorN)\n  - [wadMulUp](#wadMulUp)\n  - [wadMulDown](#wadMulDown)\n  - [wadDivUp](#wadDivUp)\n  - [wadDivDown](#wadDivDown)\n  - [formatWad](#formatWad)\n  - [toWadFloat](#toWadFloat)\n  - [wadToPercent](#wadToPercent)\n  - [wadToRay](#wadToRay)\n  - [wadToDecimals](#wadToDecimals)\n- [Ray-based utilities](#ray-based-utilities)\n  - [rayMul](#rayMul)\n  - [rayDiv](#rayDiv)\n  - [rayAdd](#rayAdd)\n  - [raySub](#raySub)\n  - [rayAvg](#rayAvg)\n  - [rayPow](#rayPow)\n  - [rayPowUp](#rayPowUp)\n  - [rayPowDown](#rayPowDown)\n  - [rayExpTaylorN](#rayExpTaylorN)\n  - [rayMulUp](#rayMulUp)\n  - [rayMulDown](#rayMulDown)\n  - [rayDivUp](#rayDivUp)\n  - [rayDivDown](#rayDivDown)\n  - [formatRay](#formatRay)\n  - [toRayFloat](#toRayFloat)\n  - [rayToPercent](#rayToPercent)\n  - [rayToWad](#rayToWad)\n  - [rayToDecimals](#rayToDecimals)\n- [Percent-based utilities](#percent-based-utilities)\n  - [percentMul](#percentMul)\n  - [percentDiv](#percentDiv)\n  - [percentAdd](#percentAdd)\n  - [percentSub](#percentSub)\n  - [percentAvg](#percentAvg)\n  - [percentPow](#percentPow)\n  - [percentPowUp](#percentPowUp)\n  - [percentPowDown](#percentPowDown)\n  - [percentExpTaylorN](#percentExpTaylorN)\n  - [percentMulUp](#percentMulUp)\n  - [percentMulDown](#percentMulDown)\n  - [percentDivUp](#percentDivUp)\n  - [percentDivDown](#percentDivDown)\n  - [formatPercent](#formatPercent)\n  - [toPercentFloat](#toPercentFloat)\n  - [percentToWad](#percentToWad)\n  - [percentToRay](#percentToRay)\n  - [percentToDecimals](#percentToDecimals)\n\n---\n\n### Scale-agnostic utilities\n\n#### `approxEqAbs`\n\nReturns whether the BigNumber is approximately close to the given BigNumber, within the given tolerance\n\n```typescript\n// only if you want to avoid BigNumber prototype pollution\nimport { approxEqAbs } from \"evm-maths/lib/utils\";\n\n// Returns whether the BigNumber is approximately close to the given BigNumber, within the given tolerance: true\napproxEqAbs(0, 1, \"1\");\nBigNumber.approxEqAbs(0, 1, \"1\");\nBigNumber.from(0).approxEqAbs(1, \"1\");\n```\n\n#### `min`\n\nReturns the minimum between input BigNumberish, as a BigInt\n\n```typescript\n// only if you want to avoid BigInt prototype pollution\nimport { min } from \"evm-maths/lib/utils\";\n\n// Returns the minimum between input BigNumberish, as a BigInt: 0\nmin(0, 1, \"2\", ...);\nBigInt.min(0, 1, \"2\", ...);\nBigInt.from(0).min(1, \"2\", ...);\n```\n\n#### `max`\n\nReturns the maximum between input BigNumberish, as a BigInt\n\n```typescript\n// only if you want to avoid BigInt prototype pollution\nimport { max } from \"evm-maths/lib/utils\";\n\n// Returns the maximum between input BigNumberish, as a BigInt: 2\nmax(0, 1, \"2\", ...);\nBigInt.max(0, 1, \"2\", ...);\nBigInt.from(0).max(1, \"2\", ...);\n```\n\n#### `sum`\n\nReturns the sum of input BigNumberish array, as a BigInt\n\n```typescript\n// only if you want to avoid BigInt prototype pollution\nimport { sum } from \"evm-maths/lib/utils\";\n\n// Returns the sum of input BigNumberish array, as a BigInt: 3\nsum([0, 1, \"2\"]);\nBigInt.sum([0, 1, \"2\"]);\nBigInt.from(0).sum([1, \"2\"]);\n```\n\n#### `format`\n\nReturns a string representation of the BigInt's value, formatted according to:\n\n- the input number of decimals the BigInt value holds (default: 0)\n- the input number of digits expected after the unit, truncating the trailing digits if any (default: keep all digits after the decimal point)\n\n```typescript\n// Returns a string representation of the BigInt's value: 0.01\nBigInt.from(19).format(3, 2);\n```\n\n#### `toFloat`\n\nReturns a float representation of the BigInt's value, parsed according to the input number of decimals the BigInt value holds (default: 0)\n\nNote: 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)\n\n```typescript\n// Returns a string representation of the BigInt's value: 0.01\nBigInt.from(19).toFloat(3, 2);\n```\n\n#### `pow10`\n\nReturns a 1 followed by the input number of zeros (10 raised to the power of the input)\n\n```typescript\n// only if you want to avoid BigInt prototype pollution\nimport { pow10 } from \"evm-maths/lib/utils\";\n\n// Returns a 1 followed by the input number of zeros: 100\npow10(2);\nBigInt.pow10(2);\n```\n\n#### `mulDiv`\n\nPerforms a multiplication followed by a division, rounded half up\n\n```typescript\n// only if you want to avoid BigInt prototype pollution\nimport { mulDivHalfUp } from \"evm-maths/lib/utils\";\n\n// 1.0 (in wad) * 1 / 1 = 1.0 (in wad)\nmulDivHalfUp(BigInt.WAD, 1, 1);\nBigInt.WAD.mulDiv(1, 1);\n```\n\n#### `mulDivUp`\n\nPerforms a multiplication followed by a division, rounded up\n\n```typescript\n// only if you want to avoid BigInt prototype pollution\nimport { mulDivUp } from \"evm-maths/lib/utils\";\n\n// 0.999999999999999999 * 1 / WAD = 1.0 (in wad, rounded up)\nmulDivUp(BigInt.WAD - 1n, 1, BigInt.WAD);\n(BigInt.WAD - 1n).mulDivUp(1, BigInt.WAD);\n```\n\n#### `mulDivDown`\n\nPerforms a multiplication followed by a division, rounded down\n\n```typescript\n// only if you want to avoid BigInt prototype pollution\nimport { mulDivDown } from \"evm-maths/lib/utils\";\n\n// 1.000000000000000001 * 1 / WAD = 1.0 (in wad, rounded down)\nmulDivDown(BigInt.WAD + 1n, 1, BigInt.WAD);\n(BigInt.WAD + 1n).mulDivDown(1, BigInt.WAD);\n```\n\n---\n\n### Scale constants\n\n#### `WAD`\n\nReturns the common WAD unit, which is also known as `ether` in Solidity\n\n_Most commonly used as the ERC20 token unit_\n\n```typescript\n// only if you want to avoid BigInt prototype pollution\nimport { WAD } from \"evm-maths/lib/constants\";\n\n// Returns a 1 followed by 18 zeros: 1000000000000000000\nWAD;\nBigInt.WAD;\n```\n\n#### `RAY`\n\nReturns the common RAY unit, which is also known as `1e9 ether` in Solidity\n\n_Most commonly used as Aave's index unit_\n\n```typescript\n// only if you want to avoid BigInt prototype pollution\nimport { RAY } from \"evm-maths/lib/constants\";\n\n// Returns a 1 followed by 27 zeros: 1000000000000000000000000000\nRAY;\nBigInt.RAY;\n```\n\n#### `PERCENT`\n\nReturns the common PERCENT unit, which is also known as `100%` in basis points\n\n_Most commonly used as Aave's `PERCENTAGE_FACTOR`_\n\n```typescript\n// only if you want to avoid BigInt prototype pollution\nimport { PERCENT } from \"evm-maths/lib/constants\";\n\n// Returns a 1 followed by 4 zeros: 10000\nPERCENT;\nBigInt.PERCENT;\n```\n\n#### `HALF_WAD`\n\nReturns half of the common WAD unit, which is also known as `0.5 ether` in Solidity\n\n```typescript\n// only if you want to avoid BigInt prototype pollution\nimport { HALF_WAD } from \"evm-maths/lib/constants\";\n\n// Returns a 1 followed by 18 zeros: 1000000000000000000\nHALF_WAD;\nBigInt.HALF_WAD;\n```\n\n#### `HALF_RAY`\n\nReturns half of the common RAY unit, which is also known as `0.5e9 ether` in Solidity\n\n```typescript\n// only if you want to avoid BigInt prototype pollution\nimport { HALF_RAY } from \"evm-maths/lib/constants\";\n\n// Returns a 1 followed by 27 zeros: 1000000000000000000000000000\nHALF_RAY;\nBigInt.HALF_RAY;\n```\n\n#### `HALF_PERCENT`\n\nReturns the common PERCENT unit, which is also known as `50%` in basis points\n\n_Most commonly used as Aave's `HALF_PERCENTAGE_FACTOR`_\n\n```typescript\n// only if you want to avoid BigInt prototype pollution\nimport { HALF_PERCENT } from \"evm-maths/lib/constants\";\n\n// Returns a 1 followed by 4 zeros: 10000\nHALF_PERCENT;\nBigInt.HALF_PERCENT;\n```\n\n---\n\n### Wad-based utilities\n\n#### `wadMul`\n\nReturns the result of the wad-based multiplication (18 decimals precision), rounded half up\n\n```typescript\nBigInt.WAD.wadMul(BigInt.WAD); // 1.0 * 1.0 = 1.0 (in wad)\n```\n\n#### `wadDiv`\n\nReturns the result of the wad-based division (18 decimals precision), rounded half up\n\n```typescript\nBigInt.WAD.wadDiv(BigInt.WAD); // 1.0 / 1.0 = 1.0 (in wad)\n```\n\n#### `wadAdd`\n\nReturns the result of the addition of a BigNumberish and a wad-based percentage of it (18 decimals), rounded half up\n\n```typescript\nBigInt.WAD.wadAdd(\n  BigInt.HALF_WAD, // 50% in wad\n); // 1.0 * (1.0 + 0.5) = 1.5 (in wad)\n```\n\n#### `wadSub`\n\nReturns the result of the subtraction of a BigNumberish and a wad-based percentage of it (18 decimals), rounded half up\n\n```typescript\nBigInt.WAD.wadSub(\n  BigInt.HALF_WAD, // 50% in wad\n); // 1.0 * (1.0 - 0.5) = 0.5 (in wad)\n```\n\n#### `wadAvg`\n\nReturns the weighted average of 2 BigNumberishs, using a wad-based weight (18 decimals), rounded half up\n\n```typescript\nBigInt.WAD.wadAvg(\n  BigInt.WAD * 2n, // 2 WAD\n  BigInt.HALF_WAD, // 50% in WAD\n); // 1.0 * (1.0 - 0.5) + 2.0 * 0.5 = 1.5 (in wad)\n```\n\n#### `wadPow`\n\nReturns the integer power of a BigInt, calculated using wad-based multiplications (18 decimals precision), rounded half up\n\n```typescript\nBigInt.WAD *\n  2n // 2 WAD\n    .wadPow(2n); // 2.0 ** 2 = 4.0 (in wad)\n```\n\n#### `wadPowUp`\n\nReturns the integer power of a BigInt, calculated using wad-based multiplications (4 decimals precision), rounded up\n\n```typescript\nBigInt.PERCENT *\n  2n // 200% in wad\n    .wadPowUp(2n); // 2.0 ** 2 = 4.0 (in wad)\n```\n\n#### `wadPowDown`\n\nReturns the integer power of a BigInt, calculated using wad-based multiplications (18 decimals precision), rounded down\n\n```typescript\nBigInt.PERCENT *\n  2n // 200% in wad\n    .wadPowDown(2n); // 2.0 ** 2 = 4.0 (in wad)\n```\n\n#### `wadExpTaylorN`\n\nReturns the N-th order Taylor polynomial approximation of the integer exp of a BigInt, calculated using wad-based multiplications (18 decimals precision), rounded down\n\n```typescript\nBigInt.PERCENT.wadExpTaylorN(3n); // ~exp(1.0) ~= exp (in wad), using third-order Taylor polynomial\n```\n\n#### `wadMulUp`\n\nReturns the result of the wad-based multiplication (18 decimals precision), rounded up\n\n```typescript\n(BigInt.WAD - 1n).wadMulUp(BigInt.WAD - 1n); // 0.999999999999999999 * 0.999999999999999999 = 0.999999999999999999 (in wad, rounded up)\n```\n\n#### `wadMulDown`\n\nReturns the result of the wad-based multiplication (18 decimals precision), rounded down\n\n```typescript\n(BigInt.WAD - 1n).wadMulDown(BigInt.WAD - 1n); // 0.999999999999999999 * 0.999999999999999999 = 0.999999999999999998 (in wad, rounded down)\n```\n\n#### `wadDivUp`\n\nReturns the result of the wad-based division (18 decimals precision), rounded up\n\n```typescript\nBigInt.WAD.wadDivUp(BigInt.WAD - 1n); // 1.0 * 0.999999999999999999 = 1.000000000000000002 (in wad, rounded up)\n```\n\n#### `wadDivDown`\n\nReturns the result of the wad-based division (18 decimals precision), rounded down\n\n```typescript\nBigInt.WAD.wadDivDown(BigInt.WAD - 1n); // 1.0 * 0.999999999999999999 = 1.000000000000000001 (in wad, rounded down)\n```\n\n#### `formatWad`\n\nReturns 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)\n\n```typescript\nBigInt.WAD.formatWad(3); // 1.000\n```\n\n#### `toWadFloat`\n\nReturns a float representation of the BigInt's value, parsed as a wad-based number.\n\nNote: 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)\n\n```typescript\nBigInt.WAD.toWadFloat(); // 1.0\n```\n\n#### `wadToPercent`\n\nScales the wad-based BigInt down to the percent scale (losing 14 decimals)\n\n```typescript\nBigInt.WAD.wadToPercent(); // 1 PERCENT\n```\n\n#### `wadToRay`\n\nScales the wad-based BigInt up to the ray scale (adding 9 decimals)\n\n```typescript\nBigInt.WAD.wadToRay(); // 1 RAY\n```\n\n#### `wadToDecimals`\n\nScales the wad-based BigInt up or down to the given scale defined by its number of decimals\n\n```typescript\nBigInt.WAD.wadToDecimals(27); // 1 RAY\n```\n\n---\n\n### Ray-based utilities\n\n#### `rayMul`\n\nReturns the result of the ray-based multiplication (27 decimals precision), rounded half up\n\n```typescript\nBigInt.RAY.rayMul(BigInt.RAY); // 1.0 * 1.0 = 1.0 (in ray)\n```\n\n#### `rayDiv`\n\nReturns the result of the ray-based division (27 decimals precision), rounded half up\n\n```typescript\nBigInt.RAY.rayDiv(BigInt.RAY); // 1.0 / 1.0 = 1.0 (in ray)\n```\n\n#### `rayAdd`\n\nReturns the result of the addition of a BigNumberish and a ray-based percentage of it (27 decimals), rounded half up\n\n```typescript\nBigInt.RAY.rayAdd(\n  BigInt.HALF_RAY, // 50% in ray\n); // 1.0 * (1.0 + 0.5) = 1.5 (in ray)\n```\n\n#### `raySub`\n\nReturns the result of the subtraction of a BigNumberish and a ray-based percentage of it (27 decimals), rounded half up\n\n```typescript\nBigInt.RAY.raySub(\n  BigInt.HALF_RAY, // 50% in ray\n); // 1.0 * (1.0 - 0.5) = 0.5 (in ray)\n```\n\n#### `rayAvg`\n\nReturns the weighted average of 2 BigNumberishs, using a ray-based weight (27 decimals), rounded half up\n\n```typescript\nBigInt.RAY.rayAvg(\n  BigInt.RAY * 2n, // 2 RAY\n  BigInt.HALF_RAY, // 50% in RAY\n); // 1.0 * (1.0 - 0.5) + 2.0 * 0.5 = 1.5 (in ray)\n```\n\n#### `rayPow`\n\nReturns the integer power of a BigInt, calculated using ray-based multiplications (27 decimals precision), rounded half up\n\n```typescript\n(BigInt.RAY * 2n) // 2 RAY\n  .rayPow(2n); // 2.0 ** 2 = 4.0 (in ray)\n```\n\n#### `rayPowUp`\n\nReturns the integer power of a BigInt, calculated using ray-based multiplications (4 decimals precision), rounded up\n\n```typescript\nBigInt.PERCENT *\n  2n // 200% in ray\n    .rayPowUp(2n); // 2.0 ** 2 = 4.0 (in ray)\n```\n\n#### `rayPowDown`\n\nReturns the integer power of a BigInt, calculated using ray-based multiplications (27 decimals precision), rounded down\n\n```typescript\nBigInt.PERCENT *\n  2n // 200% in ray\n    .rayPowDown(2n); // 2.0 ** 2 = 4.0 (in ray)\n```\n\n#### `rayExpTaylorN`\n\nReturns the N-th order Taylor polynomial approximation of the integer exp of a BigInt, calculated using ray-based multiplications (27 decimals precision), rounded down\n\n```typescript\nBigInt.PERCENT.rayExpTaylorN(3n); // ~exp(1.0) ~= exp (in ray), using third-order Taylor polynomial\n```\n\n#### `rayMulUp`\n\nReturns the result of the ray-based multiplication (27 decimals precision), rounded up\n\n```typescript\n(BigInt.RAY - 1n).rayMulUp(BigInt.RAY - 1n); // 0.999999999999999999999999999 * 0.999999999999999999999999999 = 0.999999999999999999999999999 (in ray, rounded up)\n```\n\n#### `rayMulDown`\n\nReturns the result of the ray-based multiplication (27 decimals precision), rounded down\n\n```typescript\n(BigInt.RAY - 1n).rayMulDown(BigInt.RAY - 1n); // 0.999999999999999999999999999 * 0.999999999999999999999999999 = 0.999999999999999999999999998 (in ray, rounded down)\n```\n\n#### `rayDivUp`\n\nReturns the result of the ray-based division (27 decimals precision), rounded up\n\n```typescript\nBigInt.RAY.rayDivUp(BigInt.RAY - 1n); // 1.0 * 0.999999999999999999999999999 = 1.000000000000000000000000002 (in ray, rounded up)\n```\n\n#### `rayDivDown`\n\nReturns the result of the ray-based division (27 decimals precision), rounded down\n\n```typescript\nBigInt.RAY.rayDivDown(BigInt.RAY - 1n); // 1.0 * 0.999999999999999999999999999 = 1.000000000000000000000000001 (in ray, rounded down)\n```\n\n#### `formatRay`\n\nReturns 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)\n\n```typescript\nBigInt.RAY.formatRay(3); // 1.000\n```\n\n#### `toRayFloat`\n\nReturns a float representation of the BigInt's value, parsed as a ray-based number.\n\nNote: 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)\n\n```typescript\nBigInt.RAY.toRayFloat(); // 1.0\n```\n\n#### `rayToPercent`\n\nScales the ray-based BigInt down to the percent scale (losing 23 decimals)\n\n```typescript\nBigInt.RAY.rayToPercent(); // 1 PERCENT\n```\n\n#### `rayToWad`\n\nScales the ray-based BigInt down to the wad scale (losing 9 decimals)\n\n```typescript\nBigInt.RAY.rayToWad(); // 1 WAD\n```\n\n#### `rayToDecimals`\n\nScales the ray-based BigInt up or down to the given scale defined by its number of decimals\n\n```typescript\nBigInt.RAY.rayToDecimals(18); // 1 WAD\n```\n\n---\n\n### Percent-based utilities\n\n#### `percentMul`\n\nReturns the result of the percent-based multiplication (4 decimals precision), rounded half up\n\n```typescript\nBigInt.PERCENT.percentMul(BigInt.PERCENT); // 1.0 * 1.0 = 1.0 (in percent)\n```\n\n#### `percentDiv`\n\nReturns the result of the percent-based division (4 decimals precision), rounded half up\n\n```typescript\nBigInt.PERCENT.percentDiv(BigInt.PERCENT); // 1.0 / 1.0 = 1.0 (in percent)\n```\n\n#### `percentAdd`\n\nReturns the result of the addition of a BigNumberish and a percent-based percentage of it (4 decimals), rounded half up\n\n```typescript\nBigInt.PERCENT.percentAdd(\n  BigInt.HALF_PERCENT, // 50% in percent\n); // 1.0 * (1.0 + 0.5) = 1.5 (in percent)\n```\n\n#### `percentSub`\n\nReturns the result of the subtraction of a BigNumberish and a percent-based percentage of it (4 decimals), rounded half up\n\n```typescript\nBigInt.PERCENT.percentSub(\n  BigInt.HALF_PERCENT, // 50% in percent\n); // 1.0 * (1.0 - 0.5) = 0.5 (in percent)\n```\n\n#### `percentAvg`\n\nReturns the weighted average of 2 BigNumberishs, using a percent-based weight (4 decimals), rounded half up\n\n```typescript\nBigInt.PERCENT.percentAvg(\n  BigInt.PERCENT * 2n, // 200% in percent\n  BigInt.HALF_PERCENT, // 50% in percent\n); // 1.0 * (1.0 - 0.5) + 2.0 * 0.5 = 1.5 (in percent)\n```\n\n#### `percentPow`\n\nReturns the integer power of a BigInt, calculated using percent-based multiplications (4 decimals precision), rounded half up\n\n```typescript\nBigInt.PERCENT *\n  2n // 200% in percent\n    .percentPow(2n); // 2.0 ** 2 = 4.0 (in percent)\n```\n\n#### `percentPowUp`\n\nReturns the integer power of a BigInt, calculated using percent-based multiplications (4 decimals precision), rounded up\n\n```typescript\nBigInt.PERCENT *\n  2n // 200% in percent\n    .percentPowUp(2n); // 2.0 ** 2 = 4.0 (in percent)\n```\n\n#### `percentPowDown`\n\nReturns the integer power of a BigInt, calculated using percent-based multiplications (4 decimals precision), rounded down\n\n```typescript\nBigInt.PERCENT *\n  2n // 200% in percent\n    .percentPowDown(2n); // 2.0 ** 2 = 4.0 (in percent)\n```\n\n#### `percentExpTaylorN`\n\nReturns the N-th order Taylor polynomial approximation of the integer exp of a BigInt, calculated using percent-based multiplications (4 decimals precision), rounded down\n\n```typescript\nBigInt.PERCENT.percentExpTaylorN(3n); // ~exp(1.0) ~= exp (in percent), using third-order Taylor polynomial\n```\n\n#### `percentMulUp`\n\nReturns the result of the percent-based multiplication (4 decimals precision), rounded up\n\n```typescript\n(BigInt.PERCENT - 1n).percentMulUp(BigInt.PERCENT - 1n); // 0.9999 * 0.9999 = 0.9999 (in percent, rounded up)\n```\n\n#### `percentMulDown`\n\nReturns the result of the percent-based multiplication (4 decimals precision), rounded down\n\n```typescript\n(BigInt.PERCENT - 1n).percentMulDown(BigInt.PERCENT - 1n); // 0.9999 * 0.9999 = 0.9998 (in percent, rounded down)\n```\n\n#### `percentDivUp`\n\nReturns the result of the percent-based division (4 decimals precision), rounded up\n\n```typescript\nBigInt.PERCENT.percentDivUp(BigInt.PERCENT - 1n); // 1.0 * 0.9999 = 1.0002 (in percent, rounded up)\n```\n\n#### `percentDivDown`\n\nReturns the result of the percent-based division (4 decimals precision), rounded down\n\n```typescript\nBigInt.PERCENT.percentDivDown(BigInt.PERCENT - 1n); // 1.0 * 0.9999 = 1.0001 (in percent, rounded down)\n```\n\n#### `formatPercent`\n\nReturns 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)\n\n```typescript\nBigInt.PERCENT.formatPercent(3); // 1.000\n```\n\n#### `toPercentFloat`\n\nReturns a float representation of the BigInt's value, parsed as a percent-based number.\n\nNote: 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)\n\n```typescript\nBigInt.PERCENT.toPercentFloat(); // 1.0\n```\n\n#### `percentToWad`\n\nScales the percent-based BigInt up to the wad scale (adding 14 decimals)\n\n```typescript\nBigInt.PERCENT.percentToWad(); // 1 WAD\n```\n\n#### `percentToRay`\n\nScales the percent-based BigInt up to the ray scale (adding 23 decimals)\n\n```typescript\nBigInt.PERCENT.percentToRay(); // 1 RAY\n```\n\n#### `percentToDecimals`\n\nScales the percent-based BigInt up or down to the given scale defined by its number of decimals\n\n```typescript\nBigInt.RAY.percentToDecimals(27); // 1 RAY\n```\n\n[build-img]: https://github.com/Rubilmax/evm-maths/actions/workflows/release.yml/badge.svg\n[build-url]: https://github.com/Rubilmax/evm-maths/actions/workflows/release.yml\n[test-img]: https://github.com/Rubilmax/evm-maths/actions/workflows/test.yml/badge.svg\n[test-url]: https://github.com/Rubilmax/evm-maths/actions/workflows/test.yml\n[downloads-img]: https://img.shields.io/npm/dt/evm-maths\n[downloads-url]: https://www.npmtrends.com/evm-maths\n[npm-img]: https://img.shields.io/npm/v/evm-maths\n[npm-url]: https://www.npmjs.com/package/evm-maths\n[issues-img]: https://img.shields.io/github/issues/Rubilmax/evm-maths\n[issues-url]: https://github.com/Rubilmax/evm-maths/issues\n[semantic-release-img]: https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg\n[semantic-release-url]: https://github.com/semantic-release/semantic-release\n[commitizen-img]: https://img.shields.io/badge/commitizen-friendly-brightgreen.svg\n[commitizen-url]: http://commitizen.github.io/cz-cli/\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frubilmax%2Fevm-maths","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frubilmax%2Fevm-maths","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frubilmax%2Fevm-maths/lists"}