<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-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-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"><ahref="/api/providers/other/#ipcprovider">IpcProvider</a></div><divclass="hide link depth-3"><ahref="/api/providers/types/">Types</a></div><divclass="hide link depth-4"><ahref="/api/providers/types/#blocks">Blocks</a><
<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"><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"><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"><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"><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>
<p>The constructor of BigNumber cannot be called directly. Instead, Use the static <codeclass="inline">BigNumber.from</code>.</p>
<divclass="property"><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></div><divclass="body"><p>Returns an instance of a <b>BigNumber</b> for <i>aBigNumberish</i>.</p></div></div>
<divclass="code"><br><spanclass="comment">// From a decimal string...</span><br>BigNumber.from("42")<br><spanclass="result ok">// { BigNumber: "42" }</span><br><br><spanclass="comment">// From a hexstring...</span><br>BigNumber.from("0x2a")<br><spanclass="result ok">// { BigNumber: "42" }</span><br><br><spanclass="comment">// From a negative hexstring...</span><br>BigNumber.from("-0x2a")<br><spanclass="result ok">// { BigNumber: "-42" }</span><br><br><spanclass="comment">// From an Array (or Uint8Array)...</span><br>BigNumber.from([ 42 ])<br><spanclass="result ok">// { BigNumber: "42" }</span><br><br><spanclass="comment">// From an existing BigNumber...</span><br>let one1 = constants.One;<br>let one2 = BigNumber.from(one1)<br><br>one2<br><spanclass="result ok">// { BigNumber: "1" }</span><br><br><spanclass="comment">// ...which returns the same instance</span><br>one1 === one2<br><spanclass="result ok">// true</span><br><br><spanclass="comment">// From a (safe) number...</span><br>BigNumber.from(42)<br><spanclass="result ok">// { BigNumber: "42" }</span><br><br><spanclass="comment">// From a ES2015 BigInt... (only on platforms with BigInt support)</span><br>BigNumber.from(42n)<br><spanclass="result ok">// { BigNumber: "42" }</span><br><br><spanclass="comment">// Numbers outside the safe range fail:</span><br>BigNumber.from(Number.MAX_SAFE_INTEGER);<br><spanclass="result error">// Error: overflow (fault="overflow", operation="BigNumber.from", value=9007199254740991, version=bignumber/5.0.0-beta.129)</span><br></div>
<divclass="property"><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></div><divclass="body"><p>Returns a BigNumber with the value of <i>bignumber</i><b>+</b><i>otherValue</i>.</p></div></div>
<divclass="property"><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></div><divclass="body"><p>Returns a BigNumber with the value of <i>bignumber</i><b>–</b><i>otherValue</i>.</p></div></div>
<divclass="property"><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></div><divclass="body"><p>Returns a BigNumber with the value of <i>bignumber</i><b>×</b><i>otherValue</i>.</p></div></div>
<divclass="property"><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></div><divclass="body"><p>Returns a BigNumber with the value of <i>bignumber</i><b>÷</b><i>divisor</i>.</p></div></div>
<divclass="property"><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></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"><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></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"><divclass="signature"><spanclass="path">bignumber</span> . <spanclass="method">abs</span> ( ) <spanclass="arrow">⇒</span><spanclass="returns"><ahref="/api/utils/bignumber/">BigNumber</a></span></div><divclass="body"><p>Returns a BigNumber with the absolute value of <i>bignumber</i>.</p></div></div>
<divclass="property"><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></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 a method used to encode and decode fixed-width values which can be positive or negative, without requiring a separate sign bit. Most users will not need to interact with these.</p>
<divclass="property"><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></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"><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></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><h3>Comparison and Equivalence</h3>
<divclass="property"><divclass="signature"><spanclass="path">bignumber</span> . <spanclass="method">eq</span> ( <spanclass="param">otherValue</span> ) <spanclass="arrow">⇒</span><spanclass="returns">boolean</span></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"><divclass="signature"><spanclass="path">bignumber</span> . <spanclass="method">lt</span> ( <spanclass="param">otherValue</span> ) <spanclass="arrow">⇒</span><spanclass="returns">boolean</span></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"><divclass="signature"><spanclass="path">bignumber</span> . <spanclass="method">lte</span> ( <spanclass="param">otherValue</span> ) <spanclass="arrow">⇒</span><spanclass="returns">boolean</span></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"><divclass="signature"><spanclass="path">bignumber</span> . <spanclass="method">gt</span> ( <spanclass="param">otherValue</span> ) <spanclass="arrow">⇒</span><spanclass="returns">boolean</span></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"><divclass="signature"><spanclass="path">bignumber</span> . <spanclass="method">gte</span> ( <spanclass="param">otherValue</span> ) <spanclass="arrow">⇒</span><spanclass="returns">boolean</span></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"><divclass="signature"><spanclass="path">bignumber</span> . <spanclass="method">isZero</span> ( ) <spanclass="arrow">⇒</span><spanclass="returns">boolean</span></div><divclass="body"><p>Returns true if and only if the value of <i>bignumber</i> is zero.</p></div></div>
<aname="conversion"></a><h3>Conversion</h3>
<divclass="property"><divclass="signature"><spanclass="path">bignumber</span> . <spanclass="method">toNumber</span> ( ) <spanclass="arrow">⇒</span><spanclass="returns">number</span></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"><divclass="signature"><spanclass="path">bignumber</span> . <spanclass="method">toString</span> ( ) <spanclass="arrow">⇒</span><spanclass="returns">string</span></div><divclass="body"><p>Returns the value of <i>bignumber</i> as a base-10 string.</p></div></div>
<divclass="property"><divclass="signature"><spanclass="path">bignumber</span> . <spanclass="method">toHexString</span> ( ) <spanclass="arrow">⇒</span><spanclass="returns">string</span></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>
<aname="inspection"></a><h3>Inspection</h3>
<divclass="property"><divclass="signature"><spanclass="path">BigNumnber</span> . <spanclass="method">isBigNumber</span> ( <spanclass="param">object</span> ) <spanclass="arrow">⇒</span><spanclass="returns">boolean</span></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><h3>Why can't I just use numbers?</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://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</i> 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://linkto">parseEther( etherString )</a> and <ahref="http://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:afcc27a12ae5a43b7ee621b007c1f1ad7c6c0714b1fbb7b6d119a773de8f938d -->
