Merge commit '1a6dbeff6e86d65cae6d7db366cbaa4182eaff7f' into ethereumjs

Conflicts:
	libjsqrc/ethereumjs/dist/ethereum.js
	libjsqrc/ethereumjs/dist/ethereum.js.map
	libjsqrc/ethereumjs/dist/ethereum.min.js
	libjsqrc/ethereumjs/lib/abi.js

README.md

@@ -66,16 +66,16 @@ sudo apt-get install npm
 sudo apt-get install nodejs-legacy
 ```
 
-## Building
+### Building (gulp)
 
-```bash (gulp)
+```bash
 npm run-script build
 ```
 
 
-### Testing
+### Testing (mocha)
 
-```bash (mocha)
+```bash
 npm test
 ```
 

example/contract.html

@@ -43,7 +43,7 @@
 
         // create contract
         web3.eth.transact({code: web3.eth.solidity(source)}).then(function (address) {
-            contract = web3.contract(address, desc);
+            contract = web3.eth.contract(address, desc);
             document.getElementById('call').style.visibility = 'visible';
         });
     }

index.js

@@ -3,6 +3,6 @@ web3.providers.WebSocketProvider = require('./lib/websocket');
 web3.providers.HttpRpcProvider = require('./lib/httprpc');
 web3.providers.QtProvider = require('./lib/qt');
 web3.providers.AutoProvider = require('./lib/autoprovider');
-web3.contract = require('./lib/contract');
+web3.eth.contract = require('./lib/contract');
 
 module.exports = web3;

lib/autoprovider.js

@@ -33,6 +33,16 @@ if (process.env.NODE_ENV !== 'build') {
     var web3 = require('./web3'); // jshint ignore:line
 }
 
+/**
+ * AutoProvider object prototype is implementing 'provider protocol'
+ * Automatically tries to setup correct provider(Qt, WebSockets or HttpRpc)
+ * First it checkes if we are ethereum browser (if navigator.qt object is available)
+ * if yes, we are using QtProvider
+ * if no, we check if it is possible to establish websockets connection with ethereum (ws://localhost:40404/eth is default)
+ * if it's not possible, we are using httprpc provider (http://localhost:8080)
+ * The constructor allows you to specify uris on which we are trying to connect over http or websockets
+ * You can do that by passing objects with fields httrpc and websockets
+ */
 var AutoProvider = function (userOptions) {
     if (web3.haveProvider()) {
         return;
@@ -81,6 +91,8 @@ var AutoProvider = function (userOptions) {
     };
 };
 
+/// Sends message forward to the provider, that is being used
+/// if provider is not yet set, enqueues the message
 AutoProvider.prototype.send = function (payload) {
     if (this.provider) {
         this.provider.send(payload);
@@ -89,6 +101,7 @@ AutoProvider.prototype.send = function (payload) {
     this.sendQueue.push(payload);
 };
 
+/// On incoming message sends the message to the provider that is currently being used
 Object.defineProperty(AutoProvider.prototype, 'onmessage', {
     set: function (handler) {
         if (this.provider) {

lib/contract.js

@@ -27,9 +27,29 @@ if (process.env.NODE_ENV !== 'build') {
 
 var abi = require('./abi');
 
-// method signature length in bytes
+/// method signature length in bytes
 var ETH_METHOD_SIGNATURE_LENGTH = 4;
 
+/**
+ * This method should be called when we want to call / transact some solidity method from javascript
+ * it returns an object which has same methods available as solidity contract description
+ * usage example: 
+ *
+ * var abi = [{
+ *      name: 'myMethod',
+ *      inputs: [{ name: 'a', type: 'string' }],
+ *      outputs: [{name: 'd', type: 'string' }]
+ * }];  // contract abi
+ *
+ * var myContract = web3.eth.contract('0x0123123121', abi); // creation of contract object
+ *
+ * myContract.myMethod('this is test string param for call').call(); // myMethod call
+ * myContract.myMethod('this is test string param for transact').transact() // myMethod transact
+ *
+ * @param address - address of the contract, which should be called
+ * @param desc - abi json description of the contract, which is being created
+ * @returns contract object
+ */
 var contract = function (address, desc) {
     var inputParser = abi.inputParser(desc);
     var outputParser = abi.outputParser(desc);
@@ -70,3 +90,4 @@ var contract = function (address, desc) {
 };
 
 module.exports = contract;
+

lib/filter.js

+/*
+    This file is part of ethereum.js.
+
+    ethereum.js is free software: you can redistribute it and/or modify
+    it under the terms of the GNU Lesser General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    ethereum.js is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU Lesser General Public License for more details.
+
+    You should have received a copy of the GNU Lesser General Public License
+    along with ethereum.js.  If not, see <http://www.gnu.org/licenses/>.
+*/
+/** @file filter.js
+ * @authors:
+ *   Jeffrey Wilcke <jeff@ethdev.com>
+ *   Marek Kotewicz <marek@ethdev.com>
+ *   Marian Oancea <marian@ethdev.com>
+ *   Gav Wood <g@ethdev.com>
+ * @date 2014
+ */
+
+// TODO: is these line is supposed to be here? 
+if (process.env.NODE_ENV !== 'build') {
+    var web3 = require('./web3'); // jshint ignore:line
+}
+
+/// should be used when we want to watch something
+/// it's using inner polling mechanism and is notified about changes
+var Filter = function(options, impl) {
+    this.impl = impl;
+    this.callbacks = [];
+
+    var self = this;
+    this.promise = impl.newFilter(options);
+    this.promise.then(function (id) {
+        self.id = id;
+        web3.on(impl.changed, id, self.trigger.bind(self));
+        web3.provider.startPolling({call: impl.changed, args: [id]}, id);
+    });
+};
+
+/// alias for changed*
+Filter.prototype.arrived = function(callback) {
+    this.changed(callback);
+};
+
+/// gets called when there is new eth/shh message
+Filter.prototype.changed = function(callback) {
+    var self = this;
+    this.promise.then(function(id) {
+        self.callbacks.push(callback);
+    });
+};
+
+/// trigger calling new message from people
+Filter.prototype.trigger = function(messages) {
+    for(var i = 0; i < this.callbacks.length; i++) {
+        this.callbacks[i].call(this, messages);
+    }
+};
+
+/// should be called to uninstall current filter
+Filter.prototype.uninstall = function() {
+    var self = this;
+    this.promise.then(function (id) {
+        self.impl.uninstallFilter(id);
+        web3.provider.stopPolling(id);
+        web3.off(impl.changed, id);
+    });
+};
+
+/// should be called to manually trigger getting latest messages from the client
+Filter.prototype.messages = function() {
+    var self = this;
+    return this.promise.then(function (id) {
+        return self.impl.getMessages(id);
+    });
+};
+
+/// alias for messages
+Filter.prototype.logs = function () {
+    return this.messages();
+};
+
+module.exports = Filter;

lib/httprpc.js

@@ -26,11 +26,21 @@ if (process.env.NODE_ENV !== 'build') {
     var XMLHttpRequest = require('xmlhttprequest').XMLHttpRequest; // jshint ignore:line
 }
 
+/**
+ * HttpRpcProvider object prototype is implementing 'provider protocol'
+ * Should be used when we want to connect to ethereum backend over http && jsonrpc
+ * It's compatible with cpp client
+ * The contructor allows to specify host uri
+ * This provider is using in-browser polling mechanism
+ */
 var HttpRpcProvider = function (host) {
     this.handlers = [];
     this.host = host;
 };
 
+/// Transforms inner message to proper jsonrpc object
+/// @param inner message object
+/// @returns jsonrpc object
 function formatJsonRpcObject(object) {
     return {
         jsonrpc: '2.0',
@@ -40,6 +50,9 @@ function formatJsonRpcObject(object) {
     };
 }
 
+/// Transforms jsonrpc object to inner message
+/// @param incoming jsonrpc message 
+/// @returns inner message object
 function formatJsonRpcMessage(message) {
     var object = JSON.parse(message);
 
@@ -50,6 +63,10 @@ function formatJsonRpcMessage(message) {
     };
 }
 
+/// Prototype object method 
+/// Asynchronously sends request to server
+/// @param payload is inner message object
+/// @param cb is callback which is being called when response is comes back
 HttpRpcProvider.prototype.sendRequest = function (payload, cb) {
     var data = formatJsonRpcObject(payload);
 
@@ -63,6 +80,11 @@ HttpRpcProvider.prototype.sendRequest = function (payload, cb) {
     };
 };
 
+/// Prototype object method
+/// Should be called when we want to send single api request to server
+/// Asynchronous
+/// On response it passes message to handlers
+/// @param payload is inner message object
 HttpRpcProvider.prototype.send = function (payload) {
     var self = this;
     this.sendRequest(payload, function (request) {
@@ -72,6 +94,13 @@ HttpRpcProvider.prototype.send = function (payload) {
     });
 };
 
+/// Prototype object method
+/// Should be called only for polling requests
+/// Asynchronous
+/// On response it passege message to handlers, but only if message's result is true or not empty array
+/// Otherwise response is being silently ignored
+/// @param payload is inner message object
+/// @id is id of poll that we are calling
 HttpRpcProvider.prototype.poll = function (payload, id) {
     var self = this;
     this.sendRequest(payload, function (request) {
@@ -85,6 +114,8 @@ HttpRpcProvider.prototype.poll = function (payload, id) {
     });
 };
 
+/// Prototype object property
+/// Should be used to set message handlers for this provider
 Object.defineProperty(HttpRpcProvider.prototype, "onmessage", {
     set: function (handler) {
         this.handlers.push(handler);
@@ -92,3 +123,4 @@ Object.defineProperty(HttpRpcProvider.prototype, "onmessage", {
 });
 
 module.exports = HttpRpcProvider;
+

lib/providermanager.js

+/*
+    This file is part of ethereum.js.
+
+    ethereum.js is free software: you can redistribute it and/or modify
+    it under the terms of the GNU Lesser General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    ethereum.js is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU Lesser General Public License for more details.
+
+    You should have received a copy of the GNU Lesser General Public License
+    along with ethereum.js.  If not, see <http://www.gnu.org/licenses/>.
+*/
+/** @file providermanager.js
+ * @authors:
+ *   Jeffrey Wilcke <jeff@ethdev.com>
+ *   Marek Kotewicz <marek@ethdev.com>
+ *   Marian Oancea <marian@ethdev.com>
+ *   Gav Wood <g@ethdev.com>
+ * @date 2014
+ */
+
+// TODO: is these line is supposed to be here? 
+if (process.env.NODE_ENV !== 'build') {
+    var web3 = require('./web3'); // jshint ignore:line
+}
+
+/**
+ * Provider manager object prototype
+ * It's responsible for passing messages to providers
+ * If no provider is set it's responsible for queuing requests
+ * It's also responsible for polling the ethereum node for incoming messages
+ * Default poll timeout is 12 seconds
+ * If we are running ethereum.js inside ethereum browser, there are backend based tools responsible for polling,
+ * and provider manager polling mechanism is not used
+ */
+var ProviderManager = function() {
+    this.queued = [];
+    this.polls = [];
+    this.ready = false;
+    this.provider = undefined;
+    this.id = 1;
+
+    var self = this;
+    var poll = function () {
+        if (self.provider && self.provider.poll) {
+            self.polls.forEach(function (data) {
+                data.data._id = self.id;
+                self.id++;
+                self.provider.poll(data.data, data.id);
+            });
+        }
+        setTimeout(poll, 12000);
+    };
+    poll();
+};
+
+/// sends outgoing requests, if provider is not available, enqueue the request
+ProviderManager.prototype.send = function(data, cb) {
+    data._id = this.id;
+    if (cb) {
+        web3._callbacks[data._id] = cb;
+    }
+
+    data.args = data.args || [];
+    this.id++;
+
+    if(this.provider !== undefined) {
+        this.provider.send(data);
+    } else {
+        console.warn("provider is not set");
+        this.queued.push(data);
+    }
+};
+
+/// setups provider, which will be used for sending messages
+ProviderManager.prototype.set = function(provider) {
+    if(this.provider !== undefined && this.provider.unload !== undefined) {
+        this.provider.unload();
+    }
+
+    this.provider = provider;
+    this.ready = true;
+};
+
+/// resends queued messages
+ProviderManager.prototype.sendQueued = function() {
+    for(var i = 0; this.queued.length; i++) {
+        // Resend
+        this.send(this.queued[i]);
+    }
+};
+
+/// @returns true if the provider i properly set
+ProviderManager.prototype.installed = function() {
+    return this.provider !== undefined;
+};
+
+/// this method is only used, when we do not have native qt bindings and have to do polling on our own
+/// should be callled, on start watching for eth/shh changes
+ProviderManager.prototype.startPolling = function (data, pollId) {
+    if (!this.provider || !this.provider.poll) {
+        return;
+    }
+    this.polls.push({data: data, id: pollId});
+};
+
+/// should be called to stop polling for certain watch changes
+ProviderManager.prototype.stopPolling = function (pollId) {
+    for (var i = this.polls.length; i--;) {
+        var poll = this.polls[i];
+        if (poll.id === pollId) {
+            this.polls.splice(i, 1);
+        }
+    }
+};
+
+module.exports = ProviderManager;
+

lib/qt.js

@@ -21,6 +21,11 @@
  * @date 2014
  */
 
+/**
+ * QtProvider object prototype is implementing 'provider protocol'
+ * Should be used inside ethereum browser. It's compatible with cpp and go clients.
+ * It uses navigator.qt object to pass the messages to native bindings
+ */
 var QtProvider = function() {
     this.handlers = [];
 
@@ -32,10 +37,17 @@ var QtProvider = function() {
     };
 };
 
+/// Prototype object method
+/// Should be called when we want to send single api request to native bindings
+/// Asynchronous
+/// Response will be received by navigator.qt.onmessage method and passed to handlers
+/// @param payload is inner message object
 QtProvider.prototype.send = function(payload) {
     navigator.qt.postMessage(JSON.stringify(payload));
 };
 
+/// Prototype object property
+/// Should be used to set message handlers for this provider
 Object.defineProperty(QtProvider.prototype, "onmessage", {
     set: function(handler) {
         this.handlers.push(handler);

lib/websocket.js

@@ -27,9 +27,17 @@ if (process.env.NODE_ENV !== 'build') {
     var WebSocket = require('ws'); // jshint ignore:line
 }
 
+/**
+ * WebSocketProvider object prototype is implementing 'provider protocol'
+ * Should be used when we want to connect to ethereum backend over websockets
+ * It's compatible with go client
+ * The constructor allows to specify host uri
+ */
 var WebSocketProvider = function(host) {
+
     // onmessage handlers
     this.handlers = [];
+
     // queue will be filled with messages if send is invoked before the ws is ready
     this.queued = [];
     this.ready = false;
@@ -46,15 +54,20 @@ var WebSocketProvider = function(host) {
     this.ws.onopen = function() {
         self.ready = true;
 
-        for(var i = 0; i < self.queued.length; i++) {
+        for (var i = 0; i < self.queued.length; i++) {
             // Resend
             self.send(self.queued[i]);
         }
     };
 };
 
+/// Prototype object method
+/// Should be called when we want to send single api request to server
+/// Asynchronous, it's using websockets
+/// Response for the call will be received by ws.onmessage
+/// @param payload is inner message object
 WebSocketProvider.prototype.send = function(payload) {
-    if(this.ready) {
+    if (this.ready) {
         var data = JSON.stringify(payload);
 
         this.ws.send(data);
@@ -63,13 +76,20 @@ WebSocketProvider.prototype.send = function(payload) {
     }
 };
 
+/// Prototype object method
+/// Should be called to add handlers
 WebSocketProvider.prototype.onMessage = function(handler) {
     this.handlers.push(handler);
 };
 
+/// Prototype object method
+/// Should be called to close websockets connection
 WebSocketProvider.prototype.unload = function() {
     this.ws.close();
 };
+
+/// Prototype object property
+/// Should be used to set message handlers for this provider
 Object.defineProperty(WebSocketProvider.prototype, "onmessage", {
     set: function(provider) { this.onMessage(provider); }
 });

test/db.methods.js

@@ -7,12 +7,10 @@ web3.setProvider(new web3.providers.WebSocketProvider('http://localhost:8080'));
 
 describe('web3', function() {
     describe('db', function() {
-        it('should have all methods implemented', function() {
-            u.methodExists(web3.db, 'put');
-            u.methodExists(web3.db, 'get');
-            u.methodExists(web3.db, 'putString');
-            u.methodExists(web3.db, 'getString');
-        });
+        u.methodExists(web3.db, 'put');
+        u.methodExists(web3.db, 'get');
+        u.methodExists(web3.db, 'putString');
+        u.methodExists(web3.db, 'getString');
     });
 });
 

test/eth.methods.js

@@ -7,35 +7,31 @@ web3.setProvider(new web3.providers.WebSocketProvider('http://localhost:8080'));
 
 describe('web3', function() {
     describe('eth', function() {
-        it('should have all methods implemented', function() {
-            u.methodExists(web3.eth, 'balanceAt');
-            u.methodExists(web3.eth, 'stateAt');
-            u.methodExists(web3.eth, 'storageAt');
-            u.methodExists(web3.eth, 'countAt');
-            u.methodExists(web3.eth, 'codeAt');
-            u.methodExists(web3.eth, 'transact');
-            u.methodExists(web3.eth, 'call');
-            u.methodExists(web3.eth, 'block');
-            u.methodExists(web3.eth, 'transaction');
-            u.methodExists(web3.eth, 'uncle');
-            u.methodExists(web3.eth, 'compilers');
-            u.methodExists(web3.eth, 'lll');
-            u.methodExists(web3.eth, 'solidity');
-            u.methodExists(web3.eth, 'serpent');
-            u.methodExists(web3.eth, 'logs');
-        });
+        u.methodExists(web3.eth, 'balanceAt');
+        u.methodExists(web3.eth, 'stateAt');
+        u.methodExists(web3.eth, 'storageAt');
+        u.methodExists(web3.eth, 'countAt');
+        u.methodExists(web3.eth, 'codeAt');
+        u.methodExists(web3.eth, 'transact');
+        u.methodExists(web3.eth, 'call');
+        u.methodExists(web3.eth, 'block');
+        u.methodExists(web3.eth, 'transaction');
+        u.methodExists(web3.eth, 'uncle');
+        u.methodExists(web3.eth, 'compilers');
+        u.methodExists(web3.eth, 'lll');
+        u.methodExists(web3.eth, 'solidity');
+        u.methodExists(web3.eth, 'serpent');
+        u.methodExists(web3.eth, 'logs');
 
-        it('should have all properties implemented', function () {
-            u.propertyExists(web3.eth, 'coinbase');
-            u.propertyExists(web3.eth, 'listening');
-            u.propertyExists(web3.eth, 'mining');
-            u.propertyExists(web3.eth, 'gasPrice');
-            u.propertyExists(web3.eth, 'account');
-            u.propertyExists(web3.eth, 'accounts');
-            u.propertyExists(web3.eth, 'peerCount');
-            u.propertyExists(web3.eth, 'defaultBlock');
-            u.propertyExists(web3.eth, 'number');
-        });
+        u.propertyExists(web3.eth, 'coinbase');
+        u.propertyExists(web3.eth, 'listening');
+        u.propertyExists(web3.eth, 'mining');
+        u.propertyExists(web3.eth, 'gasPrice');
+        u.propertyExists(web3.eth, 'account');
+        u.propertyExists(web3.eth, 'accounts');
+        u.propertyExists(web3.eth, 'peerCount');
+        u.propertyExists(web3.eth, 'defaultBlock');
+        u.propertyExists(web3.eth, 'number');
     });
 });
 

test/mocha.opts

---reporter Spec
+--reporter spec 
 

test/shh.methods.js

@@ -7,13 +7,11 @@ web3.setProvider(new web3.providers.WebSocketProvider('http://localhost:8080'));
 
 describe('web3', function() {
     describe('shh', function() {
-        it('should have all methods implemented', function() {
-            u.methodExists(web3.shh, 'post');
-            u.methodExists(web3.shh, 'newIdentity');
-            u.methodExists(web3.shh, 'haveIdentity');
-            u.methodExists(web3.shh, 'newGroup');
-            u.methodExists(web3.shh, 'addToGroup');
-        });
+        u.methodExists(web3.shh, 'post');
+        u.methodExists(web3.shh, 'newIdentity');
+        u.methodExists(web3.shh, 'haveIdentity');
+        u.methodExists(web3.shh, 'newGroup');
+        u.methodExists(web3.shh, 'addToGroup');
     });
 });
 

test/utils.js

 var assert = require('assert');
 
 var methodExists = function (object, method) {
-    assert.equal('function', typeof object[method], 'method ' + method + ' is not implemented');
+    it('should have method ' + method + ' implemented', function() {
+        assert.equal('function', typeof object[method], 'method ' + method + ' is not implemented');
+    });
 };
 
 var propertyExists = function (object, property) {
-    assert.equal('object', typeof object[property], 'property ' + property + ' is not implemented');
+    it('should have property ' + property + ' implemented', function() {
+        assert.equal('object', typeof object[property], 'property ' + property + ' is not implemented');
+    });
 };
 
 module.exports = {

test/web3.methods.js

@@ -6,13 +6,11 @@ var u = require('./utils.js');
 web3.setProvider(new web3.providers.WebSocketProvider('http://localhost:8080')); // TODO: create some mock provider
 
 describe('web3', function() {
-    it('should have all methods implemented', function() {
-        u.methodExists(web3, 'sha3');
-        u.methodExists(web3, 'toAscii');
-        u.methodExists(web3, 'fromAscii');
-        u.methodExists(web3, 'toFixed');
-        u.methodExists(web3, 'fromFixed');
-        u.methodExists(web3, 'offset');
-    });
+    u.methodExists(web3, 'sha3');
+    u.methodExists(web3, 'toAscii');
+    u.methodExists(web3, 'fromAscii');
+    u.methodExists(web3, 'toFixed');
+    u.methodExists(web3, 'fromFixed');
+    u.methodExists(web3, 'offset');
 });