app3.utils¶

This package provides utility functions for APIS dapps and other app3js packages.

randomHex¶

app3.utils.randomHex(size)

The randomHex library to generate cryptographically strong pseudo-random HEX strings from a given byte size.

Parameters¶

size - Number: The byte size for the HEX string, e.g. 32 will result in a 32 bytes HEX string with 64 characters preficed with “0x”.

Returns¶

String: The generated random HEX string.

Example¶

app3.utils.randomHex(32)
> "0xa5b9d60f32436310afebcfda832817a68921beb782fabf7915cc0460b443116a"

app3.utils.randomHex(4)
> "0x6892ffc6"

app3.utils.randomHex(2)
> "0x99d6"

app3.utils.randomHex(1)
> "0x9a"

app3.utils.randomHex(0)
> "0x"

app3.utils._()

The underscore library for many convenience JavaScript functions.

See the underscore API reference for details.

Example¶

var _ = app3.utils._;

_.union([1,2],[3]);
> [1,2,3]

_.each({my: 'object'}, function(value, key){ ... })

...

BN¶

app3.utils.BN(mixed)

The BN.js library for calculating with big numbers in JavaScript. See the BN.js documentation for details.

Note

For safe conversion of many types, incl BigNumber.js use utils.toBN

Parameters¶

mixed - String|Number: A number, number string or HEX string to convert to a BN object.

Returns¶

Object: The BN.js instance.

Example¶

var BN = app3.utils.BN;

new BN(1234).toString();
> "1234"

new BN('1234').add(new BN('1')).toString();
> "1235"

new BN('0xea').toString();
> "234"

isBN¶

app3.utils.isBN(bn)

Checks if a given value is a BN.js instance.

Parameters¶

bn - Object: An BN.js instance.

Returns¶

Boolean

Example¶

var number = new BN(10);

app3.utils.isBN(number);
> true

isBigNumber¶

app3.utils.isBigNumber(bignumber)

Checks if a given value is a BigNumber.js instance.

Parameters¶

bignumber - Object: A BigNumber.js instance.

Returns¶

Boolean

Example¶

var number = new BigNumber(10);

app3.utils.isBigNumber(number);
> true

sha3¶

app3.utils.sha3(string)
app3.utils.keccak256(string) // ALIAS

Will calculate the sha3 of the input.

Note

To mimic the sha3 behaviour of solidity use soliditySha3

Parameters¶

string - String: A string to hash.

Returns¶

String: the result hash.

Example¶

app3.utils.sha3('234'); // taken as string
> "0xc1912fee45d61c87cc5ea59dae311904cd86b84fee17cc96966216f811ce6a79"

app3.utils.sha3(new BN('234'));
> "0xbc36789e7a1e281436464229828f817d6612f7b477d66591ff96a9e064bcc98a"

app3.utils.sha3(234);
> null // can't calculate the has of a number

app3.utils.sha3(0xea); // same as above, just the HEX representation of the number
> null

app3.utils.sha3('0xea'); // will be converted to a byte array first, and then hashed
> "0x2f20677459120677484f7104c76deb6846a2c071f9b3152c103bb12cd54d1a4a"

soliditySha3¶

app3.utils.soliditySha3(param1 [, param2, ...])

Will calculate the sha3 of given input parameters in the same way solidity would. This means arguments will be ABI converted and tightly packed before being hashed.

Parameters¶

paramX - Mixed: Any type, or an object with {type: 'uint', value: '123456'} or {t: 'bytes', v: '0xfff456'}. Basic types are autodetected as follows:
- String non numerical UTF-8 string is interpreted as string.
- String|Number|BN|HEX positive number is interpreted as uint256.
- String|Number|BN negative number is interpreted as int256.
- Boolean as bool.
- String HEX string with leading 0x is interpreted as bytes.
- HEX HEX number representation is interpreted as uint256.

Returns¶

String: the result hash.

Example¶

app3.utils.soliditySha3('234564535', '0xfff23243', true, -10);
// auto detects:        uint256,      bytes,     bool,   int256
> "0x3e27a893dc40ef8a7f0841d96639de2f58a132be5ae466d40087a2cfa83b7179"


app3.utils.soliditySha3('Hello!%'); // auto detects: string
> "0x661136a4267dba9ccdf6bfddb7c00e714de936674c4bdb065a531cf1cb15c7fc"


app3.utils.soliditySha3('234'); // auto detects: uint256
> "0x61c831beab28d67d1bb40b5ae1a11e2757fa842f031a2d0bc94a7867bc5d26c2"

app3.utils.soliditySha3(0xea); // same as above
> "0x61c831beab28d67d1bb40b5ae1a11e2757fa842f031a2d0bc94a7867bc5d26c2"

app3.utils.soliditySha3(new BN('234')); // same as above
> "0x61c831beab28d67d1bb40b5ae1a11e2757fa842f031a2d0bc94a7867bc5d26c2"

app3.utils.soliditySha3({type: 'uint256', value: '234'})); // same as above
> "0x61c831beab28d67d1bb40b5ae1a11e2757fa842f031a2d0bc94a7867bc5d26c2"

app3.utils.soliditySha3({t: 'uint', v: new BN('234')})); // same as above
> "0x61c831beab28d67d1bb40b5ae1a11e2757fa842f031a2d0bc94a7867bc5d26c2"


app3.utils.soliditySha3('0x407D73d8a49eeb85D32Cf465507dd71d507100c1');
> "0x4e8ebbefa452077428f93c9520d3edd60594ff452a29ac7d2ccc11d47f3ab95b"

app3.utils.soliditySha3({t: 'bytes', v: '0x407D73d8a49eeb85D32Cf465507dd71d507100c1'});
> "0x4e8ebbefa452077428f93c9520d3edd60594ff452a29ac7d2ccc11d47f3ab95b" // same result as above


app3.utils.soliditySha3({t: 'address', v: '0x407D73d8a49eeb85D32Cf465507dd71d507100c1'});
> "0x4e8ebbefa452077428f93c9520d3edd60594ff452a29ac7d2ccc11d47f3ab95b" // same as above, but will do a checksum check, if its multi case


app3.utils.soliditySha3({t: 'bytes32', v: '0x407D73d8a49eeb85D32Cf465507dd71d507100c1'});
> "0x3c69a194aaf415ba5d6afca734660d0a3d45acdc05d54cd1ca89a8988e7625b4" // different result as above


app3.utils.soliditySha3({t: 'string', v: 'Hello!%'}, {t: 'int8', v:-23}, {t: 'address', v: '0x85F43D8a49eeB85d32Cf465507DD71d507100C1d'});
> "0xa13b31627c1ed7aaded5aecec71baf02fe123797fffd45e662eac8e06fbe4955"

isHex¶

app3.utils.isHex(hex)

Checks if a given string is a HEX string.

Parameters¶

hex - String|HEX: The given HEX string.

Returns¶

Boolean

Example¶

app3.utils.isHex('0xc1912');
> true

app3.utils.isHex(0xc1912);
> true

app3.utils.isHex('c1912');
> true

app3.utils.isHex(345);
> true // this is tricky, as 345 can be a a HEX representation or a number, be careful when not having a 0x in front!

app3.utils.isHex('0xZ1912');
> false

app3.utils.isHex('Hello');
> false

isHexStrict¶

app3.utils.isHexStrict(hex)

Checks if a given string is a HEX string. Difference to app3.utils.isHex() is that it expects HEX to be prefixed with 0x.

Parameters¶

hex - String|HEX: The given HEX string.

Returns¶

Boolean

Example¶

app3.utils.isHexStrict('0xc1912');
> true

app3.utils.isHexStrict(0xc1912);
> false

app3.utils.isHexStrict('c1912');
> false

app3.utils.isHexStrict(345);
> false // this is tricky, as 345 can be a a HEX representation or a number, be careful when not having a 0x in front!

app3.utils.isHexStrict('0xZ1912');
> false

app3.utils.isHex('Hello');
> false

isAddress¶

app3.utils.isAddress(address)

Checks if a given string is a valid APIS address. It will also check the checksum, if the address has upper and lowercase letters.

Parameters¶

address - String: An address string.

Returns¶

Boolean

Example¶

app3.utils.isAddress('0xc1912fee45d61c87cc5ea59dae31190fffff232d');
> true

app3.utils.isAddress('c1912fee45d61c87cc5ea59dae31190fffff232d');
> true

app3.utils.isAddress('0XC1912FEE45D61C87CC5EA59DAE31190FFFFF232D');
> true // as all is uppercase, no checksum will be checked

app3.utils.isAddress('0xc1912fEE45d61C87Cc5EA59DaE31190FFFFf232d');
> true

app3.utils.isAddress('0xC1912fEE45d61C87Cc5EA59DaE31190FFFFf232d');
> false // wrong checksum

toChecksumAddress¶

app3.utils.toChecksumAddress(address)

Will convert an upper or lowercase APIS address to a checksum address.

Parameters¶

address - String: An address string.

Returns¶

String: The checksum address.

Example¶

app3.utils.toChecksumAddress('0xc1912fee45d61c87cc5ea59dae31190fffff2323');
> "0xc1912fEE45d61C87Cc5EA59DaE31190FFFFf232d"

app3.utils.toChecksumAddress('0XC1912FEE45D61C87CC5EA59DAE31190FFFFF232D');
> "0xc1912fEE45d61C87Cc5EA59DaE31190FFFFf232d" // same as above

checkAddressChecksum¶

app3.utils.checkAddressChecksum(address)

Checks the checksum of a given address. Will also return false on non-checksum addresses.

Parameters¶

address - String: An address string.

Returns¶

Boolean: true when the checksum of the address is valid, false if its not a checksum address, or the checksum is invalid.

Example¶

app3.utils.checkAddressChecksum('0xc1912fEE45d61C87Cc5EA59DaE31190FFFFf232d');
> true

toHex¶

app3.utils.toHex(mixed)

Will auto convert any given value to HEX. Number strings will interpreted as numbers. Text strings will be interpreted as UTF-8 strings.

Parameters¶

mixed - String|Number|BN|BigNumber: The input to convert to HEX.

Returns¶

String: The resulting HEX string.

Example¶

app3.utils.toHex('234');
> "0xea"

app3.utils.toHex(234);
> "0xea"

app3.utils.toHex(new BN('234'));
> "0xea"

app3.utils.toHex(new BigNumber('234'));
> "0xea"

app3.utils.toHex('I have 100€');
> "0x49206861766520313030e282ac"

toBN¶

app3.utils.toBN(number)

Will safely convert any given value (including BigNumber.js instances) into a BN.js instance, for handling big numbers in JavaScript.

Note

For just the BN.js class use utils.BN

Parameters¶

number - String|Number|HEX: Number to convert to a big number.

Returns¶

Object: The BN.js instance.

Example¶

app3.utils.toBN(1234).toString();
> "1234"

app3.utils.toBN('1234').add(app3.utils.toBN('1')).toString();
> "1235"

app3.utils.toBN('0xea').toString();
> "234"

hexToNumberString¶

app3.utils.hexToNumberString(hex)

Returns the number representation of a given HEX value as a string.

Parameters¶

hexString - String|HEX: A string to hash.

Returns¶

String: The number as a string.

Example¶

app3.utils.hexToNumberString('0xea');
> "234"

hexToNumber¶

app3.utils.hexToNumber(hex)
app3.utils.toDecimal(hex) // ALIAS, deprecated

Returns the number representation of a given HEX value.

Note

This is not useful for big numbers, rather use utils.toBN instead.

Parameters¶

hexString - String|HEX: A string to hash.

Returns¶

Number

Example¶

app3.utils.hexToNumber('0xea');
> 234

numberToHex¶

app3.utils.numberToHex(number)
app3.utils.fromDecimal(number) // ALIAS, deprecated

Returns the HEX representation of a given number value.

Parameters¶

number - String|Number|BN|BigNumber: A number as string or number.

Returns¶

String: The HEX value of the given number.

Example¶

app3.utils.numberToHex('234');
> '0xea'

hexToUtf8¶

app3.utils.hexToUtf8(hex)
app3.utils.hexToString(hex) // ALIAS
app3.utils.toUtf8(hex) // ALIAS, deprecated

Returns the UTF-8 string representation of a given HEX value.

Parameters¶

hex - String: A HEX string to convert to a UTF-8 string.

Returns¶

String: The UTF-8 string.

Example¶

app3.utils.hexToUtf8('0x49206861766520313030e282ac');
> "I have 100€"

hexToAscii¶

app3.utils.hexToAscii(hex)
app3.utils.toAscii(hex) // ALIAS, deprecated

Returns the ASCII string representation of a given HEX value.

Parameters¶

hex - String: A HEX string to convert to a ASCII string.

Returns¶

String: The ASCII string.

Example¶

app3.utils.hexToAscii('0x4920686176652031303021');
> "I have 100!"

utf8ToHex¶

app3.utils.utf8ToHex(string)
app3.utils.stringToHex(string) // ALIAS
app3.utils.fromUtf8(string) // ALIAS, deprecated

Returns the HEX representation of a given UTF-8 string.

Parameters¶

string - String: A UTF-8 string to convert to a HEX string.

Returns¶

String: The HEX string.

Example¶

app3.utils.utf8ToHex('I have 100€');
> "0x49206861766520313030e282ac"

asciiToHex¶

app3.utils.asciiToHex(string)
app3.utils.fromAscii(string) // ALIAS, deprecated

Returns the HEX representation of a given ASCII string.

Parameters¶

string - String: A ASCII string to convert to a HEX string.

Returns¶

String: The HEX string.

Example¶

app3.utils.asciiToHex('I have 100!');
> "0x4920686176652031303021"

hexToBytes¶

app3.utils.hexToBytes(hex)

Returns a byte array from the given HEX string.

Parameters¶

hex - String|HEX: A HEX to convert.

Returns¶

Array: The byte array.

Example¶

app3.utils.hexToBytes('0x000000ea');
> [ 0, 0, 0, 234 ]

app3.utils.hexToBytes(0x000000ea);
> [ 234 ]

bytesToHex¶

app3.utils.bytesToHex(byteArray)

Returns a HEX string from a byte array.

Parameters¶

byteArray - Array: A byte array to convert.

Returns¶

String: The HEX string.

Example¶

app3.utils.bytesToHex([ 72, 101, 108, 108, 111, 33, 36 ]);
> "0x48656c6c6f2125"

padLeft¶

app3.utils.padLeft(string, characterAmount [, sign])
app3.utils.leftPad(string, characterAmount [, sign]) // ALIAS

Adds a padding on the left of a string, Useful for adding paddings to HEX strings.

Parameters¶

string - String: The string to add padding on the left.
characterAmount - Number: The number of characters the total string should have.
sign - String (optional): The character sign to use, defaults to "0".

Returns¶

String: The padded string.

Example¶

app3.utils.padLeft('0x3456ff', 20);
> "0x000000000000003456ff"

app3.utils.padLeft(0x3456ff, 20);
> "0x000000000000003456ff"

app3.utils.padLeft('Hello', 20, 'x');
> "xxxxxxxxxxxxxxxHello"

padRight¶

app3.utils.padRight(string, characterAmount [, sign])
app3.utils.rightPad(string, characterAmount [, sign]) // ALIAS

Adds a padding on the right of a string, Useful for adding paddings to HEX strings.

Parameters¶

string - String: The string to add padding on the right.
characterAmount - Number: The number of characters the total string should have.
sign - String (optional): The character sign to use, defaults to "0".

Returns¶

String: The padded string.

Example¶

app3.utils.padRight('0x3456ff', 20);
> "0x3456ff00000000000000"

app3.utils.padRight(0x3456ff, 20);
> "0x3456ff00000000000000"

app3.utils.padRight('Hello', 20, 'x');
> "Helloxxxxxxxxxxxxxxx"

toTwosComplement¶

app3.utils.toTwosComplement(number)

Converts a negative numer into a two’s complement.

Parameters¶

number - Number|String|BigNumber: The number to convert.

Returns¶

String: The converted hex string.

Example¶

app3.utils.toTwosComplement('-1');
> "0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff"

app3.utils.toTwosComplement(-1);
> "0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff"

app3.utils.toTwosComplement('0x1');
> "0x0000000000000000000000000000000000000000000000000000000000000001"

app3.utils.toTwosComplement(-15);
> "0xfffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff1"

app3.utils.toTwosComplement('-0x1');
> "0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff"