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

Issue 1 — [Epic] Smart Contract Event & Log Observation API (Web3j-based)

Open
#307 1 comment 0 reactions 0 assignees View on GitHub
Mentorship pending-review smart-contracts
Dominant language
Java
Stars
6
Forks
21
Avg merge
10h 27m
Merged PRs (30d)
37

Description

### Summary
hiero-enterprise-java supports deploying and calling smart contracts via org.hiero.base.SmartContractClient, but has no API to observe the events/logs a contract emits. Per the agreed design, this will be implemented as a Web3j-based subscription API: a ContractListener holds one Web3j provider per LedgerId (Mainnet/Previewnet/Testnet/Solo, via the Hashio JSON-RPC relay endpoints), and SmartContractClient gets subscribeEvent(...) overloads for ContractId, EvmAddress, and raw EVM address String, all resolving to the same underlying subscription call and returning a ContractSubscription handle the caller can close to unsubscribe.

Because subscribeEvent(...) lives on SmartContractClient in the base module (same pattern as existing methods like createAccount/createTopic), it is automatically available from both hiero-enterprise-spring and hiero-enterprise-microprofile without any framework-specific glue code — consumers just call smartContractClient.subscribeEvent(...) on the client they already inject today.

### Deliverables
* EventParam: typed wrapper around Web3j's TypeReference, tracking indexed/non-indexed.
* EventLog: a record holding the raw Web3j log fields plus decoded indexed/non-indexed values.
* ContractSubscription: AutoCloseable handle returned by subscribeEvent(...), wrapping the underlying Web3j Disposable.
* ContractListener: per-ledger Web3j provider resolution + actual event subscription/decoding.
* SmartContractClient.subscribeEvent(...) overloads (ContractId, EvmAddress, String), each returning ContractSubscription.
* Tests, docs, and sample usage in both the Spring and Microprofile sample apps (no new annotations — direct SmartContractClient calls).

### Sub-issues
#308 EventParam: Web3j TypeReference wrapper with indexed-parameter factories
#309 Implement the EventLog record
#310 ContractSubscription: AutoCloseable subscription handle
#311 ContractListener: per-LedgerId Web3j provider registry
#312 ContractListener: Web3j event subscription + log decoding
#313 SmartContractClient.subscribeEvent(...): ContractId / EvmAddress / String overloads
#314 Samples + documentation (Spring + Microprofile, via direct SmartContractClient usage)
#315 Test suite (unit + testnet integration)

### Out of scope for this iteration
* Annotation-based listeners (e.g. a @ContractEventListener method annotation) for Spring or Microprofile. Per review feedback, these are experimental/exploratory and not needed once subscribeEvent(...) is a plain base-module client method — may be revisited later as a separate, standalone enhancement once the base API has stabilized.

### References
* Design doc: "Web3j Contract Event Listener" (internal, provided by mentors)
* Mentorship description: https://github.com/LF-Decentralized-Trust-Mentorships/mentorship-program/issues/70
* Earlier mirror-node-polling PoCs (superseded by this design, still useful for the decoding/ABI-matching concepts): https://github.com/manishdait/mirror-log-listener-poc, https://github.com/manishdait/hiero-event-listener-poc
* [Web3j](https://docs.web3j.io/) — TypeReference, EthFilter, event subscriptions, Disposable
* Hashio JSON-RPC relay: https://swirldslabs.com/hashio/

Contributor guide

Open the contributing guide

Research direction

Start with the SmartContractClient methods named in the issue and read the internal “Web3j Contract Event Listener” design doc, then review sub-issues #308–#315 to understand the planned boundaries. Run the existing base-module and sample-app tests before investigating the Spring and Microprofile examples. Done means the listed event types, subscription flow, samples, documentation, and tests are implemented together.

Written by the indexing model from the issue text.

Assessment

Tech stack
java
Domain
api, backend, blockchain
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.