Exonum Java Light Client
Java client for Exonum blockchain.
Exonum light client is Java library for working with Exonum blockchain
from the client side and can be easily integrated to an existing
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.
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
The following table shows versions compatibility:
|Light Client||Exonum||Exonum Java|
- Java 8 or above is required for using this client
- Maven 3.5 or above (only if you need to build it locally)
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.5.0</version> </dependency>
If you are using Gradle, add this to your dependencies
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
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);
serviceIdcan 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);
datais 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
StandardSerializersutility class which can be helpful for serialization.
keysis a key pair of private and public keys which is used for message signature.
To send the transaction just call a
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.
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);
txHashis a hash of the transaction to search.
Retrieving service info
To retrieve the list of all started service instances:
List<ServiceInfo> response = exonumClient.getServiceInfoList();
How to Build
To build the client locally, clone the repository, and run next commands from the project's root i.e. exonum-java-binding directory:
export RUSTFLAGS=none mvn install -pl exonum-light-client -am
It'll build Exonum Light client and the
which is required for the client.
Apache 2.0 - see LICENSE for more information.