web3.utils¶
해당 package 는 Ethereum dapps 와 다른 web3.js packages 를 위한 utility functions 를 제공한다.
Bloom Filters¶
bloom filters 란?¶
Bloom Filter 는 set membership 의 신속한 확인을 위한 확률적이고 공간 효율적인 데이터 구조이다. 그것은 아직 당신에게 큰 의미가 없을 것이다. 그렇기에 Bloom Filters 가 어떻게 사용될 수 있는지 알아본다.
우리가 매우 큰 데이터 세트를 가지고있고, 어떠한 요소가 현재 그 세트 안에 있는지 빠르게 테스트하길 바란다고 가정해보자. 확인을 위한 단순한 방법은 요소가 존재하는지 세트에 query 하는 것일 수도 있다. 그 방법은 데이터 세트가 상대적으로 작다면 아마 괜찮을 것이다. 그러나 만약 데이터 세트가 매우 크다면, 이러한 탐색은 시간이 걸릴 것이다. 다행이도, 우리는 Ethereum 세계에서 속도를 높일 수 있는 방법을 가지고 있다!
Bloom Filter 는 이러한 방법 중 하나이다. Bloom Filter 의 기본 개념은 데이터 세트로 들어가는 각각의 새로운 요소를 해시하고, 이 해시로 부터 특정 비트를 가져온 다음, 그 비트를 사용하여 고정 크기 비트 배열의 일부를 채우는 것이다(예: 특정 비트를 1로 설정). 이 비트 배열을 Bloom Filter 라고 한다.
나중에 어떤 요소가 세트에 있는지 확인하고 싶을 때, 우리는 단순히 요소를 해시하고 적절한 비트가 Bloom Filter 에 있는지 확인한다. 비트 중 하나 이상이 0이면 해당 요소가 데이터 집합에 없는 것이 확실하다! 모든 비트가 1이면 요소가 데이터 집합에 있을 수 있지만 실제로 데이터 베이스를 query 하여 확인해야 한다. 그래서 우리는 잘못된 긍정 결과를 얻을 수도 있지만, 결코 잘못된 부정 결과는 얻을 수 없을 것이다. 이 것은 우리가 해야하는 데이터베이스의 query 수를 크게 줄일 수 있다.
실제 사례
이 것이 유용한 Ethereum 실제 사례의 예로 가능한 한 실시간에 가깝게 유지되도록 모든 새로운 블록에서 사용자 균형을 업데이트 하려는 경우를 들 수 있다. 모든 새로운 블록에 Bloom Filter 를 사용하지 않으면 사용자가 블록 내에서 어떠한 활동도 하지 않더라도 균형을 맞춰야 할 것이다. 그러나 블록의 logBlooms 를 사용하면 더 느린 작업을 수행하기 전에 사용자들의 ethereum 주소에 대해 Bloom Filter 를 테스트 할 수 있으며, 이는 해당 ethereum 주소가 해당 블록 내에 있는 경우에만 추가 작업을 수행하므로(잘못된 긍정 결과를 최소화하여) 통신량을 크게 줄일 수 있다. 이 것은 당신의 앱에 매우 효과적일 것이다.
randomHex¶
web3.utils.randomHex(size)
주어진 바이트 크기에서 의사 난수로 강력하게 암호화된 HEX 문자열을 생성하기 위한 randomHex 라이브러리.
parameters¶
size
-Number
: HEX 문자열에 대한 바이트 크기, 예를 들어 ``32``는 "0x"로 미리 만들어진 64자의 HEX 문자열을 32바이트로 만든다.
Returns¶
String
: 무작위로 생성된 HEX 문자열.
예제¶
web3.utils.randomHex(32)
> "0xa5b9d60f32436310afebcfda832817a68921beb782fabf7915cc0460b443116a"
web3.utils.randomHex(4)
> "0x6892ffc6"
web3.utils.randomHex(2)
> "0x99d6"
web3.utils.randomHex(1)
> "0x9a"
web3.utils.randomHex(0)
> "0x"
_¶
web3.utils._()
많은 편리한 JavaScript 기능들을 위한 underscore 라이브러리
예제¶
var _ = web3.utils._;
_.union([1,2],[3]);
> [1,2,3]
_.each({my: 'object'}, function(value, key){ ... })
...
BN¶
web3.utils.BN(mixed)
The BN.js library for calculating with big numbers in JavaScript. See the BN.js documentation for details.
주석
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.
Example¶
var BN = web3.utils.BN;
new BN(1234).toString();
> "1234"
new BN('1234').add(new BN('1')).toString();
> "1235"
new BN('0xea').toString();
> "234"
isBN¶
web3.utils.isBN(bn)
Checks if a given value is a BN.js instance.
Returns¶
Boolean
Example¶
var number = new BN(10);
web3.utils.isBN(number);
> true
isBigNumber¶
web3.utils.isBigNumber(bignumber)
Checks if a given value is a BigNumber.js instance.
Parameters¶
bignumber
-Object
: A BigNumber.js instance.
Returns¶
Boolean
sha3¶
web3.utils.sha3(string)
web3.utils.keccak256(string) // ALIAS
Will calculate the sha3 of the input.
주석
To mimic the sha3 behaviour of solidity use soliditySha3
Parameters¶
string
-String
: A string to hash.
Returns¶
String
: the result hash.
Example¶
web3.utils.sha3('234'); // taken as string
> "0xc1912fee45d61c87cc5ea59dae311904cd86b84fee17cc96966216f811ce6a79"
web3.utils.sha3(new BN('234'));
> "0xbc36789e7a1e281436464229828f817d6612f7b477d66591ff96a9e064bcc98a"
web3.utils.sha3(234);
> null // can't calculate the has of a number
web3.utils.sha3(0xea); // same as above, just the HEX representation of the number
> null
web3.utils.sha3('0xea'); // will be converted to a byte array first, and then hashed
> "0x2f20677459120677484f7104c76deb6846a2c071f9b3152c103bb12cd54d1a4a"
sha3Raw¶
web3.utils.sha3Raw(string)
Will calculate the sha3 of the input but does return the hash value instead of null
if for example a empty string is passed.
주석
Further details about this function can be seen here sha3
soliditySha3¶
web3.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 asstring
.String|Number|BN|HEX
positive number is interpreted asuint256
.String|Number|BN
negative number is interpreted asint256
.Boolean
asbool
.String
HEX string with leading0x
is interpreted asbytes
.HEX
HEX number representation is interpreted asuint256
.
Returns¶
String
: the result hash.
Example¶
web3.utils.soliditySha3('234564535', '0xfff23243', true, -10);
// auto detects: uint256, bytes, bool, int256
> "0x3e27a893dc40ef8a7f0841d96639de2f58a132be5ae466d40087a2cfa83b7179"
web3.utils.soliditySha3('Hello!%'); // auto detects: string
> "0x661136a4267dba9ccdf6bfddb7c00e714de936674c4bdb065a531cf1cb15c7fc"
web3.utils.soliditySha3('234'); // auto detects: uint256
> "0x61c831beab28d67d1bb40b5ae1a11e2757fa842f031a2d0bc94a7867bc5d26c2"
web3.utils.soliditySha3(0xea); // same as above
> "0x61c831beab28d67d1bb40b5ae1a11e2757fa842f031a2d0bc94a7867bc5d26c2"
web3.utils.soliditySha3(new BN('234')); // same as above
> "0x61c831beab28d67d1bb40b5ae1a11e2757fa842f031a2d0bc94a7867bc5d26c2"
web3.utils.soliditySha3({type: 'uint256', value: '234'})); // same as above
> "0x61c831beab28d67d1bb40b5ae1a11e2757fa842f031a2d0bc94a7867bc5d26c2"
web3.utils.soliditySha3({t: 'uint', v: new BN('234')})); // same as above
> "0x61c831beab28d67d1bb40b5ae1a11e2757fa842f031a2d0bc94a7867bc5d26c2"
web3.utils.soliditySha3('0x407D73d8a49eeb85D32Cf465507dd71d507100c1');
> "0x4e8ebbefa452077428f93c9520d3edd60594ff452a29ac7d2ccc11d47f3ab95b"
web3.utils.soliditySha3({t: 'bytes', v: '0x407D73d8a49eeb85D32Cf465507dd71d507100c1'});
> "0x4e8ebbefa452077428f93c9520d3edd60594ff452a29ac7d2ccc11d47f3ab95b" // same result as above
web3.utils.soliditySha3({t: 'address', v: '0x407D73d8a49eeb85D32Cf465507dd71d507100c1'});
> "0x4e8ebbefa452077428f93c9520d3edd60594ff452a29ac7d2ccc11d47f3ab95b" // same as above, but will do a checksum check, if its multi case
web3.utils.soliditySha3({t: 'bytes32', v: '0x407D73d8a49eeb85D32Cf465507dd71d507100c1'});
> "0x3c69a194aaf415ba5d6afca734660d0a3d45acdc05d54cd1ca89a8988e7625b4" // different result as above
web3.utils.soliditySha3({t: 'string', v: 'Hello!%'}, {t: 'int8', v:-23}, {t: 'address', v: '0x85F43D8a49eeB85d32Cf465507DD71d507100C1d'});
> "0xa13b31627c1ed7aaded5aecec71baf02fe123797fffd45e662eac8e06fbe4955"
soliditySha3Raw¶
web3.utils.soliditySha3Raw(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.
The difference between this function and the soliditySha3
function is that it will return the hash value instead of null
if for example a empty string is given.
주석
Further details about this function can be seen here soliditySha3
isHex¶
web3.utils.isHex(hex)
Checks if a given string is a HEX string.
Parameters¶
hex
-String|HEX
: The given HEX string.
Returns¶
Boolean
Example¶
web3.utils.isHex('0xc1912');
> true
web3.utils.isHex(0xc1912);
> true
web3.utils.isHex('c1912');
> true
web3.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!
web3.utils.isHex('0xZ1912');
> false
web3.utils.isHex('Hello');
> false
isHexStrict¶
web3.utils.isHexStrict(hex)
Checks if a given string is a HEX string. Difference to web3.utils.isHex()
is that it expects HEX to be prefixed with 0x
.
Parameters¶
hex
-String|HEX
: The given HEX string.
Returns¶
Boolean
Example¶
web3.utils.isHexStrict('0xc1912');
> true
web3.utils.isHexStrict(0xc1912);
> false
web3.utils.isHexStrict('c1912');
> false
web3.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!
web3.utils.isHexStrict('0xZ1912');
> false
web3.utils.isHex('Hello');
> false
isAddress¶
web3.utils.isAddress(address)
Checks if a given string is a valid Ethereum address. It will also check the checksum, if the address has upper and lowercase letters.
Parameters¶
address
-String
: An address string.
Returns¶
Boolean
Example¶
web3.utils.isAddress('0xc1912fee45d61c87cc5ea59dae31190fffff232d');
> true
web3.utils.isAddress('c1912fee45d61c87cc5ea59dae31190fffff232d');
> true
web3.utils.isAddress('0XC1912FEE45D61C87CC5EA59DAE31190FFFFF232D');
> true // as all is uppercase, no checksum will be checked
web3.utils.isAddress('0xc1912fEE45d61C87Cc5EA59DaE31190FFFFf232d');
> true
web3.utils.isAddress('0xC1912fEE45d61C87Cc5EA59DaE31190FFFFf232d');
> false // wrong checksum
toChecksumAddress¶
web3.utils.toChecksumAddress(address)
Will convert an upper or lowercase Ethereum address to a checksum address.
Parameters¶
address
-String
: An address string.
Returns¶
String
: The checksum address.
Example¶
web3.utils.toChecksumAddress('0xc1912fee45d61c87cc5ea59dae31190fffff232d');
> "0xc1912fEE45d61C87Cc5EA59DaE31190FFFFf232d"
web3.utils.toChecksumAddress('0XC1912FEE45D61C87CC5EA59DAE31190FFFFF232D');
> "0xc1912fEE45d61C87Cc5EA59DaE31190FFFFf232d" // same as above
checkAddressChecksum¶
web3.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¶
web3.utils.checkAddressChecksum('0xc1912fEE45d61C87Cc5EA59DaE31190FFFFf232d');
> true
toHex¶
web3.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¶
web3.utils.toHex('234');
> "0xea"
web3.utils.toHex(234);
> "0xea"
web3.utils.toHex(new BN('234'));
> "0xea"
web3.utils.toHex(new BigNumber('234'));
> "0xea"
web3.utils.toHex('I have 100€');
> "0x49206861766520313030e282ac"
toBN¶
web3.utils.toBN(number)
Will safely convert any given value (including BigNumber.js instances) into a BN.js instance, for handling big numbers in JavaScript.
Parameters¶
number
-String|Number|HEX
: Number to convert to a big number.
Example¶
web3.utils.toBN(1234).toString();
> "1234"
web3.utils.toBN('1234').add(web3.utils.toBN('1')).toString();
> "1235"
web3.utils.toBN('0xea').toString();
> "234"
hexToNumberString¶
web3.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¶
web3.utils.hexToNumberString('0xea');
> "234"
hexToNumber¶
web3.utils.hexToNumber(hex)
web3.utils.toDecimal(hex) // ALIAS, deprecated
Returns the number representation of a given HEX value.
주석
This is not useful for big numbers, rather use utils.toBN instead.
Parameters¶
hexString
-String|HEX
: A string to hash.
Returns¶
Number
Example¶
web3.utils.hexToNumber('0xea');
> 234
numberToHex¶
web3.utils.numberToHex(number)
web3.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¶
web3.utils.numberToHex('234');
> '0xea'
hexToUtf8¶
web3.utils.hexToUtf8(hex)
web3.utils.hexToString(hex) // ALIAS
web3.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¶
web3.utils.hexToUtf8('0x49206861766520313030e282ac');
> "I have 100€"
hexToAscii¶
web3.utils.hexToAscii(hex)
web3.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.
utf8ToHex¶
web3.utils.utf8ToHex(string)
web3.utils.stringToHex(string) // ALIAS
web3.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¶
web3.utils.utf8ToHex('I have 100€');
> "0x49206861766520313030e282ac"
asciiToHex¶
web3.utils.asciiToHex(string)
web3.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¶
web3.utils.asciiToHex('I have 100!');
> "0x4920686176652031303021"
hexToBytes¶
web3.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¶
web3.utils.hexToBytes('0x000000ea');
> [ 0, 0, 0, 234 ]
web3.utils.hexToBytes(0x000000ea);
> [ 234 ]
bytesToHex¶
web3.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¶
web3.utils.bytesToHex([ 72, 101, 108, 108, 111, 33, 36 ]);
> "0x48656c6c6f2125"
toWei¶
web3.utils.toWei(number [, unit])
Converts any ether value value into wei.
주석
"wei" are the smallest ethere unit, and you should always make calculations in wei and convert only for display reasons.
Parameters¶
number
-String|BN
: The value.unit
-String
(optional, defaults to"ether"
): The ether to convert from. Possible units are:noether
: '0'wei
: '1'kwei
: '1000'Kwei
: '1000'babbage
: '1000'femtoether
: '1000'mwei
: '1000000'Mwei
: '1000000'lovelace
: '1000000'picoether
: '1000000'gwei
: '1000000000'Gwei
: '1000000000'shannon
: '1000000000'nanoether
: '1000000000'nano
: '1000000000'szabo
: '1000000000000'microether
: '1000000000000'micro
: '1000000000000'finney
: '1000000000000000'milliether
: '1000000000000000'milli
: '1000000000000000'ether
: '1000000000000000000'kether
: '1000000000000000000000'grand
: '1000000000000000000000'mether
: '1000000000000000000000000'gether
: '1000000000000000000000000000'tether
: '1000000000000000000000000000000'
Example¶
web3.utils.toWei('1', 'ether');
> "1000000000000000000"
web3.utils.toWei('1', 'finney');
> "1000000000000000"
web3.utils.toWei('1', 'szabo');
> "1000000000000"
web3.utils.toWei('1', 'shannon');
> "1000000000"
fromWei¶
web3.utils.fromWei(number [, unit])
Converts any wei value into a ether value.
주석
"wei" are the smallest ethere unit, and you should always make calculations in wei and convert only for display reasons.
Parameters¶
number
-String|BN
: The value in wei.unit
-String
(optional, defaults to"ether"
): The ether to convert to. Possible units are:noether
: '0'wei
: '1'kwei
: '1000'Kwei
: '1000'babbage
: '1000'femtoether
: '1000'mwei
: '1000000'Mwei
: '1000000'lovelace
: '1000000'picoether
: '1000000'gwei
: '1000000000'Gwei
: '1000000000'shannon
: '1000000000'nanoether
: '1000000000'nano
: '1000000000'szabo
: '1000000000000'microether
: '1000000000000'micro
: '1000000000000'finney
: '1000000000000000'milliether
: '1000000000000000'milli
: '1000000000000000'ether
: '1000000000000000000'kether
: '1000000000000000000000'grand
: '1000000000000000000000'mether
: '1000000000000000000000000'gether
: '1000000000000000000000000000'tether
: '1000000000000000000000000000000'
Returns¶
String
: It always returns a string number.
Example¶
web3.utils.fromWei('1', 'ether');
> "0.000000000000000001"
web3.utils.fromWei('1', 'finney');
> "0.000000000000001"
web3.utils.fromWei('1', 'szabo');
> "0.000000000001"
web3.utils.fromWei('1', 'shannon');
> "0.000000001"
unitMap¶
web3.utils.unitMap
Shows all possible ether value and their amount in wei.
Return value¶
Object
with the following properties:noether
: '0'wei
: '1'kwei
: '1000'Kwei
: '1000'babbage
: '1000'femtoether
: '1000'mwei
: '1000000'Mwei
: '1000000'lovelace
: '1000000'picoether
: '1000000'gwei
: '1000000000'Gwei
: '1000000000'shannon
: '1000000000'nanoether
: '1000000000'nano
: '1000000000'szabo
: '1000000000000'microether
: '1000000000000'micro
: '1000000000000'finney
: '1000000000000000'milliether
: '1000000000000000'milli
: '1000000000000000'ether
: '1000000000000000000'kether
: '1000000000000000000000'grand
: '1000000000000000000000'mether
: '1000000000000000000000000'gether
: '1000000000000000000000000000'tether
: '1000000000000000000000000000000'
Example¶
web3.utils.unitMap
> {
noether: '0',
wei: '1',
kwei: '1000',
Kwei: '1000',
babbage: '1000',
femtoether: '1000',
mwei: '1000000',
Mwei: '1000000',
lovelace: '1000000',
picoether: '1000000',
gwei: '1000000000',
Gwei: '1000000000',
shannon: '1000000000',
nanoether: '1000000000',
nano: '1000000000',
szabo: '1000000000000',
microether: '1000000000000',
micro: '1000000000000',
finney: '1000000000000000',
milliether: '1000000000000000',
milli: '1000000000000000',
ether: '1000000000000000000',
kether: '1000000000000000000000',
grand: '1000000000000000000000',
mether: '1000000000000000000000000',
gether: '1000000000000000000000000000',
tether: '1000000000000000000000000000000'
}
padLeft¶
web3.utils.padLeft(string, characterAmount [, sign])
web3.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¶
web3.utils.padLeft('0x3456ff', 20);
> "0x000000000000003456ff"
web3.utils.padLeft(0x3456ff, 20);
> "0x000000000000003456ff"
web3.utils.padLeft('Hello', 20, 'x');
> "xxxxxxxxxxxxxxxHello"
padRight¶
web3.utils.padRight(string, characterAmount [, sign])
web3.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¶
web3.utils.padRight('0x3456ff', 20);
> "0x3456ff00000000000000"
web3.utils.padRight(0x3456ff, 20);
> "0x3456ff00000000000000"
web3.utils.padRight('Hello', 20, 'x');
> "Helloxxxxxxxxxxxxxxx"
toTwosComplement¶
web3.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¶
web3.utils.toTwosComplement('-1');
> "0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff"
web3.utils.toTwosComplement(-1);
> "0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff"
web3.utils.toTwosComplement('0x1');
> "0x0000000000000000000000000000000000000000000000000000000000000001"
web3.utils.toTwosComplement(-15);
> "0xfffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff1"
web3.utils.toTwosComplement('-0x1');
> "0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff"