<html><head><title>Big Number</title><linkrel="stylesheet"type="text/css"href="/static/style.css"></head><body><divclass="sidebar"><divclass="header"><divclass="logo"><ahref="/"><divclass="image"></div><divclass="name">ethers</div><divclass="version">v5.0-beta</div></a></div></div><divclass="toc"><div><divclass="link title"><ahref="/">Documentation</a></div><divclass="base show link depth-1"><ahref="/getting-started/">Getting Started</a></div><divclass="hide link depth-2"><ahref="/getting-started/#installing">Installing</a></div><divclass="hide link depth-2"><ahref="/getting-started/#importing">Importing</a></div><divclass="base show link depth-1"><ahref="/concepts/">Concepts</a></div><divclass="hide link depth-2"><ahref="/concepts/events/">Events</a></div><divclass="hide link depth-3"><ahref="/concepts/events/#solidity-topics">Solidity Topics</a></div><divclass="hide link depth-2"><ahref="/concepts/gas/">Gas</a></div><divclass="hide link depth-3"><ahref="/concepts/gas/#gas-price">Gas Price</a></div><divclass="hide link depth-3"><ahref="/concepts/gas/#gas-limit">Gas Limit</a></div><divclass="base ancestor show link depth-1"><ahref="/api/">Application Programming Interface</a></div><divclass="show link depth-2"><ahref="/api/contract/">Contracts</a></div><divclass="hide link depth-3"><ahref="/api/contract/#buckets">Buckets</a></div><divclass="show link depth-2"><ahref="/api/signer/">Signers</a></div><divclass="hide link depth-3"><ahref="/api/signer/#signer">Signer</a></div><divclass="hide link depth-3"><ahref="/api/signer/#wallet-inherits-signer">Wallet inherits Signer</a></div><divclass="show link depth-2"><ahref="/api/providers/">Providers</a></div><divclass="hide link depth-3"><ahref="/api/providers/provider/">Provider</a></div><divclass="hide link depth-4"><ahref="/api/providers/provider/#accounts-methods">Accounts Methods</a></div><divclass="hide link depth-4"><ahref="/api/providers/provider/#blocks-methods">Blocks Methods</a></div><divclass="hide link depth-4"><ahref="/api/providers/provider/#ethereum-naming-service-(ens)-methods">Ethereum Naming Service (ENS) Methods</a></div><divclass="hide link depth-4"><ahref="/api/providers/provider/#logs-methods">Logs Methods</a></div><divclass="hide link depth-4"><ahref="/api/providers/provider/#network-status-methods">Network Status Methods</a></div><divclass="hide link depth-4"><ahref="/api/providers/provider/#transactions-methods">Transactions Methods</a></div><divclass="hide link depth-4"><ahref="/api/providers/provider/#event-emitter-methods">Event Emitter Methods</a></div><divclass="hide link depth-4"><ahref="/api/providers/provider/#inspection-methods">Inspection Methods</a></div><divclass="hide link depth-3"><ahref="/api/providers/jsonrpc-provider/">JSON-RPC Provider</a></div><divclass="hide link depth-4"><ahref="/api/providers/jsonrpc-provider/#jsonrpcprovider">JsonRpcProvider</a></div><divclass="hide link depth-4"><ahref="/api/providers/jsonrpc-provider/#jsonrpcsigner">JsonRpcSigner</a></div><divclass="hide link depth-4"><ahref="/api/providers/jsonrpc-provider/#jsonrpcuncheckedsigner">JsonRpcUncheckedSigner</a></div><divclass="hide link depth-3"><ahref="/api/providers/api-providers/">API Providers</a></div><divclass="hide link depth-4"><ahref="/api/providers/api-providers/#etherscanprovider">EtherscanProvider</a></div><divclass="hide link depth-4"><ahref="/api/providers/api-providers/#infuraprovider">InfuraProvider</a></div><divclass="hide link depth-4"><ahref="/api/providers/api-providers/#nodesmithprovider">NodesmithProvider</a></div><divclass="hide link depth-4"><ahref="/api/providers/api-providers/#alchemyprovider">AlchemyProvider</a></div><divclass="hide link depth-4"><ahref="/api/providers/api-providers/#cloudfrontprovider">CloudfrontProvider</a></div><divclass="hide link depth-3"><ahref="/api/providers/other/">Other Providers</a></div><divclass="hide link depth-4"><ahref="/api/providers/other/#fallbackprovider">FallbackProvider</a></div><divclass="hide link depth-4"><ahre
<divclass="code"><spanclass="comment">/////</span><br><spanclass="comment">// CommonJS:</span><br><br><spanclass="comment">// From the Umbrella ethers package...</span><br>const { BigNumber } = require("ethers");<br><br><spanclass="comment">// From the bignumber pacakge...</span><br>const { BigNumber } = require("@ethersproject/bignumber");<br><br><br><spanclass="comment">/////</span><br><spanclass="comment">// ES6 and TypeScript:</span><br><br><spanclass="comment">// From the Umbrella ethers package...</span><br>import { BigNumber } from "ethers";<br><br><spanclass="comment">// From the bignumber pacakge...</span><br>import { BigNumber } from "@ethersproject/bignumber";<br></div>
<p>Many functions and methods in this library take in values which can be non-ambiguously and safely converted to a BigNumber. These values can be sepcified as:</p>
<divclass="definition show-anchors"><divclass="term"><b><i>string</i></b></div><divclass="body"><p>A <ahref="/api/utils/bytes/#hexstring">hexstring</a> or a decimal string, either of which may be negative.</p></div></div>
<divclass="definition show-anchors"><divclass="term"><b><i>BytesLike</i></b></div><divclass="body"><p>A <ahref="/api/utils/bytes/#byteslike">BytesLike</a> Object, such as an Array or Uint8Array.</p></div></div>
<divclass="definition show-anchors"><divclass="term"><b><i>number</i></b></div><divclass="body"><p>A number that is within the safe range for JavaScript numbers.</p></div></div>
<divclass="definition show-anchors"><divclass="term"><b><i>BigInt</i></b></div><divclass="body"><p>A JavaScript <ahref="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt">BigInt</a> object, on environments that support BigInt.</p></div></div>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">BigNumber</span> . <spanclass="method">from</span> ( <spanclass="param">aBigNumberish</span> ) <spanclass="arrow">⇒</span><spanclass="returns"><ahref="/api/utils/bignumber/">BigNumber</a></span><divclass="anchors"></div></div><divclass="body"><p>Returns an instance of a <b>BigNumber</b> for <i>aBigNumberish</i>.</p></div></div>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">bignumber</span> . <spanclass="method">add</span> ( <spanclass="param">otherValue</span> ) <spanclass="arrow">⇒</span><spanclass="returns"><ahref="/api/utils/bignumber/">BigNumber</a></span><divclass="anchors"></div></div><divclass="body"><p>Returns a BigNumber with the value of <i>bignumber</i><b>+</b><i>otherValue</i>.</p></div></div>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">bignumber</span> . <spanclass="method">sub</span> ( <spanclass="param">otherValue</span> ) <spanclass="arrow">⇒</span><spanclass="returns"><ahref="/api/utils/bignumber/">BigNumber</a></span><divclass="anchors"></div></div><divclass="body"><p>Returns a BigNumber with the value of <i>bignumber</i><b>–</b><i>otherValue</i>.</p></div></div>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">bignumber</span> . <spanclass="method">mul</span> ( <spanclass="param">otherValue</span> ) <spanclass="arrow">⇒</span><spanclass="returns"><ahref="/api/utils/bignumber/">BigNumber</a></span><divclass="anchors"></div></div><divclass="body"><p>Returns a BigNumber with the value of <i>bignumber</i><b>×</b><i>otherValue</i>.</p></div></div>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">bignumber</span> . <spanclass="method">div</span> ( <spanclass="param">divisor</span> ) <spanclass="arrow">⇒</span><spanclass="returns"><ahref="/api/utils/bignumber/">BigNumber</a></span><divclass="anchors"></div></div><divclass="body"><p>Returns a BigNumber with the value of <i>bignumber</i><b>÷</b><i>divisor</i>.</p></div></div>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">bignumber</span> . <spanclass="method">mod</span> ( <spanclass="param">divisor</span> ) <spanclass="arrow">⇒</span><spanclass="returns"><ahref="/api/utils/bignumber/">BigNumber</a></span><divclass="anchors"></div></div><divclass="body"><p>Returns a BigNumber with the value of the <b>remainder</b> of <i>bignumber</i>÷<i>divisor</i>.</p></div></div>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">bignumber</span> . <spanclass="method">pow</span> ( <spanclass="param">exponent</span> ) <spanclass="arrow">⇒</span><spanclass="returns"><ahref="/api/utils/bignumber/">BigNumber</a></span><divclass="anchors"></div></div><divclass="body"><p>Returns a BigNumber with the value of <i>bignumber</i> to the power of <i>exponent</i>.</p></div></div>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">bignumber</span> . <spanclass="method">abs</span> ( ) <spanclass="arrow">⇒</span><spanclass="returns"><ahref="/api/utils/bignumber/">BigNumber</a></span><divclass="anchors"></div></div><divclass="body"><p>Returns a BigNumber with the absolute value of <i>bignumber</i>.</p></div></div>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">bignumber</span> . <spanclass="method">maskn</span> ( <spanclass="param">bitcount</span> ) <spanclass="arrow">⇒</span><spanclass="returns"><ahref="/api/utils/bignumber/">BigNumber</a></span><divclass="anchors"></div></div><divclass="body"><p>Returns a BigNumber with the value of <i>bignumber</i> with bits beyond the <i>bitcount</i> least significant bits set to zero.</p></div></div>
<p><ahref="https://en.wikipedia.org/wiki/Two%27s_complement">Two's Complicment</a> is an elegant method used to encode and decode fixed-width signed values while efficiently preserving mathematic operations. Most users will not need to interact with these.</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">bignumber</span> . <spanclass="method">fromTwos</span> ( <spanclass="param">bitwidth</span> ) <spanclass="arrow">⇒</span><spanclass="returns"><ahref="/api/utils/bignumber/">BigNumber</a></span><divclass="anchors"></div></div><divclass="body"><p>Returns a BigNumber with the value of <i>bignumber</i> converted from twos-compliment with <i>bitwidth</i>.</p></div></div>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">bignumber</span> . <spanclass="method">toTwos</span> ( <spanclass="param">bitwidth</span> ) <spanclass="arrow">⇒</span><spanclass="returns"><ahref="/api/utils/bignumber/">BigNumber</a></span><divclass="anchors"></div></div><divclass="body"><p>Returns a BigNumber with the value of <i>bignumber</i> converted to twos-compliment with <i>bitwidth</i>.</p></div></div>
<aname="comparison-and-equivalence"></a><h3class="show-anchors"><div>Comparison and Equivalence<divclass="anchors"><aclass="self"href="#comparison-and-equivalence"></a></div></div></h3>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">bignumber</span> . <spanclass="method">eq</span> ( <spanclass="param">otherValue</span> ) <spanclass="arrow">⇒</span><spanclass="returns">boolean</span><divclass="anchors"></div></div><divclass="body"><p>Returns true if and only if the value of <i>bignumber</i> is equal to <i>otherValue</i>.</p></div></div>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">bignumber</span> . <spanclass="method">lt</span> ( <spanclass="param">otherValue</span> ) <spanclass="arrow">⇒</span><spanclass="returns">boolean</span><divclass="anchors"></div></div><divclass="body"><p>Returns true if and only if the value of <i>bignumber</i><b><</b><i>otherValue</i>.</p></div></div>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">bignumber</span> . <spanclass="method">lte</span> ( <spanclass="param">otherValue</span> ) <spanclass="arrow">⇒</span><spanclass="returns">boolean</span><divclass="anchors"></div></div><divclass="body"><p>Returns true if and only if the value of <i>bignumber</i><b>≤</b><i>otherValue</i>.</p></div></div>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">bignumber</span> . <spanclass="method">gt</span> ( <spanclass="param">otherValue</span> ) <spanclass="arrow">⇒</span><spanclass="returns">boolean</span><divclass="anchors"></div></div><divclass="body"><p>Returns true if and only if the value of <i>bignumber</i><b>></b><i>otherValue</i>.</p></div></div>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">bignumber</span> . <spanclass="method">gte</span> ( <spanclass="param">otherValue</span> ) <spanclass="arrow">⇒</span><spanclass="returns">boolean</span><divclass="anchors"></div></div><divclass="body"><p>Returns true if and only if the value of <i>bignumber</i><b>≥</b><i>otherValue</i>.</p></div></div>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">bignumber</span> . <spanclass="method">isZero</span> ( ) <spanclass="arrow">⇒</span><spanclass="returns">boolean</span><divclass="anchors"></div></div><divclass="body"><p>Returns true if and only if the value of <i>bignumber</i> is zero.</p></div></div>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">bignumber</span> . <spanclass="method">toNumber</span> ( ) <spanclass="arrow">⇒</span><spanclass="returns">number</span><divclass="anchors"></div></div><divclass="body"><p>Returns the value of <i>bignumber</i> as a JavaScript value.</p><p>This will <b>throw an error</b> if the value is greater than or equal to <i>Number.MAX_SAFE_INTEGER</i> or less than or equal to <i>Number.MIN_SAFE_INTEGER</i>.</p></div></div>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">bignumber</span> . <spanclass="method">toString</span> ( ) <spanclass="arrow">⇒</span><spanclass="returns">string</span><divclass="anchors"></div></div><divclass="body"><p>Returns the value of <i>bignumber</i> as a base-10 string.</p></div></div>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">bignumber</span> . <spanclass="method">toHexString</span> ( ) <spanclass="arrow">⇒</span><spanclass="returns">string</span><divclass="anchors"></div></div><divclass="body"><p>Returns the value of <i>bignumber</i> as a base-16, `0x`-prefixed <ahref="/api/utils/bytes/#hexstring">hexstring</a>.</p></div></div>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">BigNumnber</span> . <spanclass="method">isBigNumber</span> ( <spanclass="param">object</span> ) <spanclass="arrow">⇒</span><spanclass="returns">boolean</span><divclass="anchors"></div></div><divclass="body"><p>Returns true if and only if the <i>object</i> is a BigNumber object.</p></div></div>
<aname="why-can't-i-just-use-numbers?"></a><h3class="show-anchors"><div>Why can't I just use numbers?<divclass="anchors"><aclass="self"href="#why-can't-i-just-use-numbers?"></a></div></div></h3>
<p>The first problem many encounter when dealing with Ethereum is the concept of numbers. Most common currencies are broken down with very little granularity. For example, there are only 100 cents in a single dollar. However, there are 10<sup>18</sup><b>wei</b> in a single <b>ether</b>.</p><p>JavaScript uses <ahref="https:<i>en.wikipedia.org/wiki/Double-precision_floating-point_format">IEEE 754 double-precision binary floating point</a> numbers to represent numeric values. As a result, there are </i>holes<i> in the integer set after 9,007,199,254,740,991; which is problematic for </i>Ethereum// because that is only around 0.009 ether (in wei), which means any value over that will begin to experience rounding errors.</p><p>To demonstrate how this may be an issue in your code, consider:</p>
<p>To remedy this, all numbers (which can be large) are stored and manipulated as <ahref="/api/utils/bignumber/">Big Numbers</a>.</p><p>The functions <ahref="http:<i>linkto">parseEther( etherString )</a> and <ahref="http:</i>linkto">formatEther( wei )</a> can be used to convert between string representations, which are displayed to or entered by the user and Big Number representations which can have mathematical operations handled safely.</p><divclass="footer"><divclass="nav previous"><ahref="/api/utils/address/"><spanclass="arrow">←</span>Addresses</a></div><divclass="nav next"><ahref="/api/utils/bytes/">Byte Manipulation<spanclass="arrow">→</span></a></div></div><divclass="copyright">The content of this site is licensed under the <ahref="https://choosealicense.com/licenses/cc-by-4.0/">Creative Commons Attribution 4.0 International License</a>.</div></div><scriptsrc="/script.js"type="text/javascript"></script></body></html><!-- ContentHash:0e51b1712c81ed1a0333503bae9b8fa66727db4f3f8004c388f900ad1efb42df -->
