hiero-ledger / hiero-ledger/hiero-enterprise-java
feat: Implement Centralized HTS Modernization and Cross-Framework REST Integration
- Dominant language
- Java
- Stars
- 6
- Forks
- 21
- Avg merge
- 10h 27m
- Merged PRs (30d)
- 37
Description
### Problem
## Problem
The Hiero Enterprise Java SDK currently lacks a unified, high-level abstraction for Hedera Token Service (HTS) operations. This architectural gap results in several enterprise-level issues:
1. **Code Duplication**: Developers are forced to implement redundant token logic across different frameworks (Spring Boot and MicroProfile).
2. **Boilerplate Overload**: Interacting with the raw Hedera SDK requires significant boilerplate for transaction construction, signing, and record processing.
3. **Inconsistent Error Handling**: Without a centralized protocol layer, ensuring uniform error mapping and transaction monitoring across modules is difficult.
4. **Limited Demoability**: The sample applications lack a standardized set of REST endpoints to showcase the full lifecycle of Fungible and Non-Fungible tokens to potential stakeholders.
### Solution
## Solution
I propose to implement a robust, centralized HTS management architecture within the `hiero-enterprise-base` module. This will provide a unified API that both Spring and MicroProfile modules can leverage.
### Proposed Operations to be Added:
The implementation will support the following core HTS operations for both Fungible and Non-Fungible Tokens:
* **Token Management**: Create Token, Delete Token, Update Token (via Builder pattern).
* **Supply Control**: Mint (Fungible/NFT), Burn (Fungible/NFT), and Wipe Token.
* **Account Governance**: Associate/Dissociate, Freeze/Unfreeze Account, and Grant/Revoke KYC.
* **Transfers**: Standardized Fungible and NFT serial transfers.
* **Lifecycle State**: Pause and Unpause Token functionality.
### Technical Approach:
1. **Unified Protocol Layer**: Implement a reflection-based `ProtocolLayerClient` to handle transaction execution dynamically while maintaining compatibility with the project's **SDK v2.32.0** baseline.
2. **Specialized Clients**: Develop `FungibleTokenClient` and `NftClient` interfaces to provide type-safe, high-level abstractions for developers.
3. **Cross-Framework REST Endpoints**:
* Add a `TokenController` in the Spring module.
* Add a `TokenResource` in the MicroProfile module.
* This ensures feature parity and provides immediate demoability for the Hiero platform.
4. **Centralized DTOs**: Standardize request/response models to ensure data consistency across the entire SDK.
### Alternatives
## Alternatives Considered
1. **Upgrading to SDK v2.41.0+**: While newer versions support advanced features like Token Airdrops, we have decided to stick with the stable **v2.32.0** baseline to avoid breaking changes in the core platform. Those features will be deferred to a future migration phase.
2. **Raw Protobuf Transactions**: We considered building transactions using raw protobuf messages to bypass SDK limitations. This was rejected because it significantly increases maintenance complexity and bypasses the safety checks of the official SDK.
3. **Framework-Specific Implementation**: Implementing the logic separately for Spring and MicroProfile was considered, but rejected in favor of a "Base-First" approach to ensure a single source of truth and easier maintenance.
## Additional Notes
The proposed architecture is designed to be "SDK-Agnostic," meaning that once the project baseline moves to a newer Hedera SDK version, adding advanced features like Airdrops or Rejections will require minimal effort without changing the consumer-facing API.
Contributor guide
Research direction
Start by mapping the hiero-enterprise-base module and the Spring and MicroProfile modules, then inspect the existing SDK v2.32.0 integration points. Review how transactions, DTOs, and REST resources are currently structured before assessing the proposed ProtocolLayerClient, FungibleTokenClient, NftClient, TokenController, and TokenResource. Done means the listed HTS operations have a consistent base API and matching REST exposure across both frameworks.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- java, spring-boot
- Domain
- api, backend-api-design
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100