From fb74d60d2050b8159825434378067f26adf04acb Mon Sep 17 00:00:00 2001 From: Fabian Vogelsteller Date: Tue, 28 Mar 2017 17:55:34 +0200 Subject: [PATCH] added web3.extend docs --- docs/include_package-core.rst | 81 ++++++++++++++++- docs/web3-eth-accounts.rst | 87 ++++++++++++++++++- packages/web3-core-method/src/index.js | 2 +- .../web3-core-requestManager/package.json | 3 + .../web3-core-requestManager/src/index.js | 7 ++ packages/web3-core/src/extend.js | 1 + packages/web3-core/src/index.js | 2 + packages/web3-eth/src/accounts.js | 4 +- src/index.js | 11 --- test/extend.js | 13 +-- 10 files changed, 188 insertions(+), 23 deletions(-) diff --git a/docs/include_package-core.rst b/docs/include_package-core.rst index 724b68e..0d97c70 100644 --- a/docs/include_package-core.rst +++ b/docs/include_package-core.rst @@ -42,7 +42,6 @@ Example ------------------------------------------------------------------------------ - providers ===================== @@ -152,3 +151,83 @@ Example batch.execute(); +------------------------------------------------------------------------------ + +extend +===================== + +.. code-block:: javascript + + web3.extend(methods) + web3.eth.extend(methods) + web3.shh.extend(methods) + web3.bzz.extend(methods) + ... + +Allows extending the web3 modules. + +.. note:: You also have ``*.extend.formatters`` as additional formatter functions to be used for in and output formatting. Please see the `source file `_ for function details. + +---------- +Parameters +---------- + +1. ``methods`` - ``Object``: Extension object with array of methods description objects as follows: + - ``property`` - ``String``: (optional) The name of the property to add to the module. If no property is set it will be added to the module directly. + - ``methods`` - ``Array``: The array of method descriptions: + - ``name`` - ``String``: Name of the method to add. + - ``call`` - ``String``: The RPC method name. + - ``params`` - ``Number``: (optional) The number of parameters for that function. Default 0. + - ``inputFormatter`` - ``Array``: (optional) Array of inputformatter functions. Each array item responds to a function parameter, so if you want some parameters not to be formatted, add a ``null`` instead. + - ``outputFormatter - ``Function``: (optional) Can be used to format the output of the method. + + +---------- +Returns +---------- + +``Object``: The extended module. + +------- +Example +------- + +.. code-block:: javascript + + web3.extend({ + property: 'myModule', + methods: [{ + name: 'getBalance', + call: 'eth_getBalance', + params: 2, + inputFormatter: [web3.extend.formatters.inputAddressFormatter, web3.extend.formatters.inputDefaultBlockNumberFormatter], + outputFormatter: web3.utils.hexToNumberString + },{ + name: 'getGasPriceSuperFunction', + call: 'eth_gasPriceSuper', + params: 2, + inputFormatter: [null, web3.utils.numberToHex] + }] + }); + + web3.extend({ + methods: [{ + name: 'directCall', + call: 'eth_callForFun', + }] + }); + + console.log(web3); + > Web3 { + myModule: { + getBalance: function(){}, + getGasPriceSuperFunction: function(){} + }, + directCall: function(){}, + eth: Eth {...}, + bzz: Bzz {...}, + ... + } + + +------------------------------------------------------------------------------ diff --git a/docs/web3-eth-accounts.rst b/docs/web3-eth-accounts.rst index ac92397..8cd92f9 100644 --- a/docs/web3-eth-accounts.rst +++ b/docs/web3-eth-accounts.rst @@ -266,6 +266,9 @@ sign Recovers the Ethereum address which was used to sign the given RLP encoded transaction. +Lets use: `https://github.com/ethereum/EIPs/issues/191 `_ + + ---------- Parameters ---------- @@ -342,7 +345,7 @@ encrypt web3.eth.accounts.encrypt(privateKey, password); -Encrypts a private key using ??? +Encrypts a private key using web3 keystore standards? ---------- Parameters @@ -378,7 +381,7 @@ decrypt web3.eth.accounts.decrypt(encryptedPrivateKey, password); -Encrypts a private key using ??? +Encrypts a private key using web3 keystore standards? ---------- Parameters @@ -584,6 +587,84 @@ Example +------------------------------------------------------------------------------ + +wallet.encrypt +===================== + +.. code-block:: javascript + + web3.eth.accounts.wallet.encrypt(privateKey, password); + +Encrypts a private key using web3 keystore standards? + +---------- +Parameters +---------- + +1. ``privateKey`` - ``String``: The private key to encrypt. +2. ``password`` - ``String``: The password used for encryption. + + +------- +Returns +------- + +``String``: The encrypted privatekey. + +------- +Example +------- + +.. code-block:: javascript + + web3.eth.accounts.encrypt('0x4c0883a69102937d6231471b5dbb6204fe5129617082792ae468d01a3f362318', 'test!$@'); + > [{"address":"4bf2a80d5c7b337da05b446081f95d0a34f79e7f","Crypto":{"cipher":"aes-128-ctr","ciphertext":"acfe42eed2d102e9bd2383c5c3f9bfdcb346a152dd7b9a3d18bab270f323f683","cipherparams":{"iv":"22cb99fa11a257f3c5b7d19ddb8bb5a4"},"kdf":"scrypt","kdfparams":{"dklen":32,"n":261144,"p":1,"r":5,"salt":"81e332698874fc168bfde32f1529648df2fb5d9b2494e7c418ff563f18cbce86"},"mac":"0e82211205dcfb8deaff19e8433f9e966f2d72c488ac54b0b4f6ab1cf594a542"},"id":"e1268f6b-1220-4f7a-a6de-f2ad695831dc","version":3}] + + + +------------------------------------------------------------------------------ + +wallet.decrypt +===================== + +.. code-block:: javascript + + web3.eth.accounts.wallet.decrypt(encryptedPrivateKey, password); + +Encrypts a private key using web3 keystore standards? + +---------- +Parameters +---------- + +1. ``encryptedPrivateKey`` - ``String``: The encrypted private key to decrypt. +2. ``password`` - ``String``: The password used for encryption. + + +------- +Returns +------- + +``String``: The decrypted privatekey. + +------- +Example +------- + +.. code-block:: javascript + + web3.eth.accounts.decrypt([{"address":"4bf2a80d5c7b337da05b446081f95d0a34f79e7f","Crypto":{"cipher":"aes-128-ctr","ciphertext":"acfe42eed2d102e9bd2383c5c3f9bfdcb346a152dd7b9a3d18bab270f323f683","cipherparams":{"iv":"22cb99fa11a257f3c5b7d19ddb8bb5a4"},"kdf":"scrypt","kdfparams":{"dklen":32,"n":261144,"p":1,"r":5,"salt":"81e332698874fc168bfde32f1529648df2fb5d9b2494e7c418ff563f18cbce86"},"mac":"0e82211205dcfb8deaff19e8433f9e966f2d72c488ac54b0b4f6ab1cf594a542"},"id":"e1268f6b-1220-4f7a-a6de-f2ad695831dc","version":3}, {...}], 'test!$@'); + > Wallet { + 0: {...}, + 1: {...}, + "0xF0109fC8DF283027b6285cc889F5aA624EaC1F55": {...}, + "0xD0122fC8DF283027b6285cc889F5aA624EaC1d23": {...} + ... + } + + + ------------------------------------------------------------------------------ wallet.save @@ -616,7 +697,7 @@ Example .. code-block:: javascript web3.eth.accounts.wallet.save('test#!$', 'myWalletKey'); - > '634534562534412426573645312443567753214567432145674321456784321345678543213456' ?? + > [{"address":"4bf2a80d5c7b337da05b446081f95d0a34f79e7f","Crypto":{"cipher":"aes-128-ctr","ciphertext":"acfe42eed2d102e9bd2383c5c3f9bfdcb346a152dd7b9a3d18bab270f323f683","cipherparams":{"iv":"22cb99fa11a257f3c5b7d19ddb8bb5a4"},"kdf":"scrypt","kdfparams":{"dklen":32,"n":261144,"p":1,"r":5,"salt":"81e332698874fc168bfde32f1529648df2fb5d9b2494e7c418ff563f18cbce86"},"mac":"0e82211205dcfb8deaff19e8433f9e966f2d72c488ac54b0b4f6ab1cf594a542"},"id":"e1268f6b-1220-4f7a-a6de-f2ad695831dc","version":3}, {...}] diff --git a/packages/web3-core-method/src/index.js b/packages/web3-core-method/src/index.js index 014ce76..1c750c6 100644 --- a/packages/web3-core-method/src/index.js +++ b/packages/web3-core-method/src/index.js @@ -16,8 +16,8 @@ */ /** * @file index.js - * @author Marek Kotewicz * @author Fabian Vogelsteller + * @author Marek Kotewicz * @date 2017 */ diff --git a/packages/web3-core-requestManager/package.json b/packages/web3-core-requestManager/package.json index 9819ade..15d24f4 100644 --- a/packages/web3-core-requestManager/package.json +++ b/packages/web3-core-requestManager/package.json @@ -7,6 +7,9 @@ "main": "src/index.js", "dependencies": { "web3-core-helpers": "^1.0.0", + "web3-providers-ipc": "^1.0.0", + "web3-providers-http": "^1.0.0", + "web3-providers-ws": "^1.0.0", "underscore": "^1.8.3", "oboe": "^2.1.3" } diff --git a/packages/web3-core-requestManager/src/index.js b/packages/web3-core-requestManager/src/index.js index 84a7d64..a4e56de 100644 --- a/packages/web3-core-requestManager/src/index.js +++ b/packages/web3-core-requestManager/src/index.js @@ -39,6 +39,7 @@ var givenProvider = require('./givenProvider.js'); */ var RequestManager = function RequestManager(provider) { this.provider = null; + this.providers = RequestManager.providers; this.setProvider(provider); this.subscriptions = {}; @@ -48,6 +49,12 @@ var RequestManager = function RequestManager(provider) { RequestManager.givenProvider = givenProvider; +RequestManager.providers = { + WebsocketProvider: require('web3-providers-ws'), + HttpProvider: require('web3-providers-http'), + IpcProvider: require('web3-providers-ipc') +}; + /** * Should be used to asynchronously send request diff --git a/packages/web3-core/src/extend.js b/packages/web3-core/src/extend.js index 84208bf..c8b7878 100644 --- a/packages/web3-core/src/extend.js +++ b/packages/web3-core/src/extend.js @@ -53,6 +53,7 @@ var extend = function (pckg) { }); } + return pckg; }; ex.formatters = formatters; diff --git a/packages/web3-core/src/index.js b/packages/web3-core/src/index.js index e23e9fd..01a5b85 100644 --- a/packages/web3-core/src/index.js +++ b/packages/web3-core/src/index.js @@ -73,6 +73,7 @@ module.exports = { // add givenProvider pkg.givenProvider = requestManager.Manager.givenProvider; + pkg.providers = requestManager.Manager.providers; // add set Provider function pkg.setProvider = function (provider) { @@ -89,6 +90,7 @@ module.exports = { }, addProviders: function (pkg) { pkg.givenProvider = requestManager.Manager.givenProvider; + pkg.providers = requestManager.Manager.providers; } }; diff --git a/packages/web3-eth/src/accounts.js b/packages/web3-eth/src/accounts.js index 37b9aef..805933a 100644 --- a/packages/web3-eth/src/accounts.js +++ b/packages/web3-eth/src/accounts.js @@ -70,10 +70,12 @@ module.exports = { // return synchronous if(tx.gas && _.isFinite(tx.gasPrice) && _.isFinite(tx.chainId) && _.isFinite(tx.nonce)) { + var signature = signer.sign(tx, privKey); + if (_.isFunction(callback)) { callback(null, signature); } - return signer.sign(tx, privKey); + return signature; } // make it async and retrive missing values diff --git a/src/index.js b/src/index.js index 71435a9..691ec6a 100644 --- a/src/index.js +++ b/src/index.js @@ -39,12 +39,6 @@ var Bzz = require('../packages/web3-bzz'); var utils = require('../packages/web3-utils'); -// providers -var providers = { - WebsocketProvider: require('../packages/web3-providers-ws'), - HttpProvider: require('../packages/web3-providers-http'), - IpcProvider: require('../packages/web3-providers-ipc') -}; var Web3 = function Web3() { @@ -54,8 +48,6 @@ var Web3 = function Web3() { this.version = version.version; - // this.providers = providers; - this.eth = new Eth(this); this.shh = new Shh(this); @@ -81,9 +73,6 @@ var Web3 = function Web3() { Web3.prototype.version = version.version; -Web3.providers = providers; -Web3.prototype.providers = providers; - core.addProviders(Web3); diff --git a/test/extend.js b/test/extend.js index 97b5f5d..c460a67 100644 --- a/test/extend.js +++ b/test/extend.js @@ -7,33 +7,33 @@ var web3 = new Web3(); var tests = [{ methods: [{ - name: 'getGasPrice', + name: 'getGasPrice2', call: 'eth_gasPrice', outputFormatter: web3.extend.formatters.outputBigNumberFormatter },{ name: 'getBalance', call: 'eth_getBalance', params: 2, - inputFormatter: [web3.extend.utils.toChecksumAddress, web3.extend.formatters.inputDefaultBlockNumberFormatter], + inputFormatter: [web3.utils.toChecksumAddress, web3.extend.formatters.inputDefaultBlockNumberFormatter], outputFormatter: web3.extend.formatters.outputBigNumberFormatter }] },{ property: 'admin', methods: [{ - name: 'getGasPrice', + name: 'getGasPrice3', call: 'eth_gasPrice', outputFormatter: web3.extend.formatters.outputBigNumberFormatter },{ name: 'getBalance', call: 'eth_getBalance', params: 2, - inputFormatter: [web3.extend.utils.toChecksumAddress, web3.extend.formatters.inputDefaultBlockNumberFormatter], + inputFormatter: [web3.utils.toChecksumAddress, web3.extend.formatters.inputDefaultBlockNumberFormatter], outputFormatter: web3.extend.formatters.outputBigNumberFormatter }] },{ error: true, methods: [{ - name: 'getGasPrice', + name: 'getGasPrice4', outputFormatter: web3.extend.formatters.outputBigNumberFormatter }] },{ @@ -62,7 +62,7 @@ describe('web3', function () { web3.extend(test); } - if(test.methods) + if(test.methods) { test.methods.forEach(function(property){ @@ -85,6 +85,7 @@ describe('web3', function () { web3[property.name](); } }); + } }); }); });