diff --git a/CHANGELOG.md b/CHANGELOG.md index 89b50feb070..b0d5b3ed240 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -58,6 +58,7 @@ Released with 1.0.0-beta.37 code base. - Add `eth.getChainId` method (#3113) - Minified file added to web3 package (#3131) - The transaction confirmation workflow can now be configured (#3130) +- Bloom filters added to web3.utils (#3137) ### Fixed diff --git a/docs/web3-utils.rst b/docs/web3-utils.rst index 0fa751ffd33..bda7dd6b1b7 100644 --- a/docs/web3-utils.rst +++ b/docs/web3-utils.rst @@ -6,6 +6,42 @@ web3.utils This package provides utility functions for Ethereum dapps and other web3.js packages. +------------------------------------------------------------------------------ + +Bloom Filters +===================== + +----------------------- +What are bloom filters? +----------------------- + +A Bloom filter is a probabilistic, space-efficient data structure used for fast checks of set membership. That probably doesn’t mean much to you yet, and so let’s explore how bloom filters might be used. + +Imagine that we have some large set of data, and we want to be able to quickly test if some element is currently in that set. The naive way of checking might be to query the set to see if our element is in there. That’s probably fine if our data set is relatively small. Unfortunately, if our data set is really big, this search might take a while. Luckily, we have tricks to speed things up in the ethereum world! + +A bloom filter is one of these tricks. The basic idea behind the Bloom filter is to hash each new element that goes into the data set, take certain bits from this hash, and then use those bits to fill in parts of a fixed-size bit array (e.g. set certain bits to 1). This bit array is called a bloom filter. + +Later, when we want to check if an element is in the set, we simply hash the element and check that the right bits are in the bloom filter. If at least one of the bits is 0, then the element definitely isn’t in our data set! If all of the bits are 1, then the element might be in the data set, but we need to actually query the database to be sure. So we might have false positives, but we’ll never have false negatives. This can greatly reduce the number of database queries we have to make. + +**Real Life Example** + +A ethereum real life example in where this is useful is if you want to update a users balance on every new block so it stays as close to real time as possible. Without using a bloom filter on every new block you would have to force the balances even if that user may not of had any activity within that block. But if you use the logBlooms from the block you can test the bloom filter against the users ethereum address before you do any more slow operations, this will dramatically decrease the amount of calls you do as you will only be doing those extra operations if that ethereum address is within that block (minus the false positives outcome which will be negligible). This will be highly performant for your app. + +--------- +Functions +--------- + +- `web3.utils.isBloom `_ +- `web3.utils.isUserEthereumAddressInBloom `_ +- `web3.utils.isContractAddressInBloom `_ +- `web3.utils.isTopic `_ +- `web3.utils.isTopicInBloom `_ +- `web3.utils.isInBloom `_ + + +.. note:: Please raise any issues `here `_ + + ------------------------------------------------------------------------------ randomHex diff --git a/packages/web3-utils/package-lock.json b/packages/web3-utils/package-lock.json index 2afa763b103..8446e08b573 100644 --- a/packages/web3-utils/package-lock.json +++ b/packages/web3-utils/package-lock.json @@ -1,11 +1,14 @@ { - "requires": true, + "name": "web3-utils", + "version": "1.2.1", "lockfileVersion": 1, + "requires": true, "dependencies": { "@babel/code-frame": { "version": "7.5.5", "resolved": "https://registry.npmjs.org/@babel/code-frame/-/code-frame-7.5.5.tgz", "integrity": "sha512-27d4lZoomVyo51VegxI20xZPuSHusqbQag/ztrBC7wegWoQ1nLREPVSKSW8byhTlzTKyNE4ifaTA6lCp7JjpFw==", + "dev": true, "requires": { "@babel/highlight": "^7.0.0" } @@ -14,6 +17,7 @@ "version": "7.5.0", "resolved": "https://registry.npmjs.org/@babel/highlight/-/highlight-7.5.0.tgz", "integrity": "sha512-7dV4eu9gBxoM0dAnj/BCFDW9LFU0zvTrkq0ugM7pnHEgguOEeOz1so2ZghEdzviYzQEED0r4EAgpsBChKy1TRQ==", + "dev": true, "requires": { "chalk": "^2.0.0", "esutils": "^2.0.2", @@ -23,12 +27,14 @@ "@types/parsimmon": { "version": "1.10.0", "resolved": "https://registry.npmjs.org/@types/parsimmon/-/parsimmon-1.10.0.tgz", - "integrity": "sha512-bsTIJFVQv7jnvNiC42ld2pQW2KRI+pAG243L+iATvqzy3X6+NH1obz2itRKDZZ8VVhN3wjwYax/VBGCcXzgTqQ==" + "integrity": "sha512-bsTIJFVQv7jnvNiC42ld2pQW2KRI+pAG243L+iATvqzy3X6+NH1obz2itRKDZZ8VVhN3wjwYax/VBGCcXzgTqQ==", + "dev": true }, "ansi-styles": { "version": "3.2.1", "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-3.2.1.tgz", "integrity": "sha512-VT0ZI6kZRdTh8YyJw3SMbYm/u+NqfsAxEpWO0Pf9sq8/e94WxxOpPKx9FR1FlyCtOVDNOQ+8ntlqFxiRc+r5qA==", + "dev": true, "requires": { "color-convert": "^1.9.0" } @@ -37,6 +43,7 @@ "version": "1.0.10", "resolved": "https://registry.npmjs.org/argparse/-/argparse-1.0.10.tgz", "integrity": "sha512-o5Roy6tNG4SL/FOkCAN6RzjiakZS25RLYFrcMttJqbdd8BWrnA+fGz57iN5Pb06pvBGvl5gQ0B48dJlslXvoTg==", + "dev": true, "requires": { "sprintf-js": "~1.0.2" } @@ -44,7 +51,8 @@ "balanced-match": { "version": "1.0.0", "resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-1.0.0.tgz", - "integrity": "sha1-ibTRmasr7kneFk6gK4nORi1xt2c=" + "integrity": "sha1-ibTRmasr7kneFk6gK4nORi1xt2c=", + "dev": true }, "bn.js": { "version": "4.11.8", @@ -55,6 +63,7 @@ "version": "1.1.11", "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.11.tgz", "integrity": "sha512-iCuPHDFgrHX7H2vEI/5xpz07zSHB00TpugqhmYtVmMO6518mCuRMoOYFldEBl0g187ufozdaHgWKcYFb61qGiA==", + "dev": true, "requires": { "balanced-match": "^1.0.0", "concat-map": "0.0.1" @@ -73,12 +82,14 @@ "builtin-modules": { "version": "1.1.1", "resolved": "https://registry.npmjs.org/builtin-modules/-/builtin-modules-1.1.1.tgz", - "integrity": "sha1-Jw8HbFpywC9bZaR9+Uxf46J4iS8=" + "integrity": "sha1-Jw8HbFpywC9bZaR9+Uxf46J4iS8=", + "dev": true }, "chalk": { "version": "2.4.2", "resolved": "https://registry.npmjs.org/chalk/-/chalk-2.4.2.tgz", "integrity": "sha512-Mti+f9lpJNcwF4tWV8/OrTTtF1gZi+f8FqlyAdouralcFWFQWF2+NgCHShjkCb+IFBLq9buZwE1xckQU4peSuQ==", + "dev": true, "requires": { "ansi-styles": "^3.2.1", "escape-string-regexp": "^1.0.5", @@ -89,6 +100,7 @@ "version": "1.9.3", "resolved": "https://registry.npmjs.org/color-convert/-/color-convert-1.9.3.tgz", "integrity": "sha512-QfAUtd+vFdAtFQcC8CCyYt1fYWxSqAiK2cSD6zDB8N3cpsEBAvRxp9zOGg6G/SHHJYAT88/az/IuDGALsNVbGg==", + "dev": true, "requires": { "color-name": "1.1.3" } @@ -96,17 +108,20 @@ "color-name": { "version": "1.1.3", "resolved": "https://registry.npmjs.org/color-name/-/color-name-1.1.3.tgz", - "integrity": "sha1-p9BVi9icQveV3UIyj3QIMcpTvCU=" + "integrity": "sha1-p9BVi9icQveV3UIyj3QIMcpTvCU=", + "dev": true }, "commander": { "version": "2.20.3", "resolved": "https://registry.npmjs.org/commander/-/commander-2.20.3.tgz", - "integrity": "sha512-GpVkmM8vF2vQUkj2LvZmD35JxeJOLCwJ9cUkugyk2nuhbv3+mJvpLYYt+0+USMxE+oj+ey/lJEnhZw75x/OMcQ==" + "integrity": "sha512-GpVkmM8vF2vQUkj2LvZmD35JxeJOLCwJ9cUkugyk2nuhbv3+mJvpLYYt+0+USMxE+oj+ey/lJEnhZw75x/OMcQ==", + "dev": true }, "concat-map": { "version": "0.0.1", "resolved": "https://registry.npmjs.org/concat-map/-/concat-map-0.0.1.tgz", - "integrity": "sha1-2Klr13/Wjfd5OnMDajug1UBdR3s=" + "integrity": "sha1-2Klr13/Wjfd5OnMDajug1UBdR3s=", + "dev": true }, "decode-uri-component": { "version": "0.2.0", @@ -133,6 +148,7 @@ "version": "1.2.0", "resolved": "https://registry.npmjs.org/definitelytyped-header-parser/-/definitelytyped-header-parser-1.2.0.tgz", "integrity": "sha512-xpg8uu/2YD/reaVsZV4oJ4g7UDYFqQGWvT1W9Tsj6q4VtWBSaig38Qgah0ZMnQGF9kAsAim08EXDO1nSi0+Nog==", + "dev": true, "requires": { "@types/parsimmon": "^1.3.0", "parsimmon": "^1.2.0" @@ -141,7 +157,8 @@ "diff": { "version": "4.0.1", "resolved": "https://registry.npmjs.org/diff/-/diff-4.0.1.tgz", - "integrity": "sha512-s2+XdvhPCOF01LRQBC8hf4vhbVmI2CGS5aZnxLJlT5FtdhPCDFq80q++zK2KlrVorVDdL5BOGZ/VfLrVtYNF+Q==" + "integrity": "sha512-s2+XdvhPCOF01LRQBC8hf4vhbVmI2CGS5aZnxLJlT5FtdhPCDFq80q++zK2KlrVorVDdL5BOGZ/VfLrVtYNF+Q==", + "dev": true }, "dom-walk": { "version": "0.1.1", @@ -152,6 +169,7 @@ "version": "0.4.2", "resolved": "https://registry.npmjs.org/dtslint/-/dtslint-0.4.2.tgz", "integrity": "sha512-ph4GXLw3HYzlQMJOFcpCqWHuL3MxJ/344OR7wn0wlQGchQGTIVNsSUl8iKEMatpy2geNMysgA9fQa6xVhHOkTQ==", + "dev": true, "requires": { "definitelytyped-header-parser": "github:Microsoft/definitelytyped-header-parser#production", "fs-extra": "^6.0.1", @@ -163,6 +181,7 @@ "definitelytyped-header-parser": { "version": "github:Microsoft/definitelytyped-header-parser#d957ad0bb2f4ecb60ac04f734e0b38fbc8e70b8a", "from": "github:Microsoft/definitelytyped-header-parser#production", + "dev": true, "requires": { "@types/parsimmon": "^1.3.0", "parsimmon": "^1.2.0" @@ -210,17 +229,20 @@ "escape-string-regexp": { "version": "1.0.5", "resolved": "https://registry.npmjs.org/escape-string-regexp/-/escape-string-regexp-1.0.5.tgz", - "integrity": "sha1-G2HAViGQqN/2rjuyzwIAyhMLhtQ=" + "integrity": "sha1-G2HAViGQqN/2rjuyzwIAyhMLhtQ=", + "dev": true }, "esprima": { "version": "4.0.1", "resolved": "https://registry.npmjs.org/esprima/-/esprima-4.0.1.tgz", - "integrity": "sha512-eGuFFw7Upda+g4p+QHvnW0RyTX/SVeJBDM/gCtMARO0cLuT2HcEKnTPvhjV6aGeqrCB/sbNop0Kszm0jsaWU4A==" + "integrity": "sha512-eGuFFw7Upda+g4p+QHvnW0RyTX/SVeJBDM/gCtMARO0cLuT2HcEKnTPvhjV6aGeqrCB/sbNop0Kszm0jsaWU4A==", + "dev": true }, "esutils": { "version": "2.0.3", "resolved": "https://registry.npmjs.org/esutils/-/esutils-2.0.3.tgz", - "integrity": "sha512-kVscqXk4OCp68SZ0dkgEKVi6/8ij300KBWTJq32P/dYeWTSwK41WyTxalN1eRmA5Z9UU/LX9D7FWSmV9SAYx6g==" + "integrity": "sha512-kVscqXk4OCp68SZ0dkgEKVi6/8ij300KBWTJq32P/dYeWTSwK41WyTxalN1eRmA5Z9UU/LX9D7FWSmV9SAYx6g==", + "dev": true }, "eth-lib": { "version": "0.2.7", @@ -232,6 +254,14 @@ "xhr-request-promise": "^0.1.2" } }, + "ethereum-bloom-filters": { + "version": "1.0.6", + "resolved": "https://registry.npmjs.org/ethereum-bloom-filters/-/ethereum-bloom-filters-1.0.6.tgz", + "integrity": "sha512-dE9CGNzgOOsdh7msZirvv8qjHtnHpvBlKe2647kM8v+yeF71IRso55jpojemvHV+jMjr48irPWxMRaHuOWzAFA==", + "requires": { + "js-sha3": "^0.8.0" + } + }, "ethjs-unit": { "version": "0.1.6", "resolved": "https://registry.npmjs.org/ethjs-unit/-/ethjs-unit-0.1.6.tgz", @@ -260,6 +290,7 @@ "version": "6.0.1", "resolved": "https://registry.npmjs.org/fs-extra/-/fs-extra-6.0.1.tgz", "integrity": "sha512-GnyIkKhhzXZUWFCaJzvyDLEEgDkPfb4/TPvJCJVuS8MWZgoSsErf++QpiAlDnKFcqhRlm+tIOcencCjyJE6ZCA==", + "dev": true, "requires": { "graceful-fs": "^4.1.2", "jsonfile": "^4.0.0", @@ -269,7 +300,8 @@ "fs.realpath": { "version": "1.0.0", "resolved": "https://registry.npmjs.org/fs.realpath/-/fs.realpath-1.0.0.tgz", - "integrity": "sha1-FQStJSMVjKpA20onh8sBQRmU6k8=" + "integrity": "sha1-FQStJSMVjKpA20onh8sBQRmU6k8=", + "dev": true }, "function-bind": { "version": "1.1.1", @@ -280,6 +312,7 @@ "version": "7.1.4", "resolved": "https://registry.npmjs.org/glob/-/glob-7.1.4.tgz", "integrity": "sha512-hkLPepehmnKk41pUGm3sYxoFs/umurYfYJCerbXEyFIWcAzvpipAgVkBqqT9RBKMGjnq6kMuyYwha6csxbiM1A==", + "dev": true, "requires": { "fs.realpath": "^1.0.0", "inflight": "^1.0.4", @@ -301,7 +334,8 @@ "graceful-fs": { "version": "4.2.2", "resolved": "https://registry.npmjs.org/graceful-fs/-/graceful-fs-4.2.2.tgz", - "integrity": "sha512-IItsdsea19BoLC7ELy13q1iJFNmd7ofZH5+X/pJr90/nRoPEX0DJo1dHDbgtYWOhJhcCgMDTOw84RZ72q6lB+Q==" + "integrity": "sha512-IItsdsea19BoLC7ELy13q1iJFNmd7ofZH5+X/pJr90/nRoPEX0DJo1dHDbgtYWOhJhcCgMDTOw84RZ72q6lB+Q==", + "dev": true }, "has": { "version": "1.0.3", @@ -314,7 +348,8 @@ "has-flag": { "version": "3.0.0", "resolved": "https://registry.npmjs.org/has-flag/-/has-flag-3.0.0.tgz", - "integrity": "sha1-tdRU3CGZriJWmfNGfloH87lVuv0=" + "integrity": "sha1-tdRU3CGZriJWmfNGfloH87lVuv0=", + "dev": true }, "has-symbols": { "version": "1.0.0", @@ -344,6 +379,7 @@ "version": "1.0.6", "resolved": "https://registry.npmjs.org/inflight/-/inflight-1.0.6.tgz", "integrity": "sha1-Sb1jMdfQLQwJvJEKEHW6gWW1bfk=", + "dev": true, "requires": { "once": "^1.3.0", "wrappy": "1" @@ -390,15 +426,22 @@ "has-symbols": "^1.0.0" } }, + "js-sha3": { + "version": "0.8.0", + "resolved": "https://registry.npmjs.org/js-sha3/-/js-sha3-0.8.0.tgz", + "integrity": "sha512-gF1cRrHhIzNfToc802P800N8PpXS+evLLXfsVpowqmAFR9uwbi89WvXg2QspOmXL8QL86J4T1EpFu+yUkwJY3Q==" + }, "js-tokens": { "version": "4.0.0", "resolved": "https://registry.npmjs.org/js-tokens/-/js-tokens-4.0.0.tgz", - "integrity": "sha512-RdJUflcE3cUzKiMqQgsCu06FPu9UdIJO0beYbPhHN4k6apgJtifcoCtT9bcxOpYBtpD2kCM6Sbzg4CausW/PKQ==" + "integrity": "sha512-RdJUflcE3cUzKiMqQgsCu06FPu9UdIJO0beYbPhHN4k6apgJtifcoCtT9bcxOpYBtpD2kCM6Sbzg4CausW/PKQ==", + "dev": true }, "js-yaml": { "version": "3.13.1", "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-3.13.1.tgz", "integrity": "sha512-YfbcO7jXDdyj0DGxYVSlSeQNHbD7XPWvrVWeVUujrQEoZzWJIRrCPoyk6kL6IAjAG2IolMK4T0hNUe0HOUs5Jw==", + "dev": true, "requires": { "argparse": "^1.0.7", "esprima": "^4.0.0" @@ -408,6 +451,7 @@ "version": "4.0.0", "resolved": "https://registry.npmjs.org/jsonfile/-/jsonfile-4.0.0.tgz", "integrity": "sha1-h3Gq4HmbZAdrdmQPygWPnBDjPss=", + "dev": true, "requires": { "graceful-fs": "^4.1.6" } @@ -439,6 +483,7 @@ "version": "3.0.4", "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-3.0.4.tgz", "integrity": "sha512-yJHVQEhyqPLUTgt9B83PXu6W3rx4MvvHvSUvToogpwoGDOUQ+yDrR0HRot+yOCdCO7u4hX3pWft6kWBBcqh0UA==", + "dev": true, "requires": { "brace-expansion": "^1.1.7" } @@ -446,12 +491,14 @@ "minimist": { "version": "0.0.8", "resolved": "https://registry.npmjs.org/minimist/-/minimist-0.0.8.tgz", - "integrity": "sha1-hX/Kv8M5fSYluCKCYuhqp6ARsF0=" + "integrity": "sha1-hX/Kv8M5fSYluCKCYuhqp6ARsF0=", + "dev": true }, "mkdirp": { "version": "0.5.1", "resolved": "https://registry.npmjs.org/mkdirp/-/mkdirp-0.5.1.tgz", "integrity": "sha1-MAV0OOrGz3+MR2fzhkjWaX11yQM=", + "dev": true, "requires": { "minimist": "0.0.8" } @@ -502,17 +549,20 @@ "parsimmon": { "version": "1.13.0", "resolved": "https://registry.npmjs.org/parsimmon/-/parsimmon-1.13.0.tgz", - "integrity": "sha512-5UIrOCW+gjbILkjKPgTgmq8LKf8TT3Iy7kN2VD7OtQ81facKn8B4gG1X94jWqXYZsxG2KbJhrv/Yq/5H6BQn7A==" + "integrity": "sha512-5UIrOCW+gjbILkjKPgTgmq8LKf8TT3Iy7kN2VD7OtQ81facKn8B4gG1X94jWqXYZsxG2KbJhrv/Yq/5H6BQn7A==", + "dev": true }, "path-is-absolute": { "version": "1.0.1", "resolved": "https://registry.npmjs.org/path-is-absolute/-/path-is-absolute-1.0.1.tgz", - "integrity": "sha1-F0uSaHNVNP+8es5r9TpanhtcX18=" + "integrity": "sha1-F0uSaHNVNP+8es5r9TpanhtcX18=", + "dev": true }, "path-parse": { "version": "1.0.6", "resolved": "https://registry.npmjs.org/path-parse/-/path-parse-1.0.6.tgz", - "integrity": "sha512-GSmOT2EbHrINBf9SR7CDELwlJ8AENk3Qn7OikK4nFYAu3Ote2+JYNVvkpAEQm3/TLNEJFD/xZJjzyxg3KBWOzw==" + "integrity": "sha512-GSmOT2EbHrINBf9SR7CDELwlJ8AENk3Qn7OikK4nFYAu3Ote2+JYNVvkpAEQm3/TLNEJFD/xZJjzyxg3KBWOzw==", + "dev": true }, "process": { "version": "0.5.2", @@ -541,6 +591,7 @@ "version": "1.12.0", "resolved": "https://registry.npmjs.org/resolve/-/resolve-1.12.0.tgz", "integrity": "sha512-B/dOmuoAik5bKcD6s6nXDCjzUKnaDvdkRyAk6rsmsKLipWj4797iothd7jmmUhWTfinVMU+wc56rYKsit2Qy4w==", + "dev": true, "requires": { "path-parse": "^1.0.6" } @@ -553,7 +604,8 @@ "semver": { "version": "5.7.1", "resolved": "https://registry.npmjs.org/semver/-/semver-5.7.1.tgz", - "integrity": "sha512-sauaDf/PZdVgrLTNYHRtpXa1iRiKcaebiKQ1BJdpQlWH2lCvexQdX55snPFyK7QzpudqbCI0qXFfOasHdyNDGQ==" + "integrity": "sha512-sauaDf/PZdVgrLTNYHRtpXa1iRiKcaebiKQ1BJdpQlWH2lCvexQdX55snPFyK7QzpudqbCI0qXFfOasHdyNDGQ==", + "dev": true }, "simple-concat": { "version": "1.0.0", @@ -573,7 +625,8 @@ "sprintf-js": { "version": "1.0.3", "resolved": "https://registry.npmjs.org/sprintf-js/-/sprintf-js-1.0.3.tgz", - "integrity": "sha1-BOaSb2YolTVPPdAVIDYzuFcpfiw=" + "integrity": "sha1-BOaSb2YolTVPPdAVIDYzuFcpfiw=", + "dev": true }, "strict-uri-encode": { "version": "1.1.0", @@ -601,12 +654,14 @@ "strip-json-comments": { "version": "2.0.1", "resolved": "https://registry.npmjs.org/strip-json-comments/-/strip-json-comments-2.0.1.tgz", - "integrity": "sha1-PFMZQukIwml8DsNEhYwobHygpgo=" + "integrity": "sha1-PFMZQukIwml8DsNEhYwobHygpgo=", + "dev": true }, "supports-color": { "version": "5.5.0", "resolved": "https://registry.npmjs.org/supports-color/-/supports-color-5.5.0.tgz", "integrity": "sha512-QjVjwdXIt408MIiAqCX4oUKsgU2EqAGzs2Ppkm4aQYbjm+ZEWEcW4SfFNTr4uMNZma0ey4f5lgLrkB0aX0QMow==", + "dev": true, "requires": { "has-flag": "^3.0.0" } @@ -619,12 +674,14 @@ "tslib": { "version": "1.10.0", "resolved": "https://registry.npmjs.org/tslib/-/tslib-1.10.0.tgz", - "integrity": "sha512-qOebF53frne81cf0S9B41ByenJ3/IuH8yJKngAX35CmiZySA0khhkovshKK+jGCaMnVomla7gVlIcc3EvKPbTQ==" + "integrity": "sha512-qOebF53frne81cf0S9B41ByenJ3/IuH8yJKngAX35CmiZySA0khhkovshKK+jGCaMnVomla7gVlIcc3EvKPbTQ==", + "dev": true }, "tslint": { "version": "5.20.0", "resolved": "https://registry.npmjs.org/tslint/-/tslint-5.20.0.tgz", "integrity": "sha512-2vqIvkMHbnx8acMogAERQ/IuINOq6DFqgF8/VDvhEkBqQh/x6SP0Y+OHnKth9/ZcHQSroOZwUQSN18v8KKF0/g==", + "dev": true, "requires": { "@babel/code-frame": "^7.0.0", "builtin-modules": "^1.1.1", @@ -645,6 +702,7 @@ "version": "2.29.0", "resolved": "https://registry.npmjs.org/tsutils/-/tsutils-2.29.0.tgz", "integrity": "sha512-g5JVHCIJwzfISaXpXE1qvNalca5Jwob6FjI4AoPlqMusJ6ftFE7IkkFoMhVLRgK+4Kx3gkzb8UZK5t5yTTvEmA==", + "dev": true, "requires": { "tslib": "^1.8.1" } @@ -652,7 +710,8 @@ "typescript": { "version": "3.7.0-dev.20191015", "resolved": "https://registry.npmjs.org/typescript/-/typescript-3.7.0-dev.20191015.tgz", - "integrity": "sha512-Cpfj1n4pEUVKL+jtS0mkZodJffyMmf3Wk/UjyZMGX4fsjK5KBPJf3NUlyXij8I8p1E2CAomdS5NPFrAR+z8pKw==" + "integrity": "sha512-Cpfj1n4pEUVKL+jtS0mkZodJffyMmf3Wk/UjyZMGX4fsjK5KBPJf3NUlyXij8I8p1E2CAomdS5NPFrAR+z8pKw==", + "dev": true }, "underscore": { "version": "1.9.1", @@ -662,7 +721,8 @@ "universalify": { "version": "0.1.2", "resolved": "https://registry.npmjs.org/universalify/-/universalify-0.1.2.tgz", - "integrity": "sha512-rBJeI5CXAlmy1pV+617WB9J63U6XcazHHF2f2dbJix4XzpUF0RS3Zbj0FGIOCAva5P/d/GBOYaACQ1w+0azUkg==" + "integrity": "sha512-rBJeI5CXAlmy1pV+617WB9J63U6XcazHHF2f2dbJix4XzpUF0RS3Zbj0FGIOCAva5P/d/GBOYaACQ1w+0azUkg==", + "dev": true }, "url-set-query": { "version": "1.0.0", diff --git a/packages/web3-utils/package.json b/packages/web3-utils/package.json index ffa2bc41960..2af56567c7c 100644 --- a/packages/web3-utils/package.json +++ b/packages/web3-utils/package.json @@ -15,6 +15,7 @@ "dependencies": { "bn.js": "4.11.8", "eth-lib": "0.2.7", + "ethereum-bloom-filters": "^1.0.6", "ethjs-unit": "0.1.6", "number-to-bn": "1.7.0", "randombytes": "^2.1.0", diff --git a/packages/web3-utils/src/utils.js b/packages/web3-utils/src/utils.js index f4bb1ef420d..386131b0d25 100644 --- a/packages/web3-utils/src/utils.js +++ b/packages/web3-utils/src/utils.js @@ -25,6 +25,8 @@ var BN = require('bn.js'); var numberToBN = require('number-to-bn'); var utf8 = require('utf8'); var Hash = require("eth-lib/lib/hash"); +var ethereumBloomFilters = require('ethereum-bloom-filters'); + /** @@ -387,17 +389,78 @@ var isHex = function (hex) { }; /** - * Check if string is HEX + * Returns true if given string is a valid Ethereum block header bloom. * - * @method isHex - * @param {String} hex to be checked - * @returns {Boolean} + * @method isBloom + * @param {String} hex encoded bloom filter + * @return {Boolean} */ -var isHex = function (hex) { - return ((_.isString(hex) || _.isNumber(hex)) && /^(-0x)?(0x)?[0-9a-f]*$/i.test(hex)); +var isBloom = function (bloom) { + return ethereumBloomFilters.isBloom(bloom); +}; + +/** + * Returns true if the ethereum users address is part of the given bloom + * note: false positives are possible. + * + * @method isUserEthereumAddressInBloom + * @param {String} hex encoded bloom filter + * @param {String} hex ethereum addresss + * @return {Boolean} + */ +var isUserEthereumAddressInBloom = function (bloom, ethereumAddress) { + return ethereumBloomFilters.isUserEthereumAddressInBloom(bloom, ethereumAddress); +}; + +/** + * Returns true if the contract address is part of the given bloom + * note: false positives are possible. + * + * @method isUserEthereumAddressInBloom + * @param {String} hex encoded bloom filter + * @param {String} hex contract addresss + * @return {Boolean} + */ +var isContractAddressInBloom = function (bloom, contractAddress) { + return ethereumBloomFilters.isContractAddressInBloom(bloom, contractAddress); }; +/** + * Returns true if given string is a valid log topic. + * + * @method isTopic + * @param {String} hex encoded topic + * @return {Boolean} + */ +var isTopic = function (topic) { + return ethereumBloomFilters.isTopic(topic); +}; +/** + * Returns true if the topic is part of the given bloom + * note: false positives are possible. + * + * @method isTopicInBloom + * @param {String} hex encoded bloom filter + * @param {String} hex encoded topic + * @return {Boolean} + */ +var isTopicInBloom = function (bloom, topic) { + return ethereumBloomFilters.isTopicInBloom(bloom, topic); +}; + +/** + * Returns true if the value is part of the given bloom + * note: false positives are possible. + * + * @method isInBloom + * @param {String} hex encoded bloom filter + * @param {String | Uint8Array} topic encoded value + * @return {Boolean} + */ +var isInBloom = function (bloom, topic) { + return ethereumBloomFilters.isInBloom(bloom, topic); +}; /** * Hashes values to a sha3 hash using keccak 256 @@ -436,6 +499,12 @@ module.exports = { isBigNumber: isBigNumber, toBN: toBN, isAddress: isAddress, + isBloom: isBloom, + isUserEthereumAddressInBloom: isUserEthereumAddressInBloom, + isContractAddressInBloom: isContractAddressInBloom, + isTopic: isTopic, + isTopicInBloom: isTopicInBloom, + isInBloom: isInBloom, checkAddressChecksum: checkAddressChecksum, utf8ToHex: utf8ToHex, hexToUtf8: hexToUtf8, diff --git a/packages/web3-utils/types/index.d.ts b/packages/web3-utils/types/index.d.ts index afdb12d385f..2b6e79bc7f4 100644 --- a/packages/web3-utils/types/index.d.ts +++ b/packages/web3-utils/types/index.d.ts @@ -106,6 +106,10 @@ export function toUtf8(string: string): string; export function toWei(val: BN, unit?: Unit): BN; export function toWei(val: string, unit?: Unit): string; export function isBloom(bloom: string): boolean; +export function isInBloom(bloom: string, value: string | Uint8Array): boolean; +export function isUserEthereumAddressInBloom(bloom: string, ethereumAddress: string): boolean; +export function isContractAddressInBloom(bloom: string, contractAddress: string): boolean; +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; @@ -156,6 +160,10 @@ export interface Utils { toWei(val: BN, unit?: Unit): BN; toWei(val: string, unit?: Unit): string; isBloom(bloom: string): boolean; + isInBloom(bloom: string, value: string | Uint8Array): boolean; + isUserEthereumAddressInBloom(bloom: string, ethereumAddress: string): boolean; + isContractAddressInBloom(bloom: string, contractAddress: string): boolean; + isTopicInBloom(bloom: string, topic: string): boolean; isTopic(topic: string): boolean; jsonInterfaceMethodToString(abiItem: AbiItem): string; soliditySha3(...val: Mixed[]): string; diff --git a/packages/web3-utils/types/tests/is-bloom-test.ts b/packages/web3-utils/types/tests/is-bloom-test.ts index e0256e92fc8..2caaddbf80d 100644 --- a/packages/web3-utils/types/tests/is-bloom-test.ts +++ b/packages/web3-utils/types/tests/is-bloom-test.ts @@ -17,11 +17,11 @@ /** * @file is-bloom-tests.ts * @author Josh Stevens - * @date 2018 + * @date 2019 */ import BN = require('bn.js'); -import {isBloom} from 'web3-utils'; +import { isBloom } from 'web3-utils'; // $ExpectType boolean isBloom('0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef'); diff --git a/packages/web3-utils/types/tests/is-contract-address-in-bloom.ts b/packages/web3-utils/types/tests/is-contract-address-in-bloom.ts new file mode 100644 index 00000000000..37c587880fe --- /dev/null +++ b/packages/web3-utils/types/tests/is-contract-address-in-bloom.ts @@ -0,0 +1,26 @@ +/* + 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 . +*/ +/** + * @file is-contract-address-in-bloom.ts + * @author Josh Stevens + * @date 2019 + */ + +import { isContractAddressInBloom } from 'web3-utils'; + +// $ExpectType boolean +isContractAddressInBloom('0x08200081a06415012858022200cc48143008908c0000824e5405b41520795989024800380a8d4b198910b422b231086c3a62cc402e2573070306f180446440ad401016c3e30781115844d028c89028008a12240c0a2c184c0425b90d7af0530002f981221aa565809132000818c82805023a132a25150400010530ba0080420a10a137054454021882505080a6b6841082d84151010400ba8100c8802d440d060388084052c1300105a0868410648a40540c0f0460e190400807008914361118000a5202e94445ccc088311050052c8002807205212a090d90ba428030266024a910644b1042011aaae05391cc2094c45226400000380880241282ce4e12518c', '0x494bfa3a4576ba6cfe835b0deb78834f0c3e3994'); diff --git a/packages/web3-utils/types/tests/is-in-bloom.ts b/packages/web3-utils/types/tests/is-in-bloom.ts new file mode 100644 index 00000000000..e2ef4fab346 --- /dev/null +++ b/packages/web3-utils/types/tests/is-in-bloom.ts @@ -0,0 +1,26 @@ +/* + 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 . +*/ +/** + * @file is-in-bloom-tests.ts + * @author Josh Stevens + * @date 2019 + */ + +import { isInBloom } from 'web3-utils'; + +// $ExpectType boolean +isInBloom('0x08200081a06415012858022200cc48143008908c0000824e5405b41520795989024800380a8d4b198910b422b231086c3a62cc402e2573070306f180446440ad401016c3e30781115844d028c89028008a12240c0a2c184c0425b90d7af0530002f981221aa565809132000818c82805023a132a25150400010530ba0080420a10a137054454021882505080a6b6841082d84151010400ba8100c8802d440d060388084052c1300105a0868410648a40540c0f0460e190400807008914361118000a5202e94445ccc088311050052c8002807205212a090d90ba428030266024a910644b1042011aaae05391cc2094c45226400000380880241282ce4e12518c', '0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef'); diff --git a/packages/web3-utils/types/tests/is-topic-in-bloom.ts b/packages/web3-utils/types/tests/is-topic-in-bloom.ts new file mode 100644 index 00000000000..e49126bf80a --- /dev/null +++ b/packages/web3-utils/types/tests/is-topic-in-bloom.ts @@ -0,0 +1,26 @@ +/* + 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 . +*/ +/** + * @file is-topic-in-bloom.ts + * @author Josh Stevens + * @date 2019 + */ + +import { isTopicInBloom } from 'web3-utils'; + +// $ExpectType boolean +isTopicInBloom('0x08200081a06415012858022200cc48143008908c0000824e5405b41520795989024800380a8d4b198910b422b231086c3a62cc402e2573070306f180446440ad401016c3e30781115844d028c89028008a12240c0a2c184c0425b90d7af0530002f981221aa565809132000818c82805023a132a25150400010530ba0080420a10a137054454021882505080a6b6841082d84151010400ba8100c8802d440d060388084052c1300105a0868410648a40540c0f0460e190400807008914361118000a5202e94445ccc088311050052c8002807205212a090d90ba428030266024a910644b1042011aaae05391cc2094c45226400000380880241282ce4e12518c', '0x4d61726b65745061792e696f206973206465706c6f79696e6720536d61727420'); diff --git a/packages/web3-utils/types/tests/is-topic.ts b/packages/web3-utils/types/tests/is-topic.ts new file mode 100644 index 00000000000..468cc655c23 --- /dev/null +++ b/packages/web3-utils/types/tests/is-topic.ts @@ -0,0 +1,26 @@ +/* + 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 . +*/ +/** + * @file is-user-ethereum-address-in-bloom.ts + * @author Josh Stevens + * @date 2019 + */ + +import { isTopic } from 'web3-utils'; + +// $ExpectType boolean +isTopic('0x000000000000000000000000b3bb037d2f2341a1c2775d51909a3d944597987d'); diff --git a/packages/web3-utils/types/tests/is-user-ethereum-address-in-bloom.ts b/packages/web3-utils/types/tests/is-user-ethereum-address-in-bloom.ts new file mode 100644 index 00000000000..2fadb639680 --- /dev/null +++ b/packages/web3-utils/types/tests/is-user-ethereum-address-in-bloom.ts @@ -0,0 +1,26 @@ +/* + 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 . +*/ +/** + * @file is-user-ethereum-address-in-bloom.ts + * @author Josh Stevens + * @date 2019 + */ + +import { isUserEthereumAddressInBloom } from 'web3-utils'; + +// $ExpectType boolean +isUserEthereumAddressInBloom('0x08200081a06415012858022200cc48143008908c0000824e5405b41520795989024800380a8d4b198910b422b231086c3a62cc402e2573070306f180446440ad401016c3e30781115844d028c89028008a12240c0a2c184c0425b90d7af0530002f981221aa565809132000818c82805023a132a25150400010530ba0080420a10a137054454021882505080a6b6841082d84151010400ba8100c8802d440d060388084052c1300105a0868410648a40540c0f0460e190400807008914361118000a5202e94445ccc088311050052c8002807205212a090d90ba428030266024a910644b1042011aaae05391cc2094c45226400000380880241282ce4e12518c', '0x494bfa3a4576ba6cfe835b0deb78834f0c3e3994'); diff --git a/packages/web3-utils/types/tslint.json b/packages/web3-utils/types/tslint.json index dc95ea202b8..903c2aa8db5 100644 --- a/packages/web3-utils/types/tslint.json +++ b/packages/web3-utils/types/tslint.json @@ -4,6 +4,7 @@ "semicolon": false, "no-import-default-of-export-equals": false, "file-name-casing": [true, "kebab-case"], - "whitespace": false + "whitespace": false, + "no-redundant-jsdoc": false } }