hiero-ledger / hiero-ledger/hiero-enterprise-java

Feature: Type-Safe Contract Proxy Framework for High-Level Smart Contract Interaction

Open
#102 2 comments 0 reactions 0 assignees View on GitHub
enhancement pending-review
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.