Events and Logs

When a transaction is mined, smart contracts emit events and write logs to the blockchain.

Logs are associated with the contract address and included in the blockchain but logs are not accessible from within contracts. Log storage is cheaper than contract storage (that is, it costs less gas) so if the required data can be stored in and accessed from logs, the cost is reduced. For example, you can use logs to display all transfers made using a specific contract but not the current state of the contract.

A Dapp front end can either request logs using the JSON-RPC API filter methods or subscribe to logs using the RPC Pub/Sub API.

Topics

Log entries contain up to four topics. The first topic is the event signature hash and up to three topics are the indexed event parameters.

!!! example Log entry for an event with one indexed parameter:

```json
{
  "logIndex": "0x0",
  "removed": false,
  "blockNumber": "0x84",
  "blockHash": "0x5fc573d76ec48ec80cbc43f299ebc306a8168112e3a4485c23e84e9a40f5d336",
  "transactionHash": "0xcb52f02342c2498df82c49ac26b2e91e182155c8b2a2add5b6dc4c249511f85a",
  "transactionIndex": "0x0",
  "address": "0x42699a7612a82f1d9c36148af9c77354759b210b",
  "data": "0x",
  "topics": [
    "0x04474795f5b996ff80cb47c148d4c5ccdbe09ef27551820caa9c2f8ed149cce3",
    "0x0000000000000000000000000000000000000000000000000000000000000001"
  ]
}
```

Event Parameters

Up to three event parameters can have the indexed attribute. Indexed parameters are stored as topics in the logs. Indexed parameters can be searched and filtered.

Topics are 32 bytes. If an indexed argument is an array (including string and byte datatypes), the keccak-256 hash of the paramater is stored as a topic.

Non-indexed parameters are included in the logs data but cannot be easily searched or filtered.

!!! example

A Solidity contract that stores one indexed and one non-indexed parameter and has an event that emits the value of each parameter: 

```solidity
pragma solidity ^0.5.1;
contract Storage {
  uint256 public valueIndexed;
  uint256 public valueNotIndexed;

  event Event1(uint256 indexed valueIndexed, uint256 valueNotIndexed);

  function setValue(uint256 _valueIndexed, uint256 _valueNotIndexed) public {
	 valueIndexed = _valueIndexed;
	 valueNotIndexed = _valueNotIndexed;
	 emit Event1(_valueIndexed, _valueNotIndexed); 
  }
}
```

!!! example
Log entry created by invoking the contract above with valueIndexed set to 5 and valueNotIndexed set to 7:

```json
 {
   "logIndex": "0x0",
   "removed": false,
   "blockNumber": "0x4d6",
   "blockHash": "0x7d0ac7c12ac9f622d346d444c7e0fa4dda8d4ed90de80d6a28814613a4884a67",
   "transactionHash": "0xe994022ada94371ace00c4e1e20663a01437846ced02f18b3f3afec827002781",
   "transactionIndex": "0x0",
   "address": "0x43d1f9096674b5722d359b6402381816d5b22f28",
   "data": "0x0000000000000000000000000000000000000000000000000000000000000007",
   "topics": [
    "0xd3610b1c54575b7f4f0dc03d210b8ac55624ae007679b7a928a4f25a709331a8",
    "0x0000000000000000000000000000000000000000000000000000000000000005"
   ]
 }
```

Event Signature Hash

The first topic in a log entry is always the the event signature hash. The event signature hash is a keccak-256 hash of the event name and input argument types. Argument names are ignored. For example, the event Hello(uint256 worldId) has the signature hash keccak('Hello(uint256)'). The signature identifies to which event log topics belong.

!!! example

A Solidity contract with two different events: 

``` solidity	
     pragma solidity ^0.5.1;
     contract Storage {
     uint256 public valueA;
     uint256 public valueB;

     event Event1(uint256 indexed valueA);
     event Event2(uint256 indexed valueB);

     function setValue(uint256 _valueA) public {
  	    valueA = _valueA;
  	    emit Event1(_valueA); 
     }
  
     function setValueAgain(uint256 _valueB) public {
  	    valueB = _valueB;
  	    emit Event2(_valueB); 
     }
   } 
```

The event signature hash for event 1 is keccak('Event1(uint256)') and the event signature hash for event 2 is keccak('Event2(uint256)'). The hashes are:

04474795f5b996ff80cb47c148d4c5ccdbe09ef27551820caa9c2f8ed149cce3 for event 1
06df6fb2d6d0b17a870decb858cc46bf7b69142ab7b9318f7603ed3fd4ad240e for event 2

!!! tip You can use a library keccak (sha3) hash function such as provided in Web3.js or an an online tool such as https://emn178.github.io/online-tools/keccak_256.html to generate event signature hashes.

!!! example Log entries from invoking the Solidity contract above:

```json
[
    {
        "logIndex": "0x0",
        "removed": false,
        "blockNumber": "0x84",
        "blockHash": "0x5fc573d76ec48ec80cbc43f299ebc306a8168112e3a4485c23e84e9a40f5d336",
        "transactionHash": "0xcb52f02342c2498df82c49ac26b2e91e182155c8b2a2add5b6dc4c249511f85a",
        "transactionIndex": "0x0",
        "address": "0x42699a7612a82f1d9c36148af9c77354759b210b",
        "data": "0x",
        "topics": [
            "0x04474795f5b996ff80cb47c148d4c5ccdbe09ef27551820caa9c2f8ed149cce3",
            "0x0000000000000000000000000000000000000000000000000000000000000001"
        ]
    },
    {
        "logIndex": "0x0",
        "removed": false,
        "blockNumber": "0x87",
        "blockHash": "0x6643a1e58ad857f727552e4572b837a85b3ca64c4799d085170c707e4dad5255",
        "transactionHash": "0xa95295fcea7df3b9e47ab95d2dadeb868145719ed9cc0e6c757c8a174e1fcb11",
        "transactionIndex": "0x0",
        "address": "0x42699a7612a82f1d9c36148af9c77354759b210b",
        "data": "0x",
        "topics": [
            "0x06df6fb2d6d0b17a870decb858cc46bf7b69142ab7b9318f7603ed3fd4ad240e",
            "0x0000000000000000000000000000000000000000000000000000000000000002"
        ]
    }
]
```

Topic Filters

Filter options objects have a topics key to filter logs by topics.

Topics are order-dependent. A transaction with a log containing topics [A, B] is matched with the following topic filters:

[] - Match any topic
[A] - Match A in first position
[[null], [B]] - Match any topic in first position AND B in second position
[[A],[B]] - Match A in first position AND B in second position
[[A, C], [B, D]] - Match (A OR C) in first position AND (B OR D) in second position

!!! example The following filter option object returns log entries for the Event Parameters example contract where valueIndexed is set to 5 or 9:

```json
{
  "fromBlock":"earliest", 
  "toBlock":"latest", 
  "address":"0x43d1f9096674b5722d359b6402381816d5b22f28",
  "topics":[
   ["0xd3610b1c54575b7f4f0dc03d210b8ac55624ae007679b7a928a4f25a709331a8"], 
   ["0x0000000000000000000000000000000000000000000000000000000000000005", "0x0000000000000000000000000000000000000000000000000000000000000009"]
  ]
}
```

7.4 KiB Raw Blame History

Events and Logs

Topics

Event Parameters

Event Signature Hash

Topic Filters

7.4 KiB

Raw Blame History