The Web3J filter provides notification of certain events occurring on the Ethereum network, which is useful for Java and Android programmers. Three types of filters are supported in Ethereum:

  • Block filters
  • Pending Transaction Filters
  • Topic filters

Block filters and pending transaction filters provide notification of the creation of new transactions or blocks on the network.

Theme filters are more flexible. Allows you to create filters based on specific criteria provided.

Unfortunately, unless you are using WebSocket to connect to Geth, processing filters through the JSON-RPC API is a tedious process, where you need to poll the Ethereum client to see if there are any new updates to your filters for the real-time synchronization features requested by HTTP and IPC. In addition, block and transaction filters only provide the hash value of the transaction or blockchain, so further requests are required to obtain the actual transaction or block corresponding to the hash.

Web3j’s filters address these issues, so you have a fully asynchronous event-based API to handle filters. It uses RXJava’s Observables, which provide a consistent API for working with events, which helps link jSON-RPC calls together through functional combinations.

Note: Infura does not support filters.

Block and trade filters

Accept all new blocks and add them to the blockchain (the false parameter specifies that we only need blocks to be ok, not embedded transactions) :

Subscription subscription = web3j.blockObservable(false).subscribe(block -> {
    ...
});
Copy the code

Accept all new transactions and add them to the block chain:

Subscription subscription = web3j.transactionObservable().subscribe(tx -> {
    ...
});
Copy the code

Receive all pending transactions and submit them to the network (i.e. before they are grouped together) :

Subscription subscription = web3j.pendingTransactionObservable().subscribe(tx -> {
    ...
});
Copy the code

Unsubscribe when no longer needed:

subscription.unsubscribe();
Copy the code

Other callbacks are provided that simply provide block or transaction hashes, details that refer to the Web3JRX interface.

Reproducing filter

Webjs also provides filters for reproducing block and transaction history.

Reproduce a series of blocks from the blockchain:

Subscription subscription = web3j.replayBlocksObservable(
        <startBlockNumber>, <endBlockNumber>, <fullTxObjects>)
        .subscribe(block -> {
            ...
});
Copy the code

Reproduce a single transaction contained within the scope of a block:

Subscription subscription = web3j.replayTransactionsObservable(
        <startBlockNumber>, <endBlockNumber>)
        .subscribe(tx -> {
            ...
});
Copy the code

You can also get Web3J to rerender the latest block and provide notifications when you see it (by submitting an Observable) :

Subscription subscription = web3j.catchUpToLatestBlockObservable(
        <startBlockNumber>, <fullTxObjects>, <onCompleteObservable>)
        .subscribe(block -> {
            ...
});
Copy the code

Alternatively, you can notify newly created subsequent blocks after you reproduce the latest block:

Subscription subscription = web3j.catchUpToLatestAndSubscribeToNewBlocksObservable(
        <startBlockNumber>, <fullTxObjects>)
        .subscribe(block -> {
            ...
});
Copy the code

As described above, and contained within the block of transactions:

Subscription subscription = web3j.catchUpToLatestAndSubscribeToNewTransactionsObservable(
        <startBlockNumber>)
        .subscribe(tx -> {
            ...
});
Copy the code

All of the above filters are exported through the Web3JRX interface.

Topic filters and EVM events

Topic filters capture the details of ethereum Virtual Machine (EVM) events that occur on the network. These events are created by the smart contract and stored in the transaction log associated with the smart contract.

The Solidity documentation provides a good overview of EVM events.

Use the EthFilter type to specify the topic you want to apply to the filter. This can include the address of the smart contract to which you want to apply the filter. You can also provide specific topics for filtering. Where a single topic represents the index parameter on the smart contract:

EthFilter filter = new EthFilter(DefaultBlockParameterName.EARLIEST, DefaultBlockParameterName.LATEST, <contract-address>) [.addSingleTopic(...) | .addOptionalTopics(..., ...) | ...] ;Copy the code

This filter can then be created using syntax similar to the block and transaction filters above:

web3j.ethLogObservable(filter).subscribe(log -> {
    ...
});
Copy the code

Filter topics can only reference the Solidity event parameters of the index. It is not possible to filter non-indexed event parameters. In addition, for any index event parameters of variable length array types (such as strings and bytes), the kECCAK-256 hash of their values is stored on the EVM log. It is impossible to store or filter with all their values.

If you create a filter instance that has no topic associated with it, all EVM events that occur in the network will be captured by the filter.

Operation combination annotation

All jSON-RPC methods except send() and sendAsync are implemented in Web3J to support observable() methods to create asynchronous execution requests. This makes it easy and straightforward to combine jSON-RPC calls into new functions.

For example, the blockObservable itself consists of many separate JSON-RPC calls:

public Observable<EthBlock> blockObservable(
        boolean fullTransactionObjects, long pollingInterval) {
    return this.ethBlockHashObservable(pollingInterval)
            .flatMap(blockHash ->
                    web3j.ethGetBlockByHash(blockHash, fullTransactionObjects).observable());
}
Copy the code

Here, we first create an observable that provides notification of the block hash for each newly created block. We then call ethGetBlockByHash using flatMap to get the full block details, which are passed to the observant subscriber.

Further examples

See ObservableIT for a further example.

For a demonstration of using the manual filter API, see EventFilterIT.

  • Web3j tutorial, mainly for Java and Android programmers for blockchain Ethereum development web3J development details.
  • Ethereum tutorial, mainly introduces smart contract and DAPP application development, suitable for getting started.
  • Ethereum development, mainly introduces the use of Node.js, mongodb, blockchain, IPFS to achieve decentralized e-commerce DApp combat, suitable for advanced.
  • PHP Ethereum mainly introduces the use of PHP for smart contract development interaction, account creation, transactions, transfers, token development, filters and events and other content.

Web3j tutorial: Filters and Events