This documentation is under construction and the web3.js 1.0 stable version isn’t released. If your using a version v0.x.x of web3.js then please have a look at

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 returning promises to chain functions.

Ethereum as a blockchain has different levels of finality and therefore needs to return multiple “stages” of an action. To cope with requirement we return a “PromiEvent” for functions like web3.eth.sendTransaction or contract methods. These stages are encapsulated into a “PromiEvent”, which combines a promise with an event emitter. The event emitter fires an event for each of the finality stages.

An example of a function that benefits from a PromiEvent is the web3.eth.sendTransaction method.

web3.eth.sendTransaction({from: '0x123...', data: '0x432...'})
.once('transactionHash', function(hash){ ... })
.once('receipt', function(receipt){ ... })
.on('confirmation', function(confNumber, receipt){ ... })
.on('error', function(error){ ... })
    // will be fired once the receipt is mined