From 54a56e770ca7a666ab681534f9776959d4ff148d Mon Sep 17 00:00:00 2001 From: Fabian Vogelsteller Date: Tue, 1 Nov 2016 16:03:03 +0100 Subject: [PATCH] changed minded event to receipt --- docs/callbacks-promises-events.rst | 22 ++++++++++++++++++++++ docs/getting-started.rst | 19 +++++++++---------- docs/index.rst | 3 ++- lib/web3/contract.js | 14 +++++++------- test/contract.js | 16 ++++++++-------- test/web3.eth.getUncle.js | 4 ++-- 6 files changed, 50 insertions(+), 28 deletions(-) create mode 100644 docs/callbacks-promises-events.rst diff --git a/docs/callbacks-promises-events.rst b/docs/callbacks-promises-events.rst new file mode 100644 index 0000000..ac6e45e --- /dev/null +++ b/docs/callbacks-promises-events.rst @@ -0,0 +1,22 @@ +############### +Callbacks Promises Events +############### + +To help web3 integrate into all kind of projects with different standards +we provide multiple ways to act on asynchronous functions. + +Most web3.js objects allow a callback as the last parameter, as well as return a promise to chain funcitons. + +Ethereum as a blockchain has different level of finality and therefore we return for some functions, +like ``web3.eth.sendTransaction`` or contract methods a "promiEvent". This is a promise combined with an event emitter. + +This promiEvent works like a normal promise with added ``on`` functions to watch for additional events like "receipt" or "transactionHash" + +.. code-block:: javascript + + web3.eth.sendTransaction({from: '0x123...', data: '0x432...'}) + .on('transactionHash', function(hash){ ... }) + .on('receipt', function(receipt){ ... }) + .then(function(receipt){ + // will be fired once the receipt its mined + }); diff --git a/docs/getting-started.rst b/docs/getting-started.rst index 9f95bb8..95c7e12 100644 --- a/docs/getting-started.rst +++ b/docs/getting-started.rst @@ -1,15 +1,14 @@ - ############### Getting Started ############### The web3.js library is a collection of modules which contain specific functionality for the ethereum ecosystem. -- The ``web3-eth`` library contains functions related to the ethereum blockchain and smart contracts -- The ``web3-net`` library contains functions related to the network connection and peers -- The ``web3-shh`` library contains functions related to the whisper protocol for p2p communication -- The ``web3-bzz`` library contains functions related to the swarm protocol for decentralized file storage -- The ``web3-personal`` library contains functions related ethereum account management +- The ``web3-eth`` is for the ethereum blockchain and smart contracts +- The ``web3-net`` is for network connection and peers +- The ``web3-shh`` is for the whisper protocol to communicate p2p and broadcast +- The ``web3-bzz`` is for the swarm protocol, the decentralized file storage +- The ``web3-personal`` is for ethereum account management The following page will describe how to install and add web3.js to your project. You can find some extra examples in the :ref:`API-reference ` and the `examples here `_. @@ -31,10 +30,10 @@ First you need to get web3.js into your project. This can be done using the foll - npm: ``npm install web3`` - bower: ``bower install web3`` - meteor: ``meteor add ethereum:web3`` -- vanilla: ``link the dist./web3.min.js`` +- pure js: link the ``dist/web3.min.js`` -After that you need to create a web3 instance, setting a provider. To make sure you don't overwrite the already set provider when in Mist. -Check first if the web3 object is available: +After that you need to create a web3 instance and set a provider. +If you are in a ethereum supported Browser like Mist or MetaMask check if the ``web3`` object is available: .. code-block:: javascript @@ -45,4 +44,4 @@ Check first if the web3 object is available: web3 = new Web3(new Web3.providers.HttpProvider("http://localhost:8545")); } -Thats it! now you can use the API of the web3 object. +Thats it! now you can use the ``web3`` object. diff --git a/docs/index.rst b/docs/index.rst index 8d5da97..d6323d1 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -5,7 +5,7 @@ web3.js is a collection of libraries which allow you to interact with a local or using a HTTP or IPC connection. The following documentation will guide you through :ref:`installing and running web3.js `, -as well as providing a :ref:`API reference documentation ` with examples. +as well as providing a :ref:`API reference documentation <#api-reference>` with examples. Contents: @@ -16,6 +16,7 @@ Contents: :caption: User Documentation getting-started + callbacks-promises-events .. toctree:: diff --git a/lib/web3/contract.js b/lib/web3/contract.js index 090b98d..151011f 100644 --- a/lib/web3/contract.js +++ b/lib/web3/contract.js @@ -441,14 +441,14 @@ Contract.prototype._checkForContractAddress = function(transactionHash, callback }; /** - * Deploys a contract and fire events based on its state: transactionHash, mined + * Deploys a contract and fire events based on its state: transactionHash, receipt * - * All event listeners will be removed, once the last possible event is fired ("error", or "mined") + * All event listeners will be removed, once the last possible event is fired ("error", or "receipt") * * @method deploy * @param {Object} options * @param {Function} callback - * @return {Object} EventEmitter possible events are "error", "transactionHash" and "mined" + * @return {Object} EventEmitter possible events are "error", "transactionHash" and "receipt" */ Contract.prototype.deploy = function(options, callback){ /*jshint maxcomplexity: 6 */ @@ -500,14 +500,14 @@ Contract.prototype.deploy = function(options, callback){ } else { defer.promise.emit('transactionHash', hash); - // wait for the contract to be mined and return the address + // wait for the contract to be receipt and return the address _this._checkForContractAddress(hash, function(err, receipt){ if(err) { defer.reject(err); defer.promise.emit('error', err); } else { defer.resolve(receipt); - defer.promise.emit('mined', receipt); + defer.promise.emit('receipt', receipt); } // remove all listeners on the end, as no event will ever fire again @@ -809,7 +809,7 @@ Contract.prototype._executeMethod = function _executeMethod(type){ if(type === 'send') { - // fire "mined" event and resolve after + // fire "receipt" event and resolve after _this._parent._web3.eth.subscribe('newBlocks', {}, function (err, block, sub) { if(!err) { @@ -819,7 +819,7 @@ Contract.prototype._executeMethod = function _executeMethod(type){ sub.unsubscribe(); if(!receipt.outOfGas) { - defer.promise.emit('mined', receipt); + defer.promise.emit('receipt', receipt); defer.resolve(receipt); defer.promise.removeAllListeners(); diff --git a/test/contract.js b/test/contract.js index 57f0f8f..c48f165 100644 --- a/test/contract.js +++ b/test/contract.js @@ -324,7 +324,7 @@ describe('contract', function () { // tx hash assert.equal(result, '0x1234000000000000000000000000000000000000000000000000000000056789'); }) - .on('mined', function(result){ + .on('receipt', function(result){ assert.deepEqual(result, { contractAddress: address, cumulativeGasUsed: 10, @@ -1256,21 +1256,21 @@ describe('contract', function () { var contract = new web3.eth.contract(abi); - var deploy = contract.deploy({ + contract.deploy({ from: address, data: '0x1234567', arguments: [address, 200], gas: 50000, gasPrice: 3000 - }); - deploy.on('transactionHash', function (value) { + }) + .on('transactionHash', function (value) { assert.equal('0x5550000000000000000000000000000000000000000000000000000000000032', value); - }); - deploy.on('mined', function (value) { - assert.equal(address, value.contractAddress); + }) + .on('receipt', function (receipt) { + assert.equal(address, receipt.contractAddress); done(); }); - // deploy.on('error', function (value) { + // .on('error', function (value) { // console.log('error', value); // done(); // }); diff --git a/test/web3.eth.getUncle.js b/test/web3.eth.getUncle.js index a8ef6b1..83bbae9 100644 --- a/test/web3.eth.getUncle.js +++ b/test/web3.eth.getUncle.js @@ -64,7 +64,7 @@ var blockResultWithTx = { "gasUsed": "0x9f759", "timestamp": "0x54e34e8e", "transactions": [{ - "status": "mined", + // "status": "mined", "hash":"0xc6ef2fc5426d6ad6fd9e2a26abeab0aa2411b7ab17f30a99d3cb96aed1d1055b", "nonce":"0x2", "blockHash": "0x6fd9e2a26ab", @@ -97,7 +97,7 @@ var formattedBlockResultWithTx = { "gasUsed": 653145, "timestamp": 1424182926, "transactions": [{ - "status": "mined", + // "status": "mined", "hash":"0xc6ef2fc5426d6ad6fd9e2a26abeab0aa2411b7ab17f30a99d3cb96aed1d1055b", "nonce": 2, "blockHash": "0x6fd9e2a26ab",