305 lines
8.1 KiB
ReStructuredText
305 lines
8.1 KiB
ReStructuredText
Utilities
|
|
*********
|
|
|
|
The utility functions exposed in both the *ethers* umbrella package and the *ethers-utils*::
|
|
|
|
var utils = require('ethers').utils;
|
|
|
|
|
|
-----
|
|
|
|
.. _bignumber:
|
|
|
|
Big Numbers
|
|
===========
|
|
|
|
A BigNumber is an immutable object which allow math operations to be carried
|
|
out on numbers far larger than :ref:`JavaScript can accurately handle <ieee754>`.
|
|
Many functions return these, so it is important to understand how to work with these.
|
|
|
|
:sup:`prototype` . add ( otherValue )
|
|
Return a new BigNumber of this plus *otherValue*
|
|
|
|
:sup:`prototype` . sub ( otherValue )
|
|
Return a new BigNumber of this minus *otherValue*
|
|
|
|
:sup:`prototype` . mul ( otherValue )
|
|
Return a new BigNumber of this times *otherValue*
|
|
|
|
:sup:`prototype` . div ( otherValue )
|
|
Return a new BigNumber of this divided by *otherValue*
|
|
|
|
:sup:`prototype` . mod ( otherValue )
|
|
Return a new BigNumber of this modulo *otherValue*
|
|
|
|
:sup:`prototype` . eq ( otherValue )
|
|
Return true if this is equal to *otherValue*
|
|
|
|
:sup:`prototype` . lt ( otherValue )
|
|
Return true if this is less than *otherValue*
|
|
|
|
:sup:`prototype` . lte ( otherValue )
|
|
Return true if this is less or equal to *otherValue*
|
|
|
|
:sup:`prototype` . gt ( otherValue )
|
|
Return true if this is greater than *otherValue*
|
|
|
|
:sup:`prototype` . gte ( otherValue )
|
|
Return true if this is greater than or equal to *otherValue*
|
|
|
|
:sup:`prototype` . isZero ( )
|
|
Return true if this is equal to zero
|
|
|
|
:sup:`prototype` . toNumber ( )
|
|
Return a JavaScript number representation; an error is thrown if the value is
|
|
outside the safe range for JavaScript IEEE 754 64-bit floating point numbers
|
|
|
|
:sup:`prototype` . toString ()
|
|
Return a decimal string representation
|
|
|
|
:sup:`prototype` . toHexString ( )
|
|
Return a **0x prefixed** hexidecimal representation
|
|
|
|
|
|
Creating Instances
|
|
------------------
|
|
|
|
:sup:`utils` **. bigNumberify** ( value )
|
|
Returns a BigNumber instance of *value*.
|
|
The *value* may be anything which can be
|
|
reliably converted into a BigNumber.
|
|
|
|
:sup:`Decimal String:`
|
|
A string consisting of the decimal digits 0 through 9, optionally with a leading
|
|
negative sign. (example: ``utils.bigNumberify("42")``)
|
|
|
|
:sup:`Hexidecimal String:`
|
|
A string with a **prefix of 0x** and consisting of the hexidecimal digits 0 through 9 and
|
|
a through f. (example: ``utils.bigNumberify("0x2a")``)
|
|
|
|
:sup:`Numbers:`
|
|
Numbers must be within the `safe range`_ for JavaScript. (example: ``utils.bigNumberify(42)``)
|
|
|
|
:sup:`Arrayish:`
|
|
Treats the :ref:`arrayish <arrayish>` as a big-endian encoded bytes representation.
|
|
(example: ``utils.bigNumberify([ 42 ])``)
|
|
|
|
:sup:`BigNumber:`
|
|
Returns the same instance (since BigNumbers are immutable).
|
|
|
|
.. _safe range: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/isSafeInteger
|
|
|
|
*Examples*
|
|
----------
|
|
|
|
::
|
|
|
|
@TODO:
|
|
var utils = require('ethers').utils;
|
|
|
|
var gasPriceWei = utils.bigNumberify();
|
|
var gasLimit = utils.bigNumberify(3000000);
|
|
|
|
var cost
|
|
|
|
console.log();
|
|
|
|
-----
|
|
|
|
|
|
Ether Strings and Wei
|
|
=====================
|
|
|
|
:sup:`utils` . etherSymbol
|
|
The ethereum symbol (the Greek letter *Xi* )
|
|
|
|
.. _parseEther:
|
|
|
|
:sup:`utils` . parseEther ( etherString )
|
|
Parse the *etherString* representation of ether into a BigNumber instance
|
|
of the amount of wei.
|
|
|
|
.. _formatEther:
|
|
|
|
:sup:`utils` . formatEther ( wei [ , options ] )
|
|
Format an amount of *wei* into a decimal string representing the amount of ether. The
|
|
*options* object supports the keys ``commify`` and ``pad``. The output will always
|
|
include at least one whole number and at least one decimal place.
|
|
|
|
|
|
*Examples*
|
|
----------
|
|
|
|
::
|
|
|
|
var wei = utils.parseEther('1000.0');
|
|
console.log(wei.toString(10));
|
|
// "1000000000000000000000"
|
|
|
|
console.log(utils.formatEther(0));
|
|
// "0.0"
|
|
|
|
var wei = utils.bigNumberify("1000000000000000000000");
|
|
|
|
console.log(utils.formatEther(wei));
|
|
// "1000.0"
|
|
|
|
console.log(utils.formatEther(wei, {commify: true}));
|
|
// "1,000.0"
|
|
|
|
console.log(utils.formatEther(wei, {pad: true}));
|
|
// "1000.000000000000000000" (18 decimal places)
|
|
|
|
console.log(utils.formatEther(wei, {commify: true, pad: true}));
|
|
// "1,000.000000000000000000" (18 decimal places)
|
|
|
|
|
|
-----
|
|
|
|
Addresses
|
|
=========
|
|
|
|
There are :ref:`several formats <checksum-address>` available on the Ethereum network for
|
|
addresses, and it is often useful to be able to convert between them.
|
|
|
|
|
|
.. _api-getAddress:
|
|
|
|
:sup:`utils` . getAddress ( address [ , generateIcap ] )
|
|
Normalize an address to a :ref:`checksum address <checksum-address>`, or as an
|
|
:ref:`ICAP <icap-address>` address if *generateIcap* is true.
|
|
|
|
*Examples*
|
|
----------
|
|
|
|
::
|
|
|
|
var address = "0xd115bffabbdd893a6f7cea402e7338643ced44a6";
|
|
var icapAddress = "XE93OF8SR0OWI6F4FO88KWO4UNNGG1FEBHI";
|
|
|
|
console.log('Checksum address: ' + utils.getAddress(address));
|
|
// "0xD115BFFAbbdd893A6f7ceA402e7338643Ced44a6"
|
|
|
|
console.log('Checksum address: ' + utils.getAddress(icapAddress));
|
|
// "0xD115BFFAbbdd893A6f7ceA402e7338643Ced44a6"
|
|
|
|
console.log('ICAP address:' + utils.getAddress(address, true));
|
|
// "XE93OF8SR0OWI6F4FO88KWO4UNNGG1FEBHI"
|
|
|
|
console.log('ICAP address:' + utils.getAddress(icapAddress, true));
|
|
// "XE93OF8SR0OWI6F4FO88KWO4UNNGG1FEBHI"
|
|
|
|
|
|
-----
|
|
|
|
|
|
UTF-8 Strings
|
|
=============
|
|
|
|
:sup:`utils` . toUtf8Bytes ( string )
|
|
Converts a UTF-8 string to a Uint8Array.
|
|
|
|
:sup:`utils` . toUtf8String ( hexStringOrArrayish )
|
|
Converts a hex-encoded string or array to its UTF-8 representation.
|
|
|
|
*Examples*
|
|
----------
|
|
|
|
::
|
|
|
|
var text = "Hello World";
|
|
|
|
var bytes = utils.toUtf8Bytes(text);
|
|
console.log(bytes);
|
|
// Uint8Array [72, 101, 108, 108, 111, 32, 87, 111, 114, 108, 100]
|
|
|
|
console.log(utils.toUtf8String(bytes));
|
|
// "Hello World"
|
|
|
|
var hexString = "0x48656c6c6f20576f726c64";
|
|
console.log(utils.toUtf8String(hexString));
|
|
// "Hello World"
|
|
|
|
|
|
-----
|
|
|
|
Cryptographic Functions
|
|
=======================
|
|
|
|
:sup:`utils` . keccak256 ( hexStringOrArrayish )
|
|
Compute the keccak256 cryptographic hash of a value, returned as a hex string. (Note:
|
|
often Ethereum refers to this, **incorrectly**, as SHA3)
|
|
|
|
:sup:`utils` . sha256 ( hexStringOrArrayish )
|
|
Compute the SHA2-256 cryptographic hash of a value, returned as a hex string.
|
|
|
|
:sup:`utils` . randomBytes ( length )
|
|
Return a Uint8Array of cryptographically secure random bytes
|
|
|
|
|
|
*Examples*
|
|
----------
|
|
|
|
::
|
|
|
|
console.log(utils.keccak256([ 0x42 ]));
|
|
// '0x1f675bff07515f5df96737194ea945c36c41e7b4fcef307b7cd4d0e602a69111'
|
|
|
|
console.log(utils.keccak256("0x42"));
|
|
// '0x1f675bff07515f5df96737194ea945c36c41e7b4fcef307b7cd4d0e602a69111'
|
|
|
|
|
|
console.log(utils.sha256([ 0x42 ]));
|
|
// '0xdf7e70e5021544f4834bbee64a9e3789febc4be81470df629cad6ddb03320a5c'
|
|
|
|
console.log(utils.sha256("0x42"));
|
|
// '0xdf7e70e5021544f4834bbee64a9e3789febc4be81470df629cad6ddb03320a5c'
|
|
|
|
|
|
// Use with the toUtf8Bytes() function to get the hash of strings
|
|
var utf8Bytes = utils.toUtf8Bytes('Hello World');
|
|
|
|
console.log(utils.keccak256(utf8Bytes));
|
|
// '0x592fa743889fc7f92ac2a37bb1f5ba1daf2a5c84741ca0e0061d243a2e6707ba'
|
|
|
|
console.log(utils.sha256(utf8Bytes));
|
|
// '0xa591a6d40bf420404a011733cfb7b190d62c65bf0bcda32b57b277d9ad9f146e'
|
|
|
|
|
|
console.log(utils.randomBytes(3));
|
|
// Uint8Array [ 194, 22, 140 ]
|
|
|
|
|
|
-----
|
|
|
|
Contract Addresses
|
|
==================
|
|
|
|
Every contract deployed on the Ethereum network requires an address (you can think
|
|
of this as the memory address which the running application lives at). The address
|
|
is generated from a cryptographic has of the address of the creator and the nonce
|
|
of the transaction.
|
|
|
|
:sup:`utils` . getContractAddress ( transaction )
|
|
Computes the contract address a contract would have if this transaction
|
|
created a contract. (transaction requires only ``from`` and ``nonce`` be
|
|
defined)
|
|
|
|
*Examples*
|
|
----------
|
|
|
|
::
|
|
|
|
// Ropsten: 0x5bdfd14fcc917abc2f02a30721d152a6f147f09e8cbaad4e0d5405d646c5c3e1
|
|
var transaction = {
|
|
from: '0xc6af6e1a78a6752c7f8cd63877eb789a2adb776c',
|
|
nonce: 0
|
|
};
|
|
|
|
console.log(utils.getContractAddress(transaction));
|
|
// "0x0CcCC7507aEDf9FEaF8C8D731421746e16b4d39D"
|
|
|
|
-----
|
|
|
|
\
|