Intruduction

An event which is emitted will be stored in the transaction logs which contains arguments passed with emit in smart contract. These logs are stored on blockchain and are accessible via transactions. An event generated can not be accessed from within contracts we need to access them externally using various methods.

Events with Web3

There are many ways  we can listen to/call events with the help of web3 

Once 

Subscribes to an event and unsubscribes immediately after the first event or error. Will only fire for a single event.

Syntax :  myContract.once(event[, options], callback)

Parameters :

event  [ String ] : The name of the event in the contract, or "allEvents" to get all events.

options [ Object ] (optional) : The options used for deployment.

callback - Function: This callback will be fired for the first event as the second argument, or an error as the first argument. See getPastEvents return values for details about the event structure.

Returns  :  Undefined

Code Example :

myContract.once('MyEvent', {
    filter: {myIndexedParam: [20,23], myOtherIndexedParam: '0x123456789...'}, 
    fromBlock: 0
}, function(error, event){ console.log(event); });

Output  :

{
    returnValues: {
        myIndexedParam: 20,
        myOtherIndexedParam: '0x123456789...',
        myNonIndexParam: 'My String'
    },
    raw: {
        data: '0x7f9fade1c0d57a7af66ab4ead79fade1c0d57a7af66ab4ead7c2c2eb7b11a91385',
        topics: ['0xfd43ade1c09fade1c0d57a7af66ab4ead7c2c2eb7b11a91ffdd57a7af66ab4ead7', '0x7f9fade1c0d57a7af66ab4ead79fade1c0d57a7af66ab4ead7c2c2eb7b11a91385']
    },
    event: 'MyEvent',
    signature: '0xfd43ade1c09fade1c0d57a7af66ab4ead7c2c2eb7b11a91ffdd57a7af66ab4ead7',
    logIndex: 0,
    transactionIndex: 0,
    transactionHash: '0x7f9fade1c0d57a7af66ab4ead79fade1c0d57a7af66ab4ead7c2c2eb7b11a91385',
    blockHash: '0xfd43ade1c09fade1c0d57a7af66ab4ead7c2c2eb7b11a91ffdd57a7af66ab4ead7',
    blockNumber: 1234,
    address: '0xde0B295669a9FD93d5F28D9Ec85E40f4cb697BAe'
}

events

Subscribe to an event.

Syntax :  myContract.events.MyEvent([options][, callback])

Parameters : 

options  [ Object ] (optional): The options used for deployment.

• filter - Object (optional): Let you filter events by indexed parameters, e.g. {filter: {myNumber: [12,13]}} means all events where “myNumber” is 12 or 13.
• fromBlock - Number|String|BN|BigNumber (optional): The block number (greater than or equal to) from which to get events on. Pre-defined block numbers as "earliest", "latest" and "pending" can also be used. For specific range use getPastEvents.
• topics - Array (optional): This allows to manually set the topics for the event filter. If given the filter property and event signature, (topic[0]) will not be set automatically.

callback  [ Function ] (optional): This callback will be fired for each event as the second argument, or an error as the first argument.

Returns  :

a) EventEmitter : Different emmiters will have different return values. The event emitter has the following events:

• "data" [ Object ] : Fires on each incoming event with the event object as argument.
• "changed" [ Object ] : Fires on each event which was removed from the blockchain. The event will have the additional property "removed: true".
• "error"  [ Object ] : Fires when an error in the subscription occours.
• "connected"  [ String ] : Fires once after the subscription successfully connected. Returns the subscription id.

The structure of the returned event Object looks as follows:

• event - String: The event name.
• signature - String|Null: The event signature, null if it’s an anonymous event.
• address - String: Address this event originated from.
• returnValues - Object: The return values coming from the event, e.g. {myVar: 1, myVar2: '0x234...'}.
• logIndex - Number: Integer of the event index position in the block.
• transactionIndex - Number: Integer of the transaction’s index position the event was created in.
• transactionHash 32 Bytes - String: Hash of the transaction this event was created in.
• blockHash 32 Bytes - String: Hash of the block this event was created in. null when it’s still pending.
• blockNumber - Number: The block number this log was created in. null when still pending.
• raw.data - String: The data containing non-indexed log parameter.
• raw.topics - Array: An array with max 4 32 Byte topics, topic 1-3 contains indexed parameters of the event.

Code Example :

myContract.events.MyEvent({
    filter: {myIndexedParam: [20,23], myOtherIndexedParam: '0x123456789...'}, // Using an array means OR: e.g. 20 or 23
    fromBlock: 0
}, function(error, event){ console.log(event); })
.on("connected", function(subscriptionId){
    console.log(subscriptionId);
})
.on('data', function(event){
    console.log(event); 
})
.on('changed', function(event){
    // remove event from local database
})
.on('error', function(error, receipt) { 
console.log(error)
});

Output :

> {
    returnValues: {
        myIndexedParam: 20,
        myOtherIndexedParam: '0x123456789...',
        myNonIndexParam: 'My String'
    },
    raw: {
        data: '0x7f9fade1c0d57a7af66ab4ead79fade1c0d57a7af66ab4ead7c2c2eb7b11a91385',
        topics: ['0xfd43ade1c09fade1c0d57a7af66ab4ead7c2c2eb7b11a91ffdd57a7af66ab4ead7', '0x7f9fade1c0d57a7af66ab4ead79fade1c0d57a7af66ab4ead7c2c2eb7b11a91385']
    },
    event: 'MyEvent',
    signature: '0xfd43ade1c09fade1c0d57a7af66ab4ead7c2c2eb7b11a91ffdd57a7af66ab4ead7',
    logIndex: 0,
    transactionIndex: 0,
    transactionHash: '0x7f9fade1c0d57a7af66ab4ead79fade1c0d57a7af66ab4ead7c2c2eb7b11a91385',
    blockHash: '0xfd43ade1c09fade1c0d57a7af66ab4ead7c2c2eb7b11a91ffdd57a7af66ab4ead7',
    blockNumber: 1234,
    address: '0xde0B295669a9FD93d5F28D9Ec85E40f4cb697BAe'
}

events.allEvents

This method is same as events but receives all events from given smart contract.

Syntax :  myContract.events.allEvents([options][, callback])

Parameters : 

options  [ Object ] (optional): The options used for deployment.

• filter - Object (optional): Let you filter events by indexed parameters, e.g. {filter: {myNumber: [12,13]}} means all events where “myNumber” is 12 or 13.
• fromBlock - Number|String|BN|BigNumber (optional): The block number (greater than or equal to) from which to get events on. Pre-defined block numbers as "earliest", "latest" and "pending" can also be used. For specific range use getPastEvents.
• topics - Array (optional): This allows to manually set the topics for the event filter. If given the filter property and event signature, (topic[0]) will not be set automatically.

callback  [ Function ] (optional): This callback will be fired for each event as the second argument, or an error as the first argument.

Returns  :

a) EventEmitter : Different emmiters will have different return values. The event emitter has the following events:

• "data" [ Object ] : Fires on each incoming event with the event object as argument.
• "changed" [ Object ] : Fires on each event which was removed from the blockchain. The event will have the additional property "removed: true".
• "error"  [ Object ] : Fires when an error in the subscription occours.
• "connected"  [ String ] : Fires once after the subscription successfully connected. Returns the subscription id.

The structure of the returned event Object looks as follows:

• event - String: The event name.
• signature - String|Null: The event signature, null if it’s an anonymous event.
• address - String: Address this event originated from.
• returnValues - Object: The return values coming from the event, e.g. {myVar: 1, myVar2: '0x234...'}.
• logIndex - Number: Integer of the event index position in the block.
• transactionIndex - Number: Integer of the transaction’s index position the event was created in.
• transactionHash 32 Bytes - String: Hash of the transaction this event was created in.
• blockHash 32 Bytes - String: Hash of the block this event was created in. null when it’s still pending.
• blockNumber - Number: The block number this log was created in. null when still pending.
• raw.data - String: The data containing non-indexed log parameter.
• raw.topics - Array: An array with max 4 32 Byte topics, topic 1-3 contains indexed parameters of the event.

Code Example :

myContract.events.allEvents({
    filter: {myIndexedParam: [20,23], myOtherIndexedParam: '0x123456789...'}, // Using an array means OR: e.g. 20 or 23
    fromBlock: 0
}, function(error, event){ console.log(event); })
.on("connected", function(subscriptionId){
    console.log(subscriptionId);
})
.on('data', function(event){
    console.log(event); 
})
.on('changed', function(event){
    // remove event from local database
})
.on('error', function(error, receipt) { 
console.log(error)
});

Output :

> {
    returnValues: {
        myIndexedParam: 20,
        myOtherIndexedParam: '0x123456789...',
        myNonIndexParam: 'My String'
    },
    raw: {
        data: '0x7f9fade1c0d57a7af66ab4ead79fade1c0d57a7af66ab4ead7c2c2eb7b11a91385',
        topics: ['0xfd43ade1c09fade1c0d57a7af66ab4ead7c2c2eb7b11a91ffdd57a7af66ab4ead7', '0x7f9fade1c0d57a7af66ab4ead79fade1c0d57a7af66ab4ead7c2c2eb7b11a91385']
    },
    event: 'MyEvent',
    signature: '0xfd43ade1c09fade1c0d57a7af66ab4ead7c2c2eb7b11a91ffdd57a7af66ab4ead7',
    logIndex: 0,
    transactionIndex: 0,
    transactionHash: '0x7f9fade1c0d57a7af66ab4ead79fade1c0d57a7af66ab4ead7c2c2eb7b11a91385',
    blockHash: '0xfd43ade1c09fade1c0d57a7af66ab4ead7c2c2eb7b11a91ffdd57a7af66ab4ead7',
    blockNumber: 1234,
    address: '0xde0B295669a9FD93d5F28D9Ec85E40f4cb697BAe'
}

getPastEvents

Gets past events for given Smart contract.

Syntax  :  myContract.getPastEvents(event[, options][, callback])

Parameters  :

event  [ String ] : The name of the event in the contract, or "allEvents" to get all events.

options  [ Object ] (optional) : The options used for deployment.

• filter - Object (optional): Lets you filter events by indexed parameters, e.g. {filter: {myNumber: [12,13]}} means all events where “myNumber” is 12 or 13.
• fromBlock - Number|String|BN|BigNumber (optional): The block number (greater than or equal to) from which to get events on. Pre-defined block numbers as "earliest", "latest" and "pending" can also be used.
• toBlock - Number|String|BN|BigNumber (optional): The block number (less than or equal to) to get events up to (Defaults to "latest"). Pre-defined block numbers as "earliest", "latest" and "pending" can also be used.
• topics - Array (optional): This allows manually setting the topics for the event filter. If given the filter property and event signature, (topic[0]) will not be set automatically.

callback  [ Function ] (optional) : This callback will be fired with an array of event logs as the second argument, or an error as the first argument.

Returns :

Promise returns Array : An array with the past event Objects, matching the given event name and filter.

Code Example :

myContract.getPastEvents('MyEvent', {
    filter: {myIndexedParam: [20,23], myOtherIndexedParam: '0x123456789...'}, 
    fromBlock: 0,
    toBlock: 'latest'
}, function(error, events){ console.log(events); })
.then(function(events){
    console.log(events) 
});

output  :

[{
    returnValues: {
        myIndexedParam: 20,
        myOtherIndexedParam: '0x123456789...',
        myNonIndexParam: 'My String'
    },
    raw: {
        data: '0x7f9f13dsc0d57a2af66ab4ead79fade1c0d57a7af66ab4ead7c2c2eb7b11a91385',
        topics: ['0xfd43ade1c09fade1c0d57a7af66ab4ead7c2c2eb7b11a91ffdd57a7af66ab4ead7', '0x7f9fade1c0d57a7af66ab4ead79fade1c0d57a7af66ab4ead7c2c2eb7b11a91385']
    },
    event: 'MyEvent',
    signature: '0xfd43ade1c09fade1c0d57a7af66ab4ead7c2c2eb7b11a91ffdd57a7af66ab4ead7',
    logIndex: 0,
    transactionIndex: 0,
    transactionHash: '0x7f9fade1c0d57a7af66ab4ead79fade1c0d57a7af66ab4ead7c2c2eb7b11a91385',
    blockHash: '0xfd43ade1c09fade1c0d57a7af66ab4ead7c2c2eb7b11a91ffdd57a7af66ab4ead7',
    blockNumber: 1234,
    address: '0xde0B295669a9FD93d5F28D9Ec85E40f4cb697BAe'
},{
    ...
}]