Skip to content
You are reading Hyperledger Besu development version documentation and some displayed features may not be available in the stable release. You can switch to stable version using the version box at screen bottom.

Updated on September 24, 2020

Accessing logs using the Hyperledger Besu API

Subscribe to events, such as logs, using either RPC Pub/Sub over WebSockets or filters over HTTP.

Access logs using the following Hyperledger Besu API methods:

Use eth_newFilter to create the filter before using eth_getFilterChanges and eth_getFilterLogs).

Access logs for private contracts using the equivalent priv_* methods and specifying the privacy group ID. For example, priv_getLogs.

Note

The sample contract included in Events and Logs created the following examples.

Creating a filter

Create a filter using eth_newFilter.

Example

If the example contract was deployed to 0x42699a7612a82f1d9c36148af9c77354759b210b, the following request for eth_newFilter creates a filter to log when valueIndexed is set to 5:

{
 "jsonrpc":"2.0",
 "method":"eth_newFilter",
 "params":[
    {
      "fromBlock":"earliest",
      "toBlock":"latest",
      "address":"0x42699a7612a82f1d9c36148af9c77354759b210b",
      "topics":[
          ["0xd3610b1c54575b7f4f0dc03d210b8ac55624ae007679b7a928a4f25a709331a8"],
          ["0x0000000000000000000000000000000000000000000000000000000000000005"]
      ]
     }
  ],
  "id":1
}

eth_newFilter returns a filter ID hash (for example, 0x1ddf0c00989044e9b41cc0ae40272df3).

Polling a filter for changes

To poll the filter for changes since the last poll, use eth_getFilterChanges with the filter ID hash returned by eth_newFilter.

Example

If the contract had been executed twice since the last poll, with valueIndexed set to 1 and 5, eth_getFilterChanges returns only the log where the topic for valueIndexed is 5:

{
    "jsonrpc": "2.0",
    "id": 1,
    "result": [
        {
            "logIndex": "0x0",
            "removed": false,
            "blockNumber": "0x21c",
            "blockHash": "0xc7e6c9d5b9f522b2c9d2991546be0a8737e587beb6628c056f3c327a44b45132",
            "transactionHash": "0xfd1a40f9fbf89c97b4545ec9db774c85e51dd8a3545f969418a22f9cb79417c5",
            "transactionIndex": "0x0",
            "address": "0x42699a7612a82f1d9c36148af9c77354759b210b",
            "data": "0x0000000000000000000000000000000000000000000000000000000000000005",
            "topics": [
                "0xd3610b1c54575b7f4f0dc03d210b8ac55624ae007679b7a928a4f25a709331a8",
                "0x0000000000000000000000000000000000000000000000000000000000000005"
            ]
        }
    ]
}

Getting all logs for a filter

To get all logs for a filter, use eth_getFilterLogs.

Example

If the contract had been executed twice with valueIndexed set to 5 since the filter was created using eth_newFilter, eth_getFilterLogs returns:

{
    "jsonrpc": "2.0",
    "id": 1,
    "result": [
        {
            "logIndex": "0x0",
            "removed": false,
            "blockNumber": "0x1a7",
            "blockHash": "0x4edda22a242ddc7bc51e2b6b11e63cd67be1af7389470cdea9c869768ff75d42",
            "transactionHash": "0x9535bf8830a72ca7d0020df0b547adc4d0ecc4321b7d5b5d6beb1eccee5c0afa",
            "transactionIndex": "0x0",
            "address": "0x42699a7612a82f1d9c36148af9c77354759b210b",
            "data": "0x0000000000000000000000000000000000000000000000000000000000000005",
            "topics": [
                "0xd3610b1c54575b7f4f0dc03d210b8ac55624ae007679b7a928a4f25a709331a8",
                "0x0000000000000000000000000000000000000000000000000000000000000005"
            ]
        },
        {
            "logIndex": "0x0",
            "removed": false,
            "blockNumber": "0x21c",
            "blockHash": "0xc7e6c9d5b9f522b2c9d2991546be0a8737e587beb6628c056f3c327a44b45132",
            "transactionHash": "0xfd1a40f9fbf89c97b4545ec9db774c85e51dd8a3545f969418a22f9cb79417c5",
            "transactionIndex": "0x0",
            "address": "0x42699a7612a82f1d9c36148af9c77354759b210b",
            "data": "0x0000000000000000000000000000000000000000000000000000000000000005",
            "topics": [
                "0xd3610b1c54575b7f4f0dc03d210b8ac55624ae007679b7a928a4f25a709331a8",
                "0x0000000000000000000000000000000000000000000000000000000000000005"
            ]
        }
    ]
}

Tip

You can use eth_getLogs with a filter options object to get all logs matching the filter options instead of using eth_newFilter followed by eth_getFilterLogs.

Uninstalling a filter

When a filter is no longer required, use eth_uninstallFilter to remove the filter.

Filters for private contracts

Filters for private contracts are created, accessed, and uninstalled using:

The privacy group ID must be specified as parameter 0 for the priv methods.

Example

{
    "jsonrpc": "2.0",
    "method": "priv_newFilter",
    "params": [
        "4rFldHM792LeP/e2WPkTXZedjwKuTr/KwCFTt6mBbkI=",
        {
         "fromBlock": "earliest",
         "toBlock": "latest",
         "addresses": ["0x991cc548c154b2953cc48c02f782e1314097dfbb"],
         "topics": ["0x85bea11d86cefb165374e0f727bacf21dc2f4ea816493981ecf72dcfb212a410"]
        }
    ],
    "id": 1
}

Getting logs using a filter options object

To get all logs for a filter options object, use eth_getLogs or priv_getLogs for a private contract.

Example

The following request for eth_getLogs returns all the logs where the example contract has been deployed to 0x42699a7612a82f1d9c36148af9c77354759b210b and executed with valueIndexed set to 5.

{
  "jsonrpc":"2.0",
  "method":"eth_getLogs",
  "params":[
    {
      "fromBlock":"earliest",
      "toBlock":"latest",
      "address":"0x42699a7612a82f1d9c36148af9c77354759b210b",
      "topics":[
        ["0xd3610b1c54575b7f4f0dc03d210b8ac55624ae007679b7a928a4f25a709331a8"],
        ["0x0000000000000000000000000000000000000000000000000000000000000005"]
      ]
      }
  ],
  "id":1
}

The above example returns the same result as calling eth_newFilter followed by eth_getFilterLogs.

Questions or feedback? You can discuss issues and obtain free support on Hyperledger Besu chat channel.
For Hyperledger Besu community support, contact the mailing list besu@lists.hyperledger.org