Documentation page for ethereum-web3-plus
Package that sits on top of web3 package by frozeman.
This package adds 2 main functionalities:
- The Solidity compilation simplified with automatic linkeage of libraries and contract deployment simplification
- A block watcher and a waitFor function to get notified when a submitted transaction is completed and considered canonical.
Note that in this version the solidity compiler is the one loaded by the geth node.
You need to run a local Ethereum node to use this library.
Installation
Node.js
npm install ethereum-web3-plus --save
Meteor.js
meteor npm install ethereum-web3-plus --save
Usage
Loading the packages. Second require will modify Web3 prototype
var Web3 = require('web3');
require('ethereum-web3-plus');
Initializing Web3 API normally. Also see web3 package documentation
let ethereum_url = "http://localhost:8545";
web3 = new Web3(new Web3.providers.HttpProvider(ethereum_url));
console.log("Connected to Geth console", web3.version.node, "on block", eth.blockNumber);
eth.defaultAccount = eth.coinbase;
web3.personal.unlockAccount(eth.defaultAccount, "capture your password here", 10);
output: Connected to Geth console Geth/v1.5.8-stable-f58fb322/darwin/go1.7.5 on block 62353
Using the solidity compiler functionality:
Note the path resolution is relative to the path where the geth node is running.
- So if the geth node runs in /home/user/guenole/ethereum, "./sources/file.sol" will be resolved as /home/user/guenole/ethereum/sources/file.sol
- You can specify an absolute path but be carefull that libraries will use the full path and cut after 36 chars. So if you have an absolute path of /home/user/guenole/ethereum/sources/library.sol containing a library Library you will have a library token being /home/user/guenole/ethereum/sources/ because the fullpath is truncated at 36 char to fit 40chars with the __ on both side.
- A workaround is to create symbolic link to the sources path either from the geth node path or from the root (/)
var compiler = web3.solidityCompiler();
compiler.addDeployedLib("MapString", "0x48f59e9fbce7880a11acd90dc2f99b28accc47f6");
compiler.addDeployedLib("MapAddress", "0xdb3d0da48c1962f5e31abd9f9904160729da9358");
compiler.addDeployedLib("MapAddressWithProps", "0x87614301dd92d49447b926941940c85533b7e147");
compiler.compile("./sources/example.sol");
compiler.displaySizes();
compiler.displayMissingLibs();
output: Compiled Example code length: 1440
Using the contract deployment functions
var tx = web3.newInstanceTx("Example", any constructor params);
var address = "0x4435dee6dd53ffad11cf4ebb85cea2e51ea62434";
var E = web3.instanceAt("Example", address);
Using the block watcher functionalities
bw= web3.BlockWatcherStart(func*);
It is possible to pass a function in parameter to the BlockWatcherStart function to wrap the callbacks.
This function parameter is optional and if not supplied, a simplest version is used (simpleWrapper).
This is necessary for some environment like Meteor where the callback must run in the proper context (eg Fiber).
So the function must work as follow: accept a callback as unique parameter. When called returns a function that wrap the callback
simpleWrapper = function(f) {
return function() { return f.apply(f, arguments); }
}
web3.BlockWatcherStart(Meteor.bindEnvironment);
Deploying a contract
web3.waitFor( web3.newInstanceTx("Example"), "Param1",
function(tx, p1, contract, err) {
console.log("callback:", tx, p1, contract, err);
if(contract) E = web3.instanceAt("Example", contract);
},
{canonicalAfter:2, dropAfter:5} );
bw.stop();
waitFor takes the following parameters:
- 1 : a valid tx hash returned by any of the web3 calls
- 2..N: any parameters to be passed to the callback
- N+1 : a callback in the form function(txHash, p2, ..., pN, contractAddress, error)
where txHash is the hash of the transaction that was waited to be executed
p2, ..., pN the custom paramters passed to the waitFor
contractAddress is the newly created contract in case the transaction is deploying a contract
or the address of the contract (or account) to which the transaction was made
- N+2 : (optional) an object with the following attributes
- canonicalAfter: <number>, default=0. tells the watcher to call the callback only canonicalAfter blocks after the transaction has been mined. This allow to control possible small soft forks and be sure to get valid transactions.
- dropAfter: <number>, default=99999999. tells the watcher to drop this transaction if not mined after dropAfter blocks. This in case the local node has been killed before sending the tx to other nodes and/or the watcher loosing the events listener.