Block callback

Introduction to block callbacks

What they do

Block callbacks are a feature included in the official Nano node application which allow you to capture blocks as they enter the network in real-time, which can have a variety of different use cases such as checking for payments, monitoring the network transaction rate or providing additional services.

The node sends notifies receivers through an HTTP request to the configured IP, port and target directory set. This library will open an elementary HTTP server, listen for new blocks from any connected nodes and then deconstruct the JSON into the relevant block classes, which are then broadcasted to the registered listener classes.

Node configuration

In order to utilise the block callback system, you will need to make the following changes to your nodes config.json file:

• node > callback_address should be set to the receiving address of your application - use ::ffff:127.0.0.1 if running on the same device and network interface
• node > callback_port is the port which the HTTP server listens on - make sure your program listens on the same port number
• node > callback_target is the additional HTTP path when the node sends requests - in most instances, this should simply be set as / (single forward slash)

How to use the library

Use the in.bigdolph.jnano.rpc.callback.server.BlockCallbackServer class to configure the listening port (and binding address) of the HTTP server through its constructors.

You will also need to have a class which implements BlockCallbackListener, which will be called whenever a new block is received by the node. This listener class should have an instance registered to the server by using the registerListener method.

Finally, you will need to start the server so it can handle the HTTP requests and notify the listeners. This process is as simple as running the start() function on the server instance, which will run and manage all the requests in separate threads.

Example

The code below constructs a new callback server to listen on, and will notify the registered listener of new blocks.

BlockCallbackServer server = new BlockCallbackServer(7077); //Initialise the callback listening server on port 7077
server.registerListener(new ExampleListener()); //Register a listener
server.start(); //Start the server (in separate thread)

The code demonstrated below defines a listener, which will print the block's information to the console.

class ExampleListener implements BlockCallbackListener {

    @Override
    public void onNewBlock(BlockInfo block, String target, InetAddress node) {
        System.out.println("New block received: " + block.getBlockHash()); //Outputs the block hash
        System.out.println("Type: " + block.getBlock().getType().toString()); //Outputs block type
        
        if(block.getTransactionalAmount() != null) { //Might be null if non-transactional (ie. change blocks)
            System.out.println("Value: " + block.getTransactionalAmount().toString()); //Outputs associated value
        }
    }

}

This gives the following output to the console when a new block is retrieved by the node:

New block received: 8F8C89C0E27C46C5D95DBE30AEE633E0D8BC89B52FA22C884FF9F2BFE57D70CA
Type: send
Value: 1000000000000000000000000000000