ethereum-web3-plus

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'); // modify Web3 prototype

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"); // path either absolute or relative to geth running node.

compiler.displaySizes();  // display all contract found and compiled and their code size (important to check they are as small as possible)
compiler.displayMissingLibs(); // display libraries that have not been found in the deployed libs and that are required.

output: Compiled Example code length: 1440

Using the contract deployment functions

// request the publication of the contract. Returns the tx hash of that request
var tx = web3.newInstanceTx("Example", any constructor params);
// convert a contract address into an javascript object
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); }
}

// for instance in Meteor
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}  );


// when you want to stop watching the blocks
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.