hiero-ledger / hiero-ledger/hiero-enterprise-java
Feature: Type-Safe Contract Proxy Framework for High-Level Smart Contract Interaction
- Dominant language
- Java
- Stars
- 6
- Forks
- 21
- Avg merge
- 10h 27m
- Merged PRs (30d)
- 37
Description
### Problem
Current smart contract interaction in the Hiero Enterprise SDK is low-level and brittle. Developers are forced to manually construct `ContractParam` objects and rely on string-based function names for every call.
**Critical Pain Points:**
1. **Runtime Fragility**: Errors in function names or parameter types are only discovered at runtime (often after paying network fees), rather than at compile-time.
2. **Boilerplate Fatigue**: Simple transfers or balance checks require significant "ceremony" code to encode parameters correctly.
3. **Low Maintainability**: If a Solidity function signature changes, developers must hunt down every string-based reference in their Java codebase to update it.
4. **Poor Developer Experience**: The SDK currently feels like a data transport layer rather than a modern, object-oriented framework.
### Solution
I propose the implementation of a **Type-Safe Contract Proxy Framework** in the `hiero-enterprise-base` module. This framework allows developers to interact with Smart Contracts as native Java objects.
**Key Features:**
- **Annotation-Driven API**: Uses `@HieroContract` and `@ContractFunction` to declaratively map Java interfaces to on-chain contracts.
- **Intelligent Type Mapping**: Automatically resolves Java types (`BigInteger`, `AccountId`, `String`, etc.) to the correct Solidity `ContractParam` types.
- **Dynamic Proxy Engine**: A `ContractProxyFactory` that generates runtime implementations of interfaces, eliminating the need for manual `callContractFunction` calls.
- **Framework Agnostic**: The core logic is implemented in `base`, making it available to both Spring and MicroProfile modules.
**Example Comparison:**
*Instead of:*
`client.callContractFunction(id, "transfer", ContractParam.address(to), ContractParam.uint256(amt));`
*You can now do:*
```java
@HieroContract(address = "0.0.12345")
public interface MyToken {
@ContractFunction
void transfer(AccountId recipient, BigInteger amount);
}
MyToken token = factory.createProxy(MyToken.class);
token.transfer(recipient, amount); // Type-safe and zero boilerplate.
### Alternatives
1. **Manual Encoding (Status Quo)**: I considered staying with the current implementation, but it is error-prone and does not scale for complex enterprise applications.
2. **Source Code Generation**: I considered using an external tool to generate Java classes from ABI files (like Web3j), but this adds heavy complexity to the build process. A reflection-based proxy is much lighter and zero-config.
3. **Raw Hex/Bytecode Interaction**: Too low-level and creates a massive barrier to entry for developers coming from traditional Java backgrounds.
Contributor guide
Research direction
Start in the hiero-enterprise-base module by reviewing the existing ContractParam and callContractFunction interaction path. Then assess the proposed @HieroContract, @ContractFunction, and ContractProxyFactory entry points; done means Java interfaces can proxy contract calls with mapped types while remaining available to Spring and MicroProfile modules.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- java
- Domain
- backend-api-design, blockchain, developer-experience
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100