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

CLPR-3: Payment & Routing Layer — connectors, payments, and application delivery

Open
#24,527 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

## Epic CLPR-3: Payment & Routing Layer

**Parent:** hiero-ledger/roadmap#48
**Repo:** hiero-ledger/hiero-consensus-node

### Objective

Implement Connector registration, authorization, payment, slashing, and application dispatch on Hiero. Connectors are the economic actors that authorize messages, fund execution, and are slashed for failures.

### Background

A Connector is registered on a specific Connection and has a counterpart on the peer ledger. The source-side Connector has an authorization contract; the destination-side provides balance and staked collateral. Bilateral registration is required for end-to-end operation. Connector balances and stakes are held in the CLPR service's internal accounting (not the Connector contract's account).

### Expected Functionality

1. **Connector registration** — `registerConnector` (HAPI + system contract) with initial balance, stake, authorization contract, and source connector address mapping.
2. **Connector lifecycle** — Top-up, withdraw, deregister (HAPI + system contract). `getConnector` as system contract `view` function.
3. **Message authorization** — `IClprConnectorAuth.authorizeMessage()` called during `sendMessage` (system contract).
4. **Application dispatch** — Data messages dispatched to `target_application` via `onClprMessage()` in child transaction context. Responses generated and enqueued.
5. **Payment flow** — Connectors charged (execution cost + margin). Margin reimburses submitting endpoint.
6. **Slashing** — Escalating penalties for `CONNECTOR_NOT_FOUND` and `CONNECTOR_UNDERFUNDED`. Ban after threshold.
7. **Queue protection** — Per-Connector queue quotas and fee escalation prevent monopolization.

### Constraints

- Black-box testing only
- Bilateral Connector registration required for end-to-end operation
- Slashing is bilateral: both source and destination sides enforce independently
- Connector funds held in CLPR service accounting, not Connector contract accounts

### Stories

- CLPR-3.1: Connector wire formats, state schema, and system contract interface
- CLPR-3.2: Connector registration and lifecycle
- CLPR-3.3: Connector authorization and application dispatch
- CLPR-3.4: Slashing, penalties, and reimbursement
- CLPR-3.5: Queue monopolization protection

### Dependencies

- CLPR-1 (Connections)
- CLPR-2 (Messaging — dispatch happens within SubmitBundle)

### Spec References

- [Cross-Platform Spec §2.2, §4.6](clpr-service-spec.md) — Connector state, slashing
- [Hiero Impl Spec §6, §7](clpr-hiero-impl-spec.md) — Connector authorization, application dispatch, fund custody

Contributor guide

Open the contributing guide

Research direction

Start with clpr-service-spec.md §2.2 and §4.6, then clpr-hiero-impl-spec.md §6 and §7, while reviewing the CLPR-1 and CLPR-2 dependencies. Use the five listed stories to define the scope and apply the stated black-box testing constraint. Done means connector registration and lifecycle, authorization and dispatch, payment and slashing, and queue protection are implemented.

Written by the indexing model from the issue text.

Assessment

Tech stack
java
Domain
backend-api-design, blockchain, payments
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Needs clarification
Newbie friendliness
20/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.