exonum-light-client

Exonum Java Light Client

Java client for Exonum blockchain.

Overview

Exonum light client is Java library for working with Exonum blockchain from the client side and can be easily integrated to an existing Java application.
Also, Exonum light client provides access to common utils (com.exonum.binding.common.* packages) toolkit which contains some helpful functions for hashing, cryptography, serialization, etc.

Capabilities

By using the client you are able to perform the following operations:

• Submit transactions to the node
• Receive transaction information
• Receive blockchain blocks information
• Receive node system information
• Receive node status information
• Receive list of started service instances

Please see the examples below and the Javadocs for details.

Compatibility

The following table shows versions compatibility:

Light Client	Exonum	Exonum Java
0.6.0	1.0.*	0.10.*
0.5.0	0.13.*	0.9.*
0.4.0	0.12.*	0.8.*

Previous versions

Light Client	Exonum	Exonum Java
0.3.0	0.11.*	0.6.0-0.7.0
0.2.0	0.11.*	0.6.0
0.1.0	0.10.*	0.4

System Dependencies

• Java 8 or above is required for using this client.

QuickStart

If you are using Maven, add this to your pom.xml file

<dependency>
  <groupId>com.exonum.client</groupId>
  <artifactId>exonum-light-client</artifactId>
  <version>0.6.0</version>
</dependency>

If you are using Gradle, add this to your dependencies

compile 'com.exonum.client:exonum-light-client:0.6.0'

Examples

This section contains most frequently used operations with the blockchain. Please navigate to Exonum client API documentation to see all supported operations.

Exonum Client Initialization

The following example shows how to create the instance of exonum client which will work with Exonum node at http://localhost:8080 address:

    ExonumClient exonumClient = ExonumClient.newBuilder()
        .setExonumHost("http://localhost:8080")
        .build();

The next example shows how to use a custom configuration of the http-client:

    OkHttpClient httpClient = new OkHttpClient.Builder()
        .callTimeout(Duration.ofSeconds(3))
        .build();

    ExonumClient exonumClient = ExonumClient.newBuilder()
        .setExonumHost("http://localhost:8080")
        .setHttpClient(httpClient)
        .build();

Creating Transaction Message

The following example shows how to create the transaction message. In addition please read about transaction message structure.

    TransactionMessage txMessage = TransactionMessage.builder()
        .serviceId(serviceId)
        .transactionId(2)
        .payload(data)
        .sign(keys);

• serviceId can be obtained, if needed, by the service name:

  int serviceId = exonumClient.findServiceInfo(serviceName)
      .map(ServiceInfo::getId)
      .orElseThrow(() -> new IllegalStateException("No service" 
          + " with the given name found: " + serviceName);

• data is a bytes array which contains transactional information/parameters in a service-defined format. It can be any object which should be serialized to bytes in advance. We recommend to use Google Protobuf for serialization, but it is always an option of your choice. Also, common package provides StandardSerializers utility class which can be helpful for serialization.
• keys is a key pair of private and public keys which is used for message signature.

Sending Transaction

To send the transaction just call a submitTransaction.
Make notice that it works in a blocking way i.e. your thread will be blocked till the response is received.

HashCode txHash = exonumClient.submitTransaction(tx);

Be aware that this method submits the transaction to the pool of uncommitted transactions and doesn't wait for the transaction acceptance to a new block.

Also, you can take a look at the integration test for the full example of how to create a transaction message and send it to Exonum node.

Transaction Info

The following method provides a possibility to get information on a transaction by its hash - status of the transaction, details of the message containing the transaction and, if available, transaction location and result:

Optional<TransactionResponse> response = exonumClient.getTransaction(txHash);

• txHash is a hash of the transaction to search.

Retrieving service info

To retrieve the list of all started service instances:

List<ServiceInfo> response = exonumClient.getServiceInfoList();

Example Client Application

The Vehicle Registry Service includes a Java client application based on this library.

How to Build

To build the client locally:

1. Install Java 11+ and Maven 3.5+.

2. Clone this repository.

3. Run the next commands from the project's root directory (i.e. exonum-java-binding):

export RUSTFLAGS=none
mvn install -pl exonum-light-client -am

It'll build Exonum Light client and the exonum-java-binding-common artifact which is required for the client.

License

Apache 2.0 - see LICENSE for more information.