hiero-ledger / hiero-ledger/hiero-consensus-node
CLPR-2.1: Messaging wire formats, state schema, and system contract interface
- Dominant language
- Java
- Stars
- 406
- Forks
- 226
- Avg merge
- 3d 4h
- Merged PRs (30d)
- 210
Description
## Story CLPR-2.1: Messaging Wire Formats, State Schema, and System Contract Interface
**Parent Epic:** CLPR-2: Messaging Layer
**Repo:** hiero-ledger/hiero-consensus-node
### Objective
Define protobuf wire formats, state stores, and the CLPR system contract interface for the messaging layer. Downstream stories compile against these types.
### Acceptance Criteria
- **AC-1:** HAPI transaction bodies defined: `ClprSubmitBundleTransactionBody` (connection_id, proof_bytes, remote_endpoint_signature), `ClprRedactMessageTransactionBody` (connection_id, message_id). Note: `sendMessage` is NOT a HAPI transaction — it is a system contract method.
- **AC-2:** CLPR system contract Solidity interface includes `sendMessage(bytes32 connectionId, bytes connectorId, bytes targetApplication, bytes messageData) returns (uint64 messageId)`. This is callable by application smart contracts.
- **AC-3:** `ClprMessagePayload` oneof with three variants: `ClprMessage` (data), `ClprMessageReply` (response), `ClprControlMessage` (control).
- **AC-4:** `ClprMessage`: `connector_id`, `target_application`, `sender`, `message_data`.
- **AC-5:** `ClprMessageReply`: `message_id` (uint64), `status` (enum: SUCCESS=0, APPLICATION_ERROR=1, CONNECTOR_NOT_FOUND=2, CONNECTOR_UNDERFUNDED=3, REDACTED=5), `message_reply_data` (bytes).
- **AC-6:** `ClprMessageKey`: `(connection_id, message_id)`. `ClprMessageValue`: `payload` + `running_hash_after_processing`.
- **AC-7:** `ClprQueueMetadata`: `next_message_id`, `sent_running_hash`, `received_message_id`, `received_running_hash`.
- **AC-8:** State stores: `MESSAGE_QUEUE` K/V (ClprMessageKey → ClprMessageValue), `MESSAGE_QUEUE_METADATA` K/V (connection_id → queue metadata).
- **AC-9:** `TransactionBody` oneof extended with `ClprSubmitBundle` and `ClprRedactMessage`.
- **AC-10:** Transaction records: `ClprSubmitBundle` includes message count, generated response IDs, slash events.
- **AC-11:** All MATS pass.
### Notes
- `ClprControlMessage` must be added to the `ClprMessagePayload` oneof (missing from prototype per Finding F-1).
- `ClprMessage` needs `connector_id`, `target_application`, `sender` fields (missing from prototype per Finding F-2).
- `ClprMessageReplyStatus` enum needs to be added (missing from prototype per Finding F-3).
- The `sendMessage` return value (`messageId`) is available to the calling smart contract for correlation with the eventual response.
### Dependencies
- CLPR-1.1 (extends network-layer types)
### Risk
**Medium** — Introduces the CLPR system contract pattern. The system contract must be callable from EVM context and interact with native CLPR service state.
Contributor guide
Research direction
Read the CLPR-1.1 network-layer types and the existing CLPR prototype first; map the protobuf transaction, payload, key/value, metadata, and record definitions plus the Solidity system-contract interface. Use the acceptance criteria as the completion checklist and run MATS.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- java, solidity
- Domain
- backend-api-design, blockchain, distributed-systems
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100