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.

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

var compiler = web3.solidityCompiler();
compiler.addDeployedLib("MapString", "0x48f59e9fbce7880a11acd90dc2f99b28accc47f6");
compiler.addDeployedLib("MapAddress", "0xdb3d0da48c1962f5e31abd9f9904160729da9358");
compiler.addDeployedLib("MapAddressWithProps", "0x87614301dd92d49447b926941940c85533b7e147");
compiler.compile("./sources/solidity.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();

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:1, 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: , 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: , 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.