Merge pull request #3226 from ethereum/issue/1961

Implements sha3Raw and soliditySha3Raw

docs/web3-utils.rst

@@ -241,6 +241,8 @@ Example
 
 ------------------------------------------------------------------------------
 
+.. _utils-sha3:
+
 sha3
 =====================
 
@@ -287,10 +289,26 @@ Example
     > "0x2f20677459120677484f7104c76deb6846a2c071f9b3152c103bb12cd54d1a4a"
 
 
+------------------------------------------------------------------------------
+
+
+sha3Raw
+=====================
+
+.. code-block:: javascript
+
+    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.
+
+.. note::  Further details about this function can be seen here :ref:`sha3 <utils-sha3>`
+
+
 ------------------------------------------------------------------------------
 
 .. _utils-soliditysha3:
 
+
 soliditySha3
 =====================
 
@@ -371,6 +389,26 @@ Example
 
 
 
+------------------------------------------------------------------------------
+
+.. _utils-soliditysha3Raw:
+
+
+soliditySha3Raw
+=====================
+
+.. code-block:: javascript
+
+    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.
+
+
+.. note::  Further details about this function can be seen here :ref:`soliditySha3 <utils-soliditysha3>`
+
+
 ------------------------------------------------------------------------------
 
 isHex

packages/web3-utils/src/index.js

@@ -330,8 +330,10 @@ module.exports = {
     isHex: utils.isHex,
     isHexStrict: utils.isHexStrict,
     sha3: utils.sha3,
+    sha3Raw: utils.sha3Raw,
     keccak256: utils.sha3,
-    soliditySha3: soliditySha3,
+    soliditySha3: soliditySha3.soliditySha3,
+    soliditySha3Raw: soliditySha3.soliditySha3Raw,
     isAddress: utils.isAddress,
     checkAddressChecksum: utils.checkAddressChecksum,
     toChecksumAddress: toChecksumAddress,

packages/web3-utils/src/soliditySha3.js

@@ -241,5 +241,18 @@ var soliditySha3 = function () {
     return utils.sha3('0x'+ hexArgs.join(''));
 };
 
+/**
+ * Hashes solidity values to a sha3 hash using keccak 256 but does return the hash of value `null` instead of `null`
+ *
+ * @method soliditySha3Raw
+ * @return {Object} the sha3
+ */
+var soliditySha3Raw = function () {
+    return utils.sha3Raw('0x'+ _.map(Array.prototype.slice.call(arguments), _processSoliditySha3Args).join(''));
+};
+
 
-module.exports = soliditySha3;
+module.exports = {
+    soliditySha3: soliditySha3,
+    soliditySha3Raw: soliditySha3Raw
+};

packages/web3-utils/src/utils.js

@@ -493,6 +493,23 @@ var sha3 = function (value) {
 // expose the under the hood keccak256
 sha3._Hash = Hash;
 
+/**
+ * @method sha3Raw
+ *
+ * @param value
+ *
+ * @returns {string}
+ */
+var sha3Raw = function(value) {
+    value = sha3(value);
+
+    if (value === null) {
+        return SHA3_NULL_S;
+    }
+
+    return value;
+};
+
 
 module.exports = {
     BN: BN,
@@ -520,5 +537,6 @@ module.exports = {
     leftPad: leftPad,
     rightPad: rightPad,
     toTwosComplement: toTwosComplement,
-    sha3: sha3
+    sha3: sha3,
+    sha3Raw: sha3Raw
 };

packages/web3-utils/types/index.d.ts

@@ -95,7 +95,8 @@ export function padLeft(value: string | number, characterAmount: number, sign?:
 export function leftPad(string: string | number, characterAmount: number, sign?: string): string;
 export function rightPad(string: string | number, characterAmount: number, sign?: string): string;
 export function padRight(string: string | number, characterAmount: number, sign?: string): string;
-export function sha3(value: string | BN): string;
+export function sha3(value: string | BN): string | null;
+export function sha3Raw(value: string | BN): string;
 export function randomHex(bytesSize: number): string;
 export function utf8ToHex(string: string): string;
 export function stringToHex(string: string): string;
@@ -112,7 +113,8 @@ export function isContractAddressInBloom(bloom: string, contractAddress: string)
 export function isTopicInBloom(bloom: string, topic: string): boolean;
 export function isTopic(topic: string): boolean;
 export function jsonInterfaceMethodToString(abiItem: AbiItem): string;
-export function soliditySha3(...val: Mixed[]): string;
+export function soliditySha3(...val: Mixed[]): string | null;
+export function soliditySha3Raw(...val: Mixed[]): string;
 export function getUnitValue(unit: Unit): string;
 export function unitMap(): Units;
 export function testAddress(bloom: string, address: string): boolean;
@@ -149,7 +151,7 @@ export interface Utils {
     leftPad(string: string | number, characterAmount: number, sign?: string): string;
     rightPad(string: string | number, characterAmount: number, sign?: string): string;
     padRight(string: string | number, characterAmount: number, sign?: string): string;
-    sha3(value: string | BN): string;
+    sha3(value: string | BN): string | null;
     randomHex(bytesSize: number): string;
     utf8ToHex(string: string): string;
     stringToHex(string: string): string;
@@ -166,7 +168,8 @@ export interface Utils {
     isTopicInBloom(bloom: string, topic: string): boolean;
     isTopic(topic: string): boolean;
     jsonInterfaceMethodToString(abiItem: AbiItem): string;
-    soliditySha3(...val: Mixed[]): string;
+    soliditySha3(...val: Mixed[]): string | null;
+    soliditySha3Raw(...val: Mixed[]): string;
     getUnitValue(unit: Unit): string;
     unitMap(): Units;
     testAddress(bloom: string, address: string): boolean;

packages/web3-utils/types/tests/sha3-raw-test.ts

@@ -0,0 +1,44 @@
+/*
+    This file is part of web3.js.
+
+    web3.js is free software: you can redistribute it and/or modify
+    it under the terms of the GNU Lesser General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    web3.js is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU Lesser General Public License for more details.
+
+    You should have received a copy of the GNU Lesser General Public License
+    along with web3.js.  If not, see <http://www.gnu.org/licenses/>.
+*/
+/**
+ * @file sha3Raw-tests.ts
+ * @author Samuel Furter <[email protected]>
+ * @date 2019
+ */
+
+import BN = require('bn.js');
+import {sha3Raw} from 'web3-utils';
+
+// $ExpectType string
+sha3Raw('234');
+// $ExpectType string
+sha3Raw(new BN(3));
+
+// $ExpectError
+sha3Raw(['string']);
+// $ExpectError
+sha3Raw(234);
+// $ExpectError
+sha3Raw([4]);
+// $ExpectError
+sha3Raw({});
+// $ExpectError
+sha3Raw(true);
+// $ExpectError
+sha3Raw(null);
+// $ExpectError
+sha3Raw(undefined);

packages/web3-utils/types/tests/sha3-test.ts

@@ -23,9 +23,9 @@
 import BN = require('bn.js');
 import {sha3} from 'web3-utils';
 
-// $ExpectType string
+// $ExpectType string | null
 sha3('234');
-// $ExpectType string
+// $ExpectType string | null
 sha3(new BN(3));
 
 // $ExpectError

packages/web3-utils/types/tests/solidity-sha3-raw-test.ts

@@ -0,0 +1,52 @@
+/*
+    This file is part of web3.js.
+
+    web3.js is free software: you can redistribute it and/or modify
+    it under the terms of the GNU Lesser General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    web3.js is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU Lesser General Public License for more details.
+
+    You should have received a copy of the GNU Lesser General Public License
+    along with web3.js.  If not, see <http://www.gnu.org/licenses/>.
+*/
+/**
+ * @file solidity-sha3-raw-test.ts
+ * @author Josh Stevens <[email protected]>
+ * @date 2018
+ */
+
+import BN = require('bn.js');
+import {soliditySha3Raw} from 'web3-utils';
+
+// $ExpectType string
+soliditySha3Raw('234564535', '0xfff23243', true, -10);
+// $ExpectType string
+soliditySha3Raw('Hello!%');
+// $ExpectType string
+soliditySha3Raw('234');
+// $ExpectType string
+soliditySha3Raw(0xea);
+// $ExpectType string
+soliditySha3Raw(new BN(3));
+// $ExpectType string
+soliditySha3Raw({type: 'uint256', value: '234'});
+// $ExpectType string
+soliditySha3Raw({t: 'uint', v: new BN('234')});
+// $ExpectType string
+soliditySha3Raw({t: 'string', v: 'Hello!%'}, {t: 'int8', v: -23}, {t: 'address', v: '0x85F43D8a49eeB85d32Cf465507DD71d507100C1d'});
+// $ExpectType string
+soliditySha3Raw('0x407D73d8a49eeb85D32Cf465507dd71d507100c1');
+
+// $ExpectError
+soliditySha3Raw(['hey']);
+// $ExpectError
+soliditySha3Raw([34]);
+// $ExpectError
+soliditySha3Raw(null);
+// $ExpectError
+soliditySha3Raw(undefined);

packages/web3-utils/types/tests/solidity-sha3-test.ts

@@ -23,23 +23,23 @@
 import BN = require('bn.js');
 import {soliditySha3} from 'web3-utils';
 
-// $ExpectType string
+// $ExpectType string | null
 soliditySha3('234564535', '0xfff23243', true, -10);
-// $ExpectType string
+// $ExpectType string | null
 soliditySha3('Hello!%');
-// $ExpectType string
+// $ExpectType string | null
 soliditySha3('234');
-// $ExpectType string
+// $ExpectType string | null
 soliditySha3(0xea);
-// $ExpectType string
+// $ExpectType string | null
 soliditySha3(new BN(3));
-// $ExpectType string
+// $ExpectType string | null
 soliditySha3({type: 'uint256', value: '234'});
-// $ExpectType string
+// $ExpectType string | null
 soliditySha3({t: 'uint', v: new BN('234')});
-// $ExpectType string
+// $ExpectType string | null
 soliditySha3({t: 'string', v: 'Hello!%'}, {t: 'int8', v: -23}, {t: 'address', v: '0x85F43D8a49eeB85d32Cf465507DD71d507100C1d'});
-// $ExpectType string
+// $ExpectType string | null
 soliditySha3('0x407D73d8a49eeb85D32Cf465507dd71d507100c1');
 
 // $ExpectError

test/utils.sha3Raw.js

@@ -0,0 +1,22 @@
+var chai = require('chai');
+var assert = chai.assert;
+var cjsSha3 = require('crypto-js/sha3');
+var sha3Raw = require('../packages/web3-utils').sha3Raw;
+
+describe('web3.sha3Raw', function () {
+    it('should return the sha3 hash with hex prefix', function() {
+        assert.deepEqual(sha3Raw(''), '0xc5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470');
+    });
+
+    it('should return sha3 with hex prefix', function() {
+        assert.deepEqual(
+            sha3Raw('test123'),
+            '0x' + cjsSha3('test123', {outputLength: 256}).toString()
+        );
+
+        assert.deepEqual(
+            sha3Raw('test(int)'),
+            '0x' + cjsSha3('test(int)', {outputLength: 256}).toString()
+        );
+    });
+});

test/utils.soliditySha3Raw.js

@@ -0,0 +1,24 @@
+var chai = require('chai');
+var assert = chai.assert;
+var soliditySha3Raw = require('../packages/web3-utils').soliditySha3Raw;
+
+describe('web3.soliditySha3Raw', function () {
+    it('should return the sha3 hash of a empty string with hex prefix', function () {
+        assert.deepEqual(
+            soliditySha3Raw(
+                {t: 'string', v: ''}
+            ),
+            '0xc5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470'
+        );
+    });
+
+    it('should return the expected sha3 hash with hex prefix', function () {
+        assert.deepEqual(soliditySha3Raw(
+            'Hello!%',
+            2345676856,
+            '2342342342342342342345676856',
+            'Hello!%',
+            false
+        ), '0x7eb45eb9a0e1f6904514bc34c8b43e71c2e1f96f21b45ea284a0418cb351ec69');
+    });
+});