Common Types¶

There are several parameter formats and types that come up often:

Addresses – Ethereum Accounts and Contracts all have an address, which is needed to interact with them
Big Numbers (BN.js) – Precise numbers to work around JavaScript’s lossy floating point system
Hex Strings – Strings of hexidecimal encoded binary data and numbers
Errors – An error indicating the user (explicitly or implicitly) cancelled an operation

Addresses¶

Addresses come in many formats, and any may be used.

Hex Strings (eg. 0x1234567890abcdef1234567890abcdef12345678)
ICAP Addresses (eg. XE0724JX5HRQ9R1XA24VWJM008DMOB17YBC)
Checksum Address (eg. 0x1234567890AbcdEF1234567890aBcdef12345678; notice uppercase and lowercase letters)

The ICAP Address format uses the International Bank Account Number (IBAN) format with a prefex of XE.

The Checksum Address format uses a mixture of uppercase and lowercase letters to encode checksum information in an address, but remains backward compatible with systems that do not understand checksum addresses. Because of this, addresses which are not checksum addresses must use entirely uppercase or entirely lowercase letters.

To convert between the various formats:

// Get an ICAP address (from any address format)
var icapAddress = ethers.getAddress(address, true);

// Get a checksum address (from any address format)
var address = ethers.getAddress(address)

Big Numbers¶

Since Ethereum deals a great deal with large numberic values (far larger than JavaScript can handle without `loss of precission`_), many calls require and return instances of BigNumber.

Some common things you will likely want to do with a BigNumber:

// Convert to base 10 string
var valueBase10 = value.toString();

// Convert to a number (only valid for values that fit in 53 bits)
var valueNumber = value.toNumber();

// Convert to hex string
var valueHexString = value.toHexString();

// Convert from a base 10 string
var value = ethers.utils.bigNumberify('1000000');

// Convert from a hex string (the 0x prefex is REQUIRED)
var value = ethers.utils.bigNumberify('0xf4240');

// Multiple two values
var product = value1.mul(value2)

// Convert from ether (string) to wei (BN)
var wei = ethers.parseEther('1.0');

// Convert from wei to ether (string)
var ether = ethers.formatEther(wei)

Hex Strings¶

Often functions deal with binary data, which should be specified using a hex string. Functions which require big numbers can also be passed the hex string equivalent.

It is important to note, it MUST be a string, and it MUST begin with the prefix 0x.

Example:

var binaryHelloWorld = '0x48656c6c6f576f726c64';
var thirtySeven = '0x25';

 // Convert a hex string to a byte Array
 ethers.utils.arrayify(binaryHelloWorld);
// Uint8Array [ 72, 101, 108, 108, 111, 87, 111, 114, 108, 100 ]

// Convert a byte Array to a hex string
ethers.utils.hexlify([12, 34, 56]);
// '0x0c2238'

// Convert a number to a hex string
ethers.utils.hexlify(37);
// '0x25'

Errors¶

Cancelled Error¶

Any operation which requires the user to accept or decline, may reject with an error with the message cancelled. This could occur without user interaction, if for example, the application attempts to send a transaction, but the user is new and has not added an account.

Example:

somePromise.then(function(result) {
    // The call returned a result

}, function(error) {
    if (error.message === 'cancelled') {
        // Whatever needs to be done
    }
});

Server Error¶

Any operation that requests further information from the ethers.io services may reject with an error with the message server error.

Example:

somePromise.then(function(result) {
    // The call returned a result

}, function(error) {
    if (error.message === 'server error') {
        // Whatever needs to be done
    }
});