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

CLPR-2.1: Messaging wire formats, state schema, and system contract interface

Open
#24,515 0 comments 0 reactions 0 assignees View on GitHub
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

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.