This project provides Java modules to interact with a Hiero network in a Java Enterprise application. The project provides integrations to Spring Boot or Eclipse Microprofile (like Quarkus) for interacting with Hiero. This module is based on the Hedera Java SDK(will be migrated to Hiero Java SDK in near future) and provides a set of managed services to interact with a Hiero network.
To use this module, you need to add the following dependency to your project:
<dependency>
<groupId>com.open-elements.hiero</groupId>
<artifactId>hiero-enterprise-spring</artifactId>
<version>VERSION</version>
</dependency>Note
We are currently working on migrating the project to the Hiero namespace.
The groupId, package names and Java module names will be changed with that in near future.
To configure the module, you need to add the following properties to your application.properties file:
spring.hiero.accountId=0.0.53854625
spring.hiero.privateKey=2130020100312346052b8104400304220420c236508c429395a8180b1230f436d389adc5afaa9145456783b57b2045c6cc37
spring.hiero.network=hedera-testnetThe spring.hiero.network property defines the network that is used to interact with the Hiero network.
In the given example, the Hedera testnet network is used.
Hedera is based on Hiero and therefore the testnet can be used to interact with a Hiero network.
The account information (accountId, privateKey) can all be found at the Hedera portal for a testnet or previewnet account.
Today only the "DER Encoded Private Key" of the "ECDSA" key type is supported for the spring.hiero.privateKey property.
The 2 properties spring.hiero.accountId and spring.hiero.privateKey define the "operator account".
The operator account is used as the account that sends all transactions against the Hiero network.
To use the module, you need to add the @EnableHiero annotation to your Spring Boot application class.
import com.open.elements.spring.hiero.EnableHiero;
@SpringBootApplication
@EnableHiero
public class Application {
public static void main(String[] args) {
SpringApplication.run(Application.class, args);
}
}Once that is done you can for example autowire the FileClient class and call the methods to interact with a Hiero network.
@Service
public class HieroAccountService {
@Autowired
private FileClient fileClient;
public String readFile(String id) {
FileId fileId = FileId.of(id);
byte[] content = fileClient.readFile(fileId);
return new String(content);
}
}All APIs of the client are synchronous and return the result of the operation.
For asynchronous operations, you can easily wrap calls by use the @Async annotation of spring.
A sample application that uses the Hiero Spring module can be found in the hiero-enterprise-spring-sample module.
The sample application is a simple Spring Boot application that reads has a REST endpoint at localhost:8080/ and shows the hbar balance of the account 0.0.100 on the Hedera testnet.
To use the application, you need to have created a Hedera testnet account at the Hedera portal.
The account information can be added to the application.properties file in the hedera-spring-sample module:
spring.hiero.accountId=0.0.3447271
spring.hiero.privateKey=2130020100312346052b8104400304220420c236508c429395a8180b1230f436d389adc5afaa9145456783b57b2045c6cc37The module supports a .env file in the root of the module to define the account information.
The file is added to the .gitignore file and is not committed to the repository.
By doing that you can define the account information in the .env file without the risk of committing it to the repository.
The .env file should look like this:
spring.hiero.accountId=0.0.3447271
spring.hiero.privateKey=2130020100312346052b8104400304220420c236508c429395a8180b1230f436d389adc5afaa9145456783b57b2045c6cc37Alternatively, you can provide the account information as environment variables:
export HEDERA_ACCOUNT_ID=0.0.3447271
export HEDERA_PRIVATE_KEY=2130020100312346052b8104400304220420c236508c429395a8180b1230f436d389adc5afaa9145456783b57b2045c6cc37An external sample project can be found at https://github.com/hendrikebbers/spring-hiero-sample
To use this module, you need to add the following dependency to your project:
<dependency>
<groupId>com.open-elements.hiero</groupId>
<artifactId>hiero-enterprise-microprofile</artifactId>
<version>VERSION</version>
</dependency>The hiero-enterprise-microprofile-sample module contains a sample application that uses the Hiero Microprofile module.
The sample application is a simple Quarkus application that reads has a REST endpoint at localhost:8080/ and shows
the hbar balance of the account 0.0.100 on the Hedera testnet.
For most of the part, the sample application is the same as the Spring Boot sample application.
A sample project can be found at https://github.com/hendrikebbers/quarkus-hiero-sample
The module provides a set of managed services that can be used to interact with a Hiero network. The following services are available in spring and microprofile:
org.hiero.base.HieroContext: component that provides the information about the Hiero network and the operator accountorg.hiero.base.AccountClient: to interact with accountsorg.hiero.base.FileClient: to interact with filesorg.hiero.base.FungibleTokenClient: to interact with fungible tokensorg.hiero.base.NftClient: to interact with NFTsorg.hiero.base.SmartContractClient: to interact with smart contractsorg.hiero.base.verifcation.ContractVerificationClient: to verify smart contractsbase.org.hiero.mirrornode.AccountRepository: to query accountsbase.org.hiero.mirrornode.NetworkRepository: to query network informationbase.org.hiero.mirrornode.NftRepository: to query NFTsbase.org.hiero.mirrornode.TransactionRepository: to query transaction information
Next to that the following low-level services are available:
base.org.hiero.protocol.ProtocolLayerClient: to interact with the Hiero protocol layerbase.org.hiero.mirrornode.MirrorNodeClient: to query the Hiero mirror node
The project is based on Maven. The Maven wrapper is used to build the project. Therefore you do not need to install Maven on your machine. To build the project, you can use the following command:
./mvnw verifyThe tests in the project are working against any Hiero network. You need to provide the account id and the private key of an account that is used to run the tests. If no account is provided, the tests will fail. The most easy way to run the tests is to use the Hedera testnet network. To run the tests, you need to provide the account id and the "DER Encoded Private Key" of the "ECDSA" testnet account. That information can be provided as environemt variables:
export HEDERA_ACCOUNT_ID=0.0.3447271
export HEDERA_PRIVATE_KEY=2130020100312346052b8104400304220420c236508c429395a8180b1230f436d389adc5afaa9145456783b57b2045c6cc37
export HEDERA_NETWORK=testnetAs an alternative you can define the information in a .env file in each sub-module that contains tests.
The files are added to the .gitignore file and will not be committed to the repository.
The file should look like this:
spring.hiero.accountId=0.0.3447271
spring.hiero.privateKey=2130020100312346052b8104400304220420c236508c429395a8180b1230f436d389adc5afaa9145456783b57b2045c6cc37
Currently there is no running release process and we work on setting uop everything to do releases under the hiero-ledger org.
Technical documentation (getting started, architecture, Spring/MicroProfile, managed services, ADRs) is in the docs folder and is published as GitHub Pages.
Pull requests that change the docs get a preview at …/pr/<number>/.
This project is licensed under the Apache License 2.0 - see the LICENSE file for details.