hiero-ledger / hiero-ledger/hiero-consensus-node
CLPR-2.3: submitBundle HAPI transaction handler
Nobody has claimed this yet.
- Dominant language
- Java
- Stars
- 407
- Forks
- 226
- Avg merge
- 3d 4h
- Merged PRs (30d)
- 210
Description
## Story CLPR-2.3: submitBundle (HAPI Transaction Handler)
**Parent Epic:** #24514 (CLPR-2: Messaging Layer)
### Objective
Implement `ClprSubmitBundleHandler` — the most complex handler in CLPR — per cross-platform spec §4.2 and Hiero impl spec §3.2.1. This is a HAPI transaction submitted by endpoint nodes.
### Acceptance Criteria
**Per-endpoint throttle (step 0):**
- **AC-0:** Recover the submitter's identity from `endpoint_signature` via ecrecover. Verify the submitter is a registered endpoint on the local ledger. Enforce per-endpoint rate limit: each endpoint gets `max_bundles_per_sec / num_endpoints` capacity. Excess submissions rejected and charged.
**Verification (steps 1–5 reject bad bundles with NO state change):**
- **AC-1:** Reject if Connection is CLOSED. HALTED accepts inbound (acknowledgements must flow).
- **AC-2:** Call verifier via `verifyBundle(proof_bytes)` → `(ClprQueueMetadata, ClprMessagePayload[])`. Revert → reject; submitter pays.
- **AC-3:** Bundle size: message count ≤ `max_messages_per_bundle`, each payload ≤ `max_message_payload_bytes`. Violation → reject.
- **AC-4:** Replay defense: first ID = `received_message_id + 1`, contiguous ascending, last ID = `metadata.next_message_id - 1`. Violation → reject.
- **AC-5:** Running hash: recompute `SHA-256` chain from `received_running_hash`; final must equal `metadata.sent_running_hash`. Mismatch → reject.
**State updates (steps 6–8):**
- **AC-6:** Update `acked_message_id` from metadata. Delete acknowledged Response/Control Messages from outbound queue. Retain acknowledged Data Messages (for response ordering).
- **AC-7:** Lazy config propagation: enqueue ConfigUpdate if `last_config_timestamp` is stale.
- **AC-8:** Per-message dispatch:
- **Control:** Apply directly (store peer config from ConfigUpdate). No response.
- **Data:** Resolve Connector, charge (execution + margin), dispatch to app, generate Response Message and enqueue.
- **Response:** Deliver to originating app. Verify ordering (CLPR-2.4). Violation → HALTED.
- **AC-9:** Failure isolation: one message's failure does not stop remaining messages.
- **AC-10:** Permissionless. Typically submitted by consensus node endpoint accounts.
- **AC-11:** Transaction record includes message count, generated response IDs, slash events.
- **AC-12:** Black-box tests: per-endpoint throttle enforcement, successful mixed-type bundle, verifier revert, size violation, replay, hash mismatch, ack deletes old messages, config propagation, control messages applied, data dispatched with responses, response ordering, individual message failure isolation, duplicate submission
### Dependencies
- #24515 (CLPR-2.1: wire formats)
- #24510 (CLPR-1.4: Connection with verifier)
- #24530 (CLPR-3.3: Connector charging and dispatch — for data messages)
### Risk
**High** — Most complex handler. Per-endpoint throttle adds admission control. Thorough testing critical.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with ClprSubmitBundleHandler and read cross-platform spec §4.2 and Hiero implementation spec §3.2.1, then review dependencies #24515, #24510, and #24530. Done means all listed acceptance criteria are implemented, including failure isolation and transaction records, with the specified black-box tests covering throttling, validation, dispatch, acknowledgements, propagation, ordering, and duplicate submission.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- java
- Domain
- backend-api-design, distributed-systems
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 28/100