eth_getProof added to web3-eth package

docs/web3-eth.rst

@@ -1765,3 +1765,79 @@ Example
     > "Mist/v0.9.3/darwin/go1.4.1"
 
 ------------------------------------------------------------------------------
+
+.. _eth-getProof:
+
+getProof
+========
+
+.. code-block:: javascript
+
+    web3.eth.getProof(address, storageKey, blockNumber, [callback])
+
+Returns the account and storage-values of the specified account including the Merkle-proof as described in `EIP-1186 <https://github.com/ethereum/EIPs/blob/master/EIPS/eip-1186.md>`_.
+
+----------
+Parameters
+----------
+
+1. ``String`` 20 Bytes:  The Address of the account or contract.
+2. ``Number[] | BigNumber[] | BN[] | String[]`` 32 Bytes: Array of storage-keys which should be proofed and included. See :ref:`web3.eth.getStorageAt <eth-getStorageAt>`.
+3. ``Number | String | BN | BigNumber``: Integer block number. Pre-defined block numbers as ``"latest"``, ``"earlist"``, ``"pending"``, and ``"genesis"`` can also be used.
+4. ``Function`` - (optional) Optional callback, returns an error object as first parameter and the result as second.
+
+-------
+Returns
+-------
+
+``Promise<Object>`` - A account object.
+
+    - ``address`` - ``String``: The address of the account.
+    - ``balance`` - ``String``: The balance of the account. See :ref:`web3.eth.getBalance <eth-getBalance>`.
+    - ``codeHash`` - ``String``: hash of the code of the account. For a simple Account without code it will return "0xc5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470"
+    - ``nonce`` -  ``String``: Nonce of the account.
+    - ``storageHash`` - ``String``: SHA3 of the StorageRoot. All storage will deliver a MerkleProof starting with this rootHash.
+    - ``accountProof`` - ``String[]``:Array of rlp-serialized MerkleTree-Nodes, starting with the stateRoot-Node, following the path of the SHA3 (address) as key.
+    - ``storageProof`` - ``Object[]`` Array of storage-entries as requested.
+        - ``key`` - ``String``  The requested storage key.
+        - ``value`` - ``String``  The storage value.
+
+-------
+Example
+-------
+
+
+.. code-block:: javascript
+
+    web3.eth.getProof(
+        "0x1234567890123456789012345678901234567890",
+        ["0x0000000000000000000000000000000000000000000000000000000000000000","0x0000000000000000000000000000000000000000000000000000000000000001"],
+        "latest"
+    ).then(console.log);
+    > {
+        "address": "0x1234567890123456789012345678901234567890",
+        "accountProof": [
+            "0xf90211a090dcaf88c40c7bbc95a912cbdde67c175767b31173df9ee4b0d733bfdd511c43a0babe369f6b12092f49181ae04ca173fb68d1a5456f18d20fa32cba73954052bda0473ecf8a7e36a829e75039a3b055e51b8332cbf03324ab4af2066bbd6fbf0021a0bbda34753d7aa6c38e603f360244e8f59611921d9e1f128372fec0d586d4f9e0a04e44caecff45c9891f74f6a2156735886eedf6f1a733628ebc802ec79d844648a0a5f3f2f7542148c973977c8a1e154c4300fec92f755f7846f1b734d3ab1d90e7a0e823850f50bf72baae9d1733a36a444ab65d0a6faaba404f0583ce0ca4dad92da0f7a00cbe7d4b30b11faea3ae61b7f1f2b315b61d9f6bd68bfe587ad0eeceb721a07117ef9fc932f1a88e908eaead8565c19b5645dc9e5b1b6e841c5edbdfd71681a069eb2de283f32c11f859d7bcf93da23990d3e662935ed4d6b39ce3673ec84472a0203d26456312bbc4da5cd293b75b840fc5045e493d6f904d180823ec22bfed8ea09287b5c21f2254af4e64fca76acc5cd87399c7f1ede818db4326c98ce2dc2208a06fc2d754e304c48ce6a517753c62b1a9c1d5925b89707486d7fc08919e0a94eca07b1c54f15e299bd58bdfef9741538c7828b5d7d11a489f9c20d052b3471df475a051f9dd3739a927c89e357580a4c97b40234aa01ed3d5e0390dc982a7975880a0a089d613f26159af43616fd9455bb461f4869bfede26f2130835ed067a8b967bfb80",
+            "0xf90211a0395d87a95873cd98c21cf1df9421af03f7247880a2554e20738eec2c7507a494a0bcf6546339a1e7e14eb8fb572a968d217d2a0d1f3bc4257b22ef5333e9e4433ca012ae12498af8b2752c99efce07f3feef8ec910493be749acd63822c3558e6671a0dbf51303afdc36fc0c2d68a9bb05dab4f4917e7531e4a37ab0a153472d1b86e2a0ae90b50f067d9a2244e3d975233c0a0558c39ee152969f6678790abf773a9621a01d65cd682cc1be7c5e38d8da5c942e0a73eeaef10f387340a40a106699d494c3a06163b53d956c55544390c13634ea9aa75309f4fd866f312586942daf0f60fb37a058a52c1e858b1382a8893eb9c1f111f266eb9e21e6137aff0dddea243a567000a037b4b100761e02de63ea5f1fcfcf43e81a372dafb4419d126342136d329b7a7ba032472415864b08f808ba4374092003c8d7c40a9f7f9fe9cc8291f62538e1cc14a074e238ff5ec96b810364515551344100138916594d6af966170ff326a092fab0a0d31ac4eef14a79845200a496662e92186ca8b55e29ed0f9f59dbc6b521b116fea090607784fe738458b63c1942bba7c0321ae77e18df4961b2bc66727ea996464ea078f757653c1b63f72aff3dcc3f2a2e4c8cb4a9d36d1117c742833c84e20de994a0f78407de07f4b4cb4f899dfb95eedeb4049aeb5fc1635d65cf2f2f4dfd25d1d7a0862037513ba9d45354dd3e36264aceb2b862ac79d2050f14c95657e43a51b85c80",
+            "0xf90171a04ad705ea7bf04339fa36b124fa221379bd5a38ffe9a6112cb2d94be3a437b879a08e45b5f72e8149c01efcb71429841d6a8879d4bbe27335604a5bff8dfdf85dcea00313d9b2f7c03733d6549ea3b810e5262ed844ea12f70993d87d3e0f04e3979ea0b59e3cdd6750fa8b15164612a5cb6567cdfb386d4e0137fccee5f35ab55d0efda0fe6db56e42f2057a071c980a778d9a0b61038f269dd74a0e90155b3f40f14364a08538587f2378a0849f9608942cf481da4120c360f8391bbcc225d811823c6432a026eac94e755534e16f9552e73025d6d9c30d1d7682a4cb5bd7741ddabfd48c50a041557da9a74ca68da793e743e81e2029b2835e1cc16e9e25bd0c1e89d4ccad6980a041dda0a40a21ade3a20fcd1a4abb2a42b74e9a32b02424ff8db4ea708a5e0fb9a09aaf8326a51f613607a8685f57458329b41e938bb761131a5747e066b81a0a16808080a022e6cef138e16d2272ef58434ddf49260dc1de1f8ad6dfca3da5d2a92aaaadc58080",
+            "0xf851808080a009833150c367df138f1538689984b8a84fc55692d3d41fe4d1e5720ff5483a6980808080808080808080a0a319c1c415b271afc0adcb664e67738d103ac168e0bc0b7bd2da7966165cb9518080"
+            ],
+            "balance": 0,
+            "codeHash": "0xc5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470",
+            "nonce": 0,
+            "storageHash": "0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421",
+            "storageProof": [
+            {
+                "key": "0x0000000000000000000000000000000000000000000000000000000000000000",
+                "value": '0',
+                "proof": []
+            },
+            {
+                "key": "0x0000000000000000000000000000000000000000000000000000000000000001",
+                "value": '0',
+                "proof": []
+            }
+        ]
+    }
+
+------------------------------------------------------------------------------

packages/web3-core-helpers/src/formatters.js

@@ -23,11 +23,41 @@
 
 "use strict";
 
-
 var _ = require('underscore');
 var utils = require('web3-utils');
 var Iban = require('web3-eth-iban');
 
+
+/**
+ * Will format the given storage key array values to hex strings.
+ *
+ * @method inputStorageKeysFormatter
+ *
+ * @param {Array<Number|String|BN|BigNumber>} keys
+ *
+ * @returns {Array<String>}
+ */
+var inputStorageKeysFormatter = function (keys) {
+    return keys.map(utils.numberToHex);
+};
+
+/**
+ * Will format the given proof response from the node.
+ *
+ * @method outputProofFormatter
+ *
+ * @param {object} proof
+ *
+ * @returns {object}
+ */
+var outputProofFormatter = function (proof) {
+    proof.address = utils.toChecksumAddress(proof.address);
+    proof.nonce = utils.hexToNumberString(proof.nonce);
+    proof.balance = utils.hexToNumberString(proof.balance);
+
+    return proof;
+};
+
 /**
  * Should the format output to a big number
  *
@@ -96,7 +126,7 @@ var inputBlockNumberFormatter = function (blockNumber) {
  * @param {Object} transaction options
  * @returns object
  */
-var _txInputFormatter = function (options){
+var _txInputFormatter = function (options) {
 
     if (options.to) { // it might be contract creation
         options.to = inputAddressFormatter(options.to);
@@ -111,7 +141,7 @@ var _txInputFormatter = function (options){
         delete options.input;
     }
 
-    if(options.data && !utils.isHex(options.data)) {
+    if (options.data && !utils.isHex(options.data)) {
         throw new Error('The data field must be HEX encoded data.');
     }
 
@@ -122,7 +152,7 @@ var _txInputFormatter = function (options){
 
     ['gasPrice', 'gas', 'value', 'nonce'].filter(function (key) {
         return options[key] !== undefined;
-    }).forEach(function(key){
+    }).forEach(function (key) {
         options[key] = utils.numberToHex(options[key]);
     });
 
@@ -135,8 +165,8 @@ var _txInputFormatter = function (options){
  * @method inputCallFormatter
  * @param {Object} transaction options
  * @returns object
-*/
-var inputCallFormatter = function (options){
+ */
+var inputCallFormatter = function (options) {
 
     options = _txInputFormatter(options);
 
@@ -156,7 +186,7 @@ var inputCallFormatter = function (options){
  * @method inputTransactionFormatter
  * @param {Object} options
  * @returns object
-*/
+ */
 var inputTransactionFormatter = function (options) {
 
     options = _txInputFormatter(options);
@@ -192,24 +222,24 @@ var inputSignFormatter = function (data) {
  * @method outputTransactionFormatter
  * @param {Object} tx
  * @returns {Object}
-*/
-var outputTransactionFormatter = function (tx){
-    if(tx.blockNumber !== null)
+ */
+var outputTransactionFormatter = function (tx) {
+    if (tx.blockNumber !== null)
         tx.blockNumber = utils.hexToNumber(tx.blockNumber);
-    if(tx.transactionIndex !== null)
+    if (tx.transactionIndex !== null)
         tx.transactionIndex = utils.hexToNumber(tx.transactionIndex);
     tx.nonce = utils.hexToNumber(tx.nonce);
     tx.gas = utils.hexToNumber(tx.gas);
     tx.gasPrice = outputBigNumberFormatter(tx.gasPrice);
     tx.value = outputBigNumberFormatter(tx.value);
 
-    if(tx.to && utils.isAddress(tx.to)) { // tx.to could be `0x0` or `null` while contract creation
+    if (tx.to && utils.isAddress(tx.to)) { // tx.to could be `0x0` or `null` while contract creation
         tx.to = utils.toChecksumAddress(tx.to);
     } else {
         tx.to = null; // set to `null` if invalid address
     }
 
-    if(tx.from) {
+    if (tx.from) {
         tx.from = utils.toChecksumAddress(tx.from);
     }
 
@@ -222,28 +252,28 @@ var outputTransactionFormatter = function (tx){
  * @method outputTransactionReceiptFormatter
  * @param {Object} receipt
  * @returns {Object}
-*/
-var outputTransactionReceiptFormatter = function (receipt){
-    if(typeof receipt !== 'object') {
-        throw new Error('Received receipt is invalid: '+ receipt);
+ */
+var outputTransactionReceiptFormatter = function (receipt) {
+    if (typeof receipt !== 'object') {
+        throw new Error('Received receipt is invalid: ' + receipt);
     }
 
-    if(receipt.blockNumber !== null)
+    if (receipt.blockNumber !== null)
         receipt.blockNumber = utils.hexToNumber(receipt.blockNumber);
-    if(receipt.transactionIndex !== null)
+    if (receipt.transactionIndex !== null)
         receipt.transactionIndex = utils.hexToNumber(receipt.transactionIndex);
     receipt.cumulativeGasUsed = utils.hexToNumber(receipt.cumulativeGasUsed);
     receipt.gasUsed = utils.hexToNumber(receipt.gasUsed);
 
-    if(_.isArray(receipt.logs)) {
+    if (_.isArray(receipt.logs)) {
         receipt.logs = receipt.logs.map(outputLogFormatter);
     }
 
-    if(receipt.contractAddress) {
+    if (receipt.contractAddress) {
         receipt.contractAddress = utils.toChecksumAddress(receipt.contractAddress);
     }
 
-    if(typeof receipt.status !== 'undefined' && receipt.status !== null) {
+    if (typeof receipt.status !== 'undefined' && receipt.status !== null) {
         receipt.status = Boolean(parseInt(receipt.status));
     }
 
@@ -256,8 +286,8 @@ var outputTransactionReceiptFormatter = function (receipt){
  * @method outputBlockFormatter
  * @param {Object} block
  * @returns {Object}
-*/
-var outputBlockFormatter = function(block) {
+ */
+var outputBlockFormatter = function (block) {
 
     // transform to number
     block.gasLimit = utils.hexToNumber(block.gasLimit);
@@ -267,14 +297,14 @@ var outputBlockFormatter = function(block) {
     if (block.number !== null)
         block.number = utils.hexToNumber(block.number);
 
-    if(block.difficulty)
+    if (block.difficulty)
         block.difficulty = outputBigNumberFormatter(block.difficulty);
-    if(block.totalDifficulty)
+    if (block.totalDifficulty)
         block.totalDifficulty = outputBigNumberFormatter(block.totalDifficulty);
 
     if (_.isArray(block.transactions)) {
-        block.transactions.forEach(function(item){
-            if(!_.isString(item))
+        block.transactions.forEach(function (item) {
+            if (!_.isString(item))
                 return outputTransactionFormatter(item);
         });
     }
@@ -291,16 +321,16 @@ var outputBlockFormatter = function(block) {
  * @method inputLogFormatter
  * @param {Object} log object
  * @returns {Object} log
-*/
-var inputLogFormatter = function(options) {
-    var toTopic = function(value){
+ */
+var inputLogFormatter = function (options) {
+    var toTopic = function (value) {
 
-        if(value === null || typeof value === 'undefined')
+        if (value === null || typeof value === 'undefined')
             return null;
 
         value = String(value);
 
-        if(value.indexOf('0x') === 0)
+        if (value.indexOf('0x') === 0)
             return value;
         else
             return utils.fromUtf8(value);
@@ -315,7 +345,7 @@ var inputLogFormatter = function(options) {
 
     // make sure topics, get converted to hex
     options.topics = options.topics || [];
-    options.topics = options.topics.map(function(topic){
+    options.topics = options.topics.map(function (topic) {
         return (_.isArray(topic)) ? topic.map(toTopic) : toTopic(topic);
     });
 
@@ -336,16 +366,16 @@ var inputLogFormatter = function(options) {
  * @method outputLogFormatter
  * @param {Object} log object
  * @returns {Object} log
-*/
-var outputLogFormatter = function(log) {
+ */
+var outputLogFormatter = function (log) {
 
     // generate a custom log id
-    if(typeof log.blockHash === 'string' &&
-       typeof log.transactionHash === 'string' &&
-       typeof log.logIndex === 'string') {
-        var shaId = utils.sha3(log.blockHash.replace('0x','') + log.transactionHash.replace('0x','') + log.logIndex.replace('0x',''));
-        log.id = 'log_'+ shaId.replace('0x','').substr(0,8);
-    } else if(!log.id) {
+    if (typeof log.blockHash === 'string' &&
+        typeof log.transactionHash === 'string' &&
+        typeof log.logIndex === 'string') {
+        var shaId = utils.sha3(log.blockHash.replace('0x', '') + log.transactionHash.replace('0x', '') + log.logIndex.replace('0x', ''));
+        log.id = 'log_' + shaId.replace('0x', '').substr(0, 8);
+    } else if (!log.id) {
         log.id = null;
     }
 
@@ -369,8 +399,8 @@ var outputLogFormatter = function(log) {
  * @method inputPostFormatter
  * @param {Object} transaction object
  * @returns {Object}
-*/
-var inputPostFormatter = function(post) {
+ */
+var inputPostFormatter = function (post) {
 
     // post.payload = utils.toHex(post.payload);
 
@@ -387,7 +417,7 @@ var inputPostFormatter = function(post) {
     }
 
     // format the following options
-    post.topics = post.topics.map(function(topic){
+    post.topics = post.topics.map(function (topic) {
         // convert only if not hex
         return (topic.indexOf('0x') === 0) ? topic : utils.fromUtf8(topic);
     });
@@ -402,7 +432,7 @@ var inputPostFormatter = function(post) {
  * @param {Object}
  * @returns {Object}
  */
-var outputPostFormatter = function(post){
+var outputPostFormatter = function (post) {
 
     post.expiry = utils.hexToNumber(post.expiry);
     post.sent = utils.hexToNumber(post.sent);
@@ -419,7 +449,7 @@ var outputPostFormatter = function(post){
     if (!post.topics) {
         post.topics = [];
     }
-    post.topics = post.topics.map(function(topic){
+    post.topics = post.topics.map(function (topic) {
         return utils.toUtf8(topic);
     });
 
@@ -431,13 +461,13 @@ var inputAddressFormatter = function (address) {
     if (iban.isValid() && iban.isDirect()) {
         return iban.toAddress().toLowerCase();
     } else if (utils.isAddress(address)) {
-        return '0x' + address.toLowerCase().replace('0x','');
+        return '0x' + address.toLowerCase().replace('0x', '');
     }
-    throw new Error('Provided address "'+ address +'" is invalid, the capitalization checksum test failed, or its an indrect IBAN address which can\'t be converted.');
+    throw new Error('Provided address "' + address + '" is invalid, the capitalization checksum test failed, or its an indrect IBAN address which can\'t be converted.');
 };
 
 
-var outputSyncingFormatter = function(result) {
+var outputSyncingFormatter = function (result) {
 
     result.startingBlock = utils.hexToNumber(result.startingBlock);
     result.currentBlock = utils.hexToNumber(result.currentBlock);
@@ -459,6 +489,8 @@ module.exports = {
     inputPostFormatter: inputPostFormatter,
     inputLogFormatter: inputLogFormatter,
     inputSignFormatter: inputSignFormatter,
+    inputStorageKeysFormatter: inputStorageKeysFormatter,
+    outputProofFormatter: outputProofFormatter,
     outputBigNumberFormatter: outputBigNumberFormatter,
     outputTransactionFormatter: outputTransactionFormatter,
     outputTransactionReceiptFormatter: outputTransactionReceiptFormatter,