Block callback

NOTE: This is a deprecated feature (though still fully functional). It's recommended that you use the new WebSocket API for better reliability.

Introduction to block callbacks

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 operate a basic 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 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.

//Initialise the callback listening server on port 8080
BlockCallbackServer server = new BlockCallbackServer(8080);

//Register the listener (defined below)
server.registerListener(new ExampleListener());

//Start the server (in separate thread)
server.start();

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(BlockData block, String target, InetAddress node) {
        System.out.println("New block received: " + block.getBlockHash()); //Outputs the block hash
        System.out.println("Type: " + block.getBlockContents().getType().toString()); //Outputs block type
        
        if(block.getTransactionalAmount() != null) { //Might be null if non-transactional (ie. change blocks)
            System.out.println("Value: " + block.getTransactionalAmount()); //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: 1 Nano