hiero-ledger / hiero-ledger/hiero-consensus-node

CLPR-2.3: submitBundle HAPI transaction handler

Open
#24,517 0 comments 0 reactions 0 assignees View on GitHub

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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.