changed minded event to receipt

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
+    });

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-eth`` is for the ethereum blockchain and smart contracts
-- The ``web3-net`` library contains functions related to the network connection and peers
+- The ``web3-net`` is for network connection and peers
-- The ``web3-shh`` library contains functions related to the whisper protocol for p2p communication
+- The ``web3-shh`` is for the whisper protocol to communicate p2p and broadcast
-- The ``web3-bzz`` library contains functions related to the swarm protocol for decentralized file storage
+- The ``web3-bzz`` is for the swarm protocol, the decentralized file storage
-- The ``web3-personal`` library contains functions related ethereum account management
+- 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 <api-reference>` and the `examples here <https://github.com/ethereum/web3.js/tree/master/examples>`_.
@@ -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.
+After that you need to create a web3 instance and set a provider.
-Check first if the web3 object is available:
+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.

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 <adding-web3>`,
-as well as providing a :ref:`API reference documentation <api-reference>` 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::

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();
 

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) {
+            .on('receipt', function (receipt) {
-                assert.equal(address, value.contractAddress);
+                assert.equal(address, receipt.contractAddress);
                 done();
             });
-            // deploy.on('error', function (value) {
+            // .on('error', function (value) {
             //     console.log('error', value);
             //     done();
             // });

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",